Low-carbon desktop computing

1. Building the FiDo software on a Windows-based server with a pre-configured Tomcat bundle.

This section of the guide aims to help you install the FiDo software on a Windows operating system from a pre-configured Tomcat bundle. The operating system used in this tutorial is Windows Vista. One of the important steps to accommodate the FiDo software on the network is to apply for X.509 certificate (which usually takes a few days!)

1.1. Installing Java SDK

The FiDo software requires the Java Runtime Environment (JRE) installed on the Windows computer. The relevant package can be downloaded from the address:
http://java.com/en/download/

By default the JRE installs in C:\Program Files\Java\jre6\

In order for Java to work properly, an environment variable has to be setup. In order to do it, go to Control Panel -> System -> Advanced tab and click the Environment Variables button.
System Properties

On the following screen add new System Variable JRE_HOME pointing to C:\Program Files\Java\jre6:
System Properties

1.2. Installing required libraries

The FiDo software requires additional libraries to capture network packets: WinPcap and Jpcap. To download latest versions, visit the following pages:
http://www.winpcap.org.
http://netresearch.ics.uci.edu/kfujii/jpcap/doc/download.html

1.3. Installing the FiDo software

Once the libraries are installed properly, you can proceed to install the FiDo software. The package can be downloaded from the following address:
http://lowcarbonict.googlecode.com/files/wol-gateway-tomcat.tar.gz

It's supplied as a ZIP archive and can be extracted to any folder. For the purpose of this guide, we assume the folder D:\gateway-tomcat\ holds the extracted files.

To start the Tomcat server, run the following file:
D:\gateway-tomcat\bin\startup.bat
To stop it, run:
D:\gateway-tomcat\bin\shutdown.bat

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

If a page opens, Tomcat works properly.
Tomcat http test page

Once the web page opens, the web browser will warn you about using a fake certificate (created for test purposes only). To get your FiDo software to work, you have to replace the fake certificate with a legitimate one and to tell it to accept connections from the Central WOL Server.
To test, that the FiDo software was loaded properly, go to https://localhost:8443/cwolf-gateway/services to check out the available services on the server. You should be able to see a service called "ProxyServer" that includes three methods:
  • sendMagicPacket
  • getSubnetStatus
  • sendARPRequest
These are the web services and methods available on the FiDo software , to be called by WOL central server. The correct display of this page indicates your FiDo software service has been started successfully.

1.4. Establishing secure communication with Central Server

The FiDo software needs to know which central server it should trust. The authentication with the central wake on LAN (WOL) server and central power management monitor (PMM) server is done by examining the signature of each request from the FiDo software. The set of trusted machines by a particular FiDo software installation is stored in a Java truststore:
D:\gateway-tomcat\webapps\cwolf-gateway\WEB-INF\trustedClientCerts.jks

To make your FiDo software 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 a gateway server is approved. Please contact 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: D:\gateway-tomcat\webapps\cwolf-gateway\WEB-INF\classes\crypto.properties accordingly.

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

1.5. Installing GlobalSign certificate

The Tomcat package you downloaded and deployed is using a test certificate issued by low-carbon ICT Certificate Authority (CA). You are required to replace this with a GlobalSign issued certificate.

The test certificate keystore is stored here: D:\gateway-tomcat\conf\sample.jks.

Tomcat supports three kinds of keystores: JKS, PKCS12 and PKCS11. We recommend choosing PKCS12 because it appears to be most convenient option for majority of our users.

We would assume you have applied for a certificate from UK JANET Global Sign CA, and have in hand both the certificate and private key in separated PEM files, public.pem and private.pem.

Creating CA certificate bundle.

It's essential to import the full CA chain with your certificate into the keystore, because the central server is configured to trust only the root certificate of a given CA. We can create a CA certificate bundle file ca_bundle.crt containing all the CA certificates:

type ct_root.pem sureserverEDU.pem > ca_bundle.crt

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

Creating new PKCS12 keystore to be used with Tomcat

In order to complete the following step, you have to make sure OpenSSL is running on the FiDo software. It comes preinstalled on most Linux systems and can be downloaded otherwise from the following website: http://www.openssl.org/related/binaries.html. To create a keystore use the command:

openssl pkcs12 -export -in public.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 and wol-gateway is the alias of the key in the store. You will also be prompted to set a password to procect the keystore. The password has to be updated in the Tomcat configuration file in step (3).

To check if the full certificate chain has been imported succesfully, issue the command:

keytool -v -list -keystore tomcat.p12 -storetype pkcs12

Updating server.xml of Tomcat and restarting the server

The newly generated PKCS12 keystore has to be configured in the server.xml file of Tomcat. A sample configuration is as follows:

<Connector port="8443" minSpareThreads="5" maxSpareThreads="75" enableLookups="true" disableUploadTimeout="true" acceptCount="100" maxThreads="200" debug="0" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" SSLEnabled="true" keystoreFile="conf/tomcat.p12" keystorePass="storepassword" keystoreType="pkcs12" keyAlias="wol-gateway"/>

1.6. Enabling the monitoring service

The FiDo software is more than a proxy to dispatch wake on LAN (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: D:\gateway-tomcat\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 monitoring service is enabled, it is required to update the "ProxyServerIpAddress" and "NetMask" parameter with the IP address and netmask of your FiDo software. These parameters are used by the FiDo software to figure out the size of your local subnet. For example, if the FiDo software 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