University of Oxford Wake-on-LAN service

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

The WOL software was written by Kang Tang between late 2007 and early 2009 as part of the Low Carbon ICT project. The work was supported by by the JISC Institutional Exemplar Programme.

Contents

  1. Introduction
    1. Registering and waking computers
    2. Gateway server
    3. Firewalls
    4. Operation system
    5. Using the packaged database and user interface
  2. Deploying a LINUX WOL Gateway Server appliance in a VMware environment
    1. Importing the Linux WOL Gateway Appliance
    2. Edit networking parameters
    3. Change the hostname
    4. Change passwords
    5. Edit Tomcat parameters
    6. Edit the local firewall
    7. Disable root access via SSH
  3. Deploying the WINDOWS WOL gateway server appliance in a VMware environment
    1. Importing the Windows WOL Gateway Appliance
    2. Boot up the VM and run through the initial customisation sequence.
    3. Change administrator password
    4. Edit Tomcat parameters
    5. Patch the server
    6. Install anti-virus
    7. Edit the local firewall
  4. Installing a WOL Gateway Server from source
    1. Prerequisite
    2. Download the software
    3. Build the source
    4. Install Gateway server
  5. Installing a Central WOL Server
    1. Prerequisite
    2. Download the software
    3. Build the source
    4. Install the Central WOL Server
  6. Post Configuration
    1. Make the sample service work
    2. Adapt to your real environment
    3. Integrate with non-webservice client
    4. Integrate with external single sign-on infrastructure
  7. Appendices
    1. Install Jpcap7 and libpcap 0.9.4+
    2. Prepare Certificates for CWoLF
    3. Dependent Third Party Packages

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:

pmmandwolsystem.png

Registering and waking computers

A user guide to the WOL service at is provided on Oxford University Computing Services website: http://www.oucs.ox.ac.uk/wol/index.xml

Gateway server

The gateway server performs two main functions:

  1. Broadcasts WOL "magic packets" to switch a specific computer on (through including a computers globally unique MAC address).
  2. Send ARP queries to retrieve the MAC address for a specific computer.

The number of gateway servers that are needed will be dependent on how an organisation has designed the underlying network. Institutional networks are normally divided up into subnets for security reasons, and since WOL "magic packets" are 'broadcast' 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 ports on any firewalls are opened between your central server and department gateway servers. 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 the Linux operating system is recommended for both central and gateway software. However, since the software is implemented as standard java web applications within Tomcat 5.5, it should be possible to install the software in both windows and Mac server environment.

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 "redhat" 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.

Deploying a LINUX WOL Gateway Server appliance in a VMware environment

Importing the Linux WOL Gateway Appliance

Once the VM has been imported into your VMware environment, you will need to customise it as is described in the following sections:

Edit networking parameters

Edit the /etc/udev/rules.d/70-persistent-net.rules file

The VM will have been assigned a new ethernet adapter, so ensure that the first line with MAC address 00:50:56:8f:6a:e7 is removed and the second line is edited so that it is configured as eth0 rather than eth1, e.g: 

SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:50:56:8f:70:c3", ATTR{type}=="1", KERNEL=="eth*", NAME="eth0"

Restart /etc/init.d/udev to get this to take: 

/etc/init.d/udev restart

Edit /etc/network/interfaces and change the following parameters:

address <new IP address e.g. 163.1.9.61>
netmask <new subnet mask e.g. 255.255.255.0>
network <network range e.g. 163.1.9.0>
broadcast <broadcast address e.g. 163.1.9.255>
gateway <gateway address e.g. 163.1.9.254>
dns-search <domain name e.g. oucs.ox.ac.uk>

Save the file and restart networking e.g. 

/etc/init.d/networking restart

Edit the /etc/networks file

localnet <network range e.g. 163.1.9.0>

Change the hostname

Edit the /etc/hostname file and enter the appropriate hostname

Edit the /etc/hosts file

<new IP address e.g. 163.1.9.61>  <FQDN e.g. wolg.oucs.ox.ac.uk> <shortname e.g. wolg>

Change passwords

Two accounts are provided, root and itss. Change the passwords for both of these from the defaults using the password utility.

Edit Tomcat parameters

Change the passwords on the gateway keystore: 

cd /var/lib/tomcat5.5/webapps/cwolf-gateway/WEB-INF
keytool -list -keystore trustedClientCerts.jks

Password is the same as for the itss and root accounts.

Check that the only entry in here is for goose. This is the central WoL server at OUCS - if you want to use a different central server, you will need to import the public key of your central server. Follow the instructions in the Appendix for this.

Otherwise, all you need to do is change the password on the keystore: 

keytool -storepasswd -keystore trustedClientCerts.jks

Update the Tomcat crypto.properties file to reflect the new keystore password

vi /var/lib/tomcat5.5/webapps/cwolf-gateway/WEB-INF/classes/crypto.properties

Edit the line 

org.apache.ws.security.crypto.merlin.keystore.password=<new keystore password>

