University of Oxford wake-on-lan service

Guide to installation of the software and maintenance of the service

The wake-on-lan software was written by [http://www.oerc.ox.ac.uk/people/kang-tang Kang Tang] throughout 2008 and early 2009.This guide provides detailed information on how to download and install the software, and gives guidance on the ongoing support and maintenance tasks that are likely to constitute the management of the service when in production. The project has set up an [http://groups.google.com/group/low-carbon-ict?hl=en on-line discussion group] to support other organisations that are interested in using the software.

The software was developed at the University of Oxford as part of the [http://projects.oucs.ox.ac.uk/lowcarbonict/ Low Carbon ICT project], funded by the [http://www.jisc.ac.uk/whatwedo/programmes/exemplars.aspx JISC Institutional Exemplar Programme].

TableOfContents([2])

Introduction

We use this section to provide a technical description of:

1. How computers are registered with the WoL service
2. How a ICT managers and end-users can use the WoL service to wake computers
3. How third-party systems can call the WoL service to wake computers.

The diagram below illustrates the main software components implemented at the University of Oxford to provide an institutional WoL service.

attachment:wol-design-diagramv6.png

Registering computers to use the WoL service

The WoL service at Oxford allows both end-users and ICT managers to register computers. Managers can register clusters of computers, while end-users are restricted to just registering the computer(s) that they use.

To register a computer it must be connected with an ethernet cable to a subnet within a network that has a WoL gateway server installed. Computers that are connected using wireless, VPN or to a network that doesn't have a gateway cannot register with the institutional WoL service.

End-user: registering personal computers

1. User logs into the central computing registration service WoL web page using their institutional single sign-on (SSO) authentication credentials
2. The user clicks the register button, which then causes the registration service to ask the central WoL service to retrieve the user's MAC address.
3. The central WoL service retrieves the MAC address by asking all known gateway servers to send an ARP request with the IP address of the user that is logged into the service.
4. If the MAC address is found, the MAC address is returned to the registration service via the central WoL service.
5. The registration service stores the MAC address along with the users account name and address of the gateway server that is installed on the subnet where their computer is connected
6. The user is also asked to select any third-party services that they want to allow to switch their computer on. This could include backup, software patching and GRID services (e.g. such as Condor)

ICT managers: registering clusters of computers

1. An ICT manager logs into the registration service WoL web page using their institutional single sign-on (SSO) authentication credentials
2. Using the registration service WoL pages for ICT managers they can create a group in the registration service database
3. They can then upload a list of computers they want to register for the WoL service. The list is uploaded as a comma-delimited file compose of:
   • MAC Address (17 chars),
   • computer name
   • userId of computer owner (barcode)
   • third-party account name e.g. HFS TSM account id

Notes:

• A MAC address cannot be registered to more than one user. If a MAC address is already registered to a user then the registration web pages will display a message to ask the person trying to register a computer to contact their local ICT manager.
• It is possible for ICT managers to provide a list of MAC addresses that should never be registered. This can help stop the service being used to wake computers that should never be switched on remotely

Waking computers

To wake a computer it must be connected with an ethernet cable to a subnet within a network that has a WoL gateway server installed. Computers that are connected using wireless, VPN or to a network that doesn't have a gateway server cannot be woken by the institutional WoL service.

End-user

1. User logs into the registration WoL web page with their institutional single sign-on account
2. The registration service uses the single sign-on user name to retrieve the MAC address, gateway server name from the registration WoL database tables
3. The registration WoL service then calls the central WoL service using the Kerberos Negotiate messaging process to request a specific computer is sent a WoL "magic packet"
4. The central WoL service sends an HTTP SOAP message to the appropriate gateway server to wake a specific computer. The SOAP messages are signed by central server and encrypted using SSL.
5. The gateway server then broadcasts a "magic packets" to wake the target machine.

ICT manager waking clusters of computers

1. ICT manager logs into the registration WoL web page using institutional single sign-on account
2. The registration service uses the single sing-on user name to retrieve the groups the ICT manager has previously set up
3. Groups of computers are woken by pressing a button in the web page
4. The registration service sends a message to the central WoL service which includes all the MAC addresses that need to be woken
5. The registration service sends messages to the appropriate gateway servers

Notes:

• The WoL service will prevent more than 20 computers being send "magic packets" at the same time. This precaution has been built into the system to stop a power surge within the building that could result from too many computers being switched on at the same time.

Third-party use of the WoL service

Third-party services can call the WoL central server to wake one or more computers. For example the HFS backup service at the University follows the following procedure:

1. Every day the HFS service retrieves a file with an up-to-date list of HFS account names, MAC addresses and gateway server names
2. Before a scheduled backup is due the HFS service queries this file to retrieve the MAC address, gateway server name for a specific computer.
3. This information is then sent to the central WoL service as a secure signed SOAP message
4. The central service then sends a secure signed SOAP message to the correct gateway server
5. The gateway server then generates a WoL magic packet to wake a specific computer.

Additionally [http://www.oucs.ox.ac.uk/hfs/help/faq/index.xml.ID=shutdown computers can be configured to turn off] after the HFS service has finished backing up a computer.

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.

• Insert Entity Relationship Diagram
• Insert screenshot of prototype UI

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.

Installation guide

Prerequisite

The following tools need to be installed on the server machines before installing the central wol and gateway software.

Java SDK 1.5

Java JRE 1.5 is required on both Central and gateway servers. In addition, on the system where you want to build source from, java SDK 1.5 is also required.

Apache Tomcat 5.5

Apache Tomcat 5.5.x is required for both central and gateway server. SSL support is also required, which means you will need valid server certificates for both them. For testing purpose, the package includes two sample JCE keystore files under ${cwolf}/certs directory: sample-wolserv-tomcat.jks and sample-gateway-tomcat.jks. The key stores contain 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.

BouncyCastle JCE provider

Due to the fact that the WSS4J API was extensively used in the package, which have heavy dependency on BouncyCastle JCE provider, you will need to enable the BouncyCastle as JCE provider for your Java Runtime Environment. 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.

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 traffic through system network interface from within 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.

PostgreSQL 7.x +

As mentioned earlier, a database on central server is only required when you want to setup a local database to store information about registered computers. Although we were using PostgreSQL 7.4.19, we believe any other standard SQL relationship database should be working as well. All the iteraction between the software and database are done through Hibernate 3 API. Therefore in theory, all databases supported by Hibernate 3 should just work with only configuration changes.

Download the software

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

https://goose.oerc.ox.ac.uk:8843/public/LCICT

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://goose.oerc.ox.ac.uk:8843/public/LCICT/cwolf ./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 only, 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 only, 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

Installing central wol server

Install Webapp

It is really simple 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 tomcat is working properly, the archive will be automatically extracted under same directory after a few seconds. Now, open your browser and go to

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

to see how it goes.

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. If you are using these testing keystores, in your firefox browser, you will now see a page with title of "Secure Connection Failed". This is 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 detailed definition of the service, go to,

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

You have now successfully installed 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 is also installed.

Install 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 according to your own database setup information. In particular, change the following section according to your local setup:

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

Restart your 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 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 CWoLF software itself, it will certainly affect whether your service works as you expected. Firstly, 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, then you will have to install one separate gateway server for each of them. As mentioned before this is because wake-on-lan packets are broadcast traffic. Broadcast does not transverse between different subnets.

Install 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 detailed definition of the service, go to,

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

Now, 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 configuration work has to be done.

Installing gateway server with VMware

• download
• copy
• configure
• maintain

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:

• Location of central WoL service
• Location of gateway WoL service
• MAC address of the computer to wake up

To tell the system about this information, you might need to update following 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:

• lowCarbon-ca.jks - The truststore tells central server to trust certificates presented by sample gateway server, which is issued by lowCarbon CA.
• sample-wolserv.jks - The keystore holding host credential of central server. Key passphase is differernt than keystore passphase.
• sample-wolserv-tomcat.jks - The keystore holding host credential of central server. Key passphase is same as keystore passphase.
• trustedClientCerts.jks - The truststore contains list of trusted WoL client certificates.

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:

• sample-wolserv.jks - The keystore holding host credential of gateway server. Key passphase is differernt than keystore passphase.
• sample-wolserv-tomcat.jks - The keystore holding host credential of gateway server. Key passphase is same as keystore passphase.
• trustedClientCerts.jks - The truststore contains certificate of central server.

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:

• lowCarbon-ca.jks - need to be replaced by truststore containing the CA root certificate that issued certificate for central server.
• testclient.jks - need to be replaced by keystore containing your client credential. The public certificate of this client credential need to exist in trustedClientCerts.jks on central server.

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-diagramv6.png

Power Monitoring Service

The power monitoring service is an option feature that has been integrated with gateway server, which has been disabled by default. For details about it, please check out document of power monitoring service.

Third-party integration with central WoL service

Backup service: HFS

• component diagram
• explanation

Maintenance considerations

• Scalability - how many departments can use the service in its present form?
• Certificates between central and gateway service
• When computers are allocated to new owners ICT managers will have to re-register the computer to a new owner
• Patching operating system on central and gateway services
• If there is a problem with the service and users seek support:
  • Computers fail to wake
  • Monitoring service plotting

Support considerations

• PXE boot
• Power surge
• Roll out service gradually to make sure computers behave as you expect
• Best effort service e.g. dependencies include
• What considerations need to be made when NAT is used?
• I cannot wake my computer - BIOS, Network Card configuration
• I woke my computer last night but it doesn't wake any more - lost network packets, firewall, gateway server, central server

Appendix

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, which can be very frustrating for users who do not have much experience with certificates based security before. This chapter describes how to prepare the certificates issued by Certificate Authority to be used by CWoLF.

Convert PEM into PKCS12

Typically the certificate will be issued to you in format of encrypted PKCS12 file ( e.g., yourname.p12). If this is the case, you can simply skip this step. However, sometime you might only access to certificates of format PEM, and normally you will have two separated PEM files, one of which contains only your certificate ( public key) and the other contains your private key. Presumably 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"

(Please check http://www.grid-support.ac.uk/content/view/377/276/ for more commands of converting different formats of certificate.)

Convert PKCS12 into JKS

WoL Service uses WSS4J API to authenticate clients. WSS4J supports three keystore types at this moment, JKS and PKCS12 and JCEKS. We recommend JKS for simplicity. In order to convert a PKCS12 keytstore into JKS, simply use the free PKCS12Import tool released by Jetty (binary is downloadable at http://goose.oerc.ox.ac.uk:8899/PKCS12Import.class) and use,

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 truststores

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.