activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chir...@apache.org
Subject svn commit: r1097288 - in /activemq/activemq-apollo/trunk/apollo-website/src/documentation: getting-started.md user-manual.md
Date Thu, 28 Apr 2011 00:07:53 GMT
Author: chirino
Date: Thu Apr 28 00:07:53 2011
New Revision: 1097288

URL: http://svn.apache.org/viewvc?rev=1097288&view=rev
Log:
Adding more config details about transport protocols

Modified:
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/getting-started.md
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md

Modified: activemq/activemq-apollo/trunk/apollo-website/src/documentation/getting-started.md
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/getting-started.md?rev=1097288&r1=1097287&r2=1097288&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/getting-started.md (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/getting-started.md Thu
Apr 28 00:07:53 2011
@@ -90,7 +90,7 @@ The default login id and password is `ad
 
 ### Switching to the BDB Store
 
-Apollo's most fastest message store implementation is the BDB based message store.  
+Apollo's fastest message store implementation is the BDB based message store.  
 Unfortunately, BDB cannot be redistributed by Apache.  It is highly recommended
 that you add it to your apollo installation. You can download it from Oracle at
 [je-4.1.6.jar](http://download.oracle.com/maven/com/sleepycat/je/4.1.6/je-4.1.6.jar) and
@@ -100,5 +100,5 @@ For those of you with curl installed, yo
 
     curl http://download.oracle.com/maven/com/sleepycat/je/4.1.6/je-4.1.6.jar > ${APOLLO_HOME}/lib/je-4.1.6.jar
     
-Next, you need to update the configuration by editing the `etc/apollo.xml` file and
+Once installed, you then need to update the configuration by editing the `etc/apollo.xml`
file and
 replace `jdbm2_store` with `bdb_store`.

Modified: activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md?rev=1097288&r1=1097287&r2=1097288&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md Thu Apr
28 00:07:53 2011
@@ -103,7 +103,8 @@ A `connector` element can be configured 
 * `enabled` : if set to false, then the connector host will be disabled.
 
 * `bind` : The transport that the connector will listen on, it includes the
-  ip address and port that it will bind to.
+  ip address and port that it will bind to.  Transports are specified using 
+  a URI syntax.
 
 * `connection_limit` : The maximum number of concurrently open connections
   this connector will accept before it stops accepting additional
@@ -123,6 +124,43 @@ use the following configuration:
 </connector>
 {pygmentize}
 
+##### TCP Transports
+
+The TCP transport uses the `tcp://` URI scheme.  It uses the URI host
+and port to determine to which local interfaces to bind.  For example:
+
+* `tcp://0.0.0.0:61613` binds to all IPv4 interfaces on port 61613
+* `tcp://[::]:61613` binds to all IPv4 and IPv6 interfaces on port 61613
+* `tcp://127.0.0.1:0` binds to the loopback interface on a dynamic port
+
+The TCP URI also supports several query parameters to fine tune the
+settings used on the socket.  The supported parameters are:
+
+* `receive_buffer_size` : Sets the size of the internal socket receive buffer 
+   and the size of the TCP receive window that is advertised to the remote 
+   peer.  Defaults to 65536 (64k)
+
+* `traffic_class` : Sets traffic class or type-of-service octet in the IP 
+  header for packets sent from the transport.  Defaults to `8` which
+  means the traffic should be optimized for throughput.
+
+* `max_read_rate` : Sets the maximum bytes per second that this transport will
+  receive data at.  This setting throttles reads so that the rate is not exceeded.
+  Defaults to 0 which disabled throttling.
+
+* `max_write_rate` : Sets the maximum bytes per second that this transport will
+  send data at.  This setting throttles writes so that the rate is not exceeded.
+  Defaults to 0 which disabled throttling.
+  
+Example which uses a couple of options:
+
+{pygmentize:: xml}
+<connector id="tcp" bind="tcp://0.0.0.0:61613?receive_buffer_size=1024&amp;max_read_rate=65536"/>
+{pygmentize}
+
+Note that `&amp;` was used to separate the option values instead of just `&` since
the 
+URI being written within an XML file.
+
 #### Virtual Hosts
 
 A virtual hosts allows ${project_name} to support multi tenant style
@@ -375,14 +413,14 @@ A `hawtdb_store` element may be configur
 
 ### Security
 
-#### Using SSL/TLS
+#### The SSL/TLS Transport
 
 ${project_name} supports SSL/TLS for transport level security to avoid 3rd
 parties listening in on the communications between the broker and it's
-clients. To enable it, you just need to add a connector which uses the `ssl`
-or `tls` transport and add a `key_storage` configuration element under the
-`broker` to configure the where the encryption keys and certificates are
-stored.
+clients. To enable it, you just need to add a connector which binds using
+on of the secure transports such as `ssl://`.  It also requires having a 
+`key_storage` configuration element under the `broker` to configure the where 
+the encryption keys and certificates are stored.
 
 Example:
 {pygmentize:: xml}
@@ -391,10 +429,21 @@ Example:
      file="${apollo.base}/etc/keystore" 
      password="password" 
      key_password="password"/>
-  <connector id="tls" bind="tls://0.0.0.0:61614"/>
+  
+  <connector id="stomp-secure" bind="ssl://0.0.0.0:61614"/>
   ...
 {pygmentize}
 
+The `connector` element's `bind` attribute controls which secure transport 
+algorithm gets used by the sever.  Supported values are:
+
+* `ssl://`    - Supports some version of SSL
+* `sslv2://`  - Supports SSL version 2 or higher
+* `sslv3://`  - Supports SSL version 3
+* `tls://`    - Supports some version of TLS
+* `tlsv://`   - Supports RFC 2246: TLS version 1.0 
+* `tls1.1://` - Supports RFC 4346: TLS version 1.1 
+
 The attributes that you can configure on the `key_storage` element are:
 
 * `file` : Path to where the key store is located.
@@ -404,6 +453,9 @@ The attributes that you can configure on
 * `trust_algorithm` : The trust management algorithm, defaults to `SunX509`.
 * `key_algorithm` : The key management algorithm, defaults to `SunX509`.
 
+The SSL/TLS transport is an extension of the TCP transport and as such it supports
+all the same URI options which the TCP transport supports.
+
 #### Authentication
 
 The first step to securing the broker is authenticating users. The default
@@ -780,11 +832,50 @@ messaging interoperability among many la
 ${project_name} supports the following versions of the STOMP specification: 
 
 * [STOMP 1.0](http://stomp.github.com/stomp-specification-1.0.html)
-* [STOMP 1.1](http://stomp.github.com/stomp-specification-1.1.html) *Not final*
+* [STOMP 1.1](http://stomp.github.com/stomp-specification-1.1.html)
 
 The specification is short and simple to read, it is highly recommend that users
 to get familiar with it before using one of the many available client libraries.
 
+### Stomp Protocol Options
+
+You can use the `stomp` configuration element within the `connector` element
+in the `apollo.xml` configuration file to change the default settings used
+in the STOMP protocol implementation.  The `stomp` element supports the 
+following configuration attributes:
+
+* `add_user_header` :  Name of the header which will be added to every received 
+  message received.  The value of the header will be set to the id of user that 
+  sent the message.  Not set by default.
+* `max_header_length` : The maximum allowed length of a STOMP header. Defaults 
+  to 10240 (10k).
+* `max_headers` : The maximum number of allowed headers in a frame.  Defaults 
+  to 1000.
+* `max_data_length` : The maximum size of the body portion of a STOMP frame.  
+  Defaults to 104857600 (100 megs).
+
+It also supports nested `add_user_header` elements to more finely control how
+user headers are added to received STOMP messages.  The `add_user_header` element
+supports the following attributes:
+
+* `name` : The name of the header to set on the STOMP message
+* `separator` : If user has multiple principles which match, this separator
+  will be used to delimit them in the header.  If not set, then only the first
+  matching principle will be set in the header.
+* `kind` : The principle kind to look for.  Defaults to `*` (matches all 
+  principle kinds)
+
+Example:
+
+{pygmentize:: xml}
+<connector id="tcp" bind="tcp://0.0.0.0:61613">
+  <stomp max_header_length="10000">
+    <add_user_header name="user" separator=","
+      kind="org.apache.activemq.jaas.UserPrincipal" />
+  </stomp>
+</connector>
+{pygmentize}
+
 ### Client Libraries
 
 There are many open source STOMP clients for different platforms and



Mime
View raw message