1. Introduction

The Energy Efficiency and Monitoring services (wake-on-lan and power management monitoring) are delivered to University networks by "EEM gateways". Each University network on which EEM services are to be offered must be connected to a gateway, but each gateway can serve multiple networks (physical, logical, and virtual). This means that typical units will only need a single EEM gateway, regardless of the number of separate physical networks, IP subnets, and virtual networks (virtual infrastructure networks and/or VLANs).

EEM gateways are lightweight, fully managed Debian GNU/Linux servers running the EEM system components and registered with the central EEM server. There are two options for deploying a gateway on your network:
  • Fully managed: IT Services will supply and manage a gateway for you - the gateway will be a small (low power) appliance and all you need to do is connect it to your network(s)
  • Part managed: Provision and maintenance of EEM gateways is shared between local ITSS (you provide the physical or virtual host and carry out the initial installation) and IT Services (we provide configuration and ongoing maintenance of the operating system and installed software).

This document provides first-time installation instructions for local ITSS wishing to set up an EEM gateway on one or more networks. A typical set up can be completed in under a day.

2. Installation Procedure - Fully Managed

If you wish to take a fully managed gateway then you should request this by emailing sysdev e.g. using following email template:
To: sysdev@it.ox.ac.uk Subject: EEM fully managed gateway request: Unit name Please supply an EEM gateway for use as follows: Contact email : it-support@unit.ox.ac.uk Gateway FQDN : eem-gateway.unit.ox.ac.uk Gateway subnet mask: /24 (or 255.255.255.0) Gateway router address: 163.1.42.254 Network "Unit Offices": VLAN : None Units : unit, survey Publish : yes Network "Unit IT Lab": VLAN : 15 Units : unit, survey Publish : no Thanks, IT Support for Unit
  • Gateway FQDN is the FQDN of the gateway on your network - you will need to register this DNS name
  • Gateway subnet maskis the subnet mask for the EEM gateway's IP configuration
  • Gateway router addressis the EEM gateway's local router
  • Contact email is an email address that we can use to contact the appropriate person if there is a problem with the gateway
  • One or more Network sections, with a friendly name, define the networks that this gateway should monitor. The friendly name will be used to identify the network to users on the PMM graphs.
  • VLAN is the VLAN on which the network is connected, or None if VLAN tagging is not used for this network
  • Units is a list of units whose members can view PMM graphs for this network (useful if you want to share your data with other units)
  • Publish specifies whether PMM data should be available for public viewing

Once your request has been received, IT Services will contact you to arrange a convenient installation date.

The EEM gateway will need to accept the following network connections, which may require perimeter firewall/IPS/router configuration:
  • From 163.1.160.50 and/or 2001:630:440:105:0:1:0:19 to ports tcp/22 and tcp/4373

3. Installation Procedure - Part Managed

3.1. Vanilla Debian (wheezy) install

Please note that, as the system configuration of this host will be fully managed by IT Services, we strongly recommend that a fresh host is used, dedicated for EEM, and not used for any other purpose.

  • Host can be physical or virtual
  • Supported architectures: i386 and amd64
  • Minimum supported host specification:
    • 1GB RAM
    • 10GB disk, preferably using Debian's "separate partitions" model
    • 1 core of a contemporary Intel/AMD CPU
    • 100Mbps wired Ethernet connection
  • At least one public IP address assigned for management access
  • Any physical or VLAN networks must be connected to this host, but there is no need to have an IP address on each
  • The host will need to accept the following network connections, which may require perimeter firewall/IPS/router configuration:
    • From 163.1.160.50 and/or 2001:630:440:105:0:1:0:19 to ports tcp/22 and tcp/4373

3.2. Register server

Registration is done by emailing sysdev e.g. using following email template:
To: sysdev@it.ox.ac.uk Subject: EEM gateway registration request: Unit name Please register the following EEM gateway and networks: Gateway FQDN : eem-gateway.unit.ox.ac.uk ITSS Managers : unit0001/itss, unit0017/itss Contact email : it-support@unit.ox.ac.uk Network "Unit Offices": Interface : eth0 Units : unit, survey Publish : yes Network "Unit IT Lab": Interface : eth1.15 Units : unit, survey Publish : no Thanks, ITServicesBot
  • Gateway FQDN is the FQDN of the gateway on your network
  • ITSS Managers is a list of the /itss principals of ITSS who will be setting up / managing the gateway.
  • Contact email is an email address that we can use to contact the appropriate person if there is a problem with the gateway
  • One or more Network sections, with a friendly name, define the networks that this gateway should monitor. The friendly name will be used to identify the network to users on the PMM graphs.
  • Interface is the Ethernet interface that this network is connected to on the gateway. For simple setups this will usually be eth0. VLANs must be specified individually in the ethX.VLAN format.
  • Units is a list of units whose members can view PMM graphs for this network (useful if you want to share your data with other units)
  • Publish specifies whether PMM data should be available for public viewing

Once you have sent in your registration, please wait until sysdev has processed this and replied to you before continuing with the next step.

3.3. Install EEM Components

  1. Download the EEM package signing key and add to apt keyring, configure EEM package repository and install EEM gateway for Oxford:
    # wget -O- https://www.oucs.ox.ac.uk/services/eem/package-signing-key.txt | apt-key add - # echo "deb http://debian.oucs.ox.ac.uk/eem/wheezy stable general" > /etc/apt/sources.list.d/eem.list # apt-get update # apt-get install eem-gateway-oxford # eem-configure
  2. Generate Kerberos keytab for host:
    # kadmin -p unit9999/itss@OX.AC.UK kadmin: ktadd -k /etc/krb5.keytab host/FQDN@OX.AC.UK kadmin: exit

