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