Provided by: freeipmi-tools_1.1.5-3ubuntu3.3_amd64 bug

NAME

       ipmiconsole - IPMI console utility

SYNOPSIS

       ipmiconsole [OPTION...]

DESCRIPTION

       ipmiconsole  is  a  Serial-over-LAN  (SOL)  console  utility.  It can be used to establish
       console sessions to  remote  machines  using  the  IPMI  2.0  SOL  protocol.   Ipmiconsole
       communicates  with a remote machine's Baseboard Management Controller (BMC) to establish a
       console session. Before any SOL communication can take place,  the  remote  machine's  BMC
       must  be  configured  properly.   The  FreeIPMI  tool bmc-config(8) may be used to do this
       configuration.

       Often (although not always), console redirection must be also be  configured  properly  in
       the  BIOS and/or operating system. Both must be configured to redirect console traffic out
       the  appropriate  COM  port.   Please  see  your  motherboard  and  OS  documentation  for
       instructions on proper setup.

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

GENERAL OPTIONS

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

       -h IPMIHOST, --hostname=IPMIHOST
              Specify the remote host to communicate with.

       -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 a high enough
              privilege to establish a SOL session and have SOL session abilities.

       -p PASSWORD, --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=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 60000 milliseconds (60
              seconds) if not specified.

       --retransmission-timeout=MILLISECONDS
              Specify  the  packet  retransmission  timeout  in  milliseconds.  Defaults  to  500
              milliseconds (0.5 seconds) 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
              user  should  be  aware  that  only  cipher  suite ids 3, 8, and 12 encrypt console
              payloads. Console information will be sent in the  clear  if  an  alternate  cipher
              suite id is selected. 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=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. A special command line flag of "none", will indicate
              no workarounds (may be useful for overriding configured defaults). 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.

IPMICONSOLE OPTIONS

       The following options are specific to Ipmiconsole.

       -e CHAR, --escape-char=CHAR
              Specify an alternate escape character (default char '&').

       --dont-steal
              Do  not steal an SOL session if one is already detected as being in use. Under most
              circumstances, if SOL is detected as being in  use,  ipmiconsole  will  attempt  to
              steal the SOL session away from the previous session.  This default behavior exists
              for several reasons, most notably that earlier SOL sessions may have not been  able
              to be deactivate properly.

       --deactivate
              Deactivate a SOL session if one is detected as being in use and exit.

       --serial-keepalive
              Occasionally send NUL characters to detect inactive serial connections. This option
              is particularly useful for  those  who  intend  to  run  ipmiconsole  without  much
              interaction,  such  as  for  logging  purposes. While IPMI connections may still be
              alive, some motherboards have exhibited bugs in which underlying serial data can no
              longer  be  sent/received. From the viewpoint of ipmiconsole, data is simply not be
              sent out of the remote system and this problem is only detected once there is  user
              interaction. By sending the occasional NUL character, the underlying loss of serial
              data transfer can be detected far more  quickly.  There  is  some  risk  with  this
              option,  as  the  NUL character byte may affect the remote system depending on what
              data it may or may not be expecting.

       --serial-keepalive-empty
              This option is identical to --serial-keepalive except that SOL packets will contain
              no  NUL character data. On some motherboards, this may be sufficient to deal with a
              hanging IPMI session without the risk regularly sending a NUL  character  byte  may
              have.  However, some systems may not ACK a SOL packet without character data in it,
              meaning these keepalive packets do nothing.

       --lock-memory
              Lock sensitive information (such as usernames and passwords) in memory.

ESCAPE CHARACTERS

       The following escape sequences are supported. The default supported  escape  character  is
       '&', but can be changed with the -e option.

       &?     Display a list of currently available escape sequences.

       &.     Terminate the connection.

       &B     Send a "serial-break" to the remote console.

       &D     Send a DEL character.

       &&     Send a single escape character.

GENERAL TROUBLESHOOTING

       Most often, IPMI problems are due to configuration problems.

       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.

       In  addition  to  the  troubleshooting tips below, please see WORKAROUNDS below to also if
       there are any vendor specific bugs that have been discovered and worked around.

       Listed below are many of the common issues for error messages.   For  additional  support,
       please e-mail the <freeipmi-users@gnu.org> mailing list.

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

