path: root/chapter09/systemd-custom.xml

<?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;
]>

<sect1 id="ch-config-systemd-custom" revision="systemd">
  <?dbhtml filename="systemd-custom.html"?>

  <title>Systemd Usage and Configuration</title>

  <indexterm zone="ch-config-systemd-custom">
    <primary sortas="e-Systemd">Systemd Customization</primary>
  </indexterm>

  <sect2>
    <title>Basic Configuration</title>

    <para>The <filename>/etc/systemd/system.conf</filename> file contains a set
    of options to control basic systemd operations. The default file has all
    entries commented out with the default settings indicated. This file is
    where the log level may be changed as well as some basic logging settings.
    See the <filename>systemd-system.conf(5)</filename> manual page for details
    on each configuration option.</para>

  </sect2>

  <sect2>
    <title>Disabling Screen Clearing at Boot Time</title>

    <para>The normal behavior for systemd is to clear the screen at
    the end of the boot sequence. If desired, this behavior may be
    changed by running the following command:</para>

<screen role="nodump"><userinput>mkdir -pv /etc/systemd/system/getty@tty1.service.d

cat &gt; /etc/systemd/system/getty@tty1.service.d/noclear.conf &lt;&lt; EOF
<literal>[Service]
TTYVTDisallocate=no</literal>
EOF</userinput></screen>

    <para>The boot messages can always be reviewed by using the
    <userinput>journalctl -b</userinput> command as the root user.</para>

  </sect2>

  <sect2>
    <title>Disabling tmpfs for /tmp</title>

    <para>By default, <filename class="directory">/tmp</filename> is created as
    a tmpfs. If this is not desired, it can be overridden by executing the 
    following command:</para>

