M100382: Behavior explanation: Wake-on-LAN (WOL)

Summary

Describes the algorithm used to generate Wake-on-LAN jobs and possible configuration options.

In order for Wake-on-LAN (WOL) to work effectively in an environment, it helps to understand the necessary requirements for operation and how WOL jobs are created and targeted.

Wake-on-LAN operational requirements

For Wake-on-LAN to operate effectively in your environment, the warehouse and managed device must meet specific requirements.

The warehouse requires that:

The target machine must be in Active Directory (AD).
Machine inventory including the default IP gateway, machine subnet mask, IP address, and MAC address for the target machine must be in the ManageSoft database.
A gateway must be configured that allows a distribution server to target the machines it must wake-up.
Wake-on-LAN operators' accounts must be members of the MGS Administrators security group. For the distribution server, the replication agent account must have appropriate read/write permissions and the ability to create scheduled tasks as the local SYSTEM account.

The managed device requires that:

The Network Interface Card (NIC) supports Wake-on-LAN and is enabled.
It is in the 'Sleep' state and has been shutdown through the Start menu. It must NOT be in "Suspend" or "Hibernation" mode, nor turned off with the power button.

Wake-on-LAN defaults

ManageSoft WOL packets are sent by the selected distribution server over UDP port 1230. This port number is currently not configurable.
The default maximum "distance" a distribution server can be from a managed device is specified on the warehouse in
ManageSoft\Distributor\CurrentVersion\WakeOnLANWizard\MaxDistance. The DWORD value defaults to 0x00010000. For a description of how "distance" is calculated, see below.
After a WOL job is sent to the managed device, the distribution server pings the managed device to determine if it has woken up. The default time from WOL job to managed device being pinged is 5 minutes. This setting is controlled by the ManageSoft\Distributor\CurrentVersion\WakeOnLANWizard\BootDelay registry setting on the warehouse, which specifies the number of seconds to wait before doing the ping (defaults to 300).

Wake-on-LAN job distribution algorithm

A WOL job is similar to any other ManageSoft distribution job. The basic flow is:

A job is generated on the warehouse in the Job Queue.
The job is sent through the distribution hierarchy as normal.
WOL jobs are sent to the distribution server with the closest IP subnet to the targeted managed device. The distance of a managed device from the distribution server is determined by the first bit that is different in the subnet address. If this result is larger than theManageSoft\Distributor\CurrentVersion\WakeOnLANWizard\MaxDistance registry setting on the warehouse, then the Wake-on-LAN job will not be attempted for the given managed device from this distribution server.
The job is processed on the target distribution server. The distribution server creates a scheduled task in MSTask to execute wolgen.exe at the appropriate time.
MSTask invokes wolgen.exe at the appointed time.
The WOL packet is sent by the selected distribution server over UDP port 1230 to the broadcast address of the subnet of the managed device that has been targeted. The packet contains the MAC address of the network card in the managed device.
wolgen.exe generates a .rev file indicating success/failure of the WOL job, which is uploaded through the distribution hierarchy.

ManageSoft Wake-on-LAN tracing

To enable WOL tracing, configure the \Program Files\ManageSoft\etap.trace file on your warehouse.

To apply this to the distribution server, copy etap.trace to mgswolgen.trace in the same directory as wolgen.exe (\Program\ files\ManageSoft\common).

Example: Configuring "MaxDistance" for WOL

In this example:

MaxDistance default = 0x00010000
Warehouse IP address = 10.31.15.3 in subnet mask 255.255.255.0, with the distribution server in the same subnet (that is, DS is 10.31.15.X)
Managed device = 10.30.11.8 (subnet mask 255.255.255.0).

1. How is MaxDistance used to determine if this machine can be woken up?

The distance is calculated as (server IP & client subnet mask) ^ client subnet (where & is the bitwise AND operator and ^ is bitwise XOR). If the DS and managed device are on the same subnet, the distance between them will be 0.

Substituting the example figures (10.31.15.3 and 255.255.255.0) ^ 10.30.11.0 = 0.1.4.0 evaluates to 0x00010400 (each octet in the IP address is 0 to 255, or two hexadecimal digits).

This must be less than MaxDistance for the MD to be woken up. Since the default MaxDistance is 0x00010000, this device is outside the MaxDistance and will not be woken.

2. If it cannot be woken up, what IP address of the MD will be woken up?

If the DS is 10.31.15.X, client subnet mask is 255.255.255.0 and MaxDistance is 0x00010000 (0.1.0.0), any MD 10.31.Y.Z can be woken up, since its distance will be 0.0.15^Y.0. Any other MD (outside 10.31) will not be woken, since its distance will be 0.1.0.0 or greater.

3. If it cannot be woken up, how do you change MaxDistance in order for the MD to be woken up?

Since the second octet differs by 1, MaxDistance should be 0.2.0.0 or 0x00020000.

ManageSoft database

The following ManageSoft tables and view are associated with WOL:

WakeOnLANTask - Keeps the start time for the WOL jobs and friendly name of the task.
WakeOnLANDistributionJob - Controls the distribution of the WOL job to the nearest distribution server for the targeted managed device. Each row represents a WOL job that has been distributed to a distribution server. Contains state of distribution job - Pending, Failed, Success. Relevant to the distribution server.
WakeOnLANStatus - Status of managed devices targeted by the WOL job. Each row represents a managed device to be woken by a WOL task from a distribution job. Includes ComputerID and State (Pending, Failed, Woken, Awake).
WakeOnLANHostInfo view - Contains network information about a managed device. Computer distinguished name, IP address, subnet mask, and MAC address.

More information

Additional information can be found in the following ManageSoft manuals:

ManageSoft Operations Guide - Chapter 6: Deployment policies - Wake on LAN
ManageSoft Reference: Configuration - Chapter 6: Rights configuration - ManageSoft for warehouse servers - Features and ManageSoft for distribution servers - Features
ManageSoft Reference: System Reference - Chapter 5: Database schema - Wake on LAN tables and views
ManageSoft Upgrade Guide: Chapter 2: Upgrading ManageSoft 6.x to ManageSoft 6.6.