ePowerSwitch Tools for Perl

by John Walker


ePowerSwitch

Every so often some wag starts a rumour about the imminent announcement of a new "Internet-ready" product for the home: an e-refrigerator that orders groceries on-line so you never run out of anything, an e-toaster that sends you an E-mail when the toast pops up, an e-toilet which . . . never mind. Well, here is an Internet-ready outlet strip, and it's not a joke. In fact, it's extremely handy in setting up a high-reliability site and implementing "lights-out" remote administration of data centres.

The Neol ePowerSwitch provides four independently-controllable outlets. It can be connected to any 10Base-T network with its built-in RJ-45 jack (after being initially configured via an RS-232 port), and controlled over a local network or the Internet with a Web browser which connects to its built in mini Web server. The outlet strip as a whole and each individual power socket are password protected to prevent malicious users from turning off equipment connected to it. (The power strip does not, however, support secure connections, so there's a risk of passwords being "sniffed" by third parties. Unless off-site control of the power strip is absolutely required, it's wise to block packets directed to it from the Internet at your firewall.)

While browser-based control is fine for interactive operation of the power strip, many potential applications require automated control by programs. You might, for example wish to switch equipment on and off according to a schedule, or have one or more machines on your network monitor the status of network hardware (modems, routers, firewalls, wireless access points, etc.) and power cycle components detected to have failed in order to reset them. Real system administrators prefer to accomplish such tasks with Perl programs. This page describes tools to assist in writing such programs.

The ePowerSwitch.pm Perl module implements an object-oriented interface to the ePowerSwitch, permitting either complete control over all four outlets or restricted control of a single outlet granted by its outlet-specific password. The ePowerSwitch program is a command-line application implemented in Perl which serves both as an example of a program using ePowerSwitch.pm, and as a stand-alone utility in its own right, suitable for interactive use or in applications implemented as shell scripts. Both the command line application and Perl module are described, in manual page format (extracted from the "pod" language documentation embedded in the Perl programs), in the following sections.

Downloading and Installation

The ePowerSwitch Perl utilities may be downloaded from the following link:
ePowerSwitch.tar.gz: Gzipped TAR archive (13 Kb)

Included in the archive are the command line utility ePowerSwitch, the Perl module ePowerSwitch.pm, and manual pages for the two programs extracted from the documentation embedded within them. You can use these files in the directory in which you extracted them or install them in your system's library directories to make them available to all users.

Manual Pages

ePowerSwitch Command Line Utility

SYNOPSIS

ePowerSwitch [--copyright] [--help] [--host hostname] [--ip address] [--password password] [--port portno] [--socket socketno] [--verbose] [--version] command...


DESCRIPTION

The ePowerSwitch is a TCP/IP compatible power strip with four outlets which can be controlled via HTTP requests to an embedded mini Web server. For details about the ePowerSwitch, see the manufacturer's site:

http://www.neol.com/

This program provides command-line control of an ePowerSwitch, operating it with the companion ePowerSwitch.pm Perl module, which you can use to directly control the switch from your own Perl programs. Options are used to specify the address (via IP address or host name) of the switch, and the password granting access to all sockets or a specific socket, followed by or more commands to query the status of the switch and/or turn sockets on or off.


OPTIONS

All options may be abbreviated to their shortest unambiguous prefix.

--copyright
Display copyright information.

--help
Display how to call information.

--host hostname
Specify the address of the ePowerSwitch by its hostname (either a locally-defined host, or by a fully qualified domain name).

--ip address
Specify the IP address of the ePowerSwitch in ``dotted quad'' (for example, 192.168.33.111) notation. You must specify the address with either the --host or --ip options, but not both.

--password password
Specify the password used to access the switch. This may be either the global administration password permitting access to any of the sockets on the switch, or the restricted ``user'' password which grants access only to a single socket. If the latter is specified, the --socket option must also be specified to indicate which socket the password governs.

--port portno
Specify the port used to access the mini Web server in the ePowerSwitch. If omitted, the default HTTP port of 80 is used.

