source: general/sysutils/acpid.xml@ 2314cd7

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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>

    &lfs120_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 (it requires <xref linkend="pm-utils"/>):
    </para>

    <!-- TODO: Move from pm-suspend to systemctl suspend for systemd -->
<screen role="root"><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</userinput></screen>

    <para>
      Unfortunately, not every computer labels ACPI events in the same way. 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>