Adding upstream version 241.upstream/241upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 425 insertions, 0 deletions

diff --git a/man/journald.conf.xml b/man/journald.conf.xml
new file mode 100644
index 0000000..2791678
--- /dev/null
+++ b/man/journald.conf.xml
@@ -0,0 +1,425 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  SPDX-License-Identifier: LGPL-2.1+
+-->
+
+<refentry id="journald.conf"
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+  <refentryinfo>
+    <title>journald.conf</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>journald.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>journald.conf</refname>
+    <refname>journald.conf.d</refname>
+    <refpurpose>Journal service configuration files</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>/etc/systemd/journald.conf</filename></para>
+    <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para>
+    <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para>
+    <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>These files configure various parameters of the systemd journal service,
+    <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+    See
+    <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for a general description of the syntax.</para>
+
+  </refsect1>
+
+  <xi:include href="standard-conf.xml" xpointer="main-conf" />
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>All options are configured in the
+    <literal>[Journal]</literal> section:</para>
+
+    <variablelist class='config-directives'>
+
+      <varlistentry>
+        <term><varname>Storage=</varname></term>
+
+        <listitem><para>Controls where to store journal data. One of
+        <literal>volatile</literal>,
+        <literal>persistent</literal>,
+        <literal>auto</literal> and
+        <literal>none</literal>. If
+        <literal>volatile</literal>, journal
+        log data will be stored only in memory, i.e. below the
+        <filename>/run/log/journal</filename> hierarchy (which is
+        created if needed). If <literal>persistent</literal>, data
+        will be stored preferably on disk, i.e. below the
+        <filename>/var/log/journal</filename> hierarchy (which is
+        created if needed), with a fallback to
+        <filename>/run/log/journal</filename> (which is created if
+        needed), during early boot and if the disk is not writable.
+        <literal>auto</literal> is similar to
+        <literal>persistent</literal> but the directory
+        <filename>/var/log/journal</filename> is not created if
+        needed, so that its existence controls where log data goes.
+        <literal>none</literal> turns off all storage, all log data
+        received will be dropped. Forwarding to other targets, such as
+        the console, the kernel log buffer, or a syslog socket will
+        still work however. Defaults to
+        <literal>auto</literal>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>Compress=</varname></term>
+
+        <listitem><para>Can take a boolean value. If enabled (the
+        default), data objects that shall be stored in the journal
+        and are larger than the default threshold of 512 bytes are
+        compressed before they are written to the file system. It
+        can also be set to a number of bytes to specify the
+        compression threshold directly. Suffixes like K, M, and G
+        can be used to specify larger units.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>Seal=</varname></term>
+
+        <listitem><para>Takes a boolean value. If enabled (the
+        default), and a sealing key is available (as created by
+        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+        <option>--setup-keys</option> command), Forward Secure Sealing
+        (FSS) for all persistent journal files is enabled. FSS is
+        based on <ulink
+        url="https://eprint.iacr.org/2013/397">Seekable Sequential Key
+        Generators</ulink> by G. A. Marson and B. Poettering
+        (doi:10.1007/978-3-642-40203-6_7) and may be used to protect
+        journal files from unnoticed alteration.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>SplitMode=</varname></term>
+
+        <listitem><para>Controls whether to split up journal files per user, either <literal>uid</literal> or
+        <literal>none</literal>. Split journal files are primarily useful for access control: on UNIX/Linux access
+        control is managed per file, and the journal daemon will assign users read access to their journal files. If
+        <literal>uid</literal>, all regular users will each get their own journal files, and system users will log to
+        the system journal. If <literal>none</literal>, journal files are not split up by user and all messages are
+        instead stored in the single system journal. In this mode unprivileged users generally do not have access to
+        their own log data. Note that splitting up journal files by user is only available for journals stored
+        persistently. If journals are stored on volatile storage (see <varname>Storage=</varname> above), only a single
+        journal file is used. Defaults to <literal>uid</literal>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>RateLimitIntervalSec=</varname></term>
+        <term><varname>RateLimitBurst=</varname></term>
+
+        <listitem><para>Configures the rate limiting that is applied
+        to all messages generated on the system. If, in the time
+        interval defined by <varname>RateLimitIntervalSec=</varname>,
+        more messages than specified in
+        <varname>RateLimitBurst=</varname> are logged by a service,
+        all further messages within the interval are dropped until the
+        interval is over. A message about the number of dropped
+        messages is generated. This rate limiting is applied
+        per-service, so that two services which log do not interfere
+        with each other's limits. Defaults to 10000 messages in 30s.
+        The time specification for
+        <varname>RateLimitIntervalSec=</varname> may be specified in the
+        following units: <literal>s</literal>, <literal>min</literal>,
+        <literal>h</literal>, <literal>ms</literal>,
+        <literal>us</literal>. To turn off any kind of rate limiting,
+        set either value to 0.</para>
+
+        <para>If a service provides rate limits for itself through
+        <varname>LogRateLimitIntervalSec=</varname> and/or <varname>LogRateLimitBurst=</varname>
+        in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        those values will override the settings specified here.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>SystemMaxUse=</varname></term>
+        <term><varname>SystemKeepFree=</varname></term>
+        <term><varname>SystemMaxFileSize=</varname></term>
+        <term><varname>SystemMaxFiles=</varname></term>
+        <term><varname>RuntimeMaxUse=</varname></term>
+        <term><varname>RuntimeKeepFree=</varname></term>
+        <term><varname>RuntimeMaxFileSize=</varname></term>
+        <term><varname>RuntimeMaxFiles=</varname></term>
+
+        <listitem><para>Enforce size limits on the journal files
+        stored. The options prefixed with <literal>System</literal>
+        apply to the journal files when stored on a persistent file
+        system, more specifically
+        <filename>/var/log/journal</filename>. The options prefixed
+        with <literal>Runtime</literal> apply to the journal files
+        when stored on a volatile in-memory file system, more
+        specifically <filename>/run/log/journal</filename>. The former
+        is used only when <filename>/var</filename> is mounted,
+        writable, and the directory
+        <filename>/var/log/journal</filename> exists. Otherwise, only
+        the latter applies. Note that this means that during early
+        boot and if the administrator disabled persistent logging,
+        only the latter options apply, while the former apply if
+        persistent logging is enabled and the system is fully booted
+        up. <command>journalctl</command> and
+        <command>systemd-journald</command> ignore all files with
+        names not ending with <literal>.journal</literal> or
+        <literal>.journal~</literal>, so only such files, located in
+        the appropriate directories, are taken into account when
+        calculating current disk usage.</para>
+
+        <para><varname>SystemMaxUse=</varname> and
+        <varname>RuntimeMaxUse=</varname> control how much disk space
+        the journal may use up at most.
+        <varname>SystemKeepFree=</varname> and
+        <varname>RuntimeKeepFree=</varname> control how much disk
+        space systemd-journald shall leave free for other uses.
+        <command>systemd-journald</command> will respect both limits
+        and use the smaller of the two values.</para>
+
+        <para>The first pair defaults to 10% and the second to 15% of
+        the size of the respective file system, but each value is
+        capped to 4G. If the file system is nearly full and either
+        <varname>SystemKeepFree=</varname> or
+        <varname>RuntimeKeepFree=</varname> are violated when
+        systemd-journald is started, the limit will be raised to the
+        percentage that is actually free. This means that if there was
+        enough free space before and journal files were created, and
+        subsequently something else causes the file system to fill up,
+        journald will stop using more space, but it will not be
+        removing existing files to reduce the footprint again,
+        either. Also note that only archived files are deleted to reduce the
+        space occupied by journal files. This means that, in effect, there might
+        still be more space used than <varname>SystemMaxUse=</varname> or
+        <varname>RuntimeMaxUse=</varname> limit after a vacuuming operation is
+        complete.</para>
+
+        <para><varname>SystemMaxFileSize=</varname> and
+        <varname>RuntimeMaxFileSize=</varname> control how large
+        individual journal files may grow at most. This influences
+        the granularity in which disk space is made available through
+        rotation, i.e. deletion of historic data. Defaults to one
+        eighth of the values configured with
+        <varname>SystemMaxUse=</varname> and
+        <varname>RuntimeMaxUse=</varname>, so that usually seven
+        rotated journal files are kept as history.</para>
+
+        <para>Specify values in bytes or use K, M, G, T, P, E as
+        units for the specified sizes (equal to 1024, 1024², … bytes).
+        Note that size limits are enforced synchronously when journal
+        files are extended, and no explicit rotation step triggered by
+        time is needed.</para>
+
+        <para><varname>SystemMaxFiles=</varname> and
+        <varname>RuntimeMaxFiles=</varname> control how many
+        individual journal files to keep at most. Note that only
+        archived files are deleted to reduce the number of files until
+        this limit is reached; active files will stay around. This
+        means that, in effect, there might still be more journal files
+        around in total than this limit after a vacuuming operation is
+        complete. This setting defaults to 100.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>MaxFileSec=</varname></term>
+
+        <listitem><para>The maximum time to store entries in a single
+        journal file before rotating to the next one. Normally,
+        time-based rotation should not be required as size-based
+        rotation with options such as
+        <varname>SystemMaxFileSize=</varname> should be sufficient to
+        ensure that journal files do not grow without bounds. However,
+        to ensure that not too much data is lost at once when old
+        journal files are deleted, it might make sense to change this
+        value from the default of one month. Set to 0 to turn off this
+        feature. This setting takes time values which may be suffixed
+        with the units <literal>year</literal>,
+        <literal>month</literal>, <literal>week</literal>,
+        <literal>day</literal>, <literal>h</literal> or
+        <literal>m</literal> to override the default time unit of
+        seconds.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>MaxRetentionSec=</varname></term>
+
+        <listitem><para>The maximum time to store journal entries.
+        This controls whether journal files containing entries older
+        than the specified time span are deleted. Normally, time-based
+        deletion of old journal files should not be required as
+        size-based deletion with options such as
+        <varname>SystemMaxUse=</varname> should be sufficient to
+        ensure that journal files do not grow without bounds. However,
+        to enforce data retention policies, it might make sense to
+        change this value from the default of 0 (which turns off this
+        feature). This setting also takes time values which may be
+        suffixed with the units <literal>year</literal>,
+        <literal>month</literal>, <literal>week</literal>,
+        <literal>day</literal>, <literal>h</literal> or <literal>
+        m</literal> to override the default time unit of
+        seconds.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>SyncIntervalSec=</varname></term>
+
+        <listitem><para>The timeout before synchronizing journal files
+        to disk. After syncing, journal files are placed in the
+        OFFLINE state. Note that syncing is unconditionally done
+        immediately after a log message of priority CRIT, ALERT or
+        EMERG has been logged. This setting hence applies only to
+        messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The
+        default timeout is 5 minutes. </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>ForwardToSyslog=</varname></term>
+        <term><varname>ForwardToKMsg=</varname></term>
+        <term><varname>ForwardToConsole=</varname></term>
+        <term><varname>ForwardToWall=</varname></term>
+
+        <listitem><para>Control whether log messages received by the journal daemon shall
+        be forwarded to a traditional syslog daemon, to the kernel log buffer (kmsg), to
+        the system console, or sent as wall messages to all logged-in users.  These
+        options take boolean arguments. If forwarding to syslog is enabled but nothing
+        reads messages from the socket, forwarding to syslog has no effect. By default,
+        only forwarding to wall is enabled. These settings may be overridden at boot time
+        with the kernel command line options
+        <literal>systemd.journald.forward_to_syslog</literal>,
+        <literal>systemd.journald.forward_to_kmsg</literal>,
+        <literal>systemd.journald.forward_to_console</literal>, and
+        <literal>systemd.journald.forward_to_wall</literal>. If the option name is
+        specified without <literal>=</literal> and the following argument, true is
+        assumed. Otherwise, the argument is parsed as a boolean. When forwarding to the
+        console, the TTY to log to can be changed with <varname>TTYPath=</varname>,
+        described below.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>MaxLevelStore=</varname></term>
+        <term><varname>MaxLevelSyslog=</varname></term>
+        <term><varname>MaxLevelKMsg=</varname></term>
+        <term><varname>MaxLevelConsole=</varname></term>
+        <term><varname>MaxLevelWall=</varname></term>
+
+        <listitem><para>Controls the maximum log level of messages
+        that are stored on disk, forwarded to syslog, kmsg, the
+        console or wall (if that is enabled, see above). As argument,
+        takes one of
+        <literal>emerg</literal>,
+        <literal>alert</literal>,
+        <literal>crit</literal>,
+        <literal>err</literal>,
+        <literal>warning</literal>,
+        <literal>notice</literal>,
+        <literal>info</literal>,
+        <literal>debug</literal>,
+        or integer values in the range of 0–7 (corresponding to the
+        same levels). Messages equal or below the log level specified
+        are stored/forwarded, messages above are dropped. Defaults to
+        <literal>debug</literal> for <varname>MaxLevelStore=</varname>
+        and <varname>MaxLevelSyslog=</varname>, to ensure that the all
+        messages are written to disk and forwarded to syslog. Defaults
+        to
+        <literal>notice</literal> for <varname>MaxLevelKMsg=</varname>,
+        <literal>info</literal> for <varname>MaxLevelConsole=</varname>,
+        and <literal>emerg</literal> for
+        <varname>MaxLevelWall=</varname>. These settings may be
+        overridden at boot time with the kernel command line options
+        <literal>systemd.journald.max_level_store=</literal>,
+        <literal>systemd.journald.max_level_syslog=</literal>,
+        <literal>systemd.journald.max_level_kmsg=</literal>,
+        <literal>systemd.journald.max_level_console=</literal>,
+        <literal>systemd.journald.max_level_wall=</literal>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>ReadKMsg=</varname></term>
+
+        <listitem><para>Takes a boolean value. If enabled (the
+        default), journal reads <filename>/dev/kmsg</filename>
+        messages generated by the kernel.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>TTYPath=</varname></term>
+
+        <listitem><para>Change the console TTY to use if
+        <varname>ForwardToConsole=yes</varname> is used. Defaults to
+        <filename>/dev/console</filename>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>LineMax=</varname></term>
+
+        <listitem><para>The maximum line length to permit when converting stream logs into record logs. When a systemd
+        unit's standard output/error are connected to the journal via a stream socket, the data read is split into
+        individual log records at newline (<literal>\n</literal>, ASCII 10) and NUL characters. If no such delimiter is
+        read for the specified number of bytes a hard log record boundary is artificially inserted, breaking up overly
+        long lines into multiple log records. Selecting overly large values increases the possible memory usage of the
+        Journal daemon for each stream client, as in the worst case the journal daemon needs to buffer the specified
+        number of bytes in memory before it can flush a new log record to disk. Also note that permitting overly large
+        line maximum line lengths affects compatibility with traditional log protocols as log records might not fit
+        anymore into a single <constant>AF_UNIX</constant> or <constant>AF_INET</constant> datagram. Takes a size in
+        bytes. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes,
+        Gigabytes, or Terabytes (with the base 1024), respectively. Defaults to 48K, which is relatively large but
+        still small enough so that log records likely fit into network datagrams along with extra room for
+        metadata. Note that values below 79 are not accepted and will be bumped to 79.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Forwarding to traditional syslog daemons</title>
+
+    <para>
+      Journal events can be transferred to a different logging daemon
+      in two different ways. With the first method, messages are
+      immediately forwarded to a socket
+      (<filename>/run/systemd/journal/syslog</filename>), where the
+      traditional syslog daemon can read them. This method is
+      controlled by the <varname>ForwardToSyslog=</varname> option. With a
+      second method, a syslog daemon behaves like a normal journal
+      client, and reads messages from the journal files, similarly to
+      <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+      With this, messages do not have to be read immediately,
+      which allows a logging daemon which is only started late in boot
+      to access all messages since the start of the system. In
+      addition, full structured meta-data is available to it. This
+      method of course is available only if the messages are stored in
+      a journal file at all. So it will not work if
+      <varname>Storage=none</varname> is set. It should be noted that
+      usually the <emphasis>second</emphasis> method is used by syslog
+      daemons, so the <varname>Storage=</varname> option, and not the
+      <varname>ForwardToSyslog=</varname> option, is relevant for them.
+    </para>
+  </refsect1>
+
+  <refsect1>
+      <title>See Also</title>
+      <para>
+        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      </para>
+  </refsect1>
+
+</refentry>