= Java Message Server =

The CSS MessageLog and the [wiki:BEAST Best Ever Alarm System Toolkit] use a Java Message Server. Specifically, the Apache ActiveMQ implementation of JMS. Download it from http://activemq.apache.org.

== Minimal Setup == Unpack the ActiveMQ package from the Apache web site, then {{{ cd apache-activemq-*/bin ./activemq }}}

You might want to copy its default configuration file, conf/activemp.xml into something like my_activemq_setup and then use that configuration file: {{{ ./activemq xbean:file:/path/to/my_activemq_setup.xml }}} That way you can disable things that you don't need, like the web monitor, or enable HTTPTransport to allow tunneling though web proxies.

Markus Moeller (DESY) suggested disabling the "multicast" option in the "networkConnectors" section to prevent multiple JMS servers from magically finding each other and causing more confusion than good.

== Client (CSS) Configuration == When you configure CSS tools to use your JMS server, use a "failover:" URL: {{{ failover:(tcp://your_jms_host:61616) }}} Failover with a single server means: clients re-connect automatically after network problems.

== Multiple JMS Servers, Master/Slave == In operational SNS experience, a basic JMS setup with a single server on the accelerator network has been very reliable. While we tried some master/slave failover setups, we would for now actually ''discourage'' them because they add complexity without gain in reliability.

You can configure JMS servers for a master/slave failover. Clients then use a URL like {{{ failover:(tcp://first_jms_host:61616,tcp://second_jms_host:61616) }}}

'''Note:''' Only use multi-host failover URLs if you specifically configured those JMS hosts for master/slave failover or message forwarding, or if they are on different networks!

At the SNS, we have one JMS host on the office network and one on the accelerator network. CSS can be configured with failover for both because a client on the network will only be able to connect to one of the hosts. If a client could potentially reach either of the hosts in a failover URL, you cannot predict which one it will reach! If the JMS servers were not configured for master/slave or message forwarding, one CSS component will end up connecting to the first JMS host, another to the second, and they effectively don't talk to each other!

== HTML Tunneling == The default ActiveMQ !OpenWire protocol, defaulting to port 61616, works best.

The alternate/additional HTTP Transport can be useful for HTTP tunneling, to allow access to JMS on your control system network through a firewall, but it is not suggested for an operational setup.

To enable HTTP Transport, add these 2 jars from the xstream ZIP file to the JMS server: {{{ xstream and xmlpull for JMS 5.2, xstream and xpp3_min for JMS 5.1 }}} JMS clients that use the HTTP Transport need commons-httpclient in addition to activemq-all.

Add this the JMS server activemq.xml file: {{{ ... }}}

Your JMS server will now offer a http transport that clients can access under {{{ failover:(http://host-name:61618) }}} Use the real host name! 'localhost' will not work as a host-name, unless you really only want local clients which use "http://localhost:61618" to connect!

When using JMS with HTTP transport, it's then easy to configure an Apache HTTPD as a Proxy to that JMS server, so no firewall exception is needed for JMS.

In the httpd.conf, do this: {{{

LoadModule ..mod_proxy.. LoadModule ..mod_proxy_http..

ProxyRequests Off <Proxy *> Order deny,allow Allow from all

ProxyPass /jms http://localhost:61618 ProxyPassReverse /jms http://localhost:61618 }}}

CSS clients can now use this URL, and the web server will forward the traffic to the HTTP Transport of your JMS server: {{{ failover:(http://your.web.server.org/jms) }}}