OpenAMQ quick start


The OpenAMQ software is licensed under the GPLv2 or later, with the exception of the WireAPI client libraries, which are licensed under the BSD. Applications that include only the WireAPI client code and dependent classes are not affected by the GPL.

If you are an enterprise customer, we encourage you to purchase an enterprise support package from iMatix Corporation and receive benefits such as support for your mission-critical use of OpenAMQ.


iMatix accepts code submissions from developers who have either signed the Copyright Assignment and License, or who publish their code submissions under the MIT license.


If you have questions on any aspect of OpenAMQ, contact us directly or via the openamq-dev mailing list. If you're an enterprise customer and using OpenAMQ as part of your messaging architecture, help from an iMatix consultant will be invaluable in helping you understand the potential of AMQP and of OpenAMQ, and designing an architecture that is properly stable and fast.

Building from source

OpenAMQ is provided principally as source packages. Binary packages may be provided from time to time. OpenAMQ builds and runs on Linux 2.4, 2.6 kernels; Solaris 8 & 10 (use Sun Studio 11 compilers), Mac OS/X Darwin, and Windows with MSVC/6.x or VS.NET 2003 7.1.

These shell commands build OpenAMQ from the Unix source kit, which is a .tar.gz file:

$ IBASE=$HOME/ibase
$ export IBASE
$ export PATH
$ BOOM_MODEL="mt,release"
$ export BOOM_MODEL
$ tar zxvf /path/to/
$ cd /path/to/
$ sh

These console commands build OpenAMQ from the Windows source kit, which is a .zip file:

> set IBASE=c:\ibase
> set PATH=%IBASE%\bin;%PATH%
> set BOOM_MODEL=mt,release
> unzip \path\to\
> cd \path\to\
> build

You can tune the build by setting the BOOM_MODEL environment variable:

  • BOOM_MODEL=st - single-threaded, useful for single-core servers
  • BOOM_MODEL=mt - multi-threaded, ideal for servers with two or more cores
  • BOOM_MODEL=debug - with full debugging information
  • BOOM_MODEL=release - optimised, without debugging information

These options can be combined. The default build is "mt,release".

Compiling on Windows

To build on Windows the C/C++ compiler must be configured for command-line compilation. To test this, open a console window and type this command:

> cl /?

If the command shows help for the MSVC compiler, it has been configured correctly. Otherwise follow these instructions:

  • During MSVC installation, make sure you register the environment variables needed for command-line use of the compiler.
  • Check the vcvars32.bat script for correctness.
  • When you open a console box, the MSVCDir variable must point correctly to the MSVC application directory.
  • You can set this manually in the system environment variables.

Note that the provided OpenAMQ project files are not compatible with Visual Studio 2005 (including the Express Edition).

Test the server

After a successful build, start the server as follows:

$ amq_server
Production release
Copyright (c) 2007 iMatix Corporation
This is free software; see the source for copying conditions.  There is NO
2006-05-09 10:12:41: W: security warning - console login uses default password
2006-05-09 10:12:42: I: server ready for incoming AMQ connections

And in a second window, start the test client as follows:

$ amq_client -n 1000

The client will create a temporary queue on the server, send 1000 messages to its own queue, and read the message back off its queue. To stop the server, press Ctrl-C.

Deploying the OpenAMQ server

The server can run in user mode and to open the default AMQP port of 5672, does not need root access (root access is needed to run servers on port numbers lower than 4096).

Required Files

The OpenAMQ server is installed into the %IBASE%/bin directory (%IBASE\bin on Windows). If you wish to move the server elsewhere (e.g. to a different machine), you need to copy these three files:

  • amq_server (amq_server.exe on Windows)
  • amq_server_base.cfg
  • amq_console_schema.cml

Background operation

On UNIX/Linux systems you can run the server as a detached background process using this command:

amq_server -b

On Windows, to start the server as a service, use the 'srvany' tool that is part of the Windows Resource Kit.

Working directory

It is best to start amq_server in a specific working directory which has the right permissions to allow the process to create logging directories and files. You can start many instances of the server in the same directory. The server will create two subdirectories:

  • logs, in which the server will create current log files.
  • archive, to which the server will move old (yesterday's) log files.

Important server options

To see a short list of all server options, type this command:

amq_server -h

To see a long list of all server options, with full explanations, type this command:

amq_server --help

If you want to run several instances of the server on the same machine you must start them on different ports. The default AMQP port is 5672. To start the server on a different port, type this command:

amq_server --port portnumber

Setting custom passwords

amq_server defines two types of user:

  • Normal application logins, which can do all normal operations on the server. The default normal login is "guest", with password "guest".
  • Super-user logins, which can exceed configured limits and do updates via the Console. The default super user login is "super", with password "super".

We advise you to set custom passwords for all production-use of OpenAMQ. To do this, in the file amq_server.cfg, add this section:

<security name = "plain">
    <user name = "guest" password = "[new normal password]" />
    <user name = "super" password = "[new super password]" />

Note that if amq_server.cfg does not already exist, it should look like this (when empty):

<?xml version="1.0"?>
    <!-- Configuration data comes here -->

Defining new logins

To create new logins for normal applications, add lines in this form to the amq_server.cfg file:

<security name = "plain">
    <user name = "[login name]" password = "[new normal password]" group = "normal"/>

To create new logins for super user applications, add lines in this form to the amq_server.cfg file:

<security name = "plain">
    <user name = "[login name]" password = "[new super password]" group = "super"/>