man/journalctl.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6   <refentry id="journalctl"
   7             xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9     <refentryinfo>
  10       <title>journalctl</title>
  11       <productname>systemd</productname>
  12     </refentryinfo>
  13
  14     <refmeta>
  15       <refentrytitle>journalctl</refentrytitle>
  16       <manvolnum>1</manvolnum>
  17     </refmeta>
  18
  19     <refnamediv>
  20       <refname>journalctl</refname>
  21       <refpurpose>Query the systemd journal</refpurpose>
  22     </refnamediv>
  23
  24     <refsynopsisdiv>
  25       <cmdsynopsis>
  26         <command>journalctl</command>
  27         <arg choice="opt" rep="repeat">OPTIONS</arg>
  28         <arg choice="opt" rep="repeat">MATCHES</arg>
  29       </cmdsynopsis>
  30     </refsynopsisdiv>
  31
  32     <refsect1>
  33       <title>Description</title>
  34
  35       <para><command>journalctl</command> may be used to query the
  36       contents of the
  37       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  38       journal as written by
  39       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  40
  41       <para>If called without parameters, it will show the full
  42       contents of the journal, starting with the oldest entry
  43       collected.</para>
  44
  45       <para>If one or more match arguments are passed, the output is
  46       filtered accordingly. A match is in the format
  47       <literal>FIELD=VALUE</literal>,
  48       e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>, referring
  49       to the components of a structured journal entry. See
  50       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  51       for a list of well-known fields. If multiple matches are
  52       specified matching different fields, the log entries are
  53       filtered by both, i.e. the resulting output will show only
  54       entries matching all the specified matches of this kind. If two
  55       matches apply to the same field, then they are automatically
  56       matched as alternatives, i.e. the resulting output will show
  57       entries matching any of the specified matches for the same
  58       field. Finally, the character <literal>+</literal> may appear
  59       as a separate word between other terms on the command line. This
  60       causes all matches before and after to be combined in a
  61       disjunction (i.e. logical OR).</para>
  62
  63       <para>It is also possible to filter the entries by specifying an
  64       absolute file path as an argument. The file path may be a file or
  65       a symbolic link and the file must exist at the time of the query. If a
  66       file path refers to an executable binary, an <literal>_EXE=</literal>
  67       match for the canonicalized binary path is added to the query. If a
  68       file path refers to an executable script, a <literal>_COMM=</literal>
  69       match for the script name is added to the query. If a file path
  70       refers to a device node, <literal>_KERNEL_DEVICE=</literal> matches for
  71       the kernel name of the device and for each of its ancestor devices is
  72       added to the query. Symbolic links are dereferenced, kernel names are
  73       synthesized, and parent devices are identified from the environment at
  74       the time of the query. In general, a device node is the best proxy for
  75       an actual device, as log entries do not usually contain fields that
  76       identify an actual device. For the resulting log entries to be correct
  77       for the actual device, the relevant parts of the environment at the time
  78       the entry was logged, in particular the actual device corresponding to
  79       the device node, must have been the same as those at the time of the
  80       query. Because device nodes generally change their corresponding devices
  81       across reboots, specifying a device node path causes the resulting
  82       entries to be restricted to those from the current boot.</para>
  83
  84       <para>Additional constraints may be added using options
  85       <option>--boot</option>, <option>--unit=</option>, etc., to
  86       further limit what entries will be shown (logical AND).</para>
  87
  88       <para>Output is interleaved from all accessible journal files,
  89       whether they are rotated or currently being written, and
  90       regardless of whether they belong to the system itself or are
  91       accessible user journals.</para>
  92
  93       <para>The set of journal files which will be used can be
  94       modified using the <option>--user</option>,
  95       <option>--system</option>, <option>--directory</option>, and
  96       <option>--file</option> options, see below.</para>
  97
  98       <para>All users are granted access to their private per-user
  99       journals. However, by default, only root and users who are
 100       members of a few special groups are granted access to the system
 101       journal and the journals of other users. Members of the groups
 102       <literal>systemd-journal</literal>, <literal>adm</literal>, and
 103       <literal>wheel</literal> can read all journal files. Note
 104       that the two latter groups traditionally have additional
 105       privileges specified by the distribution. Members of the
 106       <literal>wheel</literal> group can often perform administrative
 107       tasks.</para>
 108
 109       <para>The output is paged through <command>less</command> by
 110       default, and long lines are "truncated" to screen width. The
 111       hidden part can be viewed by using the left-arrow and
 112       right-arrow keys. Paging can be disabled; see the
 113       <option>--no-pager</option> option and the "Environment" section
 114       below.</para>
 115
 116       <para>When outputting to a tty, lines are colored according to
 117       priority: lines of level ERROR and higher are colored red; lines
 118       of level NOTICE and higher are highlighted; lines of level DEBUG
 119       are colored lighter grey; other lines are displayed normally.</para>
 120     </refsect1>
 121
 122     <refsect1>
 123       <title>Options</title>
 124
 125       <para>The following options are understood:</para>
 126
 127       <variablelist>
 128         <varlistentry>
 129           <term><option>--no-full</option></term>
 130           <term><option>--full</option></term>
 131           <term><option>-l</option></term>
 132
 133           <listitem><para>Ellipsize fields when they do not fit in
 134           available columns.  The default is to show full fields,
 135           allowing them to wrap or be truncated by the pager, if one
 136           is used.</para>
 137
 138           <para>The old options
 139           <option>-l</option>/<option>--full</option> are not useful
 140           anymore, except to undo <option>--no-full</option>.</para>
 141           </listitem>
 142         </varlistentry>
 143
 144         <varlistentry>
 145           <term><option>-a</option></term>
 146           <term><option>--all</option></term>
 147
 148           <listitem><para>Show all fields in full, even if they include unprintable characters or are very long. By
 149           default, fields with unprintable characters are abbreviated as "blob data". (Note that the pager may escape
 150           unprintable characters again.)</para></listitem>
 151         </varlistentry>
 152
 153         <varlistentry>
 154           <term><option>-f</option></term>
 155           <term><option>--follow</option></term>
 156
 157           <listitem><para>Show only the most recent journal entries,
 158           and continuously print new entries as they are appended to
 159           the journal.</para></listitem>
 160         </varlistentry>
 161
 162         <varlistentry>
 163           <term><option>-e</option></term>
 164           <term><option>--pager-end</option></term>
 165
 166           <listitem><para>Immediately jump to the end of the journal
 167           inside the implied pager tool. This implies
 168           <option>-n1000</option> to guarantee that the pager will not
 169           buffer logs of unbounded size. This may be overridden with
 170           an explicit <option>-n</option> with some other numeric
 171           value, while <option>-nall</option> will disable this cap.
 172           Note that this option is only supported for the
 173           <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 174           pager.</para></listitem>
 175         </varlistentry>
 176
 177         <varlistentry>
 178           <term><option>-n</option></term>
 179           <term><option>--lines=</option></term>
 180
 181           <listitem><para>Show the most recent journal events and
 182           limit the number of events shown. If
 183           <option>--follow</option> is used, this option is
 184           implied. The argument is a positive integer or
 185           <literal>all</literal> to disable line limiting. The default
 186           value is 10 if no argument is given.</para></listitem>
 187         </varlistentry>
 188
 189         <varlistentry>
 190           <term><option>--no-tail</option></term>
 191
 192           <listitem><para>Show all stored output lines, even in follow
 193           mode. Undoes the effect of <option>--lines=</option>.
 194           </para></listitem>
 195         </varlistentry>
 196
 197         <varlistentry>
 198           <term><option>-r</option></term>
 199           <term><option>--reverse</option></term>
 200
 201           <listitem><para>Reverse output so that the newest entries
 202           are displayed first.</para></listitem>
 203         </varlistentry>
 204
 205         <varlistentry>
 206           <term><option>-o</option></term>
 207           <term><option>--output=</option></term>
 208
 209           <listitem><para>Controls the formatting of the journal
 210           entries that are shown. Takes one of the following
 211           options:</para>
 212           <variablelist>
 213             <varlistentry>
 214               <term>
 215                 <option>short</option>
 216               </term>
 217               <listitem>
 218                 <para>is the default and generates an output that is
 219                 mostly identical to the formatting of classic syslog
 220                 files, showing one line per journal entry.</para>
 221               </listitem>
 222             </varlistentry>
 223
 224             <varlistentry>
 225               <term>
 226                 <option>short-full</option>
 227               </term>
 228               <listitem>
 229                 <para>is very similar, but shows timestamps in the format the <option>--since=</option> and
 230                 <option>--until=</option> options accept. Unlike the timestamp information shown in
 231                 <option>short</option> output mode this mode includes weekday, year and timezone information in the
 232                 output, and is locale-independent.</para>
 233               </listitem>
 234             </varlistentry>
 235
 236             <varlistentry>
 237               <term>
 238                 <option>short-iso</option>
 239               </term>
 240               <listitem>
 241                 <para>is very similar, but shows ISO 8601 wallclock
 242                 timestamps.</para>
 243               </listitem>
 244             </varlistentry>
 245
 246             <varlistentry>
 247               <term>
 248                 <option>short-iso-precise</option>
 249               </term>
 250               <listitem>
 251                 <para>as for <option>short-iso</option> but includes full
 252                 microsecond precision.</para>
 253               </listitem>
 254             </varlistentry>
 255
 256             <varlistentry>
 257               <term>
 258                 <option>short-precise</option>
 259               </term>
 260               <listitem>
 261                 <para>is very similar, but shows classic syslog timestamps
 262                 with full microsecond precision.</para>
 263               </listitem>
 264             </varlistentry>
 265
 266             <varlistentry>
 267               <term>
 268                 <option>short-monotonic</option>
 269               </term>
 270               <listitem>
 271                 <para>is very similar, but shows monotonic timestamps
 272                 instead of wallclock timestamps.</para>
 273               </listitem>
 274             </varlistentry>
 275
 276             <varlistentry>
 277               <term>
 278                 <option>short-unix</option>
 279               </term>
 280               <listitem>
 281                 <para>is very similar, but shows seconds passed since January 1st 1970 UTC instead of wallclock
 282                 timestamps ("UNIX time"). The time is shown with microsecond accuracy.</para>
 283               </listitem>
 284             </varlistentry>
 285
 286             <varlistentry>
 287               <term>
 288                 <option>verbose</option>
 289               </term>
 290               <listitem>
 291                 <para>shows the full-structured entry items with all
 292                 fields.</para>
 293               </listitem>
 294             </varlistentry>
 295
 296             <varlistentry>
 297               <term>
 298                 <option>export</option>
 299               </term>
 300               <listitem>
 301                 <para>serializes the journal into a binary (but mostly
 302                 text-based) stream suitable for backups and network
 303                 transfer (see
 304                 <ulink url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format</ulink>
 305                 for more information). To import the binary stream back
 306                 into native journald format use
 307                 <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 308               </listitem>
 309             </varlistentry>
 310
 311             <varlistentry>
 312               <term>
 313                 <option>json</option>
 314               </term>
 315               <listitem>
 316                 <para>formats entries as JSON objects, separated by newline characters (see <ulink
 317                 url="https://www.freedesktop.org/wiki/Software/systemd/json">Journal JSON Format</ulink> for more
 318                 information). Field values are generally encoded as JSON strings, with three exceptions:
 319                 <orderedlist>
 320                   <listitem><para>Fields larger than 4096 bytes are encoded as <constant>null</constant> values. (This
 321                   may be turned off by passing <option>--all</option>, but be aware that this may allocate overly long
 322                   JSON objects.) </para></listitem>
 323
 324                   <listitem><para>Journal entries permit non-unique fields within the same log entry. JSON does not allow
 325                   non-unique fields within objects. Due to this, if a non-unique field is encountered a JSON array is
 326                   used as field value, listing all field values as elements.</para></listitem>
 327
 328                   <listitem><para>Fields containing non-printable or non-UTF8 bytes are encoded as arrays containing
 329                   the raw bytes individually formatted as unsigned numbers.</para></listitem>
 330                 </orderedlist>
 331
 332                 Note that this encoding is reversible (with the exception of the size limit).</para>
 333               </listitem>
 334             </varlistentry>
 335
 336             <varlistentry>
 337               <term>
 338                 <option>json-pretty</option>
 339               </term>
 340               <listitem>
 341                 <para>formats entries as JSON data structures, but
 342                 formats them in multiple lines in order to make them
 343                 more readable by humans.</para>
 344               </listitem>
 345             </varlistentry>
 346
 347             <varlistentry>
 348               <term>
 349                 <option>json-sse</option>
 350               </term>
 351               <listitem>
 352                 <para>formats entries as JSON data structures, but wraps
 353                 them in a format suitable for
 354                 <ulink url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent Events</ulink>.
 355                 </para>
 356               </listitem>
 357             </varlistentry>
 358
 359             <varlistentry>
 360               <term>
 361                 <option>json-seq</option>
 362               </term>
 363               <listitem>
 364                 <para>formats entries as JSON data structures, but prefixes them with an ASCII Record Separator
 365                 character (0x1E) and suffixes them with an ASCII Line Feed character (0x0A), in accordance with <ulink
 366                 url="https://tools.ietf.org/html/rfc7464">JavaScript Object Notation (JSON) Text Sequences </ulink>
 367                 (<literal>application/json-seq</literal>).
 368                 </para>
 369               </listitem>
 370             </varlistentry>
 371
 372             <varlistentry>
 373               <term>
 374                 <option>cat</option>
 375               </term>
 376               <listitem>
 377                 <para>generates a very terse output, only showing the
 378                 actual message of each journal entry with no metadata,
 379                 not even a timestamp.</para>
 380               </listitem>
 381             </varlistentry>
 382
 383             <varlistentry>
 384               <term>
 385                 <option>with-unit</option>
 386               </term>
 387               <listitem>
 388                 <para>similar to short-full, but prefixes the unit and
 389                 user unit names instead of the traditional syslog
 390                 identifier. Useful when using templated instances, as it
 391                 will include the arguments in the unit names.</para>
 392               </listitem>
 393             </varlistentry>
 394           </variablelist>
 395         </listitem>
 396       </varlistentry>
 397
 398       <varlistentry>
 399         <term><option>--output-fields=</option></term>
 400
 401         <listitem><para>A comma separated list of the fields which should be included in the output. This only has an
 402         effect for the output modes which would normally show all fields (<option>verbose</option>,
 403         <option>export</option>, <option>json</option>, <option>json-pretty</option>, <option>json-sse</option> and
 404         <option>json-seq</option>). The <literal>__CURSOR</literal>, <literal>__REALTIME_TIMESTAMP</literal>,
 405         <literal>__MONOTONIC_TIMESTAMP</literal>, and <literal>_BOOT_ID</literal> fields are always
 406         printed.</para></listitem>
 407       </varlistentry>
 408
 409       <varlistentry>
 410         <term><option>--utc</option></term>
 411
 412         <listitem><para>Express time in Coordinated Universal Time
 413         (UTC).</para></listitem>
 414       </varlistentry>
 415
 416       <varlistentry>
 417         <term><option>--no-hostname</option></term>
 418
 419         <listitem><para>Don't show the hostname field of log messages originating from the local host. This switch only
 420         has an effect on the <option>short</option> family of output modes (see above).</para></listitem>
 421       </varlistentry>
 422
 423       <varlistentry>
 424         <term><option>-x</option></term>
 425         <term><option>--catalog</option></term>
 426
 427         <listitem><para>Augment log lines with explanation texts from
 428         the message catalog. This will add explanatory help texts to
 429         log messages in the output where this is available. These
 430         short help texts will explain the context of an error or log
 431         event, possible solutions, as well as pointers to support
 432         forums, developer documentation, and any other relevant
 433         manuals. Note that help texts are not available for all
 434         messages, but only for selected ones. For more information on
 435         the message catalog, please refer to the
 436         <ulink url="https://www.freedesktop.org/wiki/Software/systemd/catalog">Message Catalog Developer Documentation</ulink>.</para>
 437
 438         <para>Note: when attaching <command>journalctl</command>
 439         output to bug reports, please do <emphasis>not</emphasis> use
 440         <option>-x</option>.</para>
 441         </listitem>
 442       </varlistentry>
 443
 444       <varlistentry>
 445         <term><option>-q</option></term>
 446         <term><option>--quiet</option></term>
 447
 448         <listitem><para>Suppresses all informational messages
 449         (i.e. "-- Logs begin at …", "-- Reboot --"),
 450         any warning messages regarding
 451         inaccessible system journals when run as a normal
 452         user.</para></listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><option>-m</option></term>
 457         <term><option>--merge</option></term>
 458
 459         <listitem><para>Show entries interleaved from all available
 460         journals, including remote ones.</para></listitem>
 461       </varlistentry>
 462
 463       <varlistentry>
 464         <term><option>-b <optional><optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional>|<constant>all</constant></optional></option></term>
 465         <term><option>--boot<optional>=<optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional>|<constant>all</constant></optional></option></term>
 466
 467         <listitem><para>Show messages from a specific boot. This will
 468         add a match for <literal>_BOOT_ID=</literal>.</para>
 469
 470         <para>The argument may be empty, in which case logs for the
 471         current boot will be shown.</para>
 472
 473         <para>If the boot ID is omitted, a positive
 474         <replaceable>offset</replaceable> will look up the boots
 475         starting from the beginning of the journal, and an
 476         equal-or-less-than zero <replaceable>offset</replaceable> will
 477         look up boots starting from the end of the journal. Thus,
 478         <constant>1</constant> means the first boot found in the
 479         journal in chronological order, <constant>2</constant> the
 480         second and so on; while <constant>-0</constant> is the last
 481         boot, <constant>-1</constant> the boot before last, and so
 482         on. An empty <replaceable>offset</replaceable> is equivalent
 483         to specifying <constant>-0</constant>, except when the current
 484         boot is not the last boot (e.g. because
 485         <option>--directory</option> was specified to look at logs
 486         from a different machine).</para>
 487
 488         <para>If the 32-character <replaceable>ID</replaceable> is
 489         specified, it may optionally be followed by
 490         <replaceable>offset</replaceable> which identifies the boot
 491         relative to the one given by boot
 492         <replaceable>ID</replaceable>. Negative values mean earlier
 493         boots and positive values mean later boots. If
 494         <replaceable>offset</replaceable> is not specified, a value of
 495         zero is assumed, and the logs for the boot given by
 496         <replaceable>ID</replaceable> are shown.</para>
 497
 498         <para>The special argument <constant>all</constant> can be
 499         used to negate the effect of an earlier use of
 500         <option>-b</option>.</para>
 501         </listitem>
 502       </varlistentry>
 503
 504       <varlistentry>
 505         <term><option>--list-boots</option></term>
 506
 507         <listitem><para>Show a tabular list of boot numbers (relative to
 508         the current boot), their IDs, and the timestamps of the first
 509         and last message pertaining to the boot.</para></listitem>
 510       </varlistentry>
 511
 512       <varlistentry>
 513         <term><option>-k</option></term>
 514         <term><option>--dmesg</option></term>
 515
 516         <listitem><para>Show only kernel messages. This implies
 517         <option>-b</option> and adds the match
 518         <literal>_TRANSPORT=kernel</literal>.</para></listitem>
 519       </varlistentry>
 520
 521       <varlistentry>
 522         <term><option>-t</option></term>
 523         <term><option>--identifier=<replaceable>SYSLOG_IDENTIFIER</replaceable></option></term>
 524
 525         <listitem><para>Show messages for the specified syslog
 526         identifier
 527         <replaceable>SYSLOG_IDENTIFIER</replaceable>.</para>
 528
 529         <para>This parameter can be specified multiple
 530         times.</para></listitem>
 531       </varlistentry>
 532
 533       <varlistentry>
 534         <term><option>-u</option></term>
 535         <term><option>--unit=<replaceable>UNIT</replaceable>|<replaceable>PATTERN</replaceable></option></term>
 536
 537         <listitem><para>Show messages for the specified systemd unit
 538         <replaceable>UNIT</replaceable> (such as a service unit), or
 539         for any of the units matched by
 540         <replaceable>PATTERN</replaceable>.  If a pattern is
 541         specified, a list of unit names found in the journal is
 542         compared with the specified pattern and all that match are
 543         used. For each unit name, a match is added for messages from
 544         the unit
 545         (<literal>_SYSTEMD_UNIT=<replaceable>UNIT</replaceable></literal>),
 546         along with additional matches for messages from systemd and
 547         messages about coredumps for the specified unit. A match
 548         is also added for <literal>_SYSTEMD_SLICE=<replaceable>UNIT</replaceable></literal>,
 549         such that if the provided <replaceable>UNIT</replaceable> is a
 550         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 551         unit, all logs of the children of the slice will be logged.
 552        </para>
 553
 554         <para>This parameter can be specified multiple times.</para>
 555         </listitem>
 556       </varlistentry>
 557
 558       <varlistentry>
 559         <term><option>--user-unit=</option></term>
 560
 561         <listitem><para>Show messages for the specified user session
 562         unit. This will add a match for messages from the unit
 563         (<literal>_SYSTEMD_USER_UNIT=</literal> and
 564         <literal>_UID=</literal>) and additional matches for messages
 565         from session systemd and messages about coredumps for the
 566         specified unit. A match
 567         is also added for <literal>_SYSTEMD_USER_SLICE=<replaceable>UNIT</replaceable></literal>,
 568         such that if the provided <replaceable>UNIT</replaceable> is a
 569         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 570         unit, all logs of the children of the unit will be logged.</para>
 571
 572         <para>This parameter can be specified multiple times.</para>
 573         </listitem>
 574       </varlistentry>
 575
 576       <varlistentry>
 577         <term><option>-p</option></term>
 578         <term><option>--priority=</option></term>
 579
 580         <listitem><para>Filter output by message priorities or
 581         priority ranges. Takes either a single numeric or textual log
 582         level (i.e. between 0/<literal>emerg</literal> and
 583         7/<literal>debug</literal>), or a range of numeric/text log
 584         levels in the form FROM..TO. The log levels are the usual
 585         syslog log levels as documented in
 586         <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 587         i.e. <literal>emerg</literal> (0),
 588         <literal>alert</literal> (1), <literal>crit</literal> (2),
 589         <literal>err</literal> (3), <literal>warning</literal> (4),
 590         <literal>notice</literal> (5), <literal>info</literal> (6),
 591         <literal>debug</literal> (7). If a single log level is
 592         specified, all messages with this log level or a lower (hence
 593         more important) log level are shown. If a range is specified,
 594         all messages within the range are shown, including both the
 595         start and the end value of the range. This will add
 596         <literal>PRIORITY=</literal> matches for the specified
 597         priorities.</para></listitem>
 598       </varlistentry>
 599
 600       <varlistentry>
 601         <term><option>-g</option></term>
 602         <term><option>--grep=</option></term>
 603
 604         <listitem><para>Filter output to entries where the <varname>MESSAGE=</varname>
 605         field matches the specified regular expression. PERL-compatible regular expressions
 606         are used, see
 607         <citerefentry><refentrytitle>pcre2pattern</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 608         for a detailed description of the syntax.</para>
 609
 610         <para>If the pattern is all lowercase, matching is case insensitive.
 611         Otherwise, matching is case sensitive. This can be overridden with the
 612         <option>--case-sensitive</option> option, see below.</para>
 613         </listitem>
 614       </varlistentry>
 615
 616       <varlistentry>
 617         <term><option>--case-sensitive<optional>=BOOLEAN</optional></option></term>
 618
 619         <listitem><para>Make pattern matching case sensitive or case insenstive.</para>
 620         </listitem>
 621       </varlistentry>
 622
 623       <varlistentry>
 624         <term><option>-c</option></term>
 625         <term><option>--cursor=</option></term>
 626
 627         <listitem><para>Start showing entries from the location in the
 628         journal specified by the passed cursor.</para></listitem>
 629       </varlistentry>
 630
 631       <varlistentry>
 632         <term><option>--cursor-file=<replaceable>FILE</replaceable></option></term>
 633
 634         <listitem><para>If <replaceable>FILE</replaceable> exists and contains a
 635         cursor, start showing entries <emphasis>after</emphasis> this location.
 636         Otherwise the show entries according the other given options. At the end,
 637         write the cursor of the last entry to <replaceable>FILE</replaceable>. Use
 638         this option to continually read the journal by sequentially calling
 639         <command>journalctl</command>.</para></listitem>
 640       </varlistentry>
 641
 642       <varlistentry>
 643         <term><option>--after-cursor=</option></term>
 644
 645         <listitem><para>Start showing entries from the location in the
 646         journal <emphasis>after</emphasis> the location specified by
 647         the passed cursor.  The cursor is shown when the
 648         <option>--show-cursor</option> option is used.</para>
 649         </listitem>
 650       </varlistentry>
 651
 652       <varlistentry>
 653         <term><option>--show-cursor</option></term>
 654
 655         <listitem><para>The cursor is shown after the last entry after
 656         two dashes:</para>
 657         <programlisting>-- cursor: s=0639…</programlisting>
 658         <para>The format of the cursor is private
 659         and subject to change.</para></listitem>
 660       </varlistentry>
 661
 662       <varlistentry>
 663         <term><option>-S</option></term>
 664         <term><option>--since=</option></term>
 665         <term><option>-U</option></term>
 666         <term><option>--until=</option></term>
 667
 668         <listitem><para>Start showing entries on or newer than the specified date, or on or older than the specified
 669         date, respectively. Date specifications should be of the format <literal>2012-10-30 18:17:16</literal>.  If the
 670         time part is omitted, <literal>00:00:00</literal> is assumed.  If only the seconds component is omitted,
 671         <literal>:00</literal> is assumed. If the date component is omitted, the current day is assumed. Alternatively
 672         the strings <literal>yesterday</literal>, <literal>today</literal>, <literal>tomorrow</literal> are understood,
 673         which refer to 00:00:00 of the day before the current day, the current day, or the day after the current day,
 674         respectively. <literal>now</literal> refers to the current time. Finally, relative times may be specified,
 675         prefixed with <literal>-</literal> or <literal>+</literal>, referring to times before or after the current
 676         time, respectively. For complete time and date specification, see
 677         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Note that
 678         <option>--output=short-full</option> prints timestamps that follow precisely this format.
 679         </para>
 680         </listitem>
 681       </varlistentry>
 682
 683       <varlistentry>
 684         <term><option>-F</option></term>
 685         <term><option>--field=</option></term>
 686
 687         <listitem><para>Print all possible data values the specified
 688         field can take in all entries of the journal.</para></listitem>
 689       </varlistentry>
 690
 691       <varlistentry>
 692         <term><option>-N</option></term>
 693         <term><option>--fields</option></term>
 694
 695         <listitem><para>Print all field names currently used in all entries of the journal.</para></listitem>
 696       </varlistentry>
 697
 698       <varlistentry>
 699         <term><option>--system</option></term>
 700         <term><option>--user</option></term>
 701
 702         <listitem><para>Show messages from system services and the
 703         kernel (with <option>--system</option>). Show messages from
 704         service of current user (with <option>--user</option>).  If
 705         neither is specified, show all messages that the user can see.
 706         </para></listitem>
 707       </varlistentry>
 708
 709       <varlistentry>
 710         <term><option>-M</option></term>
 711         <term><option>--machine=</option></term>
 712
 713         <listitem><para>Show messages from a running, local
 714         container. Specify a container name to connect to.</para>
 715         </listitem>
 716       </varlistentry>
 717
 718       <varlistentry>
 719         <term><option>-D <replaceable>DIR</replaceable></option></term>
 720         <term><option>--directory=<replaceable>DIR</replaceable></option></term>
 721
 722         <listitem><para>Takes a directory path as argument. If
 723         specified, journalctl will operate on the specified journal
 724         directory <replaceable>DIR</replaceable> instead of the
 725         default runtime and system journal paths.</para></listitem>
 726       </varlistentry>
 727
 728       <varlistentry>
 729         <term><option>--file=<replaceable>GLOB</replaceable></option></term>
 730
 731         <listitem><para>Takes a file glob as an argument. If
 732         specified, journalctl will operate on the specified journal
 733         files matching <replaceable>GLOB</replaceable> instead of the
 734         default runtime and system journal paths. May be specified
 735         multiple times, in which case files will be suitably
 736         interleaved.</para></listitem>
 737       </varlistentry>
 738
 739       <varlistentry>
 740         <term><option>--root=<replaceable>ROOT</replaceable></option></term>
 741
 742         <listitem><para>Takes a directory path as an argument. If
 743         specified, journalctl will operate on journal directories and catalog file hierarchy
 744         underneath the specified directory instead of the root
 745         directory (e.g. <option>--update-catalog</option> will create
 746         <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>,
 747         and journal files under <filename><replaceable>ROOT</replaceable>/run/journal</filename>
 748         or <filename><replaceable>ROOT</replaceable>/var/log/journal</filename> will be displayed).
 749         </para></listitem>
 750       </varlistentry>
 751
 752       <varlistentry>
 753         <term><option>--namespace=<replaceable>NAMESPACE</replaceable></option></term>
 754
 755         <listitem><para>Takes a journal namespace identifier string as argument. If not specified the data
 756         collected by the default namespace is shown. If specified shows the log data of the specified
 757         namespace instead. If the namespace is specified as <literal>*</literal> data from all namespaces is
 758         shown, interleaved. If the namespace identifier is prefixed with <literal>+</literal> data from the
 759         specified namespace and the default namespace is shown, interleaved, but no other. For details about
 760         journal namespaces see
 761         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
 762       </varlistentry>
 763
 764       <varlistentry>
 765         <term><option>--header</option></term>
 766
 767         <listitem><para>Instead of showing journal contents, show
 768         internal header information of the journal fields
 769         accessed.</para></listitem>
 770       </varlistentry>
 771
 772       <varlistentry>
 773         <term><option>--disk-usage</option></term>
 774
 775         <listitem><para>Shows the current disk usage of all journal
 776         files. This shows the sum of the disk usage of all archived
 777         and active journal files.</para></listitem>
 778       </varlistentry>
 779
 780       <varlistentry>
 781         <term><option>--vacuum-size=</option></term>
 782         <term><option>--vacuum-time=</option></term>
 783         <term><option>--vacuum-files=</option></term>
 784
 785         <listitem><para>Removes the oldest archived journal files until the disk space they use falls below the
 786         specified size (specified with the usual <literal>K</literal>, <literal>M</literal>, <literal>G</literal> and
 787         <literal>T</literal> suffixes), or all archived journal files contain no data older than the specified timespan
 788         (specified with the usual <literal>s</literal>, <literal>m</literal>, <literal>h</literal>,
 789         <literal>days</literal>, <literal>months</literal>, <literal>weeks</literal> and <literal>years</literal>
 790         suffixes), or no more than the specified number of separate journal files remain. Note that running
 791         <option>--vacuum-size=</option> has only an indirect effect on the output shown by
 792         <option>--disk-usage</option>, as the latter includes active journal files, while the vacuuming operation only
 793         operates on archived journal files. Similarly, <option>--vacuum-files=</option> might not actually reduce the
 794         number of journal files to below the specified number, as it will not remove active journal
 795         files.</para>
 796
 797         <para><option>--vacuum-size=</option>, <option>--vacuum-time=</option> and <option>--vacuum-files=</option>
 798         may be combined in a single invocation to enforce any combination of a size, a time and a number of files limit
 799         on the archived journal files. Specifying any of these three parameters as zero is equivalent to not enforcing
 800         the specific limit, and is thus redundant.</para>
 801
 802         <para>These three switches may also be combined with <option>--rotate</option> into one command. If so, all
 803         active files are rotated first, and the requested vacuuming operation is executed right after. The rotation has
 804         the effect that all currently active files are archived (and potentially new, empty journal files opened as
 805         replacement), and hence the vacuuming operation has the greatest effect as it can take all log data written so
 806         far into account.</para></listitem>
 807       </varlistentry>
 808
 809       <varlistentry>
 810         <term><option>--list-catalog
 811         <optional><replaceable>128-bit-ID…</replaceable></optional>
 812         </option></term>
 813
 814         <listitem><para>List the contents of the message catalog as a
 815         table of message IDs, plus their short description strings.
 816         </para>
 817
 818         <para>If any <replaceable>128-bit-ID</replaceable>s are
 819         specified, only those entries are shown.</para>
 820         </listitem>
 821       </varlistentry>
 822
 823       <varlistentry>
 824         <term><option>--dump-catalog
 825         <optional><replaceable>128-bit-ID…</replaceable></optional>
 826         </option></term>
 827
 828         <listitem><para>Show the contents of the message catalog, with
 829         entries separated by a line consisting of two dashes and the
 830         ID (the format is the same as <filename>.catalog</filename>
 831         files).</para>
 832
 833         <para>If any <replaceable>128-bit-ID</replaceable>s are
 834         specified, only those entries are shown.</para>
 835         </listitem>
 836       </varlistentry>
 837
 838       <varlistentry>
 839         <term><option>--update-catalog</option></term>
 840
 841         <listitem><para>Update the message catalog index. This command
 842         needs to be executed each time new catalog files are
 843         installed, removed, or updated to rebuild the binary catalog
 844         index.</para></listitem>
 845       </varlistentry>
 846
 847       <varlistentry>
 848         <term><option>--setup-keys</option></term>
 849
 850         <listitem><para>Instead of showing journal contents, generate
 851         a new key pair for Forward Secure Sealing (FSS). This will
 852         generate a sealing key and a verification key. The sealing key
 853         is stored in the journal data directory and shall remain on
 854         the host. The verification key should be stored
 855         externally. Refer to the <option>Seal=</option> option in
 856         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 857         for information on Forward Secure Sealing and for a link to a
 858         refereed scholarly paper detailing the cryptographic theory it
 859         is based on.</para></listitem>
 860       </varlistentry>
 861
 862       <varlistentry>
 863         <term><option>--force</option></term>
 864
 865         <listitem><para>When <option>--setup-keys</option> is passed
 866         and Forward Secure Sealing (FSS) has already been configured,
 867         recreate FSS keys.</para></listitem>
 868       </varlistentry>
 869
 870       <varlistentry>
 871         <term><option>--interval=</option></term>
 872
 873         <listitem><para>Specifies the change interval for the sealing
 874         key when generating an FSS key pair with
 875         <option>--setup-keys</option>. Shorter intervals increase CPU
 876         consumption but shorten the time range of undetectable journal
 877         alterations. Defaults to 15min.</para></listitem>
 878       </varlistentry>
 879
 880       <varlistentry>
 881         <term><option>--verify</option></term>
 882
 883         <listitem><para>Check the journal file for internal
 884         consistency. If the file has been generated with FSS enabled and
 885         the FSS verification key has been specified with
 886         <option>--verify-key=</option>, authenticity of the journal file
 887         is verified.</para></listitem>
 888       </varlistentry>
 889
 890       <varlistentry>
 891         <term><option>--verify-key=</option></term>
 892
 893         <listitem><para>Specifies the FSS verification key to use for
 894         the <option>--verify</option> operation.</para></listitem>
 895       </varlistentry>
 896
 897       <varlistentry>
 898         <term><option>--sync</option></term>
 899
 900         <listitem><para>Asks the journal daemon to write all yet
 901         unwritten journal data to the backing file system and
 902         synchronize all journals. This call does not return until the
 903         synchronization operation is complete. This command guarantees
 904         that any log messages written before its invocation are safely
 905         stored on disk at the time it returns.</para></listitem>
 906       </varlistentry>
 907
 908       <varlistentry>
 909         <term><option>--flush</option></term>
 910
 911         <listitem><para>Asks the journal daemon to flush any log data stored in
 912         <filename>/run/log/journal/</filename> into <filename>/var/log/journal/</filename>, if persistent
 913         storage is enabled. This call does not return until the operation is complete. Note that this call is
 914         idempotent: the data is only flushed from <filename>/run/log/journal/</filename> into
 915         <filename>/var/log/journal</filename> once during system runtime (but see
 916         <option>--relinquish-var</option> below), and this command exits cleanly without executing any
 917         operation if this has already happened. This command effectively guarantees that all data is flushed
 918         to <filename>/var/log/journal</filename> at the time it returns.</para></listitem>
 919       </varlistentry>
 920
 921       <varlistentry>
 922         <term><option>--relinquish-var</option></term>
 923
 924         <listitem><para>Asks the journal daemon for the reverse operation to <option>--flush</option>: if
 925         requested the daemon will write further log data to <filename>/run/log/journal/</filename> and stops
 926         writing to <filename>/var/log/journal/</filename>. A subsequent call to <option>--flush</option>
 927         causes the log output to switch back to <filename>/var/log/journal/</filename>, see
 928         above.</para></listitem>
 929       </varlistentry>
 930
 931       <varlistentry>
 932         <term><option>--smart-relinquish-var</option></term>
 933
 934         <listitem><para>Similar to <option>--relinquish-var</option> but executes no operation if the root file
 935         system and <filename>/var/lib/journal/</filename> reside on the same mount point. This operation is
 936         used during system shutdown in order to make the journal daemon stop writing data to
 937         <filename>/var/log/journal/</filename> in case that directory is located on a mount point that needs
 938         to be unmounted.</para></listitem>
 939       </varlistentry>
 940
 941       <varlistentry>
 942         <term><option>--rotate</option></term>
 943
 944         <listitem><para>Asks the journal daemon to rotate journal files. This call does not return until the rotation
 945         operation is complete. Journal file rotation has the effect that all currently active journal files are marked
 946         as archived and renamed, so that they are never written to in future. New (empty) journal files are then
 947         created in their place. This operation may be combined with <option>--vacuum-size=</option>,
 948         <option>--vacuum-time=</option> and <option>--vacuum-file=</option> into a single command, see
 949         above.</para></listitem>
 950       </varlistentry>
 951
 952       <xi:include href="standard-options.xml" xpointer="help" />
 953       <xi:include href="standard-options.xml" xpointer="version" />
 954       <xi:include href="standard-options.xml" xpointer="no-pager" />
 955     </variablelist>
 956   </refsect1>
 957
 958   <refsect1>
 959     <title>Exit status</title>
 960
 961     <para>On success, 0 is returned; otherwise, a non-zero failure
 962     code is returned.</para>
 963   </refsect1>
 964
 965   <xi:include href="less-variables.xml" />
 966
 967   <refsect1>
 968     <title>Examples</title>
 969
 970     <para>Without arguments, all collected logs are shown
 971     unfiltered:</para>
 972
 973     <programlisting>journalctl</programlisting>
 974
 975     <para>With one match specified, all entries with a field matching
 976     the expression are shown:</para>
 977
 978     <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service
 979 journalctl _SYSTEMD_CGROUP=/user.slice/user-42.slice/session-c1.scope</programlisting>
 980
 981     <para>If two different fields are matched, only entries matching
 982     both expressions at the same time are shown:</para>
 983
 984     <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
 985
 986     <para>If two matches refer to the same field, all entries matching
 987     either expression are shown:</para>
 988
 989     <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
 990
 991     <para>If the separator <literal>+</literal> is used, two
 992     expressions may be combined in a logical OR. The following will
 993     show all messages from the Avahi service process with the PID
 994     28097 plus all messages from the D-Bus service (from any of its
 995     processes):</para>
 996
 997     <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
 998
 999     <para>To show all fields emitted <emphasis>by</emphasis> a unit and <emphasis>about</emphasis>
