source: general/sysutils/acpid.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY acpid-download-http "&sourceforge-dl;/acpid2/acpid-&acpid-version;.tar.xz">
  <!ENTITY acpid-download-ftp  " ">
  <!ENTITY acpid-md5sum        "988c2e3fd5ba0ea4492d3ba7273af295">
  <!ENTITY acpid-size          "160 KB">
  <!ENTITY acpid-buildsize     "1.9 MB">
  <!ENTITY acpid-time          "less than 0.1 SBU">
]>

<sect1 id="acpid" xreflabel="acpid-&acpid-version;">
  <?dbhtml filename="acpid.html"?>


  <title>acpid-&acpid-version;</title>

  <indexterm zone="acpid">
    <primary sortas="a-acpid">acpid</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to acpid</title>

    <para>
      The <application>acpid</application> (Advanced Configuration and Power
      Interface event daemon) is a completely flexible, totally extensible
      daemon for delivering ACPI events. It listens on netlink interface and
      when an event occurs, executes programs to handle the event. The programs
      it executes are configured through a set of configuration files, which can
      be dropped into place by packages or by the user.
    </para>

    <note>
      <para>
        Some other packages may handle some ACPI events as well and they
        may conflict with this package.  For example, &logind;
        (read the documentation for <option>Handle*=</option> in
        <ulink role='man' url='&man;logind.conf.5'>logind.conf(5)</ulink>
        for details) and
        <xref linkend='upower'/> (used by many desktop environments such as
        GNOME, KDE, and XFCE for handling ACPI events).  If you've installed
        such a package and it's enough for your use case, this package is
        probably not needed.  If you really need this package, you must be
        careful configuring it and the other packages handling ACPI events
        to avoid conflicts.  Notably, &logind; handles some ACPI events
        by default, so the handling of these events by &logind; should be
        disabled first if handling these events with acpid
        (again, read <ulink role='man'
        url='&man;logind.conf.5'>logind.conf(5)</ulink> for details).
      </para>
    </note>

    &lfs121_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&acpid-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&acpid-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &acpid-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &acpid-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &acpid-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &acpid-time;
        </para>
      </listitem>
    </itemizedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of acpid</title>

    <para>
      Install <application>acpid</application> by
      running the following commands:
    </para>

<screen><userinput>./configure --prefix=/usr \
            --docdir=/usr/share/doc/acpid-&acpid-version; &amp;&amp;
make</userinput></screen>

    <para>
      This package does not come with a test suite.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install                         &amp;&amp;
install -v -m755 -d /etc/acpi/events &amp;&amp;
cp -r samples /usr/share/doc/acpid-&acpid-version;</userinput></screen>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring acpid</title>

    <para>
      <application>acpid</application> is configured by user defined events.
      Place event files under
      <filename class="directory">/etc/acpi/events</filename> directory. If an
      event occurs, <command>acpid</command> recurses through the event files in
      order to see if the regex defined after "event" matches. If they do,
      action is executed.
    </para>

    <para>
      The following brief example will suspend the system when the laptop
      lid is closed<phrase revision='sysv'> (it requires
      <xref linkend="pm-utils"/>)</phrase>.  The example also disables
      the default handling of the lid close event by &logind; when the
      system is on battery and not connected to any external monitor,
      in order to avoid a conflict:
    </para>

<screen revision='sysv' role="nodump"><userinput>cat &gt; /etc/acpi/events/lid &lt;&lt; "EOF"
<literal>event=button/lid
action=/etc/acpi/lid.sh</literal>
EOF

cat &gt; /etc/acpi/lid.sh &lt;&lt; "EOF"
<literal>#!/bin/sh
/bin/grep -q open /proc/acpi/button/lid/LID/state &amp;&amp; exit 0
/usr/sbin/pm-suspend</literal>
EOF
chmod +x /etc/acpi/lid.sh

mkdir -pv /etc/elogind/logind.conf.d
echo <literal>HandleLidSwitch=ignore</literal> &gt; /etc/elogind/logind.conf.d/acpi.conf</userinput></screen>

<screen revision='systemd' role="nodump"><userinput>cat &gt; /etc/acpi/events/lid &lt;&lt; "EOF"
<literal>event=button/lid
action=/etc/acpi/lid.sh</literal>
EOF

cat &gt; /etc/acpi/lid.sh &lt;&lt; "EOF"
<literal>#!/bin/sh
/bin/grep -q open /proc/acpi/button/lid/LID/state &amp;&amp; exit 0
/usr/bin/systemctl suspend</literal>
EOF
chmod +x /etc/acpi/lid.sh

mkdir -pv /etc/systemd/logind.conf.d
echo <literal>HandleLidSwitch=ignore</literal> &gt; /etc/systemd/logind.conf.d/acpi.conf</userinput></screen>

    <para>
      Unfortunately, not every computer labels ACPI events in the same way
      (for example, the lid may be recognized as <filename>LID0</filename>
      instead of <filename>LID</filename>).
      To determine how your buttons are recognized, use the
      <command>acpi_listen</command> tool. Also, look in the <filename
      class="directory">samples</filename> directory under <filename
      class="directory">/usr/share/doc/acpid-&acpid-version;</filename>
      for more examples.
    </para>

    <sect3  id="acpid-init">
      <title><phrase revision="sysv">Boot Script</phrase>
             <phrase revision="systemd">Systemd Socket</phrase></title>

      <para revision="sysv">
        To automatically start <command>acpid</command> when the system is
        rebooted, install the <filename>/etc/rc.d/init.d/acpid</filename>
        boot script from the <xref linkend="bootscripts"/> package.
      </para>

      <para revision="systemd">
        To start the <command>acpid</command> daemon at boot,
        install the systemd unit from the <xref linkend="systemd-units"/>
        package by running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

      <indexterm zone="acpid acpid-init">
        <primary sortas="f-acpid">acpid</primary>
      </indexterm>

<screen role="root"><userinput>make install-acpid</userinput></screen>

      <note revision="systemd">
        <para>
          This package uses socket based activation and will be started when
          something needs it. No standalone unit file is provided for this
          package.
        </para>
      </note>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          acpid, acpi_listen, and kacpimon
        </seg>
        <seg>
          None
        </seg>
        <seg>
          /etc/acpi and /usr/share/doc/acpid-&acpid-version;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="acpid-prog">
        <term><command>acpid</command></term>
        <listitem>
          <para>
            is a program that listens for ACPI events and executes the rules
            that match the received event
          </para>
          <indexterm zone="acpid acpid-prog">
            <primary sortas="b-acpid">acpid</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="acpi_listen">
        <term><command>acpi_listen</command></term>
        <listitem>
          <para>
            is a simple tool which connects to <command>acpid</command> and
            listens for events
          </para>
          <indexterm zone="acpid acpi_listen">
            <primary sortas="b-acpi_listen">acpi_listen</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kacpimon">
        <term><command>kacpimon</command></term>
        <listitem>
          <para>
            is a monitor program that connects to three sources of ACPI events
            (events file, netlink and input layer) and then reports on what it
            sees while it is connected
          </para>
          <indexterm zone="acpid kacpimon">
            <primary sortas="b-kacpimon">kacpimon</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>