Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::ILO(3)	      User Contributed Perl Documentation	   Net::ILO(3)

NAME
       Net::ILO	- Interface to HP Integrated Lights-Out

SYNOPSIS
	   use Net::ILO;

	   my $ilo = Net::ILO->new({
	       address	   => '192.168.128.10',
	       username	   => 'Administrator',
	       password	   => 'secret',
	   });

	   # returns 'on' or 'off'
	   my $power_status = $ilo->power or die $ilo->error;

	   $ilo->power('off');
	   $ilo->power('reset');

	   my $mac01  =	$ilo->mac01;
	   my $mac02  =	$ilo->mac02;
	   my $macilo =	$ilo->macilo;

	   # see METHODS for complete listing

DESCRIPTION
       The Net::ILO module is an interface to a	subset of Hewlett-Packards
       Integrated Lights-Out out-of-band management system. HP's API is	XML-
       based and cumbersome to use; this module	aims to	simplify accessing the
       iLO from	Perl while retaining as	much functionality as possible.

       Not every iLO function is implemented here, however most	common ones
       are.

       This module is based on the sixth edition of the	"HP Integrated Lights-
       Out Management Processor	Scripting and Command Line Resource Guide" and
       has been	successfully tested with the following server types:

	   DL360/G3
	   DL360/G4
	   DL360/G4p
	   DL360/G5
	   DL360/G6
	   DL360/G7 ** see note	below
	   DL380/G3
	   DL380/G4
	   DL380/G5

       It should work with other server	models;	feedback (either way) is much
       appreciated.

       Note: iLO 3 support is in BETA, and still being tested.

INTERFACE QUIRKS
       Wherever	possible, I have mimicked HP's API to maintain consistency.
       However,	certain	names have been	changed	to reflect a more common
       usage, for example, what	HP calls 'DNS_NAME' is referred	to as
       'hostname' by Net::ILO.

       Boolean types are represented in	the documentation as either 'Yes' or
       'No'.  When ILO returns a boolean response, it is shortened to 'Y' or
       'N'. Either form	is acceptable when passing a value to your server's
       iLO.

       Power and UID statuses are an exception;	their states can be either
       'on' or 'off'.