1000     the unit, option <option>-u</option>/<option>--unit=</option> should be used.
1001     <command>journalctl -u <replaceable>name</replaceable></command>
1002     expands to a complex filter similar to
1003     <programlisting>_SYSTEMD_UNIT=<replaceable>name</replaceable>.service
1004   + UNIT=<replaceable>name</replaceable>.service _PID=1
1005   + OBJECT_SYSTEMD_UNIT=<replaceable>name</replaceable>.service _UID=0
1006   + COREDUMP_UNIT=<replaceable>name</replaceable>.service _UID=0 MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1
1007     </programlisting>
1008     (see <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1009     for an explanation of those patterns).
1010     </para>
1011
1012     <para>Show all logs generated by the D-Bus executable:</para>
1013
1014     <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
1015
1016     <para>Show all kernel logs from previous boot:</para>
1017
1018     <programlisting>journalctl -k -b -1</programlisting>
1019
1020     <para>Show a live log display from a system service
1021     <filename>apache.service</filename>:</para>
1022
1023     <programlisting>journalctl -f -u apache</programlisting>
1024
1025   </refsect1>
1026
1027   <refsect1>
1028     <title>See Also</title>
1029     <para>
1030       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1031       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1032       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1033       <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1034       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1035       <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1036       <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1037       <citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1038       <citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
1039     </para>
1040   </refsect1>
1041 </refentry>