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