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 (with UID outside the range of system users, dynamic service users,
 114         and the nobody user) will each get their own journal files, and system users will log to the system journal.
 115         See <ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink>
 116         for more details about UID ranges.
 117         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>Note that the effective rate limit is multiplied with a
 146         factor derived from the available free disk space for the journal.
 147         Currently, this factor is calculated using the base 2 logarithm.</para>
 148
 149         <table>
 150           <title>Example <varname>RateLimitBurst=</varname> rate
 151             modifications by the available disk space</title>
 152           <tgroup cols='2'>
 153             <colspec colname='freespace' />
 154             <colspec colname='multiplier' />
 155             <thead>
 156               <row>
 157                 <entry>Available Disk Space</entry>
 158                 <entry>Burst Multiplier</entry>
 159               </row>
 160             </thead>
 161             <tbody>
 162               <row>
 163                 <entry>&lt;= 1MB</entry>
 164                 <entry>1</entry>
 165               </row>
 166               <row>
 167                 <entry>&lt;= 16MB</entry>
 168                 <entry>2</entry>
 169               </row>
 170               <row>
 171                 <entry>&lt;= 256MB</entry>
 172                 <entry>3</entry>
 173               </row>
 174               <row>
 175                 <entry>&lt;= 4GB</entry>
 176                 <entry>4</entry>
 177               </row>
 178               <row>
 179                 <entry>&lt;= 64GB</entry>
 180                 <entry>5</entry>
 181               </row>
 182               <row>
 183                 <entry>&lt;= 1TB</entry>
 184                 <entry>6</entry>
 185               </row>
 186             </tbody>
 187           </tgroup>
 188         </table>
 189
 190         <para>If a service provides rate limits for itself through
 191         <varname>LogRateLimitIntervalSec=</varname> and/or <varname>LogRateLimitBurst=</varname>
 192         in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 193         those values will override the settings specified here.</para>
 194         </listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term><varname>SystemMaxUse=</varname></term>
 199         <term><varname>SystemKeepFree=</varname></term>
 200         <term><varname>SystemMaxFileSize=</varname></term>
 201         <term><varname>SystemMaxFiles=</varname></term>
 202         <term><varname>RuntimeMaxUse=</varname></term>
 203         <term><varname>RuntimeKeepFree=</varname></term>
 204         <term><varname>RuntimeMaxFileSize=</varname></term>
 205         <term><varname>RuntimeMaxFiles=</varname></term>
 206
 207         <listitem><para>Enforce size limits on the journal files
 208         stored. The options prefixed with <literal>System</literal>
 209         apply to the journal files when stored on a persistent file
 210         system, more specifically
 211         <filename>/var/log/journal</filename>. The options prefixed
 212         with <literal>Runtime</literal> apply to the journal files
 213         when stored on a volatile in-memory file system, more
 214         specifically <filename>/run/log/journal</filename>. The former
 215         is used only when <filename>/var</filename> is mounted,
 216         writable, and the directory
 217         <filename>/var/log/journal</filename> exists. Otherwise, only
 218         the latter applies. Note that this means that during early
 219         boot and if the administrator disabled persistent logging,
 220         only the latter options apply, while the former apply if
 221         persistent logging is enabled and the system is fully booted
 222         up. <command>journalctl</command> and
 223         <command>systemd-journald</command> ignore all files with
 224         names not ending with <literal>.journal</literal> or
 225         <literal>.journal~</literal>, so only such files, located in
 226         the appropriate directories, are taken into account when
 227         calculating current disk usage.</para>
 228
 229         <para><varname>SystemMaxUse=</varname> and
 230         <varname>RuntimeMaxUse=</varname> control how much disk space
 231         the journal may use up at most.
 232         <varname>SystemKeepFree=</varname> and
 233         <varname>RuntimeKeepFree=</varname> control how much disk
 234         space systemd-journald shall leave free for other uses.
 235         <command>systemd-journald</command> will respect both limits
 236         and use the smaller of the two values.</para>
 237
 238         <para>The first pair defaults to 10% and the second to 15% of
 239         the size of the respective file system, but each value is
 240         capped to 4G. If the file system is nearly full and either
 241         <varname>SystemKeepFree=</varname> or
 242         <varname>RuntimeKeepFree=</varname> are violated when
 243         systemd-journald is started, the limit will be raised to the
 244         percentage that is actually free. This means that if there was
 245         enough free space before and journal files were created, and
 246         subsequently something else causes the file system to fill up,
 247         journald will stop using more space, but it will not be
 248         removing existing files to reduce the footprint again,
 249         either. Also note that only archived files are deleted to reduce the
 250         space occupied by journal files. This means that, in effect, there might
 251         still be more space used than <varname>SystemMaxUse=</varname> or
 252         <varname>RuntimeMaxUse=</varname> limit after a vacuuming operation is
 253         complete.</para>
 254
 255         <para><varname>SystemMaxFileSize=</varname> and
 256         <varname>RuntimeMaxFileSize=</varname> control how large
 257         individual journal files may grow at most. This influences
 258         the granularity in which disk space is made available through
 259         rotation, i.e. deletion of historic data. Defaults to one
 260         eighth of the values configured with
 261         <varname>SystemMaxUse=</varname> and
 262         <varname>RuntimeMaxUse=</varname>, so that usually seven
 263         rotated journal files are kept as history.</para>
 264
 265         <para>Specify values in bytes or use K, M, G, T, P, E as
 266         units for the specified sizes (equal to 1024, 1024², … bytes).
 267         Note that size limits are enforced synchronously when journal
 268         files are extended, and no explicit rotation step triggered by
 269         time is needed.</para>
 270
 271         <para><varname>SystemMaxFiles=</varname> and
 272         <varname>RuntimeMaxFiles=</varname> control how many
 273         individual journal files to keep at most. Note that only
 274         archived files are deleted to reduce the number of files until
 275         this limit is reached; active files will stay around. This
 276         means that, in effect, there might still be more journal files
 277         around in total than this limit after a vacuuming operation is
 278         complete. This setting defaults to 100.</para></listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term><varname>MaxFileSec=</varname></term>
 283
 284         <listitem><para>The maximum time to store entries in a single
 285         journal file before rotating to the next one. Normally,
 286         time-based rotation should not be required as size-based
 287         rotation with options such as
 288         <varname>SystemMaxFileSize=</varname> should be sufficient to
 289         ensure that journal files do not grow without bounds. However,
 290         to ensure that not too much data is lost at once when old
 291         journal files are deleted, it might make sense to change this
 292         value from the default of one month. Set to 0 to turn off this
 293         feature. This setting takes time values which may be suffixed
 294         with the units <literal>year</literal>,
 295         <literal>month</literal>, <literal>week</literal>,
 296         <literal>day</literal>, <literal>h</literal> or
 297         <literal>m</literal> to override the default time unit of
 298         seconds.</para></listitem>
 299       </varlistentry>
 300
 301       <varlistentry>
 302         <term><varname>MaxRetentionSec=</varname></term>
 303
 304         <listitem><para>The maximum time to store journal entries.
 305         This controls whether journal files containing entries older
 306         than the specified time span are deleted. Normally, time-based
 307         deletion of old journal files should not be required as
 308         size-based deletion with options such as
 309         <varname>SystemMaxUse=</varname> should be sufficient to
 310         ensure that journal files do not grow without bounds. However,
 311         to enforce data retention policies, it might make sense to
 312         change this value from the default of 0 (which turns off this
 313         feature). This setting also takes time values which may be
 314         suffixed with the units <literal>year</literal>,
 315         <literal>month</literal>, <literal>week</literal>,
 316         <literal>day</literal>, <literal>h</literal> or <literal>
 317         m</literal> to override the default time unit of
 318         seconds.</para></listitem>
 319       </varlistentry>
 320
 321       <varlistentry>
 322         <term><varname>SyncIntervalSec=</varname></term>
 323
 324         <listitem><para>The timeout before synchronizing journal files
 325         to disk. After syncing, journal files are placed in the
 326         OFFLINE state. Note that syncing is unconditionally done
 327         immediately after a log message of priority CRIT, ALERT or
 328         EMERG has been logged. This setting hence applies only to
 329         messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The
 330         default timeout is 5 minutes. </para></listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><varname>ForwardToSyslog=</varname></term>
 335         <term><varname>ForwardToKMsg=</varname></term>
 336         <term><varname>ForwardToConsole=</varname></term>
 337         <term><varname>ForwardToWall=</varname></term>
 338
 339         <listitem><para>Control whether log messages received by the journal daemon shall be forwarded to a
 340         traditional syslog daemon, to the kernel log buffer (kmsg), to the system console, or sent as wall
 341         messages to all logged-in users.  These options take boolean arguments. If forwarding to syslog is
 342         enabled but nothing reads messages from the socket, forwarding to syslog has no effect. By default,
 343         only forwarding to wall is enabled. These settings may be overridden at boot time with the kernel
 344         command line options <literal>systemd.journald.forward_to_syslog</literal>,
 345         <literal>systemd.journald.forward_to_kmsg</literal>,
 346         <literal>systemd.journald.forward_to_console</literal>, and
 347         <literal>systemd.journald.forward_to_wall</literal>. If the option name is specified without
 348         <literal>=</literal> and the following argument, true is assumed. Otherwise, the argument is parsed
 349         as a boolean.</para>
 350
 351         <para>When forwarding to the console, the TTY to log to can be changed with
 352         <varname>TTYPath=</varname>, described below.</para>
 353
 354         <para>When forwarding to the kernel log buffer (kmsg), make sure to select a suitably large size for
 355         the log buffer, and ensure the kernel's rate-limiting applied to userspace processes is turned
 356         off. Specifically, add <literal>log_buf_len=8M</literal> and <literal>printk.devkmsg=on</literal> (or
 357         similar) to the kernel command line.</para></listitem>
 358       </varlistentry>
 359
 360       <varlistentry>
 361         <term><varname>MaxLevelStore=</varname></term>
 362         <term><varname>MaxLevelSyslog=</varname></term>
 363         <term><varname>MaxLevelKMsg=</varname></term>
 364         <term><varname>MaxLevelConsole=</varname></term>
 365         <term><varname>MaxLevelWall=</varname></term>
 366
 367         <listitem><para>Controls the maximum log level of messages
 368         that are stored in the journal, forwarded to syslog, kmsg, the
 369         console or wall (if that is enabled, see above). As argument,
 370         takes one of
 371         <literal>emerg</literal>,
 372         <literal>alert</literal>,
 373         <literal>crit</literal>,
 374         <literal>err</literal>,
 375         <literal>warning</literal>,
 376         <literal>notice</literal>,
 377         <literal>info</literal>,
 378         <literal>debug</literal>,
 379         or integer values in the range of 0–7 (corresponding to the
 380         same levels). Messages equal or below the log level specified
 381         are stored/forwarded, messages above are dropped. Defaults to
 382         <literal>debug</literal> for <varname>MaxLevelStore=</varname>
 383         and <varname>MaxLevelSyslog=</varname>, to ensure that the all
 384         messages are stored in the journal and forwarded to syslog.
 385         Defaults to
 386         <literal>notice</literal> for <varname>MaxLevelKMsg=</varname>,
 387         <literal>info</literal> for <varname>MaxLevelConsole=</varname>,
 388         and <literal>emerg</literal> for
 389         <varname>MaxLevelWall=</varname>. These settings may be
 390         overridden at boot time with the kernel command line options
 391         <literal>systemd.journald.max_level_store=</literal>,
 392         <literal>systemd.journald.max_level_syslog=</literal>,
 393         <literal>systemd.journald.max_level_kmsg=</literal>,
 394         <literal>systemd.journald.max_level_console=</literal>,
 395         <literal>systemd.journald.max_level_wall=</literal>.</para>
 396         </listitem>
 397       </varlistentry>
 398
 399       <varlistentry>
 400         <term><varname>ReadKMsg=</varname></term>
 401
 402         <listitem><para>Takes a boolean value. If enabled (the
 403         default), journal reads <filename>/dev/kmsg</filename>
 404         messages generated by the kernel.</para></listitem>
 405       </varlistentry>
 406
 407       <varlistentry>
 408         <term><varname>TTYPath=</varname></term>
 409
 410         <listitem><para>Change the console TTY to use if
 411         <varname>ForwardToConsole=yes</varname> is used. Defaults to
 412         <filename>/dev/console</filename>.</para></listitem>
 413       </varlistentry>
 414
 415       <varlistentry>
 416         <term><varname>LineMax=</varname></term>
 417
 418         <listitem><para>The maximum line length to permit when converting stream logs into record logs. When a systemd
 419         unit's standard output/error are connected to the journal via a stream socket, the data read is split into
 420         individual log records at newline (<literal>\n</literal>, ASCII 10) and NUL characters. If no such delimiter is
 421         read for the specified number of bytes a hard log record boundary is artificially inserted, breaking up overly
 422         long lines into multiple log records. Selecting overly large values increases the possible memory usage of the
 423         Journal daemon for each stream client, as in the worst case the journal daemon needs to buffer the specified
 424         number of bytes in memory before it can flush a new log record to disk. Also note that permitting overly large
 425         line maximum line lengths affects compatibility with traditional log protocols as log records might not fit
 426         anymore into a single <constant>AF_UNIX</constant> or <constant>AF_INET</constant> datagram. Takes a size in
 427         bytes. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes,
 428         Gigabytes, or Terabytes (with the base 1024), respectively. Defaults to 48K, which is relatively large but
 429         still small enough so that log records likely fit into network datagrams along with extra room for
 430         metadata. Note that values below 79 are not accepted and will be bumped to 79.</para></listitem>
 431       </varlistentry>
 432
 433     </variablelist>
 434
 435   </refsect1>
 436
 437   <refsect1>
 438     <title>Forwarding to traditional syslog daemons</title>
 439
 440     <para>
 441       Journal events can be transferred to a different logging daemon
 442       in two different ways. With the first method, messages are
 443       immediately forwarded to a socket
 444       (<filename>/run/systemd/journal/syslog</filename>), where the
 445       traditional syslog daemon can read them. This method is
 446       controlled by the <varname>ForwardToSyslog=</varname> option. With a
 447       second method, a syslog daemon behaves like a normal journal
 448       client, and reads messages from the journal files, similarly to
 449       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 450       With this, messages do not have to be read immediately,
 451       which allows a logging daemon which is only started late in boot
 452       to access all messages since the start of the system. In
 453       addition, full structured meta-data is available to it. This
 454       method of course is available only if the messages are stored in
 455       a journal file at all. So it will not work if
 456       <varname>Storage=none</varname> is set. It should be noted that
 457       usually the <emphasis>second</emphasis> method is used by syslog
 458       daemons, so the <varname>Storage=</varname> option, and not the
 459       <varname>ForwardToSyslog=</varname> option, is relevant for them.
 460     </para>
 461   </refsect1>
 462
 463   <refsect1>
 464       <title>See Also</title>
 465       <para>
 466         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 467         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 468         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 469         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 470         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 471       </para>
 472   </refsect1>
 473
 474 </refentry>