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">
27 <title>journalctl</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>journalctl</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>journalctl</refname>
47 <refpurpose>Query the systemd journal</refpurpose>
52 <command>journalctl</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
54 <arg choice="opt" rep="repeat">MATCHES</arg>
59 <title>Description</title>
61 <para><command>journalctl</command> may be used to
62 query the contents of the
63 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
65 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
67 <para>If called without parameter it will show the full
68 contents of the journal, starting with the oldest
69 entry collected.</para>
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
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>
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
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>
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>
113 <title>Options</title>
115 <para>The following options are understood:</para>
119 <term><option>-h</option></term>
120 <term><option>--help</option></term>
122 <listitem><para>Prints a short help
123 text and exits.</para></listitem>
127 <term><option>--version</option></term>
129 <listitem><para>Prints a short version
130 string and exits.</para></listitem>
134 <term><option>--no-pager</option></term>
136 <listitem><para>Do not pipe output into a
137 pager.</para></listitem>
141 <term><option>-l</option></term>
142 <term><option>--full</option></term>
144 <listitem><para>Show all (printable) fields in
145 full.</para></listitem>
149 <term><option>-a</option></term>
150 <term><option>--all</option></term>
152 <listitem><para>Show all fields in
153 full, even if they include unprintable
154 characters or are very
155 long.</para></listitem>
159 <term><option>-f</option></term>
160 <term><option>--follow</option></term>
162 <listitem><para>Show only the most recent
163 journal entries, and continuously print
164 new entries as they are appended to
165 the journal.</para></listitem>
169 <term><option>-e</option></term>
170 <term><option>--pager-end</option></term>
172 <listitem><para>Immediately jump to
173 the end of the journal inside the
174 implied pager tool. This implies
175 <option>-n1000</option> to guarantee
176 that the pager won't buffer logs of
177 unbounded size. This may be overridden
178 with an explicit <option>-n</option>
179 with some other numeric value on the
180 command line. Note that this option is
181 only supported for the
182 <citerefentry><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
183 pager.</para></listitem>
187 <term><option>-n</option></term>
188 <term><option>--lines=</option></term>
190 <listitem><para>Show the most recent
191 journal events and limit the number of
193 <option>--follow</option> is used,
194 this option is implied. The argument,
195 a positive integer, is optional, and
196 defaults to 10. </para></listitem>
200 <term><option>--no-tail</option></term>
202 <listitem><para>Show all stored output
203 lines, even in follow mode. Undoes the
205 <option>--lines=</option>.</para></listitem>
209 <term><option>-r</option></term>
210 <term><option>--reverse</option></term>
212 <listitem><para>Reverse output, so the newest
213 entries are displayed first.</para></listitem>
217 <term><option>-o</option></term>
218 <term><option>--output=</option></term>
220 <listitem><para>Controls the
221 formatting of the journal entries that
222 are shown. Takes one of
223 <literal>short</literal>,
224 <literal>short-monotonic</literal>,
225 <literal>verbose</literal>,
226 <literal>export</literal>,
227 <literal>json</literal>,
228 <literal>json-pretty</literal>,
229 <literal>json-sse</literal>,
230 <literal>cat</literal>. <literal>short</literal>
231 is the default and generates an output
232 that is mostly identical to the
233 formatting of classic syslog log
234 files, showing one line per journal
235 entry. <literal>short-monotonic</literal>
236 is very similar but shows monotonic
237 timestamps instead of wallclock
238 timestamps. <literal>verbose</literal>
239 shows the full structured entry items
241 fields. <literal>export</literal>
242 serializes the journal into a binary
243 (but mostly text-based) stream
244 suitable for backups and network
246 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
247 Export Format</ulink> for more
248 information). <literal>json</literal>
249 formats entries as JSON data
252 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
253 JSON Format</ulink> for more
254 information). <literal>json-pretty</literal>
255 also formats entries as JSON data
256 structures, but formats them in
257 multiple lines in order to make them
259 humans. <literal>json-sse</literal>
260 also formats entries as JSON data
261 structures, but wraps them in a format
263 url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent
264 Events</ulink>. <literal>cat</literal>
265 generates a very terse output only
266 showing the actual message of each
267 journal entry with no meta data, not
268 even a timestamp.</para></listitem>
272 <term><option>-x</option></term>
273 <term><option>--catalog</option></term>
275 <listitem><para>Augment log lines with
276 explanation texts from the message
277 catalog. This will add explanatory
278 help texts to log messages in the
279 output where this is available. These
280 short help texts will explain the
281 context of an error or log event,
282 possible solutions, as well as
283 pointers to support forums, developer
284 documentation and any other relevant
285 manuals. Note that help texts are not
286 available for all messages, but only
287 for selected ones. For more
288 information on the message catalog
289 please refer to the <ulink
290 url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Message
292 Documentation</ulink>.</para></listitem>
296 <term><option>-q</option></term>
297 <term><option>--quiet</option></term>
299 <listitem><para>Suppresses any warning
300 message regarding inaccessible system
301 journals when run as normal
302 user.</para></listitem>
306 <term><option>-m</option></term>
307 <term><option>--merge</option></term>
309 <listitem><para>Show entries
310 interleaved from all available
311 journals, including remote
312 ones.</para></listitem>
316 <term><option>-b</option></term>
317 <term><option>--this-boot</option></term>
319 <listitem><para>Show data only from
320 current boot. This will add a match
321 for <literal>_BOOT_ID=</literal> for
322 the current boot ID of the
323 kernel.</para></listitem>
327 <term><option>-k</option></term>
328 <term><option>--dmesg</option></term>
330 <listitem><para>Show kernel messages from
331 current boot. This implies <option>-b</option>
332 and adds the match <literal>_TRANSPORT=kernel</literal>.
337 <term><option>-u</option></term>
338 <term><option>--unit=</option></term>
340 <listitem><para>Show messages for the
341 specified systemd unit. This will add
342 a match for messages from the unit
343 (<literal>_SYSTEMD_UNIT=</literal>)
344 and additional matches for messages
345 from systemd and messages about
346 coredumps for the specified unit.</para>
347 <para>This parameter can be specified multiple times.
352 <term><option>--user-unit=</option></term>
354 <listitem><para>Show messages for the
355 specified user session unit. This will
356 add a match for messages from the unit
357 (<literal>_SYSTEMD_USER_UNIT=</literal>
358 and <literal>_UID=</literal>) and
359 additional matches for messages from
360 session systemd and messages about
361 coredumps for the specified unit.</para>
362 <para>This parameter can be specified multiple times.
367 <term><option>-p</option></term>
368 <term><option>--priority=</option></term>
370 <listitem><para>Filter output by
371 message priorities or priority
372 ranges. Takes either a single numeric
373 or textual log level (i.e. between
374 0/<literal>emerg</literal> and
375 7/<literal>debug</literal>), or a
376 range of numeric/text log levels in
377 the form FROM..TO. The log levels are
378 the usual syslog log levels as
380 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
381 i.e. <literal>emerg</literal> (0),
382 <literal>alert</literal> (1),
383 <literal>crit</literal> (2),
384 <literal>err</literal> (3),
385 <literal>warning</literal> (4),
386 <literal>notice</literal> (5),
387 <literal>info</literal> (6),
388 <literal>debug</literal> (7). If a
389 single log level is specified all
390 messages with this log level or a
391 lower (hence more important) log level
392 are shown. If a range is specified all
393 messages within the range are shown,
394 including both the start and the end
395 value of the range. This will add
396 <literal>PRIORITY=</literal> matches
398 priorities.</para></listitem>
402 <term><option>-c</option></term>
403 <term><option>--cursor=</option></term>
405 <listitem><para>Start showing entries
406 from the location in the journal
407 specified by the passed
408 cursor.</para></listitem>
412 <term><option>--since=</option></term>
413 <term><option>--until=</option></term>
415 <listitem><para>Start showing entries
416 on or newer than the specified date,
417 or on or older than the specified
418 date, respectively. Date specifications should be of
419 the format "2012-10-30 18:17:16". If
420 the time part is omitted, 00:00:00 is
421 assumed. If only the seconds component
422 is omitted, :00 is assumed. If the
423 date component is omitted, the
424 current day is assumed. Alternatively
426 <literal>yesterday</literal>,
427 <literal>today</literal>,
428 <literal>tomorrow</literal> are
429 understood, which refer to 00:00:00 of
430 the day before the current day, the
431 current day, or the day after the
432 current day, respectively. <literal>now</literal>
433 refers to the current time. Finally,
434 relative times may be specified,
435 prefixed with <literal>-</literal> or
436 <literal>+</literal>, referring to
437 times before or after the current
438 time, respectively.</para></listitem>
442 <term><option>-F</option></term>
443 <term><option>--field=</option></term>
445 <listitem><para>Print all possible
446 data values the specified field can
447 take in all entries of the
448 journal.</para></listitem>
452 <term><option>--system</option></term>
453 <term><option>--user</option></term>
455 <listitem><para>Show messages from
456 system services and the kernel (with
457 <option>--system</option>). Show
458 messages from service of current user
459 (with <option>--user</option>).
460 If neither is specified, show all
461 messages that the user can see.
466 <term><option>-D <replaceable>DIR</replaceable></option></term>
467 <term><option>--directory=<replaceable>DIR</replaceable></option></term>
469 <listitem><para>Takes a directory path
470 as argument. If specified journalctl
471 will operate on the specified journal
473 <replaceable>DIR</replaceable> instead
474 of the default runtime and system
475 journal paths.</para></listitem>
479 <term><option>--file=<replaceable>GLOB</replaceable></option></term>
481 <listitem><para>Takes a file glob as
482 argument. If specified journalctl will
483 operate on the specified journal files
484 matching <replaceable>GLOB</replaceable>
485 instead of the default runtime and
486 system journal paths. May be specified
487 multiple times, in which case files will
488 be suitably interleaved.</para></listitem>
492 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
494 <listitem><para>Takes a directory path
495 as argument. If specified journalctl
496 will operate on catalog file hierarchy
497 underneath the specified directory
498 instead of the root directory
499 (e.g. <option>--update-catalog</option>
501 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
506 <term><option>--new-id128</option></term>
508 <listitem><para>Instead of showing
509 journal contents generate a new 128
510 bit ID suitable for identifying
511 messages. This is intended for usage
512 by developers who need a new
513 identifier for a new message they
514 introduce and want to make
515 recognizable. Will print the new ID in
516 three different formats which can be
517 copied into source code or
518 similar.</para></listitem>
522 <term><option>--header</option></term>
524 <listitem><para>Instead of showing
525 journal contents show internal header
526 information of the journal fields
527 accessed.</para></listitem>
531 <term><option>--disk-usage</option></term>
533 <listitem><para>Shows the current disk
535 journal files.</para></listitem>
539 <term><option>--list-catalog
540 <optional><replaceable>ID128...</replaceable></optional>
543 <listitem><para>List the contents of
544 the message catalog, as table of
545 message IDs plus their short
546 description strings.</para>
549 <replaceable>ID128</replaceable>s are
550 specified, only those entries are shown.
556 <term><option>--dump-catalog
557 <optional><replaceable>ID128...</replaceable></optional>
560 <listitem><para>Show the contents of
561 the message catalog, with entries
562 separated by a line consisting of two
563 dashes and the id (the format is the
564 same as <filename>.catalog</filename>
568 <replaceable>ID128</replaceable>s are
569 specified, only those entries are shown.
575 <term><option>--update-catalog</option></term>
577 <listitem><para>Update the message
578 catalog index. This command needs to
579 be executed each time new catalog
580 files are installed, removed or
581 updated to rebuild the binary catalog
582 index.</para></listitem>
586 <term><option>--setup-keys</option></term>
588 <listitem><para>Instead of showing
589 journal contents generate a new key
590 pair for Forward Secure Sealing
591 (FSS). This will generate a sealing
592 key and a verification key. The
593 sealing key is stored in the journal
594 data directory and shall remain on the
595 host. The verification key should be
596 stored externally. Also see the
597 <option>Seal=</option> option in
598 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
599 for details.</para></listitem>
603 <term><option>--interval=</option></term>
605 <listitem><para>Specifies the change
606 interval for the sealing key, when
607 generating an FSS key pair with
608 <option>--setup-keys</option>. Shorter
609 intervals increase CPU consumption but
610 shorten the time range of
612 alterations. Defaults to
613 15min.</para></listitem>
617 <term><option>--verify</option></term>
619 <listitem><para>Check the journal file
620 for internal consistency. If the
621 file has been generated with FSS
622 enabled, and the FSS verification key
623 has been specified with
624 <option>--verify-key=</option>
625 authenticity of the journal file is
626 verified.</para></listitem>
630 <term><option>--verify-key=</option></term>
632 <listitem><para>Specifies the FSS
633 verification key to use for the
634 <option>--verify</option>
635 operation.</para></listitem>
642 <title>Exit status</title>
644 <para>On success 0 is returned, a non-zero failure
645 code otherwise.</para>
649 <title>Environment</title>
651 <variablelist class='environment-variables'>
653 <term><varname>$SYSTEMD_PAGER</varname></term>
654 <listitem><para>Pager to use when
655 <option>--no-pager</option> is not given;
656 overrides <varname>$PAGER</varname>. Setting
657 this to an empty string or the value
658 <literal>cat</literal> is equivalent to passing
659 <option>--no-pager</option>.</para></listitem>
665 <title>Examples</title>
667 <para>Without arguments all collected logs are shown
670 <programlisting>journalctl</programlisting>
672 <para>With one match specified all entries with a field matching the expression are shown:</para>
674 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
676 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
678 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
680 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
682 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
684 <para>If the separator "<literal>+</literal>" is used
685 two expressions may be combined in a logical OR. The
686 following will show all messages from the Avahi
687 service process with the PID 28097 plus all messages
688 from the D-Bus service (from any of its
691 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
693 <para>Show all logs generated by the D-Bus executable:</para>
695 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
697 <para>Show all logs of the kernel device node <filename noindex='true'>/dev/sda</filename>:</para>
699 <programlisting>journalctl /dev/sda</programlisting>
704 <title>See Also</title>
706 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
707 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
708 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
709 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
710 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>