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 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id="journalctl"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>journalctl</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>journalctl</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>journalctl</refname>
48 <refpurpose>Query the systemd journal</refpurpose>
53 <command>journalctl</command>
54 <arg choice="opt" rep="repeat">OPTIONS</arg>
55 <arg choice="opt" rep="repeat">MATCHES</arg>
60 <title>Description</title>
62 <para><command>journalctl</command> may be used to
63 query the contents of the
64 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
66 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
68 <para>If called without parameters, it will show the full
69 contents of the journal, starting with the oldest
70 entry collected.</para>
72 <para>If one or more match arguments are passed, the
73 output is filtered accordingly. A match is in the
74 format <literal>FIELD=VALUE</literal>,
75 e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>,
76 referring to the components of a structured journal
78 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
79 for a list of well-known fields. If multiple matches
80 are specified matching different fields, the log
81 entries are filtered by both, i.e. the resulting output
82 will show only entries matching all the specified
83 matches of this kind. If two matches apply to the same
84 field, then they are automatically matched as
85 alternatives, i.e. the resulting output will show
86 entries matching any of the specified matches for the
87 same field. Finally, the character
88 <literal>+</literal> may appears as a separate word
89 between other terms on the command line. This causes
90 all matches before and after to be combined in a
91 disjunction (i.e. logical OR).</para>
93 <para>As shortcuts for a few types of field/value
94 matches, file paths may be specified. If a file path
95 refers to an executable file, this is equivalent to an
96 <literal>_EXE=</literal> match for the canonicalized
97 binary path. Similarly, if a path refers to a device
98 node, this is equivalent to a
99 <literal>_KERNEL_DEVICE=</literal> match for the
102 <para>Additional contraints may be added using options
103 <option>--boot</option>, <option>--unit=</option>,
104 etc, to futher limit what entries will be shown
105 (logical AND).</para>
107 <para>Output is interleaved from all accessible
108 journal files, whether they are rotated or currently
109 being written, and regardless of whether they belong to the
110 system itself or are accessible user journals.</para>
112 <para>The set of journal files which will be used
113 can be modified using the <option>--user</option>,
114 <option>--system</option>, <option>--directory</option>,
115 and <option>--file</option> options, see below.</para>
117 <para>All users are granted access to their private
118 per-user journals. However, by default, only root and
119 users who are members of the <literal>systemd-journal</literal>
120 group get access to the system journal and the
121 journals of other users.</para>
123 <para>The output is paged through
124 <command>less</command> by default, and long lines are
125 "truncated" to screen width. The hidden part can be
126 viewed by using the left-arrow and right-arrow
127 keys. Paging can be disabled; see the
128 <option>--no-pager</option> option and the "Environment"
129 section below.</para>
131 <para>When outputing to a tty, lines are colored
132 according to priority: lines of level ERROR and higher
133 are colored red; lines of level NOTICE and higher are
134 highlighted; other lines are displayed normally.
139 <title>Options</title>
141 <para>The following options are understood:</para>
145 <term><option>--no-full</option></term>
146 <term><option>--full</option></term>
147 <term><option>-l</option></term>
149 <listitem><para>Ellipsize fields when
150 they do not fit in available columns.
151 The default is to show full fields,
152 allowing them to wrap or be truncated
153 by the pager, if one is used.</para>
155 <para>The old options
156 <option>-l</option>/<option>--full</option>
157 are not useful anymore, except to undo
158 <option>--no-full</option>.</para></listitem>
162 <term><option>-a</option></term>
163 <term><option>--all</option></term>
165 <listitem><para>Show all fields in
166 full, even if they include unprintable
167 characters or are very
168 long.</para></listitem>
172 <term><option>-f</option></term>
173 <term><option>--follow</option></term>
175 <listitem><para>Show only the most recent
176 journal entries, and continuously print
177 new entries as they are appended to
178 the journal.</para></listitem>
182 <term><option>-e</option></term>
183 <term><option>--pager-end</option></term>
185 <listitem><para>Immediately jump to
186 the end of the journal inside the
187 implied pager tool. This implies
188 <option>-n1000</option> to guarantee
189 that the pager will not buffer logs of
190 unbounded size. This may be overridden
191 with an explicit <option>-n</option>
192 with some other numeric value on the
193 command line. Note that this option is
194 only supported for the
195 <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
196 pager.</para></listitem>
200 <term><option>-n</option></term>
201 <term><option>--lines=</option></term>
203 <listitem><para>Show the most recent
204 journal events and limit the number of
206 <option>--follow</option> is used,
207 this option is implied. The argument,
208 a positive integer, is optional, and
209 defaults to 10. </para></listitem>
213 <term><option>--no-tail</option></term>
215 <listitem><para>Show all stored output
216 lines, even in follow mode. Undoes the
218 <option>--lines=</option>.</para></listitem>
222 <term><option>-r</option></term>
223 <term><option>--reverse</option></term>
225 <listitem><para>Reverse output so that the newest
226 entries are displayed first.</para></listitem>
230 <term><option>-o</option></term>
231 <term><option>--output=</option></term>
233 <listitem><para>Controls the
234 formatting of the journal entries that
235 are shown. Takes one of the following options:
240 <option>short</option>
244 and generates an output
245 that is mostly identical
247 classic syslog files,
249 journal entry.</para>
255 <option>short-iso</option>
258 <para>is very similar,
260 wallclock timestamps.
267 <option>short-precise</option>
270 <para>is very similar,
272 with full microsecond
280 <option>short-monotonic</option>
283 <para>is very similar,
285 timestamps instead of
286 wallclock timestamps.
293 <option>verbose</option>
297 full-structured entry
298 items with all fields.
305 <option>export</option>
309 journal into a binary
310 (but mostly text-based)
314 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
315 Export Format</ulink>
323 <option>json</option>
326 <para>formats entries
327 as JSON data structures,
328 one per line (see <ulink
329 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
330 JSON Format</ulink> for
331 more information).</para>
337 <option>json-pretty</option>
340 <para>formats entries as
341 JSON data structures,
343 multiple lines in order
345 readable by humans.</para>
351 <option>json-sse</option>
354 <para>formats entries as
355 JSON data structures,
357 format suitable for <ulink
358 url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent
359 Events</ulink>.</para>
368 <para>generates a very
371 message of each journal
372 entry with no metadata,
373 not even a timestamp.
382 <term><option>-x</option></term>
383 <term><option>--catalog</option></term>
385 <listitem><para>Augment log lines with
386 explanation texts from the message
387 catalog. This will add explanatory
388 help texts to log messages in the
389 output where this is available. These
390 short help texts will explain the
391 context of an error or log event,
392 possible solutions, as well as
393 pointers to support forums, developer
394 documentation, and any other relevant
395 manuals. Note that help texts are not
396 available for all messages, but only
397 for selected ones. For more
398 information on the message catalog,
399 please refer to the <ulink
400 url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Message
402 Documentation</ulink>.</para>
404 <para>Note: when attaching
405 <command>journalctl</command> output
406 to bug reports, please do
407 <emphasis>not</emphasis> use
408 <option>-x</option>.</para>
413 <term><option>-q</option></term>
414 <term><option>--quiet</option></term>
416 <listitem><para>Suppresses any warning
417 messages regarding inaccessible system
418 journals when run as a normal
419 user.</para></listitem>
423 <term><option>-m</option></term>
424 <term><option>--merge</option></term>
426 <listitem><para>Show entries
427 interleaved from all available
428 journals, including remote
429 ones.</para></listitem>
433 <term><option>-b <optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional></option></term>
434 <term><option>--boot=<optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional></option></term>
436 <listitem><para>Show messages from a specific
437 boot. This will add a match for
438 <literal>_BOOT_ID=</literal>.</para>
440 <para>The argument may be empty, in which case
441 logs for the current boot will be shown.</para>
443 <para>If the boot ID is omitted, a positive
444 <replaceable>offset</replaceable> will look up
445 the boots starting from the beginning of the
446 journal, and a equal-or-less-than zero
447 <replaceable>offset</replaceable> will look up
448 boots starting from the end of the
449 journal. Thus, <constant>1</constant> means the
450 first boot found in the journal in
451 chronological order, <constant>2</constant> the
452 second and so on; while <constant>-0</constant>
453 is the last boot, <constant>-1</constant> the
454 boot before last, and so on. An empty
455 <replaceable>offset</replaceable> is equivalent
456 to specifying <constant>-0</constant>, except
457 when the current boot is not the last boot
458 (e.g. because <option>--directory</option> was
459 specified to look at logs from a different
462 <para>If the 32-character
463 <replaceable>ID</replaceable> is specified, it
464 may optionally be followed by
465 <replaceable>offset</replaceable> which
466 identifies the boot relative to the one given by
467 boot <replaceable>ID</replaceable>. Negative
468 values mean earlier boots and a positive values
470 <replaceable>offset</replaceable> is not
471 specified, a value of zero is assumed, and the
472 logs for the boot given by
473 <replaceable>ID</replaceable> are shown.
480 <term><option>--list-boots</option></term>
482 <listitem><para>Show a tabular list of
483 boot numbers (relative to the current
484 boot), their IDs, and the timestamps
485 of the first and last message
486 pertaining to the boot.
491 <term><option>-k</option></term>
492 <term><option>--dmesg</option></term>
494 <listitem><para>Show only kernel messages. This
495 implies <option>-b</option> and adds the match
496 <literal>_TRANSPORT=kernel</literal>.
501 <term><option>-u</option></term>
502 <term><option>--unit=<replaceable>UNIT</replaceable>|<replaceable>PATTERN</replaceable></option></term>
504 <listitem><para>Show messages for the
505 specified systemd unit
506 <replaceable>UNIT</replaceable> (such
507 as a service unit), or for any of the
509 <replaceable>PATTERN</replaceable>.
510 If a pattern is specified, a list of
511 unit names found in the journal is
512 compared with the specified pattern
513 and all that match are used. For each
514 unit name, a match is added for
515 messages from the unit
516 (<literal>_SYSTEMD_UNIT=<replaceable>UNIT</replaceable></literal>),
517 along with additional matches for
518 messages from systemd and messages
519 about coredumps for the specified
522 <para>This parameter can be specified
523 multiple times.</para></listitem>
527 <term><option>--user-unit=</option></term>
529 <listitem><para>Show messages for the
530 specified user session unit. This will
531 add a match for messages from the unit
532 (<literal>_SYSTEMD_USER_UNIT=</literal>
533 and <literal>_UID=</literal>) and
534 additional matches for messages from
535 session systemd and messages about
536 coredumps for the specified unit.</para>
537 <para>This parameter can be specified multiple times.
542 <term><option>-p</option></term>
543 <term><option>--priority=</option></term>
545 <listitem><para>Filter output by
546 message priorities or priority
547 ranges. Takes either a single numeric
548 or textual log level (i.e. between
549 0/<literal>emerg</literal> and
550 7/<literal>debug</literal>), or a
551 range of numeric/text log levels in
552 the form FROM..TO. The log levels are
553 the usual syslog log levels as
555 <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
556 i.e. <literal>emerg</literal> (0),
557 <literal>alert</literal> (1),
558 <literal>crit</literal> (2),
559 <literal>err</literal> (3),
560 <literal>warning</literal> (4),
561 <literal>notice</literal> (5),
562 <literal>info</literal> (6),
563 <literal>debug</literal> (7). If a
564 single log level is specified, all
565 messages with this log level or a
566 lower (hence more important) log level
567 are shown. If a range is specified, all
568 messages within the range are shown,
569 including both the start and the end
570 value of the range. This will add
571 <literal>PRIORITY=</literal> matches
573 priorities.</para></listitem>
577 <term><option>-c</option></term>
578 <term><option>--cursor=</option></term>
580 <listitem><para>Start showing entries
581 from the location in the journal
582 specified by the passed
583 cursor.</para></listitem>
587 <term><option>--after-cursor=</option></term>
589 <listitem><para>Start showing entries
590 from the location in the journal
591 <emphasis>after</emphasis> the
592 location specified by the this cursor.
593 The cursor is shown when the
594 <option>--show-cursor</option> option
595 is used.</para></listitem>
599 <term><option>--show-cursor</option></term>
601 <listitem><para>The cursor is shown after the last
602 entry after two dashes:</para>
603 <programlisting>-- cursor: s=0639...</programlisting>
604 <para>The format of the cursor is private
605 and subject to change.</para></listitem>
609 <term><option>--since=</option></term>
610 <term><option>--until=</option></term>
612 <listitem><para>Start showing entries
613 on or newer than the specified date,
614 or on or older than the specified
615 date, respectively. Date specifications
616 should be of the format
617 <literal>2012-10-30 18:17:16</literal>.
618 If the time part is omitted,
619 <literal>00:00:00</literal> is assumed.
620 If only the seconds component is omitted,
621 <literal>:00</literal> is assumed. If the
622 date component is omitted, the current
623 day is assumed. Alternatively the strings
624 <literal>yesterday</literal>,
625 <literal>today</literal>,
626 <literal>tomorrow</literal> are
627 understood, which refer to 00:00:00 of
628 the day before the current day, the
629 current day, or the day after the
630 current day, respectively. <literal>now</literal>
631 refers to the current time. Finally,
632 relative times may be specified,
633 prefixed with <literal>-</literal> or
634 <literal>+</literal>, referring to
635 times before or after the current
636 time, respectively.</para></listitem>
640 <term><option>-F</option></term>
641 <term><option>--field=</option></term>
643 <listitem><para>Print all possible
644 data values the specified field can
645 take in all entries of the
646 journal.</para></listitem>
650 <term><option>--system</option></term>
651 <term><option>--user</option></term>
653 <listitem><para>Show messages from
654 system services and the kernel (with
655 <option>--system</option>). Show
656 messages from service of current user
657 (with <option>--user</option>).
658 If neither is specified, show all
659 messages that the user can see.
664 <term><option>-M</option></term>
665 <term><option>--machine=</option></term>
667 <listitem><para>Show messages from a
668 running, local container. Specify a
669 container name to connect
670 to.</para></listitem>
674 <term><option>-D <replaceable>DIR</replaceable></option></term>
675 <term><option>--directory=<replaceable>DIR</replaceable></option></term>
677 <listitem><para>Takes a directory path
678 as argument. If specified, journalctl
679 will operate on the specified journal
681 <replaceable>DIR</replaceable> instead
682 of the default runtime and system
683 journal paths.</para></listitem>
687 <term><option>--file=<replaceable>GLOB</replaceable></option></term>
689 <listitem><para>Takes a file glob as an
690 argument. If specified, journalctl will
691 operate on the specified journal files
692 matching <replaceable>GLOB</replaceable>
693 instead of the default runtime and
694 system journal paths. May be specified
695 multiple times, in which case files will
696 be suitably interleaved.</para></listitem>
700 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
702 <listitem><para>Takes a directory path
703 as an argument. If specified, journalctl
704 will operate on catalog file hierarchy
705 underneath the specified directory
706 instead of the root directory
707 (e.g. <option>--update-catalog</option>
709 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
714 <term><option>--new-id128</option></term>
716 <listitem><para>Instead of showing
717 journal contents, generate a new 128-bit
718 ID suitable for identifying
719 messages. This is intended for usage
720 by developers who need a new
721 identifier for a new message they
722 introduce and want to make
723 recognizable. This will print the new ID in
724 three different formats which can be
725 copied into source code or
726 similar.</para></listitem>
730 <term><option>--header</option></term>
732 <listitem><para>Instead of showing
733 journal contents, show internal header
734 information of the journal fields
735 accessed.</para></listitem>
739 <term><option>--disk-usage</option></term>
741 <listitem><para>Shows the current disk
743 journal files.</para></listitem>
747 <term><option>--list-catalog
748 <optional><replaceable>128-bit-ID...</replaceable></optional>
751 <listitem><para>List the contents of
752 the message catalog as a table of
753 message IDs, plus their short
754 description strings.</para>
757 <replaceable>128-bit-ID</replaceable>s are
758 specified, only those entries are shown.
764 <term><option>--dump-catalog
765 <optional><replaceable>128-bit-ID...</replaceable></optional>
768 <listitem><para>Show the contents of
769 the message catalog, with entries
770 separated by a line consisting of two
771 dashes and the ID (the format is the
772 same as <filename>.catalog</filename>
776 <replaceable>128-bit-ID</replaceable>s are
777 specified, only those entries are shown.
783 <term><option>--update-catalog</option></term>
785 <listitem><para>Update the message
786 catalog index. This command needs to
787 be executed each time new catalog
788 files are installed, removed, or
789 updated to rebuild the binary catalog
790 index.</para></listitem>
794 <term><option>--setup-keys</option></term>
796 <listitem><para>Instead of showing
797 journal contents, generate a new key
798 pair for Forward Secure Sealing
799 (FSS). This will generate a sealing
800 key and a verification key. The
801 sealing key is stored in the journal
802 data directory and shall remain on the
803 host. The verification key should be
804 stored externally. Refer to the
805 <option>Seal=</option> option in
806 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
807 for information on Forward Secure
808 Sealing and for a link to a refereed
809 scholarly paper detailing the
810 cryptographic theory it is based on.
815 <term><option>--force</option></term>
818 <option>--setup-keys</option> is passed and
819 Forward Secure Sealing (FSS) has already been
820 configured, recreate FSS keys.</para></listitem>
824 <term><option>--interval=</option></term>
826 <listitem><para>Specifies the change
827 interval for the sealing key when
828 generating an FSS key pair with
829 <option>--setup-keys</option>. Shorter
830 intervals increase CPU consumption but
831 shorten the time range of
833 alterations. Defaults to
834 15min.</para></listitem>
838 <term><option>--verify</option></term>
840 <listitem><para>Check the journal file
841 for internal consistency. If the
842 file has been generated with FSS
843 enabled and the FSS verification key
844 has been specified with
845 <option>--verify-key=</option>,
846 authenticity of the journal file is
847 verified.</para></listitem>
851 <term><option>--verify-key=</option></term>
853 <listitem><para>Specifies the FSS
854 verification key to use for the
855 <option>--verify</option>
856 operation.</para></listitem>
859 <xi:include href="standard-options.xml" xpointer="help" />
860 <xi:include href="standard-options.xml" xpointer="version" />
861 <xi:include href="standard-options.xml" xpointer="no-pager" />
866 <title>Exit status</title>
868 <para>On success, 0 is returned; otherwise, a non-zero
869 failure code is returned.</para>
872 <xi:include href="less-variables.xml" />
875 <title>Examples</title>
877 <para>Without arguments, all collected logs are shown
880 <programlisting>journalctl</programlisting>
882 <para>With one match specified, all entries with a field matching the expression are shown:</para>
884 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
886 <para>If two different fields are matched, only entries matching both expressions at the same time are shown:</para>
888 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
890 <para>If two matches refer to the same field, all entries matching either expression are shown:</para>
892 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
894 <para>If the separator <literal>+</literal> is used,
895 two expressions may be combined in a logical OR. The
896 following will show all messages from the Avahi
897 service process with the PID 28097 plus all messages
898 from the D-Bus service (from any of its
901 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
903 <para>Show all logs generated by the D-Bus executable:</para>
905 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
907 <para>Show all logs of the kernel device node <filename noindex='true'>/dev/sda</filename>:</para>
909 <programlisting>journalctl /dev/sda</programlisting>
911 <para>Show all kernel logs from previous boot:</para>
913 <programlisting>journalctl -k -b -1</programlisting>
915 <para>Show a live log display from a system service <filename>apache.service</filename>:</para>
917 <programlisting>journalctl -f -u apache</programlisting>
922 <title>See Also</title>
924 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
925 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
926 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
927 <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
928 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
929 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>