\input texinfo
@setfilename wol.info
@settitle Wake On LAN client
@afourpaper
@finalout
@setcontentsaftertitlepage


@set UPDATED 18 April 2004
@set EDITION 0.7.1
@set VERSION 0.7.1


@comment Tell install-info what to do
@dircategory Net utilities
@direntry
* Wol: (wol).              A Wake On LAN client.
@end direntry


@ifinfo
This file documents wol @value{VERSION}, the Wake On LAN client.

@c man begin COPYRIGHT
Copyright (C) 2001,2002,2003,2004 Thomas Krennwallner @email{krennwallner@@aon.at}

This document may be distributed and modified under the terms of the GNU
General Public License.

This manual is free software; you may redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2, or (at your option) any later version.

This manual is distributed in the hope that it will be useful, but without any
warranty; without even the implied warranty of merchantability or fitness for a
particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available on the World Wide Web at
the GNU website. You can also obtain it by writing to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
@c man end
@end ifinfo


@titlepage
@title wol
@subtitle Wake On LAN client
@subtitle Edition @value{EDITION}
@subtitle @value{UPDATED}
@author Thomas Krennwallner

@ignore
@c man begin SYNOPSIS
wol [@var{OPTION}] @dots{} @var{MAC-ADDRESS} @dots{}
@c man end
@c man begin AUTHOR
Written by Thomas Krennwallner <krennwallner@aon.at>.
@c man end
@c man begin SEEALSO
GNU info entry for @file{wol}.
@c man end
@end ignore


@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001,2002,2003,2004 Thomas Krennwallner
@email{krennwallner@@aon.at}

This document may be distributed and modified under the terms of the GNU
General Public License.

This manual is free software; you may redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2, or (at your option) any later version.

This manual is distributed in the hope that it will be useful, but without any
warranty; without even the implied warranty of merchantability or fitness for a
particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available on the World Wide Web at
the GNU website. You can also obtain it by writing to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
@end titlepage


@contents


@node Top, Basics, (dir), (dir)
@top wol - Wake On LAN client

@c man begin DESCRIPTION
This manual gives you an introduction into @code{wol}, the Wake On LAN client.
It remotely turns on computers that supports Magic Packet technology
(also known as Wake On LAN).

Some workstations support SecureON password feature. These machines only
wake up if you provide the correct password. @code{wol} also provides this
feature.
@c man end

