doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Ports.xml

<?xml version="1.0"?>
<!--

 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.

-->

<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Management-Managing-Ports">
    <title>Ports</title>
    <para>Ports provide TCP/IP connectivity for messaging and management. A port is defined to use a
        protocol. This can be an AMQP protocol for messaging or HTTP for management.</para>
    <para>A port is defined to have one or more transports. A transport can either be plain (TCP) or
        SSL (TLS). When SSL is in use, the port can be configured to accept or require client
        authentication.</para>
    <para>Any number of ports defined to use AMQP or HTTP protocols can be defined.</para>
    <para>Ports can only be managed by the HTTP management channel.</para>
    <section xml:id="Java-Broker-Management-Managing-Ports-Context">
        <title>Context</title>
        <para>
            <itemizedlist>
                <listitem>
                    <para><emphasis>qpid.port.max_open_connections</emphasis>. The default maximum number
                       of concurrent connections supported by an AMQP port.</para>
                </listitem>
                <listitem>
                    <para><emphasis>qpid.port.amqp.acceptBacklog</emphasis>. The backlog is the maximum
                        number of pending connections that may be queued by the AMQP port. Once the queue
                        is full, further connections will be refused. This is a request to the operating system
                        which may or may not be respected. The operating system itself may impose a ceiling.
                        <footnote><para>Some Linux distributions govern the ceiling with a <literal>sysctl</literal>
                            setting <literal>net.core.somaxconn</literal>.</para></footnote></para>
                </listitem>
            </itemizedlist>
        </para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Ports-Attributes">
        <title>Attributes</title>
        <para><itemizedlist>
                <listitem>
                    <para><emphasis>Name the port</emphasis>.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Port number</emphasis>.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Binding address</emphasis>. Used to limit port binding to a
                        single network interface.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Authentication Provider</emphasis>. The <link linkend="Java-Broker-Concepts-Authentication-Providers">authentication
                            provider</link> used to authenticate incoming connections.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Protocol(s)</emphasis>. A list of protocols to be supported by
                        the port. For messaging choose one or more AMQP protocols. For management
                        choose HTTP.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Transports</emphasis>. A list of transports supported by the
                        port. For messaging or HTTP management chose TCP, SSL or both.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Enabled/Disabled Cipher Suites</emphasis>. Allows cipher
                        suites supported by the JVM to be enabled or disabled.  The cipher
                        suite names are those understood by the JVM.
                    </para>
                    <para>SSLv3 is disabled by default.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Keystore</emphasis>. <link linkend="Java-Broker-Management-Managing-Keystores">Keystore</link>
                        containing the Broker's private key. Required if SSL is in use.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Want/Need Client Auth</emphasis>. Client authentication can be
                        either accepted if offered (want), or demanded (need). When Client
                        Certificate Authentication is in use a Truststore must be configured. When
                        using Client Certificate Authentication it may be desirable to use the <link linkend="Java-Broker-Security-External-Provider">External Authentication
                            Provider</link>.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Truststore</emphasis>. <link linkend="Java-Broker-Management-Managing-Truststores">Trust store</link>
                        contain an issuer certificate or the public keys of the clients themselves
                        if peers only is desired.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Maximum Open Connections</emphasis>. AMQP ports only.  Limits
                     the number of connections that may be open at any one time.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Thread pool size</emphasis>. AMQP ports only.  Number of worker threads
                    used to process AMQP connections during connection negotiation phase.</para>
                    <para>Defaults to 8.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Number of selectors</emphasis>. AMQP ports only.  Number of worker threads
                    used from the thread pool to dispatch I/O activity to the worker threads.</para>
                    <para>Defaults to one eighth of the thread pool size. Minimum 1.</para>
                </listitem>
        </itemizedlist></para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Ports-Children">
        <title>Children</title>
        <para>
            <itemizedlist>
                <listitem>
                    <para>Connection</para>
                </listitem>
            </itemizedlist>
        </para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Ports-Lifecycle">
        <title>Lifecycle</title>
        <para>Not supported</para>
        <important>
            <para>When updating an existing port, changes to SSL settings, binding address and port
                numbers do not become effective until the Broker is restarted.</para>
        </important>
    </section>
</section>