Provided by: freeipmi-tools_1.6.13-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 ipmi-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[:PORT]
              Specify the remote host to communicate with. An optional  port  can  be  specified,
              which may be useful in port forwarding or similar situations. If specifying an IPv6
              address and port, use the format [ADDRESS]:PORT.

       -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

              15  -  Authentication  Algorithm  =  HMAC-SHA256;  Integrity  Algorithm   =   None;
              Confidentiality Algorithm = None

              16 - Authentication Algorithm = HMAC-SHA256; Integrity Algorithm = HMAC_SHA256_128;
              Confidentiality Algorithm = None

              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 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. For  example,  a  NUL  character  received  by
              getty(8)  and  its  descendants  (such as agetty(8)) will cause a baud rate change,
              which may lock up the terminal.

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

       --sol-payload-instance=NUM
              Specify the SOL payload instance number. The default value is 1, valid values range
              from  1  to  15.  Most  systems only support a single instance, however a few allow
              users to access multiple.

       --deactivate-all-instances
              When used along with the  --deactivate  option,  will  deactivate  all  active  SOL
              instances instead of just the currently configured payload instance.

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

       --debugfile
              Output debugging to files in current directory rather than to standard output.

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

       "internal IPMI error" - An IPMI error has occurred that FreeIPMI  does  not  know  how  to
       handle. Please e-mail <freeipmi-users@gnu.org> to report the issue.

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. Not all BMCs support the ability to steal away a SOL 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.

       nochecksumcheck  -  This  workaround  flag  will  tell FreeIPMI to not check the checksums
       returned from IPMI  command  responses.  It  works  around  systems  that  return  invalid
       checksums  due  to  implementation  errors,  but  the packet is otherwise valid. Users are
       cautioned on the use of this option, as it removes validation of  packet  integrity  in  a
       number  of circumstances. However, it is unlikely to be an issue in most situations. Those
       hitting  this  issue  may  see  "connection  timeout",  "session  timeout",  or  "password
       verification  timeout"  errors.  On IPMI 1.5 connections, the "noauthcodecheck" workaround
       may also needed too. Issue observed  on  Supermicro  X9SCM-iiF,  Supermicro  X9DRi-F,  and
       Supermicro X9DRFR.

       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, Quanta QSSC-S4R/Appro GB812X-CN, and Dell C5220.  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.

       solchannelsupport - This workaround flag will not check if SOL is supported on the current
       channel. It works around remote systems that do not properly support this  command.  Those
       hitting  this  issue  may see "BMC Error" errors. Issue observed on Intel Windmill, Quanta
       Winterfell, and Wiwynn Windmill

       serialalertsdeferred - This workaround option  will  set  serial  alerts  to  be  deferred
       instead  of  have  them be failures. This works around motherboards that perform IPMI over
       serial along with IPMI  serial  over  LAN.  Those  hitting  this  issue  may  see  "excess
       retransmissions  sent"  when  they attempt to input data via SOL.  Issue observed on Intel
       Windmill, Quanta Winterfell, and Wiwynn Windmill.

       solpacketseq - This workaround option will  increment  the  SOL  payload  packet  sequence
       number  under  dire  circumstances.  Normally  SOL  should  never  do  this,  however some
       motherboards have shown to get "stuck" due to an internal bug  on  the  motherboard.  This
       workaround  can help in getting the BMC un-stuck. Those hitting this issue may see "excess
       retransmissions sent" when they attempt to input data via SOL.  Issue  observed  on  Intel
       Windmill, Quanta Winterfell, and Wiwynn Windmill.

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 session with a remote host.

REPORTING BUGS

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

COPYRIGHT

       Copyright (C) 2007-2015 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), ipmi-config(8)

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