ipmipower(8)

."############################################################################# ."$Id: ipmipower.8.in,v 1.71.6.3 2007/08/24 16:32:48 chu11 Exp $ ."############################################################################# ." Copyright (C) 2003 The Regents of the University of California. ." Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). ." Written by Albert Chu <chu11@llnl.gov> ." UCRL-CODE-155698 ." ." This file is part of Ipmipower, a remote power control utility. ." For details, see http://www.llnl.gov/linux/. ." ." Ipmipower is free software; you can 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 of the License, or (at your option) ." any later version. ." ." Ipmipower 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. ." ." You should have received a copy of the GNU General Public License along ." with Ipmipower; if not, write to the Free Software Foundation, Inc., ." 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. ."############################################################################

NAME
ipmipower - IPMI power control utility

SYNOPSIS
ipmipower [OPTIONS]

DESCRIPTION
ipmipower allows users to remotely power on, off, cycle, hard reset, get a power status query, perform a pulse diagnostic interrupt, or initiate a soft-shutdown of the OS via ACPI through the IPMI over LAN protocol. See IPMI over LAN below for more information on IPMI. When a power command (--on, --off, --cycle, --reset, --stat, --pulse, or --soft) is specified on the command line, ipmipower will attempt to run the power command on all hostnames listed on the command line then exit. If no power commands are specified on the command line, ipmipower will run in interactive mode. Interactive mode gives the user a command line interface to enter various commands. Details of the interactive command line interface can be found below under INTERACTIVE COMMANDS. See EXAMPLES below for examples of how ipmipower is commonly used.

BASIC OPTIONS
The following options are the most common options used with ipmipower.

-h, --hostnames host1,host2,...
    Specify the list of remote hosts to be controlled by ipmipower. This option is required if a power command (--on, --off, --cycle, --reset, --stat, --pulse, or --soft) is specified on the command line. Hostnames may be specified in a range format; see HOST RANGES below.

-u, --username name
    Sets the username to use when authenticating with the remote host. The user must have OPERATOR or ADMINISTRATOR privilege to run the --on, --off, --reset, --cycle, --pulse, or --soft power control commands. The user only needs USER privileges to determine the power status of the machine through --stat. If not specified, a null (i.e. anonymous) username is assumed.

-p, --password pw
    Sets the password to use when authenticating with the BMC. If not specified, a null password is assumed.

-P, --password-prompt
    Prompt for password to avoid possibility of listing it in process lists.

-k, --k-g str
    Sets the K_g BMC Key to use when authenticating with the BMC for ipmi 2.0. If not specified, a null key is assumed. To input the key in hexadecimal form, prefix the string with '0x'. E.g., the key 'abc' can be entered with the either the string 'abc' or the string '0x616263'

-K, --k-g-prompt
    Prompt for K_g to avoid possibility of listing it in process lists. To input the key in hexadecimal form, prefix the string with '0x'.

-n, --on
    Power on the target hosts.

-f, --off
    Power off the target hosts.

-c, --cycle
    Power cycle the target hosts.

-r, --reset
    Reset the target hosts.

-s, --stat
    Get power status of the target hosts.

-j, --pulse
    Send power diagnostic interrupt to target hosts.

-m, --soft
    Initiate a soft-shutdown of the OS via ACPI.

-H, --help
    Output help menu and exit.

-V, --version
    Output version and exit.

-X, --config file
    Specify alternate configuration file.

ADVANCED OPTIONS
The following advanced options are used to change the default behavior of ipmipower.

-a, --authentication-type str
    Sets the IPMI 1.5 authentication type to use with ipmipower. The currently available authentication types are "auto", "none", "straight_password_key", "md2", and "md5". If not specified, ipmipower uses "auto" authentication, which will automatically select the most secure authentication mechanism available from the remote machine.

-l, --privilege str
    Sets the privilege type to use with ipmipower. The currently available privilege types are "auto", "user", "operator", and "admin". If not specified, ipmipower uses "auto", which will automatically select the minimal privilege required for the power control operation selected. Atleast the "operator" is required for --on, --off, --cycle, --reset, --pulse, or --soft. The "user" privilege is sufficient for --stat.

-R, --ipmi-version version
    Set the IPMI protocol version to use. The currently available versions are "auto", "1.5", and "2.0". If not specified, ipmipower uses "auto", which will try find an IPMI protocol version that is suitable. IPMI 1.5 is given weight over IPMI 2.0.

