The WOL Service

1. Building the FiDo software on Linux (from source).

This section of the guide aims to help you install the FiDo software on a Linux operating system from source. The operating system used in this tutorial is CentOS 5, commands and paths used may vary depending on the distribution in place. Some of the tasks in this guide require root privileges (marked accordingly). The process takes approximately 20-40 minutes to complete. Please note: applying for a globalsign certificate may take up to 2 days - once you have decided on the DNS name you can apply for a certificate here: https://wiki.oucs.ox.ac.uk/itss/CertificateService.

1.1. Installing Java SDK

The FiDo sofwtare requires the Java Software Development Kit to be installed. The relevant package can be downloaded from:http://java.sun.com/javase/downloads/index.jsp. It is essential, to download the JDK, not JRE.

To install the Java binary package, you use the command:
[gw@localhost gw]$ sh jdk-6u13-linux.i586.bin

After it's been installed, the bashrc file has to be updated with relevant system variables to be used by Java:
export JAVA_HOME=~/jdk1.6.0_13
export PATH=$JAVA_HOME/bin:$PATH

To check if the correct version of Java is installed, issue the commands:
[gw@localhost gw]$ which java[gw@localhost gw]$ java -version

For the environment variables to take effect, log off and on.

1.2. Installing Tomcat

Apache Tomcat is a servlet container providing Java HTTP web server environment for Java code to run. Tomcat can work independently to your existing WWW server. It's available to download from here:
http://tomcat.apache.org/download-60.cgi

To uncompress the tar archive, use the command:
[gw@localhost gw]$ tar zxvf apache-tomcat-6.0.18.tar.gz

Tomcat can be started using the following command:
[gw@localhost gw]$ cd ~/apache-tomcat-6.0.18/bin
[gw@localhost gw]$ ./startup.sh

To check, that Tomcat has been properly installed, open the following address in your browser:
http://localhost:8080

If a page opens, Tomcat works properly.

Tomcat http test page

1.3. Installing required libraries

The FiDo software also requires the jpcap and libpcap libraries to capture network packets which can be downloaded from:
http://www.tcpdump.org/
http://netresearch.ics.uci.edu/kfujii/jpcap/doc/download.html

Please note, that root access and a gcc (incl gcc-java) compiler are required to install the library. You may also need to install the following to satisfy the dependencies:
[gw@localhost gw]# yum install flex
[gw@localhost gw]# yum install bison
[gw@localhost gw]# yum install byacc
[gw@localhost gw]# yum install gcc

To install the libraries, issue the following commands:
[gw@localhost gw]# tar zxvf libpcap-1.0.0.tar.gz
[gw@localhost libpcap-1.0.0]# cd ~/libpcap-1.0.0
[gw@localhost libpcap-1.0.0]# ./configure –prefix=/usr
[gw@localhost libpcap-1.0.0]# make
[gw@localhost libpcap-1.0.0]# sudo make install

The commands above will install newly downloaded libpcap to /usr/local/libpcap-1.0.0. In principle you can install it to any location, but it's better not to install it under /usr because that's where system libraries are located. After these steps, you should be able to see a new directory called "libpcap-1.0.0" created under your /usr/local directory, with "include", "lib" and "share" subdirectories.

Now it's time to install jpcap:

[gw@localhost gw]# tar zxvf jpcap-0.7.tar.gz
[gw@localhost gw]# cd ~/jpcap-0.7/src/c

Before compiling the code, use your favorite text editor to modify Makefile to the location where libpcap has been installed. This is done by modifying the value of PCAP_INCLUDE in Makefile:

PCAP_INCLUDE = /usr/local/libpcap-1.0.0/include

Save the editing and set environment variable LIBRARY_PATH so that the newly installed libpcap static libary can be found by gcc:

[gw@localhost gw]#export LIBRARY_PATH=/usr/local/libpcap-1.0.0/lib

Finally, compile the code using:
[gw@localhost jpcap-0.7/src/c]# make

Now copy the compiled libjpcap.so file to ~$JAVA_HOME/jre/lib/i386.

It's important to use the JAVA installed at ~/jdk1.6.0_13 with your tomcat server, because only this JAVA instance has libjpcap.so installed. It might occur, that the system has one or more JAVA instances already installed. In this case, we can explicitly tell Tomcat server which JAVA instance to use by setting JAVA_HOME environment variable. If you are using bash as root, one easy of way of doing this is to add the following line into your ~/.bashrc file:

export JAVA_HOME=~/jdk1.6.0_13

After you saved the file, for changes to apply you need to log out and then log back in.
If you use startup scripts to automatically start Tomcat service during system boot, once again please make sure the correct JAVA instance is used in the script.

1.4. Installing the FiDo software

Once the libraries are installed properly, install ant using the command:
[gw@localhost gw]$ yum install ant

Then install subversion:
[gw@localhost gw]$ yum install subversion

Now it's time to install the cwolf software from the subversion repository:
[gw@localhost gw]$ svn checkout https://svn.oucs.ox.ac.uk/projects/lcict/cwolf/trunk/ ./cwolf

The next step is to prepare the gateway software:
[gw@localhost gw]$ ant build-gateway
[gw@localhost gw]$ cp -r ~/cwolf/build/dist/ ~/apache-tomcat-6.0.18/webapps/

