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