-T, --cipher-suite-id id
    Set the IPMI 2.0 Cipher Suite ID to use. The Cipher Suite ID identifies a set of authentication, integrity, and confidentiality algorithms to use for IPMI 2.0 communication. The authentication algorithm identifies the algorithm to use for session setup, the integrity algorithm identifies the algorithm to use for session packet signatures, and the confidentiality algorithm identifies the algorithm to use for payload encryption. If not specified ipmipower uses the "auto" cipher suite, which will automatically select the most secure sipher suite available from the remote machine. The following cipher suite id's are currently supported:

    auto - Select the most secure cipher suite available from the remote machine

    0 - Authentication Algorithm = None; Integrity Algorithm = None; Confidentiality Algorithm = None

    1 - Authentication Algorithm = HMAC-SHA1; Integrity Algorithm = None; Confidentiality Algorithm = None

    2 - Authentication Algorithm = HMAC-SHA1; Integrity Algorithm = HMAC-SHA1-96; Confidentiality Algorithm = None

    3 - Authentication Algorithm = HMAC-SHA1; Integrity Algorithm = HMAC-SHA1-96; Confidentiality Algorithm = AES-CBC-128 ." .sp ." 4 - Authentication Algorithm = HMAC-SHA1; Integrity Algorithm = HMAC-SHA1-96; Confidentiality Algorithm = xRC4-128 ." .sp ." 5 - Authentication Algorithm = HMAC-SHA1; Integrity Algorithm = HMAC-SHA1-96; Confidentiality Algorithm = xRC4-40

    6 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = None; Confidentiality Algorithm = None

    7 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = HMAC-MD5-128; Confidentiality Algorithm = None

    8 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = HMAC-MD5-128; Confidentiality Algorithm = AES-CBC-128 ." .sp ." 9 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = HMAC-MD5-128; Confidentiality Algorithm = xRC4-128 ." .sp ." 10 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = HMAC-MD5-128; Confidentiality Algorithm = xRC4-40

    11 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = MD5-128; Confidentiality Algorithm = None

    12 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = MD5-128; Confidentiality Algorithm = AES-CBC-128 ." .sp ." 13 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = MD5-128; Confidentiality Algorithm = xRC4-128 ." .sp ." 14 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = MD5-128; Confidentiality Algorithm = xRC4-40

-g, --on-if-off
    The IPMI specification does not require the power cycle or hard reset commands to turn on a machine that is currently powered off. This option will force ipmipower to issue a power on command instead of a power cycle or hard reset command if the remote machine's power is currently off.

-A, --wait-until-on
    The IPMI specification allows power on commands to return prior the power on actually taking place. This option will force ipmipower to regularly query the remote BMC and return only after the machine has powered on.

-B, --wait-until-off
    The IPMI specification allows power off commands to return prior the power off actually taking place. This option will force ipmipower to regularly query the remote BMC and return only after the machine has powered off.

-C, --consolidate-output
    Consolidate ipmipower output. Consolidated output can be used to shorten output if the number of nodes being power controlled is quite large. However, hostrange output will only output after all machines have completed their power control operation. See HOST RANGES below.

-E, --eliminate
    Eliminate hosts determined as undetected by ipmidetect. This attempts to remove the common issue of execution timing out due to several nodes being removed from service in a large cluster. The ipmidetectd daemon must be running on the node executing the command. Only works in non-interactive mode. See HOST RANGES below for additional information.

-W, --workaround-flags str
    Informs ipmipower to use one of the several possible workarounds to get around vendor specific IPMI compliance issues. Multiple workarounds can be specified separated by commas. For information on available workarounds, see WORKAROUNDS below.

-D, --debug
    Turn on debugging output.

-I, --ipmidump
    Turn on IPMI packet dump output. Warning, the dump output can get extremely long.

-M, --rmcpdump
    Turn on RMCP packet dump output. Warning, the dump output can get extremely long.

-L, --log
    Turn on logging. Default logfile is /tmp/ipmipower.PID, where PID is the current process id.

-F, --logfile
    Change current logfile.

NETWORK OPTIONS
The following options are used to change the behavior of ipmipower's network behavior.

-t, --timeout ms
    Sets the timeout in milliseconds. Ipmipower uses the timeout value to determine when to give up on a power control command. If not specified, a default timeout of 20000 milliseconds (20 seconds) is used.