METHODS
       The interface is	extensive and methods have been	grouped	by function
       for easier digestion.

   GENERAL METHODS
       new()
	       my $ilo = Net::ILO->new({
		   address     => '192.168.131.185',
		   username    => 'Administrator',
		   password    => 'secret',
	       });

	       # can also use a	hash rather than hashref

	       my $ilo = Net::ILO->new(
		   address     => '192.168.131.185',
		   username    => 'Administrator',
		   password    => 'secret',
	       );

	   Creates a new ILO object, but does not attempt a connection.
	   Parameters are passed as an anonymous hash or hashref.

	   Required paramters:

	   None, however trying	to call	any method without setting at least
	   the address,	username and password will fail. You may however, set
	   these later using their associated methods if you want.

	   Optional parameters:

	     address - hostname	or IP of remote	machine's iLO
		port - default is 443, you may specify another port here
	    username - username	for logging in to iLO
	    password - password	for logging in to iLO
	     version - version of iLO API to use, '1', '2' or '3'. versions 1 and 2 are
		       the same	and correspond to iLO and iLO 2	respectively, if version
		       '3' is used the module will use the new iLO 3 interface.	if not
		       specified the version will be detected automatically (recommended)
	       debug - debug level (default 0).	Increasing this	number (to a maximum of	3)
		       displays	more diagnostic	information to the screen, such	as the
		       data sent to and	received from iLO, the Perl data structure
		       created from the	XML received, etc.

       address()
	       # connect to a different	machine
	       $ilo->address('192.168.131.186');

	       print $ilo->power;

	   Returns or sets the address of the remote machine to	connect	to.

	   Please note that a lot of the data gathered (power state excluded)
	   is cached.  Connecting to machine A,	calling	mac01(), then
	   connecting to machine B and calling mac01() will return the same
	   data. It is recommended that	you instantiate	a new object for each
	   server you connect to.

       port()
	       # your company's	machines use a non-standard SSL	port
	       $ilo->port(447);

	   Returns or sets the port to connect to the remote server on.	 Port
	   443 is assumed if not specified.

       username()
	       $ilo->username('jane_doe');

	       # do some non-admin tasks
	       # power-cycling machine requires	elevated privileges

	       $ilo->username('Administrator');
	       $ilo->power('reset');

	   Returns or sets the username	to use when logging in.

       password()
	       # try both passwords, we	forgot which one was good
	       $ilo->password('foobar');

	       # all methods return false on failure
	       if (!$ilo->power) {

		   $ilo->password('barfoo');

	       }

	   Returns or sets the password	to use when logging in.

       error()
	       $ilo->address('127.0.0.1');

	       my $power_status	= $ilo->power or die $ilo->error;

	       Unable to establish SSL connection with 127.0.0.1:443
	       [IO::Socket::INET6 configuration	failederror:00000000:lib(0):func(0):reason(0)] at /somescript.pl line 14.

	   Returns the last error reported, if any. All	methods	return false
	   when	an error is encountered, and $ilo->error is set	to the error
	   message reported by the remote machine. Note	that on	success,
	   error() is not cleared, and so should not be	used to	determine
	   whether an error occurred.

	   Every single	method which interacts with the	remote machine may
	   throw an error, so it is very important that	you check to ensure
	   the command succeeded. Error	checking has been omitted from most
	   examples for	brevity.

   POWER MANAGEMENT
       power()
	       my $power_status	= $ilo->power;

	       if ($power_status eq 'off') {

		   $ilo->power('on');

	       }
	       else {

		   $ilo->power('reset');

	       }

	   Calling this	method without parameters will return the current
	   power state of the machine, either 'on' or 'off'. Passing any of
	   the following to this method	will attempt to	change the power
	   state:

	       on
	       off
	       reset

       power_consumption()
	       # something like	340
	       print $ilo->power_consumption;

	   Returns the current power consumption in watts.

	   This	method is only available when using iLO	2 and above. Calling
	   it on an older machine will cause the following error to be
	   returned:

	   Method not supported	by this	iLO version

   NETWORKING
       hostname
	       # default is ILO0000000000 where	000... is your serial number
	       my $machine_name	= $ilo->hostname;

	   Returns the hostname	of the remote machine. This is also the	name
	   shown when logging in to the	iLO interface, in the SSL cert,	etc.

	   For information on changing the hostname, see the network() method.

       domain_name()
	       # maybe ilo.somecompany.net
	       my $domain_name = $ilo->domain_name;

	   Returns the DNS domain name of the remote machine.

	   For information on changing the domain name,	see the	network()
	   method.

       dhcp_enabled()
	       # either	'Y' or 'N'
	       print $ilo->dhcp_enabled;

	   Returns 'Y' if DHCP is enabled for the iLO networking, and 'N' if a
	   static IP address is	in use.

       ip_address()
	       # network dependent, something like 192.168.1.129
	       print $ilo->ip_address;

	   Returns the IP address of the iLO processor.	Note that the IP can
	   NOT be changed using	this method. For managing network settings,
	   see network().

       subnet_mask()
	       # network dependent, something like 255.255.255.0
	       print $ilo->subnet_mask;

	   Returns the subnet mask of the iLO processor.

       gateway()
	       # you guessed it, network dependent
	       print $ilo->gateway;

	   Returns the default gateway in use for the iLO networking.

       network()
	       $ilo->network({
		   name		   => 'testbox01',
		   domain_name	   => 'mydomain.com',
		   dhcp_enabled	   => 'no',
		   ip_address	   => '192.168.128.10',
		   subnet_mask	   => '255.255.255.0',
		   gateway	   => '192.168.128.1',
	       }) or die $ilo->error;

	   Allows you to modify	the network configuration of the iLO
	   processor. The following parameters are allowed, see	individual
	   methods above for more detail:

	       name
	       domain_name
	       dhcp_enabled
	       ip_address
	       subnet_mask
	       gateway

	   If any parameter is not specified, current values are used.

	   Setting dhcp_enabled	to 'yes' causes	all IP related settings	to
	   have	no effect.

	   If the IP address is	changed	here, address()	is updated with	the
	   new information.

	   Networking changes cause the	iLO processor to reset,	it should
	   become available again within 30 seconds.

	   The rationale behind	seperate methods for viewing and changing
	   network settings is as follows:

	   Network configuration generally needs to be modified	as a package,
	   for example,	changing both the IP address and default gateway.
	   Without a separate method, calling the ip_address() method as a
	   setter could	cause you to lose connectivity.

   SYSTEM INFORMATION
       model()
	       # ProLiant DL380	G5
	       print $ilo->model;

	   Returns the model name of the machine.

       serialID()
	       # unique	to your	machine
	       print $ilo->serialID;

	   Returns the serial number of	the remote machine.

       cpus()
	       my $cpus	= $ilo->cpus;

	       print "Number of	CPUs: ", scalar	@$cpus,	"\n\n";

	       foreach my $cpu (@$cpus)	{

		   print "  CPU: ", $cpu->{name}, "\n";
		   print "Speed: ", $cpu->{speed}, "\n";
		   print "Cores: ", $cpu->{cores}, "\n";

	       }

	       # yields	the following on a single CPU Xeon:
	       #
	       # Number	of CPUs: 1
	       #
	       #   CPU:	Proc 1
	       # Speed:	2000 MHz
	       # Cores:	4 of 4 cores; 4	threads

	   Returns arrayref containing information about each CPU. Included is
	   the CPU name	(eg. Proc 1, Proc 2, etc.), speed in MHz and number of
	   cores.

       ramslots()
	       my $ramslots = $ilo->ramslots or	die $ilo->error;

	       print "DIMM slots: ", scalar @$ramslots,	"\n\n";

	       foreach my $slot	(@$ramslots) {

		   print " Slot: ", $slot->{location}, "\n";
		   print " Size: ", $slot->{size},     "\n";
		   print "Speed: ", $slot->{speed},    "\n" if defined $slot->{speed};

	       }

	       # yields	the following on a DL360/G5 with 8 GB of RAM:
	       #
	       # DIMM slots: 8
	       #
	       # Slot: DIMM 1A
	       # Size: 2048 MB
	       # Speed:	667 MHz
	       #
	       # Slot: DIMM 2C
	       # Size: 1024 MB
	       # Speed:	667 MHz
	       #
	       # Slot: DIMM 3A
	       # Size: 2048 MB
	       # Speed:	667 MHz
	       #
	       # Slot: DIMM 4C
	       # Size: 1024 MB
	       # Speed:	667 MHz
	       #
	       # Slot: DIMM 5B
	       # Size: 1024 MB
	       # Speed:	667 MHz
	       #
	       # Slot: DIMM 6D
	       # Size: not installed
	       #
	       # Slot: DIMM 7B
	       # Size: 1024 MB
	       # Speed:	667 MHz
	       #
	       # Slot: DIMM 8D
	       # Size: not installed

	   Returns arrayref containing information about installed memory
	   modules. Includes slot name,	module size and	module speed. Speed is
	   undefined when slot is empty.

       mac01()
	       my $eth0_mac = $ilo->mac01;

	   Returns the mac address associated with the machine's primary NIC
	   (aka	eth0).

	   This	method is not supported	by pre-generation 4 hardware.

       mac02()
	       my $eth1_mac = $ilo->mac02;

	   Returns the mac address associated with the machine's secondary NIC
	   (aka	eth1).

	   This	method is not supported	by pre-generation 4 hardware.

       mac03()
	       my $eth2_mac = $ilo->mac03;

	   Returns the mac address associated with the machine's tertiary NIC,
	   if installed. Note that mac addresses for add-on cards will not be
	   available via this method.

       mac04()
	       my $eth3_mac = $ilo->mac04;

	   Returns the mac address associated with the machine's quaternary
	   NIC,	if installed. Note that	mac addresses for add-on cards will
	   not be available via	this method.

       macilo()
	       my $ilo_mac = $ilo->macilo;

	   Returns the mac address associated with the machine's iLO
	   interface.

	   This	method is not supported	by pre-generation 4 hardware.

       biosdate()
	       # format	is 11/30/2006
	       print $ilo->biosdate;

	   Returns the release date of the system's BIOS.

   SERVER HEALTH
       fans()
	       my $fans	= $ilo->fans;

	       foreach my $fan (@$fans)	{

		   print "    Name: ", $fan->{name},	 "\n";
		   print "Location: ", $fan->{location}, "\n";
		   print "   Speed: ", $fan->{speed},	 "\n";
		   print "    Unit: ", $fan->{unit},	 "\n";
		   print "  Status: ", $fan->{status},	 "\n\n";

	       }

	       #     Name: Fan Block 1
	       # Location: Power Supply
	       #    Speed: 34
	       #     Unit: Percentage
	       #   Status: Ok
	       #
	       #     Name: Fan Block 2
	       # Location: CPU 2
	       #    Speed: 29
	       #     Unit: Percentage
	       #   Status: Ok
	       #
	       #     Name: Fan Block 3
	       # Location: CPU 1
	       #    Speed: 34
	       #     Unit: Percentage
	       #   Status: Ok

	   Returns arrayref containing the status of the fan block(s)
	   installed in	the system. 'status' will be 'Ok' or 'Failed'.

       temperatures()
	       my $temperatures	= $ilo->temperatures;

	       foreach my $sensor (@$temperatures) {

		   print "    Name: ", $sensor->{name},	    "\n";
		   print "Location: ", $sensor->{location}, "\n";
		   print "   Value: ", $sensor->{value},    "\n";
		   print "    Unit: ", $sensor->{unit},	    "\n";
		   print " Caution: ", $sensor->{caution},  "\n";
		   print "Critical: ", $sensor->{critical}, "\n";
		   print "  Status: ", $sensor->{status},   "\n\n";

	       }

	       #     Name: Temp	1
	       # Location: I/O Board
	       #    Value: 49
	       #     Unit: Celsius
	       #  Caution: 80
	       # Critical: 90
	       #   Status: Ok
	       #
	       #     Name: Temp	2
	       # Location: Ambient
	       #    Value: 19
	       #     Unit: Celsius
	       #  Caution: 80
	       # Critical: 90
	       #   Status: Ok
	       #
	       #     Name: Temp	3
	       # Location: CPU 1
	       #    Value: 32
	       #     Unit: Celsius
	       #  Caution: 80
	       # Critical: 90
	       #   Status: Ok
	       #
	       #     Name: Temp	4
	       # Location: CPU 1
	       #    Value: 32
	       #     Unit: Celsius
	       #  Caution: 80
	       # Critical: 90
	       #   Status: Ok
	       #
	       #     Name: Temp	5
	       # Location: Power Supply
	       #    Value: 28
	       #     Unit: Celsius
	       #  Caution: 80
	       # Critical: 90
	       #   Status: Ok

	   Returns arrayref containing the status of the temperature sensor(s)
	   installed in	the system. 'status' will be 'Failed' if the
	   temperature exceeds the critical threshold.

       power_supplies()
	       my $power_supplies = $ilo->power_supplies;

	       foreach my $power_supply	(@$power_supplies) {

		   print "  Name: ", $power_supply->{name},   "\n";
		   print "Status: ", $power_supply->{status}, "\n\n";

	       }

	       #   Name: Power Supply 1
	       # Status: Ok

	   Returns arrayref containing the status of the power supplies
	   installed in	the system. 'status' will be 'Ok' or 'Failed'.

   ILO INFORMATION AND MANAGEMENT
       reset()
	       # iLO web interface is hung, try	resetting it
	       $ilo->reset;

	   Resets the iLO management processor.

       license()
	       # 25 characters,	according to HP
	       $ilo->license('1111122222333334444455555');

	   Activates iLO advanced pack licensing. An error will	be returned if
	   the key is not valid	or if it is already in use.

       fw_type()
	       # either	'iLO', 'iLO2' or 'iLO3'
	       print $ilo->fw_type;

	   Returns the type of iLO management processor	in the remote machine.
	   Possible values are 'iLO', 'iLO2' and 'iLO3', depending on how
	   modern the server is.

       fw_version()
	       # something like	1.26
	       print $ilo->fw_version;

	   Returns the version of iLO firmware currently running.

       fw_date()
	       # format	is Nov 17 2006
	       print $ilo->fw_date;

	   Returns the date the	iLO firmware was released.

       ssh_status()
	       # either	'Y' or 'N'
	       print $ilo->ssh_status;

	       # disable SSH access to iLO
	       $ilo->ssh_status('No');

	   Returns or modifies whether SSH access is enabled on	the iLO.
	   Gives 'Y' if	SSH is enabled and 'N' if SSH is disabled.

       ssh_port()
	       if ($ilo->ssh_port == 22) {

		   $ilo->ssh_port(12345);

	       }

	   Returns or sets the port iLO	will listen on for incoming SSH
	   connections.	 This should be	an integer between 0 and 65535.

	   Changing the	SSH port causes	the iLO	processor to reset, it should
	   become available again within about 30 seconds.

       http_port()
	       # default is 80
	       print $ilo->http_port;

	       $ilo->http_port(8000);

	   Returns or sets the port iLO's http service listens on. Valid port
	   numbers are between 0 and 65535.

	   Changing the	HTTP port causes the iLO processor to reset, it	should
	   become available again within about 30 seconds.

       https_port()
	       # default is 443
	       print $ilo->https_port;

	       $ilo->https_port(554);

	   Returns or sets the port iLO's https	service	listens	on. Valid port
	   numbers are between 0 and 65535.

	   Changing the	HTTPS port causes the iLO processor to reset, it
	   should become available again within	about 30 seconds.

       session_timeout()
	       # default is 30
	       print $ilo->session_timeout;

	   Returns the current session timeout in minutes. This	applies	to all
	   sessions, eg. http, https, ssh, etc.

   USER	MANAGEMENT
       add_user()
	       # add a user with admin privileges
	       $ilo->add_user({
		   name	    => 'John Doe',
		   username => 'jdoe',
		   password => 'secret',
		   admin    => 'Yes',
	       });

	       # add a regular user with no privileges
	       $ilo->add_user({
		   name	    => 'Jim Beam',
		   username => 'jbeam',
		   password => 'secret',
	       });

	       # add a regular user with full privileges (aside	from managing users)
	       #
	       # for a detailed	discussion of what each	privilege provides, please see
	       # the document 'HP Integrated Lights-Out	Management Processor Scripting and
	       # Command Line Resource Guide'
	       #
	       # if unspecified, default for each privilege is 'No'.

	       $ilo->add_user({
		   name	    => 'Jack Daniels',
		   username => 'jdaniels',
		   password => 'secret',
		   remote_console_privilege => 'Yes',
		   reset_privilege	    => 'Yes',
		   virtual_media_privilege  => 'Yes',
		   config_ilo_privilege	    => 'Yes',
		   view_logs_privilege	    => 'Yes',
		   clear_logs_privilege	    => 'Yes',
		   update_ilo_privilege	    => 'Yes',
	       })

	   Adds	an iLO user. Admin users have full priveleges, including the
	   ability to add and remove other users. Non-admin users have
	   configurable	privileges which default to disabled. The subset of
	   permissions implemented is listed above.  Users can log in to iLO
	   via any interface, ie. HTTPS, SSH, etc. When	adding a non-admin
	   user, passing in the	parameter admin	=> 'No'	is also	acceptable.

       mod_user()
	       # change	current	user's password
	       # in this case username is optional

	       $ilo->mod_user({
		   password => 'supersecret',
	       });

	       # change	another	user's password
	       # this requires administrator privileges

	       $ilo->mod_user({
		   username => 'guest',
		   password => 'changem3!',
	       });

	   Method for modifying	existing user accounts.	Currently this method
	   is only able	to change user's passwords; it cannot change
	   permission levels.

	   Passwords may consist of up to 39 printable characters. If you
	   exceed the maximum password length, an error	to that	effect will be
	   returned.

	   If you update the current user's password the stored	password used
	   for logging in will be updated automatically.

       del_user()
	       # you're	fired!
	       $ilo->del_user('jbeam');

	   Removes an existing user from the iLO.

   MISCELLANEOUS
       uid()
	       if ($ilo->uid eq	'on') {

		   $ilo->uid('off');

	       }

	   Get the status of or	control	the machine's UID light.

	   Called without parameters simply returns the	current	status,	either
	   'on'	or 'off'.

	   You may pass	values 'on' or 'off' to	this method however be careful
	   not to set the uid light to on when it is currently on, and vice
	   versa, as this could	throw an error,	depending on iLO firmware
	   version.

	   An error will be returned if	you pass an invalid state.

	       $ilo->uid('blinking') or	die $ilo->error;

	       State blinking is not valid at /somescript.pl line 13.

