1 2 ipmitool 3 Duncan Laurie 4 ipmitool-devel@lists.sourceforge.net 5 6Overview 7======== 8ipmitool is a utility for managing and configuring devices that support 9the Intelligent Platform Management Interface. IPMI is an open standard 10for monitoring, logging, recovery, inventory, and control of hardware 11that is implemented independent of the main CPU, BIOS, and OS. The 12service processor (or Baseboard Management Controller, BMC) is the brain 13behind platform management and its primary purpose is to handle the 14autonomous sensor monitoring and event logging features. 15 16The ipmitool program provides a simple command-line interface to this BMC. 17It features the ability to read the sensor data repository (SDR) and print 18sensor values, display the contents of the System Event Log (SEL), print 19Field Replaceable Unit (FRU) inventory information, read and set LAN 20configuration parameters, and perform remote chassis power control. 21 22 23Background 24========== 25I originally wrote ipmitool while between projects and employeed at Sun 26Microsystems. Sun had just embarked on a new line of general-purpose x86 27servers that inclued an OEM Intel board with an IPMIv1.5 BMC on board. 28It started with an idea that remote chassis power control would be a handy 29feature for my systems in the lab and from there it grew into a multi- 30purpose tool that lots of people found useful. I decided to release it 31under a BSD license and give others the chance to make use of it. 32 33ipmitool was not written to provide large-scale (aka Enterprise) management 34application functionality. The functionality that ipmitool proivides is 35easily accomplished by sending simple IPMI request messages and parsing 36the returned response. It is intended to be used by system administrators 37who like the simplicity and scriptability of command-line utilities, as 38well as those debugging or developing their own BMC implementations. 39 40 41Requirements 42============ 43Obviously the largest requirement is hardware with a service processor 44that supports the IPMI specification. Many x86-based servers are now 45comming with IPMI support, check with your preferred hardware vendor 46about available prodcuts. 47 48Once you are certain you have the required hardware, you then need to 49decide how you want to access the BMC. The most common case involve 50access through the System Interface or over the LAN. (or serial, but 51currently ipmitool does not support the serial interface) 52 53 54System Interface 55---------------- 56There are multiple types of system interfaces, but they are all similar 57enough to allow a single well-designed driver to support them all. 58Different types of system interfaces include Keyboard Controller Style 59(KCS), Block Transfer (BT), System Management Interface Chip (SMIC) and 60SMBus. Different hardware vendors will have different preference and 61implementations. 62 63On Linux the OpenIPMI kernel driver should support all of these system 64interfaces and it should be a simple matter of loading the right 65kernel modules and setting up the device node to use it. The driver 66module names vary slightly in different kernel versions, but for all 67releases you need these two modules: 68 69 ipmi_msghandler: incoming and outgoing message handler 70 ipmi_devintf: character device interface to IPMI driver 71 72For 2.4.x and early 2.6.x kernels you need to choose a module based on 73the type of system interface your hardware supports. For example: 74 75 ipmi_kcs_drv: Keyboard Controller Style driver 76 77More recent 2.6.x kernels have combined these into a single module: 78 79 ipmi_si: a universal IPMI system interface driver 80 81See the documentation that comes with your distribution and/or kernel 82for more information on what kernel modules are required. Once the 83required modules are loaded and the driver has found a suitable system 84interface to the BMC then you need to ensure the device node at 85/dev/ipmi0 is pointing at the correct major number. 86 87This is because OpenIPMI is given a dynamically assigned major number 88when it is loaded, but depending on what other modules are present 89this number may be anywhere from 254 on down. The easiest way to tell 90is to check the output of /proc/devices and see what major number the 91"ipmidev" device is assigned to. 92 93There is a sample script included with ipmitool called ipmi.init that 94can be used to automate this process at bootup. 95 96 97LAN Interface 98------------- 99This is often referred to as "IPMI-over-LAN" and defines how IPMI messages 100can be sent to and from the BMC encapsulated in Remote Management Control 101Protocol (RMCP) packets which are then transferred as UDP datagrams. 102 103IPMI-over-LAN is only supported with version 1.5 and higher of the IPMI 104specification. The RMCP packet format is defined by the Alert Standard 105Forum, and it has been followed up with the RMCP+ protocol that adds 106encryption and payload support. The IPMIv2 specification was updated 107accordingly to to support the RMCP+ protocol and brings with it enhanced 108security with encryption as well as support for Serial over LAN. 109 110There are different types of LAN interfaces as well. Some systems have 111shared management networks where the NIC will intercept UDP packets to 112port 623 and redirect them to the BMC over SMBUS. This type of LAN 113interface requires that the BMC be configured with the same settings that 114the system uses. It also suffers from an increased security risk just by 115the nature of sharing that interface with normal traffic. 116 117I have also seen bugs in some implementations that have rendered the 118IPMI-over-LAN feature "dangerous" to enable in some situations. (in 119particular there can be an issue with RPC because it will sometimes choose 120to use port 623 and you will lose response packets...) 121 122There is a sample shell script included with ipmitool called bmclanconf 123that can be used to simplify the LAN settings configuration process using 124the System Interface to configure the settings. In some cases the 125hardware will come with a utility (often a DOS bootable CD) for configuring 126enabling the LAN interface as well. 127 128In order to support the IPMIv2.0 interface you must have an OpenSSL library 129with the required encrytion functions. Recent distributions should have 130no problems. The IPMIv1.5 interface will attempt to use OpenSSL for MD5 131hash function at compile time but if that is not found it will use an 132internal library. 133 134IPMB Dual Bridging in IPMITOOL 135------------------------------- 136 137IPMI offers a standard messaging interface. 138 139The following concepts are related to this messaging interface: 140 141Channel type : Communication channel type (SMS/KCS, IPMB, LAN) 142Channel number : Channel descriptor 143Requester : Address of the requester 144Responder : Address of the responder 145NetFN : The logical function for the request/response. 146Command : The command number 147Sequence : An ID identifiying the request/response pair 148Message tracking : The ability to match request/response pair. 149 150When a communication is issued through any of the channels, an application 151formats a request and expect a response. 152 153Direct Command 154-------------- 155The simplest form of communication is a "direct command" using SMS/KCS 156 157Example: 158 ipmitool raw 6 4 159 55 00 160 161This send raw command 4 (selftest) from netfn 6(application) to KCS, the driver 162takes care of 'message tracking' and provides the answer. 163 164Hopefully, the application also includes a "human readable" instance of the API: 165 ipmitool mc selftest 166 Selftest: passed 167 168Bridged Command 169--------------- 170One slightly more complicated communication mode is the so-called 171"bridged command" using IPMB. 172 173Example: 174 ipmitool -m 0x94 -t 0x9a raw 6 4 175 55 00 176 177 or 178 179 ipmitool -m 0x94 -t 0x9a mc selftest 180 Selftest: passed 181 182 183This still sends the same command 4 (selftest) from netfn 6(application) to 184the target. However, to do so, the command is encapsulated (by the driver) and 185sent using the command 0x34 (send message) from netfn 6(application) to KCS. 186Then KCS is polled by the driver until a message has been received, then the 187driver uses command 0x33 (get message). The driver also tracks the message 188and makes sure the response matches the request. Then it decapsultates the 189message and gives the response back to the application. 190 191Dual Bridged Command 192-------------------- 193Things get a little more ugly when the application needs to reach a management 194controller sitting on an interface (or channel) not directly connected to the 195BMC/IPMC. In the case the application must encapsulate its message itself and 196request the IPMC to deal with message tracking itself. 197 198Its been working well with IPMITOOL on the LAN interface with: 199 ipmitool -H <ip> -U <user> -P <password> -B 0 -T 0x8a -m 0x20 -t 0x7a -b 7 200 mc selftest 201 202However, trying to dual bridge commands locally with : 203 ipmitool -B 0 -T 0x9a -m 0x94 -t 0x7a -b 7 mc selftest didn't work 204 (it returned the same data as ipmitool -m 0x20 -t 0x7a -b 7 mc selftest ) 205 206The reason was that the "openipmi" interface pluging didn't 207encapsulate/decapsulate the message and didn't even detect the intent 208to double bridge the request. 209 210 ./src/ipmitool -B 0 -T 0x8a -m 0x94 -t 0x7a -b 7 mc selftest 211 212-B 0 : transit channel for first bridge level (channel 0: IPMB-0) 213-T 0x8a : transit destination address (remote IPMC address) 214-m 0x94 : source address (local IPMC address on IPMB-0) 215-t 0x7a : remote target (AMC IPMB-L address) 216-b 7 : remote channel (channel 7: IPMB-L) 217 218The transit source address (remote IPMC address on remote channel) is 219automatically assigned by the remote IPMC. 220 221Payload Size Limit 222------------------ 223Because some commands return a lot of data (fru read/get sdr) and because 2 224levels of encapsulation are used, some command will fail. 225 226For instance this works. 227 228ipmitool -H <ip> -U <user> -P <password> -B 0 -T 0x8a -m 0x94 -t 0x7a -b 7 229 mc selftest 230 231but this does not: 232 233ipmitool -H <ip> -U <user> -P <password> -B 0 -T 0x8a -m 0x94 -t 0x7a -b 7 234 fru print. 235 236 237 238Usage 239===== 240All invocations of ipmitool require specifying an interface to use, unless 241you want to use the default interface as set at compile time. Each call 242must also specify a command to run. You can see the list of supported 243interfaces and which is default as well as a list of top level commands in 244the usage output available with the -h option: 245 246usage: ipmitool [options...] <command> 247 248 -h This help 249 -V Show version information 250 -v Verbose (can use multiple times) 251 -c Display output in comma separated format 252 -I intf Interface to use 253 -H hostname Remote host name for LAN interface 254 -p port Remote RMCP port [default=623] 255 -L level Remote session privilege level [default=USER] 256 -A authtype Force use of authtype NONE, PASSWORD, MD2 or MD5 257 -U username Remote session username 258 -P password Remote session password 259 -f file Read remote session password from file 260 -a Prompt for remote password 261 -E Read password from IPMI_PASSWORD environment variable 262 -m address Set local IPMB address 263 -t address Bridge request to remote target address 264 265Interfaces: 266 open Linux OpenIPMI Interface [default] 267 imb Intel IMB Interface 268 lan IPMI v1.5 LAN Interface 269 lanplus IPMI v2.0 RMCP+ LAN Interface 270 271Commands: 272 raw Send a RAW IPMI request and print response 273 lan Configure LAN Channels 274 chassis Get chassis status and set power state 275 event Send pre-defined events to BMC 276 bmc Print BMC status and configure global enables 277 sdr Print Sensor Data Repository entries and readings 278 sensor Print detailed sensor information 279 fru Print built-in FRU and scan SDR for FRU locators 280 sel Print System Evelnt Log 281 sol Configure IPMIv2.0 Serial-over-LAN 282 user Configure BMC users 283 channel Configure BMC channels 284 session Print session information 285 shell Launch interactive IPMI shell 286 exec Run list of commands from file 287 set Set runtime variable for shell and exec 288 289 290Commands 291======== 292More help on the supported commands can be found by running them with the 293help argument, for example "chassis help". There are a few commands with 294special meaning: 295 296> shell: This command will launch an shell interface to the ipmitool 297 command set. You can use this for interactively entering commands to 298 monitor system status. An example session: 299 300# ipmitool -I open shell 301ipmitool> chassis status 302System Power : off 303Power Overload : false 304Power Interlock : inactive 305Main Power Fault : false 306Power Control Fault : false 307Power Restore Policy : always-off 308Last Power Event : command 309Chassis Intrusion : active 310Front-Panel Lockout : inactive 311Drive Fault : false 312Cooling/Fan Fault : false 313ipmitool> user list 7 314ID Name Callin Link Auth IPMI Msg Channel Priv Limit 3151 true false true ADMINISTRATOR 316ipmitool> exit 317 318> exec: This command will read a text file and execute ipmitool commands 319 in sequence. It can be used for scriptable commands: 320 321# cat lansetup.scr 322lan set 7 ipsrc static 323lan set 7 ipaddr 10.1.1.10 324lan set 7 netmask 255.255.255.0 325lan set 7 defgw ipaddr 10.1.1.254 326# ipmitool -I open exec lansetup.scr 327Setting LAN IP Address to 10.1.1.10 328Setting Lan Subnet Mask to 255.255.255.0 329Setting Lan Default Gateway IP to 10.1.1.254 330 331> set: This command can be used by the shell and exec modes to configure 332 various session parameters: 333 334 hostname <host> Session hostname 335 username <user> Session username 336 password <pass> Session password 337 privlvl <level> Session privilege level force 338 authtype <type> Authentication type force 339 localaddr <addr> Local IPMB address 340 targetaddr <addr> Remote target IPMB address 341 port <port> Remote RMCP port 342 csv [level] enable output in comma separated format 343 verbose [level] Verbose level 344 345# cat getstatus.scr 346set hostname sf-v20z-1 347set password admin 348chassis status 349# ipmitool -I lan exec getstatus.scr 350Set session hostname to lx50 351Set session password 352System Power : off 353Power Overload : false 354Power Interlock : inactive 355Main Power Fault : false 356Power Control Fault : false 357Power Restore Policy : always-off 358Last Power Event : command 359Chassis Intrusion : active 360Front-Panel Lockout : inactive 361Drive Fault : false 362Cooling/Fan Fault : false 363 364 365ipmievd 366======= 367Included with ipmitool is another utility called ipmievd that is a daemon 368which will listen for events from the BMC that are being sent to the SEL 369and also log those messages to syslog. By default when run (as root) with 370no arguments it will daemonize and poll on the OpenIPMI device waiting for 371an event notification. Upon receipt of an event it will log it to syslog 372with the LOG_LOCAL4 facility. You can test ipmievd by sending test events 373over the LAN interface with ipmitool: 374 375remote# ipmievd 376 377local$ ipmitool -I lan -H lx50 -P admin event help 378usage: event <num> 379 1 : Temperature - Upper Critical - Going High 380 2 : Voltage Threshold - Lower Critical - Going Low 381 3 : Memory - Correctable ECC 382local$ ipmitool -I lan -H lx50 -P admin event 1 383Sending Temperature - Upper Critical - Going High event to BMC 384local$ ipmitool -I lan -H lx50 -P admin event 2 385Sending Voltage Threshold - Lower Critical - Going Low event to BMC 386local$ ipmitool -I lan -H lx50 -P admin event 3 387Sending Memory - Correctable ECC event to BMC 388 389remote# tail /var/log/messages (timestamps removed) 390ipmievd: Waiting for events... 391ipmievd: Temperature Sensor 30 - Upper Critical - going high 392ipmievd: Voltage Sensor 60 - Lower Critical - going low 393ipmievd: Memory Sensor 01 - Correctable ECC 394 395 396Resources 397========= 398IPMItool homepage 399http://ipmitool.sourceforge.net 400 401IPMItool manpage 402http://ipmitool.sourceforge.net/manpage.html 403 404IPMItool overview paper from Linux.conf.au 2004 405http://ipmitool.sourceforge.net/lca2004_ipmitool.pdf 406 407Intelligent Platform Management Interface specification 408http://www.intel.com/design/servers/ipmi/spec.htm 409 410OpenIPMI project: Linux IPMI kernel driver and userland library 411http://openipmi.sourceforge.net 412 413IPMItool commit archive 414https://lists.sourceforge.net/lists/listinfo/ipmitool-cvs 415