-y, --retry-timeout ms
    Sets the retry-timeout in milliseconds. IPMI over LAN requires a series of packets to be sent back and forth to a remote host BMC. When a response to any individual packet is not received after retry-timeout milliseconds, ipmipower will retry sending that packet. If not specified, packet retransmissions will occur after 400 milliseconds (0.4 seconds). The value "ms" must be less than the timeout length specified with --timeout. Packet retransmissions can be disabled by setting the retry-timeout length to 0. Note how this option differs from the "--timeout" option above. The "--timeout" option refers to the entire amount of time the IPMI protocol has to complete a power control operation. The "--retry-timeout" option refers to the amount of time any individual packet within the IPMI protocol has to complete.

-q, --retry-wait-timeout ms
    Sets the retry-wait-timeout in milliseconds. The retry-wait-timeout is similar to the 'retry-timeout' above, but is used specifically for power completion verification in the "--wait-until-on" and "--wait-until-off" options.

-b, --retry-backoff-count num
    After every retry-backoff-count retransmissions, ipmipower will increase the retry-timeout length by another factor for the duration of the current power control operation. This is done to reduce network traffic and allow BMC buffers to empty. If not specified, retry-backoff-count is 8. Retransmission backoff can be disabled by setting the retry backoff count to 0.

-i, --ping-interval ms

-z, --ping-timeout ms
    When running in interactive mode, ipmipower will send RMCP (Remote Management Control Protocol) ping discovery messages every ping-interval milliseconds to discover all remote hosts and confirm its support of IPMI. Power comamnds cannot be sent to a host until it is discovered (or possibly re-discovered). A remote host is considered undiscovered if the host does not respond to RMCP ping messages within ping-timeout milliseconds. When a host is considered undiscovered, power control commands will not be sent to it. If not specified, ping-interval is 5000 milliseconds (5 seconds) and ping-timeout is 30000 milliseconds (30 seconds). Ping discovery requests can be disabled by setting the ping interval to 0. If ping discovery messages are disabled, power commands will be attempted without knowledge of the host's existence or its support of IPMI. The value of ping-interval must be less than the ping-timeout length. RMCP ping discovery messages are automatically disabled in non-interactive mode.

-v, --ping-packet-count num

-w, --ping-percent num
    Since IPMI is based off of a UDP protocol, it is difficult for ipmipower to distinguish between a missing machine and a bad network connection when running in interactive mode. For example, suppose a link consistently drops 80% of the packets to a particular machine. The power control operation may have difficulty completing, although a recent pong response from RMCP makes ipmipower believe the machine is up and functioning properly. The --ping-packet-count and --ping-percent options are used to alleviate this problem. Ipmipower will monitor RMCP ping packets in ping-packet-count chunks. If ipmipower does not receive a response to greater than ping-percent of those packets, ipmipower will assume the link to this node is bad and will not send power control operations to that node until the connection is determined to be reliable. If not specified, ping-packet-count is 10 and ping-percent is 50. This heuristic can be disabled by setting either ping-packet-count or ping-percent to 0. This feature is not used if ping-interval is set to 0. Note that the --ping-percent option takes an integer as an argument, not a decimal.

-x, --ping-consec-count num
    Ping-consec-count is another heuristic used to determine if a node should be considered discovered, undiscovered, or with a bad connection. If a valid RMCP pong response was received for the last ping-consec-count RMCP ping packets, a node will be considered discovered, regardless if ping-packet-count and ping-percent statistically consider the link to be unreliable. If not specified, ping-consec-count is 5. This feature can be disabled by setting ping-consec-count to 0. This feature is not used if ping-interval, --ping-packet-count, or --ping-percent are set to 0.

INTERACTIVE COMMANDS
ipmipower provides the following interactive commands at the ipmipower> prompt. Before any power commands (on, off, cycle, reset, stat, pulse, or soft) can be used, hostnames must be configured into ipmipower, either through the command prompt or the hostnames command below.

hostnames [str]
    specify a new set of hosts, no str to unconfigure all hosts

username [str]
    specify a new username, no str for null username

password [str]
    specify a new password, no str for null password

k_g [str]
    specify a new K_g BMC Key, no str for null, prefix with '0x' to enter a key in hexadecimal

on [host(s)]
    turns on all hosts, or only the specified host(s).

off [host(s)]
    turns off all hosts, or only the specified host(s).

cycle [host(s)]
    power cycle all hosts, or specified host(s).

reset [host(s)]
    hard reset all hosts or specified host(s).

stat [host(s)]
    queries power status for all hosts, or only the specified host(s).

pulse [host(s)]
    send pulse diagnostic interrupt to all hosts, or only the specified host(s).

soft [host(s)]
    Initiate a soft-shutdown of the OS via ACPI to all hosts, or only the specified host(s).

help
    output help menu

