glfs/general/sysutils/systemd.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 systemd-download-http "https://anduin.linuxfromscratch.org/LFS/systemd-&systemd-version;-&systemd-stable;.tar.xz"> For whenever we move to a stable snapshot for backports -->
  <!ENTITY systemd-download-http "https://github.com/systemd/systemd/archive/v&systemd-version;/systemd-&systemd-version;.tar.gz">
  <!ENTITY systemd-download-ftp  " ">
  <!ENTITY systemd-md5sum        "521cda27409a9edf0370c128fae3e690">
  <!ENTITY systemd-size          "15 MB">
  <!ENTITY systemd-buildsize     "198 MB (with tests)">
  <!ENTITY systemd-time          "3.7 SBU (with tests using 4 cores)">

]>

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


  <title>Systemd-&systemd-version;</title>
  <!-- Whenever we switch back to stable backports, make sure to add the systemd-stable reference back. -->

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

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

    <para>
      While <application>systemd</application> was installed when
      building LFS, there are many features provided by the package that
      were not included in the initial installation because
      <application>Linux-PAM</application> was not yet installed.
      The <application>systemd</application> package needs to be
      rebuilt to provide a working <command>systemd-logind</command> service,
      which provides many additional features for dependent packages.
    </para>

    &lfs121_checked;

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

<!--  Comment out (instead of remove) in case a patch will be needed.-->
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
         Required patch:
         <ulink url="&patch-root;/systemd-&systemd-version;-upstream_fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Recommended</bridgehead>

    <note>
      <para>
        <xref linkend='linux-pam'/> is not strictly required to build
        <application>systemd</application>, but the main reason to rebuild
        <application>systemd</application> in BLFS (it's already built in
        LFS anyway) is for the <command>systemd-logind</command> daemon and
        the
        <filename class='libraryfile'>pam_systemd.so</filename> PAM module.
        <xref linkend='linux-pam'/> is required for them.  All packages in
        BLFS book with a dependency on <application>systemd</application>
        expects it has been rebuilt with <xref linkend='linux-pam'/>.
      </para>
    </note>

    <para role="recommended">
      <xref linkend="linux-pam"/> and
      <xref role="runtime" linkend="polkit"/> (runtime)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="btrfs-progs"/>, <!-- homed may support it, see the C.E.-->
      <xref linkend="curl"/>,
      <xref linkend="cryptsetup"/>,
      <xref linkend="git"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="iptables"/>,
      <xref linkend="libgcrypt"/>,
      <xref linkend="libidn2"/>,
      <xref linkend="libpwquality"/>,
      <xref linkend="libseccomp"/>,
      <xref linkend="libxkbcommon"/>,
      <xref linkend="make-ca"/>,
      <xref linkend="p11-kit"/>,
      <xref linkend="pcre2"/>,
      <xref linkend="qemu"/>,
      <xref linkend="qrencode"/>,
      <xref linkend="rsync"/>,
      <xref linkend="sphinx"/>,
      <xref linkend="valgrind"/>,
      <xref linkend="zsh"/> (for the zsh completions),
      <ulink url="https://www.apparmor.net/">AppArmor</ulink>,
      <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://jekyllrb.com/">jekyll</ulink>,
      <ulink url="https://www.kernel.org/pub/linux/utils/kernel/kexec/">kexec-tools</ulink>,
      <ulink url="https://github.com/libbpf/libbpf">libbpf</ulink>,
      <ulink url="https://sourceware.org/elfutils/">libdw</ulink>,
      <ulink url="https://developers.yubico.com/libfido2/">libfido2</ulink>,
      <ulink url="https://www.gnu.org/software/libmicrohttpd/">libmicrohttpd</ulink>,
      <ulink url="https://pypi.org/project/pefile/">pefile</ulink>,
      <ulink url="https://pypi.org/project/pyelftools/">pyelftools</ulink>,
      <ulink url="https://sourceforge.net/projects/linuxquota/">quota-tools</ulink>,
      <ulink url="https://rpm.org/">rpm</ulink>,
      <ulink url="https://github.com/SELinuxProject/selinux">SELinux</ulink>,
      <ulink url="https://sourceware.org/systemtap/">systemtap</ulink>,
      <ulink url="https://tpm2-tss.readthedocs.io/en/latest/">tpm2-tss</ulink>
      and <ulink url="https://xenproject.org">Xen</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (to rebuild the manual pages)</bridgehead>
    <para role="optional">
      <xref linkend="DocBook"/>,
      <xref linkend="docbook-xsl"/>,
      <xref linkend="libxslt"/>, and
      <xref linkend="lxml"/> (to build the index of systemd manual pages)
    </para>

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

  </sect2>

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

    <para>
      Remove two unneeded groups,
      <systemitem class="groupname">render</systemitem> and
      <systemitem class="groupname">sgx</systemitem>, from the default udev
      rules:
    </para>

