path: root/chapter07/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-scripts-systemd-custom" revision="systemd">
  <?dbhtml filename="systemd-custom.html"?>

  <title>Systemd Usage and Configuration</title>

  <indexterm zone="ch-scripts-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 the following:</para>

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

    <para>Alternatively, if a a separate partition for
    <filename class="directory">/tmp</filename> is desired, specify that 
    partition in an <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 is 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 parameter 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 work 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>: povides functionality similar
         to tail -f (follow).</para>
       </listitem>
    </itemizedlist>

  </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>deamon()</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 enable
          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>