~ubuntu-branches/ubuntu/maverick/ipmitool/maverick

.TH "ipmitool" "1" "" "Duncan Laurie" ""

.SH "NAME"

.LP 

ipmitool \- utility for controlling IPMI-enabled devices

.SH "SYNOPSIS"

.LP 

ipmitool [\fB\-ghcvV\fR] \fB\-I\fR \fIlan\fP \fB\-H\fR \fIhostname\fP [\fB\-L\fR \fIprivlvl\fP] [\fB\-a\fR|\fB\-E\fR|\fB\-P\fR \fIpassword\fP] <\fIexpression\fP>

.LP

ipmitool [\fB\-ghcvV\fR] \fB\-I\fR \fIlanplus\fP \fB\-H\fR \fIhostname\fP [\fB\-L\fR \fIprivlvl\fP] [\fB\-a\fR|\fB\-E\fR|\fB\-P\fR \fIpassword\fP] <\fIexpression\fP>

.LP

ipmitool [\fB\-ghcvV\fR] \fB\-I\fR \fIopen\fP <\fIexpression\fP>

.SH "DESCRIPTION"

.LP 

This program lets you manage Intelligent Platform Management Interface 

(IPMI) functions of either the local system, via a kernel device driver,

or a remote system, using IPMI V1.5 . These functions include printing 

FRU information, LAN configuration, sensor readings, and remote chassis 

power control.

.SH "OPTIONS"

.LP 

.TP 

\fB\-h\fR

Get basic usage help from the command line.

.TP 

\fB\-c\fR

Display output with comma field separator instead of spaces.  Not available with all commands.

.TP 

\fB\-V\fR

Display version information.

.TP

\fB\-v\fR

Increase verbose output level.  This option may be specified multiple times to increase the level of debug output.

.TP 

\fB\-I\fR <\fIinterface\fP>

Selects IPMI interface to use.  Possible interfaces are \fIlan\fP, \fIlanplus\fP or \fIopen\fP.

.TP 

\fB\-H\fR <\fIaddress\fP>

Remote server address, can be IP address or hostname.  This option is required for the LAN interface connection.

.TP 

\fB\-U\fR <\fIusername\fP>

Remote username, default is NULL user.

.TP

\fB\-L\fR <\fIprivlvl\fP>

Force session privilege level.  Can be CALLBACK, USER, OPERATOR, ADMIN.  Default is ADMIN.

.TP 

\fB\-a\fR

Prompt for the remote server password, 16 character maximum. This is optional for the LAN interface, if a password is not provided the session will not be authenticated.

.TP 

\fB\-E\fR

The remote server password is specified by the environment variable \fBIPMI_PASSWORD\fR. This option is intended for shell scripts.

.TP

\fB\-f\fR <\fIfile\fP>

Read remote server password from file.

.TP 

\fB\-P\fR <\fIpassword\fP>

Remote server password. \fBNote!\fR Specifying the password as a commandline option is not recommended since it will be visible in the process list.

.SH "EXPRESSIONS"

.LP

.TP

.I help

This can be used to get command-line help on ipmitool commands.  It may also be placed at the end of commands to get option usage help.

.RS

.PP

ipmitool -I open help

.br

Commands:  bmc, chassis, event, fru, lan, raw, sdr, sel, sensor, sol, userinfo, channel

.LP

.PP

ipmitool -I open chassis help

.br

Chassis Commands:  status, power, identify, policy, restart_cause, poh

.LP

.PP

ipmitool -I open chassis power help

.br

Chassis Power Commands: status, on, off, cycle, reset, diag, soft

.LP

.RE

.TP

\fIraw\fP <\fBnetfn\fR> <\fBcmd\fR> [\fBdata\fR]

This will allow you to execute raw IPMI commands.  For example to query the POH counter with a raw command:

.RS

.PP

ipmitool -v -I open raw 0x0 0xf

.br

RAW REQ (netfn=0x0 cmd=0xf data_len=0)

.br

