source: general/sysutils/elogind.xml@ ba6e7d32

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

<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>

    &lfs121_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>

    <para condition="html" role="usernotes">
      Editor Notes: <ulink url="&blfs-wiki;/Logind"/>
    </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>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="elogind-kernel.xml"/>

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

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="elogind-test-kernel.xml"/>

    <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>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           \
      -Ddev-kvm-mode=0660                   \
      -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 &root; privileges.  
      One test, <filename>test-fs-util</filename> is known to fail.
      <!--
      <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.

      I did have the symlink and test-fs-util still failed (the only
      one).  The error was 
         Assertion 'chase_symlinks(q, NULL, CHASE_SAFE, NULL, NULL) >= 0' 
         failed at src/test/test-fs-util.c:303, function 
         test_chase_symlinks(). Aborting.
      Looking at teh code, I don't think that is related to the 
      /etc/machine-id symlink. - bdubbs, version 252.23
      -->
    </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>-Ddev-kvm-mode=0660</parameter>: The LFS udev rule sets the
      mode of <filename class='devicefile'>/dev/kvm</filename> to 0660.
      This option ensures the elogind udev rules consistent with the LFS
      configuration.
    </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>

    <note>
      <para>After completion of <application>elogind</application>, 
      you should check that it functions properly.  First ensure that
      <application>dbus</application> is running.  It may be easiest
      to do this by rebooting the system.  After logging in again, run 
      the command <command>loginctl</command>.  The result should indicate 
      that a SESSION and a SEAT have been created.</para>
    </note>

    </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>