Author: tundish
Date: 19th May 2007
Copyright: 2007 Thuswise Ltd
Contact: tundish at thuswise . org . uk

2   Sprinkle: Guide for Administrators

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.

2.1   Download the source

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.

2.2   Install

  1. 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.

  2. Become sprinkle (su sprinkle). Copy all the files from the temporary space to this home directory.

  3. 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
      
  4. 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.

2.3   Basic Use

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).

  1. Start the sprinkle server

    $ ./sprinkle.py
    sprinkle[1289]: Starting up...
    sprinkle[1290]: Listening on port 12000
    
  2. 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 '^]'.
    
  3. We will now log in as Siegfried, establish a transaction, and send a couple of messages to the gardening queue.

    1. Type:

      CONNECT
      login: siegfried
      passcode: canine
      
      ^@
      
    2. Sprinkle sends back (your session number may differ):

      CONNECTED
      session: 1194
      
      ^@
      
    3. 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!
      ^@
      
    4. This second message asked for a receipt, which you should get back straight away:

      RECEIPT
      receipt-id: spring
      
      ^@
      
    5. Finally, we commit the transaction:

      COMMIT
      transaction: t1
      
      ^@
      
    6. 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
      ^@
      
    7. It's now time to say goodbye, so enter:

      DISCONNECT
      
      ^@
      
    8. 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.
      

2.4   Additional features

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

2.4.1   Activating subscription

  1. 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.

  2. Start the Sprinkle server with an extra option as follows:

    $ ./sprinkle.py --allow-subscribe
    sprinkle[1307]: Starting up...
    sprinkle[1308]: Listening on port 12000
    
  3. Follow steps 3a and 3b from the previous section to log in as Siegfried.

  4. Open a second window, start another telnet session, and login as Tristan, like this:

    CONNECT
    login: tristan
    passcode: cricket
    
    ^@
    
  5. 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.

  6. Now, as Tristan, subscribe to the gardening queue:

    SUBSCRIBE
    destination: gardening
    ack: auto
    
    ^@
    
  7. Siegfried sends another message:

    SEND
    destination: gardening
    
    Spring has sprung!
    ^@
    

    Both Siegfried and Tristan should receive a copy of this one.

  8. Tristan now unsubscribes from gardening:

    UNSUBSCRIBE
    destination: gardening
    
    ^@
    
  9. One more contribution from Siegfried:

    SEND
    destination: gardening
    
    They'll be lambing soon.
    ^@
    

    This time, only Siegfried gets the message.

2.5   Common Errors

  1. 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.

  2. 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`
    
  3. 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'}
    
  4. 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