diff options
Diffstat (limited to 'man/journald.conf.xml')
| -rw-r--r-- | man/journald.conf.xml | 511 |
1 files changed, 511 insertions, 0 deletions
diff --git a/man/journald.conf.xml b/man/journald.conf.xml new file mode 100644 index 0000000..2db6a0f --- /dev/null +++ b/man/journald.conf.xml @@ -0,0 +1,511 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<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> + <refname>journald@.conf</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> + <para><filename>/etc/systemd/journald@<replaceable>NAMESPACE</replaceable>.conf</filename></para> + <para><filename>/etc/systemd/journald@<replaceable>NAMESPACE</replaceable>.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/journald@<replaceable>NAMESPACE</replaceable>.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/journald@<replaceable>NAMESPACE</replaceable>.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>7</manvolnum></citerefentry> + for a general description of the syntax.</para> + + <para>The <command>systemd-journald</command> instance managing the default namespace is configured by + <filename>/etc/systemd/journald.conf</filename> and associated drop-ins. Instances managing other + namespaces read <filename>/etc/systemd/journald@<replaceable>NAMESPACE</replaceable>.conf</filename> + and associated drop-ins with the namespace identifier filled in. This allows each namespace to carry + a distinct configuration. See + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about journal namespaces.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + [Journal] 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> behaves like <literal>persistent</literal> if the + <filename>/var/log/journal</filename> directory exists, and <literal>volatile</literal> otherwise + (the existence of the directory controls the storage mode). <literal>none</literal> turns off all + storage, all log data received will be dropped (but forwarding to other targets, such as the console, + the kernel log buffer, or a syslog socket will still work). Defaults to <literal>auto</literal> in + the default journal namespace, and <literal>persistent</literal> in all others.</para> + + <para>Note that journald will initially use volatile storage, until a call to + <command>journalctl --flush</command> (or sending <constant>SIGUSR1</constant> to journald) will cause + it to switch to persistent logging (under the conditions mentioned above). This is done automatically + on boot via <literal>systemd-journal-flush.service</literal>.</para> + + <para>Note that when this option is changed to <literal>volatile</literal>, existing persistent data + is not removed. In the other direction, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> with + the <option>--flush</option> option may be used to move volatile data to persistent storage.</para> + + <para>When journal namespacing (see <varname>LogNamespace=</varname> in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>) is + used, setting <varname>Storage=</varname> to <literal>volatile</literal> or <literal>auto</literal> + will not have an effect on the creation of the per-namespace logs directory in + <filename>/var/log/journal/</filename>, as the <filename>systemd-journald@.service</filename> service + file by default carries <varname>LogsDirectory=</varname>. To turn that off, add a unit file drop-in + file that sets <varname>LogsDirectory=</varname> to an empty string.</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 (with UID outside the range of system users, dynamic service users, + and the nobody user) will each get their own journal files, and system users will log to the system journal. + See <ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink> + for more details about UID ranges. + 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>Note that the effective rate limit is multiplied by a + factor derived from the available free disk space for the journal. + Currently, this factor is calculated using the base 2 logarithm.</para> + + <table> + <title>Example <varname>RateLimitBurst=</varname> rate + modifications by the available disk space</title> + <tgroup cols='2'> + <colspec colname='freespace' /> + <colspec colname='multiplier' /> + <thead> + <row> + <entry>Available Disk Space</entry> + <entry>Burst Multiplier</entry> + </row> + </thead> + <tbody> + <row> + <entry><= 1MB</entry> + <entry>1</entry> + </row> + <row> + <entry><= 16MB</entry> + <entry>2</entry> + </row> + <row> + <entry><= 256MB</entry> + <entry>3</entry> + </row> + <row> + <entry><= 4GB</entry> + <entry>4</entry> + </row> + <row> + <entry><= 64GB</entry> + <entry>5</entry> + </row> + <row> + <entry><= 1TB</entry> + <entry>6</entry> + </row> + </tbody> + </tgroup> + </table> + + <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> capped + to 128M, so that usually seven rotated journal files are kept as history. If the journal compact + mode is enabled (enabled by default), the maximum file size is capped to 4G.</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.</para> + + <para>When forwarding to the console, the TTY to log to can be changed with + <varname>TTYPath=</varname>, described below.</para> + + <para>When forwarding to the kernel log buffer (kmsg), make sure to select a suitably large size for + the log buffer, for example by adding <literal>log_buf_len=8M</literal> to the kernel command line. + <command>systemd</command> will automatically disable kernel's rate-limiting applied to userspace + processes (equivalent to setting <literal>printk.devkmsg=on</literal>).</para></listitem> + + <para>Note: Forwarding is performed synchronously within journald, and may significantly affect its + performance. This is particularly relevant when using ForwardToConsole=yes in cloud environments, + where the console is often a slow, virtual serial port. Since journald is implemented as a + conventional single-process daemon, forwarding to a completely hung console will block journald. + This can have a cascading effect resulting in any services synchronously logging to the blocked + journal also becoming blocked. Unless actively debugging/developing something, it's generally + preferable to setup a <command>journalctl --follow</command> style service redirected to the + console, instead of ForwardToConsole=yes, for production use.</para> + </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 in the journal, 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 stored in the journal 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 <command>systemd-journal</command> processes + <filename>/dev/kmsg</filename> messages generated by the kernel. In the default journal namespace + this option is enabled by default, it is disabled in all others.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Audit=</varname></term> + + <listitem><para>Takes a boolean value. If enabled <command>systemd-journal</command> will turn on + kernel auditing on start-up. If disabled it will turn it off. If unset it will neither enable nor + disable it, leaving the previous state unchanged. Note that this option does not control whether + <command>systemd-journald</command> collects generated audit records, it just controls whether it + tells the kernel to generate them. This means if another tool turns on auditing even if + <command>systemd-journald</command> left it off, it will still collect the generated + messages. Defaults to on.</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 <constant>NUL</constant> 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> |