chiark / gitweb /
man: add various filenames to the index
[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.</para>
336                                 <para>This parameter can be specified multiple times.
337                                 </para></listitem>
338                         </varlistentry>
339
340                         <varlistentry>
341                                 <term><option>--user-unit=</option></term>
342
343                                 <listitem><para>Show messages for the
344                                 specified user session unit. This will
345                                 add a match for messages from the unit
346                                 (<literal>_SYSTEMD_USER_UNIT=</literal>
347                                 and <literal>_UID=</literal>) and
348                                 additional matches for messages from
349                                 session systemd and messages about
350                                 coredumps for the specified unit.</para>
351                                 <para>This parameter can be specified multiple times.
352                                 </para></listitem>
353                         </varlistentry>
354
355                         <varlistentry>
356                                 <term><option>-p</option></term>
357                                 <term><option>--priority=</option></term>
358
359                                 <listitem><para>Filter output by
360                                 message priorities or priority
361                                 ranges. Takes either a single numeric
362                                 or textual log level (i.e. between
363                                 0/<literal>emerg</literal> and
364                                 7/<literal>debug</literal>), or a
365                                 range of numeric/text log levels in
366                                 the form FROM..TO. The log levels are
367                                 the usual syslog log levels as
368                                 documented in
369                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
370                                 i.e. <literal>emerg</literal> (0),
371                                 <literal>alert</literal> (1),
372                                 <literal>crit</literal> (2),
373                                 <literal>err</literal> (3),
374                                 <literal>warning</literal> (4),
375                                 <literal>notice</literal> (5),
376                                 <literal>info</literal> (6),
377                                 <literal>debug</literal> (7). If a
378                                 single log level is specified all
379                                 messages with this log level or a
380                                 lower (hence more important) log level
381                                 are shown. If a range is specified all
382                                 messages within the range are shown,
383                                 including both the start and the end
384                                 value of the range. This will add
385                                 <literal>PRIORITY=</literal> matches
386                                 for the specified
387                                 priorities.</para></listitem>
388                         </varlistentry>
389
390                         <varlistentry>
391                                 <term><option>-c</option></term>
392                                 <term><option>--cursor=</option></term>
393
394                                 <listitem><para>Start showing entries
395                                 from the location in the journal
396                                 specified by the passed
397                                 cursor.</para></listitem>
398                         </varlistentry>
399
400                         <varlistentry>
401                                 <term><option>--since=</option></term>
402                                 <term><option>--until=</option></term>
403
404                                 <listitem><para>Start showing entries
405                                 on or newer than the specified date,
406                                 or on or older than the specified
407                                 date, respectively. Date specifications should be of
408                                 the format "2012-10-30 18:17:16". If
409                                 the time part is omitted, 00:00:00 is
410                                 assumed. If only the seconds component
411                                 is omitted, :00 is assumed. If the
412                                 date component is omitted, the
413                                 current day is assumed. Alternatively
414                                 the strings
415                                 <literal>yesterday</literal>,
416                                 <literal>today</literal>,
417                                 <literal>tomorrow</literal> are
418                                 understood, which refer to 00:00:00 of
419                                 the day before the current day, the
420                                 current day, or the day after the
421                                 current day, respectively. <literal>now</literal>
422                                 refers to the current time. Finally,
423                                 relative times may be specified,
424                                 prefixed with <literal>-</literal> or
425                                 <literal>+</literal>, referring to
426                                 times before or after the current
427                                 time, respectively.</para></listitem>
428                         </varlistentry>
429
430                         <varlistentry>
431                                 <term><option>-F</option></term>
432                                 <term><option>--field=</option></term>
433
434                                 <listitem><para>Print all possible
435                                 data values the specified field can
436                                 take in all entries of the
437                                 journal.</para></listitem>
438                         </varlistentry>
439
440                         <varlistentry>
441                                 <term><option>-D</option></term>
442                                 <term><option>--directory=</option></term>
443
444                                 <listitem><para>Takes a
445                                 directory path as argument. If
446                                 specified journalctl will operate on the
447                                 specified journal directory instead of
448                                 the default runtime and system journal
449                                 paths.</para></listitem>
450                         </varlistentry>
451
452                         <varlistentry>
453                                 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
454
455                                 <listitem><para>Takes a directory path
456                                 as argument. If specified journalctl
457                                 will operate on catalog file hierarchy
458                                 underneath the specified directory
459                                 instead of the root directory
460                                 (e.g. <option>--update-catalog</option>
461                                 will create
462                                 <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>).
463                                 </para></listitem>
464                         </varlistentry>
465
466                         <varlistentry>
467                                 <term><option>--new-id128</option></term>
468
469                                 <listitem><para>Instead of showing
470                                 journal contents generate a new 128
471                                 bit ID suitable for identifying
472                                 messages. This is intended for usage
473                                 by developers who need a new
474                                 identifier for a new message they
475                                 introduce and want to make
476                                 recognizable. Will print the new ID in
477                                 three different formats which can be
478                                 copied into source code or
479                                 similar.</para></listitem>
480                         </varlistentry>
481
482                         <varlistentry>
483                                 <term><option>--header</option></term>
484
485                                 <listitem><para>Instead of showing
486                                 journal contents show internal header
487                                 information of the journal fields
488                                 accessed.</para></listitem>
489                         </varlistentry>
490
491                         <varlistentry>
492                                 <term><option>--disk-usage</option></term>
493
494                                 <listitem><para>Shows the current disk
495                                 usage of all
496                                 journal files.</para></listitem>
497                         </varlistentry>
498
499                         <varlistentry>
500                                 <term><option>--list-catalog
501                                 <optional><replaceable>ID128...</replaceable></optional>
502                                 </option></term>
503
504                                 <listitem><para>List the contents of
505                                 the message catalog, as table of
506                                 message IDs plus their short
507                                 description strings.</para>
508
509                                 <para>If any
510                                 <replaceable>ID128</replaceable>s are
511                                 specified, only those entries are shown.
512                                 </para>
513                                 </listitem>
514                         </varlistentry>
515
516                         <varlistentry>
517                                 <term><option>--dump-catalog
518                                 <optional><replaceable>ID128...</replaceable></optional>
519                                 </option></term>
520
521                                 <listitem><para>Show the contents of
522                                 the message catalog, with entries
523                                 separated by a line consisting of two
524                                 dashes and the id (the format is the
525                                 same as <filename>.catalog</filename>
526                                 files.</para>
527
528                                 <para>If any
529                                 <replaceable>ID128</replaceable>s are
530                                 specified, only those entries are shown.
531                                 </para>
532                                 </listitem>
533                         </varlistentry>
534
535                         <varlistentry>
536                                 <term><option>--update-catalog</option></term>
537
538                                 <listitem><para>Update the message
539                                 catalog index. This command needs to
540                                 be executed each time new catalog
541                                 files are installed, removed or
542                                 updated to rebuild the binary catalog
543                                 index.</para></listitem>
544                         </varlistentry>
545
546                         <varlistentry>
547                                 <term><option>--setup-keys</option></term>
548
549                                 <listitem><para>Instead of showing
550                                 journal contents generate a new key
551                                 pair for Forward Secure Sealing
552                                 (FSS). This will generate a sealing
553                                 key and a verification key. The
554                                 sealing key is stored in the journal
555                                 data directory and shall remain on the
556                                 host. The verification key should be
557                                 stored externally.</para></listitem>
558                         </varlistentry>
559
560                         <varlistentry>
561                                 <term><option>--interval=</option></term>
562
563                                 <listitem><para>Specifies the change
564                                 interval for the sealing key, when
565                                 generating an FSS key pair with
566                                 <option>--setup-keys</option>. Shorter
567                                 intervals increase CPU consumption but
568                                 shorten the time range of
569                                 undetectable journal
570                                 alterations. Defaults to
571                                 15min.</para></listitem>
572                         </varlistentry>
573
574                         <varlistentry>
575                                 <term><option>--verify</option></term>
576
577                                 <listitem><para>Check the journal file
578                                 for internal consistency. If the
579                                 file has been generated with FSS
580                                 enabled, and the FSS verification key
581                                 has been specified with
582                                 <option>--verify-key=</option>
583                                 authenticity of the journal file is
584                                 verified.</para></listitem>
585                         </varlistentry>
586
587                         <varlistentry>
588                                 <term><option>--verify-key=</option></term>
589
590                                 <listitem><para>Specifies the FSS
591                                 verification key to use for the
592                                 <option>--verify</option>
593                                 operation.</para></listitem>
594                         </varlistentry>
595
596                 </variablelist>
597         </refsect1>
598
599         <refsect1>
600                 <title>Exit status</title>
601
602                 <para>On success 0 is returned, a non-zero failure
603                 code otherwise.</para>
604         </refsect1>
605
606         <refsect1>
607                 <title>Environment</title>
608
609                 <variablelist class='environment-variables'>
610                         <varlistentry>
611                                 <term><varname>$SYSTEMD_PAGER</varname></term>
612                                 <listitem><para>Pager to use when
613                                 <option>--no-pager</option> is not given;
614                                 overrides <varname>$PAGER</varname>.  Setting
615                                 this to an empty string or the value
616                                 <literal>cat</literal> is equivalent to passing
617                                 <option>--no-pager</option>.</para></listitem>
618                         </varlistentry>
619                 </variablelist>
620         </refsect1>
621
622         <refsect1>
623                 <title>Examples</title>
624
625                 <para>Without arguments all collected logs are shown
626                 unfiltered:</para>
627
628                 <programlisting>journalctl</programlisting>
629
630                 <para>With one match specified all entries with a field matching the expression are shown:</para>
631
632                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
633
634                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
635
636                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
637
638                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
639
640                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
641
642                 <para>If the separator "<literal>+</literal>" is used
643                 two expressions may be combined in a logical OR. The
644                 following will show all messages from the Avahi
645                 service process with the PID 28097 plus all messages
646                 from the D-Bus service (from any of its
647                 processes):</para>
648
649                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
650
651                 <para>Show all logs generated by the D-Bus executable:</para>
652
653                 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
654
655                 <para>Show all logs of the kernel device node <filename noindex='true'>/dev/sda</filename>:</para>
656
657                 <programlisting>journalctl /dev/sda</programlisting>
658
659         </refsect1>
660
661         <refsect1>
662                 <title>See Also</title>
663                 <para>
664                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
665                         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
666                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
667                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
668                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
669                 </para>
670         </refsect1>
671
672 </refentry>