man/journald.conf.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="journald.conf"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11   <refentryinfo>
  12     <title>journald.conf</title>
  13     <productname>systemd</productname>
  14
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>Lennart</firstname>
  19         <surname>Poettering</surname>
  20         <email>lennart@poettering.net</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>journald.conf</refentrytitle>
  27     <manvolnum>5</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>journald.conf</refname>
  32     <refname>journald.conf.d</refname>
  33     <refpurpose>Journal service configuration files</refpurpose>
  34   </refnamediv>
  35
  36   <refsynopsisdiv>
  37     <para><filename>/etc/systemd/journald.conf</filename></para>
  38     <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para>
  39     <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para>
  40     <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para>
  41   </refsynopsisdiv>
  42
  43   <refsect1>
  44     <title>Description</title>
  45
  46     <para>These files configure various parameters of the systemd journal service,
  47     <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  48     See
  49     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  50     for a general description of the syntax.</para>
  51
  52   </refsect1>
  53
  54   <xi:include href="standard-conf.xml" xpointer="main-conf" />
  55
  56   <refsect1>
  57     <title>Options</title>
  58
  59     <para>All options are configured in the
  60     <literal>[Journal]</literal> section:</para>
  61
  62     <variablelist>
  63
  64       <varlistentry>
  65         <term><varname>Storage=</varname></term>
  66
  67         <listitem><para>Controls where to store journal data. One of
  68         <literal>volatile</literal>,
  69         <literal>persistent</literal>,
  70         <literal>auto</literal> and
  71         <literal>none</literal>. If
  72         <literal>volatile</literal>, journal
  73         log data will be stored only in memory, i.e. below the
  74         <filename>/run/log/journal</filename> hierarchy (which is
  75         created if needed). If <literal>persistent</literal>, data
  76         will be stored preferably on disk, i.e. below the
  77         <filename>/var/log/journal</filename> hierarchy (which is
  78         created if needed), with a fallback to
  79         <filename>/run/log/journal</filename> (which is created if
  80         needed), during early boot and if the disk is not writable.
  81         <literal>auto</literal> is similar to
  82         <literal>persistent</literal> but the directory
  83         <filename>/var/log/journal</filename> is not created if
  84         needed, so that its existence controls where log data goes.
  85         <literal>none</literal> turns off all storage, all log data
  86         received will be dropped. Forwarding to other targets, such as
  87         the console, the kernel log buffer, or a syslog socket will
  88         still work however. Defaults to
  89         <literal>auto</literal>.</para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><varname>Compress=</varname></term>
  94
  95         <listitem><para>Can take a boolean value. If enabled (the
  96         default), data objects that shall be stored in the journal
  97         and are larger than the default threshold of 512 bytes are
  98         compressed before they are written to the file system. It
  99         can also be set to a number of bytes to specify the
 100         compression threshold directly. Suffixes like K, M, and G
 101         can be used to specify larger units.</para></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><varname>Seal=</varname></term>
 106
 107         <listitem><para>Takes a boolean value. If enabled (the
 108         default), and a sealing key is available (as created by
 109         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 110         <option>--setup-keys</option> command), Forward Secure Sealing
 111         (FSS) for all persistent journal files is enabled. FSS is
 112         based on <ulink
 113         url="https://eprint.iacr.org/2013/397">Seekable Sequential Key
 114         Generators</ulink> by G. A. Marson and B. Poettering
 115         (doi:10.1007/978-3-642-40203-6_7) and may be used to protect
 116         journal files from unnoticed alteration.</para></listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><varname>SplitMode=</varname></term>
 121
 122         <listitem><para>Controls whether to split up journal files per user, either <literal>uid</literal> or
 123         <literal>none</literal>. Split journal files are primarily useful for access control: on UNIX/Linux access
 124         control is managed per file, and the journal daemon will assign users read access to their journal files. If
 125         <literal>uid</literal>, all regular users will each get their own journal files, and system users will log to
 126         the system journal. If <literal>none</literal>, journal files are not split up by user and all messages are
 127         instead stored in the single system journal. In this mode unprivileged users generally do not have access to
 128         their own log data. Note that splitting up journal files by user is only available for journals stored
 129         persistently. If journals are stored on volatile storage (see <varname>Storage=</varname> above), only a single
 130         journal file is used. Defaults to <literal>uid</literal>.</para></listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><varname>RateLimitIntervalSec=</varname></term>
 135         <term><varname>RateLimitBurst=</varname></term>
 136
 137         <listitem><para>Configures the rate limiting that is applied
 138         to all messages generated on the system. If, in the time
 139         interval defined by <varname>RateLimitIntervalSec=</varname>,
 140         more messages than specified in
 141         <varname>RateLimitBurst=</varname> are logged by a service,
 142         all further messages within the interval are dropped until the
 143         interval is over. A message about the number of dropped
 144         messages is generated. This rate limiting is applied
 145         per-service, so that two services which log do not interfere
 146         with each other's limits. Defaults to 10000 messages in 30s.
 147         The time specification for
 148         <varname>RateLimitIntervalSec=</varname> may be specified in the
 149         following units: <literal>s</literal>, <literal>min</literal>,
 150         <literal>h</literal>, <literal>ms</literal>,
 151         <literal>us</literal>. To turn off any kind of rate limiting,
 152         set either value to 0.</para></listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term><varname>SystemMaxUse=</varname></term>
 157         <term><varname>SystemKeepFree=</varname></term>
 158         <term><varname>SystemMaxFileSize=</varname></term>
 159         <term><varname>SystemMaxFiles=</varname></term>
 160         <term><varname>RuntimeMaxUse=</varname></term>
 161         <term><varname>RuntimeKeepFree=</varname></term>
 162         <term><varname>RuntimeMaxFileSize=</varname></term>
 163         <term><varname>RuntimeMaxFiles=</varname></term>
 164
 165         <listitem><para>Enforce size limits on the journal files
 166         stored. The options prefixed with <literal>System</literal>
 167         apply to the journal files when stored on a persistent file
 168         system, more specifically
 169         <filename>/var/log/journal</filename>. The options prefixed
 170         with <literal>Runtime</literal> apply to the journal files
 171         when stored on a volatile in-memory file system, more
 172         specifically <filename>/run/log/journal</filename>. The former
 173         is used only when <filename>/var</filename> is mounted,
 174         writable, and the directory
 175         <filename>/var/log/journal</filename> exists. Otherwise, only
 176         the latter applies. Note that this means that during early
 177         boot and if the administrator disabled persistent logging,
 178         only the latter options apply, while the former apply if
 179         persistent logging is enabled and the system is fully booted
 180         up. <command>journalctl</command> and
 181         <command>systemd-journald</command> ignore all files with
 182         names not ending with <literal>.journal</literal> or
 183         <literal>.journal~</literal>, so only such files, located in
 184         the appropriate directories, are taken into account when
 185         calculating current disk usage.</para>
 186
 187         <para><varname>SystemMaxUse=</varname> and
 188         <varname>RuntimeMaxUse=</varname> control how much disk space
 189         the journal may use up at most.
 190         <varname>SystemKeepFree=</varname> and
 191         <varname>RuntimeKeepFree=</varname> control how much disk
 192         space systemd-journald shall leave free for other uses.
 193         <command>systemd-journald</command> will respect both limits
 194         and use the smaller of the two values.</para>
 195
 196         <para>The first pair defaults to 10% and the second to 15% of
 197         the size of the respective file system, but each value is
 198         capped to 4G. If the file system is nearly full and either
 199         <varname>SystemKeepFree=</varname> or
 200         <varname>RuntimeKeepFree=</varname> are violated when
 201         systemd-journald is started, the limit will be raised to the
 202         percentage that is actually free. This means that if there was
 203         enough free space before and journal files were created, and
 204         subsequently something else causes the file system to fill up,
 205         journald will stop using more space, but it will not be
 206         removing existing files to reduce the footprint again,
 207         either.</para>
 208
 209         <para><varname>SystemMaxFileSize=</varname> and
 210         <varname>RuntimeMaxFileSize=</varname> control how large
 211         individual journal files may grow at most. This influences
 212         the granularity in which disk space is made available through
 213         rotation, i.e. deletion of historic data. Defaults to one
 214         eighth of the values configured with
 215         <varname>SystemMaxUse=</varname> and
 216         <varname>RuntimeMaxUse=</varname>, so that usually seven
 217         rotated journal files are kept as history.</para>
 218
 219         <para>Specify values in bytes or use K, M, G, T, P, E as
 220         units for the specified sizes (equal to 1024, 1024², … bytes).
 221         Note that size limits are enforced synchronously when journal
 222         files are extended, and no explicit rotation step triggered by
 223         time is needed.</para>
 224
 225         <para><varname>SystemMaxFiles=</varname> and
 226         <varname>RuntimeMaxFiles=</varname> control how many
 227         individual journal files to keep at most. Note that only
 228         archived files are deleted to reduce the number of files until
 229         this limit is reached; active files will stay around. This
 230         means that, in effect, there might still be more journal files
 231         around in total than this limit after a vacuuming operation is
 232         complete. This setting defaults to 100.</para></listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term><varname>MaxFileSec=</varname></term>
 237
 238         <listitem><para>The maximum time to store entries in a single
 239         journal file before rotating to the next one. Normally,
 240         time-based rotation should not be required as size-based
 241         rotation with options such as
 242         <varname>SystemMaxFileSize=</varname> should be sufficient to
 243         ensure that journal files do not grow without bounds. However,
 244         to ensure that not too much data is lost at once when old
 245         journal files are deleted, it might make sense to change this
 246         value from the default of one month. Set to 0 to turn off this
 247         feature. This setting takes time values which may be suffixed
 248         with the units <literal>year</literal>,
 249         <literal>month</literal>, <literal>week</literal>,
 250         <literal>day</literal>, <literal>h</literal> or
 251         <literal>m</literal> to override the default time unit of
 252         seconds.</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><varname>MaxRetentionSec=</varname></term>
 257
 258         <listitem><para>The maximum time to store journal entries.
 259         This controls whether journal files containing entries older
 260         then the specified time span are deleted. Normally, time-based
 261         deletion of old journal files should not be required as
 262         size-based deletion with options such as
 263         <varname>SystemMaxUse=</varname> should be sufficient to
 264         ensure that journal files do not grow without bounds. However,
 265         to enforce data retention policies, it might make sense to
 266         change this value from the default of 0 (which turns off this
 267         feature). This setting also takes time values which may be
 268         suffixed with the units <literal>year</literal>,
 269         <literal>month</literal>, <literal>week</literal>,
 270         <literal>day</literal>, <literal>h</literal> or <literal>
 271         m</literal> to override the default time unit of
 272         seconds.</para></listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><varname>SyncIntervalSec=</varname></term>
 277
 278         <listitem><para>The timeout before synchronizing journal files
 279         to disk. After syncing, journal files are placed in the
 280         OFFLINE state. Note that syncing is unconditionally done
 281         immediately after a log message of priority CRIT, ALERT or
 282         EMERG has been logged. This setting hence applies only to
 283         messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The
 284         default timeout is 5 minutes. </para></listitem>
 285       </varlistentry>
 286
 287       <varlistentry>
 288         <term><varname>ForwardToSyslog=</varname></term>
 289         <term><varname>ForwardToKMsg=</varname></term>
 290         <term><varname>ForwardToConsole=</varname></term>
 291         <term><varname>ForwardToWall=</varname></term>
 292
 293         <listitem><para>Control whether log messages received by the journal daemon shall
 294         be forwarded to a traditional syslog daemon, to the kernel log buffer (kmsg), to
 295         the system console, or sent as wall messages to all logged-in users.  These
 296         options take boolean arguments. If forwarding to syslog is enabled but nothing
 297         reads messages from the socket, forwarding to syslog has no effect. By default,
 298         only forwarding to wall is enabled. These settings may be overridden at boot time
 299         with the kernel command line options
 300         <literal>systemd.journald.forward_to_syslog</literal>,
 301         <literal>systemd.journald.forward_to_kmsg</literal>,
 302         <literal>systemd.journald.forward_to_console</literal>, and
 303         <literal>systemd.journald.forward_to_wall</literal>. If the option name is
 304         specified without <literal>=</literal> and the following argument, true is
 305         assumed. Otherwise, the argument is parsed as a boolean. When forwarding to the
 306         console, the TTY to log to can be changed with <varname>TTYPath=</varname>,
 307         described below.</para></listitem>
 308       </varlistentry>
 309
 310       <varlistentry>
 311         <term><varname>MaxLevelStore=</varname></term>
 312         <term><varname>MaxLevelSyslog=</varname></term>
 313         <term><varname>MaxLevelKMsg=</varname></term>
 314         <term><varname>MaxLevelConsole=</varname></term>
 315         <term><varname>MaxLevelWall=</varname></term>
 316
 317         <listitem><para>Controls the maximum log level of messages
 318         that are stored on disk, forwarded to syslog, kmsg, the
 319         console or wall (if that is enabled, see above). As argument,
 320         takes one of
 321         <literal>emerg</literal>,
 322         <literal>alert</literal>,
 323         <literal>crit</literal>,
 324         <literal>err</literal>,
 325         <literal>warning</literal>,
 326         <literal>notice</literal>,
 327         <literal>info</literal>,
 328         <literal>debug</literal>,
 329         or integer values in the range of 0–7 (corresponding to the
 330         same levels). Messages equal or below the log level specified
 331         are stored/forwarded, messages above are dropped. Defaults to
 332         <literal>debug</literal> for <varname>MaxLevelStore=</varname>
 333         and <varname>MaxLevelSyslog=</varname>, to ensure that the all
 334         messages are written to disk and forwarded to syslog. Defaults
 335         to
 336         <literal>notice</literal> for <varname>MaxLevelKMsg=</varname>,
 337         <literal>info</literal> for <varname>MaxLevelConsole=</varname>,
 338         and <literal>emerg</literal> for
 339         <varname>MaxLevelWall=</varname>. These settings may be
 340         overridden at boot time with the kernel command line options
 341         <literal>systemd.journald.max_level_store=</literal>,
 342         <literal>systemd.journald.max_level_syslog=</literal>,
 343         <literal>systemd.journald.max_level_kmsg=</literal>,
 344         <literal>systemd.journald.max_level_console=</literal>,
 345         <literal>systemd.journald.max_level_wall=</literal>.</para>
 346         </listitem>
 347       </varlistentry>
 348
 349       <varlistentry>
 350         <term><varname>ReadKMsg=</varname></term>
 351
 352         <listitem><para>Takes a boolean value. If enabled (the
 353         default), journal reads <filename>/dev/kmsg</filename>
 354         messages generated by the kernel.</para></listitem>
 355       </varlistentry>
 356
 357       <varlistentry>
 358         <term><varname>TTYPath=</varname></term>
 359
 360         <listitem><para>Change the console TTY to use if
 361         <varname>ForwardToConsole=yes</varname> is used. Defaults to
 362         <filename>/dev/console</filename>.</para></listitem>
 363       </varlistentry>
 364
 365       <varlistentry>
 366         <term><varname>LineMax=</varname></term>
 367
 368         <listitem><para>The maximum line length to permit when converting stream logs into record logs. When a systemd
 369         unit's standard output/error are connected to the journal via a stream socket, the data read is split into
 370         individual log records at newline (<literal>\n</literal>, ASCII 10) and NUL characters. If no such delimiter is
 371         read for the specified number of bytes a hard log record boundary is artificially inserted, breaking up overly
 372         long lines into multiple log records. Selecting overly large values increases the possible memory usage of the
 373         Journal daemon for each stream client, as in the worst case the journal daemon needs to buffer the specified
 374         number of bytes in memory before it can flush a new log record to disk. Also note that permitting overly large
 375         line maximum line lengths affects compatibility with traditional log protocols as log records might not fit
 376         anymore into a single <constant>AF_UNIX</constant> or <constant>AF_INET</constant> datagram. Takes a size in
 377         bytes. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes,
 378         Gigabytes, or Terabytes (with the base 1024), respectively. Defaults to 48K, which is relatively large but
 379         still small enough so that log records likely fit into network datagrams along with extra room for
 380         metadata. Note that values below 79 are not accepted and will be bumped to 79.</para></listitem>
 381       </varlistentry>
 382
 383     </variablelist>
 384
 385   </refsect1>
 386
 387   <refsect1>
 388     <title>Forwarding to traditional syslog daemons</title>
 389
 390     <para>
 391       Journal events can be transferred to a different logging daemon
 392       in two different ways. With the first method, messages are
 393       immediately forwarded to a socket
 394       (<filename>/run/systemd/journal/syslog</filename>), where the
 395       traditional syslog daemon can read them. This method is
 396       controlled by the <varname>ForwardToSyslog=</varname> option. With a
 397       second method, a syslog daemon behaves like a normal journal
 398       client, and reads messages from the journal files, similarly to
 399       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 400       With this, messages do not have to be read immediately,
 401       which allows a logging daemon which is only started late in boot
 402       to access all messages since the start of the system. In
 403       addition, full structured meta-data is available to it. This
 404       method of course is available only if the messages are stored in
 405       a journal file at all. So it will not work if
 406       <varname>Storage=none</varname> is set. It should be noted that
 407       usually the <emphasis>second</emphasis> method is used by syslog
 408       daemons, so the <varname>Storage=</varname> option, and not the
 409       <varname>ForwardToSyslog=</varname> option, is relevant for them.
 410     </para>
 411   </refsect1>
 412
 413   <refsect1>
 414       <title>See Also</title>
 415       <para>
 416         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 417         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 418         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 419         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 420         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 421       </para>
 422   </refsect1>
 423
 424 </refentry>