Provided by: freeipmi-tools_0.8.12-3ubuntu1_amd64 bug

NAME

       ipmi-chassis - IPMI chassis management utility

SYNOPSIS

       ipmi-chassis [OPTION...]

DESCRIPTION

       Ipmi-chassis  is  used  for  managing/monitoring  an  IPMI chassis, such as chassis power,
       indentification (i.e. LED  control),  and  status.  See  OPTIONS  below  for  all  chassis
       management options available.

       Listed   below   are  general  IPMI  options,  tool  specific  options,  trouble  shooting
       information,  workaround  information,  examples,  and  known  issues.   For   a   general
       introduction  to  FreeIPMI please see freeipmi(7).  To perform IPMI chassis configuration,
       please see ipmi-chassis-config(8).  To perform some advanced  chassis  management,  please
       see bmc-device(8).

GENERAL OPTIONS

       The following options are general options for configuring IPMI communication and executing
       general tool commands.

       -D, --driver-type=IPMIDRIVER
              Specify the driver type to use instead of doing an auto selection.   The  currently
              available  outofband  drivers  are LAN and LAN_2_0, which perform IPMI 1.5 and IPMI
              2.0 respectively. The currently available inband drivers are KCS,  SSIF,  OPENIPMI,
              and SUNBMC.

       --disable-auto-probe
              Do not probe in-band IPMI devices for default settings.

       --driver-address=DRIVER-ADDRESS
              Specify  the in-band driver address to be used instead of the probed value. DRIVER-
              ADDRESS should be prefixed with "0x" for a hex value and '0' for an octal value.

       --driver-device=DEVICE
              Specify the in-band driver device path to be used instead of the probed path.

       --register-spacing=REGISTER-SPACING
              Specify the in-band driver register spacing instead of the probed value.

       -h, --hostname=IPMIHOST1,IPMIHOST2,...
              Specify the remote host(s) to communicate with. Multiple hostnames may be separated
              by comma or may be specified in a range format; see HOSTRANGED SUPPORT below.

       -u, --username=USERNAME
              Specify  the  username  to  use  when  authenticating with the remote host.  If not
              specified, a null (i.e. anonymous) username is assumed. The user must have  atleast
              ADMIN privileges in order for this tool to operate fully.

       -p, --password=PASSWORD
              Specify  the  password  to  use  when authenticationg with the remote host.  If not
              specified, a null password is assumed. Maximum password length is 16 for  IPMI  1.5
              and 20 for IPMI 2.0.

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

       -k, --k-g=K_G
              Specify  the  K_g  BMC key to use when authenticating with the remote host 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.

       --session-timeout=MILLISECONDS
              Specify the session timeout in milliseconds. Defaults  to  20000  milliseconds  (20
              seconds) if not specified.

       --retransmission-timeout=MILLISECONDS
              Specify  the  packet  retransmission  timeout  in  milliseconds.  Defaults  to 1000
              milliseconds (1 second) if not specified.  The  retransmission  timeout  cannot  be
              larger than the session timeout.

       -a, --authentication-type=AUTHENTICATION-TYPE
              Specify   the  IPMI  1.5  authentication  type  to  use.  The  currently  available
              authentication types are NONE, STRAIGHT_PASSWORD_KEY, MD2, and MD5. Defaults to MD5
              if not specified.

       -I, --cipher-suite-id=CIPHER-SUITE-ID
              Specify  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. Defaults to cipher suite ID 3  if  not  specified.  The
              following cipher suite ids are currently supported:

              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

              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

              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

              17 - Authentication Algorithm = HMAC-SHA256; Integrity Algorithm = HMAC_SHA256_128;
              Confidentiality Algorithm = AES-CBC-128

       -l, --privilege-level=PRIVILEGE-LEVEL
              Specify  the  privilege  level to be used. The currently available privilege levels
              are USER, OPERATOR, and ADMIN. Defaults to ADMIN if not specified.

       --config-file=FILE
              Specify an alternate configuration file.

       -W WORKAROUNDS, --workaround-flags=WORKAROUNDS
              Specify workarounds to  vendor  compliance  issues.  Multiple  workarounds  can  be
              specified  separated  by  commas.  See  WORKAROUNDS  below  for a list of available
              workarounds.

       --debug
              Turn on debugging.

       -?, --help
              Output a help list and exit.

       --usage
              Output a usage message and exit.

       -V, --version
              Output the program version and exit.

