man/systemd-journald.service.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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-journald.service"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-journald.service</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-journald.service</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-journald.service</refname>
  21     <refname>systemd-journald.socket</refname>
  22     <refname>systemd-journald-dev-log.socket</refname>
  23     <refname>systemd-journald-audit.socket</refname>
  24     <refname>systemd-journald@.service</refname>
  25     <refname>systemd-journald@.socket</refname>
  26     <refname>systemd-journald-varlink@.socket</refname>
  27     <refname>systemd-journald</refname>
  28     <refpurpose>Journal service</refpurpose>
  29   </refnamediv>
  30
  31   <refsynopsisdiv>
  32     <para><simplelist>
  33       <member><filename>systemd-journald.service</filename></member>
  34       <member><filename>systemd-journald.socket</filename></member>
  35       <member><filename>systemd-journald-dev-log.socket</filename></member>
  36       <member><filename>systemd-journald-audit.socket</filename></member>
  37       <member><filename>systemd-journald@.service</filename></member>
  38       <member><filename>systemd-journald@.socket</filename></member>
  39       <member><filename>systemd-journald-varlink@.socket</filename></member>
  40       <member><filename>/usr/lib/systemd/systemd-journald</filename></member>
  41     </simplelist></para>
  42   </refsynopsisdiv>
  43
  44   <refsect1>
  45     <title>Description</title>
  46
  47     <para><filename>systemd-journald</filename> is a system service
  48     that collects and stores logging data. It creates and maintains
  49     structured, indexed journals based on logging information that is
  50     received from a variety of sources:</para>
  51
  52     <itemizedlist>
  53       <listitem><para>Kernel log messages, via kmsg</para></listitem>
  54
  55       <listitem><para>Simple system log messages, via the <filename>libc</filename> <citerefentry
  56       project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  57       call</para></listitem>
  58
  59       <listitem><para>Structured system log messages via the native Journal API, see
  60       <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  61       and <ulink url="https://systemd.io/JOURNAL_NATIVE_PROTOCOL">Native Journal
  62       Protocol</ulink></para></listitem>
  63
  64       <listitem><para>Standard output and standard error of service units. For further details see
  65       below.</para></listitem>
  66
  67       <listitem><para>Audit records, originating from the kernel audit subsystem</para></listitem>
  68     </itemizedlist>
  69
  70     <para>The daemon will implicitly collect numerous metadata fields
  71     for each log messages in a secure and unfakeable way. See
  72     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  73     for more information about the collected metadata.
  74     </para>
  75
  76     <para>Log data collected by the journal is primarily text-based but can also include binary data where
  77     necessary. Individual fields making up a log record stored in the journal may be up to 2⁶⁴-1 bytes in size.</para>
  78
  79     <para>The journal service stores log data either persistently below <filename>/var/log/journal</filename> or in a
  80     volatile way below <filename>/run/log/journal/</filename> (in the latter case it is lost at reboot). By default, log
  81     data is stored persistently if <filename>/var/log/journal/</filename> exists during boot, with an implicit fallback
  82     to volatile storage otherwise. Use <varname>Storage=</varname> in
  83     <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> to configure
  84     where log data is placed, independently of the existence of <filename>/var/log/journal/</filename>.</para>
  85
  86     <para>Note that journald will initially use volatile storage, until a call to
  87     <command>journalctl --flush</command> (or sending <constant>SIGUSR1</constant> to journald) will cause
  88     it to switch to persistent logging (under the conditions mentioned above). This is done automatically
  89     on boot via <literal>systemd-journal-flush.service</literal>.</para>
  90
  91     <para>On systems where <filename>/var/log/journal/</filename> does not exist yet but where persistent logging is
  92     desired (and the default <filename>journald.conf</filename> is used), it is sufficient to create the directory, and
  93     ensure it has the correct access modes and ownership:</para>
  94
  95     <programlisting>mkdir -p /var/log/journal
  96 systemd-tmpfiles --create --prefix /var/log/journal</programlisting>
  97
  98     <para>See
  99     <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 100     for information about the configuration of this service.</para>
 101   </refsect1>
 102
 103   <refsect1>
 104     <title>Stream logging</title>
 105
 106     <para>The systemd service manager invokes all service processes with standard output and standard error connected
 107     to the journal by default. This behaviour may be altered via the
 108     <varname>StandardOutput=</varname>/<varname>StandardError=</varname> unit file settings, see
 109     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The
 110     journal converts the log byte stream received this way into individual log records, splitting the stream at newline
 111     (<literal>\n</literal>, ASCII <constant>10</constant>) and <constant>NUL</constant> bytes.</para>
 112
 113     <para>If <filename>systemd-journald.service</filename> is stopped, the stream connections associated with all
 114     services are terminated. Further writes to those streams by the service will result in <constant>EPIPE</constant>
 115     errors. In order to react gracefully in this case it is recommended that programs logging to standard output/error
 116     ignore such errors. If the <constant>SIGPIPE</constant> UNIX signal handler is not blocked or turned off, such
 117     write attempts will also result in such process signals being generated, see
 118     <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 119     To mitigate this issue, systemd service manager explicitly turns off the <constant>SIGPIPE</constant>
 120     signal for all invoked processes by default (this may be changed for each unit individually via the
 121     <varname>IgnoreSIGPIPE=</varname> option, see
 122     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 123     details). After the standard output/standard error streams have been terminated they may not be recovered
 124     until the services they are associated with are restarted. Note that during normal operation,
 125     <filename>systemd-journald.service</filename> stores copies of the file descriptors for those streams in
 126     the service manager. If <filename>systemd-journald.service</filename> is restarted using
 127     <command>systemctl restart</command> or equivalent operation instead of a pair of separate
 128     <command>systemctl stop</command> and <command>systemctl start</command> commands (or equivalent
 129     operations), these stream connections are not terminated and survive the restart. It is thus safe to
 130     restart <filename>systemd-journald.service</filename>, but stopping it is not recommended.</para>
 131
 132     <para>Note that the log record metadata for records transferred via such standard output/error streams reflect the
 133     metadata of the peer the stream was originally created for. If the stream connection is passed on to other
 134     processes (such as further child processes forked off the main service process), the log records will not reflect
 135     their metadata, but will continue to describe the original process. This is different from the other logging
 136     transports listed above, which are inherently record based and where the metadata is always associated with the
 137     individual record.</para>
 138
 139     <para>In addition to the implicit standard output/error logging of services, stream logging is also available
 140     via the <citerefentry><refentrytitle>systemd-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> command
 141     line tool.</para>
 142
 143     <para>Currently, the number of parallel log streams <filename>systemd-journald</filename> will accept is limited to
 144     4096. When this limit is reached further log streams may be established but will receive
 145     <constant>EPIPE</constant> right from the beginning.</para>
 146   </refsect1>
 147
 148   <refsect1>
 149     <title>Journal Namespaces</title>
 150
 151     <para>Journal 'namespaces' are both a mechanism for logically isolating the log stream of projects
 152     consisting of one or more services from the rest of the system and a mechanism for improving
 153     performance. Multiple journal namespaces may exist simultaneously, each defining its own, independent log
 154     stream managed by its own instance of <command>systemd-journald</command>. Namespaces are independent of
 155     each other, both in the data store and in the IPC interface. By default only a single 'default' namespace
 156     exists, managed by <filename>systemd-journald.service</filename> (and its associated socket
 157     units). Additional namespaces are created by starting an instance of the
 158     <filename>systemd-journald@.service</filename> service template. The instance name is the namespace
 159     identifier, which is a short string used for referencing the journal namespace. Service units may be
 160     assigned to a specific journal namespace through the <varname>LogNamespace=</varname> unit file setting,
 161     see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 162     details. The <option>--namespace=</option> switch of
 163     <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> may be
 164     used to view the log stream of a specific namespace. If the switch is not used the log stream of the
 165     default namespace is shown, i.e. log data from other namespaces is not visible.</para>
 166
 167     <para>Services associated with a specific log namespace may log via syslog, the native logging protocol
 168     of the journal and via stdout/stderr; the logging from all three transports is associated with the
 169     namespace.</para>
 170
 171     <para>By default only the default namespace will collect kernel and audit log messages.</para>
 172
 173     <para>The <command>systemd-journald</command> instance of the default namespace is configured through
 174     <filename>/etc/systemd/journald.conf</filename> (see below), while the other instances are configured
 175     through <filename>/etc/systemd/journald@<replaceable>NAMESPACE</replaceable>.conf</filename>. The journal
 176     log data for the default namespace is placed in
 177     <filename>/var/log/journal/<replaceable>MACHINE_ID</replaceable></filename> (see below) while the data
 178     for the other namespaces is located in
 179     <filename>/var/log/journal/<replaceable>MACHINE_ID</replaceable>.<replaceable>NAMESPACE</replaceable></filename>.</para>
 180   </refsect1>
 181
 182   <refsect1>
 183     <title>Signals</title>
 184
 185     <variablelist>
 186       <varlistentry>
 187         <term>SIGUSR1</term>
 188
 189         <listitem><para>Request that journal data from <filename>/run/</filename> is flushed to
 190         <filename>/var/</filename> in order to make it persistent (if this is enabled). This must be used
 191         after <filename>/var/</filename> is mounted, as otherwise log data from <filename>/run/</filename> is
 192         never flushed to <filename>/var/</filename> regardless of the configuration. Use the
 193         <command>journalctl --flush</command> command to request flushing of the journal files, and wait for
 194         the operation to complete. See
 195         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 196         details.</para>
 197
 198         <xi:include href="version-info.xml" xpointer="v186"/></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term>SIGUSR2</term>
 203
 204         <listitem><para>Request immediate rotation of the journal files. Use the <command>journalctl
 205         --rotate</command> command to request journal file rotation, and wait for the operation to
 206         complete.</para>
 207
 208         <xi:include href="version-info.xml" xpointer="v186"/></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term>SIGRTMIN+1</term>
 213
 214         <listitem><para>Request that all unwritten log data is written to disk. Use the <command>journalctl
 215         --sync</command> command to trigger journal synchronization, and wait for the operation to
 216         complete.</para>
 217
 218         <xi:include href="version-info.xml" xpointer="v228"/></listitem>
 219       </varlistentry>
 220     </variablelist>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>Credentials</title>
 225
 226     <para><command>systemd-journald</command> supports the service credentials logic as implemented by
 227     <varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname>
 228     (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 229     details). The following credentials are used when passed in:</para>
 230
 231     <variablelist class='system-credentials'>
 232       <varlistentry>
 233         <term><varname>journal.forward_to_socket</varname></term>
 234
 235         <listitem><para>May contain a socket address to which logs should be forwarded. See
 236         <varname>ForwardToSocket=</varname> in
 237         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 238
 239         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 240       </varlistentry>
 241
 242       <varlistentry>
 243         <term><varname>journal.storage</varname></term>
 244
 245         <listitem><para>May be used to specify where journal files should be stored. See
 246         <varname>Storage=</varname> in
 247         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 248
 249         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 250       </varlistentry>
 251     </variablelist>
 252   </refsect1>
 253
 254   <refsect1>
 255     <title>Kernel Command Line</title>
 256
 257     <para>A few configuration parameters from
 258     <filename>journald.conf</filename> may be overridden on the kernel
 259     command line:</para>
 260
 261     <variablelist class='kernel-commandline-options'>
 262       <varlistentry>
 263         <term><varname>systemd.journald.forward_to_syslog=</varname></term>
 264         <term><varname>systemd.journald.forward_to_kmsg=</varname></term>
 265         <term><varname>systemd.journald.forward_to_console=</varname></term>
 266         <term><varname>systemd.journald.forward_to_wall=</varname></term>
 267
 268         <listitem><para>Enables/disables forwarding of collected log
 269         messages to syslog, the kernel log buffer, the system console
 270         or wall.
 271         </para>
 272
 273         <para>See
 274         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 275         for information about these settings.</para>
 276
 277         <xi:include href="version-info.xml" xpointer="v186"/>
 278         </listitem>
 279
 280       </varlistentry>
 281
 282       <varlistentry>
 283         <term><varname>systemd.journald.max_level_store=</varname></term>
 284         <term><varname>systemd.journald.max_level_syslog=</varname></term>
 285         <term><varname>systemd.journald.max_level_kmsg=</varname></term>
 286         <term><varname>systemd.journald.max_level_console=</varname></term>
 287         <term><varname>systemd.journald.max_level_wall=</varname></term>
 288         <term><varname>systemd.journald.max_level_socket=</varname></term>
 289
 290         <listitem><para>Controls the maximum log level of messages that are stored in the journal, forwarded
 291         to syslog, kmsg, the console, the wall, or a socket. This kernel command line options override the
 292         settings of the same names in the
 293         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 294         file.</para>
 295
 296         <xi:include href="version-info.xml" xpointer="v232"/>
 297         </listitem>
 298       </varlistentry>
 299     </variablelist>
 300
 301     <para>Note that these kernel command line options are only honoured by the default namespace, see
 302     above.</para>
 303   </refsect1>
 304
 305   <refsect1>
 306     <title>Access Control</title>
 307
 308     <para>Journal files are, by default, owned and readable by the
 309     <literal>systemd-journal</literal> system group but are not
 310     writable. Adding a user to this group thus enables them to read
 311     the journal files.</para>
 312
 313     <para>By default, each user, with a UID outside the range of system users,
 314     dynamic service users, and the nobody user, will get their own set of
 315     journal files in <filename>/var/log/journal/</filename>. See
 316     <ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink>
 317     for more details about UID ranges. These journal
 318     files will not be owned by the user, however, in order to avoid
 319     that the user can write to them directly. Instead, file system
 320     ACLs are used to ensure the user gets read access only.</para>
 321
 322     <para>Additional users and groups may be granted access to journal
 323     files via file system access control lists (ACL). Distributions
 324     and administrators may choose to grant read access to all members
 325     of the <literal>wheel</literal> and <literal>adm</literal> system
 326     groups with a command such as the following:</para>
 327
 328     <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/</programlisting>
 329
 330     <para>Note that this command will update the ACLs both for
 331     existing journal files and for future journal files created in the
 332     <filename>/var/log/journal/</filename> directory.</para>
 333   </refsect1>
 334
 335   <refsect1>
 336     <title>Files</title>
 337
 338     <variablelist>
 339       <varlistentry>
 340         <term><filename>/etc/systemd/journald.conf</filename></term>
 341
 342         <listitem><para>Configure <command>systemd-journald</command> behavior. See
 343         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 344         </para>
 345
 346         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 347       </varlistentry>
 348
 349       <varlistentry>
 350         <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term>
 351         <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term>
 352         <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term>
 353         <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term>
 354
 355         <listitem><para><command>systemd-journald</command> writes entries to files in
 356         <filename>/run/log/journal/<replaceable>machine-id</replaceable>/</filename>
 357         or
 358         <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
 359         with the <literal>.journal</literal> suffix. If the daemon is
 360         stopped uncleanly, or if the files are found to be corrupted,
 361         they are renamed using the <literal>.journal~</literal>
 362         suffix, and <command>systemd-journald</command> starts writing
 363         to a new file. <filename>/run/</filename> is used when
 364         <filename>/var/log/journal</filename> is not available, or
 365         when <option>Storage=volatile</option> is set in the
 366         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 367         configuration file.</para>
 368
 369         <para>When <filename>systemd-journald</filename> ceases writing to a journal file,
 370         it will be renamed to <literal><replaceable>original-name</replaceable>@<replaceable>suffix.journal</replaceable></literal>
 371         (or <literal><replaceable>original-name</replaceable>@<replaceable>suffix.journal~</replaceable></literal>).
 372         Such files are "archived" and will not be written to any more.</para>
 373
 374         <para>In general, it is safe to read or copy any journal file (active or archived).
 375         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 376         and the functions in the
 377         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 378         library should be able to read all entries that have been fully written.</para>
 379
 380         <para><filename>systemd-journald</filename> will automatically remove the oldest
 381         archived journal files to limit disk use. See <varname>SystemMaxUse=</varname>
 382         and related settings in
 383         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 384         </para>
 385
 386         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 387       </varlistentry>
 388
 389       <varlistentry>
 390         <term><filename>/dev/kmsg</filename></term>
 391         <term><filename>/dev/log</filename></term>
 392         <term><filename>/run/systemd/journal/dev-log</filename></term>
 393         <term><filename>/run/systemd/journal/socket</filename></term>
 394         <term><filename>/run/systemd/journal/stdout</filename></term>
 395
 396         <listitem><para>Sockets and other file node paths that <command>systemd-journald</command> will
 397         listen on and are visible in the file system. In addition to these,
 398         <command>systemd-journald</command> can listen for audit events using <citerefentry
 399         project='man-pages'><refentrytitle>netlink</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 400         depending on whether <literal>systemd-journald-audit.socket</literal> is enabled or
 401         not.</para>
 402
 403         <xi:include href="version-info.xml" xpointer="v228"/></listitem>
 404       </varlistentry>
 405     </variablelist>
 406
 407     <para>If journal namespacing is used these paths are slightly altered to include a namespace identifier, see above.</para>
 408   </refsect1>
 409
 410   <refsect1>
 411     <title>See Also</title>
 412     <para><simplelist type="inline">
 413       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 414       <member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 415       <member><citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 416       <member><citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 417       <member><citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 418       <member><citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 419       <member><citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 420       <member><citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 421       <member><command>pydoc systemd.journal</command></member>
 422     </simplelist></para>
 423   </refsect1>
 424
 425 </refentry>