mced.8

.TH mced 8 ""
.\" Copyright (c) 2007 Tim Hockin (thockin@google.com)
.SH NAME
mced \- Machine Check Event daemon
.SH SYNOPSIS
\fBmced\fP [\fIoptions\fP]

.SH DESCRIPTION
\fBmced\fP is designed to notify user-space programs of Machine Check events.
\fBmced\fP should be started during the system boot, and will run as a
background process by default.  It will open the kernel MCE log device
(\fI/dev/mcelog\fP by default) and wait for events.  When an event is
received \fBmced\fP will execute its list of handler rules.
.PP
\fIRules\fP are defined by simple configuration files.  \fBmced\fP
will look in a configuration directory (\fI/etc/mced/\fP by default),
and parse all files that do not begin with a period ('.') or end with a
tilde ('~').  Any blank lines, or lines where the first character is a
hash ('#') are ignored.  Extraneous lines are flagged as warnings,
but are not fatal.  Each line has three tokens: the key, a literal equal
sign, and the value.  Each token may be surrounded by whitespace which
will be ignored.  The key is a series of alpha-numeric characters or a
underscores and is case-insensitive.  The value begins at the first
non-whitespace character after the equal sign.  Examples:
.br
	foo=bar         => key = "foo", value = "bar"
.br
	foo = bar       => key = "foo", value = "bar"
.br
	 foo = bar      => key = "foo", value = "bar"
.br
	foo = "bar"     => key = "foo", value = "\\"bar\\""
.PP
The only supported configuration key at this time is \fIaction\fP.  Each
config file must define exactly one \fIaction\fP.
.PP
The action value is a commandline, which will be invoked via \fI/bin/sh\fP
whenever an event occurs.  The commandline may
include shell-special characters, and they will be preserved.  The only special
characters in an action value are "%" escaped.  The following escapes will
be processed:
.br
	%c	- CPU number (unsigned)
.br
	%S	- CPU socket number (signed)
.br
	%v	- CPU vendor (signed)
.br
	%A	- CPUID level 1, EAX (unsigned)
.br
	%p	- CPU initial APIC ID (unsigned)
.br
	%b	- MCE bank (unsigned)
.br
	%s	- MCi status (unsigned)
.br
	%a	- MCi address (unsigned)
.br
	%m	- MCi misc (unsigned)
.br
	%g	- MCG status (unsigned)
.br
	%G	- MCG capabilities (unsigned)
.br
	%t	- timestamp (usecs since epoch, unsigned)
.br
	%T	- CPU timestamp counter (unsigned)
.br
	%C	- CPU code segment register (unsigned)
.br
	%I	- CPU instruction pointer (unsigned)
.br
	%B	- boot number (signed)
.PP
The "%t" expansion reflects the best-available timestamp.  Older kernels
(pre 2.6.31) do not provide a wall-time timestamp, so \fBmced\fP uses the
time, from gettimeofday(2), at which the MCE was delivered to it.  Kernel
2.6.31 added a time_t field to its MCE structure, which is limited to
seconds resolution.  If the kernel's time field is 0, \fBmced\fP will fall
back on gettimeofday(2).
.PP
The "%v" expansion is only supported on kernel 2.6.31 and higher.  It is
an enumerated value, taken from the Linux kernel.  It will read as -1 on
older kernels.
.br
	-1	= VENDOR_UNKNOWN
.br
	 0	= VENDOR_INTEL
.br
	 1	= VENDOR_CYRIX
.br
	 2	= VENDOR_AMD
.br
	 3	= VENDOR_UMC
.br
	 5	= VENDOR_CENTAUR
.br
	 7	= VENDOR_TRANSMETA
.br
	 8	= VENDOR_NSC
