<div class="wiki-content maincontent"><p><structured-macro ac:macro-id="4fe7f2d0-8790-4f66-9f98-c49b9473a801" ac:name="toc" ac:schema-version="1"></structured-macro></p><h1>Functional overview</h1><p>From version 5.4.0 onwards, ActiveMQ comes with a enhanced shell script for starting, stopping and managing the broker in Unix environment. For basic <link ac:anchor="activemq"><page ri:content-title="ActiveMQ Command Line Tools Reference"></page><plain-text-link-body>activemq</plain-text-link-body></link> and <link ac:anchor="activemq-admin"><page ri:content-title="ActiveMQ Command Line Tools Reference"></page><plain-text-link-body>activemq-admin</plain-text-link-body></link> scripts functionality take a look at <link><page ri:content-title="ActiveMQ Command Line Tools Reference"></page></link>.</p><p>This <code>activemq</code> script incorporate these two scripts into one and adds some new functionalities. On top of regular <code>activemq</code> and <code>activemq-admin</code> scripts, it adds the following features:</p><ul><li><p><strong>start</strong> - starts the broker in background. It saves process id in the <code>${ACTIVEMQ_DATA_DIR}/activemq.pid</code> for future reference. It accepts the same command line arguments like the original <code>activemq</code> script, so you can do something like</p><structured-macro ac:macro-id="0c704072-5079-4fd6-9810-894f71eead7c" ac:name="code" ac:schema-version="1"><plain-text-body>bin/activemq start xbean:conf/activemq-stomp.xml</plain-text-body></structured-macro></li><li><p><strong>console</strong> - starts the broker in foreground. It is basically the replacement for the old <code>activemq</code> script<br clear="none">(you can interrupt the )</p></li></ul><ul><li><strong>stop</strong> - stops the broker that is running in the background. It tries first to stop the broker using <link ac:anchor="shutdown"><page ri:content-title="ActiveMQ Command Line Tools Reference"></page><plain-text-link-body>shutdown</plain-text-link-body></link> task. If that task doesn't return in 30 seconds (configurable), it will kill the process.</li></ul><ul><li><strong>restart</strong> - stops the running instance (if there's one) and starts the new one</li></ul><ul><li><strong>status</strong> - checks if activemq process is running<br clear="none">(exitcode: 1 = broker is down, 0 = broker is up)</li></ul><ul><li><p><strong>create</strong> - create an ACTIVEMQ_BASE directory that separates a broker instance from its binaries, i.e., it creates copies of the ActiveMQ configuration files into the command-line specified directory and points to the binaries. You can start the broker with the <code>/bin</code> scripts in the newly created instance.</p><structured-macro ac:macro-id="d1b4e2e2-fc3b-417d-a726-60c0e7ef4b64" ac:name="code" ac:schema-version="1"><plain-text-body>bin/activemq create /path/to/brokers/mybroker </plain-text-body></structured-macro></li><li><p><strong>browse</strong> - Display selected messages in a specified destination</p><structured-macro ac:macro-id="98c932fe-4a01-48da-83d3-d39c39f56647" ac:name="code" ac:schema-version="1"><plain-text-body>bin/activemq browse FOO.BAR # use broker connection from configuration
bin/activemq browse --amqurl tcp://localhost:61616 FOO.BAR</plain-text-body></structured-macro></li><li><p><strong>bstat</strong> - Performs a predefined query that displays useful statistics regarding the specified broker</p></li><li><p><strong>dstat</strong> - Performs a predefined query that displays useful tabular statistics regarding the specified destination type</p></li><li><p><strong>decrypt</strong> - Decrypts given text</p><structured-macro ac:macro-id="5071f416-262d-46d8-9411-9e5735babb7e" ac:name="code" ac:schema-version="1"><plain-text-body>bin/activemq decrypt --input 'BkiT42A0CZfL1SanJIgxvQ==' --password asdasdasdasd</plain-text-body></structured-macro></li><li><p><strong>encrypt</strong> - Encrypts given text</p><structured-macro ac:macro-id="5807cac9-a043-4279-bc0e-3a9af1e33d68" ac:name="code" ac:schema-version="1"><plain-text-body>bin/activemq encrypt --password TESTPASSWORD --input FOOBAR</plain-text-body></structured-macro></li><li><p><strong>export</strong> - Exports a stopped brokers data files to an archive file for importing to another brokers like ActiveMQ Artemis</p><structured-macro ac:macro-id="d98f7539-e414-4c95-be60-83c50bfaafcf" ac:name="code" ac:schema-version="1"><plain-text-body>$ bin/activemq export --file=archivefile</plain-text-body></structured-macro></li><li><p><strong>list</strong> - Lists all available brokers in the specified JMX context</p></li><li><p><strong>purge</strong> - Delete selected destination's messages that matches the message selector</p><structured-macro ac:macro-id="f03850c0-26d7-4de8-8cff-b28194e1f301" ac:name="code" ac:schema-version="1"><plain-text-body>bin/activemq purge FOO.BAR # use jmx access data from configuration
bin/activemq purge --jmxurl service:jmx:rmi:///jndi/rmi://127.0.0.1:11098/jmxrmi --jmxuser controlRole --jmxpassword abcd1234 FOO.BAR</plain-text-body></structured-macro></li><li><p><strong>query</strong> - Display selected broker component's attributes and statistics</p><structured-macro ac:macro-id="5dd089e1-681c-4780-82b8-077dd70092ed" ac:name="code" ac:schema-version="1"><plain-text-body>bin/activemq query # use jmx access data from configuration
bin/activemq query --jmxurl service:jmx:rmi:///jndi/rmi://127.0.0.1:11098/jmxrmi --jmxuser controlRole --jmxpassword abcd1234</plain-text-body></structured-macro></li></ul><h1>Configuring the init-script</h1><p>For ActiveMQ server to run properly some basic system variables must be set. These variables define how much memory broker will have, SSL, logging, JAAS options and similar.</p><h2>Version 5.11.0 and higher</h2><h3>Configuration file of the init-script</h3><p>Since version 5.11.0, all default configuration variables are moved to the new <code>env</code> script file, so that they can be easily inspected and configured in a easy way. <br clear="none">There are also other configuration locations</p><p>The script scans the following locations for configurations in the following order:</p><ol><li>/etc/default/activemq</li><li>$HOME/.activemqrc</li><li>$INSTALLDIR/apache-activemq-&lt;version&gt;/bin/env</li></ol><p>The first existing file is read exclusively - all other files are ignored. <br clear="none">Undefined values are discovered in a automated way.</p><h3>Versions prior 5.11.0</h3><p>These parameters were configurable in <code>activemq</code> script itself. <br clear="none"><br clear="none">You could use <code>setup</code> command to create additional system wide defaults file to configure the broker.<br clear="none">(modify the settings in this file if neccessary - the default entries look a bit garbled due to an accidentally applied bugfix in this release)</p><structured-macro ac:macro-id="d866b6dc-3b3c-474a-91ed-95edf3884735" ac:name="code" ac:schema-version="1"><parameter ac:name="language">bash</parameter><plain-text-body>./activemq setup /etc/default/activemq</plain-text-body></structured-macro><p>The configuration of the script can be placed at <code>/etc/default/activemq</code> or <code>$HOME/.activemqrc</code>. Note, this is the configuration for the <em>script</em> not for configuring ActiveMQ.</p><p>To use addtional configurations for running multiple instances on the same operating system rename or symlink script to a name matching to <code>activemq-instance-&lt;INSTANCENAME&gt;</code>. This changes the configuration location to <code>/etc/default/activemq-instance-&lt;INSTANCENAME&gt;</code> and <code>$HOME/.activemqrc-instance-&lt;INSTANCENAME&gt;</code>. Configuration files in /etc have higher precedence.</p><h2>Running activemq as a unix daemon</h2><ul><li><p>Install activemq broker as "root" to be run as "activemq"</p><structured-macro ac:macro-id="30cb19f1-9767-4b15-9df6-3ba3fc98b006" ac:name="code" ac:schema-version="1"><plain-text-body>useradd -m activemq -d /srv/activemq
cd /srv/activemq
tar zxvf apache-activemq-&lt;version&gt;-bin.tar.gz$ ln -snf apache-activemq-&lt;version&gt; current
chown -R activemq:users apache-activemq-&lt;version&gt;
</plain-text-body></structured-macro></li><li><p>Create a global default configuration and edit the configuration</p><structured-macro ac:macro-id="b45c45da-0f64-4a5b-b8e4-01215a038292" ac:name="code" ac:schema-version="1"><plain-text-body>cp apache-activemq-&lt;version&gt;/bin/env /etc/default/activemq
sed -i '~s/^ACTIVEMQ_USER=""/ACTIVEMQ_USER="activemq"/' /etc/default/activemq
vim /etc/default/activemq
chmod 644 /etc/default/activemq</plain-text-body></structured-macro><ul><li>Configure the java heap to a size suitable to your system environment and usage</li><li>Consider to move the folders "data", "tmp" and "conf" out of the installation path</li></ul></li><li><p>Install the init script</p><structured-macro ac:macro-id="a7caa18a-0f98-4b60-960a-3af354196b21" ac:name="code" ac:schema-version="1"><plain-text-body>ln -snf  /srv/activemq/current/bin/activemq /etc/init.d/activemq</plain-text-body></structured-macro></li><li><p>Activate the init script at system startup<br clear="none">(TODO: uncomplete)</p><structured-macro ac:macro-id="53b72991-21e7-46b8-b5c5-f19ba2cf94fe" ac:name="code" ac:schema-version="1"><plain-text-body># RHEL
chkconfig --add activemq
chkconfig activemq on