IPMICONSOLE TROUBLESHOOTING

       The following are common issues for error messages in ipmiconsole.

       "SOL  unavailable"  -  SOL  is  not  configured  for use on the remote BMC.  It may be not
       configured in general or for the specific user specified. Authenticating with a  different
       user  may  be  sufficient, however the IPMI protocol does not reveal detail on what is not
       configured on the remote BMC.

       "SOL in use" - SOL is already in use on the remote BMC. If you do not specify the  --dont-
       steal  option,  ipmiconsole  will  attempt  to  steal  the SOL session away from the other
       session.

       "SOL session stolen" - Your SOL session has been stolen by another session. You  may  wish
       to try and steal the session back by reconnecting.

       "SOL  requires  encryption"  -  SOL  requires  a cipher suite id that includes encryption.
       Please try to use cipher suite id 3, 8, or 12.  It may also  be  possible  the  encryption
       requirements are not configured correctly on the remote BMC.

       "SOL  requires  no  encryption"  -  SOL  requires  a  cipher  suite  id  that does not use
       encryption. Please try to use cipher suite id 0, 1, 2,  6,  7,  or  11.  It  may  also  be
       possible the encryption requirements are not configured correctly on the remote BMC.

       "BMC  Implementation"  -  The  BMC  on  the  remote  machine  has  a severe problem in its
       implementation. Please see the WORKAROUNDS section  below  for  possible  workarounds.  If
       additional vendor workarounds are required, please contact the authors.

       "excess  retransmissions sent" - An excessive number of retransmissions of SOL packets has
       occurred and ipmiconsole has given up. This may be due to network issues  or  SOL  issues.
       Some of the same issues involved with "connection timeout" or "session timeout" errors may
       be involved.  Please try to reconnect.

       "excess errors received" - An excessive number of  SOL  packet  errors  has  occurred  and
       ipmiconsole  has given up. This may be due to network issues or SOL issues.  Please try to
       reconnect.

       "BMC Error" - This error usually means a vendor SOL implementation requires a  combination
       of  authentication,  encryption,  privilege,  etc.  that  have  not been met by the user's
       choices.  Please try a combination of different cipher suites, privileges, etc. to resolve
       the problem. Please see the WORKAROUNDS section below for possible workarounds too.

WORKAROUNDS

       With  so  many  different vendors implementing their own IPMI solutions, different vendors
       may implement their IPMI protocols  incorrectly.  The  following  describes  a  number  of
       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.

       If you believe your hardware has an additional compliance issue that needs a workaround to
       be implemented, please contact the FreeIPMI  maintainers  on  <freeipmi-users@gnu.org>  or
       <freeipmi-devel@gnu.org>.

       authcap  -  This  workaround  flag  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  flag  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  flag  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  flag 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  flag 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, Intel S5500WBV/Penguin Relion 700, Intel
       S2600JF/Appro 512X, and Quanta QSSC-S4R//Appro GB812X-CN. This workaround is automatically
       triggered with the "sun20" workaround.

       integritycheckvalue  -  This  workaround  flag 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, and Intel S2600JF/Appro
       512X.

       solpayloadsize - This workaround flag will not check  for  valid  SOL  payload  sizes  and
       assume  a  proper  set.  It  works  around remote systems that report invalid IPMI 2.0 SOL
       payload sizes. Those hitting  this  issue  may  see  "BMC  Implementation"  errors.  Issue
       observed  on  Asus  P5M2/RS162-E4/RX4, Intel SR1520ML/X38ML, Inventec 5441/Dell Xanadu II,
       Sun x4100,  Supermicro  X8DTH,  Supermicro  X8DTG,  Supermicro  X8DTU,  and  Quanta  QSSC-
       S4R//Appro GB812X-CN.

       solport  -  This  workaround  flag  will  ignore  alternate SOL ports specified during the
       protocol. It works around remote systems that report invalid alternate  SOL  ports.  Those
       hitting  this issue may see "connection timeout" errors. Issue observed on Asus P5MT-R and
       Supermicro X8DTH-iF.

       solstatus - This workaround flag will not check  the  current  activation  status  of  SOL
       during  the  protocol  setup.  It works around remote systems that do not properly support
       this command. Those hitting this issue may see  "BMC  Error"  errors.  Issue  observed  on
       Supermicro X8SIL-F.

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.

       Some motherboards define an OEM SOL inactivity timeout for SOL sessions. If  SOL  sessions
       stay  inactive for long periods of time, ipmiconsole sessions may be abruptly closed, most
       likely resulting in session timeout errors.  Please  see  OEM  notes  for  information  on
       modifying this parameter if you wish for sessions to stay active longer.

SPECIFIC HARDWARE NOTES

       Intel  SR1520ML/X38ML:  After  a  reboot, the SOL session appears to "disconnect" from the
       motherboard but stay alive.  Character data input from the ipmiconsole client is  accepted
       by  the  remote  machine, but no character data or console data is ever sent back from the
       remote machine. The SOL session is subsequently useless. There is currently no  workaround
       in place to handle this. The session must be closed and restarted.

EXAMPLES

       # ipmiconsole -h ahost -u myusername -p mypassword

       Establish a console sesssion with a remote host.

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 (C) 2007-2012 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 3 of the License, or (at your option) any later version.

SEE ALSO

       freeipmi.conf(5), freeipmi(7), bmc-config(8)

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