IPMI-CHASSIS OPTIONS

       The following options are specific to Ipmi-chassis.

       --get-chassis-capabilities
              Get chassis capabilities. This command returns information on  which  main  chassis
              management functions are available.

       --get-chassis-status
              Get  chassis  status.  This  command  returns  high level status information on the
              chassis.

       --chassis-control=CONTROL
              Control the chassis. This command provides power-up, power-down, and reset control.
              Supported     values:     POWER-DOWN,     POWER-UP,     POWER-CYCLE,    HARD-RESET,
              DIAGNOSTIC-INTERRUPT, SOFT-SHUTDOWN.

       --chassis-identify=IDENTIFY
              Set chassis identification. This command controls physical  system  identification,
              typically  a LED. Supported values: TURN-OFF to turn off identification, <interval>
              to turn on identification for "interval" seconds, FORCE to turn on indefinitely.

       --get-system-restart-cause
              Get system restart cause.

       --get-power-on-hours-counter
              Get power on hours (POH) counter.

HOSTRANGED OPTIONS

       The following options manipulate hostranged  output.  See  HOSTRANGED  SUPPORT  below  for
       additional information on hostranges.

       -B, --buffer-output
              Buffer  hostranged output. For each node, buffer standard output until the node has
              completed its IPMI operation. When specifying  this  option,  data  may  appear  to
              output  slower to the user since the the entire IPMI operation must complete before
              any data can be output.  See HOSTRANGED SUPPORT below for additional information.

       -C, --consolidate-output
              Consolidate hostranged  output.  The  complete  standard  output  from  every  node
              specified  will  be consolidated so that nodes with identical output are not output
              twice. A header will list those nodes  with  the  consolidated  output.  When  this
              option  is  specified, no output can be seen until the IPMI operations to all nodes
              has completed. If  the  user  breaks  out  of  the  program  early,  all  currently
              consolidated  output  will  be  dumped. See HOSTRANGED SUPPORT below for additional
              information.

       -F, --fanout
              Specify multiple host fanout. A "sliding window" (or fanout) algorithm is used  for
              parallel IPMI communication so that slower nodes or timed out nodes will not impede
              parallel communication. The maximum number of threads available at the same time is
              limited by the fanout. The default is 64.

       -E, --eliminate
              Eliminate  hosts  determined  as undetected by ipmidetect.  This attempts to remove
              the common issue of hostranged 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.

       --always-prefix
              Always prefix output, even if only one host is specified or communicating  in-band.
              This  option  is primarily useful for scripting purposes. Option will be ignored if
              specified with the -C option.

HOSTRANGED SUPPORT

       Multiple hosts can be input either as an explicit comma separated  lists  of  hosts  or  a
       range  of  hostnames in the general form: prefix[n-m,l-k,...], where n < m and l < k, etc.
       The later 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.

       When multiple hosts are specified by the user, a thread will be executed for each host  in
       parallel  up to the configured fanout (which can be adjusted via the -F option). This will
       allow communication to large numbers of nodes far more quickly than if done in serial.

       By default, standard output from each node specified will  be  output  with  the  hostname
       prepended  to  each  line.  Although this output is readable in many situations, it may be
       difficult to read in other situations. For example, output  from  multiple  nodes  may  be
       mixed together. The -B and -C options can be used to change this default.

       In-band  IPMI  Communication  will  be  used  when the host "localhost" is specified. This
       allows the user to add the localhost into the hostranged output.

