OpenQueue Installation - README

OpenQueue - Download Release Notes
May 6, 2000

(Contents of this download are covered by license agreements. See the
individual files for details.)

This file describes the components included in this release, and describes
how to install them.  The components are:

* Passamaquoddy -- an OpenQueue server, written in Java.
* OQApplet      -- an OpenQueue client, written as a Java applet.
* oqsend.exp    -- an Expect script for sending one OpenQueue message.
* -- a Perl benchmarking script to send hundreds of messages
at once.


* Passamaquoddy -- an OpenQueue server, written in Java.

Passamaquoddy is a multithreaded OpenQueue server written in Java.  It
uses JDBC to connect to a SQL database for persistent message storage.
The steps in setting up Passamaquoddy are:

1. Create the SQL database for the OpenQueue messages, and set up user
accounts as needed. 

The SQL instructions for creating the database, called "oqdb" in this
release, are found in /org/openqueue/passamaquoddy/setup.sql.  The
instructions are designed for mySQL, but should be easy to change for
another database system.

The setup script creates one user named "root", with a password of
"password".  CHANGE THIS PASSWORD immediately to something non-obvious.
Do this by making a SQL call of the form "UPDATE Users SET
password='wdiu26dkDW' WHERE userid=1".

Note that as of May 6, 2000, the SQL calls made by Passamaquoddy have been
pulled out into a separate file,
/org/openqueue/passamaquoddy/oq_sql_dialect.conf.  This allows you to use
the default SQL commands, or you can add custom SQL code to override the
defaults.  Change the dialect in use by editing the "db_dialect" parameter
in OQ.conf.  If it is set to "DEFAULT", the generic SQL will be used.
Create your own label for a dialect, if you like; see oq_sql_dialect for
working samples.

2. Install a Java Virtual Machine (such as from the JDK), if you don't
already have one installed.

3. Install a JDBC driver appropriate for your SQL database (e.g., whether
you have Oracle, mySQL, Interbase, etc.).

4. Edit the OQ.conf configuration file. Replace the default information
for JDBC connection strings, user name, and user password with your own
information.  You will need to provide this information so that the
OpenQueue server can connect to the SQL database and read and write into
the "oqdb" database. (You can name the database anything you like, so long
as you make a proper JDBC connection string for it in oq.conf.)

5. Call the 'java' or 'jre' program in your JDK to run the OQServer class,
with parameters as appropriate.

This is typically done by moving into the directory in which 'org' lives,
and entering a command such as:
/usr/java/jdk118_v1/bin/jre -classpath
/OQServer -i

Of course, the path to your own JDK installation will vary.  The '-i'
option starts an interactive console that allows you to monitor and
control the server.  For example, you can create new users, create new
topics, check server statistics, or shut down the server.  Enter 'help'
into this interactive console to see the available commands.  

It is useful to preface the entire command above with 'dislocate ', which
runs the console in the context of the "dislocate" Expect program. This
lets you disconnect from the console, and then reconnect to it later, even
from another machine (via telnet etc.).  Find details on Expect's
"dislocate" program for more details.

Once all this is done and the server is running, it will respond to
OpenQueue clients, on the standard OpenQueue port of 8764 by default.  You
can telnet to this port to verify that the server is running.  

