.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH STOMPSERVER "1" "July 2009" "stompserver" "User Commands"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
stompserver \- Stomp protocol messaging server
.SH SYNOPSIS
.B stompserver
[\fIoptions\fR]
.SH DESCRIPTION
Stomp messaging server with file/dbm/memory/activerecord based FIFO
queues, queue monitoring, and basic authentication.

.SH OPTIONS
.TP
\fB\-C\fR, \fB\-\-config\fR=\fICONFIGFILE\fR
Configuration File (default: stompserver.conf)
.TP
\fB\-p\fR, \fB\-\-port\fR=\fIPORT\fR
Change the port (default: 61613)
.TP
\fB\-b\fR, \fB\-\-host\fR=\fIADDR\fR
Change the host (default: localhost)
.TP
\fB\-q\fR, \fB\-\-queuetype\fR=\fIQUEUETYPE\fR
Queue type (memory|dbm|activerecord|file) (default: memory)
.TP
\fB\-w\fR, \fB\-\-working_dir\fR=\fIDIR\fR
Change the working directory (default: current directory)
.TP
\fB\-s\fR, \fB\-\-storage\fR=\fIDIR\fR
Change the storage directory (default: .stompserver, relative to working_dir)
.TP
\fB\-d\fR, \fB\-\-debug\fR
Turn on debug messages
.TP
\fB\-a\fR, \fB\-\-auth\fR
Require client authorization
.TP
\fB\-c\fR, \fB\-\-checkpoint\fR=\fISECONDS\fR
Time between checkpointing the queues in seconds (default: 0)
.TP
\fB\-h\fR, \fB\-\-help\fR
Show this message

.SH QUEUES

Stompserver handles basic message queue processing using memory, file, or dbm
based queues. Messages are sent and consumed in FIFO order (unless a
client error happens, this should be corrected in the future). Topics
are memory-only storage.  You can select activerecord, file or dbm
storage and the queues will use that, but topics will only be stored
in memory.

memory queues are of course the fastest ones but shouldn't be used if
you want to ensure all messages are delivered.

dbm queues will use berkeleydb if available, otherwise dbm or gdbm
depending on the platform. sdbm does not work well with marshalled
data. Note that these queues have not been tested in this release.

For the file based storage, each frame is stored in a single file. The
first 8 bytes contains the header length, the next 8 bytes contains
the body length, then the headers are stored as a marshalled object
followed by the body stored as a string. This storage is currently
inefficient because queues are stored separately from messages, which
forces a double write for data safety reasons on each message stored.

The activerecord based storage expects to find a database.yml file in
the configuration directory. It should be the most robust backend, but
the slowest one. The database must have an ar_messages table which can
be created with the following code (you are responsible to do so):

  ActiveRecord::Schema.define do
    create_table 'ar_messages' do |t|
      t.column 'stomp_id', :string, :null => false
      t.column 'frame', :text, :null => false
    end
  end

You can read the frames with this model:

  class ArMessage < ActiveRecord::Base
    serialize :frame
  end

The ar_message implementation will certainly change in the future.

This is meant to be easily readable by a Rails application (which
could handle the ar_messages table creation with a migration).

.SH ACCESS CONTROL

Basic client authorization is also supported.  If the \-a flag is
passed to stompserver on startup, and a .passwd file exists in the run
directory, then clients will be required to provide a valid login and
passcode.  See passwd.example for the password file format.

.SH MONITORING

Queues can be monitored via the monitor queue (this will probably not
be supported this way in the future to avoid polluting the queue
namespace). If you subscribe to /queue/monitor, you will receive a
status message every 5 seconds that displays each queue, it's size,
frames enqueued, and frames dequeued. Stats are sent in the same
format of stomp headers, so they are easy to parse. Following is an
example of a status message containing stats for 2 queues:

Queue: /queue/client2
size: 0
dequeued: 400
enqueued: 400

Queue: /queue/test
size: 50
dequeued: 250
enqueued: 300


.SH AUTHOR
stompserver was written by Patrick Hurley <phurley@gmail.com> and Lionel Bouton.
.PP
This manual page was compiled from the included documentation by 
Bryan McLellan <btm@loftninjas.org> for the Debian project (and may be used by others).
The existing documentation is distributed under the MIT license.