Provided by: freeipmi-tools_0.7.15-2_i386 bug

NAME

       bmc-device - perform advanced BMC commands

SYNOPSIS

       bmc-device [OPTION...]

DESCRIPTION

       bmc-device  supports a variety of IPMI commands to perform advanced BMC
       functions.  This tool is primarily used for development debugging,  BMC
       error  recory,  retrieving  detailed  technical  information, and other
       advanced purposes. Most IPMI users will not need to use this tool. Some
       of the bmc-device commands are not supported on all motherboards.

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 USER 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

       -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, --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.

BMC-DEVICE OPTIONS

       The following options are specific to bmc-device.

       --cold-reset
              Perform a cold reset.

       --warm-reset
              Perform a warm reset.

       --get-self-test-results
              Output BMC self test results.

       --get-acpi-power-state
              Get ACPI system and device power state.

       --set-acpi-power-state
              Set  ACPI  power  state.  Must   be   specified   to   use   the
              --set-acpi-system-power-state, and --set-acpi-device-power-state
              options listed below.

       --set-acpi-system-power-state=SYSTEM_POWER_STATE
              Set ACPI system power state. Allowed values: S0_G0, S1, S2,  S3,
              S4,   S5_G2,   S4_S5,   G3,   SLEEPING,  G1_SLEEPING,  OVERRIDE,
              LEGACY_ON,    LEGACY_OFF,    UNKNOWN.      Used     with     the
              --set-acpi-power-state option.

       --set-acpi-device-power-state=DEVICE_POWER_STATE
              Set  ACPI  device  power  state. Allowed values: D0, D1, D2, D3,
              UNKNOWN.  Used with the --set-acpi-power-state option.

       --get-lan-statistics
              Get IP, UDP, and RMCP statistics.

       --clear-lan-statistics
              Clear IP, UDP, and RMCP statistics.

       --get-sdr-repository-time
              Get SDR repository time.

       --set-sdr-repository-time=TIME
              Set SDR repository time. Input format = "MM/DD/YYYY - HH:MM:SS".
              Note  that  hours  are input in 24 hour form. Alternatively, the
              local system time can be specified with "now".

       --get-sel-time
              Get SEL time.

       --set-sel-time=TIME
              Set SEL time. Input format = "MM/DD/YYYY - HH:MM:SS". Note  that
              hours are input in 24 hour form. Alternatively, the local system
              time can be specified with "now".

       --platform-event="[generator_id]         <event_message_format_version>
       <sensor_type>     <sensor_number>     <event_type>    <event_direction>
       <event_data1> <event_data2> <event_data3>"
              Instruct the BMC to process the specified event data. Typically,
              this  data  will  be  logged  to the System Event Log (SEL), but
              depending  on  implementation  it  may  be  processed  by  other
              subsystems  such as Platform Event Filtering (PEF). The keywords
              assertion or deassertion may be used for event_direction, or the
              numerical     values     may     be     used     instead.    The
              event_message_format_version is 0x03 for IPMI 1.0 and  0x04  for
              IPMI  1.5.  The  generator_id  above  is optional, however it is
              required if generating the event via a  system  interface  (i.e.
              inband).   If  generating  the event via a system interface, the
              system management software generator id range is 0x41 to 6Fh.

       --get-mca-auxiliary-log-status
              Get  machine  check  architecture  (MCA)  auxiliary  log  status
              information.

       --get-ssif-interface-capabilities
              Get SSIF interface capabilities.

       --get-kcs-interface-capabilities
              Get KCS interface capabilities.

       --get-bt-interface-capabilities
              Get BT interface capabilities.

       --verbose
              Increase verbosity in output.

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.

       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  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  IPMI  over  LAN continually times out, you may wish to increase the
       retransmission timeout. Some remote BMCs are considerably  slower  than
       others.

       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 handful of compliance  issues  discovered  and  the
       workarounds currently supported.

       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.

       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. Automatically handled.

       Tyan S2882 with m3289 BMC: After the IPMI session is brought up, packet
       responses return empty session IDs to  the  client.  This  will  likely
       cause  "session  timeout" errors to occur. 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.

       Dell   PowerEdge   2850,SC1425:   When  Per-Message  Authentication  is
       disabled, packet responses contain non-null authentication  data  (when
       it  should  in  fact be null). This will likely cause "session timeout"
       errors  to  occur.  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.

       IBM eServer 325:  The  remote  BMC  will  advertise  that  Per  Message
       Authentication  is  disabled, but actually require it for the protocol.
       This will likely cause "session timeout" errors to occur. 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.

       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.

       Asus P5M2/P5MT-R/RS162-E4/RX4: The motherboard does not properly report
       username  capabilities  and/or  K_g  status.  This  will  likely  cause
       "username  invalid"  or "k_g invalid" errors to occur. In order to work
       around this issue, the "authcap" workaround must be specified.

       Intel SR1520ML/X38ML: The motherboard does not properly report username
       capabilities  and/or  K_g  status.  This  will  likely  cause "username
       invalid" or "k_g invalid" errors to occur. In order to work around this
       issue, the "authcap" workaround must be specified.

       Sun  ILOM  1.0/2.0:  The session sequence numbers returned for IPMI 1.5
       sessions are the wrong endian on some  systems  running  ILOM  1.0/2.0.
       The incorrect endian depends on the service processor endianness.  This
       will likely cause "session timeout" errors to occur. In order  to  work
       around this issue, the "endianseq" workaround must be specified.

       Sun  Fire  2200/4150/4450  with ELOM: The motherboard does not properly
       report username capabilities. This will likely cause "username invalid"
       errors  to  occur.   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 authentication bugs.
       These problems may cause "username  invalid",  "password  invalid",  or
       "k_g  invalid" errors to occur. They 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 problems may cause "password
       invalid" errors to occur. These compliance bugs  are  confirmed  to  be
       fixed on newer firmware.

       Sun Fire 4100/4200/4500 with ILOM: There are several Sun IPMI 2.0 bugs.
       These problems may cause "password invalid" or "bmc  error"  errors  to
       occur.  They can be worked around by specifying the "sun20" workaround.
       The workarounds include handling invalid lengthed hash keys, improperly
       hashed keys, and invalid cipher suite records.

       Inventec  5441,  Supermicro  X8DTH: 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.
       This may cause "password invalid" or "bad rmcpplus status code"  errors
       to  occur.  It  can  be  worked around by specifying the "opensesspriv"
       workaround.

EXAMPLES

       # bmc-device --cold-reset

       Perform a cold reset.

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 © 2008 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.conf(5), freeipmi(7)

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