RAW RSP (5 bytes)

.br

 3c 72 0c 00 00

.LP

.RE

.TP

.I channel

.RS

.TP

\fIauthcap\fP <\fBchannel number\fR> <\fBmax priv\fR>

This command will display information about the authentication capabilities of the selected channel at the specified privelige level.

.RS

.TP

Possible privilege levels are:

.br

1   Callback level

.br

2   User level

.br

3   Operator level

.br

4   Administrator level

.br

5   OEM Proprietary level

.LP

.RE

.TP

\fIinfo\fP [\fBchannel number\fR]

This command will display information about the selected channel.  If no channel is given it will display information about the currently used channel:

.RS

.PP

ipmitool -I open chaninfo

.br

Channel 0xf info:

.br

  Channel Medium Type   : System Interface

.br

  Channel Protocol Type : KCS

.br

  Session Support       : session-less

.br

  Active Session Count  : 0

.br

  Protocol Vendor ID    : 7154

.LP

.RE

.TP

\fIuser\fP <\fBchannel number\fR> [\fBuser number\fR]

This command will display information about configured user information on a specific LAN channel.  This command will fail on system interfaces.

.RS

.PP

ipmitool -I open channel user 6

.br

Maximum User IDs     : 4

.br

Enabled User IDs     : 1

.br

Fixed Name User IDs  : 1

.br

Access Available     : call-in / callback

.br

Link Authentication  : disabled

.br

IPMI Messaging       : enabled

.LP

.RE

.RE

.TP

.I chassis

.RS

.TP

.I status

This command returns information about the high-level status of the system chassis and main power subsystem.

.TP

.I poh

This command will return the Power-On Hours counter.

.TP

\fIidentify\fP <\fBinterval\fR>

Control the front panel identify light.  Default is 15.  Use 0 to turn off.

.TP

.I restart_cause

Query the chassis for the cause of the last system restart.

.TP

.I policy

Set the chassis power policy in the event power failure.

.RS

.TP

.I list

Return supported policies.

.TP

.I always-on

Turn on when power is restored.

.TP

.I previous

Returned to previous state when power is restored.

.TP

.I always-off

Stay off after power is restored.

.RE

.TP

.I power

Performs a chassis control command to view and change the power state.

.RS

.TP

.I status

Show current chassis power status.

.TP

.I on

Power up chassis.

.TP

.I off

Power down chassis into soft off (S4/S5 state).  WARNING: this command does not initiate a clean shutdown of the operating system prior to powering down the system.

.TP

.I cycle

This command provides a power off interval of at least 1 second.  No action should occur if chassis power is in S4/S5 state, but it is recommended to check power state first and only issue a power cycle command if the system power is on or in lower sleep state than S4/S5.

.TP

.I reset

This command will perform a hard reset.

.TP

.I diag

Pulse a version of a diagnostic interrupt (NMI) that goes directly to the processor(s).

.TP

.I soft

Initiate a soft\-shutdown of OS via ACPI by emulating a fatal overtemperature.

.RE

.RE

.TP

.I lan

.RS

.TP

\fIprint\fP <\fBchannel\fR>

Print the current configuration for the given channel.

.TP

\fIset\fP <\fBchannel\fR> <\fBparameter\fR>

Set the given parameter on the given channel.  Valid parameters are:

.RS

.TP

\fIipaddr\fP <\fBx.x.x.x\fR>

Set the IP address for this channel.

.TP

\fInetmask\fP <\fBx.x.x.x\fR>

Set the netmask for this channel.

.TP

\fImacaddr\fP <\fBxx:xx:xx:xx:xx:xx\fR>

Set the MAC adddress for this channel.

.TP

\fIdefgw\fP \fIipaddr\fP <\fBx.x.x.x\fR>

Set the default gateway IP address.

.TP

\fIdefgw\fP \fImacaddr\fP <\fBxx:xx:xx:xx:xx:xx\fR>

Set the default gateway MAC address.

.TP

