FreePastry release notes

Release 1.1,  9/13/02.

FreePastry is a modular, open source implementation of the Pastry p2p routing and location substrate.


Peter Druschel , Eric Engineer, Romer Gil , Y. Charlie Hu , Sitaram Iyer , Andrew LaddAlan Mislove , Animesh Nandi , Charlie Reis, Atul Singh , and RongMei Zhang contributed to the FreePastry code. The code is based on algorithms and protocols described in the following papers:


The software requires a Java runtime, version 1.4. The software was developed using Sun's SDK, version 1.4.0_01.


Changes since release 0.1beta


Release 1.1 has the following limitations.
Future transport protocols will also be based on an open standard to ensure interoperability among different implementations.
(Background: To start a Pastry node, the IP address (and port number, unless the default port is used) of a "bootstrap" or "contact" node must be provided. If no such node is provided, and no other Pastry node runs on the local machine, then FreePastry creates a new overlay network with itself as the only node. Any node that is already part of the Pastry node can serve as the bootstrap node.)

Future releases will address efficiency, security, interoperability and will provide additional application components like a distributed hash table, replica management, caching, PAST, etc.


To use the binary distribution, download the pastry jar file and set the Java classpath to include the path of the jar file. This can be done using the "-cp" command line argument, or by setting the CLASSPATH variable in your shell environment.

To compile the source distribution, you will need to have GNU make installed (available from , or as part of cygwin ) on your system. Expand the archive (FreePastry-1.1.tgz or into a directory. Set the environment variables mentioned in setpath.csh to values appropriate for your system. Execute "make" in the top level directory (you may have to run "make" twice the first time), then change to the "classes" directory to run FreePastry. 

You may have to provide a Java security policy file with sufficient permissions to allow FreePastry to contact other nodes. The simplest way to do this is to install a ".java.policy" file with the following content into your home directory:

grant {

Running FreePastry

1. To run a HelloWorld example:
        Usage: java [-cp pastry.jar] rice.pastry.testing.DistHelloWorld
                                [-msgs m] [-nodes n] [-port p] [-bootstrap bshost[:bsport]] [-protocol [wire,rmi]]
                                [-verbose|-silent|-verbosity v] [-help]

          Ports p and bsport refer to contact port numbers (default = 5009).
          Without -bootstrap bshost[:bsport], only localhost:p is used for bootstrap.
          Default verbosity is 5, -verbose is 10, and -silent is -1 (error msgs only).

          (replace "pastry.jar" by "FreePastry-<version>.jar", of course)
    Some interesting configurations:

        a. java rice.pastry.testing.DistHelloWorld

                Starts a standalone Pastry network, and sends two messages
                essentially to itself. Waits for anyone to connect to it,
                so terminate with ^C.

        b. ..DistHelloWorld -nodes 2

                One node starts a Pastry network, and sends two messages to
                random destination addresses. At some point another node
                joins in, synchronizes their leaf sets and route sets, and
                sends two messages to random destinations. These may be
                delivered to either node with equal probability. Note how
                the sender node gets an "enroute" upcall from Pastry before
                forwarding the message.

        c. ..DistHelloWorld -nodes 2 -verbose

                Also prints some interesting transport-level messages.

        d. pokey$ ..DistHelloWorld
           gamma$ ..DistHelloWorld -bootstrap pokey

                Two machines coordinate to form a Pastry network.

        e. pokey$ ..DistHelloWorld
           gamma$ ..DistHelloWorld -bootstrap pokey
                wait a few seconds, and interrupt with <ctrl-C>
           gamma$ ..DistHelloWorld -bootstrap pokey

                The second client restarts with a new NodeID, and joins the
                Pastry network. One of them sends messages to the now-dead
                node, finds it down, and may or may not remove it
from the leaf sets. (repeat a few times to observe both
possibilities, i.e., leaf sets of size 3 or 5). If the
latter, then leaf set maintenance kicks in within a minute
on one of the nodes, and removes the stale entries.

f. pokey$ ..DistHelloWorld
gamma$ ..DistHelloWorld -bootstrap pokey -nodes 2

The client on gamma instantiates two virtual nodes, which
are independent in identity and functionality. Note how the second virtual node bootstraps from the first (rather than from pokey). Try starting
say 10 or 30 virtual nodes, killing with a <ctrl-C>,
starting another bunch, etc.

2. To run the same HelloWorld application on an emulated network:

        Usage: java [-cp pastry.jar] rice.pastry.testing.HelloWorld
        [-msgs m] [-nodes n] [-verbose|-silent|-verbosity v]
                          [-simultaneous_joins] [-simultaneous_msgs] [-help]
    Some interesting configurations:

        a. java rice.pastry.testing.HelloWorld

                Creates three nodes, and sends total three messages from
                randomly chosen nodes to random destinations addresses
                (which are delivered to the node with the numerically
                closest address).

        b. ..HelloWorld -simultaneous_joins -simultaneous_msgs

                Join all three nodes at once, then issue three messages,
                then go about delivering them.

3. To run a regression test that constructs 500 nodes connected by an emulated network:

        java [-cp pastry.jar] rice.pastry.testing.DirectPastryRegrTest

4. To run a simple performance test based on an emulated network with successively larger numbers of nodes:

	 java [-cp pastry.jar] rice.pastry.testing.DirectPastryPingTest 


Writing applications on top of FreePastry

All applications must extend the class rice.pastry.client.PastryAppl. This class implements the Pastry API. Each application consists minimally of an application class that extends rice.pastry.client.PastryAppl, and a driver class that implements main(), creates and initializes one of more nodes, etc. Example applications and drivers can be found in rice.pastry.testing; the Hello World suite (,, may be a good starting point.

Another sample Pastry application is rice.scribe.

Running Scribe

1. To run a simple distributed test:
        Usage: java [-cp pastry.jar] rice.scribe.testing.DistScribeRegrTest
                                [-nodes n] [-port p] [-bootstrap bshost[:bsport]] [-protocol [wire,rmi]]

          Ports p and bsport refer to contact port numbers (default = 5009).
          Without -bootstrap bshost[:bsport], only localhost:p is used for bootstrap.
          (replace "pastry.jar" by "FreePastry-<version>.jar", of course)
    Some interesting configurations:

        a. java rice.scribe.testing.DistScribeRegrTest

                Starts five Scribe nodes on the local host, creates some groups and published a message every 10 seconds. Waits for anyone to connect to it,
                so terminate with ^C. 

 b. pokey$ ..DistDistScribeRegrTest gamma$ ..DistDistScribeRegrTest -bootstrap pokey Two machines with 5 Scribes nodes each coordinate to form several groups and publish a message every 10 seconds in each.
Try starting the test on several more machines then kill the test with
^C on some machine and watch how the multicast groups recover.

2. To run a regression test that constructs many Scribe nodes connected by an emulated network, and stresses many aspects of Scribe:

        java [-cp pastry.jar] rice.scribe.testing.DirectScribeRegrTest