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
 133         user. One of <literal>uid</literal>, <literal>login</literal>
 134         and <literal>none</literal>. If <literal>uid</literal>, all
 135         users will get each their own journal files regardless of
 136         whether they possess a login session or not, however system
 137         users will log into the system journal. If
 138         <literal>login</literal>, actually logged-in users will get
 139         each their own journal files, but users without login session
 140         and system users will log into the system journal. If
 141         <literal>none</literal>, journal files are not split up by
 142         user and all messages are instead stored in the single system
 143         journal. Note that splitting up journal files by user is only
 144         available for journals stored persistently. If journals are
 145         stored on volatile storage (see above), only a single journal
 146         file for all user IDs is kept. Defaults to
 147         <literal>uid</literal>.</para></listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><varname>RateLimitInterval=</varname></term>
 152         <term><varname>RateLimitBurst=</varname></term>
 153
 154         <listitem><para>Configures the rate limiting that is applied
 155         to all messages generated on the system. If, in the time
 156         interval defined by <varname>RateLimitInterval=</varname>,
 157         more messages than specified in
 158         <varname>RateLimitBurst=</varname> are logged by a service,
 159         all further messages within the interval are dropped until the
 160         interval is over. A message about the number of dropped
 161         messages is generated. This rate limiting is applied
 162         per-service, so that two services which log do not interfere
 163         with each other's limits. Defaults to 1000 messages in 30s.
 164         The time specification for
 165         <varname>RateLimitInterval=</varname> may be specified in the
 166         following units: <literal>s</literal>, <literal>min</literal>,
 167         <literal>h</literal>, <literal>ms</literal>,
 168         <literal>us</literal>. To turn off any kind of rate limiting,
 169         set either value to 0.</para></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><varname>SystemMaxUse=</varname></term>
 174         <term><varname>SystemKeepFree=</varname></term>
 175         <term><varname>SystemMaxFileSize=</varname></term>
 176         <term><varname>RuntimeMaxUse=</varname></term>
 177         <term><varname>RuntimeKeepFree=</varname></term>
 178         <term><varname>RuntimeMaxFileSize=</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.
 201         </para>
 202
 203         <para><varname>SystemMaxUse=</varname> and
 204         <varname>RuntimeMaxUse=</varname> control how much disk space
 205         the journal may use up at maximum.
 206         <varname>SystemKeepFree=</varname> and
 207         <varname>RuntimeKeepFree=</varname> control how much disk
 208         space systemd-journald shall leave free for other uses.
 209         <command>systemd-journald</command> will respect both limits
 210         and use the smaller of the two values.</para>
 211
 212         <para>The first pair defaults to 10% and the second to 15% of
 213         the size of the respective file system. If the file system is
 214         nearly full and either <varname>SystemKeepFree=</varname> or
 215         <varname>RuntimeKeepFree=</varname> is violated when
 216         systemd-journald is started, the value will be raised to
 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 go reduce footprint either.</para>
 222
 223         <para><varname>SystemMaxFileSize=</varname> and
 224         <varname>RuntimeMaxFileSize=</varname> control how large
 225         individual journal files may grow at maximum. This influences
 226         the granularity in which disk space is made available through
 227         rotation, i.e. deletion of historic data. Defaults to one
 228         eighth of the values configured with
 229         <varname>SystemMaxUse=</varname> and
 230         <varname>RuntimeMaxUse=</varname>, so that usually seven
 231         rotated journal files are kept as history.</para></listitem>
 232
 233         <para>Specify values in bytes or use K, M, G, T, P, E as
 234         units for the specified sizes (equal to 1024, 1024²,... bytes).
 235         Note that size limits are enforced synchronously when journal
 236         files are extended, and no explicit rotation step triggered by
 237         time is needed.</para>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><varname>MaxFileSec=</varname></term>
 242
 243         <listitem><para>The maximum time to store entries in a single
 244         journal file before rotating to the next one. Normally,
 245         time-based rotation should not be required as size-based
 246         rotation with options such as
 247         <varname>SystemMaxFileSize=</varname> should be sufficient to
 248         ensure that journal files do not grow without bounds. However,
 249         to ensure that not too much data is lost at once when old
 250         journal files are deleted, it might make sense to change this
 251         value from the default of one month. Set to 0 to turn off this
 252         feature. This setting takes time values which may be suffixed
 253         with the units <literal>year</literal>,
 254         <literal>month</literal>, <literal>week</literal>,
 255         <literal>day</literal>, <literal>h</literal> or
 256         <literal>m</literal> to override the default time unit of
 257         seconds.</para></listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><varname>MaxRetentionSec=</varname></term>
 262
 263         <listitem><para>The maximum time to store journal entries.
 264         This controls whether journal files containing entries older
 265         then the specified time span are deleted. Normally, time-based
 266         deletion of old journal files should not be required as
 267         size-based deletion with options such as
 268         <varname>SystemMaxUse=</varname> should be sufficient to
 269         ensure that journal files do not grow without bounds. However,
 270         to enforce data retention policies, it might make sense to
 271         change this value from the default of 0 (which turns off this
 272         feature). This setting also takes time values which may be
 273         suffixed with the units <literal>year</literal>,
 274         <literal>month</literal>, <literal>week</literal>,
 275         <literal>day</literal>, <literal>h</literal> or <literal>
 276         m</literal> to override the default time unit of
 277         seconds.</para></listitem>
 278       </varlistentry>
 279
 280
 281       <varlistentry>
 282         <term><varname>SyncIntervalSec=</varname></term>
 283
 284         <listitem><para>The timeout before synchronizing journal files
 285         to disk. After syncing, journal files are placed in the
 286         OFFLINE state. Note that syncing is unconditionally done
 287         immediately after a log message of priority CRIT, ALERT or
 288         EMERG has been logged. This setting hence applies only to
 289         messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The
 290         default timeout is 5 minutes. </para></listitem>
 291       </varlistentry>
 292
 293       <varlistentry>
 294         <term><varname>ForwardToSyslog=</varname></term>
 295         <term><varname>ForwardToKMsg=</varname></term>
 296         <term><varname>ForwardToConsole=</varname></term>
 297         <term><varname>ForwardToWall=</varname></term>
 298
 299         <listitem><para>Control whether log messages received by the
 300         journal daemon shall be forwarded to a traditional syslog
 301         daemon, to the kernel log buffer (kmsg), to the system
 302         console, or sent as wall messages to all logged-in users.
 303         These options take boolean arguments. If forwarding to syslog
 304         is enabled but nothing reads messages from the socket,
 305         forwarding to syslog has no effect. By default, only
 306         forwarding to wall is enabled. These settings may be
 307         overridden at boot time with the kernel command line options
 308         <literal>systemd.journald.forward_to_syslog=</literal>,
 309         <literal>systemd.journald.forward_to_kmsg=</literal>,
 310         <literal>systemd.journald.forward_to_console=</literal>, and
 311         <literal>systemd.journald.forward_to_wall=</literal>. When
 312         forwarding to the console, the TTY to log to can be changed
 313         with <varname>TTYPath=</varname>, described
 314         below.</para></listitem>
 315       </varlistentry>
 316
 317       <varlistentry>
 318         <term><varname>MaxLevelStore=</varname></term>
 319         <term><varname>MaxLevelSyslog=</varname></term>
 320         <term><varname>MaxLevelKMsg=</varname></term>
 321         <term><varname>MaxLevelConsole=</varname></term>
 322         <term><varname>MaxLevelWall=</varname></term>
 323
 324         <listitem><para>Controls the maximum log level of messages
 325         that are stored on disk, forwarded to syslog, kmsg, the
 326         console or wall (if that is enabled, see above). As argument,
 327         takes one of
 328         <literal>emerg</literal>,
 329         <literal>alert</literal>,
 330         <literal>crit</literal>,
 331         <literal>err</literal>,
 332         <literal>warning</literal>,
 333         <literal>notice</literal>,
 334         <literal>info</literal>,
 335         <literal>debug</literal>,
 336         or integer values in the range of 0..7 (corresponding to the
 337         same levels). Messages equal or below the log level specified
 338         are stored/forwarded, messages above are dropped. Defaults to
 339         <literal>debug</literal> for <varname>MaxLevelStore=</varname>
 340         and <varname>MaxLevelSyslog=</varname>, to ensure that the all
 341         messages are written to disk and forwarded to syslog. Defaults
 342         to
 343         <literal>notice</literal> for <varname>MaxLevelKMsg=</varname>,
 344         <literal>info</literal> for <varname>MaxLevelConsole=</varname>,
 345         and <literal>emerg</literal> for
 346         <varname>MaxLevelWall=</varname>.</para></listitem>
 347       </varlistentry>
 348
 349       <varlistentry>
 350         <term><varname>TTYPath=</varname></term>
 351
 352         <listitem><para>Change the console TTY to use if
 353         <varname>ForwardToConsole=yes</varname> is used. Defaults to
 354         <filename>/dev/console</filename>.</para></listitem>
 355       </varlistentry>
 356
 357     </variablelist>
 358
 359   </refsect1>
 360
 361   <refsect1>
 362     <title>Forwarding to traditional syslog daemons</title>
 363
 364     <para>
 365       Journal events can be transferred to a different logging daemon
 366       in two different ways. In the first method, messages are
 367       immediately forwarded to a socket
 368       (<filename>/run/systemd/journal/syslog</filename>), where the
 369       traditional syslog daemon can read them. This method is
 370       controlled by <varname>ForwardToSyslog=</varname> option.  In a
 371       second method, a syslog daemon behaves like a normal journal
 372       client, and reads messages from the journal files, similarly to
 373       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 374       In this method, messages do not have to be read immediately,
 375       which allows a logging daemon which is only started late in boot
 376       to access all messages since the start of the system. In
 377       addition, full structured meta-data is available to it. This
 378       method of course is available only if the messages are stored in
 379       a journal file at all. So it will not work if
 380       <varname>Storage=none</varname> is set. It should be noted that
 381       usually the <emphasis>second</emphasis> method is used by syslog
 382       daemons, so the <varname>Storage=</varname> option, and not the
 383       <varname>ForwardToSyslog=</varname> option, is relevant for them.
 384     </para>
 385   </refsect1>
 386
 387   <refsect1>
 388       <title>See Also</title>
 389       <para>
 390         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 391         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 392         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 393         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 394         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 395       </para>
 396   </refsect1>
 397
 398 </refentry>