\fIbakgw\fP \fIipaddr\fP <\fBx.x.x.x\fR>

Set the backup gateway IP address.

.TP

\fIbakgw\fP \fImacaddr\fP <\fBxx:xx:xx:xx:xx:xx\fR>

Set the backup gateway MAC address.

.TP

\fIpassword\fP <\fBpass\fR>

Set the null user password.

.TP

\fIsnmp\fP <\fBcommunity string\fR>

Set the SNMP community string.

.TP

\fIuser\fP

Enable user access mode.

.TP

\fIaccess\fP <\fBon|off\fR>

Set LAN channel access mode.

.TP

\fIipsrc\fP <\fBsource\fR>

Set the IP address source:

.br

none = unspecified

.br

static = manually configured static IP address

.br

dhcp = address obtained by BMC running DHCP

.br

bios = address loaded by BIOS or system software

.TP

\fIarp\fP \fIrespond\fP <\fBon|off\fR>

Set BMC generated ARP responses.

.TP

\fIarp\fP \fIgenerate\fP <\fBon|off\fR>

Set BMC generated gratuitous ARPs.

.TP

\fIarp\fP \fIinterval\fP <\fBseconds\fR>

Set BMC generated gratuitous ARP interval.

.TP

\fIauth\fP <\fBlevel,...\fR> <\fBtype,...\fR>

Set the valid authtypes for a given auth level.

.RS

Levels:

.B callback

.B user

.B operator

.B admin

.br

Types: 

.B none

.B md2

.B md5

.B key

.RE

.RE

.RE

.TP

.I fru

.RS

.TP

.I print

This command will read all Field Replacable Unit inventory data and extract such information as serial number, part number, asset tags, and short strings describing the chassis, board, or product. 

.RE

.TP

.I sdr

.RS

.TP

.I info

This command will query the BMC for information about the SDR.

.TP

.I list

This command will read the SDR and extract sensor information, then query each sensor and print its name, reading, and status.

.RE

.TP

.I pef

.RS

.TP

.I info

This command will query the BMC and print information about the PEF supported features.

.TP

.I status

This command prints the current PEF status (the last SEL entry processed by the BMC, etc).

.TP

.I policy

This command lists the PEF policy table entries.  Each policy entry describes an alert destination.  A policy set is a collection of table entries.  PEF alert actions reference policy sets.

.TP

.I list

This command lists the PEF table entries.  Each PEF entry relates a sensor event to an action.  When PEF is active, each platform event causes the BMC to scan this table for entries matching the event, and possible actions to be taken.  Actions are performed in priority order (higher criticality first).

.RE

.TP

.I sensor

.RS

.TP

.I list

This command will list sensors and thresholds in a wide table format.

.TP

\fIget\fP <\fBid\fR> ... [\fBid\fR]

This command will print info for sensors specified by name.

.TP

\fIthresh\fP <\fBid\fR> <\fBthreshold\fR> <\fBsetting\fR>

This allows you to set a particular sensor threshold value.  The sensor is specified by name.

.RS

.TP

Valid thresholds are:

.br

unr   Upper Non-Recoverable

.br

ucr   Upper Critical

.br

unc   Uperr Non-Critical

.br

lnc   Lower Non-Critical

.br

lcr   Lower Critical

.br

lnr   Lower Non-Recoverable

.LP

.RE

.RE

.TP

.I sel

.RS

.TP

.I info

This command will query the BMC for information about the SEL and its contents.

.TP

.I clear

This command will clear the contents of the SEL.  It cannot be undone so be careful.

.TP

.I list

This command will list the contents of the SEL.

.RE

.TP

.I session

.RS

.TP

\fIinfo\fP <\fBparameter\fR> [\fBargument\fR]

This command will query the BMC for information about its session capabilities and current sessions.  Valid parameters are:

.RS

.TP

\fIactive\fP 

Queries the BMC for information about the current session.  That is, the session used to execute this command.

.TP

\fIall\fP

Queries the BMC for information about all active sessions

