University of Oxford wake on LAN service

Installation guide

This guide provides detailed information on how to install the University of Oxford wake on LAN (WOL) software.

The WOL software was written by [http://www.oerc.ox.ac.uk/people/kang-tang Kang Tang] between late 2007 and early 2009 as part of the [http://projects.oucs.ox.ac.uk/lowcarbonict/ Low Carbon ICT project]. The work was funded by by the [http://www.jisc.ac.uk/whatwedo/programmes/exemplars.aspx JISC Institutional Exemplar Programme].

TableOfContents([2])

Introduction

This section provides a technical overview of the WOL service, as it has been implemented at the University of Oxford. The diagram below illustrates the main software components and how they communicate with each other:

attachment:wol-design-diagramv9.png

Registering and waking computers

Information about using the WOL service at is provided Oxford University Computing Services website: http://www.oucs.ox.ac.uk/wol/index.xml

Gateway servers

The gateway server performs two main functions:

  1. Broadcasts WOL "magic packets" within the subnet that it is installed. The gateway server broadcasts messages on request of the central WOL server which receives requests from the user who is logged into the WOL user interface.
  2. Sends ARP queries within the subnet that it is installed. This is performed when an end-user wants to register their computer. The WOL server sends the end-user's IP address, which is used to find the MAC address.

The number of gateway servers that are needed will be dependent on how an organisation has designed the underlying networked computing environment. Institutional networks are normally divided up into subnets for security reasons.

Since WOL "magic packets" are 'broadcast-type' traffic they cannot traverse subnets. This means that gateway servers need to be installed 'within' each subnet where computers are installed that require the WOL service. (There is no limit on the number of computers that a single gateway server can send magic packets to e.g. for a network with netmask of 255.255.254.0, one single gateway can easily manage up to 255 x 2 - 2 = 508 host computers).

Messages are sent securely to the gateway servers by the central WOL server through a system of signed digital certificates (e.g. X509).

Firewalls

It is important to make sure the relevant ports on firewalls are opened between your central server and department gateway servers, if there are any. By default, the central WOL server need access to port 8443 on each gateway server, but the port number is configurable on the gateway server.

Operation system

The software was developed and tested on Linux (CentOS4) OS , therefore Linux is strongly recommended for both central and gateway software. However, since they are implemented as standard java web applications within Tomcat 5.5, we could not see any reason why it would not work on a windows or Mac server environment that have Tomcat web server correctly installed.

Gateway software also requires the Pcap library to be installed before it can function correctly. Therefore if you decide to install gateway server on any system other than Linux, you will have to figure out how to install Pcap Library on your chosen operation system. This document will only cover the installation instructions on Red hat based Linux operation system. In addition, since Jpcap (Java api for packet capture) requires super-user privilege to access system network interface, you will need root privilege on the system used as gateway server.

Using the packaged database and user interface

The central WOL software comes packaged with a prototype database and web-based user interface.

The web-based user interface can be used to register computers and put them into groups so that they can be woken individually and as a cluster. As such the user interface web pages are used to interact with the database to maintain a store of groups, MAC addresses and gateway server details.

The package user interface and database will probably only serve to help organisations set up a prototype service to try out quickly. To provide a production-grade service the user interface will need to be protected by username so that only people with the correct permissions can register and wake computers. Also organisations may want to record additional details such as third-party services that are allowed to use the service.

The central wol software can be used without the packaged database and user interface. As such the software serves merely to communicate with gateway servers to wake machines and request ARP request to retrieve MAC address details.

Each organisation will need to decide how they integrate the WOL service registration data within their existing ICT systems.

Installing a Central WOL Server

Important note! The Central WOL Server will typically only need to be installed and maintained once within an organisation. At Oxford the central WOL server is maintained by the Computing Service (OUCS) for all departments and colleges to use. IT Support Staff in colleges and departments will normally not need to read this section!

Prerequisite

Some third party software need to be installed on central server system before you can successfully install and start the WoL central service.The dependencies for central server and gateway server are slightly different due to their different functionalists. Dependencies required by central server system are listed in this section. Please check installation guide for gateway server for gateway dependencies.

Java SDK 1.5+

Due to the fact that the software is written in Java, Java JRE 1.5+ is required. In addition, on the system where you want to build source from, java SDK 1.5+ is also required. The software has been tested against Java 1.5 and Java 1.6. You need to use same version of compiler and running environment for the application. E.g. If you have compiled the source using JDK 1.6, then make sure to use JRE 1.6 to start the tomcat server.

Apache Tomcat 5.5+

Apache Tomcat 5.5+ is required to host the central server. SSL support is also required, which means you will need a valid server certificate. For testing purpose, the package includes a sample JCE keystore files under ${cwolf}/certs directory: sample-wolserv-tomcat.jks. The keystore contains keys required by Tomcat to host HTTPS service. They were issued by a testing CA we set up for Low Carbon ICT Project and should only be used for internal testing. Feel free to setup your web server on any ports you prefer, however, we will assume default port 8443 is used throughout this document. For details on how to setup tomcat 5.5 with SSL support, you might want to have a look at,

http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html.

Apache Ant 1.6.5+

Apache Ant 1.6.5+ is only required on the system where you want to build the source code from.

BouncyCastle JCE provider

Due to the fact that the WSS4J API was extensively used in the software, which have heavy dependency on BouncyCastle JCE provider, you will need to enable the BouncyCastle as JCE provider for your Java Runtime Environment. To do this, on your central server simply add following line in your $JAVA_HOME/jre/lib/security/java.security file. 

security.provider.X=org.bouncycastle.jce.provider.BouncyCastleProvider

where 'X' should be replaced by a unique index number.

PostgreSQL 7.x +

As mentioned earlier, a database on central server is only required when you decide to setup a local database to store information about registered computers. Although this document assumes you are using PostgreSQL 7.4.19, we believe any other standard SQL relationship database should be working as well. The interactions between the central server and back-end database are done through Hibernate 3 API. Therefore in principle, all databases supported by Hibernate 3 should work with only configuration parameters changes.

Download the software

The latest version of the software can be downloaded from our project Subversion repository, which is located at:

https://svn.oucs.ox.ac.uk/projects/lcict/cwolf/trunk/

Use your favorite subversion client to checkout the project. For example, if you are using svn client tool shipped with Linux, you can use following command to check out the project into 'cwolf' in current directory, 

svn checkout https://svn.oucs.ox.ac.uk/projects/lcict/cwolf/trunk/ ./cwolf

In rest of the document, ${cwolf} will be used to represent the root directory of your newly checked out project.

Build the source

As mentioned in prerequisite section, to build the source code from source, you will need Apache Ant 1.6.5 +. Obviously you will need JDK installed as well. The lowest version we recommend for JDK is 1.5. The project build file build.xml is located under ${cwolf}. You might also want to have a look at build.properties under same directory, where you can set a few build parameters.

To build central server, go to ${cwolf} and type, 

ant build-central

The command will create a new web application named cwolf-central-x.x under ${cwolf}/build/dist, and generate a WAR archive under the same directory.

Similarly, to build gateway server, go to ${cwolf} and type, 

ant build-gateway

The command will create a new directory named as cwolf-gateway-x.x under ${cwolf}/build/dist and a WAR archive.

To build a sample client for testing purpose, go to ${cwolf} and type, 

ant build-sampleClient

This sample client is provided to test your WOL service after it has been successfully deployed.

If you want to build all three components of the package, just type, 

ant build-all

Finally, if you want to delete all the existing build and re-build everything, type 

ant clean

Install the Central WOL Server

Install the Webapp.

It should be straight forward to install central server webapp. on your system if you have already got a tomcat 5.5+ web server up and running. Firstly find cwolf-central-x.x.war from £{cwolf}/build/dist/ and rename it to cwolf-central.war, then copy cwolf-central.war to ${TOMCAT_HOME}/webapps, where ${TOMCAT_HOME} is the home directory for your Tomcat 5.5 installation.

If your tomcat is working properly, the archive will be automatically extracted under same directory after a few seconds. Now, open a browser on the central server system and go to, 

https://localhost:8443/cwolf-central/services

If this is your first time to install WOL Server, you are recommended to use the shipped testing keystore sample-wolserv-tomcat.jks to setup SSL on your tomcat for simplicity. Presumably you are using these testing keystores, now in your Firefox browser, you will see a page with title of "Secure Connection Failed". This is expected because your browser noticed the domain name of your server "localhost" is different than the DN subject of the certificate it retrieved from your Tomcat server. No need to worry about this since the shipped sample certificate is just for testing. Click the bottom link to add an exception. After a few clicks you should be able to see a page with a list of available web services on your server, including 'SecureWolService' with method 'sendWolRequest'.

To check the WSDL descriptions of the service, go to, 

https://localhost:8443/cwolf-central/services/SecureWolService?wsdl

Congratulations! You have now installed the central service webapp. on your system without database support. Unfortunately, We can not test the service with our sample client yet, which have to wait until at least one gateway server has been deployed.

Install central database (optional)

If you choose to install a local database on central server to store registration information, you can find the SQL scripts to install WOL database under directory ${cwolf}/WEB-INF/postgresql. Please check PostgreSQL online manual for instructions on how to create a new database, how to create new user and how to install a SQL script.

http://www.postgresql.org/docs/

After the database is successfully created and initialized, you will need to modify the hibernate engine configuration file 'hibernate.cfg.xml' under ${TOMCAT_HOME}/webapps/cwolf-central/WEB-INF/classes based on your own database schema and connection parameters. Normally, you will need to change the following section in 'hibernate.cfg.xml': 

    <property name="connection.url">jdbc:postgresql://hostname/dbname</property>
    <property name="connection.username">username</property>
    <property name="connection.driver_class">org.postgresql.Driver</property>
    <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>
    <property name="connection.password">passwd</property>

After you have done the changes, restart tomcat server and go to the testing registration page:

https://localhost:8443/cwolf-central/reg/

in order to register your first computer for wake up.

** This testing registration page doesn't work at this moment because it requires external WebAuth SSO support.

Installing a WOL Gateway Server

Prerequisite

Some third party software need to be installed on the gateway systems before you can successfully install and run the WoL software.The dependencies for central server and gateway server are slightly different due to their different functionalists. You will need following software installed on gateway systems.

Java SDK 1.5+

Java JRE 1.5+ is required on gateway servers. In addition, on the system where you want to build source from, java SDK 1.5 is also required.The software has been tested against Java 1.5 and Java 1.6. You need to use same version of compiler and running environment for the application. E.g. If you have compiled the source using JDK 1.6, then make sure to use JRE 1.6 to start the tomcat server.

Apache Tomcat 5.5+

Apache Tomcat 5.5+ is required by gateway server to host the gateway service. SSL support is also required, which means you will need valid server certificates for both them. For testing purpose, the package includes a sample JCE keystore files under ${cwolf}/certs directory: sample-gateway-tomcat.jks. The keystore contains keys required by Tomcat to host HTTPS service. They were issued by a testing CA we set up for Low Carbon ICT Project and should only be used for internal testing. Feel free to setup your web server on any ports you prefer, however, we will assume default port 8443 is used throughout this document.

For details on how to setup tomcat 5.5 with SSL support, please check,

http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html.

Apache Ant 1.6.5+

Apache Ant 1.6.5+ is only required on the system where you want to build the source code from.

Jpcap 0.7 and libpcap 0.9.4+

Jpcap 0.7 and libpcap 0.9.4+ are required on gateway servers to capture and send network packets through system network interface from within a JVM. For a detailed instructions on how to install these on your system, see [#jpcap Install Jpcap7 and libpcap 0.9.4+] in the Appendix section.

Download the software

The latest version of the software can be downloaded from our project Subversion repository, which is located at:

https://svn.oucs.ox.ac.uk/projects/lcict/cwolf/trunk/

Use your favorite subversion client to checkout the project called 'cwolf'. If you are using svn client tool shipped with Linux, use following command to check out the project into 'cwolf' in current directory, 

svn checkout https://svn.oucs.ox.ac.uk/projects/lcict/cwolf/trunk/ ./cwolf

In rest of the document, ${cwolf} will be used to represent the root directory of your newly checked out project.

Build the source

As mentioned in prerequisite section, to build the source code from source, you will need Apache Ant 1.6.5 +. Obviously you will need JDK installed as well. The lowest version we recommend for JDK is 1.5. The project build file build.xml is located under ${cwolf}. You might also want to have a look at build.properties under same directory, where you can set a few build parameters.

To build a gateway server, go to ${cwolf} and type, 

ant build-gateway

The command will create a new directory named as cwolf-gateway-x.x under ${cwolf}/build/dist and a WAR archive.

If you want to delete all the existing build before re-build everything, type 

ant clean

For more options supported by the build.xml, please check 'Build the source' section for central server.

Install Gateway server

Gateway Server Location

It is important to chose a suitable location for your gateway server. Although this has nothing to do with the WoL software itself, it will certainly affect whether your service will work correctly. Before setting up the gateway, you need to identify the computers that the users of the service will be interested to wake up. Usually this can be your office network where staff or students desktop computers are located. If this is the case, you gateway server will have to be physically located within the same network subnet as rest of the office desktop computers. For a bigger department, its office network might include multiple subnets, if this is the case, you will have to install a separate gateway server for each of them. As mentioned before this is because wake-on-lan packets are broadcast traffic. Normally broadcast does not transverse between different subnets unless your routers have been configured to allow this.

Install Gateway Webapp

Just as how you install central server webapp, after building source code for gateway server, go to ${cwolf}/build/dist to find cwolf-gateway-x.x.war and rename it to cwolf-gateway.war, or whatever you prefer, then copy cwolf-gateway.war to {TOMCAT_HOME}/webapps directory, on the server that has been chosen as a gateway.

Presumably you are using sample-gateway-tomcat.jks shipped with the package as the keystore for your tomcat SSL, open a browser on the gateway server and go to, 

https://localhost:8443/cwolf-gateway/services

to check your newly installed gateway service. Again, you will see "Secure Connection Failed" when you access the page from your browser at first time, click to add an exception and pass yourself through. You should be able to see a list of available services including 'ProxyServer'.

To check the WSDL descriptions of the service, go to, 

https://localhost:8443/cwolf-gateway/services/ProxyServer?wsdl

So far, you have installed WOL gateway server webapp on your system. However, before central server and gateway server can work together to wake up your computer,some post configuration has to be done.

Install gateway server as a VMware appliance

To ease the deployment of WoL gateway, especially in instituions where a functional VMware framework is already in place, we also provided an VMware appliance version of WoL gateway system.

More information to be added in future.

Post Configuration

Make the sample service work

In order to test the central server and gateway server, we are going to send a WOL request to WOL central server from our sample client. The request will then be processed and forwarded to our newly installed gateway server to wake up a computer which we believe is located in the same subnet.

The information we will need to make this work includes:

To tell the system about this information, you might need to update following configuration files.

WolServerConfig.xml

We need to tell central server where the gateway service is located. This is done by modifying WolServerConfig.xml under ${TOMCAT_HOME}/webapps/cwolf-central/WEB-INF on your central server. For example,if the IP address for gateway server is 192.168.1.1, you can add a new ProxyServer element with its ip element and url element set as following: 

<ProxyServer>
<!--Make sure to put IP of your gateway server here, domain name doesn't work! -->
<ip>192.168.1.1</ip>
<url>https://192.168.1.1:8443/cwolf-gateway/services/ProxyServer</url>
<port>9</port>
<broadcast>255.255.255.255</broadcast>
<name>Testing Gateway</name>
<location>Oxford e-Research Centre</location>
<description>none</description>
<contact>kang.tang@oerc.ox.ac.uk</contact>
</ProxyServer>

With this configuration in place, central server is now aware of the existence of gateway server and also knows how to access the service. Restart tomcat to make new configuration take effect.

web.xml

Since both central server and gateway server are deployed as web application inside tomcat, each of them have a deployment descriptor file. You can find them under ${CWoLF}/webapp-central and {CWoLF}/webapp-gateway. You do not change anything in either of them to make the sample service work, unless you have changed the locations or file names of your keystores or configuration files. There is a option function embedded within the gateway server, the subnet scanning function. It has been disabled by default and unless you need this feature, nothing need to be changed.

However, the changes to web.xml are mandatory when you are ready to configure the system to use in a real environment, where real certificates are used. For more details about configuration of deployment descriptor, see section "Adapt to your real environment".

sampleclient.sh

To call WOL Service from our sample client, we have to tell the sampleclient where the WOL service is. If you have already build sample client from source, you can now located the samp client application under ${cwolf}/build/dist/sampleclient.

If the hostname for our central server is host1.oerc.ox.ac.uk, then the web service URL for central WOL service will be something like: 

https://host1.oerc.ox.ac.uk:8443/cwolf-central/services/SecureWolService

Go to ${sampleclient}/bin/sampleclient.sh and update WOL_WS_URL with above URL at almost the end of the line. Also inside sampleclient.sh, update MAC_ADDR section with the MAC address of the computer you want to wake up; update GATEWAY_ADDR section with the IP address of your gateway server. Note: It is crucial to use IP address of gateway server as domain name is not supported in current version.

That is really all you need to do. Now go to ${sampleclient}/bin and run the sample client to wake up your computer by typing, 

sh ./sampleclient.sh

Adapt to your real environment

The purpose of the simple sample service is to give you a quick feeling about the whole WOL service framework. It should not , however, be used in any real network environment as a permanent service, because the testing credentials invalidate any security protection of the service.

Before you can deploy the service in a real environment, you will need valid host certificates issued by a proper Certificate Authority, for both the central server and each gateway server. Depending on the format of the certificates, normally you will need convert format of the certificates issued by your CA to a format that is accepted by Java Cryptography Extension (JCE) API, e.g. JKS. The detailed instructions on how to prepare your certificates into JKS format to be used by CWoLF can be found in Appendix section "Prepare Certificates for CWoLF".

Central server

On your central server, you can find four keystore files under {webapp}/WEB-INF:

All of them need to be replaced with your newly generated keystores.

  1. lowCabon-ca.jks should be replaced by the truststore containing (public) certificate of the root CA who issued the certificates for your gateway server. If you have multiple gateway servers that are using certificate issued by different CA, you need to put multiple CA in this truststore. After the replacement is made, make sure to update your web.xml under {webapp}/WEB-INF to use the new truststore and password: 

    ........
    </init-param>
        <init-param>
        <param-name>javax.net.ssl.trustStore</param-name>
        <param-value>/WEB-INF/lowCarbon-ca.jks</param-value>
    </init-param>
        <init-param>
        <param-name>javax.net.ssl.trustStorePassword</param-name>
        <param-value>security</param-value>
    </init-param>
   </servlet>
   ........
  1. sample-wolserv.jks should be replaced by the keystore containing your server credential ( both public and private key). Make sure to set the key password and keystore password different when creating your own keystore. Now update file "central.client.crypto.properties" under {webapp}/WEB-INF/classes: 

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=keystorepasswd
org.apache.ws.security.crypto.merlin.file=../yourserverkeystore.jks

The key password is loaded from a password callback class. By default, the class is uk.ac.ox.oerc.wol.sample.SamplePWCallback, which simply uses a hardcoded password 'treasure'. You should implement your own callback class and update client-config.wsdd under {webapp}/WEB-INF to use your own password callback: 

<deployment xmlns="http://xml.apache.org/axis/wsdd/"
        xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
        <transport name="http"
                pivot="java:org.apache.axis.transport.http.HTTPSender" />
        <globalConfiguration>
                <requestFlow>
                        <handler
                                type="java:org.apache.ws.axis.security.WSDoAllSender">
                                <parameter name="action" value="Signature" />
                                <parameter name="user" value="sample-wolserv" />
                                <parameter name="passwordCallbackClass"
                                        value="uk.ac.ox.oerc.wol.sample.SamplePWCallback" />
                                <parameter name="signatureKeyIdentifier"
                                        value="DirectReference" />
                                <parameter name="signaturePropFile"
                                        value="central.client.crypto.properties" />
                        </handler>
                </requestFlow>
        </globalConfiguration>
</deployment>
  1. sample-wolserv-tomcat.jks is server keystore used by tomcat server. It contains same credential as sample-wolserv.jks. The only difference is, sample-wolserv-tomcat use same password for key and keystore while sample-wolserv use different ones. The reason is because Tomcat web server only support keystore where key password and keystore password are same. After the change is made, make sure to update server.xml for your tomcat to use your real server keystore.
  2. trustedClientCerts.jks should be replaced by the truststore containing the certificates what your central would like to trust. Before a web service client being allowed to call WOL service, the server need to get hold of the public certificate of the client and import it into its trustedClientCerts.jks. If you prefer to use a different name for the truststore, update crypto.properties under {webapp}/WEB-INF: 

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=keystorepassword
org.apache.ws.security.crypto.merlin.file=../yourtruststore.jks

  1. Obviously you will also need to update WolServerConfig.xml under {webapp}/WEB-INF to add information of your gateway server.

Gateway server

On gateway server, you will see three keystore files under {webapp}/WEB-INF:

Just as what you did on central server, you need to replace these keystores and update configuration file {webapp}/WEB-INF/crypto.properties to use your new keystore or truststore.

WOL client

The sample web service client use two keystores:

Also, you might need to update test-client-config.wsdd and client.crypto.properties under {sampleclient}/etc to use your own keystores.

Integrate with non-webservice client

The central server not only provides standard web service interface for its clients, but also provide HTTP Get interface to non-webservice client. Although web services messages protected by WS-Security are highly secure, sometime it can be difficult to implement WS-Security based security. For example, the programming environment of the client might not have very good support to WS-security API, it could be impractical and non-efficient to require client developer to implement WS-Security API with legacy code. The HTTP Get interface is by default disabled. To enable this, you need to modify your web deployment descriptor on the central server: 

    <!--
    </servlet-mapping>
        <servlet>
        <servlet-name>WoLRegServlet</servlet-name>
        <servlet-class>uk.ac.ox.oerc.wol.reg.servlets.WoLRegServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>WoLRegServlet</servlet-name>
        <url-pattern>/reg/servlets/*</url-pattern>
    </servlet-mapping>
     -->

Just uncomment above configuration in the web.xml to enable servlet WoLRegServlet. The servlet will respond to any requests that target at /reg/servlets/*. For example, to wake up a computer with MAC address 00:11:22:33:44:55:66 through gateway server 192.168.1.1, try calling, 

https://localhost/cwolf-central/reg/servlets/WakeHostService?macaddr=00:11:22:33:44:55:66&proxyaddr=192.168.1.1

You might want to replace 'localhost' with the domain name of your central server unless you are calling from itself.The command specifies desired action as 'WakeHostService', and use 'macaddr' and 'proxyaddr' paramters to specify target MAC address and responsible Gateway IP address.

Similarly, to call the central server to find out the MAC address for a given IP host 10.10.1.1, try calling, 

https://localhost/cwolf-central/reg/servlets/GetMac?ipaddr=10.10.1.1

The returned message will be in format of XML.

Before enabling this servlet, you need to be aware that the service is not protected by any means. There is no authentication nor authorization of any sorts being implemented with the servlet because it assumes that there is already external security mechanism in place, such as your campus Single-Sign-On framework, or basic security based on your web server, etc.

Integrate with external single sign-on infrastructure

When deploying WOL service within an organisation's network it may be possible to integrate with an existing single sign-on (SSO) infrastucture. For example, in Oxford University, authentication of users is provided through WebAuth and authentication between servers is achieved though Kerberos. Kerberos based authentication is very easy to implement from the aspect of application developer, although it requires both the server and client are within same trusted 'domain'.

You are recommended to take advantage of your existing security infrastructure wherever possible. The remote HTTP Get interface provided by WOL server does not come with authentication so has to be protected by some sort of external security mechanism.

The authentication for web service interface is done through WS-Security, which gives you the freedom of deploying its client from either within the campus network, or from outside world.

The diagram below illustrates how the WOL service has been integrated within the existing SSO infrastructure at Oxford University. The diagram shows how the web-based user interface for registering and waking computers is protected by WebAuth. This allows end users and ICT managers to access the pages securely, and since WebAuth also provides a limited form of authorisation it also allows the service to give more functionality to ICT managers e.g. registering many computers within a department. Since the user interface builds on the existing registration service database then it is easy to extend the database to include mappings between users and MAC addresses.

The user interface communicates with the central service through kerberos-based authentication. The central service communicates with the gateway servers via signed SOAP messages .

attachment:wol-design-diagramv9.png

Power Monitoring Service

The power monitoring service is an optional feature that has been integrated with gateway server, and is disabled by default.

For more details about the monitoring service...

Appendices

Anchor(jpcap)

Install Jpcap7 and libpcap 0.9.4+

The libpcap library comes with older linux version such as SL4 is 0.8.x and has to be updated to newer version before jpcap can work properly. Since the new version of libpcap has not been included into yum repository of SL4 at the time when this document was written, we have to build libpcap from source and install it manually.

To do this:

1) remove libpcap 0.8.x if has been installed on a older system

Normally, following packages will also be removed due to dependencies: 

 ppp
 rp-pppoe
 wvdial

No worries, it's ok to remove them unless you need ASDL or moden connections.

2) download source packages of libpcap 0.9.8 from

http://www.sfr-fresh.com/unix/misc/libpcap-0.9.8.tar.gz/

3) go into the directory where libpcap is extracted: 

$./configure --prefix=/usr
$make
$sudo make install

4) Download and unzip jpcap-0.7 from Jpcap website. Go to jpcap-0.7/src/c and run, 

$make

This will compile the source and generate a new lib file libjpcap.so.

5) As root user, copy the generated libjpcap.so to $JAVA_HOME/jre/lib/i386. It's important to copy into the JRE instance for root if you have multiple JRE installed because the execution of jpcap requires root privilege.

6) Copy jpcap.jar under jpcap-0.7/lib to $CLASSPATH before run any java program. In our case since it is web applications hosted by Tomcat server, we can simply put jpcap.jar under $TOMCAT_HOME/common/lib.

7) As root user, start tomcat server that hosts your web application. It's a 'MUST' to start tomcat using root because Jpcap requires root permission to access your system network interface.

Prepare Certificates for CWoLF

The security of CWoLF is based on WS-Security and SSL, which requires public and private key-pair for signing, encryption, decryption, etc. The key pair usually exists in form of X.509 certificate, which means in lot of situations, you will have to deal with certificates. This can be very frustrating for users who do not have much experience with certificates based security. This chapter describes the steps required to prepare the certificates issued by Certificate Authority for CWoLF.

Prepare private keystore

A private key is required for signing and encrypting, and normally they are stored in a passphase protected repository file ,'keystore'. Our WOL Service uses WSS4J API. WSS4J 1.5.x supports three different keystore types, JKS and PKCS12 and JCEKS. The first two of them will be covered here.

PKCS12

Typically, your x509 certificate will be issued to you in format of encrypted PKCS12 file ( e.g., yourname.p12), therefore for lot of people, PKCS12 would be the most straight-forward way to go. A PKCS12 keystore has a store password, and inside the keystore, your private key has a key password. The two passwords don't have to, and normally shouldn't set same. The following are a few notes that you should read when using PKCS12 format keystore:

  1. Make sure to use WSS4J 1.5.3+. It might work against older version as well, but we didn't test that.
  2. You can change the passwords of the key and keystore by using: 

openssl pkcs12 -in old.p12 | openssl pkcs12 -export -out new.p12

What it does is to make a copy of the keystore with the new passwords you choose.

  1. After you have done the creating of a new PKCS12 store, you can use 

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

to check out the new keystore. Pay attention to the "alias" of the private key entry.It's normally a number, such as "1" or "2". That's because you haven't manually specify a proper alias for the entry yet. Make sure to change it to something else because otherwise it simply won't work! (at least in our case..) To customize the alias, use 

keytool -changealias -alias 2 -destalias newname -storetype pkcs12 -keystore new.p12
  1. The default crypto.properties files shipped with the software were using JKS keystores. If you decided to use PKCS12, you will need to manually update your crypto.properties file, and in some cases also client-config.wsdd. A sample client side crypto.properties may be like this: 

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=pkcs12
org.apache.ws.security.crypto.merlin.keystore.password=mypassword
org.apache.ws.security.crypto.merlin.file=new.p12

where 'mypassword' is keystore password. WSS4J requires to use a PasswordCallback class to supply the actual private key password for security and flexibility considerations. The simplest but not recommended way of doing this is to hardcode the password in your PasswordCallback class.

(More work here to implement a custom password callback for sysdev. - kang)

JKS

All the sample keystores shipped with the software are in JKS format. Following steps demonstrate the procedure to prepare a JKS keystore:

  1. Convert PEM into PKCS12

If your x509 certificate has been issued to you in format of encrypted PKCS12 file ( e.g., yourname.p12), you can simply skip this step. Presumably you only have access to the certificate of PEM format. Normally you will have two separated PEM files -- one of which contains only your certificate ( public key) and the other contains your private key. Lets suppose they are named as usercert.pem and userkey.pem, then you can use the openSSL tool shipped with Linux/Unix to convert these two PEM files into a single PKCS12 file: 

openssl pkcs12 -export -in usercert.pem -inkey userkey.pem -out cert.p12 -name "name for certificate"

(For more information about certificates manipulation, try http://www.grid-support.ac.uk/content/view/377/276/ )

  1. Convert PKCS12 into JKS

In order to convert a PKCS12 keytstore into JKS, you can use the free PKCS12Import tool released by Jetty (binary is downloadable at http://goose.oerc.ox.ac.uk:8899/PKCS12Import.class), 

java PKCS12Import cert.p12 cert.jks

to convert yourcert.p12 from PKCS12 into JKS version. JRE 1.5+ is required to run this program. You will be asked to provide a "input keystore passphrase" and a "output keystore passphrase". The former is the passphrase protecting your existing *.p12 file, and the latter is the new passphrase that will be used to encrypt your new generated *.jks file.

At this stage you have already have an encrypted keystore containing your private key, you can easily verify this by typing, 

keytool -list -keystore cert.jks

The command displays all the keys written into the keystore, and the entry name for each of them.

Prepare Truststore

We call the Java Keystore (JKS) contains only the public keys 'truststore', because it contains the list of certificates (with only public keys) that we would like to trust. For example, a SSL client will check its truststore to find out whether the certificate presented by a server can be trusted; and when a WS-Security server receives a signed request, it will check its truststore to verify the signature.

To import a certificate into an existing truststore, or to create a new truststore, use keytool, 

keytool -import -keystore yourtruststore.jks -trustcacerts -file yourcert.pem -alias yourcert

You will be asked to create a password for the keystore.

Low Carbon ICT CA

Low Carbon ICT Project does maintain a testing Certificate Authority, 'lowCarbon CA". It is only intended to use for internal testing. You are strongly encouraged to use certificates issued by a proper CA whenever it is possible. Please contact kang.tang@oerc.ox.ac.uk if you need a certificate from lowCarbon CA for testing purpose.

Dependent Third Party Packages

You will find quite a few dependent third party packages under lib directory of the webapp, either on central or gateway server. They can be divided into several categories.

  1. Apache Axis 

activation.jar
xercesImpl.jar
xml-apis.jar
xmlsec-1.4.0.jar
junit.jar
commons-httpclient-3.0-rc2.jar
opensaml-1.0.1.jar
serializer-2.7.0.jar
addressing-1.0.jar
xalan-2.7.0.jar
bcprov-jdk15-132.jar
axis-ant.jar
axis.jar
commons-logging-1.0.4.jar
commons-discovery-0.2.jar
commons-codec-1.3.jar
commons-collections-2.1.1.jar
jaxrpc.jar
saaj.jar
wsdl4j-1.5.1.jar
log4j-1.2.8.jar
mail.jar
  1. XMLBeans 

xbean.jar
jsr173_1.0_api.jar
  1. Hibernate 3 (required on central WoL server only) 

hibernate3.jar
cglib-2.1.3.jar
antlr-2.7.6.jar
asm-attrs.jar
asm.jar
dom4j-1.6.1.jar
jta.jar
  1. Others 

jpcap.jar    - JPCAP API 7, required only on gateway
cog-jglobus.jar - JavaCog Kit. Required on central server for certificates manipulation when cert based authorization is enabled.
postgresql-8.3-603.jdbc3.jar  - JDBC driver for postgresql, required by central server only
wss4j-1.5.3.jar - Apache WS-Security Implementation for Java
netscan.jar     - The archive compiled from the schema that defines communications format between gateway and central server.(required on gateway and central monitor server)