chiark / gitweb /
man: fix grammatical errors and other formatting issues
[elogind.git] / man / systemd-journald.service.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="systemd-journald.service">
25
26         <refentryinfo>
27                 <title>systemd-journald.service</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>systemd-journald.service</refentrytitle>
42                 <manvolnum>8</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemd-journald.service</refname>
47                 <refname>systemd-journald.socket</refname>
48                 <refname>systemd-journald</refname>
49                 <refpurpose>Journal service</refpurpose>
50         </refnamediv>
51
52         <refsynopsisdiv>
53                 <para><filename>systemd-journald.service</filename></para>
54                 <para><filename>systemd-journald.socket</filename></para>
55                 <para><filename>/usr/lib/systemd/systemd-journald</filename></para>
56         </refsynopsisdiv>
57
58         <refsect1>
59                 <title>Description</title>
60
61                 <para><filename>systemd-journald</filename> is a
62                 system service that collects and stores logging
63                 data. It creates and maintains structured, indexed
64                 journals based on logging information that is received
65                 from the kernel, from user processes via the libc
66                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
67                 call, from STDOUT/STDERR of system services or via its
68                 native API. It will implicitly collect numerous meta
69                 data fields for each log messages in a secure and
70                 unfakeable way. See
71                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
72                 for more information about the collected meta data.
73                 </para>
74
75                 <para>Log data collected by the journal is primarily
76                 text-based but can also include binary data where
77                 necessary. All objects stored in the journal can be up
78                 to 2^64-1 bytes in size.</para>
79
80                 <para>By default, the journal stores log data in
81                 <filename>/run/log/journal/</filename>. Since
82                 <filename>/run/</filename> is volatile, log data is
83                 lost at reboot. To make the data persistent, it
84                 is sufficient to create
85                 <filename>/var/log/journal/</filename> where
86                 <filename>systemd-journald</filename> will then store
87                 the data.</para>
88
89                 <para><filename>systemd-journald</filename> will
90                 forward all received log messages to the <constant>AF_UNIX</constant>
91                 <constant>SOCK_DGRAM</constant> socket
92                 <filename>/run/systemd/journal/syslog</filename>, if it exists, which
93                 may be used by Unix syslog daemons to process the data
94                 further.</para>
95
96                 <para>See
97                 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
98                 for information about the configuration of this
99                 service.</para>
100         </refsect1>
101
102         <refsect1>
103                 <title>Signals</title>
104
105                 <variablelist>
106                         <varlistentry>
107                                 <term>SIGUSR1</term>
108
109                                 <listitem><para>Request that journal
110                                 data from <filename>/run/</filename>
111                                 is flushed to
112                                 <filename>/var/</filename> in order to
113                                 make it persistent (if this is
114                                 enabled). This must be used after
115                                 <filename>/var/</filename> is mounted,
116                                 as otherwise log data from
117                                 <filename>/run</filename> is never
118                                 flushed to <filename>/var</filename>
119                                 regardless of the
120                                 configuration.</para></listitem>
121                         </varlistentry>
122
123                         <varlistentry>
124                                 <term>SIGUSR2</term>
125
126                                 <listitem><para>Request immediate
127                                 rotation of the journal
128                                 files.</para></listitem>
129                         </varlistentry>
130                 </variablelist>
131         </refsect1>
132
133         <refsect1>
134                 <title>Kernel Command Line</title>
135
136                 <para>A few configuration parameters from
137                 <filename>journald.conf</filename> may be overridden on
138                 the kernel command line:</para>
139
140                 <variablelist class='kernel-commandline-options'>
141                         <varlistentry>
142                                 <term><varname>systemd.journald.forward_to_syslog=</varname></term>
143                                 <term><varname>systemd.journald.forward_to_kmsg=</varname></term>
144                                 <term><varname>systemd.journald.forward_to_console=</varname></term>
145
146                                 <listitem><para>Enables/disables
147                                 forwarding of collected log messages
148                                 to syslog, the kernel log buffer or
149                                 the system console.
150                                 </para>
151
152                                 <para>See
153                                 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
154                                 for information about these settings.</para>
155                                 </listitem>
156
157                         </varlistentry>
158                 </variablelist>
159         </refsect1>
160
161         <refsect1>
162                 <title>Access Control</title>
163
164                 <para>Journal files are, by default, owned and readable
165                 by the <literal>systemd-journal</literal> system group
166                 but are not writable. Adding a user to this group thus
167                 enables her/him to read the journal files.</para>
168
169                 <para>By default, each logged in user will get her/his
170                 own set of journal files in
171                 <filename>/var/log/journal/</filename>. These files
172                 will not be owned by the user, however, in order to
173                 avoid that the user can write to them
174                 directly. Instead, file system ACLs are used to ensure
175                 the user gets read access only.</para>
176
177                 <para>Additional users and groups may be granted
178                 access to journal files via file system access control
179                 lists (ACL). Distributions and administrators may
180                 choose to grant read access to all members of the
181                 <literal>wheel</literal> and <literal>adm</literal>
182                 system groups with a command such as the
183                 following:</para>
184
185                 <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/</programlisting>
186
187                 <para>Note that this command will update the ACLs both
188                 for existing journal files and for future journal
189                 files created in the
190                 <filename>/var/log/journal/</filename>
191                 directory.</para>
192         </refsect1>
193
194         <refsect1>
195                 <title>Files</title>
196
197                 <variablelist>
198                         <varlistentry>
199                                 <term><filename>/etc/systemd/journald.conf</filename></term>
200
201                                 <listitem><para>Configure
202                                 <command>systemd-journald</command>
203                                 behaviour. See
204                                 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
205                                 </para></listitem>
206                         </varlistentry>
207
208                         <varlistentry>
209                                 <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term>
210                                 <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term>
211                                 <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term>
212                                 <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term>
213
214                                 <listitem><para><command>systemd-journald</command>
215                                 writes entries to files in
216                                 <filename>/run/log/journal/<replaceable>machine-id</replaceable>/</filename>
217                                 or
218                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
219                                 with the <literal>.journal</literal>
220                                 suffix. If the daemon is stopped
221                                 uncleanly, or if the files are found
222                                 to be corrupted, they are renamed
223                                 using the <literal>.journal~</literal>
224                                 suffix, and
225                                 <command>systemd-journald</command>
226                                 starts writing to a new
227                                 file. <filename>/run</filename> is
228                                 used when
229                                 <filename>/var/log/journal</filename>
230                                 is not available, or when
231                                 <option>Storage=volatile</option> is
232                                 set in the
233                                 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
234                                 configuration file.
235                                 </para></listitem>
236                         </varlistentry>
237                 </variablelist>
238         </refsect1>
239
240         <refsect1>
241                 <title>See Also</title>
242                 <para>
243                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
244                         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
245                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
246                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
247                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
248                         <citerefentry><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
249                         <command>pydoc systemd.journal</command>.
250                 </para>
251         </refsect1>
252
253 </refentry>