.PP
The "%A" expansion is only supported on kernel 2.6.31 and higher.  It
will read as 0 on older kernels.
.PP
The "%S" expansion is only supported on kernel 2.6.31 and higher.  It will
read as -1 on older kernels.
.PP
The "%p" expansion is only supported on kernel 2.6.31 and higher.  It will
read as 0xffffffff on older kernels.
.PP
The "%G" expansion is only supported on kernel 2.6.31 and higher.  It will
read as 0 on older kernels.
.PP
The command string may contain spaces, so the commandline must take care
to use quotes if it wants a token with spaces.  The string "%%" will be
replaced by a literal "%".  All other "%" expansions are reserved.
.PP
To force \fBmced\fP to reload the rule configuration, send it a SIGHUP.
.PP
In addition to rule files, \fBmced\fP also accepts connections on a UNIX
domain socket (\fI/var/run/mced2.socket\fP by default).  Any application
may connect to this socket.  Once connected, \fBmced\fP will send the text of
all MCE events to the client.  Each event is sent on a single line,
terminated by a newline ('\\n') character.  The data is formatted as a
series of space-delimited key=value pairs, where each key is one of the "%"
expansions documented above (including the "%" character) and each value is a
number (in decimal or hex format, depending on which datum).  The order of
pairs is not significant. Example:
.br
	%c=0 %v=0 %b=4 %s=0x12345678 %a=0xabcdef %m=0x00000000 %g=0x00000000
	%t=8675309 %B=42
