Provided by: freeipmi-tools_0.7.17~beta2-1_i386 bug

NAME

       ipmimonitoring - IPMI monitoring utility

SYNOPSIS

       ipmimonitoring [OPTION...]

DESCRIPTION

       ipmimonitoring  is  an  IPMI  sensor  monitoring tool that utilizes the
       libipmimonitoring(3) library to interpret sensor readings  rather  than
       just  report  them.   The  tool  will output if sensors are in NOMINAL,
       WARNING, or CRITICAL states. The library and tool  are  primarily  used
       for  host  monitoring  activities.  By  mapping  sensor  readings  into
       NOMINAL, WARNING, or CRITICAL states, it makes monitoring easier across
       large  numbers  of  nodes.  For  more general sensor reading use, it is
       recommended that users use ipmi-sensors(8).

       The state interpretations are  determined  by  the  configuration  file
       /etc/ipmi_monitoring_sensors.conf.  See ipmi_monitoring_sensors.conf(5)
       for more information on configuring sensor interpretations.

       Some sensors may not be output by default. Those  sensors  may  not  be
       readable or interpretable for a number of reasons. The --verbose may be
       used to see what sensors cannot be  read  or  interpreted.  Please  see
       IPMIMONITORING KNOWN ISSUES below for interpretation rule issues.

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

IPMIMONITORING OPTIONS

       The following options are specific to Ipmimonitoring.

       -v, --verbose
              Increase verbosity in output. This option will output additional
              sensors that are generally unreadable or uninterpretable.

       -q, --quiet-readings
              Do  not  output sensor reading values, only NOMINAL, WARNING, or
              CRITICAL states. This option is particularly useful if you  want
              to   use   hostranged  output  across  a  cluster  and  want  to
              consolidate the output.

       -L, --list-groups
              List sensor groups.

       -g GROUP-LIST, --groups=GROUP-LIST
              Specify groups to specifically monitor. Multiple groups  can  be
              separated by commas or spaces.

       -s "SENSORS-LIST", --sensors="SENSORS-LIST"
              Specify  sensors to monitor by record id. Multiple record
              ids can be separated by commas or spaces.

       -b, --bridge-sensors
              By default, ipmimonitoring will  not  read  sensors  from
              non-BMC   owners.   Setting   this   option   will   make
              ipmimonitoring  attempt  to  bridge  sensor  commands  to
              alternate  owners  (experimental).  Bridging may not work
              on some interfaces/driver types.

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

SDR CACHE OPTIONS

       This tool requires access to the sensor  data  repository  (SDR)
       cache  for  general  operation.  By  default,  SDR  data will be
       downloaded and  cached  on  the  local  machine.  The  following
       options apply to the SDR cache.

       -f, --flush-cache
              Flush  a  cached  version  of  the sensor data repository
              (SDR) cache. The  SDR  is  typically  cached  for  faster
              subsequent access. However, it may need to be flushed and
              re-generated if the SDR has been updated on a system.

       -Q, --quiet-cache
              Do not output information about cache  creation/deletion.

       --sdr-cache-directory=DIRECTORY
              Specify an alternate directory for sensor data repository
              (SDR) caches to be stored or read from. Defaults  to  the
              home directory if not specified.

       --sdr-cache-recreate
              If the SDR cache is out of date or invalid, automatically
              recreate the sensor data  repository  (SDR)  cache.  This
              option may be useful for scripting purposes.

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.

IPMIMONITORING TROUBLESHOOTING

       The  following  are  common  issues  for  given  error  messages
       specifically for ipmimonitoring.

       "sensor  config  file  parse error" - A parse error was found in
       the libipmimonitoring(3) sensor configuration file.  Please  see
       libipmimonitoring(3).

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

       # ipmimonitoring

       Show all sensors on the local machine.

       # ipmimonitoring --sensors="82 11 7 102"

       Show sensors #82, #11, #7 and #102 on the local machine.

       # ipmimonitoring --groups=TEMPERATURE

       Show all sensors in TEMPERATURE group on the local machine.

       # ipmimonitoring -h ahost -u myusername -p mypassword

       Show all sensors on a remote machine using IPMI over LAN.

       # ipmimonitoring -h mycluster[0-127] -u myusername -p mypassword

       Show all sensors across a cluster using IPMI over LAN.

IPMIMONITORING KNOWN ISSUES

       Interpretation rules have  not  been  written  for  all  sensors
       permutations  and types. Users may notice some sensors output in
       ipmi-sensors(8) do not  output  in  ipmimonitoring.   If  sensor
       interpretation  rules  are  needed,  please contact the FreeIPMI
       maintainers.

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.

       Interpretation rules have  not  been  written  for  all  sensors
       permutations  and types. Users may notice some sensors output in
       ipmi-sensors(8)  does  not   output   in   ipmimonitoring.    If
       additional   sensor  interpretation  rules  are  needed,  please
       contact the FreeIPMI maintainers.

       Some sensors may be output because the owner of  the  sensor  is
       not the BMC. To attempt to bridge sensors and access sensors not
       on the BMC, users may wish to try  the  -b  or  --bridge-sensors
       options.

FILES

       /etc/ipmi_monitoring_sensors.conf

REPORTING BUGS

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

COPYRIGHT

       Copyright (C) 2007-2008 Lawrence  Livermore  National  Security,
       LLC.
       Copyright  (C)  2006-2007  The  Regents  of  the  University  of
       California.

       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

       libipmimonitoring(3),           ipmi_monitoring_sensors.conf(5),
       freeipmi(7), ipmi-sensors(8)

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