Provided by: freeipmi-tools_1.4.11-1ubuntu1_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.

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

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

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

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

REPORTING BUGS

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

COPYRIGHT

       Copyright (C) 2007-2014 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/