-
Notifications
You must be signed in to change notification settings - Fork 208
/
using-server.xml
389 lines (375 loc) · 22.4 KB
/
using-server.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
<?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>run.sh</literal> and a windows batch file called <literal
>run.bat</literal></para>
<para>To run on Unix/Linux type <literal>./run.sh</literal></para>
<para>To run on Windows type <literal>run.bat</literal></para>
<para>These scripts are very simple and basically just set-up the classpath and some JVM
parameters and start the JBoss Microcontainer. The Microcontainer is a light weight
container used to deploy the HornetQ POJO's</para>
<para>To stop the server you will also find a Unix/Linux script <literal>stop.sh</literal> and
a windows batch file <literal>stop.bat</literal></para>
<para>To run on Unix/Linux type <literal>./stop.sh</literal></para>
<para>To run on Windows type <literal>stop.bat</literal></para>
<para>Please note that HornetQ requires a Java 6 or later runtime to run.</para>
<para>Both the run and the stop scripts use the config under <literal
>config/stand-alone/non-clustered</literal> by default. The configuration can be
changed by running <literal>./run.sh ../config/stand-alone/clustered</literal> or
another config of your choosing. This is the same for the stop script and the windows
bat files.</para>
</section>
<section>
<title>Server JVM settings</title>
<para>The run scripts <literal>run.sh</literal> and <literal>run.bat</literal> set some JVM
settings for tuning running on Java 6 and choosing the garbage collection policy. 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>Server classpath</title>
<para>HornetQ looks for its configuration files on the Java classpath.</para>
<para>The scripts <literal>run.sh</literal> and <literal>run.bat</literal> specify the
classpath when calling Java to run the server.</para>
<para>In the distribution, the run scripts will add the non clustered configuration
directory to the classpath. This is a directory which contains a set of configuration
files for running the HornetQ server in a basic non-clustered configuration. In the
distribution this directory is <literal>config/stand-alone/non-clustered/</literal> from
the root of the distribution.</para>
<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>Non clustered in JBoss Application Server</para>
</listitem>
<listitem>
<para>Clustered in JBoss Application Server</para>
</listitem>
</itemizedlist>
<para>You can of course create your own configuration and specify any configuration
directory when running the run script.</para>
<para>Just make sure the directory is on the classpath and HornetQ will search there when
starting up.</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 <literal>run.sh</literal> script.</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 directory is specified on the classpath in the run scripts <literal
>run.sh</literal> and <literal>run.bat</literal> This directory can contain the
following files.</para>
<itemizedlist>
<listitem>
<para><literal>hornetq-beans.xml</literal> (or <literal
>hornetq-jboss-beans.xml</literal> if you're running inside JBoss
Application Server). This is the JBoss Microcontainer beans file which defines
what beans the Microcontainer should create and what dependencies to enforce
between them. Remember that HornetQ is just a set of POJOs. In the stand-alone
server, it's the JBoss Microcontainer which instantiates these POJOs and
enforces dependencies between them and other beans. </para>
</listitem>
<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>
<listitem>
<para><literal>logging.properties</literal> This is used to configure the logging
handlers used by the Java logger. For more information on configuring logging,
please see <xref linkend="logging"/>.</para>
</listitem>
<listitem>
<para><literal>log4j.xml</literal> This is the Log4j configuration if the Log4j
handler is configured.</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.hornetq.core.remoting.impl.netty.NettyConnectorFactory</factory-class>
<param key="host" value="${hornetq.remoting.netty.host:localhost}" type="String"/>
<param key="port" value="${hornetq.remoting.netty.port:5445}" type="Integer"/>
</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.microcontainer.configuration">
<title>JBoss Microcontainer Beans File</title>
<para>The stand-alone server is basically a set of POJOs which are instantiated by the light
weight<ulink url="http://www.jboss.org/jbossmc/"> JBoss Microcontainer
</ulink>engine.</para>
<note>
<para>A beans file is also needed when the server is deployed in the JBoss Application
Server but this will deploy a slightly different set of objects since the
Application Server will already have things like security etc deployed.</para>
</note>
<para>Let's take a look at an example beans file from the stand-alone server:</para>
<para>
<programlisting>
<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
<!-- MBean server -->
<bean name="MBeanServer" class="javax.management.MBeanServer">
<constructor factoryClass="java.lang.management.ManagementFactory"
factoryMethod="getPlatformMBeanServer"/>
</bean>
<!-- The core configuration -->
<bean name="Configuration" class="org.hornetq.core.config.impl.FileConfiguration">
</bean>
<!-- The security manager -->
<bean name="HornetQSecurityManager" class="org.hornetq.spi.core.security.HornetQSecurityManagerImpl">
<start ignored="true"/>
<stop ignored="true"/>
</bean>
<!-- The core server -->
<bean name="HornetQServer" class="org.hornetq.core.server.impl.HornetQServerImpl">
<constructor>
<parameter>
<inject bean="Configuration"/>
</parameter>
<parameter>
<inject bean="MBeanServer"/>
</parameter>
<parameter>
<inject bean="HornetQSecurityManager"/>
</parameter>
</constructor>
<start ignored="true"/>
<stop ignored="true"/>
</bean>
<!-- The Stand alone server that controls the jndi server-->
<bean name="StandaloneServer" class="org.hornetq.jms.server.impl.StandaloneNamingServer">
<constructor>
<parameter>
<inject bean="HornetQServer"/>
</parameter>
</constructor>
<property name="port">${jnp.port:1099}</property>
<property name="bindAddress">${jnp.host:localhost}</property>
<property name="rmiPort">${jnp.rmiPort:1098}</property>
<property name="rmiBindAddress">${jnp.host:localhost}</property>
</bean>
<!-- The JMS server -->
<bean name="JMSServerManager" class="org.hornetq.jms.server.impl.JMSServerManagerImpl">
<constructor>
<parameter>
<inject bean="HornetQServer"/>
</parameter>
</constructor>
</bean>
</deployment></programlisting>
</para>
<para>We can see that, as well as the core HornetQ server, the stand-alone server
instantiates various different POJOs, let's look at them in turn:</para>
<itemizedlist>
<listitem>
<para>MBeanServer</para>
<para>In order to provide a JMX management interface a JMS MBean server is necessary
in which to register the management objects. Normally this is just the default
platform MBean server available in the JVM instance. If you don't want to
provide a JMX management interface this can be commented out or removed.</para>
</listitem>
<listitem>
<para>Configuration</para>
<para>The HornetQ server is configured with a Configuration object. In the default
stand-alone set-up it uses a FileConfiguration object which knows to read
configuration information from the file system. In different configurations such
as embedded you might want to provide configuration information from somewhere
else.</para>
</listitem>
<listitem>
<para>Security Manager. The security manager used by the messaging server is
pluggable. The default one used just reads user-role information from the
<literal>hornetq-users.xml</literal> file on disk. However it can be
replaced by a JAAS security manager, or when running inside JBoss Application
Server it can be configured to use the JBoss AS security manager for tight
integration with JBoss AS security. If you've disabled security altogether you
can remove this too.</para>
</listitem>
<listitem>
<para>HornetQServer</para>
<para>This is the core server. It's where 99% of the magic happens</para>
</listitem>
<listitem>
<para>StandaloneServer</para>
<para>Many clients like to look up JMS Objects from JNDI so we provide a JNDI server
for them to do that. This class is a wrapper around the JBoss naming server.
If you don't need JNDI this can be commented out or removed.</para>
</listitem>
<listitem id="bean-jmsservermanager">
<para>JMSServerManager</para>
<para>This deploys any JMS Objects such as JMS Queues, Topics and ConnectionFactory
instances from <literal>hornetq-jms.xml</literal> files on the disk. 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 ConnectionFactorys from server side configuration
and don't require the JMS management interface this can be disabled.</para>
</listitem>
</itemizedlist>
</section>
<section id="server.microkernel.configuration">
<title>JBoss AS4 MBean Service.</title>
<note>
<para>The section is only to configure HornetQ on JBoss AS4. The service functionality is
similar to Microcontainer Beans</para>
</note>
<para>
<programlisting>
<?xml version="1.0" encoding="UTF-8"?>
<server>
<mbean code="org.hornetq.service.HornetQFileConfigurationService"
name="org.hornetq:service=HornetQFileConfigurationService">
</mbean>
<mbean code="org.hornetq.service.JBossASSecurityManagerService"
name="org.hornetq:service=JBossASSecurityManagerService">
</mbean>
<mbean code="org.hornetq.service.HornetQStarterService"
name="org.hornetq:service=HornetQStarterService">
<!--let's let the JMS Server start us-->
<attribute name="Start">false</attribute>
<depends optional-attribute-name="SecurityManagerService"
proxy-type="attribute">org.hornetq:service=JBossASSecurityManagerService</depends>
<depends optional-attribute-name="ConfigurationService"
proxy-type="attribute">org.hornetq:service=HornetQFileConfigurationService</depends>
</mbean>
<mbean code="org.hornetq.service.HornetQJMSStarterService"
name="org.hornetq:service=HornetQJMSStarterService">
<depends optional-attribute-name="HornetQServer"
proxy-type="attribute">org.hornetq:service=HornetQStarterService</depends>
</mbean>
</server></programlisting>
</para>
<para>This jboss-service.xml configuration file is included inside the hornetq-service.sar
on AS4 with embedded HornetQ. As you can see, on this configuration file we are starting
various services:</para>
<itemizedlist>
<listitem>
<para>HornetQFileConfigurationService</para>
<para>This is an MBean Service that takes care of the life cycle of the <literal>FileConfiguration POJO</literal></para>
</listitem>
<listitem>
<para>JBossASSecurityManagerService</para>
<para>This is an MBean Service that takes care of the lifecycle of the <literal>JBossASSecurityManager</literal> POJO</para>
</listitem>
<listitem>
<para>HornetQStarterService</para>
<para>This is an MBean Service that controls the main <literal>HornetQServer</literal> POJO.
this has a dependency on JBossASSecurityManagerService and HornetQFileConfigurationService MBeans</para>
</listitem>
<listitem>
<para>HornetQJMSStarterService</para>
<para>This is an MBean Service that controls the <literal>JMSServerManagerImpl</literal> POJO.
If you aren't using jms this can be removed.</para>
</listitem>
<listitem>
<para>JMSServerManager</para>
<para>Has the responsibility to start the JMSServerManager and the same behaviour that JMSServerManager Bean</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>