chiark / gitweb /
3cfda5b84b5fbf12c92a79012760bb7469389d13
[elogind.git] / man / journalctl.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 2012 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="journalctl">
25
26         <refentryinfo>
27                 <title>journalctl</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>journalctl</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>journalctl</refname>
47                 <refpurpose>Query the systemd journal</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>journalctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">MATCHES</arg></command>
53                 </cmdsynopsis>
54         </refsynopsisdiv>
55
56         <refsect1>
57                 <title>Description</title>
58
59                 <para><command>journalctl</command> may be used to
60                 query the contents of the
61                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
62                 journal as written by
63                 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
64
65                 <para>If called without parameter will show the full
66                 contents of the journal, starting with the oldest
67                 entry collected.</para>
68
69                 <para>If one or more match arguments are passed the
70                 output is filtered accordingly. A match is in the
71                 format <literal>FIELD=VALUE</literal>,
72                 e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>,
73                 referring to the components of a structured journal
74                 entry. See
75                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
76                 for a list of well-known fields. If multiple matches
77                 are specified matching different fields the log
78                 entries are filtered by both, i.e. the resulting output
79                 will show only entries matching all the specified
80                 matches of this kind. If two matches apply to the same
81                 field, then they are automatically matched as
82                 alternatives, i.e. the resulting output will show
83                 entries matching any of the specified matches for the
84                 same field. Finally, if the character
85                 "<literal>+</literal>" appears as separate word on the
86                 command line all matches before and after are combined
87                 in a disjunction (i.e. logical OR).</para>
88
89                 <para>As shortcuts for a few types of field/value
90                 matches file paths may be specified. If a file path
91                 refers to an executable file, this is equivalent to an
92                 <literal>_EXE=</literal> match for the canonicalized
93                 binary path. Similar, if a path refers to a device
94                 node, this is equivalent to a
95                 <literal>_KERNEL_DEVICE=</literal> match for the
96                 device.</para>
97
98                 <para>Output is interleaved from all accessible
99                 journal files, whether they are rotated or currently
100                 being written, and regardless whether they belong to the
101                 system itself or are accessible user journals.</para>
102
103                 <para>All users are granted access to their private
104                 per-user journals. However, by default only root and
105                 users who are members of the <literal>adm</literal>
106                 group get access to the system journal and the
107                 journals of other users.</para>
108         </refsect1>
109
110         <refsect1>
111                 <title>Options</title>
112
113                 <para>The following options are understood:</para>
114
115                 <variablelist>
116                         <varlistentry>
117                                 <term><option>--help</option></term>
118                                 <term><option>-h</option></term>
119
120                                 <listitem><para>Prints a short help
121                                 text and exits.</para></listitem>
122                         </varlistentry>
123
124                         <varlistentry>
125                                 <term><option>--version</option></term>
126
127                                 <listitem><para>Prints a short version
128                                 string and exits.</para></listitem>
129                         </varlistentry>
130
131                         <varlistentry>
132                                 <term><option>--no-pager</option></term>
133
134                                 <listitem><para>Do not pipe output into a
135                                 pager.</para></listitem>
136                         </varlistentry>
137
138                         <varlistentry>
139                                 <term><option>--all</option></term>
140                                 <term><option>-a</option></term>
141
142                                 <listitem><para>Show all fields in
143                                 full, even if they include unprintable
144                                 characters or are very
145                                 long.</para></listitem>
146                         </varlistentry>
147
148                         <varlistentry>
149                                 <term><option>--follow</option></term>
150                                 <term><option>-f</option></term>
151
152                                 <listitem><para>Show only most recent
153                                 journal entries, and continuously print
154                                 new entries as they are appended to
155                                 the journal.</para></listitem>
156                         </varlistentry>
157
158                         <varlistentry>
159                                 <term><option>--lines=</option></term>
160                                 <term><option>-n</option></term>
161
162                                 <listitem><para>Controls the number of
163                                 journal lines to show, counting from
164                                 the most recent ones. Takes a positive
165                                 integer argument. In follow mode
166                                 defaults to 10, otherwise is unset
167                                 thus not limiting how many lines are
168                                 shown.</para></listitem>
169                         </varlistentry>
170
171                         <varlistentry>
172                                 <term><option>--no-tail</option></term>
173
174                                 <listitem><para>Show all stored output
175                                 lines, even in follow mode. Undoes the
176                                 effect of
177                                 <option>--lines=</option>.</para></listitem>
178                         </varlistentry>
179
180                         <varlistentry>
181                                 <term><option>--output=</option></term>
182                                 <term><option>-o</option></term>
183
184                                 <listitem><para>Controls the
185                                 formatting of the journal entries that
186                                 are shown. Takes one of
187                                 <literal>short</literal>,
188                                 <literal>short-monotonic</literal>,
189                                 <literal>verbose</literal>,
190                                 <literal>export</literal>,
191                                 <literal>json</literal>,
192                                 <literal>cat</literal>. <literal>short</literal>
193                                 is the default and generates an output
194                                 that is mostly identical to the
195                                 formatting of classic syslog log
196                                 files, showing one line per journal
197                                 entry. <literal>short-monotonic</literal>
198                                 is very similar but shows monotonic
199                                 timestamps instead of wallclock
200                                 timestamps. <literal>verbose</literal>
201                                 shows the full structured entry items
202                                 with all
203                                 fields. <literal>export</literal>
204                                 serializes the journal into a binary
205                                 (but mostly text-based) stream
206                                 suitable for backups and network
207                                 transfer (see <ulink
208                                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
209                                 Export Format</ulink> for more
210                                 information). <literal>json</literal>
211                                 formats entries as JSON data
212                                 structures. <literal>cat</literal>
213                                 generates a very terse output only
214                                 showing the actual message of each
215                                 journal entry with no meta data, not
216                                 even a timestamp.</para></listitem>
217                         </varlistentry>
218
219                         <varlistentry>
220                                 <term><option>--quiet</option></term>
221                                 <term><option>-q</option></term>
222
223                                 <listitem><para>Suppresses any warning
224                                 message regarding inaccessible system
225                                 journals when run as normal
226                                 user.</para></listitem>
227                         </varlistentry>
228
229                         <varlistentry>
230                                 <term><option>--local</option></term>
231                                 <term><option>-l</option></term>
232
233                                 <listitem><para>Show only locally
234                                 generated messages.</para></listitem>
235                         </varlistentry>
236
237                         <varlistentry>
238                                 <term><option>--this-boot</option></term>
239                                 <term><option>-b</option></term>
240
241                                 <listitem><para>Show data only from
242                                 current boot.</para></listitem>
243                         </varlistentry>
244
245                         <varlistentry>
246                                 <term><option>--directory=</option></term>
247                                 <term><option>-D</option></term>
248
249                                 <listitem><para>Takes an absolute
250                                 directory path as argument. If
251                                 specified will operate on the
252                                 specified journal directory instead of
253                                 the default runtime and system journal
254                                 paths.</para></listitem>
255                         </varlistentry>
256
257                         <varlistentry>
258                                 <term><option>--new-id128</option></term>
259
260                                 <listitem><para>Instead of showing
261                                 journal contents generate a new 128
262                                 bit ID suitable for identifying
263                                 messages. This is intended for usage
264                                 by developers who need a new
265                                 identifier for a new message they
266                                 introduce and want to make
267                                 recognizable. Will print the new ID in
268                                 three different formats which can be
269                                 copied into source code or
270                                 similar.</para></listitem>
271                         </varlistentry>
272
273                         <varlistentry>
274                                 <term><option>--header</option></term>
275
276                                 <listitem><para>Instead of showing
277                                 journal contents show internal header
278                                 information of the journal fiels
279                                 accessed.</para></listitem>
280                         </varlistentry>
281
282                         <varlistentry>
283                                 <term><option>-p</option></term>
284                                 <term><option>--priority=</option></term>
285
286                                 <listitem><para>Filter output by
287                                 message priorities or priority
288                                 ranges. Takes either a single numeric
289                                 or textual log level (i.e. between
290                                 0/<literal>emerg</literal> and
291                                 7/<literal>debug</literal>), or a
292                                 range of numeric/text log levels in
293                                 the form FROM..TO. The log levels are
294                                 the usual syslog log levels as
295                                 documented in
296                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
297                                 i.e. <literal>emerg</literal> (0),
298                                 <literal>alert</literal> (1),
299                                 <literal>crit</literal> (2),
300                                 <literal>err</literal> (3),
301                                 <literal>warning</literal> (4),
302                                 <literal>notice</literal> (5),
303                                 <literal>info</literal> (6),
304                                 <literal>debug</literal> (7). If a
305                                 single log level is specified all
306                                 messages with this log levels or a
307                                 lower (hence more important) log level
308                                 are shown. If a range is specified all
309                                 messages within the range are shown,
310                                 including both the start and the end
311                                 value of the range.</para></listitem>
312                         </varlistentry>
313
314                 </variablelist>
315         </refsect1>
316
317         <refsect1>
318                 <title>Exit status</title>
319
320                 <para>On success 0 is returned, a non-zero failure
321                 code otherwise.</para>
322         </refsect1>
323
324         <refsect1>
325                 <title>Environment</title>
326
327                 <variablelist>
328                         <varlistentry>
329                                 <term><varname>$SYSTEMD_PAGER</varname></term>
330                                 <listitem><para>Pager to use when
331                                 <option>--no-pager</option> is not given;
332                                 overrides <varname>$PAGER</varname>.  Setting
333                                 this to an empty string or the value
334                                 <literal>cat</literal> is equivalent to passing
335                                 <option>--no-pager</option>.</para></listitem>
336                         </varlistentry>
337                 </variablelist>
338         </refsect1>
339
340         <refsect1>
341                 <title>Examples</title>
342
343                 <para>Without arguments all collected logs are shown
344                 unfiltered:</para>
345
346                 <programlisting>journalctl</programlisting>
347
348                 <para>With one match specified all entries with a field matching the expression are shown:</para>
349
350                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
351
352                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
353
354                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
355
356                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
357
358                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
359
360                 <para>If the separator "<literal>+</literal>" is used
361                 two expression may be combined in a logical OR. The
362                 following will show all messages from the Avahi
363                 service process with the PID 28097 plus all messages
364                 from the D-Bus service (from any of its
365                 processes):</para>
366
367                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
368
369                 <para>Show all logs generated by the D-Bus executable:</para>
370
371                 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
372
373                 <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
374
375                 <programlisting>journalctl /dev/sda</programlisting>
376
377         </refsect1>
378
379         <refsect1>
380                 <title>See Also</title>
381                 <para>
382                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
383                         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
384                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
385                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
386                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
387                 </para>
388         </refsect1>
389
390 </refentry>