PsEPR Documentation: Server Guide

In the subversion tree for the PsEPR project on SourceForge, the sub directory org.psepr.PsEPRServer/build contains a Makefile that will take a jar file and create the PsEPRServer rpm. The way the server jar is usually created is by exporting it from Eclipse. There are beginnings of a build.xml for an Ant build, but that is not completed.

The version of the server is built from the Subversion version of the source file for org.psepr.PsEPRServer.PsEPRServer. The Makefile extracts that version number and builds the rest of the RPM filename (and thus the version) from the date.

Building creates an RPM file of the PsEPR server but there are a few scripts and related files that must be installed.

In the subversion tree for the PsEPR project on SourceForge, the sub directory org.psepr.PsEPRServer/install includes the script pseprInstall which pushes the required RPMs to a PlanetLab sliver and installs same.

If you look in the script, you will see it looks for RPMs in a subdirectory. The RPMs it requires are:

• PsEPRServer-52-200709182234.noarch.rpm
• PsEPRjClient-2.11-200608301415.noarch.rpm
• SendGeneric-1.7-200608291216.noarch.rpm
• WatchChannel-1.8-200608291302.noarch.rpm
• jre-1_5_0_04-linux-i586.rpm
• which-2.16-6.i386.rpm

Additionally, the script installs a server configuration file which replaces whatever was installed by the RPM. So, you must also place the following files in the installation directory:

• PsEPRServer.xml
• jClient.xml

The installation process is to cd into the install directory as checked out from subverion, create the rpm subdirectory, populate the directory with the RPMs listed above, add the two configuration files mentioned above into the install directory and then to execute:

              ./pseprInstall SLICENAME HOSTNAME
              

There are zillions of configurable parameters for the server. These are all listed in the module org.psepr.PsEPRServer.ParamServer. Each parameter name is slash seperated set of words. So, for instance, /PsEPRServer/peer/leasepeer/outboundQueueMax is the name of the output queue max size for the LeasePeer version of peer (server to server) connections.

The parameters all have default values which are also listed in the org.psepr.PsEPRServer.ParamServer. module. The values can be changed for a run of the server by specifying them in the file PsEPRServer.xml. This file is looked for at

• /usr/local/psepr/etc/psepr/PsEPRServer.xml
• $HOME/.psepr/PsEPRServer.xml
• \Documents and Settings\$USER\.psepr\PsEPRServer.xml
• ./PsEPRServer.xml

The format of the PsEPRServer.xml file is XML. The name of a parameter acts likes a poor man's XPath expression to select the value in the file. The default configuration file looks like:

<PsEPRServer>
    <client>
        <XMPP>
          <maximumConnections>400</maximumConnections>
      </XMPP>
    </client>
    <peer>
        <leasePeer>
            <!-- URL of central peer config file -->
            <configurationURL>http://psepr.org/PsEPRServer/config/LeasePeer.xml</configurationURL>
            <!-- number of seconds between fetches and checking of central peer config file -->
            <configurationCheckSeconds>300</configurationCheckSeconds>
            <!-- seconds that a peer makes a lease to another peer -->
            <leaseSeconds>600</leaseSeconds>
        </leasePeer>
    </peer>
    <service>
    	<statusReporter>
	    	  <!-- seconds between sending general status messages -->
	        <periodSeconds>300</periodSeconds>
	        <clientConnections> <include>no</include> </clientConnections>
	        <peerConnections> <include>no</include> </peerConnections>
	        <routeTable> <include>no</include> </routeTable>
	        <service> <include>yes</include> </service>
    	</statusReporter>
    </service>
    <debug>
        <comment>0xB072=SERVICES,PEER,GLEANER,LEASE,BADERROR,STATUSREPORT,IO</comment>
        <comment>0xB062=SERVICES,PEER,GLEANER,LEASE,BADERROR,IO</comment>
        <comment>0xB062=SERVICES,GLEANER,LEASE,BADERROR,IO</comment>
        <filterLevel>
            0xB062
        </filterLevel>
    </debug>
</PsEPRServer>
              