4. Testing the Gateway

4.1. Register a workstation

Visit https://eem.ox.ac.uk/ from a workstation that has not previously been registered with the EEM service, and select Register machine.

This should take you to a registration page with the MAC address for the workstation auto-completed. Other fields may also have been completed for you. Complete the registration.

4.2. On-demand Wake-up

Power down the machine you registered above, and visit https://eem.ox.ac.uk/ from another workstation. Select Turn a machine on and click on the button for the registered workstation.

This should send a wake-up call to the registered workstation within a few seconds, and the workstation should start to boot.

4.3. Scheduled Wake-up

Back at https://eem.ox.ac.uk/, select Manage Schedules and configure a schedule for the registered workstation (choosing a wake-up time around 10 minutes in the future is suitable for a quick test). Power down the workstation to be woken-up.

This should cause a wake-up call to be sent to the registered workstation at the scheduled time, and the workstation should boot.

4.4. View Energy Usage Charts

Visit https://eem.ox.ac.uk/cgi-webauth/graphs.cgi.

You should see energy usage charts for all networks that you are authorised to view - including those that your gateway supports. Charts are generated once an hour, so you may need to wait a bit before the first set are ready for display.

5. Common Questions

5.1. Can I run EEM on other Linux flavours than Debian?

The EEM system is developed for the Debian GNU/Linux operating system as target platform and we do not support other Linux distributions.

5.2. How do I install Debian?

The Debian installation manual provides comprehensive guidance for anyone who is not already familiar with installing Debian GNU/Linux.

5.3. How do I configure VLANs in Debian?

You will need to specify the relevant interface in /etc/network/interfaces, for example the following sample configures 3 VLANs on the first Ethernet interface (eth0), where VLAN 13 is used to provide host connectivity to the outside world (note that you do not need to specify IP addresses for all interfaces - only the one that will be used to contact the gateway):
auto lo iface lo inet loopback auto eth0.13 iface eth0.13 inet static address 129.67.160.17 netmask 255.255.252.0 gateway 129.67.3.254 auto eth0.100 auto eth0.105

5.4. What is a /itss principal and how do I set one up?

Oxford SSO accounts include a Kerberos principal that can be used for authentication - to prove your identity. Normal SSO accounts are based on a "simple" principal of the form unit9999@OX.AC.UK - the first part is often referred to as the Oxford username. These accounts are used for a wide variety of purposes, and the account password is likely to be used in a number of situations where convenience is preferred over security.

For certain administrative IT activities, such as establishing server-to-server trust, a higher level of security is required than can be assumed for most SSO accounts. IT Services therefore issues a separate set of credentials to ITSS who need this facility. For consistency and ease of remembering, the principal is based on the usual SSO username, taking the form unit9999/itss@OX.AC.UK. The password constraints on these accounts are more stringent as well, requiring a minimum of 8 characters. /itss accounts can be managed in the same way as a normal SSO account, through the Webauth account management pages.

Registered ITSS can request a /itss principal by email to sysdev@it.ox.ac.uk. In order to set a password on this account you will typically need to visit IT Services with your University Card as photographic identification, although we can send temporary passwords encrypted with GPG where we already have trusted keys for the relevant recipient.

5.5. Who is responsible for maintaining the gateway once it is installed?

Responsibility for maintenance is shared between yourself and IT Services. Under normal circumstances IT Services will ensure that updates to the installed Debian release are applied expediently, and will manage the system configuration. You should maintain the infrastructure (physical or virtual), environment, and network connectivity.

IT Services will endeavour to identify and resolve minor platform issues if/when they arise. If a problem cannot be resolved then you may need to reinstall the gateway using the instructions above. EEM gateways are not backed up as the only data that could be lost are the recent observations of active devices.

Upgrading to future Debian releases is expected to be the responsibility of local ITSS, carried out by way of a new installation / full reinstallation. This has not yet been explored or tested however, and a more lightweight upgrade option may become available.

5.6. What if I am not able to provide a suitable platform?

Some people may not have the infrastructure, resources, capabilities, or authorisation to meet the requirements set out above to run their own part managed EEM gateway. Therefore you can request a fully managed gateway provided by IT Services free of charge.

5.7. Why don't you make krb5-user a dependency of eem-gateway-oxford?

The main reason is that krb5-user on its own is not enough - you also need proper configuration in /etc/krb5.conf. The eem-configure step will do both things for you, which is why it comes before the kadmin step in the installation instructions.

5.8. Does EEM work with Cisco VMPS / dynamic VLANs?

No. EEM is perfectly capable of being used on VLANs, and even of waking up hosts that move from one VLAN to another, and works well with systems such as the Bradford Campus Manager. However, Cisco's VMPS DVLAN solution actually marks as "inactive" any managed switch ports that have not seen traffic from the connected device for a given period of time, and will not forward any further network packets on that port. This means that when a computer is turned off, the switch port is marked "inactive" and the switch will not send the wake-on-LAN magic packet to the target host.

The Cisco support forms include a ticket about this issue, available at https://supportforums.cisco.com/thread/15213

5.9. Does EEM work with Windows 8?

Windows 8 introduces a new behaviour during normal shutdown where the network adaptor is disabled. This means that if a user shuts down their machine via this route, it will not be possible to use EEM to wake up the system (including, for example, for HFS backups). Instead, the user would need to suspend or hibernate the system. This should be considered during any large-scale Windows 8 deployments on EEM-supported networks.

The Microsoft support documentation includes an article about this issue, available at http://support.microsoft.com/kb/2776718. However, please note that the workarounds on this page do not directly enable wakeups following shutdown.