--socket socketno
If the password given in the --password option is the ``user'' password for a specific socket, the --socket option must be supplied to indicate which socket the password pertains to. When the --socket option is specified, no socket number is given after socket control commands. Sockets are numbered 1 through 4.

--verbose
Generate verbose output to indicate what's going on.

--version
Display version number.


COMMANDS

Following the option specifications, one or more commands to query or change the status of the switch may be specified. Commands which pertain to a specific socket (for example, to turn it on or off) are followed by the socket number (from 1 to 4) to which they apply if the --password used to log into the switch was the global administration password granting access to all sockets. If the ``user'' password for a specific socket was specified along with a --socket option giving the socket number it governs, no socket number is specified after such commands. In the following command descriptions the notation ``[socket]'' is used to indicate these conditional socket number specifications.

List
Display status of ePowerSwitch on standard output. If the global administration password is given, the complete status of the switch and all sockets is given, for example:
 IP: 192.168.33.111  Port: 80
      Password: 'venona'
   Logged in.
   Switch name: Commrack1
   Socket 1: Firewall.2 On
   Socket 2: Firewall.3 On
   Socket 3: Hub-DMZ On
   Socket 4: Hub-LAN Off

If the ``user'' password for a specific socket is specified, only the state of that socket will be shown:

 IP: 192.168.33.111  Port: 80
      Password: 'venona2'  Socket: 2
   Logged in.
   Switch name: Commrack1
   Socket 2: Firewall.3 On

Name
Display name of ePowerSwitch on standard output.

Off [socket]
Turn socket off.

On [socket]
Turn socket on.

Query [socket]
Exit with return code 1 if the socket is on, 0 if it's off. ePowerSwitch exits immediately with the status code, ignoring any subsequent commands on the command line.

Reboot [socket]
Turn socket off for 60 seconds, then back on. This can be used for rebooting equipment such as network appliances (routers, switches, firewalls) which can be restarted by cycling power to them. Note that ePowerSwitch does not wait for the 60 second interval to elapse; timing is performed within the power switch itself, and a successful status is given as soon as the command is accepted.

Socketname [socket]
Display name assigned to a specific socket on standard output.

Status [socket]
Print 1 if socket is on, 0 if off. The status is printed to standard output.

Toggle [socket]
Turn socket on if off, off if on.


VERSION

This is ePowerSwitch version 1.0, released on November 8th, 2003. The current version of this program is always posted at http://www.fourmilab.ch/webtools/ePowerSwitch/.


AUTHOR

    John Walker
    http://www.fourmilab.ch/


BUGS

This program operates the ePowerSwitch via the ePowerSwitch.pm Perl module, which should be supplied with it. If you're running this program from a library directory on your PATH, the module must be installed in a location where Perl can find it. The ePowerSwitch.pm module, in turn, requires the LWP (``Library for the World Wide Web in Perl'') module; if it isn't installed on your system, you can obtain the current version from CPAN http://www.cpan.org/.

The term ``socket'' is used herein exclusively to refer to the outlets on the power strip into which you plug stuff, not network sockets, notwithstanding that the latter are used in the process of controlling the former.

Please report any bugs to bugs at fourmilab.ch


SEE ALSO

ePowerSwitch.pm Perl module.


COPYRIGHT

This program is in the public domain.

 

ePowerSwitch.pm Perl Module

SYNOPSIS

    use ePowerSwitch;
    
    $eps = ePowerSwitch->new($ip_address, $port,
    	    	    	     $password, $socket);
    $eps->login();
    $eps->logout();
    $are_we = $eps->loggedin();
    $ok = $eps->switch($socket_number, $command);
    $eps->describe($filehandle);
    $swname = $eps->switchname();
    $sockname = $eps->socketname($socket_number);
    $on_or_off = $eps->socketstat($socket_number);
    $vmode = $eps->verbose($mode);


DESCRIPTION

The ePowerSwitch is a TCP/IP compatible power strip with four outlets which can be controlled via HTTP requests to an embedded mini Web server. For details about the ePowerSwitch, see the manufacturer's site:

http://www.neol.com/

