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