DIAGNOSTICS
       "User login name	was not	found"
	   General authentication error, eg. bad username or password when
	   logging in.

	   Could also mean you attempted to change the settings	(eg. password)
	   for a user which doesn't exist

       "Method not supported by	this iLO version"
	   Either your machine / iLO firmware version is too old, or the
	   method you called requires a	more advanced license than you have.

       "State %s is not	valid"
	   An invalid UID state	was passed to uid(). Valid states are 'on' and
	   'off'.

       "Unable to establish SSL	connection with	%s:%d [%s]"
	   An error occurred while connecting to iLO. The message in brackets
	   is propagated from IO::Socket::SSL, and is rarely useful.

       "Error transmitting command to server"
	   A connection	was established, but something went wrong while
	   sending the command to the remote iLO. Try reconnecting, and	ensure
	   that	your network settings are correct.

       "No response received from remote machine"
	   A connection	was established	and a command successfully sent	to the
	   iLO,	but no data was	received. Again, ensure	that your network
	   settings are	correct.

	   There could also be something wrong with the	remote iLO management
	   processor.  Troubleshooting is beyond the scope of this document.

       "Error parsing response:	%s"
	   An error occurred while parsing the XML response from the iLO. The
	   error message is propagated from XML::Simple, and could mean	HP
	   changed the iLO API.

DEPENDENCIES
	   IO::Socket::SSL
	   XML::Simple

AUTHOR
       Nicholas	Lewis, "<nick.lewis at gmail.com>"

BUGS
       Please report any bugs or feature requests to "bug-net-ilo at
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-ILO>.  I will be
       notified, and then you'll automatically be notified of progress on your
       bug as I	make changes.

SUPPORT
       You can find documentation for this module with the perldoc command.

	   perldoc Net::ILO

       You can also look for information at:

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-ILO>

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/Net-ILO>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/d/Net-ILO>

       o   Search CPAN

	   <http://search.cpan.org/dist/Net-ILO>

COPYRIGHT & LICENSE
       Copyright 2011 Nicholas Lewis, all rights reserved.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2011-08-01			   Net::ILO(3)

NAME | SYNOPSIS | DESCRIPTION | INTERFACE QUIRKS | METHODS | DIAGNOSTICS | DEPENDENCIES | AUTHOR | BUGS | SUPPORT | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::ILO&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help