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">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2010 Lennart Poettering
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.
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.
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/>.
26 <refentry id=
"systemd-journald.service">
29 <title>systemd-journald.service
</title>
30 <productname>systemd
</productname>
34 <contrib>Developer
</contrib>
35 <firstname>Lennart
</firstname>
36 <surname>Poettering
</surname>
37 <email>lennart@poettering.net
</email>
43 <refentrytitle>systemd-journald.service
</refentrytitle>
44 <manvolnum>8</manvolnum>
48 <refname>systemd-journald.service
</refname>
49 <refname>systemd-journald.socket
</refname>
50 <refname>systemd-journald-dev-log.socket
</refname>
51 <refname>systemd-journald-audit.socket
</refname>
52 <refname>systemd-journald
</refname>
53 <refpurpose>Journal service
</refpurpose>
57 <para><filename>systemd-journald.service
</filename></para>
58 <para><filename>systemd-journald.socket
</filename></para>
59 <para><filename>systemd-journald-dev-log.socket
</filename></para>
60 <para><filename>systemd-journald-audit.socket
</filename></para>
61 <para><filename>/usr/lib/systemd/systemd-journald
</filename></para>
65 <title>Description
</title>
67 <para><filename>systemd-journald
</filename> is a system service
68 that collects and stores logging data. It creates and maintains
69 structured, indexed journals based on logging information that is
70 received from a variety of sources:
</para>
73 <listitem><para>Kernel log messages, via kmsg
</para></listitem>
75 <listitem><para>Simple system log messages, via the
<filename>libc
</filename> <citerefentry
76 project='man-pages'
><refentrytitle>syslog
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
77 call
</para></listitem>
79 <listitem><para>Structured system log messages via the native
81 <citerefentry><refentrytitle>sd_journal_print
</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem>
83 <listitem><para>Standard output and standard error of service units. For further details see
84 below.
</para></listitem>
86 <listitem><para>Audit records, originating from the kernel audit subsystem
</para></listitem>
89 <para>The daemon will implicitly collect numerous metadata fields
90 for each log messages in a secure and unfakeable way. See
91 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
92 for more information about the collected metadata.
95 <para>Log data collected by the journal is primarily text-based but can also include binary data where
96 necessary. Individual fields making up a log record stored in the journal may be up to
2^
64-
1 bytes in size.
</para>
98 <para>The journal service stores log data either persistently below
<filename>/var/log/journal
</filename> or in a
99 volatile way below
<filename>/run/log/journal/
</filename> (in the latter case it is lost at reboot). By default, log
100 data is stored persistently if
<filename>/var/log/journal/
</filename> exists during boot, with an implicit fallback
101 to volatile storage otherwise. Use
<varname>Storage=
</varname> in
102 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry> to configure
103 where log data is placed, independently of the existence of
<filename>/var/log/journal/
</filename>.
</para>
105 <para>On systems where
<filename>/var/log/journal/
</filename> does not exist yet but where persistent logging is
106 desired (and the default
<filename>journald.conf
</filename> is used), it is sufficient to create the directory, and
107 ensure it has the correct access modes and ownership:
</para>
109 <programlisting>mkdir -p /var/log/journal
110 systemd-tmpfiles --create --prefix /var/log/journal
</programlisting>
113 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
114 for information about the configuration of this service.
</para>
118 <title>Stream logging
</title>
120 <para>The systemd service manager invokes all service processes with standard output and standard error connected
121 to the journal by default. This behaviour may be altered via the
122 <varname>StandardOutput=
</varname>/
<varname>StandardError=
</varname> unit file settings, see
123 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The
124 journal converts the log byte stream received this way into individual log records, splitting the stream at newline
125 (
<literal>\n
</literal>, ASCII
<constant>10</constant>) and
<constant>NUL
</constant> bytes.
</para>
127 <para>If
<filename>systemd-journald.service
</filename> is stopped, the stream connections associated with all
128 services are terminated. Further writes to those streams by the service will result in
<constant>EPIPE
</constant>
129 errors. In order to react gracefully in this case it is recommended that programs logging to standard output/error
130 ignore such errors. If the
<constant>SIGPIPE
</constant> UNIX signal handler is not blocked or turned off, such
131 write attempts will also result in such process signals being generated, see
132 <citerefentry><refentrytitle>signal
</refentrytitle><manvolnum>7</manvolnum></citerefentry>. To mitigate this issue,
133 systemd service manager explicitly turns off the
<constant>SIGPIPE
</constant> signal for all invoked processes by
134 default (this may be changed for each unit individually via the
<varname>IgnoreSIGPIPE=
</varname> option, see
135 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
136 details). After the standard output/standard error streams have been terminated they may not be recovered until the
137 services they are associated with are restarted. Note that during normal operation,
138 <filename>systemd-journald.service
</filename> stores copies of the file descriptors for those streams in the
139 service manager. If
<filename>systemd-journald.service
</filename> is restarted using
<command>systemctl
140 restart
</command> or equivalent operation instead of a pair of separate
<command>systemctl stop
</command> and
141 <command>systemctl start
</command> commands (or equivalent operations), these stream connections are not terminated
142 and survive the restart. It is thus safe to restart
<filename>systemd-journald.service
</filename>, but stopping it
143 is not recommended.
</para>
145 <para>Note that the log record metadata for records transferred via such standard output/error streams reflect the
146 metadata of the peer the stream was originally created for. If the stream connection is passed on to other
147 processes (such as further child processes forked off the main service process), the log records will not reflect
148 their metadata, but will continue to describe the original process. This is different from the other logging
149 transports listed above, which are inherently record based and where the metadata is always associated with the
150 individual record.
</para>
152 <para>In addition to the implicit standard output/error logging of services, stream logging is also available
153 via the
<citerefentry><refentrytitle>systemd-cat
</refentrytitle><manvolnum>1</manvolnum></citerefentry> command
156 <para>Currently, the number of parallel log streams
<filename>systemd-journald
</filename> will accept is limited to
157 4096. When this limit is reached further log streams may be established but will receive
158 <constant>EPIPE
</constant> right from the beginning.
</para>
162 <title>Signals
</title>
168 <listitem><para>Request that journal data from
169 <filename>/run/
</filename> is flushed to
170 <filename>/var/
</filename> in order to make it persistent (if
171 this is enabled). This must be used after
172 <filename>/var/
</filename> is mounted, as otherwise log data
173 from
<filename>/run
</filename> is never flushed to
174 <filename>/var
</filename> regardless of the configuration. The
175 <command>journalctl --flush
</command> command uses this signal
176 to request flushing of the journal files, and then waits for
177 the operation to complete. See
178 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
179 for details.
</para></listitem>
185 <listitem><para>Request immediate rotation of the journal
186 files. The
<command>journalctl --rotate
</command> command uses
187 this signal to request journal file
188 rotation.
</para></listitem>
192 <term>SIGRTMIN+
1</term>
194 <listitem><para>Request that all unwritten log data is written
195 to disk. The
<command>journalctl --sync
</command> command uses
196 this signal to trigger journal synchronization, and then waits
197 for the operation to complete.
</para></listitem>
203 <title>Kernel Command Line
</title>
205 <para>A few configuration parameters from
206 <filename>journald.conf
</filename> may be overridden on the kernel
209 <variablelist class='kernel-commandline-options'
>
211 <term><varname>systemd.journald.forward_to_syslog=
</varname></term>
212 <term><varname>systemd.journald.forward_to_kmsg=
</varname></term>
213 <term><varname>systemd.journald.forward_to_console=
</varname></term>
214 <term><varname>systemd.journald.forward_to_wall=
</varname></term>
216 <listitem><para>Enables/disables forwarding of collected log
217 messages to syslog, the kernel log buffer, the system console
222 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
223 for information about these settings.
</para>
231 <title>Access Control
</title>
233 <para>Journal files are, by default, owned and readable by the
234 <literal>systemd-journal
</literal> system group but are not
235 writable. Adding a user to this group thus enables her/him to read
236 the journal files.
</para>
238 <para>By default, each logged in user will get her/his own set of
239 journal files in
<filename>/var/log/journal/
</filename>. These
240 files will not be owned by the user, however, in order to avoid
241 that the user can write to them directly. Instead, file system
242 ACLs are used to ensure the user gets read access only.
</para>
244 <para>Additional users and groups may be granted access to journal
245 files via file system access control lists (ACL). Distributions
246 and administrators may choose to grant read access to all members
247 of the
<literal>wheel
</literal> and
<literal>adm
</literal> system
248 groups with a command such as the following:
</para>
250 <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/
</programlisting>
252 <para>Note that this command will update the ACLs both for
253 existing journal files and for future journal files created in the
254 <filename>/var/log/journal/
</filename> directory.
</para>
262 <term><filename>/etc/systemd/journald.conf
</filename></term>
264 <listitem><para>Configure
265 <command>systemd-journald
</command>
267 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
272 <term><filename>/run/log/journal/
<replaceable>machine-id
</replaceable>/*.journal
</filename></term>
273 <term><filename>/run/log/journal/
<replaceable>machine-id
</replaceable>/*.journal~
</filename></term>
274 <term><filename>/var/log/journal/
<replaceable>machine-id
</replaceable>/*.journal
</filename></term>
275 <term><filename>/var/log/journal/
<replaceable>machine-id
</replaceable>/*.journal~
</filename></term>
277 <listitem><para><command>systemd-journald
</command> writes
279 <filename>/run/log/journal/
<replaceable>machine-id
</replaceable>/
</filename>
281 <filename>/var/log/journal/
<replaceable>machine-id
</replaceable>/
</filename>
282 with the
<literal>.journal
</literal> suffix. If the daemon is
283 stopped uncleanly, or if the files are found to be corrupted,
284 they are renamed using the
<literal>.journal~
</literal>
285 suffix, and
<command>systemd-journald
</command> starts writing
286 to a new file.
<filename>/run
</filename> is used when
287 <filename>/var/log/journal
</filename> is not available, or
288 when
<option>Storage=volatile
</option> is set in the
289 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
290 configuration file.
</para></listitem>
294 <term><filename>/dev/kmsg
</filename></term>
295 <term><filename>/dev/log
</filename></term>
296 <term><filename>/run/systemd/journal/dev-log
</filename></term>
297 <term><filename>/run/systemd/journal/socket
</filename></term>
298 <term><filename>/run/systemd/journal/stdout
</filename></term>
300 <listitem><para>Sockets and other paths that
301 <command>systemd-journald
</command> will listen on that are
302 visible in the file system. In addition to these, journald can
303 listen for audit events using netlink.
</para></listitem>
309 <title>See Also
</title>
311 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
312 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
313 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
314 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
315 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
316 <citerefentry><refentrytitle>systemd-coredump
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
317 <citerefentry project='die-net'
><refentrytitle>setfacl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
318 <citerefentry><refentrytitle>sd_journal_print
</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
319 <command>pydoc systemd.journal
</command>