/* Copyright (C) 1991‐2012 Free Software Foundation, Inc.
This file is part of the GNU C Library.
The GNU C Library is free software; you can redistribute it
and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later ver‐
sion.
The GNU C Library is distributed in the hope that it will be
useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Pub‐
lic
License along with the GNU C Library; if not, see
<http://www.gnu.org/licenses/>. */ /* This header is separate
from features.h so that the compiler can
include it implicitly at the start of every compilation. It
must
not itself include <features.h> or any other header that in‐
cludes
<features.h> because the implicit include comes before any
feature
test macros that may be defined in a source file before it
first
explicitly includes a system header. GCC knows the name of
this
header in order to preinclude it. */ /* We do support the IEC
559 math functionality, real and complex. */ /* wchar_t uses
ISO/IEC 10646 (2nd ed., published 2011‐03‐15) /
bmc-config.conf(5) System Commands bmc-config.conf(5)
Unicode 6.0. */ /* We do not support C11 <threads.h>. */
NAME
bmc-config - BMC configuration file format and details
DESCRIPTION
Before many IPMI tools can be used over a network, a machine's Base‐
board Management Controller (BMC) must be configured. The configuration
of a BMC can be quite daunting for those who do not know much about
IPMI. This manpage hopes to provide enough information on BMC configu‐
ration so that you can configure the BMC for your system. When appro‐
priate, typical BMC configurations will be suggested.
The following is an example BMC configuration file partially generated
from the bmc-config(1) command. This example configuration should be
sufficient for most users after the appropriate local IP and MAC
addresses are input. Following this example, separate sections of this
manpage will discuss the different sections of the BMC configuration
file in more detail with explanations of how the BMC can be configured
for different environments.
Note that many options may or may not be available on your particular
machine. For example, Serial-Over-Lan (SOL) is available only on IPMI
2.0 machines. Therefore, if you are looking to configure an IPMI 1.5
machine, many of the SOL or IPMI 2.0 related options will be be
unavailable to you. The number of configurable users may also vary for
your particular machine.
The below configuration file and most of this manpage assume the user
is interested in configuring a BMC for use with IPMI over LAN. Various
configuration options from bmc-config(1) have been left out or skipped
because it is considered unnecessary. Future versions of this manpage
will try to include more information.
Section User1
## Give username
## Username NULL
## Give password or leave it blank to clear password
Password mypassword
## Possible values: Yes/No or blank to not set
Enable_User Yes
## Possible values: Yes/No
Lan_Enable_Ipmi_Msgs Yes
## Possible values: Callback/User/Operator/Administrator/OEM_Proprietary/No_Access
Lan_Privilege_Limit Administrator
## Possible values: 0-17, 0 is unlimited; May be reset to 0 if not specified
## Lan_Session_Limit
## Possible values: Yes/No
SOL_Payload_Access Yes
EndSection
Section User2
## Give username
Username user2
## Give password or leave it blank to clear password
Password userpass
## Possible values: Yes/No or blank to not set
Enable_User No
## Possible values: Yes/No
Lan_Enable_Ipmi_Msgs No
## Possible values: Callback/User/Operator/Administrator/OEM_Proprietary/No_Access
Lan_Privilege_Limit No_Access
## Possible values: 0-17, 0 is unlimited; May be reset to 0 if not specified
## Lan_Session_Limit
## Possible values: Yes/No
SOL_Payload_Access No
EndSection
Section Lan_Channel
## Possible values: Disabled/Pre_Boot_Only/Always_Available/Shared
Volatile_Access_Mode Always_Available
## Possible values: Yes/No
Volatile_Enable_User_Level_Auth Yes
## Possible values: Yes/No
Volatile_Enable_Per_Message_Auth Yes
## Possible values: Yes/No
Volatile_Enable_Pef_Alerting No
## Possible values: Callback/User/Operator/Administrator/OEM_Proprietary/No_Access
Volatile_Channel_Privilege_Limit Administrator
## Possible values: Disabled/Pre_Boot_Only/Always_Available/Shared
Non_Volatile_Access_Mode Always_Available
## Possible values: Yes/No
Non_Volatile_Enable_User_Level_Auth Yes
## Possible values: Yes/No
Non_Volatile_Enable_Per_Message_Auth Yes
## Possible values: Yes/No
Non_Volatile_Enable_Pef_Alerting No
## Possible values: Callback/User/Operator/Administrator/OEM_Proprietary/No_Access
Non_Volatile_Channel_Privilege_Limit Administrator
EndSection
Section Lan_Conf
## Possible values: Unspecified/Static/Use_DHCP/Use_BIOS/Use_Others
Ip_Address_Source Static
## Give valid IP Address
Ip_Address 192.168.1.100
## Give valid MAC Address
Mac_Address 00:0E:0E:FF:AA:12
## Give valid Subnet mask
Subnet_Mask 255.255.255.0
## Give valid IP Address
Default_Gateway_Ip_Address 192.168.1.1
## Give valid MAC Address
Default_Gateway_Mac_Address 00:0E:0E:FF:AA:18
## Give valid IP Address
Backup_Gateway_Ip_Address 192.168.1.2
## Give valid MAC Address
Backup_Gateway_Mac_Address 00:0E:0E:FF:AA:15
EndSection
Section Lan_Conf_Auth
## Possible values: Yes/No
Callback_Enable_Auth_Type_None No
## Possible values: Yes/No
Callback_Enable_Auth_Type_Md2 No
## Possible values: Yes/No
Callback_Enable_Auth_Type_Md5 No
## Possible values: Yes/No
Callback_Enable_Auth_Type_Straight_Password No
## Possible values: Yes/No
Callback_Enable_Auth_Type_Oem_Proprietary No
## Possible values: Yes/No
User_Enable_Auth_Type_None No
## Possible values: Yes/No
User_Enable_Auth_Type_Md2 Yes
## Possible values: Yes/No
User_Enable_Auth_Type_Md5 Yes
## Possible values: Yes/No
User_Enable_Auth_Type_Straight_Password No
## Possible values: Yes/No
User_Enable_Auth_Type_Oem_Proprietary No
## Possible values: Yes/No
Operator_Enable_Auth_Type_None No
## Possible values: Yes/No
Operator_Enable_Auth_Type_Md2 Yes
## Possible values: Yes/No
Operator_Enable_Auth_Type_Md5 Yes
## Possible values: Yes/No
Operator_Enable_Auth_Type_Straight_Password No
## Possible values: Yes/No
Operator_Enable_Auth_Type_Oem_Proprietary No
## Possible values: Yes/No
Admin_Enable_Auth_Type_None No
## Possible values: Yes/No
Admin_Enable_Auth_Type_Md2 Yes
## Possible values: Yes/No
Admin_Enable_Auth_Type_Md5 Yes
## Possible values: Yes/No
Admin_Enable_Auth_Type_Straight_Password No
## Possible values: Yes/No
Admin_Enable_Auth_Type_Oem_Proprietary No
## Possible values: Yes/No
Oem_Enable_Auth_Type_None No
## Possible values: Yes/No
Oem_Enable_Auth_Type_Md2 No
## Possible values: Yes/No
Oem_Enable_Auth_Type_Md5 No
## Possible values: Yes/No
Oem_Enable_Auth_Type_Straight_Password No
## Possible values: Yes/No
Oem_Enable_Auth_Type_Oem_Proprietary No
EndSection
Section Lan_Conf_Security_Keys
## Give string or blank to clear. Max 20 chars
K_G
EndSection
Section Lan_Conf_Misc
## Possible values: Yes/No
Enable_Gratuitous_Arps Yes
## Possible values: Yes/No
Enable_Arp_Response No
## Give valid number. Intervals are 500 ms.
Gratuitous_Arp_Interval 4
EndSection
Section Rmcpplus_Conf_Privilege
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_0 Unused
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_1 Unused
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_2 Unused
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_3 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_4 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_5 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_6 Unused
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_7 Unused
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_8 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_9 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_10 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_11 Unused
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_12 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_13 Administrator
## Possible values: Unused/User/Operator/Administrator/OEM_Proprietary
Maximum_Privilege_Cipher_Suite_Id_14 Administrator
EndSection
Section SOL_Conf
## Possible values: Yes/No
Enable_SOL Yes
## Possible values: Callback/User/Operator/Administrator/OEM_Proprietary
SOL_Privilege_Level Administrator
## Possible values: Yes/No
Force_SOL_Payload_Authentication Yes
## Possible values: Yes/No
Force_SOL_Payload_Encryption Yes
## Give a valid integer. Each unit is 5ms
Character_Accumulate_Interval 50
## Give a valid number
Character_Send_Threshold 100
## Give a valid integer
SOL_Retry_Count 5
## Give a valid integer. Interval unit is 10ms
SOL_Retry_Interval 50
## Possible values: Serial/9600/19200/38400/57600/115200
Non_Volatile_Bit_Rate 115200
## Possible values: Serial/9600/19200/38400/57600/115200
Volatile_Bit_Rate 115200
EndSection
Section Misc
## Possible Values: Off_State_AC_Apply/Restore_State_AC_Apply/On_State_AC_Apply
Power_Restore_Policy Restore_State_Ac_Apply
EndSection
Section User1, User2, ...
The User sections of the BMC configuration file are for username con‐
figuration for IPMI over LAN communication. The number of users avail‐
able to be configured on your system will vary by manufacturer. With
the exception of the Username for User1, all sections are identical.
The username(s) you wish to configure the BMC with are defined with
Username. The first username under Section User1 is typically the NULL
username and cannot be modified. The password for the username can be
specified with Password. It can be left empty to define a NULL pass‐
word. Each user you wish to enable must be enabled through the
Enable_User configuration option. It is recommended that all usernames
have non-NULL passwords or be disabled for security reasons.
Lan_Enable_Ipmi_Msgs is used to enable or disable IPMI over LAN access
for the user. This should be set to "Yes" to allow IPMI over LAN tools
to work.
Lan_Privilege_Limit specifies the maximum privilege level limit the
user is allowed. Different IPMI commands have different privilege
restrictions. For example, determining the power status of a machine
only requires the "User" privilege level. However, power cycling
requires the "Operator" privilege. Typically, you will want to assign
atleast one user with a privilege limit of "Administrator" so that all
system functions are available to atleast one user via IPMI over LAN.
Lan_Session_Limit specifies the number of simultaneous IPMI sessions
allowed for the user. Most users will wish to set this to "0" to allow
unlimited simultaneous IPMI sessions. This field is considered optional
by IPMI standards, and may result in errors when attempting to config‐
ure it to a non-zero value. If errors to occur, setting the value back
to 0 should resolve problems.
SOL_Payload_Access specifies if a particular user is allowed to connect
with Serial-Over-LAN (SOL). This should be set to "Yes" to allow this
username to use SOL.
The example configuration above disables "User2" but enables the
default "NULL" (i.e. anonymous) user. Many IPMI tools (both open-source
and vendor) do not allow the user to input a username and assume the
NULL username by default. If the tools you are interested in using
allow usernames to be input, then it is recommended that one of the
non-NULL usernames be enabled and the NULL username disabled for secu‐
rity reasons. It is recommeneded that you disable the NULL username in
section User1, so that users are required to specify a username for
IPMI over LAN communication.
Some motherboards may require a Username to be configured prior to
other fields being read/written. If this is the case, those fields will
be set to <username-not-set-yet>.
Section Lan_Channel
The Lan_Channel section configures a variety of IPMI over LAN configu‐
ration parameters. Both Volatile and Non_Volatile configurations can be
set. Volatile configurations are immediately configured onto the BMC
and will have immediate effect on the system. Non_Volatile configura‐
tions are only available after the next system reset. Generally, both
the Volatile and Non_Volatile should be configured identically.
The Access_Mode parameter configures the availability of IPMI over LAN
on the system. Typically this should be set to "Always_Available" to
enable IPMI over LAN.
The Privilege_Limit sets the maximum privilege any user of the system
can have when performing IPMI over LAN. This should be set to the maxi‐
mum privilege level configured to a username. Typically, this should be
set to "Administrator".
Typically User_Level_Auth and Per_Message_Auth should be set to "Yes"
for additional security. Disabling User_Level_Auth allows "User" privi‐
leged IPMI commands to be executed without authentication. Disabling
Per_Message_Auth allows fewer individual IPMI messages to require
authentication.
Section Lan_Conf
Those familiar with setting up networks should find most of the fields
in this section self explanatory. The example BMC configuration above
illustrates the setup of a static IP address. The field
IP_Address_Source is configured with "Static". The IP address, subnet
mask, and gateway IP addresses of the machine are respecitvely config‐
ured with the IP_Address, Subnet_Mask, Default_Gateway_Ip_Address, and
Backup_Gateway_Ip_Address fields. The respective MAC addresses for the
IP addresses are configured under Mac_Address, Default_Gate‐
way_Mac_Address, and Backup_Gateway_Mac_Address.
It is not required to setup the BMC IP_Address to be the same P_Address
used by your operating system for that network interface. However, if
you choose to use a different address, an alternate ARP configuration
may need to be setup.
To instead setup your BMC network information via DHCP, the field
IP_Address_Source should be configured with "Use_DHCP".
It is recommended that static IP addresses be configured for address
resolution reasons. See Lan_Conf_Misc below for a more detailed expla‐
nation.
Section Lan_Conf_Auth
This section determines what types of password authentication mecha‐
nisms are allowed for users at different privilege levels under the
IPMI 1.5 protocol. The currently supported authentication methods for
IPMI 1.5 are None (no username/password required), Straight_Password
(passwords are sent in the clear), MD2 (passwords are MD2 hashed), and
MD5 (passwords are MD5 hashed). Different usernames at different priv‐
ilege levels may be allowed to authenticate differently through this
configuration. For example, a username with "User" privileges may be
allowed to authenticate with a straight password, but a username with
"Administrator" privileges may be allowed only authenticate with MD5.
The above example configuration supports MD2 and MD5 authentication for
all users at the "User", "Operator", and "Administrator" privilege lev‐
els. All authentication mechanisms have been disabled for the "Call‐
back" privilege level.
Generally speaking, you do not want to allow any user to authenticate
with None or Straight_Password for security reasons. MD2 and MD5 are
digital signature algorithms that can minimally encrypt passwords. If
you have chosen to support the NULL username (enabled User1) and NULL
passwords (NULL password for User1), you will have to enable the None
authentication fields above to allow users to connect via None.
Section Lan_Conf_Security_Keys
This section supports configuration of the IPMI 2.0 (including Serial-
over-LAN) K_g key. If your machine does not support IPMI 2.0, this
field will not be configurable.
The key is used for two-key authentication in IPMI 2.0. In most tools,
when doing IPMI 2.0, the K_g can be optionally specified. It is not
required for IPMI 2.0 operation.
In the above example, we have elected to leave this field blank so the
K_g key is not used.
Section Lan_Conf_Misc
This section lists miscellaneous IPMI over LAN configuration options.
These are optional IPMI configuration options that are not implemented
on all BMCs.
Normally, a client cannot resolve the ethernet MAC address without the
remote operating system running. However, IPMI over LAN would not work
when a machine is powered off or if the IP address used by the operat‐
ing system for that network interface differs from the BMC IP Address.
One way to work around this is through gratuitous ARPs. Gratuitous
ARPs are ARP packets generated by the BMC and sent out to advertise the
BMC's IP and MAC address. Other machines on the network can store this
information in their local ARP cache for later IP/hostname resolution.
This would allow IPMI over LAN to work when the remote machine is pow‐
ered off. The Enable_Gratuitous_Arps option allows you to enable or
disable this feature. The Gratuitous_Arp_Interval option allows you to
configure the frequency at which gratuitous ARPs are sent onto the net‐
work.
Instead of gratuitous ARPs some BMCs are able to respond to ARP
requests, even when powered off. If offerred, this feature can be
enabled through the Enable_Arp_Response option.
Generally speaking, turning on gratuitous ARPs is acceptable. However,
it will increase traffic on your network. If you are using IPMI on a
large cluster, the gratuitous ARPs may easily flood your network. They
should be tuned to occur less frequently or disabled. If disabled, the
remote machine's MAC address should be permanently stored in the local
ARP cache through arp(8).
See bmc-watchdog(8) for a method which allows gratuitous ARPs to be
disabled when the operating system is running, but enabled when the
system is down.
Section Rmcpplus_Conf_Privilege
This section supports configuration of the IPMI 2.0 (including Serial-
over-LAN) cipher suite IDs. If your machine does not support IPMI 2.0,
the fields will not be configurable.
Each cipher suite ID describes a combination of an authentication algo‐
rithm, integrity algorithm, and encryption algorithm for IPMI 2.0. The
authentication algorithm is used for user authentication with the BMC.
The integrity algorithm is used for generating signatures on IPMI pack‐
ets. The confidentiality algorithm is used for encrypting data. The
configuration in this section enables certain cipher suite IDs to be
enabled or disabled, and the maximum privilege level a username can
authenticate with.
The following table shows the cipher suite ID to algorithms mapping:
0 - Authentication Algorithm = None; Integrity Algorithm = None; Confi‐
dentiality 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
4 - Authentication Algorithm = HMAC-SHA1; Integrity Algorithm = HMAC-
SHA1-96; Confidentiality Algorithm = xRC4-128
5 - Authentication Algorithm = HMAC-SHA1; Integrity Algorithm = HMAC-
SHA1-96; Confidentiality Algorithm = xRC4-40
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
9 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = HMAC-
MD5-128; Confidentiality Algorithm = xRC4-128
10 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm = HMAC-
MD5-128; Confidentiality Algorithm = xRC4-40
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
13 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm =
MD5-128; Confidentiality Algorithm = xRC4-128
14 - Authentication Algorithm = HMAC-MD5; Integrity Algorithm =
MD5-128; Confidentiality Algorithm = xRC4-40
Generally speaking, HMAC-SHA1 based algorithms are stronger than HMAC-
MD5, which are better than MD5-128 algorithms. AES-CBC-128 confiden‐
tiality algorithms are stronger than xRC4-128 algorithms, which are
better than xRC4-40 algorithms. Cipher suite ID 3 is therefore typi‐
cally considered the most secure. Some users may wish to set cipher
suite ID 3 to a privilege level and disable all remaining cipher suite
IDs.
The above example configuration has decided to allow any user with
"Administrator" privileges use any Cipher Suite algorithm suite which
requires an authentication, integrity, and confidentiality algorithm.
Typically, the maximum privilege level configured to a username should
be set for atleast one cipher suite ID. Typically, this is the "Admin‐
istrator" privilege.
A number of cipher suite IDs are optionally implemented, so the avail‐
able cipher suite IDs available your system may vary.
Section SOL_Conf
This section is for setting up Serial-Over-Lan (SOL) and will only be
available for configuration on those machines. SOL can be enabled with
the Enable_SOL field. The minimum privilege level required for connect‐
ing with SOL is specified by SOL_Privilege_Level. This should be set
to the maximum privilege level configured to a username that has SOL
enabled. Typically, this is the "Administrator" privilege. Authentica‐
tion and Encryption can be forced or not using the fields
Force_SOL_Payload_Authentication and Force_SOL_Payload_Encryption
respectively. It is recommended that these be set on. However, forced
authentication and/or encryption support depend on the cipher suite IDs
supported.
The Character_Accumulate_Interval, Character_Send_Threshold ,
SOL_Retry_Count and , SOL_Retry_Interval options are used to set SOL
character output speeds. Character_Accumulate_Interval determines how
often serial data should be regularly sent and Character_Send_Threshold
indicates the character count that if passed, will force serial data to
be sent. SOL_Retry_Count indicates how many times packets must be
retransmitted if acknowledgements are not received. SOL_Retry_Interval
indicates the timeout interval. Generally, the manufacturer recommended
numbers will be sufficient. However, you may wish to experiment with
these values for faster SOL throughput.
The Non_Volatile_Bit_Rate and Volatile_Bit_Rate determine the baudrate
the BMC should use. This should match the baudrate set in the BIOS and
operating system, such as agetty(8). Generally speaking, both the
Volatile and Non_Volatile options should be set identically.
In addition to enabling SOL in this section, individual users most also
be capable of connecting with SOL. See the section Section User1,
User2, ... above for details.
Section Misc
The Power_Restore_Policy determines the behavior of the machine when AC
power returns after a power loss. The behavior can be set to always
power on the machine ("On_State_AC_Apply"), power off the machine
("Off_State_AC_Apply"), or return the power to the state that existed
before the power loss ("Restore_State_AC_Apply").
REPORTING BUGS
Report bugs to <freeipmi-users@gnu.org> or <freeipmi-devel@gnu.org>.
SEE ALSOfreeipmi(7), bmc-config(8), bmc-watchdog(8), agetty(8)
http://www.gnu.org/software/freeipmi/
bmc-config 1.2.9 2014-05-01 bmc-config.conf(5)