See @url{http://ahh.sourceforge.net/wol/} for updates and further readings.

@c man begin BUGS
Please report bugs to @email{krennwallner@@aon.at}. Feel free to send bug
reports, translations, improvement suggestions and patches to this email
address.
@c man end


@menu
* Basics::                        Wake On LAN basics
* Description::                   Description
* Options::                       Options to wol
* Examples::                      Examples for program invocation
@end menu


@node Basics, Description, Top, Top
@chapter Basics

This chapter explains the Wake On LAN basics.

@menu
* How does it work::              Technical explanation of Wake On LAN
* Wake On LAN requirements::      What is needed to have Wake On LAN?
* Magic Packet::                  How does a Magic Packet look like?
@end menu


@node How does it work, Wake On LAN requirements, Basics, Basics
@section How does it work

If you are intending to switch on a computer, you need his @dfn{MAC-ADDRESS}.
This is the 48 bit hardware address of the network card which is written as
x:x:x:x:x:x, where x is a hexadecimal number between 0 and ff which represents
one byte of the address, which is in network byte order (big-endian).

@code{wol} assembles a hardware address to a Magic Packet and
sends it over the network. The Wake On LAN enabled computer provides enough
power for the NIC to listen to the attached network and waits for arriving
Wake On LAN packets. The NIC recognizes the wake up call and turns on.


@node Wake On LAN requirements, Magic Packet, How does it work, Basics
@section Wake On LAN requirements

@code{wol} broadcasts so-called Magic Packet frames across a network to
wake up hardware that understands such packets. These are normally NIC's with
Wake On Lan function. To make use of this feature your motherboard and your
power supply have to support Wake On LAN. But there are still some things
needed to have a working Wake On LAN setup. Most PCI NIC's come with a so-called
WOL-connector and a 3 pin wire. This wire has to be connected from the
motherboards WOL connector to the NIC's. After this basic hardware requirements
you have to enable Wake On LAN in your systems BIOS (or whatever called). If
you have a builtin network card with WOL support, you don't have to wire,
enabling WOL in the BIOS should be enough.


@node Magic Packet, , Wake On LAN requirements, Basics
@section Magic Packet

A Magic Packet is any packet which contains a special sequence of a six byte
header (six times 0xff) and then 16 times the repetition of the intent to wake
up @var{MAC-ADDRESS} within this packet. The optional SecureON password is
attached at the end of the packet. So if you want to wake up the computer with
the hardware address @code{00:E0:98:13:45:E2} the corresponding Magic Packet
looks like:

@multitable {ff} {ff} {ff} {ff} {ff} {ff} {ff}
@item @strong{00} @tab ff @tab ff @tab ff @tab ff @tab ff @tab ff
@item @strong{06} @tab 00 @tab E0 @tab 98 @tab 13 @tab 45 @tab E2
@item @strong{12} @tab 00 @tab E0 @tab 98 @tab 13 @tab 45 @tab E2
@item @strong{**} @tab  @tab  @tab  @tab  @tab  @tab
@item @strong{96} @tab 00 @tab E0 @tab 98 @tab 13 @tab 45 @tab E2
@end multitable

To simplify things @code{wol} encapsulates such Magic Packets inside an
broadcast UDP packet. This gives various benefits over raw ethernet frames, one
is OS interoperability. Another one is the fact that you don't need to be
root to wake up a machine since sending raw ethernet packets requires
superuser privileges.


@node Description, Options, Basics, Top
@chapter Description

@code{wol} is a feature rich Wake On LAN utility. Beyond the basic Wake On LAN
function it also provides the ability to send a SecureON password along with
the Magic Packet. Another useful feature is the capability to read MAC
addresses and the corresponding IP addresses/hostnames from a file or from
standard input. You can optionally specify the corresponding UDP destination
port and a SecureON password.

There are also additional @code{AWK} scripts provided that parse ISC dhcpd's
@file{dhcpd.conf} and bootpc's @file{bootptab} and outputs them in @code{wol's}
native fileformat.  They are called @code{wol-dhcpdconf} and
@code{wol-bootptab}.  You can invoke them as following: @code{wol-dhcpdconf <
/etc/dhcpd.conf | wol -} or @code{wol-bootptab < /etc/bootptab | wol -}.

An example of usage is @code{wol MAC-ADDRESS} which assembles a Magic
Packet which is intended to wake up the NIC with hardware address
@var{MAC-ADDRESS}. See @ref{Examples} for additional examples.

If you do not provide the argument in @var{MAC-ADDRESS} syntax @code{wol}
tries to lookup the ethernet address in the @file{ethers} file. See your
systems documentation for setting up your @file{ethers} file.


@node Options
@chapter Options

