doc/book/src/java-broker/Java-Broker-Ports.xml

<?xml version="1.0" encoding="utf-8"?>
<!--

 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.

-->

<chapter id="Java-Broker-Ports">
  <title>Broker Ports</title>
  <para>This section guides through the process of configuring of Broker AMQP and non-AMQP ports.</para>

  <section id="Java-Broker-Ports-Configuring">
    <title>Configuring Broker Ports</title>
    <para>
        The Broker Ports can be configured using the
        <link linkend="Java-Broker-Configuring-And-Managing-HTTP-Management-Introduction">HTTP management interfaces</link>.
    </para>

    <para>The following Port managing operations are available from the
            <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>:
        <itemizedlist>
            <listitem><para>A new Port can be created by clicking "Add Port" button on the Broker tab.</para></listitem>
            <listitem><para>An existing Port details are displayed on the Port tab after clicking
            on Port name in the Broker object tree or after clicking on a Port row in the Ports grid on the Broker tab.</para></listitem>
            <listitem><para>An existing Port can be edited by clicking on "Edit" button on the Port tab.</para></listitem>
            <listitem><para>An existing Port can be deleted by clicking on "Delete Port" button
            on Broker tab or "Delete" button on the Port tab.</para></listitem>
        </itemizedlist>
    </para>

    <para>Three different types of ports can be created:
        <itemizedlist>
            <listitem><para>AMQP ports accepting connections for supported AMQP protocols.</para></listitem>
            <listitem><para>HTTP ports accepting connections for HTTP and HTTPS (by selecting the SSL transport) and used by web management plugin.</para></listitem>
            <listitem><para>JMX related ports supporting RMI and JMX_RMI protocols and used by JMX management plugin.</para></listitem>
        </itemizedlist>
    </para>

    <para>
        It is possible to create any number of HTTP and AMQP (supporting any mixture of AMQP versions) ports, however only
        two JMX-related ports can recommended to configure on the Broker: one with the RMI protocol for the RMI Registry to
        advertise the JMX Connector Server and another with the JMX_RMI protocol for the JMX Connector Server itself.
    </para>

    <para>
        A configured <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Provider</link> must be
        selected on ports using the AMQP, HTTP and JMX_RMI protocols.
    </para>

    <para>
        SSL can be enabled forPorts with protocols that support it by selecting the 'SSL' transport, at which
        point a configured <link linkend="Java-Broker-SSL-Keystore">KeyStore</link> must also be selected for the Port.
    </para>

    <para>
        Client Certificate Authentication can be configured for AMQP ports. This requires selecting one or more configured
        <link linkend="SSL-Truststore-ClientCertificate">TrustStores</link> on the Port and setting the <emphasis>needClientAuthentication</emphasis>
        and <emphasis>wantClientAuthentication</emphasis> attributes as desired.
        They allow control of whether the client must present an SSL certificate, allowing for three possible states:
        required (needClientAuth = true), requested (wantClientAuth = true), or none desired (both false, the default).
        If both elements are set to true, needClientAuth takes precedence. When using Client Certificate Authentication
        it may be desirable to use the <link linkend="Java-Broker-Security-External-Provider">External Authentication Provider</link>.
    </para>

    <important>
        Changes to port attributes will take effect only after broker restart. You should restart the broker
        immediately if you require the attribute change sto take effect.
    </important>

    <important>
        Following deletion of an active Port, the port remains bound until the Broker is restarted. You should restart the broker
        immediately if you require preventing new connections on the port or disconnecting existing clients.
    </important>

  </section>

</chapter>