This module provides an object-oriented interface to an ePowerStrip. A program can create one or more ePowerSwitch objects, each bound to a specific network-accessible switch (or an individual socket on a switch), and then query status and switch power on and off with method calls.


METHODS

$eps = ePowerSwitch->new($ip_address, $port, $password, $socket);
The new method is the constructor for the ePowerSwitch class. It creates a new ePowerSwitch with IP address $ip_address and port $port. You can create an ePowerSwitch object to access all outlets on the switch by specifying the administration password for $password and 0 for $socket (or omitting the $socket argument), or to access a single socket by supplying the ``user'' password for that socket and its socket number (1 through 4) as $socket. The constructor returns a new ePowerSwitch object which may be manipulated through the following methods.

$eps->login();
Logs in to to the power switch (either for administrative access to all sockets or a specific socket, depending on the $password and $socket given when the object was created with new). You must log in before using any methods which query the status of the switch or turn sockets on or off. Returns 1 if the login was successful, 0 if the login failed.

$eps->logout();
Logs out from the power switch. Returns 1 if the logout was successful, 0 if it fails. You can log in and out as many times as you wish.

$are_we = $eps->loggedin();
Returns 1 if currently logged in to the switch, 0 if not logged in.

$ok = $eps->switch($socket_number, $command);
Sends a command, specified by a single character $command argument, to socket $socket_number. If you created the ePowerSwitch with the administrative password, $socket_number can be any socket (1 through 4). If you gave the password for a single socket in the call to new, the $socket_number must be the same as the $socket specified in the new call.

Commands are as follows:

"0"
Turn socket off.

"1"
Turn socket on.

t
Toggle: if socket is off, turn it on; if on, turn it off.

r
Reboot: turn socket off, wait 60 seconds, then turn the socket back on. After a reboot command is given, the switch method returns immediately--it does not wait until the socket is turned back on.

The switch method returns 1 if the command was executed normally and 0 if an error occurred.

$eps->describe($filehandle);
The properties and status of the ePowerSwitch are printed on the file opened on $filehandle or, if $filehandle is omitted, STDOUT. (f you want to print the status on a filehandle OFILE, pass a reference to it: describe(\*OFILE).) The arguments used to create the object with new are shown, then the login status. If logged in to the switch, its name, and the name and on/off status of each of the sockets is shown if logged in with the administrative password. If logged in with the password for a single socket, only the status of that socket is shown.

$swname = $eps->switchname();
Returns a string containing the name of the ePowerSwitch. You must be logged in to retrieve the switch name; either the administrative password or the password for a single socket entitles you to query the name of the switch.

$sockname = $eps->socketname($socket_number);
Returns the name of the socket specified by $socket_number (1 through 4). You must be logged in; if logged in with the administrative password, you may obtain the name of any socket. If logged in with the password for a single socket, only the name of that socket may be retrieved.

$on_or_off = $eps->socketstat($socket_number);
Returns 1 if the specified $socket_number is on, 0 if it is off. You must be logged in to query the socket status. If logged in with the administrative password, you can query the status of any socket (1 through 4); if logged in with the password for a specific socket, only that socket's status may be obtained.

$vmode = $eps->verbose($mode);
By default, errors in communicating with the switch simply return a zero status to the caller. (Invalid arguments, however, use die to report the error.) If you set verbose mode by calling verbose with a nonzero $mode argument, diagnostic messages will be printed on standard output for all operations, successful or not. The previous setting of verbose mode is returned, permitting you to save and restore it


VERSION

This is ePowerSwitch version 1.0, released on November 8th, 2003.


AUTHOR

    John Walker
    http://www.fourmilab.ch/


BUGS

This module requires the LWP (``Library for the World Wide Web in Perl'') module; if it isn't installed on your system, you can obtain the current version from CPAN.

The term ``socket'' is used herein exclusively to refer to the outlets on the power strip into which you plug stuff, not network sockets, notwithstanding that the latter are used in the process of controlling the former.

Please report any bugs to bugs at fourmilab.ch


SEE ALSO

ePowerSwitch command line utility.


COPYRIGHT

This program is in the public domain.


by John Walker
November, 2003

Fourmilab Home Page