.TP

\fIid\fP <\fBid\fR>

Queries the BMC for information about the session with the specified ID.  The ID should be specified in hex.

.TP

\fIhandle\fP <\fBhandle\fR>

Queries the BMC for information about the session with the specified handle.  The handle should be specified in hex.

.RE

.RE

.TP

.I sol

.RS

.TP

\fIinfo\fP [\fBchannel\fR]

Retrieve information about the Serial-Over-LAN configuration on the specified channel.  If no channel is given, it will display SOL configuration data for the currently used channel.

.RE

.RS

.TP

\fIset\fP <\fBparameter\fR> <\fBvalue\fR> [\fBchannel\fR]

Configure parameters for Serial Over Lan.  If no channel is given, it will display SOL configuration data for the currently used channel.  Configuration parameter updates are automatically guarded with the updates to the set-in-progress parameter.

.RS

.TP

Valid parameters and values are:

.br

.TP

set-in-progress  

set-complete set-in-progress commit-write

.TP

enabled

true false

.TP

force-encryption

true false

.TP

force-authentication

true false

.TP

privilege-level

user operator admin oem

.TP

character-accumulate-level

Decimal number given in 5 milliseconds increments

.TP

character-send-threshold

Decimal number

.TP

retry-count

Decimal number.  0 indicates no retries after packet is transmitted.

.TP

retry-interval

Decimal number in 10 millisend increments.  0 indicates that retries should be sent back to back.

.TP

non-volatile-bit-rate

serial, 19.2, 38.4, 57.6, 115.2.  Setting this value to serial indiates that the BMC should use the setting used by the IPMI over serial channel.

.TP

volatile-bit-rate

serial, 19.2, 38.4, 57.6, 115.2.  Setting this value to serial indiates that the BMC should use the setting used by the IPMI over serial channel.

.LP

.RE

.RE

.RS

.TP

.I activate

This command causes ipmitool to enter Serial Over LAN mode, and is only available when using the lanplus interface.  An RMCP+ connection is made to the BMC, the terminal is set to raw mode, and user input is sent to the serial console on the remote server.  On exit, the the SOL payload mode is deactivated and the terminal is reset to its original settings.

.RS

.TP

Special escape sequences are provided to control the SOL session:

~.   Terminate connection

.br

~^Z  Suspend ipmitool

.br

~B   Send break

.br

~~   Send the escape character by typing it twice

.br

~?   Print the supported escape sequences

.LP

.RE

.RE

.RS

.TP

.I deactivate

This command deactivates Serial Over LAN mode on the BMC.  Exiting Serial Over LAN mode should automatically cause this command to be sent to the BMC, but in the case of an unintentional exit from SOL mode, this command may be necessary to reset the state of the BMC.

.RE

.RE

.SH "OPEN INTERFACE"

.LP 

The ipmitool \fIopen\fP interface utilizes the MontaVista OpenIPMI kernel device driver.  This driver is present in 2.5.57 and later development kernels and in 2.4.21pre1 and later stable kernels.  There are also IPMI driver kernel patches for different versions available from the OpenIPMI homepage.

.LP 

The following kernel modules must be loaded in order for ipmitool to work:

.TP 

.B ipmi_msghandler

Incoming and outgoing message handler for IPMI interfaces.

.TP 

.B ipmi_kcs_drv

An IPMI Keyboard Controler Style (KCS) interface driver for the message handler.

.TP 

.B ipmi_devintf

Linux character device interface for the message handler.

.LP 

Once they are loaded there will be a dynamic char device entry that must exist at \fB/dev/ipmi0\fR.  Usually if this is the first dynamic device it will be major number \fB254\fR and minor number \fB0\fR so you would create the dev entry with:

.LP 

.I mknod /dev/ipmi0 c 254 0

.LP 

In order to force ipmitool to make use of the OpenIPMI device interface you can specifiy it on the command line:

.PP 

ipmitool \-I open <expression>

.SH "LIPMI INTERFACE"

