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
|
<?xml version="1.0"?>
<!DOCTYPE entities [
<!ENTITY % entities SYSTEM "commonEntities.xml">
%entities;
]>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<chapter id="Java-Broker-Installation">
<title>Installation</title>
<section role="h2" id="Java-Broker-Installation-Introduction">
<title>Introduction</title>
<para>This document describes how to install the Java Broker on both Windows and UNIX
platforms.</para>
</section>
<section role="h2" id="Java-Broker-Installation-Prerequistes">
<title>Prerequisites</title>
<section role="h3" id="Java-Broker-Installation-Prerequistes-Java">
<title>Java Platform</title>
<para>
The Java Broker is an 100% Java implementation and as such it can be used on any operating
system supporting Java 1.6 or higher. This includes Linux, Solaris, Mac OS X, and Windows XP/Vista/7/8.</para>
<para>
The broker has been tested with Java implementations from both Oracle and IBM. Whatever
platform you chose, it is recommended that you ensure it is patched with any critical updates made
available from the vendor.
</para>
<para>
Verify that your JVM is installed properly by following <link linkend="Java-Broker-Miscellaneous-JVM-Verification">these instructions.</link>
</para>
</section>
<section role="h3" id="Java-Broker-Installation-Prerequistes-Disk">
<title>Disk</title>
<para>The Java Broker installation requires approximately 20MB of free disk space.</para>
<para>The Java Broker also requires a working directory. The working directory is used for
the message store, that is, the area of the file-system used to record persistent messages whilst they
are passing through the Broker. The working directory is also used for the default location of the log file.
The size of the working directory will depend on the how the Broker is used.</para>
<para>The performance of the file system hosting the work directory is key to the performance of Broker as
a whole. For best performance, choose a device that has low latency and one that is uncontended by other
applications.</para>
<para>Be aware that there are additional considerations if you are considering hosting the working directory on NFS. See
<xref linkend="Java-Broker-Stores"/> for further details.</para>
</section>
<section role="h3" id="Java-Broker-Installation-Prerequistes-Memory">
<title>Memory</title>
<para>Qpid caches messages on the heap for performance reasons, so in general, the Broker will
benefit from as much heap as possible. However, on a 32bit JVM, the maximum addressable memory range
for a process is 4GB, after leaving space for the JVM's own use this will give a maximum heap size
of approximately ~3.7GB.</para>
</section>
<section role="h3" id="Java-Broker-Installation-Prerequistes-OperatingSystemAccount">
<title>Operating System Account</title>
<para>Installation or operation of Qpid does <emphasis>not</emphasis> require a privileged account (i.e. root
on UNIX platforms or Administrator on Windows). However it is suggested that you use an dedicated account
(e.g. qpid) for the installation and operation of the Java Broker.</para>
</section>
</section>
<section role="h2" id="Java-Broker-Installation-Download">
<title>Download</title>
<section role="h3" id="Java-Broker-Installation-Download-Release">
<title>Broker Release</title>
<para>You can download the latest qpid-java-broker-&qpidCurrentRelease;.tar.gz package from the <ulink
url="&qpidDownloadUrl;">Download Page</ulink>.
</para>
<para> It is recommended that you confirm the integrity of the download by verifying the PGP signature
matches that available on the site. Instrutions are given on the download page.
</para>
</section>
<section role="h3" id="Java-Broker-Installation-Download-OptionalDependencies">
<title>Optional Dependencies</title>
<para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these
stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref>
</para>
</section>
</section>
<section role="h2" id="Java-Broker-Installation-InstallationWindows">
<title>Installation on Windows</title>
<para>
Firstly, verify that your JVM is installed properly by following
<link linkend="Java-Broker-Miscellaneous-JVM-Verification-Windows">these instructions.</link>
</para>
<para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files.
It need not be the same location as the store used for the persistent messages or the log file (you will chose this
location later). For the remainder this example we will assumed that location c:\qpid has been chosen.</para>
<para>Now using WinZip<footnote><para>WinZip is a Registered Trademark of WinZip International LLC</para></footnote> (or similar)
extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para>
<para>The extraction of the Qpid package will have created a directory qpid-broker-&qpidCurrentRelease; within c:\qpid</para>
<screen>Volume in drive C has no label
Directory of c:\qpid\qpid-broker-&qpidCurrentRelease;
07/25/2012 11:22 PM .
09/30/2012 10:51 AM ..
09/30/2012 12:24 AM bin
08/21/2012 11:17 PM etc
07/25/2012 11:22 PM lib
07/20/2012 08:10 PM 65,925 LICENSE
07/20/2012 08:10 PM 3,858 NOTICE
07/20/2012 08:10 PM 1,346 README.txt
3 File(s) 71,129 bytes
5 Dir(s) 743,228,796,928 bytes free</screen>
<section role="h3" id="Java-Broker-Installation-InstallationWindows-SettingQPIDWORK">
<title>Setting the working directory</title>
<para>Qpid requires a work directory. This directory is used for the default location of the Qpid log
file and is used for the storage of persistent messages. The work directory can be set on the
command-line (for the lifetime of the command interpreter), but you will normally want to set
the environment variable permanently via the Advanced System Settings in the Control Panel.</para>
<screen>set QPID_WORK=S:\qpidwork</screen>
<para>If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it
on start-up.</para>
</section>
<section role="h3" id="Java-Broker-Installation-InstallationWindows-OptionalDependencies">
<title>Optional Dependencies</title>
<para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these
stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref>
</para>
</section>
</section>
<section role="h2" id="Java-Broker-Installation-InstallationUnix">
<title>Installation on UNIX platforms</title>
<para>
Firstly, verify that your JVM is installed properly by following
<link linkend="Java-Broker-Miscellaneous-JVM-Verification-Unix">these instructions.</link>
</para>
<para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files.
It need not be the same location as the store used for the persistent messages or the log file (you will chose this
location later). For the remainder this example we will assumed that location /usr/local/qpid has been chosen.</para>
<para>Extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para>
<programlisting>mkdir /usr/local/qpid
cd /usr/local/qpid
tar xvzf qpid-java-broker-&qpidCurrentRelease;.tar.gz></programlisting>
<para>The extraction of the Qpid package will have created a directory qpid-broker-x.x</para>
<screen>ls -la qpid-broker-&qpidCurrentRelease;/
total 152
drwxr-xr-x 8 qpid qpid 272 25 Jul 23:22 .
drwxr-xr-x 45 qpid qpid 1530 30 Sep 10:51 ..
-rw-r--r--@ 1 qpid qpid 65925 20 Jul 20:10 LICENSE
-rw-r--r--@ 1 qpid qpid 3858 20 Jul 20:10 NOTICE
-rw-r--r--@ 1 qpid qpid 1346 20 Jul 20:10 README.txt
drwxr-xr-x 10 qpid qpid 340 30 Sep 00:24 bin
drwxr-xr-x 9 qpid qpid 306 21 Aug 23:17 etc
drwxr-xr-x 34 qpid qpid 1156 25 Jul 23:22 lib
</screen>
<section role="h3" id="Java-Broker-Installation-InstallationUnix-SettingQPIDWORK">
<title>Setting the working directory</title>
<para>Qpid requires a work directory. This directory is used for the default location of the Qpid log
file and is used for the storage of persistent messages. The work directory can be set on the
command-line (for the lifetime of the current shell), but you will normally want to set
the environment variable permanently the user's shell profile file (~/.bash_profile for Bash etc).</para>
<screen><![CDATA[export QPID_WORK=/var/qpidwork]]>
</screen>
<para>If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it
on start-up.
</para>
</section>
<section role="h3" id="Java-Broker-Installation-InstallationUnix-OptionalDependencies">
<title>Optional Dependencies</title>
<para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these
stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref>
</para>
</section>
</section>
</chapter>
|
