Imported Upstream version 2.9.3upstream/2.9.3

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
+