.LP

The ipmitool \fIlipmi\fP interface uses the Solaris x86 IPMI kernel device driver.

.LP

You can tell ipmitool to use the Solaris IPMI driver with the \fB-I\fR option:

.PP

ipmitool \-I lipmi <expression>

.SH "LAN INTERFACE"

.LP 

The ipmitool \fIlan\fP interface communicates with the BMC over an Ethernet LAN connection using UDP under IPv4.  UDP datagrams are formatted to contain IPMI request/response messages with a IPMI session headers and RMCP headers.

.LP 

IPMI\-over\-LAN uses version 1 of the Remote Management Control Protocol (RMCP) to support \fIpre\-OS\fP and \fIOS\-absent\fP management.  RMCP is a request\-response protocol delivered using UDP datagrams to port 623.

.LP 

The LAN interface is an authenticatiod multi\-session connection; messages delivered to the BMC can (and should) be authenticated with a challenge/response protocol with either straight password/key or MD5 message\-digest algorithm.  ipmitool will attempt to connect with administrator privilege level as this is required to perform chassis power functions.

.LP 

You can tell ipmitool to use the lan interface with the \fB\-I\fR option:

.PP 

ipmitool \-I lan \-H <hostname> [\-U username] [\-P password] <expression>

.LP 

A hostname \fBmust\fR be given on the command line in order to use the lan interface with ipmitool.  The password field is optional; if you do not provide a password on the command line, ipmitool will attempt to connect without authentication.  If you specify a password it will use MD5 authentication if supported by the BMC and straight password/key otherwise.

.SH "LANPLUS INTERFACE"

.LP

Like the \fIlan\fP interface, the \fIlanplus\fP interface communicates with the BMC over an Ethernet LAN connection using UDP under IPv4.  The difference is that the \fIlanplus\fP interface uses the RMCP+ protocol as described in the IMPI v2.0 specification.  RMCP+ allows for improved authentication and data integrity checks, as well as encryption and the ability to carry multiple types of payloads.  Generic Serial Over LAN support requires RMCP+, so the ipmitool \fIsol activate\fP command requires the use of the \fIlanplus\fP interface.

.LP

RMCP+ session establishment uses a protocol call RAKP (Remote Authenticated Key-Exchange Protocol) which allows the negotiation of many options.  ipmitool does not yet allow the user to specify the value of every option, defaulting to the most obvious settings, marked as required in the v2.0 specification.  Authentication and integrity HMACS are produced with SHA1, and encryption is performed with AES-CBC-128.  Role-level logins are not supported.  ipmitool must be configured with the appropriate option for the \fIlanplus\fP interface to be available, as it is not enabled by default.  This interface currently requires the OpenSSL library.

.LP

You can tell ipmitool to use the lanplus interface with the \fB\-I\fR option:

.PP 

ipmitool \-I lanplus \-H <hostname> [\-U username] [\-P password] <expression>

.LP 

The options available for the \fIlanplus\fP inteface are identical to those available for the \fIlan\fP inteface.

.SH "FILES"

.TP 

.I /dev/ipmi0

This character device file is used by the OpenIPMI kernel driver.

.SH "EXAMPLES"

.LP 

If you want to remotely control the power of an IPMI\-over\-LAN enabled system you can use:

.LP 

ipmitool \-I lan \-H 192.168.1.1 \-P password chassis power on

.br

Chassis Power Control: Up/On

.LP 

ipmitool \-I lan \-H 192.168.1.1 \-P password chassis power status

.br

Chassis Power is on

.SH "AUTHOR"

.LP 

Duncan Laurie <duncan@iceblink.org>

.SH "SEE ALSO"

.LP 

.TP 

IPMItool Homepage

http://ipmitool.sourceforge.net

.TP 

Intelligent Platform Management Interface Specification

http://www.intel.com/design/servers/ipmi/spec.htm

.TP 

OpenIPMI project (MontaVista IPMI kernel driver)

http://openipmi.sourceforge.net