Intended Audience:
Technical staff of all levels should be able to configure this web application.
Administration experience with Tomcat/MySQL is assumed.
Prerequisites:
Java: JDK 1.5
URL: http://java.sun.com/javase/downloads/index_jdk5.jsp
Recommend: /opt/java
App Server: Tomcat 5.5
URL: http://tomcat.apache.org/download-55.cgi
Recommend: /opt/tomcat
Database: MySQL5
URL: http://dev.mysql.com/downloads/mysql/5.0.html#downloads
Recommend: /opt/mysql
PSL Modules Overview
* SPIN Tools
* ETL
* Leaf
* Query Interface
$ unzip vsl-dist-1.3.4.1-dist.zip
DEPLOY SPIN TOOLS
dist$ chmod +x *.sh
dist$ ./deploy-spin-tools.sh
DEPLOY LEAF NODE
dist $ ./deploy-vsl-leaf.sh
Defaults
peerName = dns of your machine
queryType = VSLQueryAction
className = org.spin.node.leaf.VSLQueryAction
QUERYTOOL SETUP
dist$ ./deploy-vsl-querytool.sh
DEFAULTS
tools$ ./ConfigWizard.sh agent
Configuring module 'agent'
peergroup (default 'Local')
= vsl
broadcaster: (default 'https://localhost:8080/vsl-leaf/services/Broadcaster')
=
cache callback: (default 'https://localhost:8080/querytool/services/Aggregator')
=
max wait time (ttl) (default '20000')
=
number of expected nodes (0=any) (default '0')
=
use remote cache? (default 'true')
= false
Writing file /opt/spin/main/conf/agent.xml
SUPERNODE SETUP
dist$ ./deploy-vsl-supernode.sh
Cache Defaults
tools$ ./ConfigWizard.sh cache
Configuring module 'cache'
TTL: (default '15000')
=
Threshold: (default '3')
=
Writing file /opt/spin/main/conf/cache.xml
Routing Table Defaults
tools$ ./ConfigWizard.sh routingtable
Add a Peer Group? (default 'false')
= true
Peer Group Name = vsl
Add a Peer to Peer Group 'vsl'? (default 'true')
= true
URL: = https://localhost/vsl-leaf/services/QueryHandler
Add a Peer to Peer Group 'vsl'? (default 'true')
= false
Add a Peer Group? (default 'false')
= false
Writing file /opt/spin/main/conf/routingtable.xml]
ETL Setup
dist$ ./deploy-vsl-etl.sh
Defaults See VSL-ETL-User-Guide.doc
SSL Certificates
All SPIN Communication is done via SSL. Each peer has its own certificate, and each peer sending a message to another peer (submission or query or reply) needs to have imported that end peer's certificate.
The certificates are self-generated using the script SPINCertificate[.sh|.bat] which should be edited for each peer's local settings.
To generate a peer's private and public keys and import other peers' certificates:
- Edit the SPINCertificate script and set the following variables to your local settings:
SERVERNAME (fully qualified machine name or IP address)
INSTITUTION (e.g. Brigham And Women's Hospital)
- You may also change the variables KEYSTORE and PASSWORD.
- Run the script with:
SPINCertificate -generate
This will generate a file named spin.keystore, which holds your private key, and your certificate in a file named your.server.name.edu.cer. - To import the certificate from another peer (e.g. vsl-bwh.partners.org), run the script with:
SPINCertificate.sh -import vsl-bwh-partners.org
Run the ConfigWizard to setup the global properties for the keystore
$./ConfigWizard.sh keystore
@font-face
@font-face
@font-face
p.MsoNormal, li.MsoNormal, div.MsoNormal
p.MsoHeader, li.MsoHeader, div.MsoHeader
a:link, span.MsoHyperlink
a:visited, span.MsoHyperlinkFollowed
code
span.HeaderChar
div.Section1
Tomcat SSL setup
Official SSL howto guide:
http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html
Setting the keystore file location and password:
keystoreFile Add this attribute if the keystore file you created is not in the default place that Tomcat expects (a file named .keystore in the user home directory under which Tomcat is running). You can specify an absolute pathname, or a relative pathname that is resolved against the $CATALINA_BASE environment variable. keystorePass Add this element if you used a different keystore (and Certificate) password than the one Tomcat expects (changeit).
Example:
<!- Define a SSL HTTP/1.1 Connector on port 8443 ->
<Connector port="8080"
scheme="https" secure="true" clientAuth="false" sslProtocol="TLS"
keystoreFile="/opt/spin/main/conf/spin.keystore"
keystorePass="spinkeystore"/>
Logging
Log4J
SPIN uses log4j to set the logging level (DEBUG, INFO, WARN, ERROR, FATAL) and set the output targets (FILE, CONSOLE).
Log4J is described in detail here: http://logging.apache.org/log4j/docs/ , though most users will only need to set the logging level and/or the location of the log file.
Log4j logging levels are hierarchal, meaning that an ERROR message will also be logged if the level is set to DEBUG. The relationship between the levels is as follows:
DEBUG > INFO > WARN > ERROR >FATAL
Log4J also allows multiple appender types such as CONSOLE or FILE or even SMTP.
Defaults
By default, VSL will use the log4j configuration file located in /opt/spin/main/conf
This lo4j configuration will log all WARN, ERROR, or FATAL level messages to Tomcat STDOUT.
Any SPIN messaging related classes will log at the INFO level, also to Tomcat STDOUT.