This is a list of @code{wol's} command line option.

@c man begin OPTIONS
@table @samp
@item --help

Print a summary of the command line options.


@item -V
@itemx --version

Print the version number of @code{wol}.


@item -h HOST
@itemx --host=HOST
@itemx -i HOST
@itemx --ipaddr=HOST

Broadcast packet to this IP address or hostname. This is important if your wol
client is a multihomed host and you want to send only to one subnet
(default IP address is @code{255.255.255.255}).


@item -p NUM
@itemx --port=NUM

Send packet with this destination port @var{NUM}. This option is important if
your packet filter would block the default destination port @code{40000}.


@item -f FILE
@itemx --file=FILE

Read hardware addresses, IP addresses/hostnames, optional ports and SecureON
password from file @file{FILE}. If @file{FILE} is @var{-} @code{wol} reads from
stdin.


@item -

Read hardware addresses, IP addresses, optional ports and optional SecureON
password from stdin. So you can extract @var{MAC-ADDRESSES} from any source
and pipe the data into @code{wol} so.


@item -v
@itemx --verbose

Turns on verbose output.


@item -w NUM
@itemx --wait=NUM

Waits @var{NUM} milliseconds between Magic Packets. Also known as fuse health
pack.


@item --passwd[=PASS]

Send a magic packet with SecureON password feature. @var{PASS} is written as
x-x-x-x-x-x, where x is a hexadecimal number between 0 and ff which represents
one byte of the password.

If you don't provide @var{PASS} @code{wol} prompts you for a password.

To set the password of your SecureON capable NIC, you can use
@code{ethtool} (@url{http://www.sourceforge.net/projects/gkernel/}).

@end table
@c man end


@node Examples
@chapter Examples

@c man begin EXAMPLES
@table @samp
@item wol 00:4F:49:07:0B:5F 00:4F:50:06:12:4F

Sends packets addressed to 255.255.255.255:40000 and is intended to wake up
the machines with hardware addresses 00:4F:49:07:0B:5F and 00:4F:50:06:12:4F.


@item wol --host=192.168.3.255 -p 69 00:4F:49:07:0B:5F 

Sends packet addressed to 192.168.3.255:69 and is intended to wake up the
NIC with hardware address 00:4F:49:07:0B:5F.


@item wol --passwd=09-e6-f5-f3-dc-4e 00:4F:49:07:0B:5F

Sends packet addressed to 255.255.255.255:40000 with SecureON password
09-e6-f5-f3-dc-4e.


@item wol --passwd beblebroox

Prompts you for a SecureON password and looks up your @file{ethers} file for
the ethernet address of host beblebroox.


@item wol -f /path/to/my/ethernet/addresses

Read hardware addresses and corresponding IP addresses/hostnames from file
@file{/path/to/my/ethernet/addresses}.

File looks like:

@c FIXME: add @cartouche -> texi2pod.pl is buggy
@example
# comments
MAC-ADDRESS  IP-ADDRESS
MAC-ADDRESS  HOSTNAME
MAC-ADDRESS  IP-ADDRESS:port
# even more comments
MAC-ADDRESS  IP-ADDRESS:port	SecureON-password
@end example


@item wol-dhcpdconf < /etc/dhcpd.conf | wol -

@code{wol-dhcpdconf} filters MAC addresses and corresponding
IP addresses/hostnames from @file{/etc/dhcpd.conf} (config file of ISC dhcpd)
and outputs it in macfile format (native wol format). @code{wol} sends the
corresponding Magic Packets.

Valid dhcp entries:

@c FIXME: add @cartouche -> texi2pod.pl is buggy
@example
host zaphod
@{
  hardware ethernet 11:ab:e3:5f:7f:8c;
  fixed-address 10.0.0.1;
@}

host marvin
@{
  hardware ethernet 22:ba:3e:f5:f7:c8;
  fixed-address marvin.is.depp.at;
@}
@end example

@code{wol-dhcpdconf} will then generate following output:

@c FIXME: add @cartouche -> texi2pod.pl is buggy
@example
11:ab:e3:5f:7f:8c 10.0.0.1
22:ba:3e:f5:f7:c8 marvin.is.depp.at
@end example


@item wol-bootptab < /etc/bootptab | wol -

@code{wol-bootptab} filters MAC addresses and corresponding
IP addresses/hostnames from @file{/etc/bootptab} (config file of bootpc)
and outputs it in macfile format (native wol format). @code{wol} sends the
corresponding Magic Packets.

Valid bootp entries:

@c FIXME: add @cartouche -> texi2pod.pl is buggy
@example
xterm1:ha=0x00e4ff76553e:ht=ethernet:bf=vmlinuz:ip=xterm1:tc=.default:

xterm2:ha=0x00e5ee6744e3:ht=ethernet:bf=vmlinuz:ip=10.0.0.25:tc=.default:
@end example

@code{wol-bootptab} will then generate following output:

@c FIXME: add @cartouche -> texi2pod.pl is buggy
@example
00:e4:ff:76:55:3e xterm1
00:e5:ee:67:44:e3 10.0.0.25
@end example

@end table
@c man end


@bye
