mirror of
https://github.com/apache/activemq-artemis.git
synced 2025-02-15 14:35:59 +00:00
9a587c5633
https://issues.apache.org/jira/browse/ACTIVEMQ6-3 We are renaming packages from activemq6 to activemq as that's more generic and version independent The previous commit renamed the directories. On this commit now I'm changing the code. If we changed the code and the directories on the same commit git would remove and add a lot of files without recognizing the renames.
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 "HornetQ_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 HornetQ 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 HornetQ server we mean the
|
||
HornetQ 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>hornetq</literal> and a Windows script called <literal>hornetq.cmd</literal>.</para>
|
||
<para>To start the HornetQ instance on Unix/Linux type <literal>./hornetq run</literal></para>
|
||
<para>To start the HornetQ instance on Windows type <literal>hornetq.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 HornetQ instance you will use the same <literal>hornetq</literal> script.</para>
|
||
<para>To run on Unix/Linux type <literal>./hornetq stop</literal></para>
|
||
<para>To run on Windows type <literal>hornetq.cmd stop</literal></para>
|
||
<para>Please note that HornetQ 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>./hornetq 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 HornetQ 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>HornetQ 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>hornetq-configuration.xml</literal>. This is the main HornetQ
|
||
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>hornetq-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>hornetq-configuration.xml</literal>. In
|
||
fact, the default configuration sets do not have a <literal
|
||
>hornetq-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>hornetq-queues.xml</literal> files on the classpath. All
|
||
will be loaded if found.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>hornetq-users.xml</literal> HornetQ ships with a basic security
|
||
manager implementation which obtains user credentials from the <literal
|
||
>hornetq-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>hornetq-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
|
||
>hornetq-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="${hornetq.remoting.netty.host:localhost}"/>
|
||
<param key="port" value="${hornetq.remoting.netty.port:5445}"/>
|
||
</connector></programlisting>
|
||
<para>Here you can see we have replaced 2 values with system properties <literal
|
||
>hornetq.remoting.netty.host</literal> and <literal
|
||
>hornetq.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
|
||
>${hornetq.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://hornetq.org/schema">
|
||
|
||
<file:core configuration="${hornetq.home}/config/stand-alone/non-clustered/hornetq-configuration.xml"></core>
|
||
<file:jms configuration="${hornetq.home}/config/stand-alone/non-clustered/hornetq-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>hornetq-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 HornetQ core server is contained in <literal
|
||
>hornetq-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 HornetQ. 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>
|