.TH ipmi_lan 5 06/26/12 OpenIPMI "IPMI LAN Interface config file"

.SH NAME
ipmi/lan.conf \- IPMI LAN Interface config file

.SH SYNOPSIS
.B /etc/ipmi/lan.conf

.SH DESCRIPTION
The
.B ipmi_sim
and
.B ipmilan
commands are configured using this configuration file.  

.SH CONFIGURATION ITEMS

The following fields are used in many commands:

.I "boolean"
May be "\fBtrue\fP", "\fBfalse\fP", "\fBon\fP" or "\fBoff\fP".

.I "priv"
An IPMI privilege level.  This may be "\fBcallback\fP", "\fBuser\fP", "\fBoperator\fP",
or "\fBadmin\fP".

.I "auth"
An IPMI authorization type.  This may be "\fBnone\fP" for no authentication,
"\fBstraight\fP" for straight, in-the-clear password authentication, "\fBmd2\fP"
for use MD2 message digest authentication, or "\fBmd5\fP" for using MD5
message digest authentication.

.SH FILE STRUCTURE

Blank lines and lines starting with `#' are ignored.

.PP
The following commands are allowed the configuration file:

.TP
\fBname\fP \fI"name"\fP
Set a name for the BMC.  This will control other things, like the
default value of the ipmi_sim startup command file and the place where
persistent data is stored.

.TP
\fBuser\fP \fIusernum\fP \fIenabled\fP \fIusername\fP \fIpassword\fP \fImax-priv\fP \fImax-session\fP
.I usernum
specifies the user number for the user.  Note that user number \fB0\fP is
invalid, and user number \fB1\fP is the special "anonymous" user, whose
username is ignored.  This value may be up to \fB63\fP, the maximum possible
IPMI user.  If you want anonymous access, you
.B must
have a user number \fB1\fI.

.I enabled
is a boolean that specified whether the user is enabled or not.

.I username
specifies the name of the user, specified as a name.

.I password
specifies the password of the user, specified as a name.

.I max-priv
specifies the maximum privilege level allowed for the user.

.I max.sessions
specifies the maximum number of session the user may open.

.TP
\fBstartcmd\fP \fI"cmd"\fP
specifies a command to execute when a power on is requested.  This lets
a virtual machine be started that can then connect back to the simulator.
The simulator does management of the process here, and the power on
state of the process depends on if the process exists or not.  If a
poweroff is requested, if the process is connected to a VM serial
interface, a graceful shutdown is first requested.  If the process
does not terminate in a specified amount of time, a SIGTERM is sent
to the process.  The SIGTERM is sent immediately if there is no
connection.  If the process doesn't go way in another specified amount
of time, a SIGKILL is sent.

.TP
\fBstartnow\fPtrue|false\fI\fP
If true, start the startcmd at the startup of the simulator.  Otherwise
wait until a poweron is issued.

.TP
\fBpoweroff_wait\fP \fIseconds\fP
specifies the amount of time to wait for the startcmd to do a graceful shutdown
on a powerdown request.  The simulator will send a request to the
target, wait this amount of time, and then do a SIGTERM kill on the
process.  If this is zero, a SIGTERM will not be done (nor will a SIGKILL).
Note that if the simulator does not have a connection to the VM, the
graceful shutdown is skipped and a SIGTERM is done immediately.
Default time is 60 seconds.

.TP
\fBkill_wait\fP \fIseconds\fP
specifies the amount of time to wait for SIGTERM to kill the process.
If the process does not terminate in this period of time, send a
SIGKILL kill.  If this is zero, don't send the SIGKILL.  Default time
is 20 seconds.

.TP
\fBconsole\fP \fIaddress\fP \fIport\fP
specifies that a console port be opened at the given address and port.
You can telnet to the console and execute emulation commands.  Note that
this is a pretty huge security hole, it should only be used for debugging
in a captive environment.

.TP
\fBserial\fP \fIchannel\fP \fIaddr\fP \fIport\fP [\fIoption\fP [\fIoption\fP [...]]]
.I channel
specifies the channel number or type.  This may be \fBkcs\fP,
\fBsmic\fP, or \fBbt\fP or it may be 15.  Currently, only the system
interface channel (channel 15) is supported for serial interfaces, if
the others are specified it is channel 15 and the given interface is
reported in channel configuration commands.

.I addr
specifies the IP address to listen on for connections.

.I port
specifies the port to listen on for connections.

Valid options are:

.I codec name
specifies which codec to use on the serial port.  Valid options are:
\fBTerminalMode\fP, \fBDirect\fP, \fBRadisysAscii\fP, and \fBVM\fP.
The first three are implementations of IPMI serial interfaces on
certain systems and might be used for simulations of that system.  The
\fBVM\fP is probably the most interesting; it is designed to be used
with a virtual machine like qemu.

.I oem name
specified implementation of some OEM custom commands and options
on the interface.  Valid options oare \fBPigeonPoint\fP and \fBRadisys\fP.

.I attn c1[,c2[...]]
specifies a list of characters, separated by commas, to use as the
attention character on the interface.  Generally the default is
correct.  The characters are specified as decimal, octal, or hex
digits in C style.

.I ipmb addr
specifies the IPMI address of the interface.  The default, 0x20, is
usually correct, but when emulating ATCA systems this might be
required.

.TP
\fBsol\fP \fIdevice\fP \fIdefault_baud\fP [\fIhistory=size[,backupfile=filename]\fP] [\fIhistoryfru=frunum\fP]

Allow a Serial Over LAN (SOL) connection to the given device.  This
will be over interface 1 for the MC.

.I device
is the full path to the device name.  It can also be in the form
"tcp:address:port" or "telnet:address:port" to do connections
over tcp (without or with telnet processing).  This is useful
for providing SOL access to qemu ports.

.I default_baud
sets the initial default baud rate to use.  This is overriden by the
persistent SOL settings.

.I history
creates a history device on SOL interface 2.  The size is the size of
the buffer.  Data from the device is stored in the history buffer all
the time.  Connecting to SOL interface 2 will cause the full history
buffer to be dumped.  If
.I backupfile
is specified, then the history is made persistent.  However, it is
only stored when a catchable signal or normal shutdown is done, so a
poweroff or fatal signal will cause the data to be lost.

.I historyfru
makes the history available via the given FRU number on the MC.

Note that if the connection fails to come up, the simulator will
continue to try to connect.  This way you can fix UDP serial ports or
qemu sessions and it will automatically reconnect.

.TP
\fBloadlib\fP \fI"module"\fP [\fI"options"\fP]

Load the given shared object into the program.

.I "module"
is the full path to the module.  It must be in quotes.

.I "options"
is an optional string in quotes that passes options to the module.
The contents of the string are not specified, the module defines that.

The module may have a number of functions that are called:

.I ipmi_sim_module_print_version(sys_data_t *sys, char *options)
is called when ipmi_sim is started with the version print option.
This way the versions of all loaded modules may be printed.  The
module should print it's version.  You must provide this function.

.I ipmi_sim_module_init(sys_data_t *sys, char *options)
is called after the configuration file is read and before any other
initialization is done.  The module should do most of its
initialization here.  You must provide this function.

.I ipmi_sim_module_post_init(sys_data_t *sys)
is called after ipmi_sim has finished initializing.  This function is
optional.

.P The
.I sys
parameter is used for most functions interfacing to the main ipmi_sim
code, like logging, timers, and a few of the MC calls.  The contents
are opaque to the module.


.TP
\fBstartlan\fP \fIchannel\fP
Starts a LAN configuration area.  This specifies the settings for a LAN
connection using the given channel.  This may be specified more than
once in a file to support multiple LAN connections.  Commands following
this, up to \fBendlan\fP, are LAN-specific commands listed below.
.I channel
specifies the channel to set the LAN configuration for.

.SH LAN CONFIGURATION COMMANDS

The following commands are only valid inside a \fBstartlen\fP area.

.TP
\fBaddr\fP \fIIP-address\fP [\fIUDP-port\fP]
.I IP-address
specifies the IP address to use for an IP port. Up to 4 addresses may be
specified.  If no address is specified, it defaults to one port at
\fB0.0.0.0\fP (for every address on the machine) at port \fB623\fP.

.I UDP-port
specifies an optional port to listen on. It defaults to \fB623\fP (the standard port).

.TP
.BI PEF_alerting\  boolean
Turn PEF alerting on or off (not currently supported).

.TP
.BI per_msg_auth\  boolean
Turn per-message authentication on or off.

.TP
.BI priv_limit\  priv
The maximum privilege allowed on this interface.

.TP
\fBallowed_auths_callback\fP [\fIauth\fP [\fIauth\fP [...]]]
.I auth
specifies allowed authorization levels for the callback privilege level.  Only
the levels specified on this line are allowed for the authorization
level.  If this line is not present, callback authorization cannot be
used.

.TP
\fBallowed_auths_user\fP [\fIauth\fP [\fIauth\fP [...]]]
.I auth
specifies allowed authorization levels for the user privilege level.  Only
the levels specified on this line are allowed for the authorization
level.  If this line is not present, user authorization cannot be
used.

.TP
\fBallowed_auths_operator\fP [\fIauth\fP [\fIauth\fP [...]]]
.I auth
specifies allowed authorization levels for the operator privilege level.  Only
the levels specified on this line are allowed for the authorization
level.  If this line is not present, operator authorization cannot be
used.

.TP
\fBallowed_auths_admin\fP [\fIauth\fP [\fIauth\fP [...]]]
.I auth
specifies allowed authorization levels for the admin privilege level.  Only
the levels specified on this line are allowed for the authorization
level.  If this line is not present, user authorization cannot be
used.

.TP
\fBguid\fP \fIname\fP
Allows the 16-byte GUID for the IPMI LAN connection to be specified.
If this is not specified, then the GUID command is not supported.

.SH "FILES"
/etc/ipmi_lan.conf

.SH "SEE ALSO"
.BR ipmilan (8), ipmi_sim (1)

.SH "KNOWN PROBLEMS"
IPMI is unnecessarily complicated.

.SH AUTHOR
.PP
Corey Minyard <cminyard@mvista.com>