Ensure that this file is not world-readable.

Ensure that Tomcat's SSL Connector is enabled, and looking to the correct keystore

For testing purposes, the gateway server package includes two sample JCE keystore files under in the ${cwolf}/certs directory: sample-wolserv-tomcat.jks and sample-gateway-tomcat.jks. Note that these were issued by a testing CA set up for the Low Carbon ICT Project and should only be used for internal testing.

In $CATALINA_HOME/conf/server.xml, check the following: 

 <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
    <Connector port="8443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" keyAlias="sample-gateway"
               keystoreFile="/var/lib/tomcat5.5/webapps/cwolf-gateway/WEB-INF/sample-gateway-tomcat.jks"
               />

For testing, no edits are required, but you will need to prepare production keystores (as detailed in the appendices below) and then edit the keystore file line to point to the new keystore when you are ready to put the gateway server into production.

Edit the local firewall

The only incoming traffic that should be necessary is traffic to the web application from the central server, on TCP/8443, as well as SSH traffic on TCP/22 if you want to administer the gateway server remotely.

By default the gateway allows TCP/8443 in from anywhere in Oxford, most ICMP traffic and SSH traffic from a list of approved hosts. You will probably want to edit the following lines in the /etc/init.d/firewall script: 

    SSH_CLIENTS="${NSMS_DESKTOPS} 163.1.26.87 163.1.125.73"
    # Allow incoming SSH connections with trusted clients
    for addr in $SSH_CLIENTS; do
      $IPTABLES -A INPUT -p tcp -s $addr --dport 22 -m state --state NEW,ESTABLISHED -j ACCEPT
      $IPTABLES -A OUTPUT -p tcp -d $addr --sport 22 -m state --state ESTABLISHED -j ACCEPT
    done
    # Allow incoming requests to Tomcat (WoL service):
      $IPTABLES -A INPUT -p tcp -s 163.1.0.0/16 --dport 8443 -m state --state NEW,ESTABLISHED -j ACCEPT
      $IPTABLES -A OUTPUT -p tcp -s 163.1.0.0/16 --sport 8443 -m state --state ESTABLISHED -j ACCEPT
      $IPTABLES -A INPUT -p tcp -s 129.67.0.0/16 --dport 8443 -m state --state NEW,ESTABLISHED -j ACCEPT
      $IPTABLES -A OUTPUT -p tcp -s 129.67.0.0/16  --sport 8443 -m state --state ESTABLISHED -j ACCEPT
    # ...allow all other ICMP packets
    $IPTABLES -A INPUT -p icmp -j ACCEPT
    $IPTABLES -A OUTPUT -p icmp -j ACCEPT

Disable root access via SSH

By default root access is enabled via an SSH connection. You should disable this and connect via the itss account instead. This can be done by editing /etc/ssh/sshd_config and setting the line: 

PermitRootLogin no

That's it! Reboot the gateway server. You should be able to check that it is up and running by accessing it via your browser:

https://server.unit.ox.ac.uk:8443/cwolf-gateway/services

