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