man/journald.conf.xml

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