System Requirements
- You can install SPIN on most common operating systems including Microsoft Windows, and UNIX-like operating systems, such as Linux, Solaris, and Mac OSX.
- Java Runtime Environment, Standard Edition (JRE)
- Apache Tomcat, version 5.0 or 6.0
Note: This document uses Unix-like conventions for paths and environment variables that you can map to Windows equivalents.
Obtaining SPIN
You can obtain the SPIN WAR from the open.med Maven repository.
http://repo.open.med.harvard.edu/nexus/
In general, the SPIN WAR is available at the following location:
http://repo.open.med.harvard.edu/nexus/content/groups/public/org/spin/node-server/<version>/node-server-<version>.war
The location and filename corresponds to the latest released SPIN version. For example, the latest released SPIN version is 1.16. The SPIN WAR would be located at the following URL:
Installation and Configuration
Layout
SPIN is installed in two distinct places on the host operating system:
- SPIN web application (webapp) is installed within the servlet container, Tomcat.
- SPIN home directory is a place on the file system that contains folders for storing configuration files, log files and plugins.
Process Overview
Installing the SPIN software, configuring and deploying the network node consists of the following processes performed in this order:
- Configure the SPIN home directory
- Install the SPIN web application
- Configure node.xml
- Configure the routingtable.xml
- Configure the keystore.xml
- Restart the web servlet container
Step 1: Configure the SPIN Home Directory
SPIN requires a dedicated "home directory", $SPIN_HOME, which is the root of a hierarchy of folders that contain configuration files, query log files, and plugins.
The SPIN home directory consists of the following folders:
conf/--- configuration files
db/- query log files
plugins/- JARs containing plugins (queries to be run by the Node)
It is recommended that you configure the home directory outside of the Java Servlet container, specifically outside of the webapp structure, which is not the default location. The default is under the process-owner's home directory.
By default, the directory is ~/.spin, where tilde (~) is the home directory of the process-owner's home directory.
On Microsoft Windows systems, the default directory is ~/spin. The directory must be writeable by the process owner.
You can override the default location by setting:
- The environment variable, SPIN_HOME to the absolute path of the desired SPIN home directory
- The JVM system property, SPIN_HOME to the absolute path of the desired SPIN home directory
Step 2: Deploy the SPIN web application
Determine the Java servlet container's home directory, which is typically dictated by the host operating system. For example, it may be the Tomcat user's home directory, ~tomcat, which would look like: $TOMCAT_HOME/webapps directory.
- Deploy the .WAR file. Copy blank.war to the $TOMCAT_HOME/webapps directory.
- Start the servlet container (Tomcat). This will create a keystore (with a generated keypair) and keystore.xml in $SPIN_HOME/conf.
The two configuration files, node.xml and routingtable.xml will not be created, but the node will start without them.
Step 3: Create and configure node.xml and routingtable.xml
You can find examples of this files located:
Node.xml contains miscellaneous node-wide configuration information, such as the node's role in the network. The configuration identifies if the node performs the following tasks:
Authenticates users
Broadcasts queries
Aggregates responses
Performs queries
Routes incoming and outgoing messages
Node.xml also contains various values for thresholds and timeouts. You can view an example node.xml at:
http://scm.chip.org/svn/repos/spin/base/trunk/examples/src/test/resources/node.xml
Node Configuration Properties
The order of the elements in the configuration file is important. Properties are required or optional.
Required Node Configuration Properties
Version and the node name are the only required properties.
<version>
Describes the human-readable version of SPIN on which this node is running. (This field is deprecated and will go away in future SPIN versions.)
<nodeName>
Describes the human-readable node name, such as Harvard Eagle-I (production).
Node.xml contains the following optional elements. If these elements are omitted, the defaults apply.
<isAuthenticator>
Can this node authenticate users?
Default: False
<isBroadcaster>
Should this node propagate the queries it receives to other nodes.
Default: True
<isAggregator>
Identifies if this node should aggregate responses from other nodes.
Default: False, if the node is not the root of a heierarchy, otherwise true.
<isQueryable>
Identifies if this node should respond to queries.
Default: True. Set to false if the node should only broadcast queries and aggregate results, for example.
<identityServiceClass>
Identifies the fully-qualified name of the JVM class used to authenticate users based on credentials. Only required if <isAuthenticator> is true. The supplied class, if present, must implement org.spin.query.message.identity.IdentityService.
Default: Null
<queries>
Identifies the queries, other than the basic queries, to which nodes respond. Each maps a queryType string to the fully-qualified name of a JVM class that implements that query. For each <queries> element, the <queryType> and <className> sub-elements are required. May be present zero or more times.
Note that all nodes respond to the following queries, at a minimum:
Spin.Echo
Spin.Audit
Spin.Discovery
Default: no additional queries
<certificationTTL>
When clients query a SPIN network, the queries must be digitally signed. Nodes examine queries when they are received and respond only if the digital signature is valid and not expired. The <certificationTTL> element describes, in milliseconds, how old a signature can be before being considered invalid due to expiration.
Default: 3600000, or one hour)
<cacheTTL>
In some circumstances, SPIN caches the results of queries to allow clients to retrieve them at a later time. However, results that are unclaimed after some period are purged automatically. Specified, in milliseconds, by the <cacheTTL> element.
Default: 3600000, or one hour
<broadcastTimeoutPeriod>
SPIN nodes attempt to broadcast queries they receive to other nodes defined as being children of, or downstream from the current node. A timeout period for these broadcast attempts is defined by the <broadcastTimeoutPeriod> element.
The <duration> sub-element defines the amount of the timeout.
The <unit> sub element defines the unit for the value of the <duration> field. enum constants in java.util.concurrent.TimeUnit define values for this field. Note the following examples:
<broadcastTimeoutPeriod>
<duration>5</duration>
<unit>SECONDS</unit>
</broadcastTimeoutPeriod>
or
<broadcastTimeoutPeriod>
<duration>1</duration>
<unit>HOURS</unit>
</broadcastTimeoutPeriod>
or
<broadcastTimeoutPeriod>
<duration>500</duration>
<unit>MILLISECONDS</unit>
</broadcastTimeoutPeriod>
Default: 5 seconds
<resultStoreType>
The type of underlying result store used to cache query results. Allowed values are 'SimpleInMemory' and 'Ehcache'. The SimpleInMemory result store is generally faster, but fails un-gracefully when memory runs out. The EHCache result store is generally slower, but fails more gracefully.
Default: SimpleInMemory
<queryActionMapClassName>
Defines the fully-qualified name of a JVM class that implements org.spin.node.QueryActionMap and provides QueryAction instances by name. Useful for creating SPIN using Spring, Guice, or another dependency-injection framework, or for instantiating QueryActions lazily, instead of eagerly at node-startup time, which is the default behavior.
Default: Null. Eagerly instantate QueryActions defined by <queries> elements)
You will find an example of node.xml at: https://scm.chip.org/svn/repos/spin/base/trunk/examples/src/test/resources/node.xml
Step 4: Create and configure routingtable.xml.
A SPIN node's place in a network topology is defined in routingtable.xml. SPIN nodes may participate in different overlay networks, fulfilling different roles in a topology, by joining different peer groups. A peer group defines a group of nodes and how they fit into a network topology. In routingtable.xml, nodes specify their place in different network topologies for zero or more peer groups.
Nodes always belong to the peer group, LOCAL, which includes only the current node. This is useful for querying only one node, without triggering query propagation.
When clients query a SPIN network, they send, along with their query, the peer group for which that the query is intended. Nodes use that peer group to look up how to propagate the query and where to return the results.
For a given peer group, nodes may have zero or one parents, and zero or more children. If a parent node is specified, query results from the current node, and those downstream, will be sent to the parent for aggregation. If no parent is specified, results are stored at the current node until the client retrieves them. It is also possible for a client to specify an arbitrary node as the point at which results will be aggregated and stored for retrieval.
If any child nodes are specified, the current node broadcasts all queries that it receives to the child nodes. Note that node, node B, can be listed as the child of node A, but node B does not have to list node A as its parent.
routingtable.xml contains zero or more <peerGroup> elements. The structure of these elements is as follows:
peerGroup (optional)
LOCAL peer group named with no parent or children added implicitly
<groupName> (required)
Unique name of the peer group
<parent> (optional)
The current node's parent
Default: null (no parent)
<children>
Zero or more child nodes that to which the current node should broadcast queries, if it receives a query destined for this peer group.
The structure of <parent> and <children> elements are identical.
<endpointType> (required)
Values: Only supports SOAP. (Local used only for testing.)
<address> (required)
Identifies the URL of the referenced node's WSDL, such as http://my-node.med.harvard.edu:8080/node-server/node?wsdl
You can find an example routingtable.xml file at
Step 5: Configure keystore.xml
A keystore is a repository of security certificates, either Certification Authority Certificates or Public key certificates. Keystore.xml contains information about the keystore file that contains the node's cryptographic keypair. The keypair includes the keystore file password and the keystore private key alias that you should use, if more than one private key exists.
The serial number of the node private key identifies the SPIN node.
The serial number of their private key supports the PKCS12 and JKS keystore formats.
Nodes are definitively identified on a network by the serial number of their private key. This file contains information about the keystore file, which contains the Node's cryptographic keypair, including the password of the keystore file and the alias of the private key in the keystore to use---if there is more than one.
The keystore file referenced by keystore.xml will also contain the certificates of authenticating and querying agents that the Node trusts.
PKCS12 and JKS keystore formats are supported