Campus Wake-on-LAN Framework User Guide

TableOfContents([2])

Before the installation

It's important to read carefully through the this chapter before you start the installation. It describe the basic components and various installation options of the software.

Introduction

Campus Wake-on-LAN (CWoLF) Framework is a software solution developed in Oxford University to enable users within or outside campus network to wake up their computers when necessary, based on existing technologies such as Wake-on-LAN (WoL).The software package itself can be loosely divided into three components: Central WoL Server, the Departmental Gateway Server and a sample web service client for WoL Server.

Central or Gateway

In most cases, only one single Central WoL Server is required for a institution. It provides interfaces that front end (UI) that other users or other services can call to register, manage and wake up computers. In addition, it forwards the received request from clients to departmental gateway server through secured HTTP based SOAP messages.

Upon being forwarded such user request, the appropriate gateway server that is responsible for the target computers will generate and broadcast magic packet to wake up the target computers. One gateway server will be required for each network subnet, or broadcast domain. This is because Wake-on-LAN packet is broadcast traffic therefore not be able to transverse between different network subnets. There is, however, no limitation on the number of computers that a single gateway server is capable to manage, as long as the computers are physically located within same network subnet. For example, for a network with netmask of 255.255.254.0, one single gateway can easily manage up to 255x2-2 = 508 hosts.

Firewall

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

Operation System

The software was developed and tested on Linux (CentOS4), therefore Linux is 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 machine. However, since gateway server has external dependency on Pcap library , you will have to figure out yourself the correct to install Pcap Library on your chosen operation system. This document will only cover the installation instructions on Red hat based Linux operation system.

Database

It's optional to setup a database on central server to store the information for registered computers, such as their MAC addresses, owner names, and physical locations. With this information in its local database, WoL server will be able to figure out the physical location for a register MAC address. It also allow WoL server to perform some basic authorization based on the ownership of each computer. On the lack of such database on central server, the server will assume a external 3rd party database have been setup to hold such information therefore only accept request where full required information are provided, e.g. both the MAC address and physical location. In term of security, only authentication will be performed.

Installation

Prerequisite

Before install WoL Service and Gateway service on your system, the following tools and libraries need to be installed.

Java SDK 1.5+

Java JRE 1.5+ is required on both Central and gateway servers. 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. is required for both central and gateway server. SSL is also required on both of them, which means you will need certificates for both them. For testing purpose, the package includes two sample 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 SSL service. They were issued by a testing CA for Low Carbon ICT Project and should only be used for testing. Feel free to setup your web server on any ports you prefer, however, we will assume default port 8443 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 Enviroment. Simply add following line in your $JAVA_HOME/jre/lib/security/java.security file:

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

while '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 server to capture and send network traffic on your network interface from within JVM. For a detailed instructions on how to install these on your system, see XXXXX in this document.

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

Build the source

In following part of the document, we are going to use ${cwolf} to stand for the root directory of the checked out project.

To build the source code from source, you will need Apache Ant 1.6.5 + installed on your system. Obviously you will need JDK installed as well. The lowest version we recommand for JDK is 1.5. The project build file build.xml is located under ${cwolf}. Another file you might want to have a look at is build.properties under same directory, where you can set a few 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, also 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

The sample client can be used to test WoL service after you have it sucessfully deployed.

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

ant build-all

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

ant clean

Install Central 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 everything is fine, 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 doing like this, you will now see in your browser a page with title of "Secure Connection Failed" on the top. 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. We can not test the service with our sample client yet, which needs to wait until at least one gateway server is also installed.

Install Database

If you prefer 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 to your own requirement. In particular, change the database connection parameters 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.

Install Gateway Server

Gateway Server Location

Although this has nothing to do with the CWoLF software itself, it will affect whether your service works as you expected. Firstly, you need to identify the machines that the users of the service will want to wake up. Usually this is 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 deparment, its office network might include multiple subnet, then you will have to install one seperate gateway server for each of these subnets. As mentioned before this is because Wake-on-LAN packets are broadcast traffic. Broadcast does not transverse between differernt 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. Then copy cwolf-gateway.war to {TOMCAT_HOME}/webapps directory, on the server that has been picked up 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 yourelf through. You should be able to 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. Before central server and gateway server can work together to wake up your computer,some configuration work has to be done.