# Debian/Ubuntu
update-rc.d defaults activemq</plain-text-body></structured-macro></li></ul><h2>Running multiple instances</h2><p>To use additional configurations for running multiple instances on the same operating system rename or symlink script to a name matching to <code>activemq-instance-&lt;INSTANCENAME&gt;</code>.<br clear="none">This changes the configuration location to <code>/etc/default/activemq-instance-&lt;INSTANCENAME&gt;</code> and <code>$HOME/.activemqrc-instance-&lt;INSTANCENAME&gt;</code>. Configuration files in /etc have higher precedence.</p><p>Example procedure suitable to the procedure "Running activemq as a unix daemon"</p><structured-macro ac:macro-id="18c288b9-5b51-42aa-b357-898627f9ddf4" ac:name="code" ac:schema-version="1"><parameter ac:name="title">Example</parameter><plain-text-body>mkdir /srv/activemq/instance1
cp -av /srv/activemq/current/conf/ /srv/activemq/instance1/
mkdir /srv/activemq/instance1/{data,tmp}
ln -snf  /srv/activemq/current/bin/activemq /etc/init.d/activemq-instance-test1
cp /srv/activemq/install/bin/env /etc/default/activemq-instance-instance-test1</plain-text-body></structured-macro><p>Modify the configuration variables in /etc/default/activemq-instance-instance-test1</p><structured-macro ac:macro-id="8821fd41-4027-440a-a0ba-45ec44a6326f" ac:name="code" ac:schema-version="1"><plain-text-body>ACTIVEMQ_HOME="/srv/activemq/current/"
ACTIVEMQ_CONF="/srv/activemq/instance1/conf"
ACTIVEMQ_DATA="/srv/activemq/instance1/data"
ACTIVEMQ_TMP="/srv/activemq/instance1/tmp"</plain-text-body></structured-macro><p>Control the instance</p><structured-macro ac:macro-id="93b582f7-b195-460a-a35a-0c042543955b" ac:name="code" ac:schema-version="1"><plain-text-body>/etc/init.d/activemq-instance1 start|stop|restart|console|....</plain-text-body></structured-macro><p>&#160;</p><p>Hint: If you are using multiple instances you can only add the main instance to the automatic system start using ("update-rc.d" or "chkconfig") because the LSB Header "Provides" needs to be uniq.</p><h1>Testing and reporting interoperability problems for unix platforms</h1><p>&#160;</p><p>The activemq repo provides a testsuite to validate the proper operation of the unix shell script on different platforms.</p><ul><li><p>Download the testsuite<br clear="none">Alternatively clone the sourcecode repo (<link><page ri:content-title="Source"></page></link>) and pick the file <em>assembly/src/test/scripts/init-script-testsuite</em></p><structured-macro ac:macro-id="f30725ee-b742-47d8-9c94-832c2d70772e" ac:name="code" ac:schema-version="1"><plain-text-body>cd /tmp
wget -c "https://git-wip-us.apache.org/repos/asf?p=activemq.git;a=blob_plain;f=assembly/src/test/scripts/init-script-testsuite;hb=HEAD"</plain-text-body></structured-macro></li><li><p>Execute the testsuite</p><structured-macro ac:macro-id="b90c7b7e-dc6b-4bab-92a5-c5ba69f30c42" ac:name="code" ac:schema-version="1"><plain-text-body>cd &lt;Installation Dir of the ActiveMQ Script&gt;
./activemq stop
/tmp/init-script-testsuite 2&gt;&amp;1| tee /tmp/test-suite.log</plain-text-body></structured-macro></li><li><p>Detailed debug information can be provided by the following procedure</p><structured-macro ac:macro-id="86b4e441-0226-484a-900c-6634c94ae484" ac:name="code" ac:schema-version="1"><plain-text-body>export PS4=' ${BASH_SOURCE}:${LINENO}(${FUNCNAME[0]}) '
bash -x ./activemq &lt;argument&gt; 2&gt;&amp;1 |tee /tmp/detailed-debugging.log</plain-text-body></structured-macro></li><li><p>Create a ticket and attach the logfiles to the ticket.</p></li></ul><p>&#160;</p></div>