acpid.8

   1 .TH acpid 8 ""
   2 .\" Portions Copyright (c) 2001 Sun Microsystems
   3 .\" Portions Copyright (c) Tim Hockin (thockin@hockin.org)
   4 .SH NAME
   5 acpid \- Advanced Configuration and Power Interface event daemon
   6 .SH SYNOPSIS
   7 \fBacpid\fP [\fIoptions\fP]
   8
   9 .SH DESCRIPTION
  10 \fBacpid\fP is designed to notify user-space programs of ACPI events.
  11 \fBacpid\fP should be started during the system boot, and will run as a
  12 background process, by default.  It will open an events file
  13 (\fI/proc/acpi/event\fP by default) and attempt to read whole lines which
  14 represent ACPI events.  If the events file does not exist, \fBacpid\fP will
  15 attempt to connect to the Linux kernel via the input layer and netlink.  When an
  16 ACPI event is received from one of these sources, \fBacpid\fP will examine a
  17 list of rules, and execute the rules that match the event. \fBacpid\fP will
  18 ignore all incoming ACPI events if a lock file exists (\fI/var/lock/acpid\fP by
  19 default).
  20 .PP
  21 \fIRules\fP are defined by simple configuration files.  \fBacpid\fP
  22 will look in a configuration directory (\fI/etc/acpi/events\fP by default),
  23 and parse all regular files with names that consist entirely of upper and
  24 lower case letters, digits, underscores, and hyphens (similar to
  25 run-parts(8)).
  26 .\" that do not begin with a period ('.') or end with a tilde (~).
  27 Each file must define two things: an \fIevent\fP and an
  28 \fIaction\fP.  Any blank lines, or lines where the first character is a
  29 hash ('#') are ignored.  Extraneous lines are flagged as warnings, but
  30 are not fatal.  Each line has three tokens: the key, a literal equal sign,
  31 and the value.  The key can be up to 63 characters, and is case-insensitive
  32 (but whitespace matters).  The value can be up to 511 characters, and is
  33 case and whitespace sensitive.
  34 .PP
  35 The event value is a regular expression (see regcomp(3)), against which events are matched.
  36 .PP
  37 The action value is a commandline, which will be invoked via \fI/bin/sh\fP
  38 whenever an event matching the rule in question occurs.  The commandline may
  39 include shell-special characters, and they will be preserved.  The only special
  40 characters in an action value are "%" escaped.  The string "%e" will be
  41 replaced by the literal text of the event for which the action was invoked.
  42 This string may contain spaces, so the commandline must take care to quote the "%e" if it wants a single token.  The string "%%" will be replaced by a
  43 literal "%".  All other "%" escapes are reserved, and will cause a rule to
  44 not load.
  45 .PP
  46 This feature allows multiple rules to be defined for the same event (though no
  47 ordering is guaranteed), as well as one rule to be defined for multiple events.
  48 To force \fBacpid\fP to reload the rule configuration, send it a SIGHUP.
  49 .PP
  50 The pseudo-action \fI<drop>\fP causes the event to be dropped
  51 completely and no further processing undertaken; clients connecting
  52 via the UNIX domain socket (see below) will not be notified of the
  53 event. This may be useful on some machines, such as certain laptops which
  54 generate spurious battery events at frequent intervals. The name of
  55 this pseudo-action may be redefined with a commandline option.
  56 .PP
  57 In addition to rule files, \fBacpid\fP also accepts connections on a UNIX
  58 domain socket (\fI/var/run/acpid.socket\fP by default).  Any application may
  59 connect to this socket.  Once connected, \fBacpid\fP will send the text of
  60 all ACPI events to the client.  The client has the responsibility of filtering
  61 for messages about which it cares.  \fBacpid\fP will not close the client
  62 socket except in the case of a SIGHUP or \fBacpid\fP exiting.
  63 .PP
  64 For faster startup, this socket can be passed in as stdin so that \fBacpid\fP
  65 need not create the socket.  In addition, if a socket is passed in as stdin,
  66 \fBacpid\fP will not daemonize.  It will be run in foreground.  This behavior
  67 is provided to support systemd(1).
  68 .PP
  69 .B acpid
  70 will log all of its activities, as well as the stdout and stderr of any
  71 actions, to syslog.
  72 .PP
  73 All the default files and directories can be changed with commandline options.
  74 .PP
  75 When troubleshooting \fBacpid\fP, it is important to be aware that other parts
  76 of a system might be handling ACPI events.
  77 \fBsystemd\fP(1) is capable of handling the power switch and various other
  78 events that are commonly handled by \fBacpid\fP.  See the description of
  79 HandlePowerKey in \fBlogind.conf\fP(5) for more.  Some window managers also
  80 take over \fBacpid\fP's normal handling of the power button and other events.
  81 .SH OPTIONS
  82 .TP 12
  83 .BI \-c "\fR, \fP" \-\-confdir " directory"
  84 This option changes the directory in which \fBacpid\fP looks for rule
  85 configuration files.  Default is \fI/etc/acpi/events\fP.
  86 .TP 12
  87 .BI \-C "\fR, \fP" \-\-clientmax " number"
  88 This option changes the maximum number of non-root socket connections which
  89 can be made to the \fBacpid\fP socket.  Default is \fI256\fP.
  90 .TP 12
  91 .BI \-d "\fR, \fP" \-\-debug
  92 This option increases the \fBacpid\fP debug level by one.  If the debug level
  93 is non-zero, \fBacpid\fP will run in the foreground, and will log to
  94 stderr, in addition to the regular syslog.
  95 .TP
  96 .BI \-e "\fR, \fP" \-\-eventfile " filename"
  97 This option changes the event file from which \fBacpid\fP reads events.
  98 Default is \fI/proc/acpi/event\fP.
  99 .TP
 100 .BI \-n "\fR, \fP" \-\-netlink
 101 This option forces \fBacpid\fP to use the Linux kernel input layer and netlink interface for ACPI events.
 102 .TP
 103 .BI \-f "\fR, \fP" \-\-foreground
 104 This option keeps \fBacpid\fP in the foreground by not forking at startup.
 105 .TP
 106 .BI \-l "\fR, \fP" \-\-logevents
 107 This option tells \fBacpid\fP to log information about all events and actions.
 108 .TP
 109 .BI \-L "\fR, \fP" \-\-lockfile " filename"
 110 This option changes the lock file used to stop event processing.
 111 Default is \fI/var/lock/acpid\fP.
 112 .TP
 113 .BI \-g "\fR, \fP" \-\-socketgroup " groupname"
 114 This option changes the group ownership of the UNIX domain socket to which
 115 \fBacpid\fP publishes events.
 116 .TP
 117 .BI \-m "\fR, \fP" \-\-socketmode " mode"
 118 This option changes the permissions of the UNIX domain socket to which
 119 \fBacpid\fP publishes events.  Default is \fI0666\fP.
 120 .TP
 121 .BI \-s "\fR, \fP" \-\-socketfile " filename"
 122 This option changes the name of the UNIX domain socket which \fBacpid\fP opens.
 123 Default is \fI/var/run/acpid.socket\fP.
 124 .TP
 125 .BI \-S "\fR, \fP" \-\-nosocket " filename"
 126 This option tells \fBacpid\fP not to open a UNIX domain socket.  This
 127 overrides the \fI-s\fP option, and negates all other socket options.
 128 .TP
 129 .BI \-p "\fR, \fP" \-\-pidfile " filename"
 130 This option tells \fBacpid\fP to use the specified file as its pidfile.  If
 131 the file exists, it will be removed and over-written.
 132 Default is \fI/var/run/acpid.pid\fP.
 133 .TP
 134 .BI \-r "\fR, \fP" \-\-dropaction " action"
 135 This option defines the pseudo-action which tells \fBacpid\fP to abort
 136 all processing of an event, including client notifications.
 137 Default is \fI<drop>\fP.
 138 .TP
 139 .BI \-t "\fR, \fP" \-\-tpmutefix
 140 This option enables special handling of the mute button for certain
 141 ThinkPad models with mute LEDs that get out of sync with the mute state
 142 when the mute button is held down.  With this option, the mute button
 143 will generate the following events in sync with the number of presses
 144 (and, by extension, the state of the LED):
 145 .IP
 146 .br
 147 button/mute MUTE (key pressed) K
 148 .br
 149 button/mute MUTE (key released) K
 150 .TP
 151 .BI \-v "\fR, \fP" \-\-version
 152 Print version information and exit.
 153 .TP
 154 .BI \-h "\fR, \fP" \-\-help
 155 Show help and exit.
 156 .SH EXAMPLE
 157 This example will shut down your system if you press the power button.
 158 .PP
 159 Create a file named /etc/acpi/events/power that contains the following:
 160 .IP
 161 .br
 162 event=button/power
 163 .br
 164 action=/etc/acpi/power.sh "%e"
 165 .PP
 166 Then create a file named /etc/acpi/power.sh that contains the following:
 167 .IP
 168 /sbin/shutdown \-h now "Power button pressed"
 169 .PP
 170 Now, when \fBacpid\fP is running, a press of the power button will cause the
 171 rule in /etc/acpi/events/power to trigger the script in /etc/acpi/power.sh.
 172 The script will then shut down the system.
 173 .SH DEPENDENCIES
 174 \fBacpid\fP should work on any linux kernel released since 2003.
 175 .SH FILES
 176 .PD 0
 177 .B /proc/acpi/event
 178 .br
 179 .B /dev/input/event*
 180 .br
 181 .B /etc/acpi/
 182 .br
 183 .B /var/run/acpid.socket
 184 .br
 185 .B /var/run/acpid.pid
 186 .br
 187 .B /var/lock/acpid
 188 .br
 189 .PD
 190 .SH BUGS
 191 There are no known bugs.  To file bug reports, see \fBPROJECT WEBSITE\fP
 192 below.
 193 .SH SEE ALSO
 194 regcomp(3), sh(1), socket(2), connect(2), init(1), systemd(1),
 195 acpi_listen(8), kacpimon(8)
 196 .SH PROJECT WEBSITE
 197 http://sourceforge.net/projects/acpid2/
 198 .SH AUTHORS
 199 Ted Felix (ted -at- tedfelix -dot- com)
 200 .br
 201 Tim Hockin <thockin@hockin.org>
 202 .br
 203 Andrew Henroid
 204