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>--new-id128</option></term>
 452
 453                                 <listitem><para>Instead of showing
 454                                 journal contents generate a new 128
 455                                 bit ID suitable for identifying
 456                                 messages. This is intended for usage
 457                                 by developers who need a new
 458                                 identifier for a new message they
 459                                 introduce and want to make
 460                                 recognizable. Will print the new ID in
 461                                 three different formats which can be
 462                                 copied into source code or
 463                                 similar.</para></listitem>
 464                         </varlistentry>
 465
 466                         <varlistentry>
 467                                 <term><option>--header</option></term>
 468
 469                                 <listitem><para>Instead of showing
 470                                 journal contents show internal header
 471                                 information of the journal fields
 472                                 accessed.</para></listitem>
 473                         </varlistentry>
 474
 475                         <varlistentry>
 476                                 <term><option>--disk-usage</option></term>
 477
 478                                 <listitem><para>Shows the current disk
 479                                 usage of all
 480                                 journal files.</para></listitem>
 481                         </varlistentry>
 482
 483                         <varlistentry>
 484                                 <term><option>--list-catalog
 485                                 <optional><replaceable>ID128...</replaceable></optional>
 486                                 </option></term>
 487
 488                                 <listitem><para>List the contents of
 489                                 the message catalog, as table of
 490                                 message IDs plus their short
 491                                 description strings.</para>
 492
 493                                 <para>If any
 494                                 <replaceable>ID128</replaceable>s are
 495                                 specified, only those entries are shown.
 496                                 </para>
 497                                 </listitem>
 498                         </varlistentry>
 499
 500                         <varlistentry>
 501                                 <term><option>--dump-catalog
 502                                 <optional><replaceable>ID128...</replaceable></optional>
 503                                 </option></term>
 504
 505                                 <listitem><para>Show the contents of
 506                                 the message catalog, with entries
 507                                 separated by a line consisting of two
 508                                 dashes and the id (the format is the
 509                                 same as <filename>.catalog</filename>
 510                                 files.</para>
 511
 512                                 <para>If any
 513                                 <replaceable>ID128</replaceable>s are
 514                                 specified, only those entries are shown.
 515                                 </para>
 516                                 </listitem>
 517                         </varlistentry>
 518
 519                         <varlistentry>
 520                                 <term><option>--update-catalog</option></term>
 521
 522                                 <listitem><para>Update the message
 523                                 catalog index. This command needs to
 524                                 be executed each time new catalog
 525                                 files are installed, removed or
 526                                 updated to rebuild the binary catalog
 527                                 index.</para></listitem>
 528                         </varlistentry>
 529
 530                         <varlistentry>
 531                                 <term><option>--setup-keys</option></term>
 532
 533                                 <listitem><para>Instead of showing
 534                                 journal contents generate a new key
 535                                 pair for Forward Secure Sealing
 536                                 (FSS). This will generate a sealing
 537                                 key and a verification key. The
 538                                 sealing key is stored in the journal
 539                                 data directory and shall remain on the
 540                                 host. The verification key should be
 541                                 stored externally.</para></listitem>
 542                         </varlistentry>
 543
 544                         <varlistentry>
 545                                 <term><option>--interval=</option></term>
 546
 547                                 <listitem><para>Specifies the change
 548                                 interval for the sealing key, when
 549                                 generating an FSS key pair with
 550                                 <option>--setup-keys</option>. Shorter
 551                                 intervals increase CPU consumption but
 552                                 shorten the time range of
 553                                 undetectable journal
 554                                 alterations. Defaults to
 555                                 15min.</para></listitem>
 556                         </varlistentry>
 557
 558                         <varlistentry>
 559                                 <term><option>--verify</option></term>
 560
 561                                 <listitem><para>Check the journal file
 562                                 for internal consistency. If the
 563                                 file has been generated with FSS
 564                                 enabled, and the FSS verification key
 565                                 has been specified with
 566                                 <option>--verify-key=</option>
 567                                 authenticity of the journal file is
 568                                 verified.</para></listitem>
 569                         </varlistentry>
 570
 571                         <varlistentry>
 572                                 <term><option>--verify-key=</option></term>
 573
 574                                 <listitem><para>Specifies the FSS
 575                                 verification key to use for the
 576                                 <option>--verify</option>
 577                                 operation.</para></listitem>
 578                         </varlistentry>
 579
 580                 </variablelist>
 581         </refsect1>
 582
 583         <refsect1>
 584                 <title>Exit status</title>
 585
 586                 <para>On success 0 is returned, a non-zero failure
 587                 code otherwise.</para>
 588         </refsect1>
 589
 590         <refsect1>
 591                 <title>Environment</title>
 592
 593                 <variablelist class='environment-variables'>
 594                         <varlistentry>
 595                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 596                                 <listitem><para>Pager to use when
 597                                 <option>--no-pager</option> is not given;
 598                                 overrides <varname>$PAGER</varname>.  Setting
 599                                 this to an empty string or the value
 600                                 <literal>cat</literal> is equivalent to passing
 601                                 <option>--no-pager</option>.</para></listitem>
 602                         </varlistentry>
 603                 </variablelist>
 604         </refsect1>
 605
 606         <refsect1>
 607                 <title>Examples</title>
 608
 609                 <para>Without arguments all collected logs are shown
 610                 unfiltered:</para>
 611
 612                 <programlisting>journalctl</programlisting>
 613
 614                 <para>With one match specified all entries with a field matching the expression are shown:</para>
 615
 616                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
 617
 618                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
 619
 620                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
 621
 622                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
 623
 624                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
 625
 626                 <para>If the separator "<literal>+</literal>" is used
 627                 two expressions may be combined in a logical OR. The
 628                 following will show all messages from the Avahi
 629                 service process with the PID 28097 plus all messages
 630                 from the D-Bus service (from any of its
 631                 processes):</para>
 632
 633                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
 634
 635                 <para>Show all logs generated by the D-Bus executable:</para>
 636
 637                 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
 638
 639                 <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
 640
 641                 <programlisting>journalctl /dev/sda</programlisting>
 642
 643         </refsect1>
 644
 645         <refsect1>
 646                 <title>See Also</title>
 647                 <para>
 648                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 649                         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 650                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 651                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 652                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 653                 </para>
 654         </refsect1>
 655
 656 </refentry>