path: root/doc/iserial.8

.TH ISERIAL 8 "Version 2.2: 17 Feb 2010"
.SH NAME
ipmiutil_serial \- configure a system for Serial/EMP management functions, such as Terminal Mode, and optionally share the port with the Serial Console.
.SH SYNOPSIS
.B "ipmiutil serial [-bcdeflq#rsvxB -m0 -m1 -n ser_chan -u user -p passwd -NUPREFJTVY]"

.SH DESCRIPTION
.I ipmiutil serial
is a program that uses an IPMI driver to send IPMI commands which
configure a system to enable EMP/serial Terminal Mode management
functions within the firmware, so that an administrator can use
command-line character commands via the serial port to
power cycle the system and perform other functions,
even if the system is not running an OS.
This level of access needs to be protected by a username/password
login, which can be specified with this utility.
This utility can use either the /dev/ipmi0 driver from OpenIPMI,
the /dev/imb driver from Intel, the /dev/ipmikcs driver from valinux,
direct user-space IOs, or the IPMI LAN interface if \-N.

.SH OPTIONS
Command line options are described below.
.IP "-b"
Set up and enable the Serial Port EMP parameters for Basic Mode management functions.  This does not set a username or password.
.IP "-c"
Configure and enable the Serial Port EMP parameters for Terminal Mode management functions, shared with BIOS Console Redirection.
Setting a new username and password for serial access via \-u and \-p is
recommended for security.
.IP "-d"
Disable the serial port access for IPMI commands.  The serial port is then
only available for BIOS console and OS functions.
A side-effect of this option is that it sets the default user (1) back to
admin access.
.IP "-e"
Enable EMP Terminal Mode without shared BIOS console.  The serial port is
then only available for EMP Terminal Mode functions.
.IP "-f"
Specifies the Flow Control for the Serial EMP.  0 means no flow control, and
1 means RTS/CTS flow control (default).  This must match the BIOS Serial
Console setting.
.IP "-l"
Show LAN Parameters. This option reads and displays the LAN Parameter
configuration also.
.IP "-m0"
Switch the Serial Port MUX to Baseboard/BIOS Console operation.
Set no other configuration parameters.
.IP "-m1"
Switch the Serial Port MUX to Terminal Mode management.
Set no other configuration parameters.
.IP "-n ser_chan"
Sets the IPMI channel number to use for the EMP serial channel
(often 4).  Note that the IPMI channels for LAN, Serial, etc.
are numbered differently on each platform type.
The default is to detect the first available IPMI serial channel.
.IP "-#"
Same as \-q below.
.IP "-q"
Specify an alternate user number for the EMP Username from the \-u option.
This is normally user number 2, 3, or 4, where 3 is the default.
The maximum number of users is 15.
.IP "-r"
Read Only.  This option just reads the Serial Parameter configuration
without writing any values.
.IP "-s"
Set up and enable the Serial Port EMP parameters for Shared operation
between Basic Mode management functions and Baseboard (BIOS) Remote Console.
This option switches the Serial Port MUX to Baseboard Console operation.
.IP "-t"
Configure and enable the Serial Port EMP parameters for Terminal Mode management functions, shared with BIOS Console Redirection.  Same as \-c, but easier to remember.
.IP "-u username"
This specifies a username for the EMP Terminal Mode login.  It can
be any string, up to 15 characters.  If \-u is not used, the default user 1
(null) will be assumed.  The username, if specified, will be set for user 3,
unless option \-q is specified.
.IP "-p password"
This specifies a password for the EMP Terminal Mode login.  It can
be any string, up to 15 characters.  A null password is used if
none is specified.  This password applies to user 3 if \-u is used, to
user 1 otherwise.
.IP "-v priv"
Set a specific access priVilege for this user, where priv can be:
1=Callback, 2=User, 3=Operator, 4=Admin, 5=OEM, 15=NoAccess
The default if not specified or specified in error, is to use 4=Admin.
.IP "-x"
Causes extra debug messages to be displayed.
.IP "-B"
Set the Baud rate of the serial port to one of the following:
9600, 19,2K, 38.4K, 57.6K, or 115.2K.  The default is 19.2K bps.

.IP "-N nodename"
Nodename or IP address of the remote target system.  If a nodename is
specified, IPMI LAN interface is used.  Otherwise the local system
management interface is used.
.IP "-P/-R rmt_pswd"
Remote password for the nodename given.  The default is a null password.
.IP "-U rmt_user"
Remote username for the nodename given.  The default is a null username.
.IP "-E"
Use the remote password from Environment variable IPMI_PASSWORD.
.IP "-F drv_t"
Force the driver type to one of the followng:
imb, va, open, gnu, landesk, lan, lan2, lan2i, kcs, smb.
Note that lan2i means lan2 with intelplus.
The default is to detect any available driver type and use it.
.IP "-J"
Use the specified LanPlus cipher suite (0 thru 17): 0=none/none/none,
1=sha1/none/none, 2=sha1/sha1/none, 3=sha1/sha1/cbc128, 4=sha1/sha1/xrc4_128,
5=sha1/sha1/xrc4_40, 6=md5/none/none, ... 14=md5/md5/xrc4_40.
Default is 3.
.IP "-T"
Use a specified IPMI LAN Authentication Type: 0=None, 1=MD2, 2=MD5, 4=Straight Password, 5=OEM.
.IP "-V"
Use a specified IPMI LAN privilege level. 1=Callback level, 2=User level, 3=Operator level, 4=Administrator level (default), 5=OEM level.
.IP "-Y"
Yes, do prompt the user for the IPMI LAN remote password.
Alternatives for the password are \-E or \-P.

