NAME

PowerEdge::RAC - Remotely manage your PowerEdges with Perl

SYNOPSIS

  use PowerEdge::RAC;


  my $server = new PowerEdge::RAC(
                host => '192.168.0.120',
                user => 'root',
                password => 'calvin'
  );

  $server->test_email('root');
  $server->power_on();

  $| = 1;

  while(!$server->is_powered_on()) {
      print ".";
      sleep 1;
  };

  print "\n", $server->post_log();

  print $server->read_sensors_txt(), "\n";

DESCRIPTION

PowerEdge::RAC supplies some functions that you may find useful to remotely manage PowerEdge servers.

PowerEdge servers can be remotely managed with the aid of special hardware known as RAC cards (Remote Access Controller, DRAC II and III, ERA, ERA/O). The RAC can be accessed through utilities that run atop the OS, but also directly, through its own NIC. Giving you the ability to start a server even from a hung or powered-down state. For this last vital function Dell provides only a slowish and somewhat flaky interface tying you down to running Java applets in an unfree browser on an unfree OS. This module tries to remedy that.

METHODS

new([host => $h,] [user => $u,] [password => $p,] [session_id => $s])

Constructs a new PowerEdge::RAC object with specified parameters. This does not yet establish a session with the specified RAC. That is delayed until you use any of the methods below. If you must you can also call establish_session() explicitely.

Warning: currently all other methods return everything in one scalar string. In future this will likely change to lists or hashes for those methods that return multiple pieces of information (lines) like rac_log(), post_log(), sysinfo(), sessions(), arp() etc.

session_id() or session_id($sid)

Return the session_id or set it to the value $sid

Note. The RAC keeps a table of active sessions of the form

session_id user state IPaddress time

with only 16 slots. Each new login uses up another slot. Since a session expires only after a few minutes this table could easily fill up. That is why PowerEdge::RAC tries to reuse the session_id on subsequent requests. If you want to preserve sessions across instances of PowerEdge::RAC you'll have to store the session externally. E.g. in a file or in a cookie when you run PowerEdge::RAC from a CGI environment.

sessions()

Returns the RAC's active sessions.

sysinfo()

Return information about the system as stored in the RAC. Note that you cannot set the information this way. You'll have to use racadm or OMSA for that. Returns a list of info lines in list context, so you can say print $server->sysinfo(); In scalar context returns a hashref. Optionally takes one argument and prints the value of relevant system info item only. Example: print $server->sysinfo('Firmware version');

multi_info()

Return information about the system as stored in the RAC. This command is new in the 2.0 firmware and appears to be aimed at replacing getsysinfo. It has the same information only in a more structured way. Returns a hashref. Call Dumper($href) if you want to know what is there .. Subject to change.

is_powered_on()

Returns 1 when the server is in powered-on state, 0 otherwise.

power_off()