<screen><userinput remap="pre">sed -i -e 's/GROUP="render"/GROUP="video"/' \
       -e 's/GROUP="sgx", //' rules.d/50-udev-default.rules.in</userinput></screen>

    <para>
      Now fix a security vulnerability in the DNSSEC verification of
      <command>systemd-resolved</command> and a bug breaking running
      <command>systemd-analyze verify</command> on an instantiated systemd
      unit:
    </para>

    <screen><userinput>patch -Np1 -i ../systemd-&systemd-version;-upstream_fixes-1.patch</userinput></screen>

    <para>
      Rebuild <application>systemd</application> by running the
      following commands:
    </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..                \
      --prefix=/usr           \
      --buildtype=release     \
      -Ddefault-dnssec=no     \
      -Dfirstboot=false       \
      -Dinstall-tests=false   \
      -Dldconfig=false        \
      -Dman=auto              \
      -Dsysusers=false        \
      -Drpmmacrosdir=no       \
      -Dhomed=disabled        \
      -Duserdb=false          \
      -Dmode=release          \
      -Dpam=enabled           \
      -Dpamconfdir=/etc/pam.d \
      -Ddev-kvm-mode=0660     \
      -Dnobody-group=nogroup  \
      -Dsysupdate=disabled    \
      -Dukify=disabled        \
      -Ddocdir=/usr/share/doc/systemd-&systemd-version; &amp;&amp;

ninja</userinput></screen>
<!-- Regarding homed and userdb, see the note below in Command Explanations-->

    <note>
      <para>
        For the best test results, make sure you run the test suite from
        a system that is booted by the same
        <application>systemd</application> version you are rebuilding.
      </para>
    </note>

    <para>
      To test the results, issue: <command>ninja test</command>.
      <!-- test-netlink: https://github.com/systemd/systemd/issues/27969 -->
      The test named <filename>test-stat-util</filename> and
      <filename>test-netlink</filename> are known to fail
      if some kernel features are not enabled.
      If the test suite is ran as the &root; user, some
      other tests may fail because they depend on various kernel
      configuration options.
    </para>

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