<screen role="nodump"><userinput>ln -sfv /dev/null /etc/systemd/system/tmp.mount</userinput></screen>

    <para>Alternatively, if a separate partition for
    <filename class="directory">/tmp</filename> is desired, specify that 
    partition in a <filename>/etc/fstab</filename> entry.</para>

    <warning>
      <para>
        Do not create the symbolic link above if a separate partition is used
        for <filename class="directory">/tmp</filename>.  This will prevent the
        root file system (/) from being remounted r/w and make the system
        unusable when booted.
      </para>
    </warning>

  </sect2>

  <sect2>
    <title>Configuring Automatic File Creation and Deletion</title>

    <para>There are several services that create or delete files or
    directories:</para>

    <itemizedlist>
      <listitem><para>systemd-tmpfiles-clean.service</para></listitem>
      <listitem><para>systemd-tmpfiles-setup-dev.service</para></listitem>
      <listitem><para>systemd-tmpfiles-setup.service</para></listitem>
    </itemizedlist>
  
    <para>The system location for the configuration files is
    <filename>/usr/lib/tmpfiles.d/*.conf</filename>. The local 
    configuration files are in
    <filename class="directory">/etc/tmpfiles.d</filename>. Files in
    <filename class="directory">/etc/tmpfiles.d</filename> override
    files with the same name in
    <filename class="directory">/usr/lib/tmpfiles.d</filename>. See
    <filename>tmpfiles.d(5)</filename> manual page for file format
    details.</para>

    <para>
      Note that the syntax for the
      <filename>/usr/lib/tmpfiles.d/*.conf</filename> files can be 
      confusing.  For example, the default deletion of files in the /tmp directory
      is located in <filename>/usr/lib/tmpfiles.d/tmp.conf</filename> with 
      the line:

<screen role="nodump">q /tmp 1777 root root 10d</screen>

      The type field, q, discusses creating a subvolume with quotas which
      is really only applicable to btrfs filesystems.  It references type v
      which in turn references type d (directory). This then creates the
      specified directory if it is not present and adjusts the permissions
      and ownership as specified. Contents of the directory will be
      subject to time based cleanup if the age argument is specified.
     </para>

     <para>
      If the default parameters are not desired, then the file should
      be copied to <filename class="directory">/etc/tmpfiles.d</filename>
      and edited as desired.  For example:

<screen role="nodump"><userinput>mkdir -p /etc/tmpfiles.d
cp /usr/lib/tmpfiles.d/tmp.conf /etc/tmpfiles.d</userinput></screen>
     </para>

  </sect2>

  <sect2>
    <title>Overriding Default Services Behavior</title>

    <para>The parameters of a unit can be overriden by creating a directory
    and a configuration file in <filename
    class="directory">/etc/systemd/system</filename>. For example:</para>

<screen role="nodump"><userinput>mkdir -pv /etc/systemd/system/foobar.service.d

cat > /etc/systemd/system/foobar.service.d/foobar.conf &lt;&lt; EOF
<literal>[Service]
Restart=always
RestartSec=30</literal>
EOF</userinput></screen>

     <para>See <filename>systemd.unit(5)</filename> manual page for more
     information. After creating the configuration file, run
     <userinput>systemctl daemon-reload</userinput> and <userinput>systemctl
     restart foobar</userinput> to activate the changes to a service.</para>

  </sect2>

  <sect2>
    <title>Debugging the Boot Sequence</title>

    <para>Rather than plain shell scripts used in SysVinit or BSD style init
    systems, systemd uses a unified format for different types of startup
    files (or units). The command <command>systemctl</command> is used to
    enable, disable, control state, and obtain status of unit files. Here 
    are some examples of frequently used commands:</para>

    <itemizedlist>
       <listitem>
         <para><command>systemctl list-units -t <replaceable>&lt;service&gt;</replaceable> [--all]</command>:
         lists loaded unit files of type service.</para>
       </listitem>
       <listitem>
         <para><command>systemctl list-units -t <replaceable>&lt;target&gt;</replaceable> [--all]</command>:
         lists loaded unit files of type target.</para>
       </listitem>
       <listitem>
         <para><command>systemctl show -p Wants <replaceable>&lt;multi-user.target&gt;</replaceable></command>:
         shows all units that depend on the multi-user target. Targets are
         special unit files that are anogalous to runlevels under
         SysVinit.</para>
       </listitem>
       <listitem>
         <para><command>systemctl status <replaceable>&lt;servicename.service&gt;</replaceable></command>:
         shows the status of the servicename service. The .service extension
         can be omitted if there are no other unit files with the same name,
         such as .socket files (which create a listening socket that provides
         similar functionality to inetd/xinetd).</para>
       </listitem>
    </itemizedlist>

  </sect2>

  <sect2>
    <title>Working with the Systemd Journal</title>

    <para>Logging on a system booted with systemd is handled with
    systemd-journald (by default), rather than a typical unix syslog daemon.
    You can also add a normal syslog daemon and have both operate side by
    side if desired. The systemd-journald program stores journal entries in a
    binary format rather than a plain text log file. To assist with
    parsing the file, the command <command>journalctl</command> is provided.
    Here are some examples of frequently used commands:</para>

    <itemizedlist>
       <listitem>
         <para><command>journalctl -r</command>: shows all contents of the
         journal in reverse chronological order.</para>
       </listitem>
       <listitem>
         <para><command>journalctl -u <replaceable>UNIT</replaceable></command>:
         shows the journal entries associated with the specified UNIT
         file.</para>
       </listitem>
       <listitem>
         <para><command>journalctl -b[=ID] -r</command>: shows the journal
         entries since last successful boot (or for boot ID) in reverse
         chronological order.</para>
       </listitem>
       <listitem>
         <para><command>journalctl -f</command>: provides functionality similar
         to tail -f (follow).</para>
       </listitem>
    </itemizedlist>

  </sect2>

  <sect2>
    <title>Working with Core Dumps</title>

    <para>Core dumps are useful to debug crashed programs, especially
    when a daemon process crashes. On systemd booted systems the core
    dumping is handled by <command>systemd-coredump</command>.  It will
    log the core dump in the journal and store the core dump itself in
    <filename class="directory">/var/lib/systemd/coredump</filename>.
    To retrieve and process core dumps, the <command>coredumpctl</command>
    tool is provided.  Here are some examples of frequently used commands:
    </para>

    <itemizedlist>
      <listitem>
        <para><command>coredumpctl -r</command>: lists all core dumps in
        reverse chronological order.</para>
      </listitem>
      <listitem>
        <para><command>coredumpctl -1 info</command>: shows the information
        from the last core dump.</para>
      </listitem>
      <listitem>
        <para><command>coredumpctl -1 debug</command>: loads the last core
        dump into <ulink url="&blfs-book;general/gdb.html">GDB</ulink>.
        </para>
      </listitem>
    </itemizedlist>

    <para>Core dumps may use a lot of disk space.  The maximum disk space
    used by core dumps can be limited by creating a configuration file in
    <filename class="directory">/etc/systemd/coredump.conf.d</filename>.
    For example:</para>

<screen role="nodump"><userinput>mkdir -pv /etc/systemd/coredump.conf.d

cat &gt; /etc/systemd/coredump.conf.d/maxuse.conf &lt;&lt; EOF
<literal>[Coredump]
MaxUse=5G</literal>
EOF</userinput></screen>

    <para>See the <filename>systemd-coredump(8)</filename>,
    <filename>coredumpctl(1)</filename>, and
    <filename>coredump.conf.d(5)</filename> manual pages for more
    information.</para>
  </sect2>

  <sect2>
    <title>Long Running Processes</title>

    <para>Beginning with systemd-230, all user processes are killed when a user
    session is ended, even if nohup is used, or the process uses the
    <function>daemon()</function> or <function>setsid()</function> functions.
    This is a deliberate change from a historically permissive environment to a
    more restrictive one. The new behavior may cause issues if you depend on
    long running programs (e.g., <command>screen</command> or
    <command>tmux</command>) to remain active after ending your user session.
    There are three ways to enable lingering processes to remain after a user
    session is ended.</para>

    <itemizedlist>
      <listitem>
        <para>
          <emphasis>Enable process lingering for only selected users</emphasis>:
          Normal users have permission to enable process lingering
          with the command <command>loginctl enable-linger</command> for their
          own user. System administrators can use the same command with a
          <parameter>user</parameter> argument to enable for a user. That user
          can then use the <command>systemd-run</command> command to start
          long running processes. For example: <command>systemd-run --scope
          --user /usr/bin/screen</command>. If you enable lingering for your
          user, the user@.service will remain even after all login sessions are
          closed, and will automatically start at system boot. This has the
          advantage of explicitly allowing and disallowing processes to run
          after the user session has ended, but breaks backwards compatibility
          with tools like <command>nohup</command> and utilities that use
          <function>daemon()</function>.
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>Enable system-wide process lingering</emphasis>:
          You can set <parameter>KillUserProcesses=no</parameter> in
          <filename>/etc/systemd/logind.conf</filename> to enable process lingering
          globally for all users. This has the benefit of leaving the old
          method available to all users at the expense of explicit control.
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>Disable at build-time</emphasis>: You can disable
          lingering by default while building systemd by adding the switch
          <parameter>-Ddefault-kill-user-processes=false</parameter> to the
          <command>meson</command> command for systemd. This completely
          disables the ability of systemd to kill user processes at session
          end.
        </para>
      </listitem>
    </itemizedlist>

  </sect2>

</sect1>