Two administrative topics are created by default:
/system/stats/connections/total  (#101) is the total number of client
connections made since the server was started, and
/system/stats/connections/current (#102) is the current number of clients
connected.  The already-created user "root" already has a subscription to
#101.  This means that once the server is running and says it's ready to
accept clients, you can test it as follows:

1. Telnet to the machine on which Passamaquoddy running (or to localhost
if it's the same as the machine you are testing on), using port 8764, the
IANA port for OpenQueue.

2. Login as root.

3. Turn updates on. You should receive an update immediately for the
message that was posted when your telnet session connected to the server. 

4. Acknowledge the update.  

5. Now open a new telnet session to 8764, and you'll receive another
update on your first connection.  In other words, root has asked to be
notified every time a message is added to the Total Connections topic
(#101), and each time a socket connects to 8764, the server sends root
another notification.

Here is what your telnet session will look like, where S: is what the
Passamaquoddy server types and C: is what you type:

$ telnet localhost 8764
Connected to localhost.
Escape character is '^]'.
S: OPENQUEUE=0.48 SERVER=passamaquoddy/0.1.1 MODES=ALIVE
C: LOGIN root myCleverPassword mode=ALIVE
S: 200 - OK.
S: START ITEM #101 1
S: Subject: Total Connections = 1
S: Posted: 26 Apr 2000 22:58:40 GMT
S: Content-Length: 17
S: (no message body)
C: !b ACK 1
S: !b 200 - OK.

There is a third topic created by setup.sql, with a path of /test/stuff
(#755).  This allows you to try using the SEND command without having to
create a new topic.

Limitations: Passamaquoddy still has a number of limitations.
Passamaquoddy currently expects each line of an incoming message to be
less than 4K, although a complete message can be as large as 2 GB.  

* OQApplet -- an OpenQueue client, written as a Java applet.

OQApplet provides a simple scrolling list of subject lines that come in
from an OpenQueue topic.  As new messages are sent from the server, the
existing messages in the applet scroll down, and the new messages are then
displayed.  An example of a web page which uses this applet can be found
at .

* oqsend.exp -- an Expect script for sending one OpenQueue message.

Expect is a package based on the tcl language, and is commonly used for
automating interactive programs. The oqsend.exp script can be used to
automatically log into an OpenQueue server, send a message into a topic,
and log out of the server.  If an error occurs (such as the user already
being logged into the server on another connection), the script returns a
non-zero result code.

Here is an example of a basic call to oqsend.exp:

expect -- oqsend.exp '#1234' -v -u johndoe -p drowssap -s
'test subject' -m 'test message body'

In this example, the command connects to the OpenQueue server at
"", as user "johndoe" with password "drowssap" ("password"
backwards, clearly not a good choice for a password).  The command will
then send a message to the topic '#1234' (note that currently
Passamaquoddy only supports topic number references, such as this, not
topic path references). The subject of the message is "test subject", and
the body of the message is "test message body". 

Here is the description of the available options, taken from oqsend.exp:

-s subject  -- includes subject line (headline).
                if not present, should be in headers
-m message  -- body of message. if used, stdin is ignored, and
                subject (headline) must be included, using -s option.
-u user     -- user name, rather than local file lookup
-p password -- password, rather than local file lookup
-v verbose  -- shows the conversation with the OpenQueue server, and

Note that it is convenient but insecure to pass the password along in the
command line, as another user on the system could run "ps" to see all
processes, and see the password.  So oqsend.exp also supports a
configuration file, called oqsend.conf, which should live in the same
directory as oqsend.exp.  Here a username and password can be listed for a
variety of hosts, such as:           charlie       mccarthy

If oqsend.exp is run with the -u or -p parameter missing, it will look for
entries in oqsend.conf that correspond to the host parameter.  In other
words, this command:

expect -- oqsend.exp '#400' -s 'testing' -m 'just a test'

will use "charlie" as the username, and "mccarthy" as the password, when
it connects to the OpenQueue server at  The username and
password will not appear in the results from "ps" in this case.  This is a
primitive solution, and only allows limited numbers of accounts.

As noted in the list of options above, a large or binary message can be
read in from stdin, if the -m option is avoided and if the -s option is
used to provide the subject line.  Note that Passamaquoddy currently
expects each line of the message to be less than 4K.

Here's an example in PHP to send a large message:

   $messageBody = 'First, come up with a really long message .....  etc.
   $fp = popen("expect -- oqsend.exp '#100' -u joe -p foo -s 'A
Message' ",'w');
   fputs($fp, $messageBody);
   $resultCode = pclose($fp);

   if ($resultCode != 0) {
     echo "Problem with oqsend = $dummy2 \n";

* -- a Perl benchmarking script 

Run this as follows:

perl --user=yourname --password=yourpassword

By default, connects to localhost's OpenQueue server, but
add --host= to point it to a different server.  Of course, the
user account passed in will need to have write permissions for the topic.
(That currently means the user owns the topic, or is an administrator.)

The script send 1,000 messages (10 loops of 100 messages each).  Override
this setting by using --loops, where --loops=2 will send 2*100 = 200