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>--full</option></term>
143 <listitem><para>Show all (printable) fields in
144 full.</para></listitem>
148 <term><option>-a</option></term>
149 <term><option>--all</option></term>
151 <listitem><para>Show all fields in
152 full, even if they include unprintable
153 characters or are very
154 long.</para></listitem>
158 <term><option>-f</option></term>
159 <term><option>--follow</option></term>
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>
168 <term><option>-e</option></term>
169 <term><option>--pager-end</option></term>
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>
186 <term><option>-n</option></term>
187 <term><option>--lines=</option></term>
189 <listitem><para>Show the most recent
190 journal events and limit the number of
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>
199 <term><option>--no-tail</option></term>
201 <listitem><para>Show all stored output
202 lines, even in follow mode. Undoes the
204 <option>--lines=</option>.</para></listitem>
208 <term><option>-r</option></term>
209 <term><option>--reverse</option></term>
211 <listitem><para>Reverse output, so the newest
212 entries are displayed first.</para></listitem>
216 <term><option>-o</option></term>
217 <term><option>--output=</option></term>
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
240 fields. <literal>export</literal>
241 serializes the journal into a binary
242 (but mostly text-based) stream
243 suitable for backups and network
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
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
258 humans. <literal>json-sse</literal>
259 also formats entries as JSON data
260 structures, but wraps them in a format
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>
271 <term><option>-x</option></term>
272 <term><option>--catalog</option></term>
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
291 Documentation</ulink>.</para></listitem>
295 <term><option>-q</option></term>
296 <term><option>--quiet</option></term>
298 <listitem><para>Suppresses any warning
299 message regarding inaccessible system
300 journals when run as normal
301 user.</para></listitem>
305 <term><option>-m</option></term>
306 <term><option>--merge</option></term>
308 <listitem><para>Show entries
309 interleaved from all available
310 journals, including remote
311 ones.</para></listitem>
315 <term><option>-b</option></term>
316 <term><option>--this-boot</option></term>
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>
326 <term><option>-u</option></term>
327 <term><option>--unit=</option></term>
329 <listitem><para>Show messages for the
330 specified systemd unit. This will add
331 a match for messages from the unit
332 (<literal>_SYSTEMD_UNIT=</literal>)
333 and additional matches for messages
334 from systemd and messages about
335 coredumps for the specified unit.
340 <term><option>--user-unit=</option></term>
342 <listitem><para>Show messages for the
343 specified user session unit. This will
344 add a match for messages from the unit
345 (<literal>_SYSTEMD_USER_UNIT=</literal>
346 and <literal>_UID=</literal>) and
347 additional matches for messages from
348 session systemd and messages about
349 coredumps for the specified unit.
354 <term><option>-p</option></term>
355 <term><option>--priority=</option></term>
357 <listitem><para>Filter output by
358 message priorities or priority
359 ranges. Takes either a single numeric
360 or textual log level (i.e. between
361 0/<literal>emerg</literal> and
362 7/<literal>debug</literal>), or a
363 range of numeric/text log levels in
364 the form FROM..TO. The log levels are
365 the usual syslog log levels as
367 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
368 i.e. <literal>emerg</literal> (0),
369 <literal>alert</literal> (1),
370 <literal>crit</literal> (2),
371 <literal>err</literal> (3),
372 <literal>warning</literal> (4),
373 <literal>notice</literal> (5),
374 <literal>info</literal> (6),
375 <literal>debug</literal> (7). If a
376 single log level is specified all
377 messages with this log level or a
378 lower (hence more important) log level
379 are shown. If a range is specified all
380 messages within the range are shown,
381 including both the start and the end
382 value of the range. This will add
383 <literal>PRIORITY=</literal> matches
385 priorities.</para></listitem>
389 <term><option>-c</option></term>
390 <term><option>--cursor=</option></term>
392 <listitem><para>Start showing entries
393 from the location in the journal
394 specified by the passed
395 cursor.</para></listitem>
399 <term><option>--since=</option></term>
400 <term><option>--until=</option></term>
402 <listitem><para>Start showing entries
403 on or newer than the specified date,
404 or on or older than the specified
405 date, respectively. Date specifications should be of
406 the format "2012-10-30 18:17:16". If
407 the time part is omitted, 00:00:00 is
408 assumed. If only the seconds component
409 is omitted, :00 is assumed. If the
410 date component is omitted, the
411 current day is assumed. Alternatively
413 <literal>yesterday</literal>,
414 <literal>today</literal>,
415 <literal>tomorrow</literal> are
416 understood, which refer to 00:00:00 of
417 the day before the current day, the
418 current day, or the day after the
419 current day, respectively. <literal>now</literal>
420 refers to the current time. Finally,
421 relative times may be specified,
422 prefixed with <literal>-</literal> or
423 <literal>+</literal>, referring to
424 times before or after the current
425 time, respectively.</para></listitem>
429 <term><option>-F</option></term>
430 <term><option>--field=</option></term>
432 <listitem><para>Print all possible
433 data values the specified field can
434 take in all entries of the
435 journal.</para></listitem>
439 <term><option>-D</option></term>
440 <term><option>--directory=</option></term>
442 <listitem><para>Takes a
443 directory path as argument. If
444 specified journalctl will operate on the
445 specified journal directory instead of
446 the default runtime and system journal
447 paths.</para></listitem>
451 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
453 <listitem><para>Takes a directory path
454 as argument. If specified journalctl
455 will operate on catalog file hierarchy
456 underneath the specified directory
457 instead of the root directory
458 (e.g. <option>--update-catalog</option>
460 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
465 <term><option>--new-id128</option></term>
467 <listitem><para>Instead of showing
468 journal contents generate a new 128
469 bit ID suitable for identifying
470 messages. This is intended for usage
471 by developers who need a new
472 identifier for a new message they
473 introduce and want to make
474 recognizable. Will print the new ID in
475 three different formats which can be
476 copied into source code or
477 similar.</para></listitem>
481 <term><option>--header</option></term>
483 <listitem><para>Instead of showing
484 journal contents show internal header
485 information of the journal fields
486 accessed.</para></listitem>
490 <term><option>--disk-usage</option></term>
492 <listitem><para>Shows the current disk
494 journal files.</para></listitem>
498 <term><option>--list-catalog
499 <optional><replaceable>ID128...</replaceable></optional>
502 <listitem><para>List the contents of
503 the message catalog, as table of
504 message IDs plus their short
505 description strings.</para>
508 <replaceable>ID128</replaceable>s are
509 specified, only those entries are shown.
515 <term><option>--dump-catalog
516 <optional><replaceable>ID128...</replaceable></optional>
519 <listitem><para>Show the contents of
520 the message catalog, with entries
521 separated by a line consisting of two
522 dashes and the id (the format is the
523 same as <filename>.catalog</filename>
527 <replaceable>ID128</replaceable>s are
528 specified, only those entries are shown.
534 <term><option>--update-catalog</option></term>
536 <listitem><para>Update the message
537 catalog index. This command needs to
538 be executed each time new catalog
539 files are installed, removed or
540 updated to rebuild the binary catalog
541 index.</para></listitem>
545 <term><option>--setup-keys</option></term>
547 <listitem><para>Instead of showing
548 journal contents generate a new key
549 pair for Forward Secure Sealing
550 (FSS). This will generate a sealing
551 key and a verification key. The
552 sealing key is stored in the journal
553 data directory and shall remain on the
554 host. The verification key should be
555 stored externally.</para></listitem>
559 <term><option>--interval=</option></term>
561 <listitem><para>Specifies the change
562 interval for the sealing key, when
563 generating an FSS key pair with
564 <option>--setup-keys</option>. Shorter
565 intervals increase CPU consumption but
566 shorten the time range of
568 alterations. Defaults to
569 15min.</para></listitem>
573 <term><option>--verify</option></term>
575 <listitem><para>Check the journal file
576 for internal consistency. If the
577 file has been generated with FSS
578 enabled, and the FSS verification key
579 has been specified with
580 <option>--verify-key=</option>
581 authenticity of the journal file is
582 verified.</para></listitem>
586 <term><option>--verify-key=</option></term>
588 <listitem><para>Specifies the FSS
589 verification key to use for the
590 <option>--verify</option>
591 operation.</para></listitem>
598 <title>Exit status</title>
600 <para>On success 0 is returned, a non-zero failure
601 code otherwise.</para>
605 <title>Environment</title>
607 <variablelist class='environment-variables'>
609 <term><varname>$SYSTEMD_PAGER</varname></term>
610 <listitem><para>Pager to use when
611 <option>--no-pager</option> is not given;
612 overrides <varname>$PAGER</varname>. Setting
613 this to an empty string or the value
614 <literal>cat</literal> is equivalent to passing
615 <option>--no-pager</option>.</para></listitem>
621 <title>Examples</title>
623 <para>Without arguments all collected logs are shown
626 <programlisting>journalctl</programlisting>
628 <para>With one match specified all entries with a field matching the expression are shown:</para>
630 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
632 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
634 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
636 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
638 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
640 <para>If the separator "<literal>+</literal>" is used
641 two expressions may be combined in a logical OR. The
642 following will show all messages from the Avahi
643 service process with the PID 28097 plus all messages
644 from the D-Bus service (from any of its
647 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
649 <para>Show all logs generated by the D-Bus executable:</para>
651 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
653 <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
655 <programlisting>journalctl /dev/sda</programlisting>
660 <title>See Also</title>
662 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
663 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
664 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
665 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
666 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>