.PP
If the \-O (\--oldsocket) flag is specified, \fBmced\fP will retain
backwards-compatible socket behavior of \fBmced\fP version 1.x.  In
addition to the normal version 2.x socket, \fBmced\fP will open a second
socket and report MCEs in the legacy data format.  This interface is
considered deprecated but is retained for ease of migration.
.PP
\fBmced\fP will not close the client socket except in the case of a SIGHUP
or \fBmced\fP exiting.
.PP
If compiled with the ENABLE_DBUS flag, \fBmced\fP will also broadcast MCE
events over D-Bus. Clients that wish to receive MCEs over DBUS should
connect to the \fIorg.mcedaemon.MachineCheckDaemon\fP service, the
\fI/org/mcedaemon/MachineCheckNotifier\fP object path and the
\fIorg.mcedaemon.MachineCheckNotifier\fP interface.  Events are delivered
via the \fImachine_check\fP signal with a data payload of type
\fIa{sv}\fP.  The data payload is a hash of strings to variants which
contains the same information as the normal UNIX socket, described above.
The \--no-dbus flag will disable D-Bus completely.  By default \fBmced\fP
will send its signals on the DBUS_BUS_SYSTEM bus, but the
\--dbus-session-bus flag will force it to use the DBUS_BUS_SESSION bus
instead.
.PP
\fBmced\fP will log all of its activities, as well as the stdout and
stderr of any actions (depending on the \-l flag) to syslog.
.PP
All of the default file and directories can be changed with commandline options.
.SH OPTIONS
.TP 12
.BI \-b "\fR, \fP" \--bootnum " number"
This option sets the bootnumber which \fBmced\fP uses when logging events,
and which can be passed to handlers.  Default is -1.
.TP 12
.BI \-c "\fR, \fP" \--confdir " directory"
This option changes the directory in which \fBmced\fP looks for rule
configuration files.  When running as a daemon, \fBmced\fP will change
directories to the root of the filesystem, which means this argument
must be an absolute path (/path/to/conf/dir), rather than a relative path
(conf/dir or ./conf/dir).  Default is \fI/etc/mced\fP.
.TP 12
.BI \-C "\fR, \fP" \--clientmax " number"
This option changes the maximum number of non-root socket connections
which can be made to the \fBmced\fP socket.  Setting this to 0 or less
will result in non-root clients being denied access completely. Default is
\fI128\fP.
.TP 12
.BI \-d "\fR, \fP" \--debug
This option increases the \fBmced\fP debug level by one.  If the debug level
is non-zero, \fBmced\fP will run in the foreground, will log information
about each event, and will log to stderr, in addition to the regular log.
.TP
.BI \-D "\fR, \fP" \--device " filename"
This option changes the device file from which \fBmced\fP reads events.
Default is \fI/dev/mcelog\fP.
.TP
.BI \-f "\fR, \fP" \--foreground
This option keeps \fBmced\fP in the foreground by not forking at startup.
.TP
.TP
.BI \-g "\fR, \fP" \--socketgroup " groupname"
This option changes the group ownership of the UNIX domain socket to which
\fBmced\fP publishes events.
.TP
.BI \-l "\fR, \fP" \--logevents
This option tells \fBmced\fP to log information about all events and
actions.  Default is \fIoff\fP.
.TP
.BI \-m "\fR, \fP" \--socketmode " mode"
This option changes the permissions of the UNIX domain socket to which
\fBmced\fP publishes events.  Default is \fI0600\fP.
.TP
.BI \-n "\fR, \fP" \--mininterval " millisecs"
This option sets the minimum polling interval.  See \-x (\--maxinterval)
for a description of the polling algorithm.  Default is \fI100\fP
milliseconds (0.1 seconds).
.TP
.BI \-o "\fR, \fP" \--oflowsuppress " secs"
This option sets the minimum time between overflow log messages.  These
messages mean that there are more MCEs happening than the system can
handle.  This option does not change the polling rate or handling behavior
of \fBmced\fP, just the logging behavior. Setting this to 0 or less will
disable rate limiting for these messages.  Using \-l (\--logevents) will
override this option. (Default is \fI10\fP seconds.
.TP
.BI \-O "\fR, \fP" \--oldsocket " filename"
This option forces \fBmced\fP to open a second socket using the
legacy-style data format ("%c %b %s %a %m %g %t %B\\n").  Use this if you
have socket clients that require the \fBmced\fP version 1.x behavior.  Use
of this option is discouraged, as new MCE fields are only available with
the modern socket data format.  Passing and empty string argument ("")
will make \fBmced\fP use the default v1.x socket path
(\fI/var/run/mced.socket\fP).
.TP
.BI \-p "\fR, \fP" \--pidfile " filename"
This option changes the name of the pidfile to which \fBmced\fP writes.
If the file exists, it will be removed and over-written.
Default is \fI/var/run/mced.pid\fP.
.TP
.BI \-r "\fR, \fP" \--ratelimit " mces_per_second"
This option sets an upper limit on the number of MCEs that will be
processed per second.  If this option is used, a small delay will be
injected after each MCE event is handled.  NOTE: Simply turning this
option on at all, even with a very high limit, can have a detrimental
effect on the number of MCEs that can be handled in a given time period,
mostly due to inherent jitter with very small sleeps.  \fBmced\fP tries to
adjust based on real timings of the system, but there is only so much
accuracy to be had.  Setting this to 0 or less will disable rate limiting.
Default is no rate limit.
.TP
.BI \-R "\fR, \fP" \--retrydev
This option tells \fBmced\fP to retry in the event of /dev/mcelog failing
to open. \fBmced\fP will retry the device at every polling interval.  See
\-x (\--maxinterval) for a description of the polling algorithm.
.TP
.BI \-s "\fR, \fP" \--socketfile " filename"
This option changes the name of the UNIX domain socket which \fBmced\fP opens.
Default is \fI/var/run/mced2.socket\fP.  See also \-O (\--oldsocket).
.TP
.BI \-S "\fR, \fP" \--nosocket " filename"
This option tells \fBmced\fP not to open a UNIX domain socket.  This
overrides the \fI-s\fP option, and negates all other socket options.
.TP
.BI \-x "\fR, \fP" \--maxinterval " millisecs"
This option sets the maximum polling interval. Some kernels do not yet
support poll() on /dev/mcelog, so \fBmced\fP will wake up
every polling interval and check for MCEs.  Default is \fI5000\fP
milliseconds (5 seconds).  Whenever an MCE is found, the polling interval
will be reduced, with a lower bound of the \-n (\--mininterval) option.
Whenever an MCE is not found (and the polling interval has expired), the
polling interval will be increased, with an upper bound of the \-x
(\--maxinterval) option.  To disable polling completely, set this option
to 0.
.TP
.BI \--no-dbus
Disable the sending of MCEs over D-Bus.  When compiled with ENABLE_DBUS,
\fBmced\fP will send D-Bus signals by default, unless this flag is
specified.
.TP
.BI \--dbus-session-bus
Send D-Bus signals on the session bus, rather than the system bus.
Default is the system bus.
.TP
.BI \-v "\fR, \fP" \--version
Print version information and exit.
.TP
.BI \-h "\fR, \fP" \--help
Show help and exit.
.SH FILES
.PD 0
.B /dev/mcelog
.br
.B /etc/mced/
.br
.B /var/run/mced2.socket
.br
.B /var/run/mced.socket
.br
.B /var/run/mced.pid
.br
.PD
.SH BUGS
There are no known bugs.  To file bug reports, see \fBAUTHORS\fP below.
.SH SEE ALSO
sh(1), socket(2), connect(2), gettimeofday(2)
.SH AUTHORS
Tim Hockin <thockin@hockin.org>