source: general/sysutils/elogind.xml@ 08c3c25

<?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 elogind-download-http "https://github.com/elogind/elogind/archive/v&elogind-version;/elogind-&elogind-version;.tar.gz">
  <!ENTITY elogind-download-ftp  " ">
  <!ENTITY elogind-md5sum        "2be2c43298e2fc41c5bee33dde605f01">
  <!ENTITY elogind-size          "1.8 MB">
  <!ENTITY elogind-buildsize     "45 MB (with tests)">
  <!ENTITY elogind-time          "0.3 SBU (with parallelism=4)">
]>

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


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

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

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

    <para>
      <application>elogind</application> is the
      <application>systemd</application> project's "logind", extracted to
      be a standalone daemon.  It integrates with <xref linkend="linux-pam"/>
      to track all the users logged in to a system, and whether they
      are logged in graphically, on the console, or remotely.
      <application>Elogind</application> exposes this information via the
      standard org.freedesktop.login1 <application>D-Bus</application>
      interface, and also through the file system using systemd's standard
      <filename class="directory">/run/systemd</filename> layout.
    </para>

    &lfs113_checked;

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

    <bridgehead renderas="sect3">elogind Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref role="runtime" linkend="dbus"/> (runtime),
      <xref linkend="linux-pam"/> (required for Xorg),
      <xref role="runtime" linkend="polkit"/> (runtime),
      <xref linkend="DocBook"/>,
      <xref linkend="docbook-xsl"/>, and
      <xref linkend="libxslt"/> (all three to build the man pages)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="lxml"/>,
      <xref linkend="zsh"/>,
      <xref linkend="valgrind"/> (needed for tests),
      <ulink url="https://github.com/linux-audit/audit-userspace">
      audit-userspace</ulink>,
      <ulink url="https://github.com/scop/bash-completion">
      bash-completion</ulink>,
      <ulink url="https://mirrors.edge.kernel.org/pub/linux/utils/kernel/kexec/">
      kexec</ulink>, and
      <ulink url="https://selinuxproject.org/page/Main_Page">
      SELinux</ulink>
    </para>

  </sect2>

  <sect2 role="kernel" id="elogind-kernel">
    <title>Kernel Configuration</title>

    <para>
      Enable the following options in the kernel configuration and recompile the
      kernel if necessary:
    </para>

<!-- Spaces are significant in <screen> sections -->
<screen><literal>General setup ---&gt;
    [*]     Control Group support                        [CONFIG_CGROUPS]
File systems ---&gt;
    [*]     Inotify support for userspace                [CONFIG_INOTIFY_USER]
            Pseudo filesystems ---&gt;
                [*]    Tmpfs POSIX Access Control Lists  [CONFIG_TMPFS_POSIX_ACL]</literal></screen>

    <para>
      In addition, some tests need the userspace cryptographic kernel API, which
      is enabled with:
    </para>