Post Configuration

Make the sample service work

In order to test the central server and gateway server, we are hoping to send a WoL request to WoL central server from our sample client, in order to wake up a computer which we believe is located in the same subnet as the newly installed gateway server.

The information we will need to make this work includes:

1) Location of central WoL service 2)Location of gateway WoL service 3) MAC address of the computer to wake up

Firstly, 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.

If the IP address for gateway server is 192.168.1.1, you will then need to add a new ProxyServer element with its ip element set as '192.168.1.1' and its url element set as 'https://192.168.1.1:8443/cwolf-gateway/services/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.

Secondly, we change 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: 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. It is crucial to use IP address of gateway server as domain name is not supported in current version.

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

sh ./sampleclient.sh

Adapt to your real environment

The purpose of the sample service we implemented in previous section is to give you a quick idea of how the WoL service works. It should not , however, be used in any real network enviroment as a permant service, because it is not secure.

All the keys and certificates need to replaced with real valid certificate issued by a proper Certificate Authority.

Appendix

Install Jpcap 7 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 usually 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 genenrate 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 privildge.

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

Client Side

Typically the certificate will be issued to you in form of a encrypted PKCS12 file ( e.g., yourname.p12). Some CAs issue certificates in format of PEM files. If this is the case, you should have been given 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"

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

WOL Service uses WSS4J API to authenticate clients. WSS4J supports two types of keystore at this moment, JKS and PKCS12. We recommend to use JKS format. In order to convert a PKCS12 keytstore to JKS, simply download the free PKCS12Import tool (http://goose.oerc.ox.ac.uk:8899/PKCS12Import.class) released by Jetty 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, while the latter is the new passphrase that will be used to encrypt your new generated *.jks file.

Before the client can retrieve private key for this new generated cert.jks file, we need somehow tell the client what this passphrase is. At this moment, for testing purpose, a very simple Callback handler was implemented to deal with this passphrase retrieving.The passphase was simply hardcoded within the code as "treasure". That means in order to make the client work, you have to set the "output keystore passphrase" as "treasure" when generating the local cert.jks file. (This need to be changed in future!)

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

This command display all the keys written into the keystore, and the entry name for each of them. What we need now is to configure the client to use this private key to sign each SOAP request to Wake-on-LAN service. To do this, copy the newly generated cert.jks into sampleClient/bin and edit crypto2.properties under the same directory as following:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin org.apache.ws.security.crypto.merlin.file=cert.jks org.apache.ws.security.crypto.merlin.keystore.type=jks org.apache.ws.security.crypto.merlin.keystore.password=your_passowrd org.apache.ws.security.crypto.merlin.keystore.alias=your_key_entry_name javax.net.ssl.trustStore=escience-ca.jks javax.net.ssl.trustStorePassword=security

where they keystore.password is the one you specified to protect the keystore when using PKCS12Import tool, and the keystore.alias is the entry name for this key which you can find out using keytool -list command.

The sceicence-ca.jks is another keystore which holds all the trusted certificates. This file should already exist under sampleClient/bin and therefore no need to change.

That is basically all you need to do to make the sampleClient works with a new issued certificate.

Server Side

To make the call from client side accepted by the Wake-on-LAN Service, the server need to have a copy of the client's public key. This has to be provided by the client and need to be updated on server side whenever client certificate is changed.

Assuming the certificate (contains only public key) for a new WOL web service client is clientcert.pem, to configure WOL server to accept requests from this client, run following on the server:

keytool -import -keystore trustedClientCerts.jks -trustcacerts -file clientcert.pem -alias newclient-cert

where trustedClientCerts.jks is the keystore on the server that contains all the public keys of the accepted clients and is located under $TOMCAT_HOME/webapps/wolserv/WEB-INF/etc.