summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2014-07-23 15:03:01 +0200
committerJörg Frings-Fürst <debian@jff-webhosting.net>2014-07-23 15:03:01 +0200
commit777af8a8761d05c30588abec7444b143fe7393f0 (patch)
tree5a135c37eaa9ac94772819a28ce5beedd18e5c4a /README
parentc3445516ecd58e97de483cf4b7fafcc1104890d7 (diff)
parentb32d92e890caac903491116e9d817aa780c0323b (diff)
Merge tag 'upstream/1.8.14'
Upstream version 1.8.14
Diffstat (limited to 'README')
-rw-r--r--README414
1 files changed, 414 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..cc5915c
--- /dev/null
+++ b/README
@@ -0,0 +1,414 @@
+
+ ipmitool
+ Duncan Laurie
+ ipmitool-devel@lists.sourceforge.net
+
+Overview
+========
+ipmitool is a utility for managing and configuring devices that support
+the Intelligent Platform Management Interface. IPMI is an open standard
+for monitoring, logging, recovery, inventory, and control of hardware
+that is implemented independent of the main CPU, BIOS, and OS. The
+service processor (or Baseboard Management Controller, BMC) is the brain
+behind platform management and its primary purpose is to handle the
+autonomous sensor monitoring and event logging features.
+
+The ipmitool program provides a simple command-line interface to this BMC.
+It features the ability to read the sensor data repository (SDR) and print
+sensor values, display the contents of the System Event Log (SEL), print
+Field Replaceable Unit (FRU) inventory information, read and set LAN
+configuration parameters, and perform remote chassis power control.
+
+
+Background
+==========
+I originally wrote ipmitool while between projects and employeed at Sun
+Microsystems. Sun had just embarked on a new line of general-purpose x86
+servers that inclued an OEM Intel board with an IPMIv1.5 BMC on board.
+It started with an idea that remote chassis power control would be a handy
+feature for my systems in the lab and from there it grew into a multi-
+purpose tool that lots of people found useful. I decided to release it
+under a BSD license and give others the chance to make use of it.
+
+ipmitool was not written to provide large-scale (aka Enterprise) management
+application functionality. The functionality that ipmitool proivides is
+easily accomplished by sending simple IPMI request messages and parsing
+the returned response. It is intended to be used by system administrators
+who like the simplicity and scriptability of command-line utilities, as
+well as those debugging or developing their own BMC implementations.
+
+
+Requirements
+============
+Obviously the largest requirement is hardware with a service processor
+that supports the IPMI specification. Many x86-based servers are now
+comming with IPMI support, check with your preferred hardware vendor
+about available prodcuts.
+
+Once you are certain you have the required hardware, you then need to
+decide how you want to access the BMC. The most common case involve
+access through the System Interface or over the LAN. (or serial, but
+currently ipmitool does not support the serial interface)
+
+
+System Interface
+----------------
+There are multiple types of system interfaces, but they are all similar
+enough to allow a single well-designed driver to support them all.
+Different types of system interfaces include Keyboard Controller Style
+(KCS), Block Transfer (BT), System Management Interface Chip (SMIC) and
+SMBus. Different hardware vendors will have different preference and
+implementations.
+
+On Linux the OpenIPMI kernel driver should support all of these system
+interfaces and it should be a simple matter of loading the right
+kernel modules and setting up the device node to use it. The driver
+module names vary slightly in different kernel versions, but for all
+releases you need these two modules:
+
+ ipmi_msghandler: incoming and outgoing message handler
+ ipmi_devintf: character device interface to IPMI driver
+
+For 2.4.x and early 2.6.x kernels you need to choose a module based on
+the type of system interface your hardware supports. For example:
+
+ ipmi_kcs_drv: Keyboard Controller Style driver
+
+More recent 2.6.x kernels have combined these into a single module:
+
+ ipmi_si: a universal IPMI system interface driver
+
+See the documentation that comes with your distribution and/or kernel
+for more information on what kernel modules are required. Once the
+required modules are loaded and the driver has found a suitable system
+interface to the BMC then you need to ensure the device node at
+/dev/ipmi0 is pointing at the correct major number.
+
+This is because OpenIPMI is given a dynamically assigned major number
+when it is loaded, but depending on what other modules are present
+this number may be anywhere from 254 on down. The easiest way to tell
+is to check the output of /proc/devices and see what major number the
+"ipmidev" device is assigned to.
+
+There is a sample script included with ipmitool called ipmi.init that
+can be used to automate this process at bootup.
+
+
+LAN Interface
+-------------
+This is often referred to as "IPMI-over-LAN" and defines how IPMI messages
+can be sent to and from the BMC encapsulated in Remote Management Control
+Protocol (RMCP) packets which are then transferred as UDP datagrams.
+
+IPMI-over-LAN is only supported with version 1.5 and higher of the IPMI
+specification. The RMCP packet format is defined by the Alert Standard
+Forum, and it has been followed up with the RMCP+ protocol that adds
+encryption and payload support. The IPMIv2 specification was updated
+accordingly to to support the RMCP+ protocol and brings with it enhanced
+security with encryption as well as support for Serial over LAN.
+
+There are different types of LAN interfaces as well. Some systems have
+shared management networks where the NIC will intercept UDP packets to
+port 623 and redirect them to the BMC over SMBUS. This type of LAN
+interface requires that the BMC be configured with the same settings that
+the system uses. It also suffers from an increased security risk just by
+the nature of sharing that interface with normal traffic.
+
+I have also seen bugs in some implementations that have rendered the
+IPMI-over-LAN feature "dangerous" to enable in some situations. (in
+particular there can be an issue with RPC because it will sometimes choose
+to use port 623 and you will lose response packets...)
+
+There is a sample shell script included with ipmitool called bmclanconf
+that can be used to simplify the LAN settings configuration process using
+the System Interface to configure the settings. In some cases the
+hardware will come with a utility (often a DOS bootable CD) for configuring
+enabling the LAN interface as well.
+
+In order to support the IPMIv2.0 interface you must have an OpenSSL library
+with the required encrytion functions. Recent distributions should have
+no problems. The IPMIv1.5 interface will attempt to use OpenSSL for MD5
+hash function at compile time but if that is not found it will use an
+internal library.
+
+IPMB Dual Bridging in IPMITOOL
+-------------------------------
+
+IPMI offers a standard messaging interface.
+
+The following concepts are related to this messaging interface:
+
+Channel type : Communication channel type (SMS/KCS, IPMB, LAN)
+Channel number : Channel descriptor
+Requester : Address of the requester
+Responder : Address of the responder
+NetFN : The logical function for the request/response.
+Command : The command number
+Sequence : An ID identifiying the request/response pair
+Message tracking : The ability to match request/response pair.
+
+When a communication is issued through any of the channels, an application
+formats a request and expect a response.
+
+Direct Command
+--------------
+The simplest form of communication is a "direct command" using SMS/KCS
+
+Example:
+ ipmitool raw 6 4
+ 55 00
+
+This send raw command 4 (selftest) from netfn 6(application) to KCS, the driver
+takes care of 'message tracking' and provides the answer.
+
+Hopefully, the application also includes a "human readable" instance of the API:
+ ipmitool mc selftest
+ Selftest: passed
+
+Bridged Command
+---------------
+One slightly more complicated communication mode is the so-called
+"bridged command" using IPMB.
+
+Example:
+ ipmitool -m 0x94 -t 0x9a raw 6 4
+ 55 00
+
+ or
+
+ ipmitool -m 0x94 -t 0x9a mc selftest
+ Selftest: passed
+
+
+This still sends the same command 4 (selftest) from netfn 6(application) to
+the target. However, to do so, the command is encapsulated (by the driver) and
+sent using the command 0x34 (send message) from netfn 6(application) to KCS.
+Then KCS is polled by the driver until a message has been received, then the
+driver uses command 0x33 (get message). The driver also tracks the message
+and makes sure the response matches the request. Then it decapsultates the
+message and gives the response back to the application.
+
+Dual Bridged Command
+--------------------
+Things get a little more ugly when the application needs to reach a management
+controller sitting on an interface (or channel) not directly connected to the
+BMC/IPMC. In the case the application must encapsulate its message itself and
+request the IPMC to deal with message tracking itself.
+
+Its been working well with IPMITOOL on the LAN interface with:
+ ipmitool -H <ip> -U <user> -P <password> -B 0 -T 0x8a -m 0x20 -t 0x7a -b 7
+ mc selftest
+
+However, trying to dual bridge commands locally with :
+ ipmitool -B 0 -T 0x9a -m 0x94 -t 0x7a -b 7 mc selftest didn't work
+ (it returned the same data as ipmitool -m 0x20 -t 0x7a -b 7 mc selftest )
+
+The reason was that the "openipmi" interface pluging didn't
+encapsulate/decapsulate the message and didn't even detect the intent
+to double bridge the request.
+
+ ./src/ipmitool -B 0 -T 0x8a -m 0x94 -t 0x7a -b 7 mc selftest
+
+-B 0 : transit channel for first bridge level (channel 0: IPMB-0)
+-T 0x8a : transit destination address (remote IPMC address)
+-m 0x94 : source address (local IPMC address on IPMB-0)
+-t 0x7a : remote target (AMC IPMB-L address)
+-b 7 : remote channel (channel 7: IPMB-L)
+
+The transit source address (remote IPMC address on remote channel) is
+automatically assigned by the remote IPMC.
+
+Payload Size Limit
+------------------
+Because some commands return a lot of data (fru read/get sdr) and because 2
+levels of encapsulation are used, some command will fail.
+
+For instance this works.
+
+ipmitool -H <ip> -U <user> -P <password> -B 0 -T 0x8a -m 0x94 -t 0x7a -b 7
+ mc selftest
+
+but this does not:
+
+ipmitool -H <ip> -U <user> -P <password> -B 0 -T 0x8a -m 0x94 -t 0x7a -b 7
+ fru print.
+
+
+
+Usage
+=====
+All invocations of ipmitool require specifying an interface to use, unless
+you want to use the default interface as set at compile time. Each call
+must also specify a command to run. You can see the list of supported
+interfaces and which is default as well as a list of top level commands in
+the usage output available with the -h option:
+
+usage: ipmitool [options...] <command>
+
+ -h This help
+ -V Show version information
+ -v Verbose (can use multiple times)
+ -c Display output in comma separated format
+ -I intf Interface to use
+ -H hostname Remote host name for LAN interface
+ -p port Remote RMCP port [default=623]
+ -L level Remote session privilege level [default=USER]
+ -A authtype Force use of authtype NONE, PASSWORD, MD2 or MD5
+ -U username Remote session username
+ -P password Remote session password
+ -f file Read remote session password from file
+ -a Prompt for remote password
+ -E Read password from IPMI_PASSWORD environment variable
+ -m address Set local IPMB address
+ -t address Bridge request to remote target address
+
+Interfaces:
+ open Linux OpenIPMI Interface [default]
+ imb Intel IMB Interface
+ lan IPMI v1.5 LAN Interface
+ lanplus IPMI v2.0 RMCP+ LAN Interface
+
+Commands:
+ raw Send a RAW IPMI request and print response
+ lan Configure LAN Channels
+ chassis Get chassis status and set power state
+ event Send pre-defined events to BMC
+ bmc Print BMC status and configure global enables
+ sdr Print Sensor Data Repository entries and readings
+ sensor Print detailed sensor information
+ fru Print built-in FRU and scan SDR for FRU locators
+ sel Print System Evelnt Log
+ sol Configure IPMIv2.0 Serial-over-LAN
+ user Configure BMC users
+ channel Configure BMC channels
+ session Print session information
+ shell Launch interactive IPMI shell
+ exec Run list of commands from file
+ set Set runtime variable for shell and exec
+
+
+Commands
+========
+More help on the supported commands can be found by running them with the
+help argument, for example "chassis help". There are a few commands with
+special meaning:
+
+> shell: This command will launch an shell interface to the ipmitool
+ command set. You can use this for interactively entering commands to
+ monitor system status. An example session:
+
+# ipmitool -I open shell
+ipmitool> chassis status
+System Power : off
+Power Overload : false
+Power Interlock : inactive
+Main Power Fault : false
+Power Control Fault : false
+Power Restore Policy : always-off
+Last Power Event : command
+Chassis Intrusion : active
+Front-Panel Lockout : inactive
+Drive Fault : false
+Cooling/Fan Fault : false
+ipmitool> user list 7
+ID Name Callin Link Auth IPMI Msg Channel Priv Limit
+1 true false true ADMINISTRATOR
+ipmitool> exit
+
+> exec: This command will read a text file and execute ipmitool commands
+ in sequence. It can be used for scriptable commands:
+
+# cat lansetup.scr
+lan set 7 ipsrc static
+lan set 7 ipaddr 10.1.1.10
+lan set 7 netmask 255.255.255.0
+lan set 7 defgw ipaddr 10.1.1.254
+# ipmitool -I open exec lansetup.scr
+Setting LAN IP Address to 10.1.1.10
+Setting Lan Subnet Mask to 255.255.255.0
+Setting Lan Default Gateway IP to 10.1.1.254
+
+> set: This command can be used by the shell and exec modes to configure
+ various session parameters:
+
+ hostname <host> Session hostname
+ username <user> Session username
+ password <pass> Session password
+ privlvl <level> Session privilege level force
+ authtype <type> Authentication type force
+ localaddr <addr> Local IPMB address
+ targetaddr <addr> Remote target IPMB address
+ port <port> Remote RMCP port
+ csv [level] enable output in comma separated format
+ verbose [level] Verbose level
+
+# cat getstatus.scr
+set hostname sf-v20z-1
+set password admin
+chassis status
+# ipmitool -I lan exec getstatus.scr
+Set session hostname to lx50
+Set session password
+System Power : off
+Power Overload : false
+Power Interlock : inactive
+Main Power Fault : false
+Power Control Fault : false
+Power Restore Policy : always-off
+Last Power Event : command
+Chassis Intrusion : active
+Front-Panel Lockout : inactive
+Drive Fault : false
+Cooling/Fan Fault : false
+
+
+ipmievd
+=======
+Included with ipmitool is another utility called ipmievd that is a daemon
+which will listen for events from the BMC that are being sent to the SEL
+and also log those messages to syslog. By default when run (as root) with
+no arguments it will daemonize and poll on the OpenIPMI device waiting for
+an event notification. Upon receipt of an event it will log it to syslog
+with the LOG_LOCAL4 facility. You can test ipmievd by sending test events
+over the LAN interface with ipmitool:
+
+remote# ipmievd
+
+local$ ipmitool -I lan -H lx50 -P admin event help
+usage: event <num>
+ 1 : Temperature - Upper Critical - Going High
+ 2 : Voltage Threshold - Lower Critical - Going Low
+ 3 : Memory - Correctable ECC
+local$ ipmitool -I lan -H lx50 -P admin event 1
+Sending Temperature - Upper Critical - Going High event to BMC
+local$ ipmitool -I lan -H lx50 -P admin event 2
+Sending Voltage Threshold - Lower Critical - Going Low event to BMC
+local$ ipmitool -I lan -H lx50 -P admin event 3
+Sending Memory - Correctable ECC event to BMC
+
+remote# tail /var/log/messages (timestamps removed)
+ipmievd: Waiting for events...
+ipmievd: Temperature Sensor 30 - Upper Critical - going high
+ipmievd: Voltage Sensor 60 - Lower Critical - going low
+ipmievd: Memory Sensor 01 - Correctable ECC
+
+
+Resources
+=========
+IPMItool homepage
+http://ipmitool.sourceforge.net
+
+IPMItool manpage
+http://ipmitool.sourceforge.net/manpage.html
+
+IPMItool overview paper from Linux.conf.au 2004
+http://ipmitool.sourceforge.net/lca2004_ipmitool.pdf
+
+Intelligent Platform Management Interface specification
+http://www.intel.com/design/servers/ipmi/spec.htm
+
+OpenIPMI project: Linux IPMI kernel driver and userland library
+http://openipmi.sourceforge.net
+
+IPMItool commit archive
+https://lists.sourceforge.net/lists/listinfo/ipmitool-cvs