We also have to copy the sample gateway java keystore to the Tomcat folder:
[gw@localhost gw]$ cp ~/cwolf/certs/sample-gateway-tomcat.jks ~/apache-tomcat-6.0.18/conf/

1.5. Establishing secure communication with Central Server

The FiDo server needs to know which central server to trust. The authentication to central WOL server and central monitor server is done by examining the signature of each request on the gateway server. The set of trusted machines by a particular FiDo software installation is stored in a Java truststore:
~/apache-tomcat-6.0.18/webapps/cwolf-gateway/WEB-INF/trustedClientCerts.jks

To make your FiDo software installation work with a central server, you need to obtain the central server certificate (public key only). It shall be given out when the application to host your FiDo software is approved. Please contract greenit@oucs.ox.ac.uk if you don't have this certificate.

Suppose you have the certificate of the central server in PEM format - central_server_certificate.pem, you can use JAVA keytool to add this certificate into your trust list:
keytool -import -keystore trustedClientCerts.jks -trustcacerts -file central_server_certificate.pem -alias centralservername

You will be asked for the password of the truststore when issuing this command. The default password is "treasure". It's recommended to change the keystore password using the following command:
keytool -storepasswd -new new_keystore_password -keystore trustedClientCerts.jks

To list the contents of the keystore and delete the remaining test public keys, use these commands:
keytool -list -keystore trustedClientCerts.jks
keytool -delete -alias "test_key" -keystore trustedClientCerts.jks

If you decided to change the keystore password, you have to update the following entry afterwards: org.apache.ws.security.crypto.merlin.keystore.password in the file: ~/apache-tomcat-6.0.18/webapps/cwolf-gateway/WEB-INF/classes/crypto.properties accordingly.

For changes to apply, a restart of Tomcat is required.

1.6. Installing TERENA (JANET) certificate

The Tomcat package you downloaded and deployed is using a test certificate issued by the Low Carbon ICT Certificate Authority (CA). You must replace this with a Janet-issued certificate. Use the procedure detailed on the ITSS wiki at https://wiki.oucs.ox.ac.uk/itss/CertificateService to obtain a TERENA certificate.

1.6.1. Generating Java keystore

The following procedure assumes that you have a certificate from JANET called cert.pem and the private key used to sign the request, private.pem. You will also need the chaining certificates, TERENASSLCA.crt, UTNAddTrustServer_CA.crt and AddTrustExternalCARoot.crt.

1.Create a CA certificate bundle file ca_bundle.crt containing all the CA certificates:
cat TERENASSLCA.crt UTNAddTrustServer_CA.crt AddTrustExternalCARoot.crt > ca_bundle.crt

In case you had problems with creating the CA bundle, download a prepared one from here.

2.Create a new PKCS12 keystore to use with Tomcat:
openssl pkcs12 -export -in cert.pem -inkey private.pem -out tomcat.p12 -name wol-gateway -CAfile ca_bundle.crt -caname ca_chain -chain

where tomcat.p12 is the new PKCS12 keystore. You will also be prompted to set a password to protect the keystore.

3.To check if the full certificate chain has been imported successfully, issue the command:
keytool -v -list -keystore tomcat.p12 -storetype pkcs12

Finally, move the tomcat.p12 keystore into the directory /etc/tomcat6/.

1.6.2. Updating Tomcat configuration file server.xml and restarting the server

Next, the keystore generated in the previous step has to be configured in Tomcat's server.xml file. This file can usually be found at:
/etc/tomcat6/server.xml

Open the file up in a text editor and look for the SSL connector section. Edit it so that it reads as follows:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="/etc/tomcat6/tomcat.p12" keystoreType="pkcs12" keystoreAlias="wol-gateway" keystorePass="<store_password>"

Make sure for the keystorePass parameter you enter the password as set in the previous step (Section 1.5.1 step 2), but otherwise it should read exactly as above.

1.6.3.

Restart Tomcat using the following command:

/etc/init.d/tomcat6 restart
and you should be able to visit the following URL to check that the FiDo software is running correctly:https://server.unit.ox.ac.uk:8443/cwolf-gateway/services

1.6.4. Enabling the monitoring service

The FiDo software is more than a proxy to dispatch WOL packets to a local subnet. It can also act as a subnet scanning agent to collect your local subnet status. Although this feature has been disabled by default, you can easily enable it by edit your web application description file: ~/apache-tomcat-6.0.18/webapps/cwolf-gateway/WEB-INF/web.xml. At the top of the file, find the servlet parameter "MonitorSwitchOn" and change its value from "false" to "true". When the power management monitoring service is enabled, it is required to update the "ProxyServerIpAddress" and "NetMask" parameter with the IP address and netmask of your gateway server. These parameters are used by the gateway software to figure out the size of your local subnet. For example, if the gateway server IP address is 192.168.1.1, and the netmask is 255.255.255.0, you should update your web.xml to something like this:

<servlet> <servlet-name>ProxyServlet</servlet-name> <servlet-class>uk.ac.ox.oerc.wol.core.ProxyServer</servlet-class> <load-on-startup>1</load-on-startup> <init-param> <param-name>MonitorSwitchOn</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>ProxyServerIpAddress</param-name> <param-value>192.168.1.1</param-value> </init-param> <init-param> <param-name>NetMask</param-name> <param-value>255.255.255.0</param-value> </init-param> </servlet>

Up: Contents