| <?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> |