Power off the server. WARNING. This does NOT allow the OS to shutdown gracefully. In fact the RAC appears to be incapable of doing that. Although it accepts commands like `serveraction graceshutdown' that would suggest otherwise, none of appear to be implemented ... After giving power_off() the RAC simply turns of the power to the system. Only use this function when the OS is down and filesystems are unmounted. Then again, if your system hangs and you are 60 miles away from the console this might just save your day ... UPDATE: The new 2.00 firmware (released 23 jan 2003) does allow this. See the next command.

graceshutdown()

Shutdown the OS gracefully if possible. For this to work the RAC must be able to communicate with the main system. In particular o the esm module must be loaded o racser must be running o racsrvc must be running If this succeeds the command that will be invoked is shutdown -h now You then still have to call power_off() to power off the server. You'ld better sleep 60 seconds before that or risk killing the machine while it's shutting down. This only works with RAC firmware >= 2.00.

power_on()

Power on the server. Has no effect when the server is already powered on.

power_cycle()

Power off the server. Wait. Then power it on again.

test_email('racuser')

Makes the RAC send a test e-mail to the adres configured for racuser. The specified user must already have been configured in the RAC (again using either racadm or the OMSA) or the test will fail. Also a mail server must be configured and that server must be setup to relay mail from the RAC's IP address. 





arp()


Show the RAC's arp cache.




ping($ip)


Make the RAC ping the specified IP address.




netstat()


Takes one argument, a number from '1' to '9'.
Show netstat output for the specified interface.
Will return a summary for all interfaces when invoked without arguments.




post_log()


Returns the post messages.




event_log()


Takes one argument and returns the specified number of messages lines
from the RAC's System Event Log. As one string in scalar context 
or as a list of hash references in list context. Each line (hash)
has: severity, sensor_id, message, date, (key, tr, pc).




clear_event_log()


Clears the RAC's System Event Log.




rac_log()


Takes one argument and returns the specified number of messages 
from the RAC log. The format of the message lines varies between 
different hardware/firmware revisions.




clear_rac_log()


Clears the RAC log.




rac_reset()


Resets the RAC card (not the server!). After this it will take approx. 
45 seconds before the card is again ready to accepts commands.




get_gmt()


Get the date and time from the RAC. Note that before the time is set
the RAC uses a cyclic counter that only counts 24 hours. This seems to 
be indicated by the string DSU appearing in the result in those cases.
The time on the RAC can be set by either the following set_gmt()
command or e.g. with the racadm utility.




set_gmt()


Set the date and time on the RAC. This needs to be set after the card
has been reset, either by rac_reset() or e.g. after the card was 
disconnected from power. Takes two arguments, the desired time in seconds 
sinds the epoch, 00:00:00 UTC Jan 1th 1970, and an offset in seconds.
Without arguments uses the localtime of the systems this module runs on.




read_sensors_txt()


Produces a formatted text version of the sensor readings. For all sensors or 
for the list of sensorids that can optionally be specified as an argument. 
If you want control over the formatting of the sensor output use one of 
the following functions and maybe using this function as a starting point.




read_sensors_by_id()


Takes a list of sensorid's as argument and returns a hash of hashreferences
that map sensorproperties to values, for the respective sensorid's. 
Without arguments this tries to determine a list of all sensors that
are available and returns those along with their values. 
When the server is powered off the sensors cannot reliably be detected. 
In this case read_sensors() will return an empty list (or scalar).
See the caveat under sensorlist() below.




read_sensors_by_name()


Same as the previous function only sensors can be specified by their
name. You can use the next function sensorid_to_name() to obtain
a list of sensorid's and names for your hardware. This function is provided 
mainly to improve the readability of your code. Beware of the overhead
your program may incur because of the need to obtain the mapping
from the RAC. See the next function.




sensorid_to_name()


This returns a hash mapping sensorid's to names. When passed a list
of sensorid's it returns the names of the sensors, again as a list.
Sensorsid's and names can vary between firmware and hardware versions
and system model. Therefore the mapping has to be obtained from the RAC
at least once. It costs about 8 seconds to query all sensors in a PE1650 
for their name. As long as hardware and firmware don't change this 
mapping won't either so it is cached by this module. This should be safe 
as long as you don't swap machines in between queries ;-)


If you are going to query a lot of machines regularly, the fastest way is
to create a list of sensorids for your hard/firmware once and hardcode 
that in your scripts. Easily obtaining that list is exactly what this
function is for.  See the caveat under sensorlist() below.




sensorlist()


Returns a list of sensorid's. Not very useful in itself but it
can be used as input for the read_sensors_by_id() function above. 
Mainly a faster way than read_sensors_by_id() to compare the available 
sensors between different hardware.
This list isn't very reliable though. The sensorids returned do not 
necessarily reflect actual hardware found in your system. When queried 
for their properties some return no values others cause long (up to 
200 seconds) timeouts.




getniccfg()


Returns the RAC's NIC configuration: IP address (which you already 
have to know to do use this function ;-)), netmask and gateway.




setniccfg()


Set the RAC's NIC configuration: takes the following arguments:
IP address, netmask and gateway. The change will only take effect
after a reset. So you could change all your cards at once and call 
rac_reset() on each when ready. After a reset it takes about 
thirty seconds for the RAC to come up with its new IP.




fwupdate()


RAC firmware update.  This function takes two arguments:
The IP address of the TFTP server and the directory on the TFTP server 
where the firmware update resides. For example:
$rac->fwupdate('192.168.1.1', '/rac/firmware/22/');


Note that the name of the actual file that the RAC tries to transfer
depends on system model and should not be included as the firmware itself 
appends it. Therefore be sure to end the directory name with a slash.


The firmware isn't very clever at detecting various errors that may
cause the TFTP transfer to fail and simply times out after ninety
seconds. This module makes no attempt to improve this situation.


WARNING: this function may take several minutes to complete.
It involves flashing new firmware to the RAC so the author strongly advises
you to not unplug the machine from power during an update !
The author has never encountered any problems and the mechanism appears
to be quite resilient against errors but your mileage may vary. 
Use at your own risk.


See the next function too.




fwupdate_status()


The fwupdate update function will print messages informing the user about 
the progress of an update if stdout is a terminal.
This isn't possible when it is invoked in a web environment.
The fwupdate_status function can be used to poll the status of an update
and thus makes it possible to provide immediate feedback when the
user presses a button for example.




enable_dhcp()


Set the RAC's NIC configuration to use DHCP. This will only take
effect after a reset. So you could set all your cards to DHCP and
call rac_reset() when ready.






EXAMPLES


See the demo scripts included with the source package.






LICENSE


PowerEdge::RAC is free software; you may redistribute it and/or modify
it under the same terms as Perl itself.  For more information see the 
``README'' or ``Artistic'' files provided with the Perl distribution.






AUTHOR & COPYRIGHT


Copyright (c) 2003 Harold van Oostrom. All rights reserved.






SEE ALSO


the MIME::Base64 manpage, the LWP::UserAgent manpage, the XML::Simple manpage, the Digest::MD5 manpage,the Crypt::SSLeay documentation