]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/journalctl.xml
66100816ae4070c4ce7bce35dc60da32ad733fb8
[thirdparty/systemd.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</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
54 <arg choice="opt" rep="repeat">MATCHES</arg>
55 </cmdsynopsis>
56 </refsynopsisdiv>
57
58 <refsect1>
59 <title>Description</title>
60
61 <para><command>journalctl</command> may be used to
62 query the contents of the
63 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
64 journal as written by
65 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
66
67 <para>If called without parameter it will show the full
68 contents of the journal, starting with the oldest
69 entry collected.</para>
70
71 <para>If one or more match arguments are passed the
72 output is filtered accordingly. A match is in the
73 format <literal>FIELD=VALUE</literal>,
74 e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>,
75 referring to the components of a structured journal
76 entry. See
77 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
78 for a list of well-known fields. If multiple matches
79 are specified matching different fields the log
80 entries are filtered by both, i.e. the resulting output
81 will show only entries matching all the specified
82 matches of this kind. If two matches apply to the same
83 field, then they are automatically matched as
84 alternatives, i.e. the resulting output will show
85 entries matching any of the specified matches for the
86 same field. Finally, if the character
87 "<literal>+</literal>" appears as separate word on the
88 command line all matches before and after are combined
89 in a disjunction (i.e. logical OR).</para>
90
91 <para>As shortcuts for a few types of field/value
92 matches file paths may be specified. If a file path
93 refers to an executable file, this is equivalent to an
94 <literal>_EXE=</literal> match for the canonicalized
95 binary path. Similar, if a path refers to a device
96 node, this is equivalent to a
97 <literal>_KERNEL_DEVICE=</literal> match for the
98 device.</para>
99
100 <para>Output is interleaved from all accessible
101 journal files, whether they are rotated or currently
102 being written, and regardless whether they belong to the
103 system itself or are accessible user journals.</para>
104
105 <para>All users are granted access to their private
106 per-user journals. However, by default only root and
107 users who are members of the <literal>adm</literal>
108 group get access to the system journal and the
109 journals of other users.</para>
110 </refsect1>
111
112 <refsect1>
113 <title>Options</title>
114
115 <para>The following options are understood:</para>
116
117 <variablelist>
118 <varlistentry>
119 <term><option>-h</option></term>
120 <term><option>--help</option></term>
121
122 <listitem><para>Prints a short help
123 text and exits.</para></listitem>
124 </varlistentry>
125
126 <varlistentry>
127 <term><option>--version</option></term>
128
129 <listitem><para>Prints a short version
130 string and exits.</para></listitem>
131 </varlistentry>
132
133 <varlistentry>
134 <term><option>--no-pager</option></term>
135
136 <listitem><para>Do not pipe output into a
137 pager.</para></listitem>
138 </varlistentry>
139
140 <varlistentry>
141 <term><option>--full</option></term>
142
143 <listitem><para>Show all (printable) fields in
144 full.</para></listitem>
145 </varlistentry>
146
147 <varlistentry>
148 <term><option>-a</option></term>
149 <term><option>--all</option></term>
150
151 <listitem><para>Show all fields in
152 full, even if they include unprintable
153 characters or are very
154 long.</para></listitem>
155 </varlistentry>
156
157 <varlistentry>
158 <term><option>-f</option></term>
159 <term><option>--follow</option></term>
160
161 <listitem><para>Show only the most recent
162 journal entries, and continuously print
163 new entries as they are appended to
164 the journal.</para></listitem>
165 </varlistentry>
166
167 <varlistentry>
168 <term><option>-e</option></term>
169 <term><option>--pager-end</option></term>
170
171 <listitem><para>Immediately jump to
172 the end of the journal inside the
173 implied pager tool. This implies
174 <option>-n1000</option> to guarantee
175 that the pager won't buffer logs of
176 unbounded size. This may be overridden
177 with an explicit <option>-n</option>
178 with some other numeric value on the
179 command line. Note that this option is
180 only supported for the
181 <citerefentry><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
182 pager.</para></listitem>
183 </varlistentry>
184
185 <varlistentry>
186 <term><option>-n</option></term>
187 <term><option>--lines=</option></term>
188
189 <listitem><para>Show the most recent
190 journal events and limit the number of
191 events shown. If
192 <option>--follow</option> is used,
193 this option is implied. The argument,
194 a positive integer, is optional, and
195 defaults to 10. </para></listitem>
196 </varlistentry>
197
198 <varlistentry>
199 <term><option>--no-tail</option></term>
200
201 <listitem><para>Show all stored output
202 lines, even in follow mode. Undoes the
203 effect of
204 <option>--lines=</option>.</para></listitem>
205 </varlistentry>
206
207 <varlistentry>
208 <term><option>-r</option></term>
209 <term><option>--reverse</option></term>
210
211 <listitem><para>Reverse output, so the newest
212 entries are displayed first.</para></listitem>
213 </varlistentry>
214
215 <varlistentry>
216 <term><option>-o</option></term>
217 <term><option>--output=</option></term>
218
219 <listitem><para>Controls the
220 formatting of the journal entries that
221 are shown. Takes one of
222 <literal>short</literal>,
223 <literal>short-monotonic</literal>,
224 <literal>verbose</literal>,
225 <literal>export</literal>,
226 <literal>json</literal>,
227 <literal>json-pretty</literal>,
228 <literal>json-sse</literal>,
229 <literal>cat</literal>. <literal>short</literal>
230 is the default and generates an output
231 that is mostly identical to the
232 formatting of classic syslog log
233 files, showing one line per journal
234 entry. <literal>short-monotonic</literal>
235 is very similar but shows monotonic
236 timestamps instead of wallclock
237 timestamps. <literal>verbose</literal>
238 shows the full structured entry items
239 with all
240 fields. <literal>export</literal>
241 serializes the journal into a binary
242 (but mostly text-based) stream
243 suitable for backups and network
244 transfer (see <ulink
245 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
246 Export Format</ulink> for more
247 information). <literal>json</literal>
248 formats entries as JSON data
249 structures, one per
250 line (see <ulink
251 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
252 JSON Format</ulink> for more
253 information). <literal>json-pretty</literal>
254 also formats entries as JSON data
255 structures, but formats them in
256 multiple lines in order to make them
257 more readable for
258 humans. <literal>json-sse</literal>
259 also formats entries as JSON data
260 structures, but wraps them in a format
261 suitable for <ulink
262 url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent
263 Events</ulink>. <literal>cat</literal>
264 generates a very terse output only
265 showing the actual message of each
266 journal entry with no meta data, not
267 even a timestamp.</para></listitem>
268 </varlistentry>
269
270 <varlistentry>
271 <term><option>-x</option></term>
272 <term><option>--catalog</option></term>
273
274 <listitem><para>Augment log lines with
275 explanation texts from the message
276 catalog. This will add explanatory
277 help texts to log messages in the
278 output where this is available. These
279 short help texts will explain the
280 context of an error or log event,
281 possible solutions, as well as
282 pointers to support forums, developer
283 documentation and any other relevant
284 manuals. Note that help texts are not
285 available for all messages, but only
286 for selected ones. For more
287 information on the message catalog
288 please refer to the <ulink
289 url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Message
290 Catalog Developer
291 Documentation</ulink>.</para></listitem>
292 </varlistentry>
293
294 <varlistentry>
295 <term><option>-q</option></term>
296 <term><option>--quiet</option></term>
297
298 <listitem><para>Suppresses any warning
299 message regarding inaccessible system
300 journals when run as normal
301 user.</para></listitem>
302 </varlistentry>
303
304 <varlistentry>
305 <term><option>-m</option></term>
306 <term><option>--merge</option></term>
307
308 <listitem><para>Show entries
309 interleaved from all available
310 journals, including remote
311 ones.</para></listitem>
312 </varlistentry>
313
314 <varlistentry>
315 <term><option>-b</option></term>
316 <term><option>--this-boot</option></term>
317
318 <listitem><para>Show data only from
319 current boot. This will add a match
320 for <literal>_BOOT_ID=</literal> for
321 the current boot ID of the
322 kernel.</para></listitem>
323 </varlistentry>
324
325 <varlistentry>
326 <term><option>-k</option></term>
327 <term><option>--dmesg</option></term>
328
329 <listitem><para>Show kernel messages from
330 current boot. This implies <option>-b</option>
331 and adds the match <literal>_TRANSPORT=kernel</literal>.
332 </para></listitem>
333 </varlistentry>
334
335 <varlistentry>
336 <term><option>-u</option></term>
337 <term><option>--unit=</option></term>
338
339 <listitem><para>Show messages for the
340 specified systemd unit. This will add
341 a match for messages from the unit
342 (<literal>_SYSTEMD_UNIT=</literal>)
343 and additional matches for messages
344 from systemd and messages about
345 coredumps for the specified unit.</para>
346 <para>This parameter can be specified multiple times.
347 </para></listitem>
348 </varlistentry>
349
350 <varlistentry>
351 <term><option>--user-unit=</option></term>
352
353 <listitem><para>Show messages for the
354 specified user session unit. This will
355 add a match for messages from the unit
356 (<literal>_SYSTEMD_USER_UNIT=</literal>
357 and <literal>_UID=</literal>) and
358 additional matches for messages from
359 session systemd and messages about
360 coredumps for the specified unit.</para>
361 <para>This parameter can be specified multiple times.
362 </para></listitem>
363 </varlistentry>
364
365 <varlistentry>
366 <term><option>-p</option></term>
367 <term><option>--priority=</option></term>
368
369 <listitem><para>Filter output by
370 message priorities or priority
371 ranges. Takes either a single numeric
372 or textual log level (i.e. between
373 0/<literal>emerg</literal> and
374 7/<literal>debug</literal>), or a
375 range of numeric/text log levels in
376 the form FROM..TO. The log levels are
377 the usual syslog log levels as
378 documented in
379 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
380 i.e. <literal>emerg</literal> (0),
381 <literal>alert</literal> (1),
382 <literal>crit</literal> (2),
383 <literal>err</literal> (3),
384 <literal>warning</literal> (4),
385 <literal>notice</literal> (5),
386 <literal>info</literal> (6),
387 <literal>debug</literal> (7). If a
388 single log level is specified all
389 messages with this log level or a
390 lower (hence more important) log level
391 are shown. If a range is specified all
392 messages within the range are shown,
393 including both the start and the end
394 value of the range. This will add
395 <literal>PRIORITY=</literal> matches
396 for the specified
397 priorities.</para></listitem>
398 </varlistentry>
399
400 <varlistentry>
401 <term><option>-c</option></term>
402 <term><option>--cursor=</option></term>
403
404 <listitem><para>Start showing entries
405 from the location in the journal
406 specified by the passed
407 cursor.</para></listitem>
408 </varlistentry>
409
410 <varlistentry>
411 <term><option>--since=</option></term>
412 <term><option>--until=</option></term>
413
414 <listitem><para>Start showing entries
415 on or newer than the specified date,
416 or on or older than the specified
417 date, respectively. Date specifications should be of
418 the format "2012-10-30 18:17:16". If
419 the time part is omitted, 00:00:00 is
420 assumed. If only the seconds component
421 is omitted, :00 is assumed. If the
422 date component is omitted, the
423 current day is assumed. Alternatively
424 the strings
425 <literal>yesterday</literal>,
426 <literal>today</literal>,
427 <literal>tomorrow</literal> are
428 understood, which refer to 00:00:00 of
429 the day before the current day, the
430 current day, or the day after the
431 current day, respectively. <literal>now</literal>
432 refers to the current time. Finally,
433 relative times may be specified,
434 prefixed with <literal>-</literal> or
435 <literal>+</literal>, referring to
436 times before or after the current
437 time, respectively.</para></listitem>
438 </varlistentry>
439
440 <varlistentry>
441 <term><option>-F</option></term>
442 <term><option>--field=</option></term>
443
444 <listitem><para>Print all possible
445 data values the specified field can
446 take in all entries of the
447 journal.</para></listitem>
448 </varlistentry>
449
450 <varlistentry>
451 <term><option>--system</option></term>
452 <term><option>--user</option></term>
453
454 <listitem><para>Show messages from
455 system services and the kernel (with
456 <option>--system</option>). Show
457 messages from service of current user
458 (with <option>--user</option>).
459 If neither is specified, show all
460 messages that the user can see.
461 </para></listitem>
462 </varlistentry>
463
464 <varlistentry>
465 <term><option>-D</option></term>
466 <term><option>--directory=</option></term>
467
468 <listitem><para>Takes a
469 directory path as argument. If
470 specified journalctl will operate on the
471 specified journal directory instead of
472 the default runtime and system journal
473 paths.</para></listitem>
474 </varlistentry>
475
476 <varlistentry>
477 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
478
479 <listitem><para>Takes a directory path
480 as argument. If specified journalctl
481 will operate on catalog file hierarchy
482 underneath the specified directory
483 instead of the root directory
484 (e.g. <option>--update-catalog</option>
485 will create
486 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
487 </para></listitem>
488 </varlistentry>
489
490 <varlistentry>
491 <term><option>--new-id128</option></term>
492
493 <listitem><para>Instead of showing
494 journal contents generate a new 128
495 bit ID suitable for identifying
496 messages. This is intended for usage
497 by developers who need a new
498 identifier for a new message they
499 introduce and want to make
500 recognizable. Will print the new ID in
501 three different formats which can be
502 copied into source code or
503 similar.</para></listitem>
504 </varlistentry>
505
506 <varlistentry>
507 <term><option>--header</option></term>
508
509 <listitem><para>Instead of showing
510 journal contents show internal header
511 information of the journal fields
512 accessed.</para></listitem>
513 </varlistentry>
514
515 <varlistentry>
516 <term><option>--disk-usage</option></term>
517
518 <listitem><para>Shows the current disk
519 usage of all
520 journal files.</para></listitem>
521 </varlistentry>
522
523 <varlistentry>
524 <term><option>--list-catalog
525 <optional><replaceable>ID128...</replaceable></optional>
526 </option></term>
527
528 <listitem><para>List the contents of
529 the message catalog, as table of
530 message IDs plus their short
531 description strings.</para>
532
533 <para>If any
534 <replaceable>ID128</replaceable>s are
535 specified, only those entries are shown.
536 </para>
537 </listitem>
538 </varlistentry>
539
540 <varlistentry>
541 <term><option>--dump-catalog
542 <optional><replaceable>ID128...</replaceable></optional>
543 </option></term>
544
545 <listitem><para>Show the contents of
546 the message catalog, with entries
547 separated by a line consisting of two
548 dashes and the id (the format is the
549 same as <filename>.catalog</filename>
550 files.</para>
551
552 <para>If any
553 <replaceable>ID128</replaceable>s are
554 specified, only those entries are shown.
555 </para>
556 </listitem>
557 </varlistentry>
558
559 <varlistentry>
560 <term><option>--update-catalog</option></term>
561
562 <listitem><para>Update the message
563 catalog index. This command needs to
564 be executed each time new catalog
565 files are installed, removed or
566 updated to rebuild the binary catalog
567 index.</para></listitem>
568 </varlistentry>
569
570 <varlistentry>
571 <term><option>--setup-keys</option></term>
572
573 <listitem><para>Instead of showing
574 journal contents generate a new key
575 pair for Forward Secure Sealing
576 (FSS). This will generate a sealing
577 key and a verification key. The
578 sealing key is stored in the journal
579 data directory and shall remain on the
580 host. The verification key should be
581 stored externally.</para></listitem>
582 </varlistentry>
583
584 <varlistentry>
585 <term><option>--interval=</option></term>
586
587 <listitem><para>Specifies the change
588 interval for the sealing key, when
589 generating an FSS key pair with
590 <option>--setup-keys</option>. Shorter
591 intervals increase CPU consumption but
592 shorten the time range of
593 undetectable journal
594 alterations. Defaults to
595 15min.</para></listitem>
596 </varlistentry>
597
598 <varlistentry>
599 <term><option>--verify</option></term>
600
601 <listitem><para>Check the journal file
602 for internal consistency. If the
603 file has been generated with FSS
604 enabled, and the FSS verification key
605 has been specified with
606 <option>--verify-key=</option>
607 authenticity of the journal file is
608 verified.</para></listitem>
609 </varlistentry>
610
611 <varlistentry>
612 <term><option>--verify-key=</option></term>
613
614 <listitem><para>Specifies the FSS
615 verification key to use for the
616 <option>--verify</option>
617 operation.</para></listitem>
618 </varlistentry>
619
620 </variablelist>
621 </refsect1>
622
623 <refsect1>
624 <title>Exit status</title>
625
626 <para>On success 0 is returned, a non-zero failure
627 code otherwise.</para>
628 </refsect1>
629
630 <refsect1>
631 <title>Environment</title>
632
633 <variablelist class='environment-variables'>
634 <varlistentry>
635 <term><varname>$SYSTEMD_PAGER</varname></term>
636 <listitem><para>Pager to use when
637 <option>--no-pager</option> is not given;
638 overrides <varname>$PAGER</varname>. Setting
639 this to an empty string or the value
640 <literal>cat</literal> is equivalent to passing
641 <option>--no-pager</option>.</para></listitem>
642 </varlistentry>
643 </variablelist>
644 </refsect1>
645
646 <refsect1>
647 <title>Examples</title>
648
649 <para>Without arguments all collected logs are shown
650 unfiltered:</para>
651
652 <programlisting>journalctl</programlisting>
653
654 <para>With one match specified all entries with a field matching the expression are shown:</para>
655
656 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
657
658 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
659
660 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
661
662 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
663
664 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
665
666 <para>If the separator "<literal>+</literal>" is used
667 two expressions may be combined in a logical OR. The
668 following will show all messages from the Avahi
669 service process with the PID 28097 plus all messages
670 from the D-Bus service (from any of its
671 processes):</para>
672
673 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
674
675 <para>Show all logs generated by the D-Bus executable:</para>
676
677 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
678
679 <para>Show all logs of the kernel device node <filename noindex='true'>/dev/sda</filename>:</para>
680
681 <programlisting>journalctl /dev/sda</programlisting>
682
683 </refsect1>
684
685 <refsect1>
686 <title>See Also</title>
687 <para>
688 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
689 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
690 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
691 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
692 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
693 </para>
694 </refsect1>
695
696 </refentry>