advanced
    output advanced help menu

network
    output network help menu

quit
    quit ipmipower.

authentication_type str
    specify a new authentication type, auto, none, straight_password_key, md2, or md5.

privilege str
    specify a new privilege type, auto, user, operator or admin.

ipmi_version str
    specify the ipmi version, auto, 1.5 or 2.0.

cipher_suite_id str
    specify the cipher suite id, auto, 0, 1, 2, 3, 6, 7, 8, 11, 12.

on-if-off [on|off]
    toggle on-if-off functionality.

wait-until-on [on|off]
    toggle wait-until-on functionality.

wait-until-off [on|off]
    toggle wait-until-off functionality.

consolidate-output [on|off]
    toggle consolidate-output functionality

workaround-flags str
    specify workaround options.

debug [on|off]
    toggle debug output

ipmidump [on|off]
    toggle IPMI dump output

rmcpdump [on|off]
    toggle RMCP dump output

log [on|off]
    toggle logging output

logfile [str]
    specify a new log file, no str for default

config
    output the current configuration

timeout ms
    specify a new timeout length

retry-timeout ms
    specify a new retry timeout length

retry-wait-timeout ms
    specify a new retry-wait timeout length

retry-backoff-count num
    specify a new retry backoff count

ping-interval ms
    specify a new ping interval length

ping-timeout ms
    specify a new ping timeout length

ping-packet-count num
    specify a new ping packet count

ping-percent num
    specify a new ping percent

ping-consec-count num
    specify a new ping consec count

HOST RANGES
As noted above, ipmipower accepts a range of hostnames in the general form: prefix[n-m,l-k,...], where n < m and l < k, etc., as an alternative to explicit comma seperated lists of hosts. This form should not be confused with regular expression character classes (also denoted by []). For example, foo[19] does not represent foo1 or foo9, but rather represents a degenerate range: foo19.

This range syntax is meant only as a convenience on clusters with a prefixNN naming convention and specification of ranges should not be considered necessary -- the list foo1,foo9 could be specified as such, or by the range foo[1,9].

Some examples of range usage follow:
    foo[01-05] instead of foo01,foo02,foo03,foo04,foo05
    foo[7,9-10] instead of foo7,foo9,foo10
    foo[0-3] instead of foo0,foo1,foo2,foo3

As a reminder to the reader, some shells will interpret brackets ([ and ]) for pattern matching. Depending on your shell, it may be necessary to enclose ranged lists within quotes.

By default, power control results will be output one to each line. Although this output is readable in many situations, it may be difficult to read in other situations. The -C option can be used to change this default.

EXAMPLES

Determine the power status of foo[0-2] with null username and password
        ipmipower -h foo[0-2] --stat

Determine the power status of foo[0-2] with non-null username and password
        ipmipower -h foo[0-2] -u foo -p bar --stat

Hard reset nodes foo[0-2] with non-null username and password
        ipmipower -h foo[0-2] -u foo -p bar --reset