At this point the configuration of the central server will need to be updated with the details of the new gateway server. At Oxford this is achieved by contacting OUCS Registration Services (http://www.oucs.ox.ac.uk/registration/) to provide: 

keytool -export -alias sample-gateway -file mycert.crt -keystore /var/lib/tomcat5.5/webapps/cwolf-gateway/WEB-INF/sample-gateway-tomcat.jks

Once the gateway server is registered, you should be able to start registering and waking up computers through the https://register.oucs.ox.ac.uk/itss/wol interface.

Deploying the WINDOWS WOL gateway server appliance in a VMware environment

Importing the Windows WOL Gateway Appliance

Once the VM has been imported into your VMware environment, you will need to customise it as is described in the following sections:

Boot up the VM and run through the initial customisation sequence.

The licence key for Windows 2003 is included in the readme file in the download zip file. At the Networking Settings screen, select 'Custom settings' and enter your IP address, gateway etc. One thing to note is that when you are prompted for the administrator password during this setup phase, it will not actually apply, whatever you type in! You should use the administrator password provided in the readme file, and then change it once the initial sysprep sequence has completed and you are logged in.

Change administrator password

Two accounts are provided, administrator and itss (non administrative). The passwords for both of these accounts are the same and provided in the readme file in the download. You should change both of these!

Edit Tomcat parameters

Change the passwords on the gateway keystore, at the Command Prompt

cd "C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\cwolf-gateway\WEB-INF"
keytool -list -keystore trustedClientCerts.jks

Password is the same as for the itss and root accounts. The keytool utility can be found in the c:\program files\java\jre6\bin directory - you may want to add this to the path (although this isn't necessary for gateway functionality).

Check that the only entry in the trustedClientCerts.jks keystore is for goose. This is the central WoL server at OUCS - if you want to use a different central server, you will need to import the public key of your central server. Follow the instructions in the Appendix for this.

Otherwise, all you need to do is change the password on the keystore: 

keytool -storepasswd -keystore trustedClientCerts.jks

Update the Tomcat crypto.properties file to reflect the new keystore password

This file can be found in the directory: 

C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\cwolf-gateway\WEB-INF\classes

Edit the line 

org.apache.ws.security.crypto.merlin.keystore.password=<new keystore password>

Ensure that the permissions on this file are set to Administrators (Full Control) and System (Full Control) only.

Ensure that Tomcat's SSL Connector is enabled, and looking to the correct keystore.

For testing purposes, the gateway server package includes two sample JCE keystore files under in the ${cwolf}/certs directory: sample-wolserv-tomcat.jks and sample-gateway-tomcat.jks. Note that these were issued by a testing CA set up for the Low Carbon ICT Project and should only be used for internal testing.

In C:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\server.xml, check the following: 

<Connector port="8443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               keyAlias="sample-gateway" keystoreFile="C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\cwolf-gateway\WEB-INF\sample-gateway-tomcat.jks"
               />

For testing, no edits are required, but you will need to prepare production keystores as detailed in Section 5.2 of the wiki documentation and then edit the keystoreFile line to point to the new keystore when you are ready to put the gateway server into production.

Patch the server

The WoL gateway is fully patched up to and including February 2009's updates. It is also configured to automatically download and install updates from Microsoft Update at 3am daily. Before allowing incoming traffic however, a manual update is advised.

Install anti-virus

No anti-virus software is provided with the gateway server. If this is desired, you should install it separately.

Edit the local firewall

The only incoming traffic that should be necessary is traffic to the web application from the central server, on TCP/8443, as well as RDP traffic on TCP/3389 if you want to administer the gateway server remotely.

By default the gateway allows Tomcat traffic (TCP/8443) in from the OUCS central WoL server (goose.oerc.ox.ac.uk, 163.1.124.250) and the NSMS subnet (129.67.102.64/255.255.255.192, for testing purposes). You will probably want to remove the NSMS subnet and if you are deploying your own central server you will need to add that in instead of goose.oerc.following hosts:

RDP traffic is allowed by default only from the NSMS subnet (129.67.102.64/255.255.255.192) - you will probably want to change this too.

ICMP ping traffic is also allowed by default, which may or may not be desirable.

Once the firewall is configured appropriately, you should be able to check that it is up and running by accessing it via your browser:

https://server.unit.ox.ac.uk:8443/cwolf-gateway/services

At this point the configuration of the central server will need to be updated with the details of the new gateway server. At Oxford this is achieved by contacting OUCS Registration Services (http://www.oucs.ox.ac.uk/registration/) to provide: 

keytool -export -alias sample-gateway -file mycert.crt -keystore "C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\cwolf-gateway\WEB-INF\sample-gateway-tomcat.jks"

Once the gateway server is registered, you should be able to start registering and waking up computers through the https://register.oucs.ox.ac.uk/self/wol interface.

Installing a WOL Gateway Server from source

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 functionalities. 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 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.

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.

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.

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 .

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

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) Install libpcap 0.9.4+ using yum

On redhat linux, you can use yum to install libpcap if the version in your rpm repository is higher than 0.9.4. 

sudo yum install libpcap libpcap-devel

It is important to install the source package libpcap-devel.

3) Alternatively you can download libpcap from source and build it youself:

download source packages of libpcap 0.9.8 from

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

Then go into the directory where libpcap is downloaded and 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 format 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 on the central server for signing and encrypting ( no need for gateway servers ), 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.

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 be set as same. The following are a few notes that you might find helpful 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. Keytool doesn't allow to change password for PKCS12 type of keystore, but we can work around by make a copy of your existing PKCS12 because you can set the password for the new copy: 

openssl pkcs12 -nodes -in old.p12 -out tmp
openssl pkcs12 -in tmp -export -out new.p12
  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, we can use keytool that comes with JDK 1.6+. Lower version of keytool doesn't support 'changealias'. 

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 your PKCS12 keystore password.

  1. You will need to update the axis deployment descriptor client-config.wsdd on the central server to reflect the "alias" of the private key used to sign messages and the private key password, which is identical to the keystore password in case of PKCS12. WSS4J requires to use a PasswordCallback class to supply the actual private key password for extensibility . The simplest but not recommended way of doing this is to hardcode the password in your PasswordCallback class.

(todo- implement a custom password callback for sysdev. - kang)

An sample client-config.wsdd is attached as below, where the signing key is set to use "privatekey_alias" and the key password is set to provided by callback class 'uk.ac.ox.oerc.wol.sample.SamplePWCallback'. 

<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="privatekey_alias" />
                                <parameter name="passwordCallbackClass"
                                        value="uk.ac.ox.oerc.wol.sample.SamplePWCallback" />
                                <parameter name="signatureKeyIdentifier"
                                        value="DirectReference" />
                                <parameter name="signaturePropFile"
                                        value="crypto.properties" />
                        </handler>
                </requestFlow>
        </globalConfiguration>
</deployment>

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)