chiark / gitweb /
Do no isolate in case of emergency or severe problems
[elogind.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>--full</option></term>
142
143                                 <listitem><para>Show all (printable) fields in
144                                 full.</para></listitem>
145                         </varlistentry>
146
147                         <varlistentry>
148                                 <term><option>-a</option></term>
149                                 <term><option>--all</option></term>
150
151                                 <listitem><para>Show all fields in
152                                 full, even if they include unprintable
153                                 characters or are very
154                                 long.</para></listitem>
155                         </varlistentry>
156
157                         <varlistentry>
158                                 <term><option>-f</option></term>
159                                 <term><option>--follow</option></term>
160
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>
165                         </varlistentry>
166
167                         <varlistentry>
168                                 <term><option>-e</option></term>
169                                 <term><option>--pager-end</option></term>
170
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>
183                         </varlistentry>
184
185                         <varlistentry>
186                                 <term><option>-n</option></term>
187                                 <term><option>--lines=</option></term>
188
189                                 <listitem><para>Show the most recent
190                                 journal events and limit the number of
191                                 events shown. If
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>
196                         </varlistentry>
197
198                         <varlistentry>
199                                 <term><option>--no-tail</option></term>
200
201                                 <listitem><para>Show all stored output
202                                 lines, even in follow mode. Undoes the
203                                 effect of
204                                 <option>--lines=</option>.</para></listitem>
205                         </varlistentry>
206
207                         <varlistentry>
208                                 <term><option>-r</option></term>
209                                 <term><option>--reverse</option></term>
210
211                                 <listitem><para>Reverse output, so the newest
212                                 entries are displayed first.</para></listitem>
213                         </varlistentry>
214
215                         <varlistentry>
216                                 <term><option>-o</option></term>
217                                 <term><option>--output=</option></term>
218
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
239                                 with all
240                                 fields. <literal>export</literal>
241                                 serializes the journal into a binary
242                                 (but mostly text-based) stream
243                                 suitable for backups and network
244                                 transfer (see <ulink
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
249                                 structures, one per
250                                 line (see <ulink
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
257                                 more readable for
258                                 humans. <literal>json-sse</literal>
259                                 also formats entries as JSON data
260                                 structures, but wraps them in a format
261                                 suitable for <ulink
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>
268                         </varlistentry>
269
270                         <varlistentry>
271                                 <term><option>-x</option></term>
272                                 <term><option>--catalog</option></term>
273
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
290                                 Catalog Developer
291                                 Documentation</ulink>.</para></listitem>
292                         </varlistentry>
293
294                         <varlistentry>
295                                 <term><option>-q</option></term>
296                                 <term><option>--quiet</option></term>
297
298                                 <listitem><para>Suppresses any warning
299                                 message regarding inaccessible system
300                                 journals when run as normal
301                                 user.</para></listitem>
302                         </varlistentry>
303
304                         <varlistentry>
305                                 <term><option>-m</option></term>
306                                 <term><option>--merge</option></term>
307
308                                 <listitem><para>Show entries
309                                 interleaved from all available
310                                 journals, including remote
311                                 ones.</para></listitem>
312                         </varlistentry>
313
314                         <varlistentry>
315                                 <term><option>-b</option></term>
316                                 <term><option>--this-boot</option></term>
317
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>
323                         </varlistentry>
324
325                         <varlistentry>
326                                 <term><option>-u</option></term>
327                                 <term><option>--unit=</option></term>
328
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.
336                                 </para></listitem>
337                         </varlistentry>
338
339                         <varlistentry>
340                                 <term><option>--user-unit=</option></term>
341
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.
350                                 </para></listitem>
351                         </varlistentry>
352
353                         <varlistentry>
354                                 <term><option>-p</option></term>
355                                 <term><option>--priority=</option></term>
356
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
366                                 documented in
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
384                                 for the specified
385                                 priorities.</para></listitem>
386                         </varlistentry>
387
388                         <varlistentry>
389                                 <term><option>-c</option></term>
390                                 <term><option>--cursor=</option></term>
391
392                                 <listitem><para>Start showing entries
393                                 from the location in the journal
394                                 specified by the passed
395                                 cursor.</para></listitem>
396                         </varlistentry>
397
398                         <varlistentry>
399                                 <term><option>--since=</option></term>
400                                 <term><option>--until=</option></term>
401
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
412                                 the strings
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>
426                         </varlistentry>
427
428                         <varlistentry>
429                                 <term><option>-F</option></term>
430                                 <term><option>--field=</option></term>
431
432                                 <listitem><para>Print all possible
433                                 data values the specified field can
434                                 take in all entries of the
435                                 journal.</para></listitem>
436                         </varlistentry>
437
438                         <varlistentry>
439                                 <term><option>-D</option></term>
440                                 <term><option>--directory=</option></term>
441
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>
448                         </varlistentry>
449
450                         <varlistentry>
451                                 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
452
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>
459                                 will create
460                                 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
461                                 </para></listitem>
462                         </varlistentry>
463
464                         <varlistentry>
465                                 <term><option>--new-id128</option></term>
466
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>
478                         </varlistentry>
479
480                         <varlistentry>
481                                 <term><option>--header</option></term>
482
483                                 <listitem><para>Instead of showing
484                                 journal contents show internal header
485                                 information of the journal fields
486                                 accessed.</para></listitem>
487                         </varlistentry>
488
489                         <varlistentry>
490                                 <term><option>--disk-usage</option></term>
491
492                                 <listitem><para>Shows the current disk
493                                 usage of all
494                                 journal files.</para></listitem>
495                         </varlistentry>
496
497                         <varlistentry>
498                                 <term><option>--list-catalog
499                                 <optional><replaceable>ID128...</replaceable></optional>
500                                 </option></term>
501
502                                 <listitem><para>List the contents of
503                                 the message catalog, as table of
504                                 message IDs plus their short
505                                 description strings.</para>
506
507                                 <para>If any
508                                 <replaceable>ID128</replaceable>s are
509                                 specified, only those entries are shown.
510                                 </para>
511                                 </listitem>
512                         </varlistentry>
513
514                         <varlistentry>
515                                 <term><option>--dump-catalog
516                                 <optional><replaceable>ID128...</replaceable></optional>
517                                 </option></term>
518
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>
524                                 files.</para>
525
526                                 <para>If any
527                                 <replaceable>ID128</replaceable>s are
528                                 specified, only those entries are shown.
529                                 </para>
530                                 </listitem>
531                         </varlistentry>
532
533                         <varlistentry>
534                                 <term><option>--update-catalog</option></term>
535
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>
542                         </varlistentry>
543
544                         <varlistentry>
545                                 <term><option>--setup-keys</option></term>
546
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>
556                         </varlistentry>
557
558                         <varlistentry>
559                                 <term><option>--interval=</option></term>
560
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
567                                 undetectable journal
568                                 alterations. Defaults to
569                                 15min.</para></listitem>
570                         </varlistentry>
571
572                         <varlistentry>
573                                 <term><option>--verify</option></term>
574
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>
583                         </varlistentry>
584
585                         <varlistentry>
586                                 <term><option>--verify-key=</option></term>
587
588                                 <listitem><para>Specifies the FSS
589                                 verification key to use for the
590                                 <option>--verify</option>
591                                 operation.</para></listitem>
592                         </varlistentry>
593
594                 </variablelist>
595         </refsect1>
596
597         <refsect1>
598                 <title>Exit status</title>
599
600                 <para>On success 0 is returned, a non-zero failure
601                 code otherwise.</para>
602         </refsect1>
603
604         <refsect1>
605                 <title>Environment</title>
606
607                 <variablelist class='environment-variables'>
608                         <varlistentry>
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>
616                         </varlistentry>
617                 </variablelist>
618         </refsect1>
619
620         <refsect1>
621                 <title>Examples</title>
622
623                 <para>Without arguments all collected logs are shown
624                 unfiltered:</para>
625
626                 <programlisting>journalctl</programlisting>
627
628                 <para>With one match specified all entries with a field matching the expression are shown:</para>
629
630                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
631
632                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
633
634                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
635
636                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
637
638                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
639
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
645                 processes):</para>
646
647                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
648
649                 <para>Show all logs generated by the D-Bus executable:</para>
650
651                 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
652
653                 <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
654
655                 <programlisting>journalctl /dev/sda</programlisting>
656
657         </refsect1>
658
659         <refsect1>
660                 <title>See Also</title>
661                 <para>
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>
667                 </para>
668         </refsect1>
669
670 </refentry>