The default location for log files is /usr/local/psepr/logs/PsEPRServer. The log files are a rotated set of files (default of a maximum of 10 files of no more than 1 megabyte) so logs never need to be trimmed. The information that is logged is controlled by /PsEPRServer/debug/filterLevel who's bits turn on and off different log details. The bits are listed in the module org.psepr.PsEPRServer.DebugLogger. Several of the usual logging values are listed as comments in the sample configuration file.

The default ports use by the server are:

When a PsEPRServer is running, the LeasePeer protocols requires each server to know all of the other servers to talk to. The server gets this information by fetching a configuration file from an URL. If the server cannot fetch this file, it will not receive any connections or do any work.

The default location for the inter-server configuration file is http://psepr.org/PsEPRServer/config/LeasePeer.xml and is specified in the individual server configuration file as discussed above. The configuration file is an XML file which specifies, for each server, which server is should connect to, a unique ID that the other server will identify itself with and an authentication code that is used for a peer to know it's talking to the correct peer.

The LeasePeer.xml file is most easily built with a script that is in the web site information in PsEPR's Subversion tree. In the subversion directory org.psepr.www/PsEPRServer/config the scripts buildLeasePeer and buildjClientxml takes the list of active servers from the file ActivePeers and builds LeasePeer.xml and a jClient.xml both of which are then put on a web server to be fetched by the servers and the clients.

The server's job is moving events from sources to sinks. The basic structure is simple. org.psepr.ConnectionReaders receive connections from event sources, the events are packaged into org.psepr.ServerEvents and sent to the org.psepr.Route. The Router contains the destinations for events and the events are dispatched to the external connections.

org.psepr.ConnectionReaders implement two interfaces: org.psepr.Inner and org.psepr.Outter. The Inner interface passes events from the ConnectionReader and the Outter interface receives events to go out the connection.

The queuing and threading model prevents any deadlocks by requiring three threads and two queues in each ConnectionReader:

• input queue: where received events (from the socket or whatever) are placed once they are received;
• outter queue: where events to be sent over the connection are placed;
• reader thread: which listens to the input media (stream or socket), reads and assembles events and places the packaged events into the input queue;
• router thread: which takes events off the input queue and calls the RouteTable for the event. This thread will do the search of the destinations in the RouteTable and call the Outter interfaces for each destination. The Outter interface just queues the event in the ConnectionReader's output queue;
• output thread: which takes events off the output queue and sends the out the media connection (stream or socket).

If the internals of the PsEPRServer needs to generate and event, org.psepr.InternalSender implements an inbound queue with a router thread so that internal threads can't become tangled.

The org.psepr.Router calls org.psepr.RouteTable to get a list of org.psepr.Outter interfaces to send the event to. As different connections are made to the PsEPRServer and clients make leases they call RouteTable.addRoute to specify a potential destination for an event. Thus each entry in the RouteTable is for a destination: some connections request to hear about events that match certain criteria.

Each of the routes in RouteTable contain:

• identifier: a code which uniquely identifies this route. This can be used to delete the route.
• channel: the channel this lease is listening for
• service: the particular service this lease is listening for. This can be NULL so say any service will match;
• instance: the particular instance this lease is listening for. This can be NULL so say any instance will match;
• expiration time: time when this route should be removed from the RouteTable. This makes routes self-managing in that whoever adds the route can add and forget since the entry will go away when it's expiration time is reached;
• outter interface: where to send the event if the criteria is matched

The class org.psepr.ConnectionManager is the super class for the controller of connections of different types. The ConnectionManager* classes manage all the connections of the different types.

The Discovery service periodically outputs on a channel information that comes from each of the ConnectionManagers. The purpose of this service is to allow clients to listen on the "discovery channel" and find all of the connection managers it can connect to. This is the only way for clients to find all of the servers for a particular type of connection.

The Discover service loops through all the ConnectionManagers calling ConnectionManager.xmlForDiscovery() to create a message. The format of the event payload is:

<payload xmlns="http://dsmt.org/schema/psepr/payload/PsEPRServer/discovery-1.0">
  <connections>
    <hostname>hostGeneratingDiscovery</hostname>
    <instance>instanceCodeForServer</instance>
    <serverVersion>serverVersionCode</serverVersion>
    <connection>
      <type>typeOfConnection</type>
      <hostname>hostToConnectTo</hostname>
      <port>portToConnectTo</port>
      <class>classnameOfConnectionManager</class>
    </connection>
  </connections>
</payload>