Provided by: freeipmi-tools_0.8.12-3ubuntu1_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(1) 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.

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

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

IPMICONSOLE TROUBLESHOOTING

       The following are common issues for given error messages specifically for 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 lists the 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.

       "authcap"  -  This  workaround  option  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 option will work around several Intel IPMI 2.0 authentication
       issues. The issues covered 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. 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 option 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 option 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 option 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, and Intel S5500WBV/Penguin Relion 700. This
       workaround is automatically triggered with the "sun20" workaround.

       "integritycheckvalue" - This workaround option 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.

       "solpayloadsize"  -  This workaround option 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, and Supermicro X8DTU.

       "solport"  -  This  workaround option 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 option 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-2010 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

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

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