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.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"systemd-journald.service">
9 <title>systemd-journald.service
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>systemd-journald.service
</refentrytitle>
15 <manvolnum>8</manvolnum>
19 <refname>systemd-journald.service
</refname>
20 <refname>systemd-journald.socket
</refname>
21 <refname>systemd-journald-dev-log.socket
</refname>
22 <refname>systemd-journald-audit.socket
</refname>
23 <refname>systemd-journald
</refname>
24 <refpurpose>Journal service
</refpurpose>
28 <para><filename>systemd-journald.service
</filename></para>
29 <para><filename>systemd-journald.socket
</filename></para>
30 <para><filename>systemd-journald-dev-log.socket
</filename></para>
31 <para><filename>systemd-journald-audit.socket
</filename></para>
32 <para><filename>/usr/lib/systemd/systemd-journald
</filename></para>
36 <title>Description
</title>
38 <para><filename>systemd-journald
</filename> is a system service
39 that collects and stores logging data. It creates and maintains
40 structured, indexed journals based on logging information that is
41 received from a variety of sources:
</para>
44 <listitem><para>Kernel log messages, via kmsg
</para></listitem>
46 <listitem><para>Simple system log messages, via the
<filename>libc
</filename> <citerefentry
47 project='man-pages'
><refentrytitle>syslog
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
48 call
</para></listitem>
50 <listitem><para>Structured system log messages via the native
52 <citerefentry><refentrytitle>sd_journal_print
</refentrytitle><manvolnum>3</manvolnum></citerefentry></para></listitem>
54 <listitem><para>Standard output and standard error of service units. For further details see
55 below.
</para></listitem>
57 <listitem><para>Audit records, originating from the kernel audit subsystem
</para></listitem>
60 <para>The daemon will implicitly collect numerous metadata fields
61 for each log messages in a secure and unfakeable way. See
62 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
63 for more information about the collected metadata.
66 <para>Log data collected by the journal is primarily text-based but can also include binary data where
67 necessary. Individual fields making up a log record stored in the journal may be up to
2^
64-
1 bytes in size.
</para>
69 <para>The journal service stores log data either persistently below
<filename>/var/log/journal
</filename> or in a
70 volatile way below
<filename>/run/log/journal/
</filename> (in the latter case it is lost at reboot). By default, log
71 data is stored persistently if
<filename>/var/log/journal/
</filename> exists during boot, with an implicit fallback
72 to volatile storage otherwise. Use
<varname>Storage=
</varname> in
73 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry> to configure
74 where log data is placed, independently of the existence of
<filename>/var/log/journal/
</filename>.
</para>
76 <para>On systems where
<filename>/var/log/journal/
</filename> does not exist yet but where persistent logging is
77 desired (and the default
<filename>journald.conf
</filename> is used), it is sufficient to create the directory, and
78 ensure it has the correct access modes and ownership:
</para>
80 <programlisting>mkdir -p /var/log/journal
81 systemd-tmpfiles --create --prefix /var/log/journal
</programlisting>
84 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
85 for information about the configuration of this service.
</para>
89 <title>Stream logging
</title>
91 <para>The systemd service manager invokes all service processes with standard output and standard error connected
92 to the journal by default. This behaviour may be altered via the
93 <varname>StandardOutput=
</varname>/
<varname>StandardError=
</varname> unit file settings, see
94 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The
95 journal converts the log byte stream received this way into individual log records, splitting the stream at newline
96 (
<literal>\n
</literal>, ASCII
<constant>10</constant>) and
<constant>NUL
</constant> bytes.
</para>
98 <para>If
<filename>systemd-journald.service
</filename> is stopped, the stream connections associated with all
99 services are terminated. Further writes to those streams by the service will result in
<constant>EPIPE
</constant>
100 errors. In order to react gracefully in this case it is recommended that programs logging to standard output/error
101 ignore such errors. If the
<constant>SIGPIPE
</constant> UNIX signal handler is not blocked or turned off, such
102 write attempts will also result in such process signals being generated, see
103 <citerefentry><refentrytitle>signal
</refentrytitle><manvolnum>7</manvolnum></citerefentry>. To mitigate this issue,
104 systemd service manager explicitly turns off the
<constant>SIGPIPE
</constant> signal for all invoked processes by
105 default (this may be changed for each unit individually via the
<varname>IgnoreSIGPIPE=
</varname> option, see
106 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
107 details). After the standard output/standard error streams have been terminated they may not be recovered until the
108 services they are associated with are restarted. Note that during normal operation,
109 <filename>systemd-journald.service
</filename> stores copies of the file descriptors for those streams in the
110 service manager. If
<filename>systemd-journald.service
</filename> is restarted using
<command>systemctl
111 restart
</command> or equivalent operation instead of a pair of separate
<command>systemctl stop
</command> and
112 <command>systemctl start
</command> commands (or equivalent operations), these stream connections are not terminated
113 and survive the restart. It is thus safe to restart
<filename>systemd-journald.service
</filename>, but stopping it
114 is not recommended.
</para>
116 <para>Note that the log record metadata for records transferred via such standard output/error streams reflect the
117 metadata of the peer the stream was originally created for. If the stream connection is passed on to other
118 processes (such as further child processes forked off the main service process), the log records will not reflect
119 their metadata, but will continue to describe the original process. This is different from the other logging
120 transports listed above, which are inherently record based and where the metadata is always associated with the
121 individual record.
</para>
123 <para>In addition to the implicit standard output/error logging of services, stream logging is also available
124 via the
<citerefentry><refentrytitle>systemd-cat
</refentrytitle><manvolnum>1</manvolnum></citerefentry> command
127 <para>Currently, the number of parallel log streams
<filename>systemd-journald
</filename> will accept is limited to
128 4096. When this limit is reached further log streams may be established but will receive
129 <constant>EPIPE
</constant> right from the beginning.
</para>
133 <title>Signals
</title>
139 <listitem><para>Request that journal data from
<filename>/run/
</filename> is flushed to
140 <filename>/var/
</filename> in order to make it persistent (if this is enabled). This must be used
141 after
<filename>/var/
</filename> is mounted, as otherwise log data from
<filename>/run
</filename> is
142 never flushed to
<filename>/var
</filename> regardless of the configuration. Use the
143 <command>journalctl --flush
</command> command to request flushing of the journal files, and wait for
144 the operation to complete. See
145 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
146 details.
</para></listitem>
152 <listitem><para>Request immediate rotation of the journal files. Use the
<command>journalctl
153 --rotate
</command> command to request journal file rotation, and wait for the operation to
154 complete.
</para></listitem>
158 <term>SIGRTMIN+
1</term>
160 <listitem><para>Request that all unwritten log data is written to disk. Use the
<command>journalctl
161 --sync
</command> command to trigger journal synchronization, and wait for the operation to
162 complete.
</para></listitem>
168 <title>Kernel Command Line
</title>
170 <para>A few configuration parameters from
171 <filename>journald.conf
</filename> may be overridden on the kernel
174 <variablelist class='kernel-commandline-options'
>
176 <term><varname>systemd.journald.forward_to_syslog=
</varname></term>
177 <term><varname>systemd.journald.forward_to_kmsg=
</varname></term>
178 <term><varname>systemd.journald.forward_to_console=
</varname></term>
179 <term><varname>systemd.journald.forward_to_wall=
</varname></term>
181 <listitem><para>Enables/disables forwarding of collected log
182 messages to syslog, the kernel log buffer, the system console
187 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
188 for information about these settings.
</para>
196 <title>Access Control
</title>
198 <para>Journal files are, by default, owned and readable by the
199 <literal>systemd-journal
</literal> system group but are not
200 writable. Adding a user to this group thus enables them to read
201 the journal files.
</para>
203 <para>By default, each user, with a UID outside the range of system users,
204 dynamic service users, and the nobody user, will get their own set of
205 journal files in
<filename>/var/log/journal/
</filename>. See
206 <ulink url=
"https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems
</ulink>
207 for more details about UID ranges. These journal
208 files will not be owned by the user, however, in order to avoid
209 that the user can write to them directly. Instead, file system
210 ACLs are used to ensure the user gets read access only.
</para>
212 <para>Additional users and groups may be granted access to journal
213 files via file system access control lists (ACL). Distributions
214 and administrators may choose to grant read access to all members
215 of the
<literal>wheel
</literal> and
<literal>adm
</literal> system
216 groups with a command such as the following:
</para>
218 <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/
</programlisting>
220 <para>Note that this command will update the ACLs both for
221 existing journal files and for future journal files created in the
222 <filename>/var/log/journal/
</filename> directory.
</para>
230 <term><filename>/etc/systemd/journald.conf
</filename></term>
232 <listitem><para>Configure
<command>systemd-journald
</command> behavior. See
233 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
238 <term><filename>/run/log/journal/
<replaceable>machine-id
</replaceable>/*.journal
</filename></term>
239 <term><filename>/run/log/journal/
<replaceable>machine-id
</replaceable>/*.journal~
</filename></term>
240 <term><filename>/var/log/journal/
<replaceable>machine-id
</replaceable>/*.journal
</filename></term>
241 <term><filename>/var/log/journal/
<replaceable>machine-id
</replaceable>/*.journal~
</filename></term>
243 <listitem><para><command>systemd-journald
</command> writes entries to files in
244 <filename>/run/log/journal/
<replaceable>machine-id
</replaceable>/
</filename>
246 <filename>/var/log/journal/
<replaceable>machine-id
</replaceable>/
</filename>
247 with the
<literal>.journal
</literal> suffix. If the daemon is
248 stopped uncleanly, or if the files are found to be corrupted,
249 they are renamed using the
<literal>.journal~
</literal>
250 suffix, and
<command>systemd-journald
</command> starts writing
251 to a new file.
<filename>/run
</filename> is used when
252 <filename>/var/log/journal
</filename> is not available, or
253 when
<option>Storage=volatile
</option> is set in the
254 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
255 configuration file.
</para>
257 <para>When
<filename>systemd-journald
</filename> ceases writing to a journal file,
258 it will be renamed to
<literal><replaceable>original-name
</replaceable>@
<replaceable>suffix.journal
</replaceable></literal>
259 (or
<literal><replaceable>original-name
</replaceable>@
<replaceable>suffix.journal~
</replaceable></literal>).
260 Such files are
"archived" and will not be written to any more.
</para>
262 <para>In general, it is safe to read or copy any journal file (active or archived).
263 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
264 and the functions in the
265 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
266 library should be able to read all entries that have been fully written.
</para>
268 <para><filename>systemd-journald
</filename> will automatically remove the oldest
269 archived journal files to limit disk use. See
<varname>SystemMaxUse=
</varname>
270 and related settings in
271 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
276 <term><filename>/dev/kmsg
</filename></term>
277 <term><filename>/dev/log
</filename></term>
278 <term><filename>/run/systemd/journal/dev-log
</filename></term>
279 <term><filename>/run/systemd/journal/socket
</filename></term>
280 <term><filename>/run/systemd/journal/stdout
</filename></term>
282 <listitem><para>Sockets and other paths that
283 <command>systemd-journald
</command> will listen on that are
284 visible in the file system. In addition to these, journald can
285 listen for audit events using netlink.
</para></listitem>
291 <title>See Also
</title>
293 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
294 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
295 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
296 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
297 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
298 <citerefentry><refentrytitle>systemd-coredump
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
299 <citerefentry project='die-net'
><refentrytitle>setfacl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
300 <citerefentry><refentrytitle>sd_journal_print
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
301 <command>pydoc systemd.journal
</command>