<screen><literal>-*- Cryptographic API ---&gt;                                  [CONFIG_CRYPTO]
    Crypto core or helper  --->
      &lt;M/*&gt; Userspace cryptographic algorithm configuration [CONFIG_CRYPTO_USER]
    Userspace interface  --->  
      &lt;M/*&gt; Hash algorithms                                 [CONFIG_CRYPTO_USER_API_HASH]</literal></screen>

    <indexterm zone="elogind elogind-kernel">
      <primary sortas="d-elogind">elogind</primary>
    </indexterm>
  </sect2>

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

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

<screen><userinput><!--sed -i '/Disable polkit/,+8 d' meson.build &amp;&amp;

sed '/request_name/i\
r = sd_bus_set_exit_on_disconnect(m->bus, true);\
if (r &lt; 0)\
    return log_error_errno(r, "Failed to set exit on disconnect: %m");' \
    -i src/login/logind.c &amp;&amp;

-->mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..                              \
      --prefix=/usr                         \
      --buildtype=release                   \
      -Dman=auto                            \
      -Ddocdir=/usr/share/doc/elogind-&elogind-version; \
      -Dcgroup-controller=elogind           \
      -Ddbuspolicydir=/etc/dbus-1/system.d &amp;&amp;
ninja</userinput></screen>

    <para>
      To test the results, issue: <command>ninja test</command>. A few tests
      are skipped if not run with <systemitem class="username">root</systemitem>
      privileges.  Two tests named <filename>test-fs-util</filename> and
      <filename>test-id128</filename> require the
      <filename>/etc/machine-id</filename> symlink, so they will fail if
      this symlink is not created following the instruction in
      <xref linkend='dbus'/> yet.
    </para>

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

<screen role="root"><userinput>ninja install                                           &amp;&amp;
ln -sfv  libelogind.pc /usr/lib/pkgconfig/libsystemd.pc &amp;&amp;
ln -sfvn elogind /usr/include/systemd</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>
    <!--
    <para>
      <command>sed ... meson.build</command>: This change allows the
      package to be built without polkit being installed (it is still a
      runtime dependency) but able to use polkit after that package is
      installed.
    </para>

    <para>
      <command>sed ... src/login/logind.c</command>: This change allows the
      elogind daemon to exit when it is disconnected from dbus (for example
      when dbus is killed).
    </para>
    -->
    <para>
      <parameter>-Ddocdir=/usr/share/doc/elogind-&elogind-version;</parameter>:
      This is needed to install documentation in a versioned directory.
    </para>

    <para>
      <parameter>-Dcgroup-controller=elogind</parameter>: This switch is
      necessary to build this package when the kernel is not built with
      <option>CONFIG_CGROUPS</option> enabled.  Note that
      <application>elogind</application> strictly needs
      a kernel with <option>CONFIG_CGROUPS</option> enabled at runtime,
      but this switch will allow building the package first.
    </para>

    <para>
      <parameter>-Ddbuspolicydir=/etc/dbus-1/system.d</parameter>: This switch
      sets the location of the <application>D-Bus</application> policy
      directory.
    </para>

    <para>
      <parameter>-Dman=auto</parameter>: The default value of this switch is
      <emphasis>false</emphasis>. Setting it to <emphasis>auto</emphasis>
      allows building and installing the man pages if the recommended
      dependencies are installed.
    </para>

    <para>
      <option>-Dhtml=auto</option>: The default value of this switch is
      <emphasis>false</emphasis>. Setting it to <emphasis>auto</emphasis>
      allows building and installing the html documentation if the recommended
      dependencies are installed.
    </para>

    <para>
      <option>-Ddefault-kill-user-processes=false</option>: Determines whether
      the processes of a user should be killed when the user logs out. The
      default is <emphasis>true</emphasis>, but this defeats the traditional
      use of <command>screen</command> or <command>tmux</command>. This can
      also be changed in the configuration file (see below).
    </para>

    <para>
      <command>ln -s ...</command>: These commands install symlinks so that
      software packages can find the systemd-compatible library and headers.
    </para>

  </sect2>

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

    <sect3 id="elogind-config">
      <title>Config File</title>
      <para>
        <filename>/etc/elogind/logind.conf</filename>
      </para>

      <indexterm zone="elogind elogind-config">
        <primary
        sortas="e-etc-elogind-logind.conf">/etc/elogind/logind.conf</primary>
      </indexterm>
    </sect3>

    <sect3><title>Configuration Information</title>

      <para>
        The installed file <filename>/etc/elogind/logind.conf</filename>
        contains all the possible options with their defaults, commented
        out. You may wish to disable automatically killing user processes when the user logs
        out, by running, as the <systemitem class="username">root</systemitem>
        user:
      </para>

<screen role="root"><userinput>sed -e '/\[Login\]/a KillUserProcesses=no' \
    -i /etc/elogind/logind.conf</userinput></screen>

      <para>
        Each user will need to register a user session using
        <application>Linux-PAM</application> at login. The
        <filename>/etc/pam.d/system-session</filename> file needs to
        be modified and a new file must be created in order for
        <command>elogind</command> to work correctly. Run the following
        commands as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>cat &gt;&gt; /etc/pam.d/system-session &lt;&lt; "EOF" &amp;&amp;
<literal># Begin elogind addition

session  required    pam_loginuid.so
session  optional    pam_elogind.so

# End elogind addition</literal>
EOF
cat &gt; /etc/pam.d/elogind-user &lt;&lt; "EOF"
<literal># Begin /etc/pam.d/elogind-user

account  required    pam_access.so
account  include     system-account

session  required    pam_env.so
session  required    pam_limits.so
session  required    pam_unix.so
session  required    pam_loginuid.so
session  optional    pam_keyinit.so force revoke
session  optional    pam_elogind.so

auth     required    pam_deny.so
password required    pam_deny.so

# End /etc/pam.d/elogind-user</literal>
EOF</userinput></screen>

    </sect3>
  </sect2>

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

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

      <seglistitem>
        <seg>
          busctl,
          elogind-inhibit, and
          loginctl
        </seg>
        <seg>
           libelogind.so
        </seg>
        <seg>
          /usr/lib/elogind,
          /etc/elogind,
          /usr/include/elogind, and
          /usr/share/doc/elogind-&elogind-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="busctl">
        <term><command>busctl</command></term>
        <listitem>
          <para>
            is used to introspect and monitor the D-Bus bus
          </para>
          <indexterm zone="elogind busctl">
            <primary sortas="b-busctl">busctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="elogind-inhibit">
        <term><command>elogind-inhibit</command></term>
        <listitem>
          <para>
            is used to execute a program with a shutdown, sleep or idle
            inhibitor lock taken
          </para>
          <indexterm zone="elogind elogind-inhibit">
            <primary sortas="b-elogind-inhibit">elogind-inhibit</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="loginctl">
        <term><command>loginctl</command></term>
        <listitem>
          <para>
            is used to introspect and control the state of the elogind Login
            Manager
          </para>
          <indexterm zone="elogind loginctl">
            <primary sortas="b-loginctl">loginctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libelogind">
        <term><filename class="libraryfile">libelogind.so</filename></term>
        <listitem>
          <para>
            is the main elogind utility library
          </para>
          <indexterm zone="elogind libelogind">
            <primary sortas="c-libelogind">libelogind.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>