GENERAL TROUBLESHOOTING

       Most often, IPMI problems are due to configuration  problems.  Inband  IPMI  problems  are
       typically  caused  by  improperly  configured  drivers or non-standard BMCs. IPMI over LAN
       problems involve a misconfiguration of the remote machine's BMC.   Double  check  to  make
       sure  the  following  are configured properly in the remote machine's BMC: IP address, MAC
       address, subnet mask, username, user enablement, user privilege, password, LAN  privilege,
       LAN enablement, and allowed authentication type(s). For IPMI 2.0 connections, double check
       to make sure the cipher suite privilege(s) and K_g key are configured properly.  The  bmc-
       config(8) tool can be used to check and/or change these configuration settings.

       The following are common issues for given error messages:

       "username  invalid" - The username entered (or a NULL username if none was entered) is not
       available on the remote machine. It  may  also  be  possible  the  remote  BMC's  username
       configuration is incorrect.

       "password  invalid" - The password entered (or a NULL password if none was entered) is not
       correct. It may also be possible the password for the user is not correctly configured  on
       the remote BMC.

       "password  verification  timeout"  -  Password  verification  has  timed out.  A "password
       invalid" error  (described  above)  or  a  generic  "session  timeout"  (described  below)
       occurred.  During this point in the protocol it cannot be differentiated which occurred.

       "k_g  invalid"  -  The  K_g  key  entered  (or  a NULL K_g key if none was entered) is not
       correct. It may also be possible the K_g key is not correctly  configured  on  the  remote
       BMC.

       "privilege level insufficient" - An IPMI command requires a higher user privilege than the
       one authenticated with. Please try to authenticate  with  a  higher  privilege.  This  may
       require authenticating to a different user which has a higher maximum privilege.

       "privilege  level  cannot  be  obtained  for  this  user"  -  The  privilege level you are
       attempting to authenticate with is higher than the maximum allowed for this  user.  Please
       try  again  with  a  lower  privilege. It may also be possible the maximum privilege level
       allowed for a user is not configured properly on the remote BMC.

       "authentication type unavailable for attempted privilege level" - The authentication  type
       you  wish to authenticate with is not available for this privilege level. Please try again
       with an alternate authentication type  or  alternate  privilege  level.  It  may  also  be
       possible  the  available  authentication types you can authenticate with are not correctly
       configured on the remote BMC.

       "cipher suite id unavailable" - The cipher suite id you wish to authenticate with  is  not
       available  on  the  remote BMC. Please try again with an alternate cipher suite id. It may
       also be possible the available cipher suite ids are not correctly configured on the remote
       BMC.

       "ipmi  2.0 unavailable" - IPMI 2.0 was not discovered on the remote machine. Please try to
       use IPMI 1.5 instead.

       "connection timeout" - Initial IPMI communication failed. A number of potential errors are
       possible,  including an invalid hostname specified, an IPMI IP address cannot be resolved,
       IPMI is not enabled on the remote server, the  network  connection  is  bad,  etc.  Please
       verify configuration and connectivity.

       "session  timeout"  -  The  IPMI  session  has timed out. Please reconnect.  If this error
       occurs often, you may wish to increase the retransmission timeout. Some  remote  BMCs  are
       considerably slower than others.

       "device  not  found" - The specified device could not be found. Please check configuration
       or inputs and try again.

       "driver timeout" - Communication with the driver or  device  has  timed  out.  Please  try
       again.

       "message  timeout"  -  Communication  with  the driver or device has timed out. Please try
       again.

       "BMC busy" - The BMC is currently busy. It may be processing information or have too  many
       simultaneous sessions to manage. Please wait and try again.

       "could  not  find  inband  device"  -  An  inband device could not be found.  Please check
       configuration or specify specific device or driver on the command line.

       Please see WORKAROUNDS below to also if there are any vendor specific bugs that have  been
       discovered and worked around.

