]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/journalctl.xml
564634b757da04f9d77f2ff80d53271b9e49eb96
[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>-l</option></term>
142 <term><option>--full</option></term>
143
144 <listitem><para>Show all (printable) fields in
145 full.</para></listitem>
146 </varlistentry>
147
148 <varlistentry>
149 <term><option>-a</option></term>
150 <term><option>--all</option></term>
151
152 <listitem><para>Show all fields in
153 full, even if they include unprintable
154 characters or are very
155 long.</para></listitem>
156 </varlistentry>
157
158 <varlistentry>
159 <term><option>-f</option></term>
160 <term><option>--follow</option></term>
161
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>
166 </varlistentry>
167
168 <varlistentry>
169 <term><option>-e</option></term>
170 <term><option>--pager-end</option></term>
171
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>
184 </varlistentry>
185
186 <varlistentry>
187 <term><option>-n</option></term>
188 <term><option>--lines=</option></term>
189
190 <listitem><para>Show the most recent
191 journal events and limit the number of
192 events shown. If
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>
197 </varlistentry>
198
199 <varlistentry>
200 <term><option>--no-tail</option></term>
201
202 <listitem><para>Show all stored output
203 lines, even in follow mode. Undoes the
204 effect of
205 <option>--lines=</option>.</para></listitem>
206 </varlistentry>
207
208 <varlistentry>
209 <term><option>-r</option></term>
210 <term><option>--reverse</option></term>
211
212 <listitem><para>Reverse output, so the newest
213 entries are displayed first.</para></listitem>
214 </varlistentry>
215
216 <varlistentry>
217 <term><option>-o</option></term>
218 <term><option>--output=</option></term>
219
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
240 with all
241 fields. <literal>export</literal>
242 serializes the journal into a binary
243 (but mostly text-based) stream
244 suitable for backups and network
245 transfer (see <ulink
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
250 structures, one per
251 line (see <ulink
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
258 more readable for
259 humans. <literal>json-sse</literal>
260 also formats entries as JSON data
261 structures, but wraps them in a format
262 suitable for <ulink
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>
269 </varlistentry>
270
271 <varlistentry>
272 <term><option>-x</option></term>
273 <term><option>--catalog</option></term>
274
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
291 Catalog Developer
292 Documentation</ulink>.</para></listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term><option>-q</option></term>
297 <term><option>--quiet</option></term>
298
299 <listitem><para>Suppresses any warning
300 message regarding inaccessible system
301 journals when run as normal
302 user.</para></listitem>
303 </varlistentry>
304
305 <varlistentry>
306 <term><option>-m</option></term>
307 <term><option>--merge</option></term>
308
309 <listitem><para>Show entries
310 interleaved from all available
311 journals, including remote
312 ones.</para></listitem>
313 </varlistentry>
314
315 <varlistentry>
316 <term><option>-b</option></term>
317 <term><option>--this-boot</option></term>
318
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>
324 </varlistentry>
325
326 <varlistentry>
327 <term><option>-k</option></term>
328 <term><option>--dmesg</option></term>
329
330 <listitem><para>Show kernel messages from
331 current boot. This implies <option>-b</option>
332 and adds the match <literal>_TRANSPORT=kernel</literal>.
333 </para></listitem>
334 </varlistentry>
335
336 <varlistentry>
337 <term><option>-u</option></term>
338 <term><option>--unit=</option></term>
339
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.
348 </para></listitem>
349 </varlistentry>
350
351 <varlistentry>
352 <term><option>--user-unit=</option></term>
353
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.
363 </para></listitem>
364 </varlistentry>
365
366 <varlistentry>
367 <term><option>-p</option></term>
368 <term><option>--priority=</option></term>
369
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
379 documented in
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
397 for the specified
398 priorities.</para></listitem>
399 </varlistentry>
400
401 <varlistentry>
402 <term><option>-c</option></term>
403 <term><option>--cursor=</option></term>
404
405 <listitem><para>Start showing entries
406 from the location in the journal
407 specified by the passed
408 cursor.</para></listitem>
409 </varlistentry>
410
411 <varlistentry>
412 <term><option>--since=</option></term>
413 <term><option>--until=</option></term>
414
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
425 the strings
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>
439 </varlistentry>
440
441 <varlistentry>
442 <term><option>-F</option></term>
443 <term><option>--field=</option></term>
444
445 <listitem><para>Print all possible
446 data values the specified field can
447 take in all entries of the
448 journal.</para></listitem>
449 </varlistentry>
450
451 <varlistentry>
452 <term><option>--system</option></term>
453 <term><option>--user</option></term>
454
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.
462 </para></listitem>
463 </varlistentry>
464
465 <varlistentry>
466 <term><option>-D <replaceable>DIR</replaceable></option></term>
467 <term><option>--directory=<replaceable>DIR</replaceable></option></term>
468
469 <listitem><para>Takes a directory path
470 as argument. If specified journalctl
471 will operate on the specified journal
472 directory
473 <replaceable>DIR</replaceable> instead
474 of the default runtime and system
475 journal paths.</para></listitem>
476 </varlistentry>
477
478 <varlistentry>
479 <term><option>--file=<replaceable>GLOB</replaceable></option></term>
480
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>
489 </varlistentry>
490
491 <varlistentry>
492 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
493
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>
500 will create
501 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
502 </para></listitem>
503 </varlistentry>
504
505 <varlistentry>
506 <term><option>--new-id128</option></term>
507
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>
519 </varlistentry>
520
521 <varlistentry>
522 <term><option>--header</option></term>
523
524 <listitem><para>Instead of showing
525 journal contents show internal header
526 information of the journal fields
527 accessed.</para></listitem>
528 </varlistentry>
529
530 <varlistentry>
531 <term><option>--disk-usage</option></term>
532
533 <listitem><para>Shows the current disk
534 usage of all
535 journal files.</para></listitem>
536 </varlistentry>
537
538 <varlistentry>
539 <term><option>--list-catalog
540 <optional><replaceable>ID128...</replaceable></optional>
541 </option></term>
542
543 <listitem><para>List the contents of
544 the message catalog, as table of
545 message IDs plus their short
546 description strings.</para>
547
548 <para>If any
549 <replaceable>ID128</replaceable>s are
550 specified, only those entries are shown.
551 </para>
552 </listitem>
553 </varlistentry>
554
555 <varlistentry>
556 <term><option>--dump-catalog
557 <optional><replaceable>ID128...</replaceable></optional>
558 </option></term>
559
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>
565 files.</para>
566
567 <para>If any
568 <replaceable>ID128</replaceable>s are
569 specified, only those entries are shown.
570 </para>
571 </listitem>
572 </varlistentry>
573
574 <varlistentry>
575 <term><option>--update-catalog</option></term>
576
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>
583 </varlistentry>
584
585 <varlistentry>
586 <term><option>--setup-keys</option></term>
587
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>
600 </varlistentry>
601
602 <varlistentry>
603 <term><option>--interval=</option></term>
604
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
611 undetectable journal
612 alterations. Defaults to
613 15min.</para></listitem>
614 </varlistentry>
615
616 <varlistentry>
617 <term><option>--verify</option></term>
618
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>
627 </varlistentry>
628
629 <varlistentry>
630 <term><option>--verify-key=</option></term>
631
632 <listitem><para>Specifies the FSS
633 verification key to use for the
634 <option>--verify</option>
635 operation.</para></listitem>
636 </varlistentry>
637
638 </variablelist>
639 </refsect1>
640
641 <refsect1>
642 <title>Exit status</title>
643
644 <para>On success 0 is returned, a non-zero failure
645 code otherwise.</para>
646 </refsect1>
647
648 <refsect1>
649 <title>Environment</title>
650
651 <variablelist class='environment-variables'>
652 <varlistentry>
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>
660 </varlistentry>
661 </variablelist>
662 </refsect1>
663
664 <refsect1>
665 <title>Examples</title>
666
667 <para>Without arguments all collected logs are shown
668 unfiltered:</para>
669
670 <programlisting>journalctl</programlisting>
671
672 <para>With one match specified all entries with a field matching the expression are shown:</para>
673
674 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
675
676 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
677
678 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
679
680 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
681
682 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
683
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
689 processes):</para>
690
691 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
692
693 <para>Show all logs generated by the D-Bus executable:</para>
694
695 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
696
697 <para>Show all logs of the kernel device node <filename noindex='true'>/dev/sda</filename>:</para>
698
699 <programlisting>journalctl /dev/sda</programlisting>
700
701 </refsect1>
702
703 <refsect1>
704 <title>See Also</title>
705 <para>
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>
711 </para>
712 </refsect1>
713
714 </refentry>