Author: | tundish |
---|---|
Date: | 19th May 2007 |
Copyright: | 2007 Thuswise Ltd |
Contact: | tundish at thuswise . org . uk |
Sprinkle works on Unix type platforms, notably Linux. Because of the way it's written, it is not currently available for Windows. If you're looking for a suitable Linux distribution to try it out on, I recommend CentOS [1]. You need version 4.4 or later.
These instructions tell you how to install Sprinkle and set it up.
Sprinkle comes as a single zipped archive. This is a file with a name like sprinkle-2007-06-21.tar.gz.
Save it to a temporary space, and unzip it with the command tar -xzvf sprinkle-2007-06-21.tar.gz. You should see the following tree:
+ advocacy + doc | | | README.html | README.txt | hackers.html | hackers.txt | users.html | users.txt | COPYING Makefile sprinkle.py test-sprinkle.py
The doc folder contains pairs of .txt and .html files (one of which you're currently reading). COPYING and Makefile are important if you plan to modify Sprinkle; see the Developers' Guide [2] in that event.
The .py files are the ones that actually do the work. To run them you need an installation of Python, version 2.3.4 at least. To test if this exists, type python at the command line. You should get something that looks like this:
Python 2.3.4 (#1, Apr 10 2005, 22:30:36) [GCC 3.3.5] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>>
Type Ctrl-D to get back to your shell prompt.
Sprinkle will be running for extended periods, and should only have access to a small part of your server. It therefore helps if you create a special user for it.
To create a user called sprinkle, become root and do:
useradd -m sprinkle
On most systems, this will make a new home directory called /home/sprinkle.
Become sprinkle (su sprinkle). Copy all the files from the temporary space to this home directory.
The STOMP protocol [3] describes things called queues. These are places where discussions take place. In Sprinkle, there is a directory called queues, and a directory beneath that for each queue.
Create a place for the message queues:
cd /home/sprinkle mkdir queues
Create a place for each queue. In the example we are about to follow, we will use two; all and gardening. So do:
mkdir queues/all mkdir queues/gardening
Any user who logs into your Sprinkle server needs a user directory and a configuration. All the user folders live in a directory called users. A user's configuration file lives in his user folder.
Create a place for the user folders:
cd /home/sprinkle mkdir users
Create a place for each user. This example will create a user called Siegfried:
mkdir users/siegfried
Place a configuration file in each user subdirectory. The name of the file is username.cfg where username is the name of the user. The files are in a typical ini format [4]. The DEFAULT section contains the user's login and password. Then there is a section for each queue the user subscribes to, with their settings for each one (eg: ack) See the STOMP protocol [3] for what these settings mean.
This is how you would quickly make a configuration file for the user siegfried:
$ cat > users/siegfried/siegfried.cfg [DEFAULT] login: siegfried passcode: canine [all] ack: auto [gardening] ack:auto
Type Ctrl-D at the end to write the file.
When Sprinkle makes a connection, at the other end would normally be a client which also conforms to the STOMP specification. However, because of the textual nature of the protocol, you can type the necessary messages manually from a telnet session.
This is how we are going to test your sprinkle server. Type exactly what you see in the listings, except where you see ^@. This is a null character, which requires Ctrl-@ (on my keyboard, Ctrl, shift and the ' key).
Start the sprinkle server
$ ./sprinkle.py sprinkle[1289]: Starting up... sprinkle[1290]: Listening on port 12000
Start your telnet client by typing:
telnet localhost 12000
If the connection is made properly, you are likely to see:
Trying 127.0.0.1... Connected to localhost. Escape character is '^]'.
We will now log in as Siegfried, establish a transaction, and send a couple of messages to the gardening queue.
Type:
CONNECT login: siegfried passcode: canine ^@
Sprinkle sends back (your session number may differ):
CONNECTED session: 1194 ^@
So now, we begin a transaction, and send two messages to gardening:
BEGIN transaction: t1 ^@ SEND destination: gardening transaction: t1 The bluebells are out ^@ SEND destination: gardening transaction: t1 receipt: spring Spring has sprung! ^@
This second message asked for a receipt, which you should get back straight away:
RECEIPT receipt-id: spring ^@
Finally, we commit the transaction:
COMMIT transaction: t1 ^@
Sprinkle will place each message you sent on the gardening queue, and as a subscriber of that queue, Siegfried receives:
MESSAGE content-length: 20 destination: gardening message-id: gardening-Jag6xi Spring has sprung! ^@ MESSAGE content-length: 23 destination: gardening message-id: gardening-UwvWSV The bluebells are out ^@
It's now time to say goodbye, so enter:
DISCONNECT ^@
Sprinkle obliges. The final message looks a little alarming, but it's just an acknowledgement that the link is about to go down:
ERROR content-length: 10 message: disconnection notice DISCONNECT^@ Connection closed by foreign host.
Sprinkle aims to implement all of the STOMP protocol. However, you might not need all the features STOMP defines. By default, Sprinkle gives you a subset of the protocol, and other behaviour has to be requested when you run the server. This applies to the following capabilities:
- Allowing users to subscribe and unsubscribe to queues during a session
To demonstrate subscription, we will add a new user, like so:
$ mkdir users/tristan $ cat > users/tristan/tristan.cfg [DEFAULT] login: tristan passcode: cricket [all] ack: auto
Type Ctrl-D at the end to write the file.
Note that Tristan is not yet subscribed to the gardening queue.
Start the Sprinkle server with an extra option as follows:
$ ./sprinkle.py --allow-subscribe sprinkle[1307]: Starting up... sprinkle[1308]: Listening on port 12000
Follow steps 3a and 3b from the previous section to log in as Siegfried.
Open a second window, start another telnet session, and login as Tristan, like this:
CONNECT login: tristan passcode: cricket ^@
Send a message from Siegfried to gardening:
SEND destination: gardening The bluebells are out ^@
Siegfried should immediately receive a copy of this:
MESSAGE content-length: 23 destination: gardening message-id: gardening-XBiSUy The bluebells are out
Tristan however, should not.
Now, as Tristan, subscribe to the gardening queue:
SUBSCRIBE destination: gardening ack: auto ^@
Siegfried sends another message:
SEND destination: gardening Spring has sprung! ^@
Both Siegfried and Tristan should receive a copy of this one.
Tristan now unsubscribes from gardening:
UNSUBSCRIBE destination: gardening ^@
One more contribution from Siegfried:
SEND destination: gardening They'll be lambing soon. ^@
This time, only Siegfried gets the message.
You forgot to create a queue space
OSError: [Errno 2] No such file or directory: './queues'
Means you need to create a directory to hold each message queue. This by default is called queues and it lives in the same location as the Sprinkle broker.
Sprinkle is already running
socket.error: (98, 'Address already in use')
This sometimes happens if a previous error leaves an instance of Sprinkle running in the background. First stop the foreground process with Ctrl-\. Then find the running process and kill it. If you're not sure how to do this, the following magic should do the trick:
kill -s TERM `ps x | grep [s]prinkle | cut -d' ' -f2`
You forgot to configure a user
You'll know because when you try and connect, you'll get an error message like this:
ERROR content-length: 44 message: bad user credentials {'passcode': 'canine', 'login': 'siegfried'}
You forgot to create the directory for a new queue
Often the cause of:
ERROR content-length: 11 message: failure to send hi to all
[1] | http://www.centos.org/ |
[2] | hackers.html |
[3] | (1, 2) http://stomp.codehaus.org/Protocol |
[4] | http://en.wikipedia.org/wiki/INI_file |