<screen role="root"><userinput>ninja install</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>

    <para>
      <parameter>-Dpamconfdir=/etc/pam.d</parameter>: Forces the PAM files to
      be installed in /etc/pam.d rather than /usr/lib/pam.d.
    </para>

    <para>
      <parameter>-Duserdb=false</parameter>: Removes a daemon that does not
      offer any use under a BLFS configuration. If you wish to enable the
      <application>userdbd</application> daemon, replace "false" with "true"
      in the above meson command.
    </para>

    <para>
      <parameter>-Dhomed=disabled</parameter>: Removes a daemon that does not offer
      any use under a traditional BLFS configuration, especially using accounts
      created with useradd. To enable systemd-homed, first ensure that you have
      <xref linkend="cryptsetup"/> and <xref linkend="libpwquality"/> installed,
      and then change <quote>disabled</quote> to <quote>enabled</quote>
      in the above <command>meson setup</command> command.
    </para>

    <para>
      <parameter>-Dukify=disabled</parameter>: Removes a script for
      combining a kernel, an initramfs, and a kernel command line etc.
      into an UEFI application which can be loaded by the UEFI firmware
      to start the embedded Linux kernel.  It's not needed for booting a
      BLFS system with UEFI if following <xref linkend='grub-setup'/>.
      And, it requires the <application>pefile</application> Python module
      at runtime, so if it's enabled but <application>pefile</application>
      is not installed, in the test suite one test for it will fail.  To
      enable <command>systemd-ukify</command>, install the
      <application>pefile</application> module and then change
      <quote>disabled</quote> to <quote>enabled</quote> in the above
      <command>meson setup</command> command.
    </para>

    <!-- EDITORS NOTE: Explanation on removing userdbd and homed:
    In BLFS, we do not fully support disk encryption. We offer instructions for
    building 'cryptsetup' as a dependency, but we do not offer instructions for
    actually configuring it. In addition, we generally do not include
    functionality that could potentially conflict with other packages, or that
    is not of any use to us (in an enterprise configuration using Thin Clients
    or laptops with LUKS encryption, it could make sense though, but that isn't
    the configuration that we natively support).

    A few of the complications of systemd-homed include:
      - SSH Logins
      - Disk Space Assignments
      - UID Assignments (chown() on login)
      (See https://cfp.all-systems-go.io/media/homed-asg2019.pdf)

    In an article I read when systemd-homed was originally unveiled, I remember
    reading about systemd-homed causing problems with OpenSSH Private Key Auth
    because the user would have to login at the console in order to unlock
    their home directory, thus allowing the private key to be unlocked and
    processed by OpenSSH. Since BLFS does not fully support encrypted disks,
    and because systemd-homed is incompatible with our usage of useradd /
    traditional UNIX users and groups, I advise that we take the following
    approach to avoid any confusion:

    - Leave the added Short Descriptions for homectl and userdbctl
    - Add the above command explanations and restore the previous behavior

    Should we decide to enable homed by default anytime in the future,
    let's move cryptsetup to recommended or required.

    I would be open to discussing this after the next systemd version when
    systemd-homed has matured a bit more. -renodr -->

  </sect2>

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

    <para>
      The <filename>/etc/pam.d/system-session</filename> file needs to
      be modified and a new file needs to be created in order for
      <command>systemd-logind</command> to work correctly. Run the following
      commands as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>grep 'pam_systemd' /etc/pam.d/system-session ||
cat &gt;&gt; /etc/pam.d/system-session &lt;&lt; "EOF"
<literal># Begin Systemd addition

session  required    pam_loginuid.so
session  optional    pam_systemd.so

# End Systemd addition</literal>
EOF

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

account  required    pam_access.so
account  include     system-account

session  required    pam_env.so
session  required    pam_limits.so
session  required    pam_loginuid.so
session  optional    pam_keyinit.so force revoke
session  optional    pam_systemd.so

auth     required    pam_deny.so
password required    pam_deny.so

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

    <!-- For some unknown reason if I don't do this, the per-user systemd
         manager fails to start with "Trying to run as user instance,
         but $XDG_RUNTIME_DIR is not set."  This command is enough to
         fix the issue, and it also seems logical to start using the newly
         rebuilt systemd right away (like "exec bash -&dash;login" in LFS),
         so just add it.  -->
    <para>
      As the &root; user, replace the running <command>systemd</command>
      manager (the <command>init</command> process) with the
      <command>systemd</command> executable newly built and installed:
    </para>

    <screen role='root'><userinput>systemctl daemon-reexec</userinput></screen>

    <important>
      <para>
        Now ensure <xref linkend='shadow'/> has been already rebuilt with
        <xref linkend='linux-pam'/> support first, then logout, and login
        again.  This ensures the running login session registered with
        <command>systemd-logind</command> and a per-user systemd instance
        running for each user owning a login session.  Many BLFS packages
        listing Systemd as a dependency needs the
        <command>systemd-logind</command> integration and/or a running
        per-user systemd instance.
      </para>
    </important>

    <warning>
      <para>
        If upgrading from a previous version of systemd and an
        initrd is used for system boot, you should generate a new initrd before
        rebooting the system.
      </para>
    </warning>

  </sect2>

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

      <para>
        A list of the installed files, along with their short
        descriptions can be found at
        <ulink url="&lfs-root;/chapter08/systemd.html#contents-systemd"/>.
      </para>

      <para>
        Listed below are the newly installed programs
        along with short descriptions.
      </para>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>

      <seglistitem>
        <seg>
          <!-- maybe userdbd/userdbctl can go in LFS, try at next time -->
          homectl (optional),
          systemd-cryptenroll (if <xref linkend="cryptsetup"/> is installed),
          and userdbctl (optional)
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="homectl">
        <term><command>homectl</command></term>
        <listitem>
          <para>
            is a tool to create, remove, change, or inspect a home directory
            managed by <command>systemd-homed</command>;  note that it's
            useless for the classic UNIX users and home directories which
            we are using in LFS/BLFS book
          </para>
          <indexterm zone="systemd homectl">
            <primary sortas="b-homectl">homectl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="systemd-cryptenroll">
        <term><command>systemd-cryptenroll</command></term>
        <listitem>
          <para>
            Is used to enroll or remove a system from full disk encryption,
            as well as set and query private keys and recovery keys
          </para>
          <indexterm zone="systemd systemd-cryptenroll">
            <primary sortas="b-systemd-cryptenroll">systemd-cryptenroll</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="userdbctl">
        <term><command>userdbctl</command></term>
        <listitem>
          <para>
            inspects users, groups, and group memberships
          </para>
          <indexterm zone="systemd userdbctl">
            <primary sortas="b-userdbctl">userdbctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pam_systemd">
        <term><filename class="libraryfile">pam_systemd.so</filename></term>
        <listitem>
          <para>
            is a PAM module used to register user sessions with the
            <application>systemd</application> login manager,
            <command>systemd-logind</command>
          </para>
          <indexterm zone="systemd pam_systemd">
            <primary sortas="c-pam_systemd">pam_systemd.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>