WORKAROUNDS

       With  so  many  different vendors implementing their own IPMI solutions, different vendors
       may implement their IPMI  protocols  incorrectly.  The  following  lists  the  workarounds
       currently available to handle discovered compliance issues.

       When  possible, 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 hardware listed below may only indicate the hardware that a problem was discovered on.
       Newer  versions  of  hardware  may fix the problems indicated below. Similar machines from
       vendors may or may not exhibit the same problems.  Different  vendors  may  license  their
       firmware from the same IPMI firmware developer, so it may be worthwhile to try workarounds
       listed below even if your motherboard is not listed.

       "assumeio" - This workaround option will assume inband interfaces communicate with  system
       I/O  rather  than  being  memory-mapped. This will work around systems that report invalid
       base addresses. Those hitting this issue may see "device not supported" or "could not find
       inband device" errors.  Issue observed on HP ProLiant DL145 G1.

       "idzero"  -  This  workaround  option  will  allow empty session IDs to be accepted by the
       client. It works around IPMI sessions that report empty session IDs to the  client.  Those
       hitting  this  issue  may  see "session timeout" errors. Issue observed on Tyan S2882 with
       M3289 BMC.

       "unexpectedauth" - This workaround option will allow unexpected non-null authcodes  to  be
       checked  as  though they were expected. It works around an issue when packets contain non-
       null  authentication  data  when  they  should  be  null  due  to   disabled   per-message
       authentication.  Those hitting this issue may see "session timeout" errors. Issue observed
       on Dell PowerEdge 2850,SC1425. Confirmed fixed on newer firmware.

       "forcepermsg" - This workaround option will force per-message authentication to be used no
       matter  what is advertised by the remote system. It works around an issue when per-message
       authentication is advertised as disabled on the remote system, but it is actually required
       for  the  protocol.  Those  hitting  this  issue  may see "session timeout" errors.  Issue
       observed on IBM eServer 325.

       "endianseq" - This workaround option will flip the endian of the session sequence  numbers
       to  allow  the  session  to  continue properly.  It works around IPMI 1.5 session sequence
       numbers that are the wrong endian. Those hitting this  issue  may  see  "session  timeout"
       errors.  Issue observed on some Sun ILOM 1.0/2.0 (depends on service processor endian).

       "authcap"  -  This  workaround  option  will  skip early checks for username capabilities,
       authentication capabilities, and K_g support and allow IPMI authentication to succeed.  It
       works  around multiple issues in which the remote system does not properly report username
       capabilities, authentication capabilities, or K_g status. Those hitting this issue may see
       "username  invalid",  "authentication  type unavailable for attempted privilege level", or
       "k_g  invalid"  errors.   Issue   observed   on   Asus   P5M2/P5MT-R/RS162-E4/RX4,   Intel
       SR1520ML/X38ML, and Sun Fire 2200/4150/4450 with ELOM.

       "intel20"  - This workaround option will work around several Intel IPMI 2.0 authentication
       issues. The issues covered include padding of usernames, and password  truncation  if  the
       authentication  algorithm  is  HMAC-MD5-128.  Those  hitting  this issue may see "username
       invalid", "password invalid", or "k_g invalid" errors. Issue observed on  Intel  SE7520AF2
       with Intel Server Management Module (Professional Edition).

       "supermicro20"  -  This  workaround  option  will  work around several Supermicro IPMI 2.0
       authentication issues on motherboards w/  Peppercon  IPMI  firmware.  The  issues  covered
       include  handling  invalid  length  authentication codes. Those hitting this issue may see
       "password invalid" errors.  Issue observed on Supermicro H8QME with SIMSO  daughter  card.
       Confirmed fixed on newerver firmware.

       "sun20" - This workaround option will work work around several Sun IPMI 2.0 authentication
       issues. The issues covered include invalid lengthed hash keys, improperly hashed keys, and
       invalid  cipher suite records. Those hitting this issue may see "password invalid" or "bmc
       error" errors.  Issue observed on Sun Fire  4100/4200/4500  with  ILOM.   This  workaround
       automatically includes the "opensesspriv" workaround.

       "opensesspriv" - This workaround option will slightly alter FreeIPMI's IPMI 2.0 connection
       protocol to workaround an invalid  hashing  algorithm  used  by  the  remote  system.  The
       privilege  level  sent during the Open Session stage of an IPMI 2.0 connection is used for
       hashing keys instead of the privilege level sent during the RAKP1 connection stage.  Those
       hitting  this  issue  may  see  "password invalid", "k_g invalid", or "bad rmcpplus status
       code" errors.  Issue observed on Sun Fire 4100/4200/4500  with  ILOM,  Inventec  5441/Dell
       Xanadu II, Supermicro X8DTH, Supermicro X8DTG, and Intel S5500WBV/Penguin Relion 700. This
       workaround is automatically triggered with the "sun20" workaround.

       "integritycheckvalue" - This workaround option will work around an invalid integrity check
       value during an IPMI 2.0 session establishment when using Cipher Suite ID 0. The integrity
       check value should be 0 length, however the remote motherboard responds with  a  non-empty
       field. Those hitting this issue may see "k_g invalid" errors. Issue observed on Supermicro
       X8DTG, Supermicro X8DTU, and Intel S5500WBV/Penguin Relion 700.

EXAMPLES

       # ipmi-chassis --get-status

       Get the chassis status of the local machine.

       # ipmi-chassis -h ahost -u myusername -p mypassword --get-status

       Get the chassis status of a remote machine using IPMI over LAN.

       # ipmi-chassis -h mycluster[0-127] -u myusername -p mypassword --get-status

       Get the chassis status across a cluster using IPMI over LAN.

       # ipmi-chassis -h ahost -u myusername -p mypassword --chassis-control=POWER-ON

       Power on a remote machine using IPMI over LAN.

KNOWN ISSUES

       On older operating systems, if you input your username, password,  and  other  potentially
       security  relevant  information on the command line, this information may be discovered by
       other users when using tools like the ps(1) command or looking in the /proc  file  system.
       It  is  generally more secure to input password information with options like the -P or -K
       options. Configuring security relevant information  in  the  FreeIPMI  configuration  file
       would also be an appropriate way to hide this information.

       In  order  to  prevent  brute  force attacks, some BMCs will temporarily "lock up" after a
       number of remote authentication errors. You may need to  wait  awhile  in  order  to  this
       temporary "lock up" to pass before you may authenticate again.

REPORTING BUGS

       Report bugs to <freeipmi-users@gnu.org> or <freeipmi-devel@gnu.org>.

COPYRIGHT

       Copyright © 2007-2010 FreeIPMI Core Team

       This program 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.

SEE ALSO

       freeipmi(7), bmc-config(8), bmc-device(8), ipmi-chassis-config(8)

       http://www.gnu.org/software/freeipmi/