diff options
Diffstat (limited to 'doc/igetevent.8')
| -rw-r--r-- | doc/igetevent.8 | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/doc/igetevent.8 b/doc/igetevent.8 new file mode 100644 index 0000000..c5df169 --- /dev/null +++ b/doc/igetevent.8 @@ -0,0 +1,154 @@ +.TH IGETEVENT 8 "Version 1.2: 17 Feb 2010" +.SH NAME +ipmiutil_getevt \- wait for IPMI events +.SH SYNOPSIS +.B "ipmiutil getevt [-abosx -t secs -N node -U user -P/-R pswd -EFJTVY]" + +.SH DESCRIPTION +.I ipmiutil getevt +is a program that uses IPMI commands to +wait for IPMI events sent from the BMC firmware. These events are +also sent to the IPMI System Event Log (SEL). +This utility can use either the /dev/ipmi0 driver from OpenIPMI, +the /dev/imb driver from Intel, the /dev/ipmikcs driver from valinux, +direct user-space IOs, or the IPMI LAN interface if \-N. + +Some server management functions want to trigger custom actions or +alerts when IPMI hardware-related events occur, but do not want to +track all events, just newly occurring events. +This utility waits a specified timeout period for any events, and +returns interpreted output for each event. It is designed as a +scriptable command-line utility, but if the timeout is infinite +(\-t 0), then this code could be used for a sample service as well. + +.br +There are several methods to do this which are implemented here. +.PP +The SEL method: +.br +This method polls the SEL once a second, keeps track of the last +SEL event read, and only new events are processed. This ensures +that in a series of rapid events, all events are received in order, +however, some transition-to-OK events may not be configured to +write to the SEL on certain platforms. +This method is used if getevent \-s is specified. +This is the only method supported over IPMI LAN, i.e. with \-N. +.PP +The ReadEventMessageBuffer method: +.br +This uses an IPMI Message Buffer in the BMC firmware to read +each new event. This receives any event, but if two events +occur nearly simultaneously, only the most recent of the two +will be returned with this method. An example of simultaneous +events might be, if a fan stops/fails, both the non-critical +and critical fan threshold events would occur at that time. +This is the default method for getevent. +.PP +The OpenIPMI custom method: +.br +Different IPMI drivers may have varying behavior. For instance, +the OpenIPMI driver uses the IPMI GetMessage commands internally +and does not allow client programs to use those commands. It has +its own custom mechanism, see getevent_mv(). +This method is used if the OpenIPMI driver is detected, and +no other method is specified. +.PP +The Async Event method: +.br +This only gets certain Asynchronous requests from the BMC to an +SMS OS service, like a remote OS shutdown, and get_software_id. +This method is disabled by default and only turned on if +the getevent \-a option is specified. This method is only +supported via the Intel IMB and OpenIPMI driver interfaces. +There is an init script provided with ipmiutil to automate the +task of starting this async event daemon. +.br +# chkconfig \-\-add ipmiutil_asy (skip this if no chkconfig) +.br +# /etc/init.d/ipmiutil_asy start +.br +This listens for IPMI LAN requests for soft-shutdown, and logs +the output to /var/log/ipmiutil_asy.log + +.SH OPTIONS +Command line options are described below. + +.IP "-a" +Use the Async request method, which receives SMS OS requests +from the BMC using the IMB or OpenIPMI driver interface. This services +remote SMS bridge agent requests, like remote OS shutdown and get software_id. +.IP "-b" +Run in Background as a daemon. If this option is specified, normal output +will be redirected to /var/log/ipmiutil_getevt.log. The default is to run +in foreground. +.IP "-c" +Show output in a canonical format, with a delimiter of '|'. +.IP "-e N" +Wait for a specific event sensor type N. +The parameter can be in hex (0x23) or decimal (35). +The default is 0xFF which means wait for any event. +.IP "-r F" +Run script file F when an event occurs. The filename can include a full path. +The script will be passed the event description as a parameter. +A sample evt.sh script is included with the ipmiutil package. +.IP "-o" +Only run one pass to wait for the first event. Default is to loop for multiple events for the timeout period. +.IP "-s" +Use the SEL method to get events. This polls the SEL once a second for new +events. The last SEL record read is saved in /usr/share/ipmiutil/evt.idx. +Otherwise, the default is to use the ReadEventMessageBuffer method +to get new events. +.IP "-t N" +Set the timeout period to N seconds. Default is 120 seconds. +A timeout of 0 means an infinite period. +.IP "-x" +Causes extra debug messages to be displayed. +.IP "-N nodename" +Nodename or IP address of the remote target system. If a nodename is +specified, IPMI LAN interface is used. Otherwise the local system +management interface is used. +.IP "-P/-R rmt_pswd" +Remote password for the nodename given. The default is a null password. +.IP "-U rmt_user" +Remote username for the nodename given. The default is a null username. +.IP "-E" +Use the remote password from Environment variable IPMI_PASSWORD. +.IP "-F drv_t" +Force the driver type to one of the followng: +imb, va, open, gnu, landesk, lan, lan2, lan2i, kcs, smb. +Note that lan2i means lan2 with intelplus. +The default is to detect any available driver type and use it. +.IP "-J" +Use the specified LanPlus cipher suite (0 thru 17): 0=none/none/none, +1=sha1/none/none, 2=sha1/sha1/none, 3=sha1/sha1/cbc128, 4=sha1/sha1/xrc4_128, +5=sha1/sha1/xrc4_40, 6=md5/none/none, ... 14=md5/md5/xrc4_40. +Default is 3. +.IP "-T" +Use a specified IPMI LAN Authentication Type: 0=None, 1=MD2, 2=MD5, 4=Straight Password, 5=OEM. +.IP "-V" +Use a specified IPMI LAN privilege level. 1=Callback level, 2=User level, 3=Operator level, 4=Administrator level (default), 5=OEM level. +.IP "-Y" +Yes, do prompt the user for the IPMI LAN remote password. +Alternatives for the password are \-E or \-P. + + +.SH "SEE ALSO" +ipmiutil(8) ialarms(8) iconfig(8) icmd(8) idiscover(8) ievents(8) ifru(8) ihealth(8) ilan(8) ireset(8) isel(8) isensor(8) iserial(8) isol(8) iwdt(8) + +.SH WARNINGS +See http://ipmiutil.sourceforge.net/ for the latest version of ipmiutil and any bug fix list. + +.SH COPYRIGHT +Copyright (C) 2009 Kontron America, Inc. +.PP +See the file COPYING in the distribution for more details +regarding redistribution. +.PP +This utility is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY. + +.SH AUTHOR +.PP +Andy Cress <arcress at users.sourceforge.net> +.br + |