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 parameters, 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. Similarly, 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 of 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 will not 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
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
419 should be of the format
420 <literal>2012-10-30 18:17:16</literal>.
421 If the time part is omitted,
422 <literal>00:00:00</literal> is assumed.
423 If only the seconds component is omitted,
424 <literal>:00</literal> is assumed. If the
425 date component is omitted, the current
426 day is assumed. Alternatively the strings
427 <literal>yesterday</literal>,
428 <literal>today</literal>,
429 <literal>tomorrow</literal> are
430 understood, which refer to 00:00:00 of
431 the day before the current day, the
432 current day, or the day after the
433 current day, respectively. <literal>now</literal>
434 refers to the current time. Finally,
435 relative times may be specified,
436 prefixed with <literal>-</literal> or
437 <literal>+</literal>, referring to
438 times before or after the current
439 time, respectively.</para></listitem>
443 <term><option>-F</option></term>
444 <term><option>--field=</option></term>
446 <listitem><para>Print all possible
447 data values the specified field can
448 take in all entries of the
449 journal.</para></listitem>
453 <term><option>--system</option></term>
454 <term><option>--user</option></term>
456 <listitem><para>Show messages from
457 system services and the kernel (with
458 <option>--system</option>). Show
459 messages from service of current user
460 (with <option>--user</option>).
461 If neither is specified, show all
462 messages that the user can see.
467 <term><option>-D <replaceable>DIR</replaceable></option></term>
468 <term><option>--directory=<replaceable>DIR</replaceable></option></term>
470 <listitem><para>Takes a directory path
471 as argument. If specified, journalctl
472 will operate on the specified journal
474 <replaceable>DIR</replaceable> instead
475 of the default runtime and system
476 journal paths.</para></listitem>
480 <term><option>--file=<replaceable>GLOB</replaceable></option></term>
482 <listitem><para>Takes a file glob as
483 argument. If specified, journalctl will
484 operate on the specified journal files
485 matching <replaceable>GLOB</replaceable>
486 instead of the default runtime and
487 system journal paths. May be specified
488 multiple times, in which case files will
489 be suitably interleaved.</para></listitem>
493 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
495 <listitem><para>Takes a directory path
496 as argument. If specified, journalctl
497 will operate on catalog file hierarchy
498 underneath the specified directory
499 instead of the root directory
500 (e.g. <option>--update-catalog</option>
502 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
507 <term><option>--new-id128</option></term>
509 <listitem><para>Instead of showing
510 journal contents, generate a new 128
511 bit ID suitable for identifying
512 messages. This is intended for usage
513 by developers who need a new
514 identifier for a new message they
515 introduce and want to make
516 recognizable. This will print the new ID in
517 three different formats which can be
518 copied into source code or
519 similar.</para></listitem>
523 <term><option>--header</option></term>
525 <listitem><para>Instead of showing
526 journal contents, show internal header
527 information of the journal fields
528 accessed.</para></listitem>
532 <term><option>--disk-usage</option></term>
534 <listitem><para>Shows the current disk
536 journal files.</para></listitem>
540 <term><option>--list-catalog
541 <optional><replaceable>ID128...</replaceable></optional>
544 <listitem><para>List the contents of
545 the message catalog, as table of
546 message IDs plus their short
547 description strings.</para>
550 <replaceable>ID128</replaceable>s are
551 specified, only those entries are shown.
557 <term><option>--dump-catalog
558 <optional><replaceable>ID128...</replaceable></optional>
561 <listitem><para>Show the contents of
562 the message catalog, with entries
563 separated by a line consisting of two
564 dashes and the id (the format is the
565 same as <filename>.catalog</filename>
569 <replaceable>ID128</replaceable>s are
570 specified, only those entries are shown.
576 <term><option>--update-catalog</option></term>
578 <listitem><para>Update the message
579 catalog index. This command needs to
580 be executed each time new catalog
581 files are installed, removed or
582 updated to rebuild the binary catalog
583 index.</para></listitem>
587 <term><option>--setup-keys</option></term>
589 <listitem><para>Instead of showing
590 journal contents, generate a new key
591 pair for Forward Secure Sealing
592 (FSS). This will generate a sealing
593 key and a verification key. The
594 sealing key is stored in the journal
595 data directory and shall remain on the
596 host. The verification key should be
597 stored externally. Also see the
598 <option>Seal=</option> option in
599 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
600 for details.</para></listitem>
604 <term><option>--interval=</option></term>
606 <listitem><para>Specifies the change
607 interval for the sealing key when
608 generating an FSS key pair with
609 <option>--setup-keys</option>. Shorter
610 intervals increase CPU consumption but
611 shorten the time range of
613 alterations. Defaults to
614 15min.</para></listitem>
618 <term><option>--verify</option></term>
620 <listitem><para>Check the journal file
621 for internal consistency. If the
622 file has been generated with FSS
623 enabled and the FSS verification key
624 has been specified with
625 <option>--verify-key=</option>,
626 authenticity of the journal file is
627 verified.</para></listitem>
631 <term><option>--verify-key=</option></term>
633 <listitem><para>Specifies the FSS
634 verification key to use for the
635 <option>--verify</option>
636 operation.</para></listitem>
643 <title>Exit status</title>
645 <para>On success, 0 is returned, a non-zero failure
646 code otherwise.</para>
650 <title>Environment</title>
652 <variablelist class='environment-variables'>
654 <term><varname>$SYSTEMD_PAGER</varname></term>
655 <listitem><para>Pager to use when
656 <option>--no-pager</option> is not given;
657 overrides <varname>$PAGER</varname>. Setting
658 this to an empty string or the value
659 <literal>cat</literal> is equivalent to passing
660 <option>--no-pager</option>.</para></listitem>
666 <title>Examples</title>
668 <para>Without arguments, all collected logs are shown
671 <programlisting>journalctl</programlisting>
673 <para>With one match specified, all entries with a field matching the expression are shown:</para>
675 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
677 <para>If two different fields are matched, only entries matching both expressions at the same time are shown:</para>
679 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
681 <para>If two matches refer to the same field, all entries matching either expression are shown:</para>
683 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
685 <para>If the separator <literal>+</literal> is used,
686 two expressions may be combined in a logical OR. The
687 following will show all messages from the Avahi
688 service process with the PID 28097 plus all messages
689 from the D-Bus service (from any of its
692 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
694 <para>Show all logs generated by the D-Bus executable:</para>
696 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
698 <para>Show all logs of the kernel device node <filename noindex='true'>/dev/sda</filename>:</para>
700 <programlisting>journalctl /dev/sda</programlisting>
705 <title>See Also</title>
707 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
708 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
709 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
710 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
711 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>