activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From clebertsuco...@apache.org
Subject [17/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Date Mon, 08 Dec 2014 15:49:48 GMT
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/configuration-index.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuration-index.xml b/docs/user-manual/en/configuration-index.xml
deleted file mode 100644
index 8307d99..0000000
--- a/docs/user-manual/en/configuration-index.xml
+++ /dev/null
@@ -1,396 +0,0 @@
-<?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.                                                -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="configuration-index">
-    <title>Configuration Reference</title>
-    <para>This section is a quick index for looking up configuration. Click on the element name to
-        go to the specific chapter.</para>
-    <section id="server.configuration">
-        <title>Server Configuration</title>
-        <section>
-            <title>activemq-configuration.xml</title>
-            <para>This is the main core server configuration file.</para>
-            <table frame="topbot" border="2">
-                <title>Server Configuration</title>
-                <tgroup cols="4">
-                    <colspec colname="c1" colnum="1"/>
-                    <colspec colname="c2" colnum="2"/>
-                    <colspec colname="c3" colnum="3"/>
-                    <colspec colname="c4" colnum="4"/>
-                    <thead>
-                        <row>
-                            <entry>Element Name</entry>
-                            <entry>Element Type</entry>
-                            <entry>Description</entry>
-                            <entry>Default</entry>
-                        </row>
-                    </thead>
-                    <!-- The options reference is generated from the schema.  If something is wrong
-                         in the reference, it must be fixed in the annotations present in the
-                         schema. -->
-                      <xi:include href="../target/generated-resources/xml/xslt/activemq-configuration.xml"
-                                  xmlns:xi="http://www.w3.org/2001/XInclude"/>
-                </tgroup>
-            </table>
-        </section>
-        <section>
-            <title>activemq-jms.xml</title>
-            <para>This is the configuration file used by the server side JMS service to load JMS
-                Queues, Topics and Connection Factories.</para>
-            <table frame="topbot" border="2">
-                <title>JMS Server Configuration</title>
-                <tgroup cols="4">
-                    <colspec colname="c1" colnum="1"/>
-                    <colspec colname="c2" colnum="2"/>
-                    <colspec colname="c3" colnum="3"/>
-                    <colspec colname="c4" colnum="4"/>
-                    <thead>
-                        <row>
-                            <entry>Element Name</entry>
-                            <entry>Element Type</entry>
-                            <entry>Description</entry>
-                            <entry>Default</entry>
-                        </row>
-                    </thead>
-                    <tbody>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">queue</link></entry>
-                            <entry>Queue</entry>
-                            <entry>a queue to create and add to JNDI</entry>
-                            <entry/>
-                        </row>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">queue.name (attribute)</link></entry>
-                            <entry>String</entry>
-                            <entry>unique name of the queue</entry>
-                            <entry/>
-                        </row>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">queue.entry</link></entry>
-                            <entry>String</entry>
-                            <entry>context where the queue will be bound in JNDI (there can be many)</entry>
-                            <entry/>
-                        </row>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">queue.durable</link></entry>
-                            <entry>Boolean</entry>
-                            <entry>is the queue durable?</entry>
-                            <entry>true</entry>
-                        </row>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">queue.filter</link></entry>
-                            <entry>String</entry>
-                            <entry>optional filter expression for the queue</entry>
-                            <entry/>
-                        </row>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">topic</link></entry>
-                            <entry>Topic</entry>
-                            <entry>a topic to create and add to JNDI</entry>
-                            <entry/>
-                        </row>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">topic.name (attribute)</link></entry>
-                            <entry>String</entry>
-                            <entry>unique name of the topic</entry>
-                            <entry/>
-                        </row>
-                        <row>
-                            <entry><link linkend="using-jms.server.configuration">topic.entry</link></entry>
-                            <entry>String</entry>
-                            <entry>context where the topic will be bound in JNDI (there can be many)</entry>
-                            <entry/>
-                        </row>
-                    </tbody>
-                </tgroup>
-            </table>
-        </section>
-
-        <section id="configuration.masked-password">
-           <title>Using Masked Passwords in Configuration Files</title>
-           <para>By default all passwords in ActiveMQ server's configuration files are in plain text form. This usually poses no security issues as those
-           files should be well protected from unauthorized accessing. However, in some circumstances a user doesn't want to expose its passwords to more
-           eyes than necessary. </para>
-
-           <para>ActiveMQ can be configured to use 'masked' passwords in its configuration files. A masked password is an obscure string representation
-           of a real password. To mask a password a user will use an 'encoder'. The encoder takes in the real password and outputs the masked version.
-           A user can then replace the real password in the configuration files with the new masked password.
-           When ActiveMQ loads a masked password, it uses a suitable 'decoder' to decode it into real password.</para>
-
-           <para>ActiveMQ provides a default password encoder and decoder. Optionally users can use or implement their own encoder and decoder for
-           masking the passwords.</para>
-
-           <section> <title>Password Masking in Server Configuration File</title>
-
-              <section> <title>The password masking property</title>
-
-              <para>The server configuration file has a property that defines the default masking behaviors over the entire file scope.</para>
-
-              <para><literal>mask-password</literal>: this boolean type property indicates if a password should be masked or not. Set it to "true"
-              if you want your passwords masked. The default value is "false".</para>
-              </section>
-
-              <section> <title>Specific masking behaviors</title>
-
-                 <section> <title>cluster-password</title>
-
-                 <para>The nature of the value of cluster-password is subject to the value of property 'mask-password'. If it is true
-                 the cluster-password is masked.</para>
-                 </section>
-
-                 <section> <title>Passwords in connectors and acceptors</title>
-
-                 <para>In the server configuration, Connectors and Acceptors sometimes needs to specify passwords. For example
-                 if a users wants to use an SSL-enabled NettyAcceptor, it can specify a key-store-password and a trust-store-password. Because
-                 Acceptors and Connectors are pluggable implementations, each transport will have different password masking needs.</para>
-
-                 <para>When a Connector or Acceptor configuration is initialised, ActiveMQ will add the "mask-password" and
-                 "password-codec" values to the Connector or Acceptors params using the keys <literal>activemq.usemaskedpassword</literal>
-                 and <literal>activemq.passwordcodec</literal> respectively. The Netty and InVM implementations will use these
-                 as needed and any other implementations will have access to these to use if they so wish.</para>
-                 </section>
-
-                 <section> <title>Passwords in Core Bridge configurations</title>
-
-                 <para>Core Bridges are configured in the server configuration file and so the masking of its 'password' properties
-                 follows the same rules as that of 'cluster-password'.</para>
-                 </section>
-              </section>
-
-              <section> <title>Examples</title>
-
-              <para>The following table summarizes the relations among the above-mentioned properties</para>
-
-              <table frame="topbot" border="2">
-                <tgroup cols="4">
-                    <colspec colname="c1" colnum="1"/>
-                    <colspec colname="c2" colnum="2"/>
-                    <colspec colname="c3" colnum="3"/>
-                    <colspec colname="c4" colnum="4"/>
-                    <thead>
-                        <row>
-                            <entry>mask-password</entry>
-                            <entry>cluster-password</entry>
-                            <entry>acceptor/connector passwords</entry>
-                            <entry>bridge password</entry>
-                        </row>
-                    </thead>
-                    <tbody>
-                        <row>
-                            <entry>absent</entry>
-                            <entry>plain text</entry>
-                            <entry>plain text</entry>
-                            <entry>plain text</entry>
-                        </row>
-                        <row>
-                            <entry>false</entry>
-                            <entry>plain text</entry>
-                            <entry>plain text</entry>
-                            <entry>plain text</entry>
-                        </row>
-                        <row>
-                            <entry>true</entry>
-                            <entry>masked</entry>
-                            <entry>masked</entry>
-                            <entry>masked</entry>
-                        </row>
-                    </tbody>
-                </tgroup>
-              </table>
-
-<para>Examples</para>
-
-<para>Note: In the following examples if related attributed or properties are absent, it means they are not specified in the configure file.</para>
-
-<para>example 1</para>
-
-<programlisting>
-&lt;cluster-password>bbc&lt;/cluster-password></programlisting>
-
-<para>This indicates the cluster password is a plain text value ("bbc").</para>
-
-<para>example 2</para>
-
-<programlisting>
-&lt;mask-password>true&lt;/mask-password>
-&lt;cluster-password>80cf731af62c290&lt;/cluster-password></programlisting>
-
-              <para>This indicates the cluster password is a masked value and ActiveMQ will use its built-in decoder to decode it. All other
-              passwords in the configuration file, Connectors, Acceptors and Bridges, will also use masked passwords.</para>
-              </section>
-           </section>
-
-           <section> <title>JMS Bridge password masking</title>
-
-           <para>The JMS Bridges are configured and deployed as separate beans so they need separate configuration to control the password masking.
-           A JMS Bridge has two password parameters in its constructor, SourcePassword and TargetPassword. It uses the following two optional
-           properties to control their masking:</para>
-
-           <para><literal>useMaskedPassword</literal> -- If set to "true" the passwords are masked. Default is false.</para>
-           <para><literal>passwordCodec</literal> -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if
-           <literal>useMaskedPassword</literal> is false. The format of this property is a full qualified class name optionally followed by key/value pairs,
-           separated by semi-colons. For example:</para>
-
-<literal>
-&lt;property name="useMaskedPassword">true&lt;/property>
-</literal><para></para>
-<literal>
-&lt;property name="passwordCodec">com.foo.FooDecoder;key=value&lt;/property>
-</literal>
-           <para>ActiveMQ will load this property and initialize the class with a parameter map containing the "key"->"value" pair.
-           If <literal>passwordCodec</literal> is not specified, the built-in decoder is used.</para>
-
-           </section>
-
-           <section> <title>Masking passwords in ActiveMQ ResourceAdapters and MDB activation configurations</title>
-
-           <para>Both ra.xml and MDB activation configuration have a 'password' property that can be masked. They are controlled by the following two
-           optional Resource Adapter properties in ra.xml:</para>
-
-           <para><literal>UseMaskedPassword</literal> -- If setting to "true" the passwords are masked. Default is false.</para>
-           <para><literal>PasswordCodec</literal> -- Class name and its parameters for the Decoder used to decode the masked password.
-              Ignored if UseMaskedPassword is false. The format of this property is a full qualified class name optionally followed by key/value pairs.
-              It is the same format as that for JMS Bridges. Example:</para>
-
-<programlisting>
-&lt;config-property>
-  &lt;config-property-name>UseMaskedPassword&lt;/config-property-name>
-  &lt;config-property-type>boolean&lt;/config-property-type>
-  &lt;config-property-value>true&lt;/config-property-value>
-&lt;/config-property>
-&lt;config-property>
-  &lt;config-property-name>PasswordCodec&lt;/config-property-name>
-  &lt;config-property-type>java.lang.String&lt;/config-property-type>
-  &lt;config-property-value>com.foo.ADecoder;key=helloworld&lt;/config-property-value>
-&lt;/config-property></programlisting>
-
-           <para>With this configuration, both passwords in ra.xml and all of its MDBs will have to be in masked form.</para>
-
-           </section>
-
-           <section> <title>Masking passwords in activemq-users.xml</title>
-
-           <para>ActiveMQ's built-in security manager uses plain configuration files where the user passwords are specified in plaintext
-           forms by default. To mask those parameters the following two properties are needed:</para>
-
-           <para> <literal>mask-password</literal> -- If set to "true" all the passwords are masked. Default is false.</para>
-           <para> <literal>password-codec</literal> -- Class name and its parameters for the Decoder used to decode the masked password.
-           Ignored if <literal>mask-password</literal> is false. The format of this property is a full qualified class name optionally
-           followed by key/value pairs. It is the same format as that for JMS Bridges. Example:</para>
-
-<programlisting>
-&lt;mask-password>true&lt;/mask-password>
-&lt;password-codec>org.apache.activemq.utils.DefaultSensitiveStringCodec;key=hello world&lt;/password-codec></programlisting>
-
-           <para>When so configured, the ActiveMQ security manager will initialize a DefaultSensitiveStringCodec with the parameters
-           "key"->"hello world", then use it to decode all the masked passwords in this configuration file.</para>
-
-           </section>
-
-           <section> <title>Choosing a decoder for password masking</title>
-
-           <para>As described in the previous sections, all password masking requires a decoder. A decoder uses an algorithm to
-           convert a masked password into its original clear text form in order to be used in various security operations. The algorithm
-           used for decoding must match that for encoding. Otherwise the decoding may not be successful.</para>
-
-           <para>For user's convenience ActiveMQ provides a default built-in Decoder. However a user can if they so wish implement their own.</para>
-
-              <section><title>The built-in Decoder</title>
-
-              <para>Whenever no decoder is specified in the configuration file, the built-in decoder is used. The class name for the built-in
-              decoder is org.apache.activemq.utils.DefaultSensitiveStringCodec. It has both encoding and decoding capabilities. It uses java.crypto.Cipher
-              utilities to encrypt (encode) a plaintext password and decrypt a mask string using same algorithm. Using this decoder/encoder is
-              pretty straightforward. To get a mask for a password, just run the following in command line:</para>
-
-<programlisting>
-java org.apache.activemq.utils.DefaultSensitiveStringCodec "your plaintext password"</programlisting>
-
-              <para>Make sure the classpath is correct. You'll get something like</para>
-
-<programlisting>
-Encoded password: 80cf731af62c290</programlisting>
-
-              <para>Just copy "80cf731af62c290" and replace your plaintext password with it.</para>
-              </section>
-
-              <section><title>Using a different decoder</title>
-
-              <para>It is possible to use a different decoder rather than the built-in one. Simply make sure the decoder
-              is in ActiveMQ's classpath and configure the server to use it as follows:</para>
-
-<programlisting>
-&lt;password-codec>com.foo.SomeDecoder;key1=value1;key2=value2&lt;/password-codec></programlisting>
-
-              <para>If your decoder needs params passed to it you can do this via key/value pairs when configuring.
-              For instance if your decoder needs say a "key-location" parameter, you can define like so:</para>
-
-<programlisting>
-&lt;password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile&lt;/password-codec></programlisting>
-
-              <para>Then configure your cluster-password like this:</para>
-
-<programlisting>
-&lt;mask-password>true&lt;/mask-password>
-&lt;cluster-password>masked_password&lt;/cluster-password></programlisting>
-
-              <para>When ActiveMQ reads the cluster-password it will initialize the NewDecoder and use it to decode "mask_password".
-              It also process all passwords using the new defined decoder.</para>
-              </section>
-
-              <section><title>Implementing your own codecs</title>
-
-              <para>To use a different decoder than the built-in one, you either pick one from existing libraries or you implement it yourself.
-              All decoders must implement the <literal>org.apache.activemq.utils.SensitiveDataCodec&lt;T></literal> interface:</para>
-
-<programlisting>
-public interface SensitiveDataCodec&lt;T>
-{
-   T decode(Object mask) throws Exception;
-
-   void init(Map&lt;String, String> params);
-}</programlisting>
-
-              <para>This is a generic type interface but normally for a password you just need String type.
-                  So a new decoder would be defined like </para>
-
-<programlisting>
-public class MyNewDecoder implements SensitiveDataCodec&lt;String>
-{
-   public String decode(Object mask) throws Exception
-   {
-      //decode the mask into clear text password
-      return "the password";
-   }
-
-   public void init(Map&lt;String, String> params)
-   {
-      //initialization done here. It is called right after the decoder has been created.
-   }
-}</programlisting>
-
-             <para>Last but not least, once you get your own decoder, please add it to the classpath. Otherwise ActiveMQ will
-             fail to load it!</para>
-             </section>
-        </section>
-      </section>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/configuring-transports.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuring-transports.md b/docs/user-manual/en/configuring-transports.md
new file mode 100644
index 0000000..f1d6194
--- /dev/null
+++ b/docs/user-manual/en/configuring-transports.md
@@ -0,0 +1,462 @@
+Configuring the Transport
+=========================
+
+ActiveMQ has a fully pluggable and highly flexible transport layer and
+defines its own Service Provider Interface (SPI) to make plugging in a
+new transport provider relatively straightforward.
+
+In this chapter we'll describe the concepts required for understanding
+ActiveMQ transports and where and how they're configured.
+
+Understanding Acceptors
+=======================
+
+One of the most important concepts in ActiveMQ transports is the
+*acceptor*. Let's dive straight in and take a look at an acceptor
+defined in xml in the configuration file `activemq-configuration.xml`.
+
+    <acceptors>
+       <acceptor name="netty">
+          <factory-class>
+             org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory
+          </factory-class>
+          <param key="port" value="5446"/>
+       </acceptor>
+    </acceptors>
+
+Acceptors are always defined inside an `acceptors` element. There can be
+one or more acceptors defined in the `acceptors` element. There's no
+upper limit to the number of acceptors per server.
+
+Each acceptor defines a way in which connections can be made to the
+ActiveMQ server.
+
+In the above example we're defining an acceptor that uses
+[Netty](http://jboss.org/netty) to listen for connections at port
+`5446`.
+
+The `acceptor` element contains a sub-element `factory-class`, this
+element defines the factory used to create acceptor instances. In this
+case we're using Netty to listen for connections so we use the Netty
+implementation of an `AcceptorFactory` to do this. Basically, the
+`factory-class` element determines which pluggable transport we're going
+to use to do the actual listening.
+
+The `acceptor` element can also be configured with zero or more `param`
+sub-elements. Each `param` element defines a key-value pair. These
+key-value pairs are used to configure the specific transport, the set of
+valid key-value pairs depends on the specific transport be used and are
+passed straight through to the underlying transport.
+
+Examples of key-value pairs for a particular transport would be, say, to
+configure the IP address to bind to, or the port to listen at.
+
+Note that unlike versions before 2.4 an Acceptor can now support
+multiple protocols. By default this will be all available protocols but
+can be limited by either the now deprecated `protocol` param or by
+setting a comma seperated list to the newly added `protocols` parameter.
+
+Understanding Connectors
+========================
+
+Whereas acceptors are used on the server to define how we accept
+connections, connectors are used by a client to define how it connects
+to a server.
+
+Let's look at a connector defined in our `activemq-configuration.xml`
+file:
+
+    <connectors>
+       <connector name="netty">
+          <factory-class>
+             org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
+          </factory-class>
+          <param key="port" value="5446"/>
+       </connector>
+    </connectors>
+
+Connectors can be defined inside a `connectors` element. There can be
+one or more connectors defined in the `connectors` element. There's no
+upper limit to the number of connectors per server.
+
+You make ask yourself, if connectors are used by the *client* to make
+connections then why are they defined on the *server*? There are a
+couple of reasons for this:
+
+-   Sometimes the server acts as a client itself when it connects to
+    another server, for example when one server is bridged to another,
+    or when a server takes part in a cluster. In this cases the server
+    needs to know how to connect to other servers. That's defined by
+    *connectors*.
+
+-   If you're using JMS and you're using JNDI on the client to look up
+    your JMS connection factory instances then when creating the
+    `ActiveMQConnectionFactory` it needs to know what server that
+    connection factory will create connections to.
+
+    That's defined by the `java.naming.provider.url` element in the JNDI
+    context environment, e.g. `jndi.properties`. Behind the scenes, the
+    `org.apache.activemq.jndi.ActiveMQInitialContextFactory` uses the
+    `java.naming.provider.url` to construct the transport. Here's a
+    simple example:
+
+        java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+        java.naming.provider.url=tcp://myhost:5445
+
+Configuring the transport directly from the client side.
+========================================================
+
+How do we configure a core `ClientSessionFactory` with the information
+that it needs to connect with a server?
+
+Connectors are also used indirectly when directly configuring a core
+`ClientSessionFactory` to directly talk to a server. Although in this
+case there's no need to define such a connector in the server side
+configuration, instead we just create the parameters and tell the
+`ClientSessionFactory` which connector factory to use.
+
+Here's an example of creating a `ClientSessionFactory` which will
+connect directly to the acceptor we defined earlier in this chapter, it
+uses the standard Netty TCP transport and will try and connect on port
+5446 to localhost (default):
+
+    Map<String, Object> connectionParams = new HashMap<String, Object>();
+
+    connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME,
+                        5446);
+
+    TransportConfiguration transportConfiguration =
+        new TransportConfiguration(
+        "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
+        connectionParams);
+
+    ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration);
+
+    ClientSessionFactory sessionFactory = locator.createClientSessionFactory();
+
+    ClientSession session = sessionFactory.createSession(...);
+
+    etc
+
+Similarly, if you're using JMS, you can configure the JMS connection
+factory directly on the client side without having to define a connector
+on the server side or define a connection factory in `activemq-jms.xml`:
+
+    Map<String, Object> connectionParams = new HashMap<String, Object>();
+
+    connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 5446);
+
+    TransportConfiguration transportConfiguration =
+        new TransportConfiguration(
+        "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
+        connectionParams);
+
+    ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration);
+
+    Connection jmsConnection = connectionFactory.createConnection();
+
+    etc
+
+Configuring the Netty transport
+===============================
+
+Out of the box, ActiveMQ currently uses
+[Netty](http://www.jboss.org/netty/), a high performance low level
+network library.
+
+Our Netty transport can be configured in several different ways; to use
+old (blocking) Java IO, or NIO (non-blocking), also to use
+straightforward TCP sockets, SSL, or to tunnel over HTTP or HTTPS..
+
+We believe this caters for the vast majority of transport requirements.
+
+Single Port Support
+-------------------
+
+As of version 2.4 ActiveMQ now supports using a single port for all
+protocols, ActiveMQ will automatically detect which protocol is being
+used CORE, AMQP, STOMP or OPENWIRE and use the appropriate ActiveMQ
+handler. It will also detect whether protocols such as HTTP or Web
+Sockets are being used and also use the appropriate decoders
+
+It is possible to limit which protocols are supported by using the
+`protocols` parameter on the Acceptor like so:
+
+        <param key="protocols" value="CORE,AMQP"/>
+                
+
+> **Note**
+>
+> The `protocol` parameter is now deprecated
+
+Configuring Netty TCP
+---------------------
+
+Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP
+can be configured to use old blocking Java IO or non blocking Java NIO.
+We recommend you use the Java NIO on the server side for better
+scalability with many concurrent connections. However using Java old IO
+can sometimes give you better latency than NIO when you're not so
+worried about supporting many thousands of concurrent connections.
+
+If you're running connections across an untrusted network please bear in
+mind this transport is unencrypted. You may want to look at the SSL or
+HTTPS configurations.
+
+With the Netty TCP transport all connections are initiated from the
+client side. I.e. the server does not initiate any connections to the
+client. This works well with firewall policies that typically only allow
+connections to be initiated in one direction.
+
+All the valid Netty transport keys are defined in the class
+`org.apache.activemq.core.remoting.impl.netty.TransportConstants`. Most
+parameters can be used either with acceptors or connectors, some only
+work with acceptors. The following parameters can be used to configure
+Netty for simple TCP:
+
+-   `use-nio`. If this is `true` then Java non blocking NIO will be
+    used. If set to `false` then old blocking Java IO will be used.
+
+    If you require the server to handle many concurrent connections, we
+    highly recommend that you use non blocking Java NIO. Java NIO does
+    not maintain a thread per connection so can scale to many more
+    concurrent connections than with old blocking IO. If you don't
+    require the server to handle many concurrent connections, you might
+    get slightly better performance by using old (blocking) IO. The
+    default value for this property is `false` on the server side and
+    `false` on the client side.
+
+-   `host`. This specifies the host name or IP address to connect to
+    (when configuring a connector) or to listen on (when configuring an
+    acceptor). The default value for this property is `localhost`. When
+    configuring acceptors, multiple hosts or IP addresses can be
+    specified by separating them with commas. It is also possible to
+    specify `0.0.0.0` to accept connection from all the host's network
+    interfaces. It's not valid to specify multiple addresses when
+    specifying the host for a connector; a connector makes a connection
+    to one specific address.
+
+    > **Note**
+    >
+    > Don't forget to specify a host name or IP address! If you want
+    > your server able to accept connections from other nodes you must
+    > specify a hostname or IP address at which the acceptor will bind
+    > and listen for incoming connections. The default is localhost
+    > which of course is not accessible from remote nodes!
+
+-   `port`. This specified the port to connect to (when configuring a
+    connector) or to listen on (when configuring an acceptor). The
+    default value for this property is `5445`.
+
+-   `tcp-no-delay`. If this is `true` then [Nagle's
+    algorithm](http://en.wikipedia.org/wiki/Nagle%27s_algorithm) will be
+    disabled. This is a [Java (client) socket
+    option](http://docs.oracle.com/javase/7/docs/technotes/guides/net/socketOpt.html).
+    The default value for this property is `true`.
+
+-   `tcp-send-buffer-size`. This parameter determines the size of the
+    TCP send buffer in bytes. The default value for this property is
+    `32768` bytes (32KiB).
+
+    TCP buffer sizes should be tuned according to the bandwidth and
+    latency of your network. Here's a good link that explains the theory
+    behind [this](http://www-didc.lbl.gov/TCP-tuning/).
+
+    In summary TCP send/receive buffer sizes should be calculated as:
+
+        buffer_size = bandwidth * RTT.
+
+    Where bandwidth is in *bytes per second* and network round trip time
+    (RTT) is in seconds. RTT can be easily measured using the `ping`
+    utility.
+
+    For fast networks you may want to increase the buffer sizes from the
+    defaults.
+
+-   `tcp-receive-buffer-size`. This parameter determines the size of the
+    TCP receive buffer in bytes. The default value for this property is
+    `32768` bytes (32KiB).
+
+-   `batch-delay`. Before writing packets to the transport, ActiveMQ can
+    be configured to batch up writes for a maximum of `batch-delay`
+    milliseconds. This can increase overall throughput for very small
+    messages. It does so at the expense of an increase in average
+    latency for message transfer. The default value for this property is
+    `0` ms.
+
+-   `direct-deliver`. When a message arrives on the server and is
+    delivered to waiting consumers, by default, the delivery is done on
+    the same thread as that on which the message arrived. This gives
+    good latency in environments with relatively small messages and a
+    small number of consumers, but at the cost of overall throughput and
+    scalability - especially on multi-core machines. If you want the
+    lowest latency and a possible reduction in throughput then you can
+    use the default value for `direct-deliver` (i.e. true). If you are
+    willing to take some small extra hit on latency but want the highest
+    throughput set `direct-deliver` to `false
+                            `.
+
+-   `nio-remoting-threads`. When configured to use NIO, ActiveMQ will,
+    by default, use a number of threads equal to three times the number
+    of cores (or hyper-threads) as reported by
+    `Runtime.getRuntime().availableProcessors()` for processing incoming
+    packets. If you want to override this value, you can set the number
+    of threads by specifying this parameter. The default value for this
+    parameter is `-1` which means use the value from
+    `Runtime.getRuntime().availableProcessors()` \* 3.
+
+-   `local-address`. When configured a Netty Connector it is possible to
+    specify which local address the client will use when connecting to
+    the remote address. This is typically used in the Application Server
+    or when running Embedded to control which address is used for
+    outbound connections. If the local-address is not set then the
+    connector will use any local address available
+
+-   `local-port`. When configured a Netty Connector it is possible to
+    specify which local port the client will use when connecting to the
+    remote address. This is typically used in the Application Server or
+    when running Embedded to control which port is used for outbound
+    connections. If the local-port default is used, which is 0, then the
+    connector will let the system pick up an ephemeral port. valid ports
+    are 0 to 65535
+
+Configuring Netty SSL
+---------------------
+
+Netty SSL is similar to the Netty TCP transport but it provides
+additional security by encrypting TCP connections using the Secure
+Sockets Layer SSL
+
+Please see the examples for a full working example of using Netty SSL.
+
+Netty SSL uses all the same properties as Netty TCP but adds the
+following additional properties:
+
+-   `ssl-enabled`
+
+    Must be `true` to enable SSL. Default is `false`.
+
+-   `key-store-path`
+
+    When used on an `acceptor` this is the path to the SSL key store on
+    the server which holds the server's certificates (whether
+    self-signed or signed by an authority).
+
+    When used on a `connector` this is the path to the client-side SSL
+    key store which holds the client certificates. This is only relevant
+    for a `connector` if you are using 2-way SSL (i.e. mutual
+    authentication). Although this value is configured on the server, it
+    is downloaded and used by the client. If the client needs to use a
+    different path from that set on the server then it can override the
+    server-side setting by either using the customary
+    "javax.net.ssl.keyStore" system property or the ActiveMQ-specific
+    "org.apache.activemq.ssl.keyStore" system property. The
+    ActiveMQ-specific system property is useful if another component on
+    client is already making use of the standard, Java system property.
+
+-   `key-store-password`
+
+    When used on an `acceptor` this is the password for the server-side
+    keystore.
+
+    When used on a `connector` this is the password for the client-side
+    keystore. This is only relevant for a `connector` if you are using
+    2-way SSL (i.e. mutual authentication). Although this value can be
+    configured on the server, it is downloaded and used by the client.
+    If the client needs to use a different password from that set on the
+    server then it can override the server-side setting by either using
+    the customary "javax.net.ssl.keyStorePassword" system property or
+    the ActiveMQ-specific "org.apache.activemq.ssl.keyStorePassword"
+    system property. The ActiveMQ-specific system property is useful if
+    another component on client is already making use of the standard,
+    Java system property.
+
+-   `trust-store-path`
+
+    When used on an `acceptor` this is the path to the server-side SSL
+    key store that holds the keys of all the clients that the server
+    trusts. This is only relevant for an `acceptor` if you are using
+    2-way SSL (i.e. mutual authentication).
+
+    When used on a `connector` this is the path to the client-side SSL
+    key store which holds the public keys of all the servers that the
+    client trusts. Although this value can be configured on the server,
+    it is downloaded and used by the client. If the client needs to use
+    a different path from that set on the server then it can override
+    the server-side setting by either using the customary
+    "javax.net.ssl.trustStore" system property or the ActiveMQ-specific
+    "org.apache.activemq.ssl.trustStore" system property. The
+    ActiveMQ-specific system property is useful if another component on
+    client is already making use of the standard, Java system property.
+
+-   `trust-store-password`
+
+    When used on an `acceptor` this is the password for the server-side
+    trust store. This is only relevant for an `acceptor` if you are
+    using 2-way SSL (i.e. mutual authentication).
+
+    When used on a `connector` this is the password for the client-side
+    truststore. Although this value can be configured on the server, it
+    is downloaded and used by the client. If the client needs to use a
+    different password from that set on the server then it can override
+    the server-side setting by either using the customary
+    "javax.net.ssl.trustStorePassword" system property or the
+    ActiveMQ-specific "org.apache.activemq.ssl.trustStorePassword"
+    system property. The ActiveMQ-specific system property is useful if
+    another component on client is already making use of the standard,
+    Java system property.
+
+-   `enabled-cipher-suites`
+
+    Whether used on an `acceptor` or `connector` this is a comma
+    separated list of cipher suites used for SSL communication. The
+    default value is `null` which means the JVM's default will be used.
+
+-   `enabled-protocols`
+
+    Whether used on an `acceptor` or `connector` this is a comma
+    separated list of protocols used for SSL communication. The default
+    value is `null` which means the JVM's default will be used.
+
+-   `need-client-auth`
+
+    This property is only for an `acceptor`. It tells a client
+    connecting to this acceptor that 2-way SSL is required. Valid values
+    are `true` or `false`. Default is `false`.
+
+Configuring Netty HTTP
+----------------------
+
+Netty HTTP tunnels packets over the HTTP protocol. It can be useful in
+scenarios where firewalls only allow HTTP traffic to pass.
+
+Please see the examples for a full working example of using Netty HTTP.
+
+Netty HTTP uses the same properties as Netty TCP but adds the following
+additional properties:
+
+-   `http-enabled`. This is now no longer needed as of version 2.4. With
+    single port support ActiveMQ will now automatically detect if http
+    is being used and configure itself.
+
+-   `http-client-idle-time`. How long a client can be idle before
+    sending an empty http request to keep the connection alive
+
+-   `http-client-idle-scan-period`. How often, in milliseconds, to scan
+    for idle clients
+
+-   `http-response-time`. How long the server can wait before sending an
+    empty http response to keep the connection alive
+
+-   `http-server-scan-period`. How often, in milliseconds, to scan for
+    clients needing responses
+
+-   `http-requires-session-id`. If true the client will wait after the
+    first call to receive a session id. Used the http connector is
+    connecting to servlet acceptor (not recommended)
+
+Configuring Netty Servlet
+-------------------------
+
+As of 2.4 ActiveMQ Servlet support will be provided via Undertow in
+Wildfly

http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/configuring-transports.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuring-transports.xml b/docs/user-manual/en/configuring-transports.xml
deleted file mode 100644
index 7e61d50..0000000
--- a/docs/user-manual/en/configuring-transports.xml
+++ /dev/null
@@ -1,443 +0,0 @@
-<?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.                                                -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="configuring-transports">
-    <title>Configuring the Transport</title>
-    <para>ActiveMQ has a fully pluggable and highly flexible transport layer and defines its own
-        Service Provider Interface (SPI) to make plugging in a new transport provider relatively
-        straightforward.</para>
-    <para>In this chapter we'll describe the concepts required for understanding ActiveMQ transports
-        and where and how they're configured.</para>
-    <section id="configuring-transports.acceptors">
-        <title>Understanding Acceptors</title>
-        <para>One of the most important concepts in ActiveMQ transports is the
-                <emphasis>acceptor</emphasis>. Let's dive straight in and take a look at an acceptor
-            defined in xml in the configuration file <literal
-            >activemq-configuration.xml</literal>.</para>
-        <programlisting>
-&lt;acceptors>
-   &lt;acceptor name="netty">
-      &lt;factory-class>
-         org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory
-      &lt;/factory-class>
-      &lt;param key="port" value="5446"/>
-   &lt;/acceptor>
-&lt;/acceptors></programlisting>
-        <para>Acceptors are always defined inside an <literal>acceptors</literal> element. There can
-            be one or more acceptors defined in the <literal>acceptors</literal> element. There's no
-            upper limit to the number of acceptors per server.</para>
-        <para>Each acceptor defines a way in which connections can be made to the ActiveMQ
-            server.</para>
-        <para>In the above example we're defining an acceptor that uses <ulink
-                url="http://jboss.org/netty">Netty</ulink> to listen for connections at port
-                <literal>5446</literal>. </para>
-        <para>The <literal>acceptor</literal> element contains a sub-element <literal
-                >factory-class</literal>, this element defines the factory used to create acceptor
-            instances. In this case we're using Netty to listen for connections so we use the Netty
-            implementation of an <literal>AcceptorFactory</literal> to do this. Basically, the
-                <literal>factory-class</literal> element determines which pluggable transport we're
-            going to use to do the actual listening.</para>
-        <para>The <literal>acceptor</literal> element can also be configured with zero or more
-                <literal>param</literal> sub-elements. Each <literal>param</literal> element defines
-            a key-value pair. These key-value pairs are used to configure the specific transport,
-            the set of valid key-value pairs depends on the specific transport be used and are
-            passed straight through to the underlying transport.</para>
-        <para>Examples of key-value pairs for a particular transport would be, say, to configure the
-            IP address to bind to, or the port to listen at.</para>
-        <para>Note that unlike versions before 2.4 an Acceptor can now support multiple protocols. By default this will
-            be all available protocols but can be limited by either the now deprecated <literal>protocol</literal> param or
-        by setting a comma seperated list to the newly added <literal>protocols</literal> parameter.</para>
-    </section>
-    <section id="configuring-transports.connectors">
-        <title>Understanding Connectors</title>
-        <para>Whereas acceptors are used on the server to define how we accept connections,
-            connectors are used by a client to define how it connects to a server.</para>
-        <para>Let's look at a connector defined in our <literal>activemq-configuration.xml</literal>
-            file:</para>
-        <programlisting>
-&lt;connectors>
-   &lt;connector name="netty">
-      &lt;factory-class>
-         org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
-      &lt;/factory-class>
-      &lt;param key="port" value="5446"/>
-   &lt;/connector>
-&lt;/connectors></programlisting>
-        <para>Connectors can be defined inside a <literal>connectors</literal> element. There can be
-            one or more connectors defined in the <literal>connectors</literal> element. There's no
-            upper limit to the number of connectors per server.</para>
-        <para>You make ask yourself, if connectors are used by the <emphasis>client</emphasis> to
-            make connections then why are they defined on the <emphasis>server</emphasis>? There are
-            a couple of reasons for this:</para>
-        <itemizedlist>
-            <listitem>
-                <para>Sometimes the server acts as a client itself when it connects to another
-                    server, for example when one server is bridged to another, or when a server
-                    takes part in a cluster. In this cases the server needs to know how to connect
-                    to other servers. That's defined by <emphasis>connectors</emphasis>.</para>
-            </listitem>
-            <listitem>
-                <para>If you're using JMS and you're using JNDI on the client to look up your JMS connection factory
-                    instances then when creating the <literal>ActiveMQConnectionFactory</literal> it needs to know what
-                    server that connection factory will create connections to.</para>
-                <para>That's defined by the <literal>java.naming.provider.url</literal> element in the JNDI context
-                    environment, e.g. <literal>jndi.properties</literal>. Behind the scenes, the
-                    <literal>org.apache.activemq.jndi.ActiveMQInitialContextFactory</literal> uses the
-                    <literal>java.naming.provider.url</literal> to construct the transport. Here's a simple example:</para>
-                <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://myhost:5445</programlisting>
-            </listitem>
-        </itemizedlist>
-    </section>
-    <section id="configuring-transports.client.side">
-        <title>Configuring the transport directly from the client side.</title>
-        <para>How do we configure a core <literal>ClientSessionFactory</literal> with the
-            information that it needs to connect with a server?</para>
-        <para>Connectors are also used indirectly when directly configuring a core <literal
-                >ClientSessionFactory</literal> to directly talk to a server. Although in this case
-            there's no need to define such a connector in the server side configuration, instead we
-            just create the parameters and tell the <literal>ClientSessionFactory</literal> which
-            connector factory to use.</para>
-        <para>Here's an example of creating a <literal>ClientSessionFactory</literal> which will
-            connect directly to the acceptor we defined earlier in this chapter, it uses the
-            standard Netty TCP transport and will try and connect on port 5446 to localhost
-            (default):</para>
-        <programlisting>
-Map&lt;String, Object> connectionParams = new HashMap&lt;String, Object>();
-
-connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME,
-                    5446);
-
-TransportConfiguration transportConfiguration =
-    new TransportConfiguration(
-    "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
-    connectionParams);
-
-ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration);
-
-ClientSessionFactory sessionFactory = locator.createClientSessionFactory();
-
-ClientSession session = sessionFactory.createSession(...);
-
-etc</programlisting>
-        <para>Similarly, if you're using JMS, you can configure the JMS connection factory directly
-            on the client side without having to define a connector on the server side or define a
-            connection factory in <literal>activemq-jms.xml</literal>:</para>
-        <programlisting>
-Map&lt;String, Object> connectionParams = new HashMap&lt;String, Object>();
-
-connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 5446);
-
-TransportConfiguration transportConfiguration =
-    new TransportConfiguration(
-    "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
-    connectionParams);
-
-ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration);
-
-Connection jmsConnection = connectionFactory.createConnection();
-
-etc</programlisting>
-    </section>
-    <section id="configuring-transports.netty">
-        <title>Configuring the Netty transport</title>
-        <para>Out of the box, ActiveMQ currently uses <ulink url="http://www.jboss.org/netty/"
-                >Netty</ulink>, a high performance low level network library.</para>
-        <para>Our Netty transport can be configured in several different ways; to use old (blocking)
-            Java IO, or NIO (non-blocking), also to use straightforward TCP sockets, SSL, or to
-            tunnel over HTTP or HTTPS..</para>
-        <para>We believe this caters for the vast majority of transport requirements.</para>
-        <section id="configuring-transports.single-port">
-            <title>Single Port Support</title>
-            <para>As of version 2.4 ActiveMQ now supports using a single port for all protocols, ActiveMQ will automatically
-            detect which protocol is being used CORE, AMQP, STOMP or OPENWIRE and use the appropriate ActiveMQ handler. It will also detect
-            whether protocols such as HTTP or Web Sockets are being used and also use the appropriate decoders</para>
-            <para>It is possible to limit which protocols are supported by using the <literal>protocols</literal> parameter
-            on the Acceptor like so:</para>
-            <programlisting>
-    &lt;param key="protocols" value="CORE,AMQP"/>
-            </programlisting>
-            <note><para>The <literal>protocol</literal> parameter is now deprecated</para></note>
-        </section>
-        <section>
-            <title>Configuring Netty TCP</title>
-            <para>Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP can be
-                configured to use old blocking Java IO or non blocking Java NIO. We recommend you
-                use the Java NIO on the server side for better scalability with many concurrent
-                connections. However using Java old IO can sometimes give you better latency than
-                NIO when you're not so worried about supporting many thousands of concurrent
-                connections. </para>
-            <para>If you're running connections across an untrusted network please bear in mind this
-                transport is unencrypted. You may want to look at the SSL or HTTPS
-                configurations.</para>
-            <para>With the Netty TCP transport all connections are initiated from the client side.
-                I.e. the server does not initiate any connections to the client. This works well
-                with firewall policies that typically only allow connections to be initiated in one
-                direction.</para>
-            <para>All the valid Netty transport keys are defined in the class <literal
-                    >org.apache.activemq.core.remoting.impl.netty.TransportConstants</literal>. Most
-                parameters can be used either with acceptors or connectors, some only work with
-                acceptors. The following parameters can be used to configure Netty for simple
-                TCP:</para>
-            <itemizedlist>
-                <listitem>
-                    <para><literal>use-nio</literal>. If this is <literal>true</literal> then Java
-                        non blocking NIO will be used. If set to <literal>false</literal> then old
-                        blocking Java IO will be used.</para>
-                    <para>If you require the server to handle many concurrent connections, we highly
-                        recommend that you use non blocking Java NIO. Java NIO does not maintain a
-                        thread per connection so can scale to many more concurrent connections than
-                        with old blocking IO. If you don't require the server to handle many
-                        concurrent connections, you might get slightly better performance by using
-                        old (blocking) IO. The default value for this property is <literal
-                            >false</literal> on the server side and <literal>false</literal> on the
-                        client side.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>host</literal>. This specifies the host name or IP address to
-                        connect to (when configuring a connector) or to listen on (when configuring
-                        an acceptor). The default value for this property is <literal
-                            >localhost</literal>. When configuring acceptors, multiple hosts or IP
-                        addresses can be specified by separating them with commas. It is also
-                        possible to specify <code>0.0.0.0</code> to accept connection from all the
-                        host's network interfaces. It's not valid to specify multiple addresses when
-                        specifying the host for a connector; a connector makes a connection to one
-                        specific address.</para>
-                    <note>
-                        <para>Don't forget to specify a host name or IP address! If you want your
-                            server able to accept connections from other nodes you must specify a
-                            hostname or IP address at which the acceptor will bind and listen for
-                            incoming connections. The default is localhost which of course is not
-                            accessible from remote nodes!</para>
-                    </note>
-                </listitem>
-                <listitem>
-                    <para><literal>port</literal>. This specified the port to connect to (when
-                        configuring a connector) or to listen on (when configuring an acceptor). The
-                        default value for this property is <literal>5445</literal>.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>tcp-no-delay</literal>. If this is <literal>true</literal> then
-                            <ulink url="http://en.wikipedia.org/wiki/Nagle%27s_algorithm">Nagle's
-                            algorithm</ulink> will be disabled. This is a
-                            <ulink url="http://docs.oracle.com/javase/7/docs/technotes/guides/net/socketOpt.html">Java (client) socket option</ulink>. The default value for this property is <literal>true</literal>.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>tcp-send-buffer-size</literal>. This parameter determines the
-                        size of the TCP send buffer in bytes. The default value for this property is
-                            <literal>32768</literal> bytes (32KiB).</para>
-                    <para>TCP buffer sizes should be tuned according to the bandwidth and latency of
-                        your network. Here's a good link that explains the theory behind <ulink
-                            url="http://www-didc.lbl.gov/TCP-tuning/">this</ulink>.</para>
-                    <para>In summary TCP send/receive buffer sizes should be calculated as:</para>
-                    <programlisting>
-buffer_size = bandwidth * RTT.</programlisting>
-                    <para>Where bandwidth is in <emphasis>bytes per second</emphasis> and network
-                        round trip time (RTT) is in seconds. RTT can be easily measured using the
-                            <literal>ping</literal> utility.</para>
-                    <para>For fast networks you may want to increase the buffer sizes from the
-                        defaults.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>tcp-receive-buffer-size</literal>. This parameter determines the
-                        size of the TCP receive buffer in bytes. The default value for this property
-                        is <literal>32768</literal> bytes (32KiB).</para>
-                </listitem>
-                <listitem>
-                    <para><literal>batch-delay</literal>. Before writing packets to the transport,
-                        ActiveMQ can be configured to batch up writes for a maximum of <literal
-                            >batch-delay</literal> milliseconds. This can increase overall
-                        throughput for very small messages. It does so at the expense of an increase
-                        in average latency for message transfer. The default value for this property
-                        is <literal>0</literal> ms.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>direct-deliver</literal>. When a message arrives on the server
-                        and is delivered to waiting consumers, by default, the delivery is done on
-                        the same thread as that on which the message arrived. This gives good latency
-                        in environments with relatively small messages and a small number of consumers,
-                        but at the cost of overall throughput and scalability - especially on multi-core
-                        machines. If you want the lowest latency and a possible reduction in throughput
-                        then you can use the default value for <literal>direct-deliver</literal> (i.e.
-                        true). If you are willing to take some small extra hit on latency but want the
-                        highest throughput set <literal>direct-deliver</literal> to <literal>false
-                        </literal>.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>nio-remoting-threads</literal>. When configured to use NIO,
-                        ActiveMQ will, by default, use a number of threads equal to three times the
-                        number of cores (or hyper-threads) as reported by <literal
-                            >Runtime.getRuntime().availableProcessors()</literal> for processing
-                        incoming packets. If you want to override this value, you can set the number
-                        of threads by specifying this parameter. The default value for this
-                        parameter is <literal>-1</literal> which means use the value from <literal
-                            >Runtime.getRuntime().availableProcessors()</literal> * 3.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>local-address</literal>. When configured a Netty Connector it is possible to specify
-                        which local address the client will use when connecting to the remote address. This is typically used
-                        in the Application Server or when running Embedded to control which address is used for outbound
-                        connections. If the local-address is not set then the connector will use any local address available</para>
-                </listitem>
-                <listitem>
-                    <para><literal>local-port</literal>. When configured a Netty Connector it is possible to specify
-                        which local port the client will use when connecting to the remote address. This is typically used
-                        in the Application Server or when running Embedded to control which port is used for outbound
-                        connections. If the local-port default is used, which is 0, then the connector will let the
-                       system pick up an ephemeral port. valid ports are 0 to 65535</para>
-                </listitem>
-            </itemizedlist>
-        </section>
-        <section>
-            <title>Configuring Netty SSL</title>
-            <para>Netty SSL is similar to the Netty TCP transport but it provides additional
-                security by encrypting TCP connections using the Secure Sockets Layer SSL</para>
-            <para>Please see the examples for a full working example of using Netty SSL.</para>
-            <para>Netty SSL uses all the same properties as Netty TCP but adds the following
-                additional properties:</para>
-            <itemizedlist>
-                <listitem>
-                    <para><literal>ssl-enabled</literal></para>
-                    <para>Must be <literal>true</literal> to enable SSL. Default is <literal>false</literal>.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>key-store-path</literal></para>
-                    <para>When used on an <literal>acceptor</literal> this is the path to the SSL key
-                        store on the server which holds the server's certificates (whether self-signed
-                        or signed by an authority).</para>
-                    <para>When used on a <literal>connector</literal> this is the path to the client-side
-                        SSL key store which holds the client certificates. This is only relevant
-                        for a <literal>connector</literal> if you are using 2-way SSL (i.e. mutual
-                        authentication). Although this value is configured on the server, it is
-                        downloaded and used by the client. If the client needs to use a different path
-                        from that set on the server then it can override the server-side setting by either
-                        using the customary "javax.net.ssl.keyStore" system property or the ActiveMQ-specific
-                        "org.apache.activemq.ssl.keyStore" system property. The ActiveMQ-specific system property
-                        is useful if another component on client is already making use of the standard, Java
-                        system property.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>key-store-password</literal></para>
-                    <para>When used on an <literal>acceptor</literal> this is the password for the
-                        server-side keystore.</para>
-                    <para>When used on a <literal>connector</literal> this is the password for the
-                        client-side keystore.  This is only relevant for a <literal>connector</literal>
-                        if you are using 2-way SSL (i.e. mutual authentication). Although this value can
-                        be configured on the server, it is downloaded and used by the client.  If the client
-                        needs to use a different password from that set on the server then it can override
-                        the server-side setting by either using the customary "javax.net.ssl.keyStorePassword"
-                        system property or the ActiveMQ-specific "org.apache.activemq.ssl.keyStorePassword" system
-                        property. The ActiveMQ-specific system property is useful if another component on client
-                        is already making use of the standard, Java system property.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>trust-store-path</literal></para>
-                    <para>When used on an <literal>acceptor</literal> this is the path to the server-side
-                        SSL key store that holds the keys of all the clients that the server trusts.  This
-                        is only relevant for an <literal>acceptor</literal> if you are using 2-way SSL
-                        (i.e. mutual authentication).</para>
-                    <para>When used on a <literal>connector</literal> this is the path to the client-side
-                        SSL key store which holds the public keys of all the servers that the client
-                        trusts. Although this value can be configured on the server, it is downloaded and
-                        used by the client.  If the client needs to use a different path
-                        from that set on the server then it can override the server-side setting by either
-                        using the customary "javax.net.ssl.trustStore" system property or the ActiveMQ-specific
-                        "org.apache.activemq.ssl.trustStore" system property. The ActiveMQ-specific system property
-                        is useful if another component on client is already making use of the standard, Java
-                        system property.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>trust-store-password</literal></para>
-                    <para>When used on an <literal>acceptor</literal> this is the password for the
-                        server-side trust store.  This is only relevant for an <literal>acceptor</literal>
-                        if you are using 2-way SSL (i.e. mutual authentication).</para>
-                    <para>When used on a <literal>connector</literal> this is the password for the
-                        client-side truststore. Although this value can be configured on the server, it is
-                        downloaded and used by the client.   If the client
-                        needs to use a different password from that set on the server then it can override
-                        the server-side setting by either using the customary "javax.net.ssl.trustStorePassword"
-                        system property or the ActiveMQ-specific "org.apache.activemq.ssl.trustStorePassword" system
-                        property. The ActiveMQ-specific system property is useful if another component on client
-                        is already making use of the standard, Java system property.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>enabled-cipher-suites</literal></para>
-                    <para>Whether used on an <literal>acceptor</literal> or <literal>connector</literal> this is a
-                        comma separated list of cipher suites used for SSL communication. The default value is
-                        <literal>null</literal> which means the JVM's default will be used.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>enabled-protocols</literal></para>
-                    <para>Whether used on an <literal>acceptor</literal> or <literal>connector</literal> this is a
-                        comma separated list of protocols used for SSL communication. The default value is
-                        <literal>null</literal> which means the JVM's default will be used.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>need-client-auth</literal></para>
-                    <para>This property is only for an <literal>acceptor</literal>. It tells a client connecting to this
-                        acceptor that 2-way SSL is required. Valid values are <literal>true</literal> or
-                        <literal>false</literal>. Default is <literal>false</literal>.</para>
-                </listitem>
-            </itemizedlist>
-        </section>
-        <section>
-            <title>Configuring Netty HTTP</title>
-            <para>Netty HTTP tunnels packets over the HTTP protocol. It can be useful in scenarios
-                where firewalls only allow HTTP traffic to pass.</para>
-            <para>Please see the examples for a full working example of using Netty HTTP.</para>
-            <para>Netty HTTP uses the same properties as Netty TCP but adds the following additional
-                properties:</para>
-            <itemizedlist>
-                <listitem>
-                    <para><literal>http-enabled</literal>. This is now no longer needed as of version 2.4. With single
-                        port support ActiveMQ will now automatically detect if http is being used and configure itself.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>http-client-idle-time</literal>. How long a client can be idle
-                        before sending an empty http request to keep the connection alive</para>
-                </listitem>
-                <listitem>
-                    <para><literal>http-client-idle-scan-period</literal>. How often, in
-                        milliseconds, to scan for idle clients</para>
-                </listitem>
-                <listitem>
-                    <para><literal>http-response-time</literal>. How long the server can wait before
-                        sending an empty http response to keep the connection alive</para>
-                </listitem>
-                <listitem>
-                    <para><literal>http-server-scan-period</literal>. How often, in milliseconds, to
-                        scan for clients needing responses</para>
-                </listitem>
-                <listitem>
-                    <para><literal>http-requires-session-id</literal>. If true the client will wait
-                        after the first call to receive a session id. Used the http connector is
-                        connecting to servlet acceptor (not recommended) </para>
-                </listitem>
-            </itemizedlist>
-        </section>
-        <section>
-            <title>Configuring Netty Servlet</title>
-            <para>As of 2.4 ActiveMQ Servlet support will be provided via Undertow in Wildfly</para>
-        </section>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/connection-ttl.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/connection-ttl.md b/docs/user-manual/en/connection-ttl.md
new file mode 100644
index 0000000..80af334
--- /dev/null
+++ b/docs/user-manual/en/connection-ttl.md
@@ -0,0 +1,198 @@
+Detecting Dead Connections
+==========================
+
+In this section we will discuss connection time-to-live (TTL) and
+explain how ActiveMQ deals with crashed clients and clients which have
+exited without cleanly closing their resources.
+
+Cleaning up Dead Connection Resources on the Server
+===================================================
+
+Before a ActiveMQ client application exits it is considered good
+practice that it should close its resources in a controlled manner,
+using a `finally` block.
+
+Here's an example of a well behaved core client application closing its
+session and session factory in a finally block:
+
+    ServerLocator locator = null;
+    ClientSessionFactory sf = null;
+    ClientSession session = null;
+
+    try
+    {
+       locator = ActiveMQClient.createServerLocatorWithoutHA(..);
+
+       sf = locator.createClientSessionFactory();;
+
+       session = sf.createSession(...);
+       
+       ... do some stuff with the session...
+    }
+    finally
+    {
+       if (session != null)
+       {
+          session.close();
+       }
+       
+       if (sf != null)
+       {
+          sf.close();
+       }
+
+       if(locator != null)
+       {
+          locator.close();
+       }
+    }
+
+And here's an example of a well behaved JMS client application:
+
+    Connection jmsConnection = null;
+
+    try
+    {
+       ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
+
+       jmsConnection = jmsConnectionFactory.createConnection();
+
+       ... do some stuff with the connection...
+    }
+    finally
+    {
+       if (connection != null)
+       {
+          connection.close();
+       }
+    }
+
+Unfortunately users don't always write well behaved applications, and
+sometimes clients just crash so they don't have a chance to clean up
+their resources!
+
+If this occurs then it can leave server side resources, like sessions,
+hanging on the server. If these were not removed they would cause a
+resource leak on the server and over time this result in the server
+running out of memory or other resources.
+
+We have to balance the requirement for cleaning up dead client resources
+with the fact that sometimes the network between the client and the
+server can fail and then come back, allowing the client to reconnect.
+ActiveMQ supports client reconnection, so we don't want to clean up
+"dead" server side resources too soon or this will prevent any client
+from reconnecting, as it won't be able to find its old sessions on the
+server.
+
+ActiveMQ makes all of this configurable. For each `ClientSessionFactory`
+we define a *connection TTL*. Basically, the TTL determines how long the
+server will keep a connection alive in the absence of any data arriving
+from the client. The client will automatically send "ping" packets
+periodically to prevent the server from closing it down. If the server
+doesn't receive any packets on a connection for the connection TTL time,
+then it will automatically close all the sessions on the server that
+relate to that connection.
+
+If you're using JMS, the connection TTL is defined by the
+`ConnectionTTL` attribute on a `ActiveMQConnectionFactory` instance, or
+if you're deploying JMS connection factory instances direct into JNDI on
+the server side, you can specify it in the xml config, using the
+parameter `connection-ttl`.
+
+The default value for connection ttl on an "unreliable" connection (e.g.
+a Netty connection) is `60000`ms, i.e. 1 minute. The default value for
+connection ttl on a "reliable" connection (e.g. an in-vm connection) is
+`-1`. A value of `-1` for `ConnectionTTL` means the server will never
+time out the connection on the server side.
+
+If you do not wish clients to be able to specify their own connection
+TTL, you can override all values used by a global value set on the
+server side. This can be done by specifying the
+`connection-ttl-override` attribute in the server side configuration.
+The default value for `connection-ttl-override` is `-1` which means "do
+not override" (i.e. let clients use their own values).
+
+Closing core sessions or JMS connections that you have failed to close
+----------------------------------------------------------------------
+
+As previously discussed, it's important that all core client sessions
+and JMS connections are always closed explicitly in a `finally` block
+when you are finished using them.
+
+If you fail to do so, ActiveMQ will detect this at garbage collection
+time, and log a warning similar to the following in the logs (If you are
+using JMS the warning will involve a JMS connection not a client
+session):
+
+    [Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession]  I'm closing a ClientSession you left open. Please make sure you close all ClientSessions explicitly before let
+    ting them go out of scope!
+    [Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession]  The session you didn't close was created here:
+    java.lang.Exception
+       at org.apache.activemq.core.client.impl.DelegatingSession.<init>(DelegatingSession.java:83)
+       at org.acme.yourproject.YourClass (YourClass.java:666)
+
+ActiveMQ will then close the connection / client session for you.
+
+Note that the log will also tell you the exact line of your user code
+where you created the JMS connection / client session that you later did
+not close. This will enable you to pinpoint the error in your code and
+correct it appropriately.
+
+Detecting failure from the client side.
+=======================================
+
+In the previous section we discussed how the client sends pings to the
+server and how "dead" connection resources are cleaned up by the server.
+There's also another reason for pinging, and that's for the *client* to
+be able to detect that the server or network has failed.
+
+As long as the client is receiving data from the server it will consider
+the connection to be still alive.
+
+If the client does not receive any packets for
+`client-failure-check-period` milliseconds then it will consider the
+connection failed and will either initiate failover, or call any
+`FailureListener` instances (or `ExceptionListener` instances if you are
+using JMS) depending on how it has been configured.
+
+If you're using JMS it's defined by the `ClientFailureCheckPeriod`
+attribute on a `ActiveMQConnectionFactory` instance, or if you're
+deploying JMS connection factory instances direct into JNDI on the
+server side, you can specify it in the `activemq-jms.xml ` configuration
+file, using the parameter `client-failure-check-period`.
+
+The default value for client failure check period on an "unreliable"
+connection (e.g. a Netty connection) is `30000`ms, i.e. 30 seconds. The
+default value for client failure check period on a "reliable" connection
+(e.g. an in-vm connection) is `-1`. A value of `-1` means the client
+will never fail the connection on the client side if no data is received
+from the server. Typically this is much lower than connection TTL to
+allow clients to reconnect in case of transitory failure.
+
+Configuring Asynchronous Connection Execution
+=============================================
+
+Most packets received on the server side are executed on the remoting
+thread. These packets represent short-running operations and are always
+executed on the remoting thread for performance reasons.
+
+However, by default some kinds of packets are executed using a thread
+from a thread pool so that the remoting thread is not tied up for too
+long. Please note that processing operations asynchronously on another
+thread adds a little more latency. These packets are:
+
+-   `org.apache.activemq.core.protocol.core.impl.wireformat.RollbackMessage`
+
+-   `org.apache.activemq.core.protocol.core.impl.wireformat.SessionCloseMessage`
+
+-   `org.apache.activemq.core.protocol.core.impl.wireformat.SessionCommitMessage`
+
+-   `org.apache.activemq.core.protocol.core.impl.wireformat.SessionXACommitMessage`
+
+-   `org.apache.activemq.core.protocol.core.impl.wireformat.SessionXAPrepareMessage`
+
+-   `org.apache.activemq.core.protocol.core.impl.wireformat.SessionXARollbackMessage`
+
+To disable asynchronous connection execution, set the parameter
+`async-connection-execution-enabled` in `activemq-configuration.xml` to
+`false` (default value is `true`).


Mime
View raw message