210 lines
13 KiB
XML
210 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!-- ============================================================================= -->
|
||
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
||
<!-- -->
|
||
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
||
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
||
<!-- -->
|
||
<!-- An explanation of CC-BY-SA is available at -->
|
||
<!-- -->
|
||
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
||
<!-- -->
|
||
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
||
<!-- of it, you must provide the URL for the original version. -->
|
||
<!-- -->
|
||
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
||
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
||
<!-- permitted by applicable law. -->
|
||
<!-- ============================================================================= -->
|
||
|
||
<!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="using-server">
|
||
<title>Using the Server</title>
|
||
<para>This chapter will familiarise you with how to use the ActiveMQ server.</para>
|
||
<para>We'll show where it is, how to start and stop it, and we'll describe the directory layout
|
||
and what all the files are and what they do.</para>
|
||
<para>For the remainder of this chapter when we talk about the ActiveMQ server we mean the
|
||
ActiveMQ standalone server, in its default configuration with a JMS Service and JNDI service
|
||
enabled.</para>
|
||
<para>When running embedded in JBoss Application Server the layout may be slightly different but
|
||
by-and-large will be the same.</para>
|
||
<section>
|
||
<title>Starting and Stopping the standalone server</title>
|
||
<para>In the distribution you will find a directory called <literal>bin</literal>.</para>
|
||
<para><literal>cd</literal> into that directory and you will find a Unix/Linux script called
|
||
<literal>activemq</literal> and a Windows script called <literal>activemq.cmd</literal>.</para>
|
||
<para>To start the ActiveMQ instance on Unix/Linux type <literal>./activemq run</literal></para>
|
||
<para>To start the ActiveMQ instance on Windows type <literal>activemq.cmd run</literal></para>
|
||
<para>These scripts are very simple and basically just set-up the classpath and some JVM
|
||
parameters and bootstrap the server using <ulink
|
||
url="https://github.com/airlift/airline">Airline</ulink>.</para>
|
||
<para>To stop the ActiveMQ instance you will use the same <literal>activemq</literal> script.</para>
|
||
<para>To run on Unix/Linux type <literal>./activemq stop</literal></para>
|
||
<para>To run on Windows type <literal>activemq.cmd stop</literal></para>
|
||
<para>Please note that ActiveMQ requires a Java 6 or later runtime to run.</para>
|
||
<para>By default the <literal>config/non-clustered/bootstrap.xml</literal> configuration is used. The
|
||
configuration can be changed e.g. by running
|
||
<literal>./activemq run -- xml:../config/clustered/bootstrap.xml</literal> or another config of
|
||
your choosing.</para>
|
||
</section>
|
||
<section>
|
||
<title>Server JVM settings</title>
|
||
<para>The run scripts set some JVM settings for tuning the garbage collection policy
|
||
and heap size. We recommend using a parallel garbage collection algorithm to smooth
|
||
out latency and minimise large GC pauses.</para>
|
||
<para>By default ActiveMQ runs in a maximum of 1GiB of RAM. To increase the memory settings
|
||
change the <literal>-Xms</literal> and <literal>-Xmx</literal> memory settings as you
|
||
would for any Java program.</para>
|
||
<para>If you wish to add any more JVM arguments or tune the existing ones, the run scripts
|
||
are the place to do it.</para>
|
||
</section>
|
||
<section>
|
||
<title>Pre-configured Options</title>
|
||
<para>The distribution contains several standard configuration sets for running:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Non clustered stand-alone.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Clustered stand-alone</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Replicated stand-alone</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Shared-store stand-alone</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>You can of course create your own configuration and specify any configuration
|
||
when running the run script.</para>
|
||
</section>
|
||
<section id="using-server.library.path">
|
||
<title>Library Path</title>
|
||
<para>If you're using the <link linkend="aio-journal">Asynchronous IO Journal</link> on
|
||
Linux, you need to specify <literal>java.library.path</literal> as a property on your
|
||
Java options. This is done automatically in the scripts.</para>
|
||
<para>If you don't specify <literal>java.library.path</literal> at your Java options then
|
||
the JVM will use the environment variable <literal>LD_LIBRARY_PATH</literal>.</para>
|
||
</section>
|
||
<section>
|
||
<title>System properties</title>
|
||
<para>ActiveMQ can take a system property on the command line for configuring logging.</para>
|
||
<para>For more information on configuring logging, please see <xref linkend="logging"
|
||
/>.</para>
|
||
</section>
|
||
<section id="using-server.configuration">
|
||
<title>Configuration files</title>
|
||
<para>The configuration file used to bootstrap the server (e.g. <literal>bootstrap.xml</literal>
|
||
by default) references the specific broker configuration files.</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>activemq-configuration.xml</literal>. This is the main ActiveMQ
|
||
configuration file. All the parameters in this file are described in <xref
|
||
linkend="configuration-index"/>. Please see <xref
|
||
linkend="usingserver.mainconfig"/> for more information on this file.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>activemq-queues.xml</literal>. This file contains predefined queues,
|
||
queue settings and security settings. The file is optional - all this
|
||
configuration can also live in <literal>activemq-configuration.xml</literal>. In
|
||
fact, the default configuration sets do not have a <literal
|
||
>activemq-queues.xml</literal> file. The purpose of allowing queues to be
|
||
configured in these files is to allow you to manage your queue configuration
|
||
over many files instead of being forced to maintain it in a single file. There
|
||
can be many <literal>activemq-queues.xml</literal> files on the classpath. All
|
||
will be loaded if found.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>activemq-users.xml</literal> ActiveMQ ships with a basic security
|
||
manager implementation which obtains user credentials from the <literal
|
||
>activemq-users.xml</literal> file. This file contains user, password and
|
||
role information. For more information on security, please see <xref
|
||
linkend="security"/>.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>activemq-jms.xml</literal> The distro configuration by default
|
||
includes a server side JMS service which mainly deploys JMS Queues, Topics and
|
||
ConnectionFactorys from this file into JNDI. If you're not using JMS, or you
|
||
don't need to deploy JMS objects on the server side, then you don't need this
|
||
file. For more information on using JMS, please see <xref linkend="using-jms"
|
||
/>.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<note>
|
||
<para>The property <literal>file-deployment-enabled</literal> in the <literal
|
||
>activemq-configuration.xml</literal> configuration when set to false means that
|
||
the other configuration files are not loaded. This is true by default.</para>
|
||
</note>
|
||
<para>It is also possible to use system property substitution in all the configuration
|
||
files. by replacing a value with the name of a system property. Here is an example of
|
||
this with a connector configuration:</para>
|
||
<programlisting>
|
||
<connector name="netty">
|
||
<factory-class>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</factory-class>
|
||
<param key="host" value="${activemq.remoting.netty.host:localhost}"/>
|
||
<param key="port" value="${activemq.remoting.netty.port:5445}"/>
|
||
</connector></programlisting>
|
||
<para>Here you can see we have replaced 2 values with system properties <literal
|
||
>activemq.remoting.netty.host</literal> and <literal
|
||
>activemq.remoting.netty.port</literal>. These values will be replaced by the value
|
||
found in the system property if there is one, if not they default back to localhost or
|
||
5445 respectively. It is also possible to not supply a default. i.e. <literal
|
||
>${activemq.remoting.netty.host}</literal>, however the system property
|
||
<emphasis>must</emphasis> be supplied in that case.</para>
|
||
</section>
|
||
<section id="server.bootstrap.configuration">
|
||
<title>Bootstrap File</title>
|
||
<para>The stand-alone server is basically a set of POJOs which are instantiated by Airline commands.</para>
|
||
<para>The bootstrap file is very simple. Let's take a look at an example:</para>
|
||
<para>
|
||
<programlisting>
|
||
<broker xmlns="http://activemq.org/schema">
|
||
|
||
<file:core configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-configuration.xml"></core>
|
||
<file:jms configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-jms.xml"></jms>
|
||
|
||
<basic-security/>
|
||
|
||
<naming bindAddress="localhost" port="1099" rmiBindAddress="localhost" rmiPort="1098"/>
|
||
|
||
</broker></programlisting>
|
||
</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>core</para>
|
||
<para>Instantiates a core server using the configuration file from the
|
||
<literal>configuration</literal> attribute. This is the main broker POJO necessary
|
||
to do all the real messaging work.</para>
|
||
</listitem>
|
||
<listitem id="jms">
|
||
<para>jms</para>
|
||
<para>This deploys any JMS Objects such as JMS Queues, Topics and ConnectionFactory
|
||
instances from the <literal>activemq-jms.xml</literal> file specified. It also
|
||
provides a simple management API for manipulating JMS Objects. On the whole it
|
||
just translates and delegates its work to the core server. If you don't need to
|
||
deploy JMS Queues, Topics and ConnectionFactories from server side configuration
|
||
and don't require the JMS management interface this can be disabled.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>naming</para>
|
||
<para>Instantiates a naming server which implements JNDI. This is used by JMS
|
||
clients</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
<section id="usingserver.mainconfig">
|
||
<title>The main configuration file.</title>
|
||
<para>The configuration for the ActiveMQ core server is contained in <literal
|
||
>activemq-configuration.xml</literal>. This is what the FileConfiguration bean uses
|
||
to configure the messaging server.</para>
|
||
<para>There are many attributes which you can configure ActiveMQ. In most cases the defaults
|
||
will do fine, in fact every attribute can be defaulted which means a file with a single
|
||
empty <literal>configuration</literal> element is a valid configuration file. The
|
||
different configuration will be explained throughout the manual or you can refer to the
|
||
configuration reference <link linkend="configuration-index">here</link>.</para>
|
||
</section>
|
||
</chapter>
|