.SH EXAMPLES

.IP "ipmiutil serial -t (or -c)"
Enables Terminal Mode management functions, shared with BIOS Serial Console redirection.  The user can switch between serial console operations and IPMI Terminal Mode commands by typing ESC ')' and ESC 'Q'.

.IP "ipmiutil serial -s"
Enables Basic Mode management functions shared with BIOS Serial Console redirection.  The user can switch between serial console operations and IPMI Basic Mode management programs on the same serial port.

.IP "ipmiutil serial -d"
Disables the serial port management functions.  This would be used if only the BIOS Serial Console were used and no BMC serial management functions.

.P
How to login to a Terminal Mode console:
.br
ESC (                   (switch to Terminal mode)
.br
[SYS PWD \-N ]           (login for default user, null psw)
.br
[SYS PWD \-U ROOT \-N PASSWORD]  (syntax example for user 3)
.br
[SYS 000157 ACTIVATE]   (activate advanced commands)
.br
[SYS HEALTH QUERY]
.br
[SYS HELP]
.br
[SYS PWD]               (logoff)
.br
ESC Q                   (switch to BIOS console)
.br
See IPMI 1.5 Spec, Appendix E, and Intel TIGPR2U TPS for more information.

.SH DEPENDENCIES
The ipmiutil serial utility is intended to configure the EMP serial port on the
server for shared access between BMC/IPMI functions and BIOS Console
Redirection.  Some platforms only support only Basic Mode for BMC/IPMI
functions.  Basic Mode requires a remote client application to utilize it
(Windows ISC Console/DPC, or a special modified Linux telnet).
There are some platforms which implement Terminal Mode via IPMI v1.5
Appendix E to make remote management with character commands available
on the serial port without a special remote client application.

For example, Intel TSRLT2 systems would use "ipmiutil serial \-s" for Basic Mode
shared functions, but Intel TIGPR2U systems could use "ipmiutil serial \-c" to
configure Terminal Mode functions.  On your system, run "ipmiutil serial \-r" to
check whether Serial Param(29): "Terminal Mode Config" is supported.  If
not, configure Basic Mode via "ipmiutil serial \-s".


.SH "PLATFORM SERIAL PORT CONFIGURATION EXAMPLES"

First, enter BIOS Setup for Serial Console Redirection parameters:
(these vary by platform)
.br
  Console Redirection = Serial Port B
.br
  ACPI Redirection = Disabled
.br
  Baud Rate = 115.2K
.br
  Flow Control = CTS/RTS
.br
  Terminal Type = VT100
.br
  Legacy Redirection = Enabled
.br
Note that the Baud Rate can vary, but it must match in all
locations where it is used (BIOS, IPMI, and Linux).
.br
For some non-Intel platforms, the serial console would be
COM1 instead of COM2, but should be enabled in BIOS.
.br
From Linux, run "ipmiutil serial \-c" for Terminal Mode shared configuration.
.br
Or, on older Intel TSRLT2 platforms:
From Linux, run "ipmiutil serial \-s" for Basic Mode Shared configuration.

.SH "LINUX CONFIGURATION FOR SERIAL CONSOLE"

If using lilo, in /etc/lilo.conf, add
.br
  append="console=ttyS1,19200n8 console=tty0"
.br
(and comment out the "message=" line because it includes graphics)
.br
Note that the append line can be placed in the global section
and removed from each kernel section if there are no other differences.

.PP
Or, if using grub, edit /boot/grub/grub.conf as follows:
.br
  #Omit the splashimage or gfxmenu
.br
  # splashimage=(hd0,0)/grub/splash.xpm.gz
.br
  #The serial and terminal lines are not usually needed
.br
  # serial \-\-unit=1 \-\-speed=19200 \-\-word=8 \-\-parity=no \-\-stop=1
.br
  # terminal \-\-timeout=10 serial console
.br
  #Add the console=ttyS* parameter to the kernel line
.br
    kernel (hd0,0) /vmlinuz root=/dev/sda2 console=ttyS1,19200n8

.PP
Add this line to /etc/initab, if ttyS1 is not already there:
.br
  co:2345:respawn:/sbin/agetty ttyS1 19200 vt100
.PP
Add this line to /etc/securetty, if ttyS1 is not already there:
.br
  ttyS1

.SH "SEE ALSO"
ipmiutil(8) ialarms(8) iconfig(8) icmd(8) idiscover(8) ievents(8) ifru(8) igetevent(8) ihealth(8) ilan(8) ireset(8) isel(8) isensor(8) isol(8) iwdt(8)

.SH WARNINGS
See http://ipmiutil.sourceforge.net/ for the latest version of ipmiutil and any bug fix list.

.SH COPYRIGHT
Copyright (C) 2009  Kontron America, Inc.
.PP
See the file COPYING in the distribution for more details
regarding redistribution.
.PP
This utility is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY.

.SH AUTHOR
.PP
Andy Cress <arcress at users.sourceforge.net>
.br