WORKAROUNDS
With so many different vendors implementing their own IPMI solutions, different vendors may implement their IPMI protocols incorrectly. The following lists the handful of compliance issues discovered and the workarounds currently used in ipmipower. When possible, the workarounds have been implemented so they will be transparent to the user. However, some will require the user to specify a workaround be used via the -W option. The workarounds listed below are listed in the order of their implementation. Therefore, workarounds implemented earlier may work for other vendors. Note that the following only indicates the hardware that a problem was discovered on. Newer versions of a vendors firmware may fix the problems indicated below. Similar machines from vendors may or may not exhibit the same problems. Intel SR870BN4: BMCs would not respond to retransmissions of a Get Session Challenge Request if a previous Get Session Challenge response was lost. Resolved by sending retransmitted Get Session Challenge requests from a different source port. Tyan S2882 with m3289 BMC: After the IPMI session is brought up, packet responses return empty session IDs to the client. In order to work around this issue, the "idzero" workaround must be specified. The option will allow empty session IDs to be accepted by the client. This problem is apparently fixed in later firmware releases. Dell PowerEdge 2850,SC1425: When Per-Message Authentication is disabled, packet responses contain non-null authentication data (when it should in fact be null). In order to work around this issue, the "unexpectedauth" workaround must be specified. The option will allow unexpected non-null authcodes to be checked as though they were expected. This compliance bug is confirmed to be fixed on newer firmware. Intel SE7520JR2 with National Semiconductor PC87431M mBMC: The activate session response and close session response packets have invalid sequence numbers. Automatically handled by ipmipower, specific workaround does not need to be specified. IBM eServer 325: The remote BMC will advertise that Per Message Authentication is disabled, but actually require it for the protocol. In order to work around this issue, the "forcepermsg" workaround must be specified. The option will force Per Message Authentication to be used no matter what is advertised by the remote BMC. Asus P5M2/P5MT-R: The motherboard does not properly report username capabilities and or K_g status, leading to invalid username or K_g errors. In order to work around this issue, the "authcap" workaround must be specified. Intel SE7520AF2 with Intel Server Management Module (Professional Edition): There are a number of Intel IPMI 2.0 bugs which can be worked around by specifying the "intel20" workaround. The workarounds include padding of usernames, automatic acceptance of a RAKP 4 response integrity check when using the integrity algorithm MD5-128, and password truncation if the authentication algorithm is HMAC-MD5-128. Supermicro H8QME with SIMSO daughter card: There are several Supermicro IPMI 2.0 bugs on early firmware revisions which can be worked around using the "supermicro20" workaround. These compliance bugs are confirmed to be fixed on newer firmware. Supermicro H8QME with SIMSO daughter card: The remote BMC will advertise that Per Message Authentication is disabled, but actually require it for the protocol. Automatically handled by ipmipower, specific workaround does not need to be specified. Sun Fire 4100: The session sequence numbers returned from the BMC in IPMI 1.5 sessions are the wrong endian. In order to work around this issue, the "endianseq" workaround must be specified. Sun Fire 4100: There are several IPMI 2.0 bugs which can be worked around by specifying the "sun20" workaround. The workarounds include handling invalid lengthed hash keys and invalid cipher suite records.

TROUBLESHOOTING
Most often, problems with ipmipower involve a misconfiguration of the remote machine's BMC. The FreeIPMI tool bmc-config(1) may be used to do this configuration. Double check to make sure the following are configured properly in the remote machine's BMC: IP address, MAC address, subnet mask, username(s), password(s), allowed authentication type(s), atleast OPERATOR privilege level for one user, enabled LAN activity. When powering on a powered off machine, the client must have a means by which to resolve the MAC address of the remote machine's ethernet card. This is typically done in one of two ways. 1) Enable gratuitous ARPs on the remote machine. The remote machine will send out a gratuitous ARP, which advertises the ethernet IP and MAC address so that other machines on the network this information their local ARP cache. For large clusters, this method is not recommended since gratuitous ARPs can flood the network with unnecessary traffic. 2) Permanently store the remote machine's MAC address in the local ARP cache. This is the more common approach on large clusters. Other methods are listed in the IPMI specification. If ipmipower is running a tad slow when running a power control command on the commandline (compared to running a power control command in interactive mode), hostname IP resolution may be slowing the startup code down. Hostname resolution tuning may help make ipmipower execute faster on the commandline. This performance problem should not matter when running in interactive mode or with powerman, since it is a one-time setup cost. If ipmipower attempts are constantly timing out, increasing the retry timeout to a few seconds may help. Some remote BMCs are considerably slower than others.

KNOWN ISSUES
In order to prevent brute force attacks, some BMCs will "lock up" after a number of username, password, or privilege errors. There is no known way to cleanly deal with a "locked up" BMC. The best option is to simply wait "awhile". On certain operating systems, if you input your username and password on the command line, the username and password may be discovered by other users when using the ps(1) command or looking in the /proc file system. More secure solutions are to configure this information in the config file, in interactive mode, or with the -P and -K options. IPMI specifications do not require BMCs to perform a power control operation before returning a completion code to the caller. Therefore, it is possible for ipmipower to return power status queries opposite of what you are expecting. For example, if a "power off" operation is performed, a BMC may return a successful completion code to ipmipower before the "power off" operation is actually performed. Subsequent power status queries may return "on" for several seconds, until the BMC actually performs the "power off" operation. This version of ipmipower was compiled with debugging. When compiled with debugging, ipmipower is insecure. The following were intentionally left in ipmipower for debugging purposes:

o   Sensitive command line arguments are not cleared from memory.

o   Core dumps are enabled.

o   In interactive mode, commands may output sensitive information to stdout.

o   Configuration info such as username and password can be output to the log file. Before placing ipmipower in a production system, it is recommended that the program be compiled with debugging turned off.

ORIGIN
Developed by Albert Chu <chu11@llnl.gov> on LLNL's GNU/Linux clusters. This software is open source and distributed under the terms of the Gnu GPL.

SEE ALSO
bmc-config(1), ipmipower.conf(5)