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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">MATCHES</arg></command>
  53                 </cmdsynopsis>
  54         </refsynopsisdiv>
  55
  56         <refsect1>
  57                 <title>Description</title>
  58
  59                 <para><command>journalctl</command> may be used to
  60                 query the contents of the
  61                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  62                 journal as written by
  63                 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  64
  65                 <para>If called without parameter it will show the full
  66                 contents of the journal, starting with the oldest
  67                 entry collected.</para>
  68
  69                 <para>If one or more match arguments are passed the
  70                 output is filtered accordingly. A match is in the
  71                 format <literal>FIELD=VALUE</literal>,
  72                 e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>,
  73                 referring to the components of a structured journal
  74                 entry. See
  75                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  76                 for a list of well-known fields. If multiple matches
  77                 are specified matching different fields the log
  78                 entries are filtered by both, i.e. the resulting output
  79                 will show only entries matching all the specified
  80                 matches of this kind. If two matches apply to the same
  81                 field, then they are automatically matched as
  82                 alternatives, i.e. the resulting output will show
  83                 entries matching any of the specified matches for the
  84                 same field. Finally, if the character
  85                 "<literal>+</literal>" appears as separate word on the
  86                 command line all matches before and after are combined
  87                 in a disjunction (i.e. logical OR).</para>
  88
  89                 <para>As shortcuts for a few types of field/value
  90                 matches file paths may be specified. If a file path
  91                 refers to an executable file, this is equivalent to an
  92                 <literal>_EXE=</literal> match for the canonicalized
  93                 binary path. Similar, if a path refers to a device
  94                 node, this is equivalent to a
  95                 <literal>_KERNEL_DEVICE=</literal> match for the
  96                 device.</para>
  97
  98                 <para>Output is interleaved from all accessible
  99                 journal files, whether they are rotated or currently
 100                 being written, and regardless whether they belong to the
 101                 system itself or are accessible user journals.</para>
 102
 103                 <para>All users are granted access to their private
 104                 per-user journals. However, by default only root and
 105                 users who are members of the <literal>adm</literal>
 106                 group get access to the system journal and the
 107                 journals of other users.</para>
 108         </refsect1>
 109
 110         <refsect1>
 111                 <title>Options</title>
 112
 113                 <para>The following options are understood:</para>
 114
 115                 <variablelist>
 116                         <varlistentry>
 117                                 <term><option>-h</option></term>
 118                                 <term><option>--help</option></term>
 119
 120                                 <listitem><para>Prints a short help
 121                                 text and exits.</para></listitem>
 122                         </varlistentry>
 123
 124                         <varlistentry>
 125                                 <term><option>--version</option></term>
 126
 127                                 <listitem><para>Prints a short version
 128                                 string and exits.</para></listitem>
 129                         </varlistentry>
 130
 131                         <varlistentry>
 132                                 <term><option>--no-pager</option></term>
 133
 134                                 <listitem><para>Do not pipe output into a
 135                                 pager.</para></listitem>
 136                         </varlistentry>
 137
 138                         <varlistentry>
 139                                 <term><option>--full</option></term>
 140
 141                                 <listitem><para>Show all (printable) fields in
 142                                 full.</para></listitem>
 143                         </varlistentry>
 144
 145                         <varlistentry>
 146                                 <term><option>-a</option></term>
 147                                 <term><option>--all</option></term>
 148
 149                                 <listitem><para>Show all fields in
 150                                 full, even if they include unprintable
 151                                 characters or are very
 152                                 long.</para></listitem>
 153                         </varlistentry>
 154
 155                         <varlistentry>
 156                                 <term><option>-f</option></term>
 157                                 <term><option>--follow</option></term>
 158
 159                                 <listitem><para>Show only the most recent
 160                                 journal entries, and continuously print
 161                                 new entries as they are appended to
 162                                 the journal.</para></listitem>
 163                         </varlistentry>
 164
 165                         <varlistentry>
 166                                 <term><option>-e</option></term>
 167                                 <term><option>--pager-end</option></term>
 168
 169                                 <listitem><para>Immediately jump to
 170                                 the end of the journal inside the
 171                                 implied pager tool. This implies
 172                                 <option>-n1000</option> to guarantee
 173                                 that the pager won't buffer logs of
 174                                 unbounded size. This may be overridden
 175                                 with an explicit <option>-n</option>
 176                                 with some other numeric value on the
 177                                 command line. Note that this option is
 178                                 only supported for the
 179                                 <citerefentry><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 180                                 pager.</para></listitem>
 181                         </varlistentry>
 182
 183                         <varlistentry>
 184                                 <term><option>-n</option></term>
 185                                 <term><option>--lines=</option></term>
 186
 187                                 <listitem><para>Show the most recent
 188                                 journal events and limit the number of
 189                                 events shown. If
 190                                 <option>--follow</option> is used,
 191                                 this option is implied. The argument,
 192                                 a positive integer, is optional, and
 193                                 defaults to 10. </para></listitem>
 194                         </varlistentry>
 195
 196                         <varlistentry>
 197                                 <term><option>--no-tail</option></term>
 198
 199                                 <listitem><para>Show all stored output
 200                                 lines, even in follow mode. Undoes the
 201                                 effect of
 202                                 <option>--lines=</option>.</para></listitem>
 203                         </varlistentry>
 204
 205                         <varlistentry>
 206                                 <term><option>-r</option></term>
 207                                 <term><option>--reverse</option></term>
 208
 209                                 <listitem><para>Reverse output, so the newest
 210                                 entries are displayed first.</para></listitem>
 211                         </varlistentry>
 212
 213                         <varlistentry>
 214                                 <term><option>-o</option></term>
 215                                 <term><option>--output=</option></term>
 216
 217                                 <listitem><para>Controls the
 218                                 formatting of the journal entries that
 219                                 are shown. Takes one of
 220                                 <literal>short</literal>,
 221                                 <literal>short-monotonic</literal>,
 222                                 <literal>verbose</literal>,
 223                                 <literal>export</literal>,
 224                                 <literal>json</literal>,
 225                                 <literal>json-pretty</literal>,
 226                                 <literal>json-sse</literal>,
 227                                 <literal>cat</literal>. <literal>short</literal>
 228                                 is the default and generates an output
 229                                 that is mostly identical to the
 230                                 formatting of classic syslog log
 231                                 files, showing one line per journal
 232                                 entry. <literal>short-monotonic</literal>
 233                                 is very similar but shows monotonic
 234                                 timestamps instead of wallclock
 235                                 timestamps. <literal>verbose</literal>
 236                                 shows the full structured entry items
 237                                 with all
 238                                 fields. <literal>export</literal>
 239                                 serializes the journal into a binary
 240                                 (but mostly text-based) stream
 241                                 suitable for backups and network
 242                                 transfer (see <ulink
 243                                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 244                                 Export Format</ulink> for more
 245                                 information). <literal>json</literal>
 246                                 formats entries as JSON data
 247                                 structures, one per
 248                                 line (see <ulink
 249                                 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
 250                                 JSON Format</ulink> for more
 251                                 information). <literal>json-pretty</literal>
 252                                 also formats entries as JSON data
 253                                 structures, but formats them in
 254                                 multiple lines in order to make them
 255                                 more readable for
 256                                 humans. <literal>json-sse</literal>
 257                                 also formats entries as JSON data
 258                                 structures, but wraps them in a format
 259                                 suitable for <ulink
 260                                 url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent
 261                                 Events</ulink>. <literal>cat</literal>
 262                                 generates a very terse output only
 263                                 showing the actual message of each
 264                                 journal entry with no meta data, not
 265                                 even a timestamp.</para></listitem>
 266                         </varlistentry>
 267
 268                         <varlistentry>
 269                                 <term><option>-x</option></term>
 270                                 <term><option>--catalog</option></term>
 271
 272                                 <listitem><para>Augment log lines with
 273                                 explanation texts from the message
 274                                 catalog. This will add explanatory
 275                                 help texts to log messages in the
 276                                 output where this is available. These
 277                                 short help texts will explain the
 278                                 context of an error or log event,
 279                                 possible solutions, as well as
 280                                 pointers to support forums, developer
 281                                 documentation and any other relevant
 282                                 manuals. Note that help texts are not
 283                                 available for all messages, but only
 284                                 for selected ones. For more
 285                                 information on the message catalog
 286                                 please refer to the <ulink
 287                                 url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Message
 288                                 Catalog Developer
 289                                 Documentation</ulink>.</para></listitem>
 290                         </varlistentry>
 291
 292                         <varlistentry>
 293                                 <term><option>-q</option></term>
 294                                 <term><option>--quiet</option></term>
 295
 296                                 <listitem><para>Suppresses any warning
 297                                 message regarding inaccessible system
 298                                 journals when run as normal
 299                                 user.</para></listitem>
 300                         </varlistentry>
 301
 302                         <varlistentry>
 303                                 <term><option>-m</option></term>
 304                                 <term><option>--merge</option></term>
 305
 306                                 <listitem><para>Show entries
 307                                 interleaved from all available
 308                                 journals, including remote
 309                                 ones.</para></listitem>
 310                         </varlistentry>
 311
 312                         <varlistentry>
 313                                 <term><option>-b</option></term>
 314                                 <term><option>--this-boot</option></term>
 315
 316                                 <listitem><para>Show data only from
 317                                 current boot. This will add a match
 318                                 for <literal>_BOOT_ID=</literal> for
 319                                 the current boot ID of the
 320                                 kernel.</para></listitem>
 321                         </varlistentry>
 322
 323                         <varlistentry>
 324                                 <term><option>-u</option></term>
 325                                 <term><option>--unit=</option></term>
 326
 327                                 <listitem><para>Show messages for the
 328                                 specified systemd unit. This will add
 329                                 a match for messages from the unit
 330                                 (<literal>_SYSTEMD_UNIT=</literal>)
 331                                 and additional matches for messages
 332                                 from systemd and messages about
 333                                 coredumps for the specified unit.
 334                                 </para></listitem>
 335                         </varlistentry>
 336
 337                         <varlistentry>
 338                                 <term><option>--user-unit=</option></term>
 339
 340                                 <listitem><para>Show messages for the
 341                                 specified user session unit. This will
 342                                 add a match for messages from the unit
 343                                 (<literal>_SYSTEMD_USER_UNIT=</literal>
 344                                 and <literal>_UID=</literal>) and
 345                                 additional matches for messages from
 346                                 session systemd and messages about
 347                                 coredumps for the specified unit.
 348                                 </para></listitem>
 349                         </varlistentry>
 350
 351                         <varlistentry>
 352                                 <term><option>-p</option></term>
 353                                 <term><option>--priority=</option></term>
 354
 355                                 <listitem><para>Filter output by
 356                                 message priorities or priority
 357                                 ranges. Takes either a single numeric
 358                                 or textual log level (i.e. between
 359                                 0/<literal>emerg</literal> and
 360                                 7/<literal>debug</literal>), or a
 361                                 range of numeric/text log levels in
 362                                 the form FROM..TO. The log levels are
 363                                 the usual syslog log levels as
 364                                 documented in
 365                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 366                                 i.e. <literal>emerg</literal> (0),
 367                                 <literal>alert</literal> (1),
 368                                 <literal>crit</literal> (2),
 369                                 <literal>err</literal> (3),
 370                                 <literal>warning</literal> (4),
 371                                 <literal>notice</literal> (5),
 372                                 <literal>info</literal> (6),
 373                                 <literal>debug</literal> (7). If a
 374                                 single log level is specified all
 375                                 messages with this log level or a
 376                                 lower (hence more important) log level
 377                                 are shown. If a range is specified all
 378                                 messages within the range are shown,
 379                                 including both the start and the end
 380                                 value of the range. This will add
 381                                 <literal>PRIORITY=</literal> matches
 382                                 for the specified
 383                                 priorities.</para></listitem>
 384                         </varlistentry>
 385
 386                         <varlistentry>
 387                                 <term><option>-c</option></term>
 388                                 <term><option>--cursor=</option></term>
 389
 390                                 <listitem><para>Start showing entries
 391                                 from the location in the journal
 392                                 specified by the passed
 393                                 cursor.</para></listitem>
 394                         </varlistentry>
 395
 396                         <varlistentry>
 397                                 <term><option>--since=</option></term>
 398                                 <term><option>--until=</option></term>
 399
 400                                 <listitem><para>Start showing entries
 401                                 on or newer than the specified date,
 402                                 or on or older than the specified
 403                                 date, respectively. Date specifications should be of
 404                                 the format "2012-10-30 18:17:16". If
 405                                 the time part is omitted, 00:00:00 is
 406                                 assumed. If only the seconds component
 407                                 is omitted, :00 is assumed. If the
 408                                 date component is omitted, the
 409                                 current day is assumed. Alternatively
 410                                 the strings
 411                                 <literal>yesterday</literal>,
 412                                 <literal>today</literal>,
 413                                 <literal>tomorrow</literal> are
 414                                 understood, which refer to 00:00:00 of
 415                                 the day before the current day, the
 416                                 current day, or the day after the
 417                                 current day, respectively. <literal>now</literal>
 418                                 refers to the current time. Finally,
 419                                 relative times may be specified,
 420                                 prefixed with <literal>-</literal> or
 421                                 <literal>+</literal>, referring to
 422                                 times before or after the current
 423                                 time, respectively.</para></listitem>
 424                         </varlistentry>
 425
 426                         <varlistentry>
 427                                 <term><option>-F</option></term>
 428                                 <term><option>--field=</option></term>
 429
 430                                 <listitem><para>Print all possible
 431                                 data values the specified field can
 432                                 take in all entries of the
 433                                 journal.</para></listitem>
 434                         </varlistentry>
 435
 436                         <varlistentry>
 437                                 <term><option>-D</option></term>
 438                                 <term><option>--directory=</option></term>
 439
 440                                 <listitem><para>Takes a
 441                                 directory path as argument. If
 442                                 specified journalctl will operate on the
 443                                 specified journal directory instead of
 444                                 the default runtime and system journal
 445                                 paths.</para></listitem>
 446                         </varlistentry>
 447
 448                         <varlistentry>
 449                                 <term><option>--new-id128</option></term>
 450
 451                                 <listitem><para>Instead of showing
 452                                 journal contents generate a new 128
 453                                 bit ID suitable for identifying
 454                                 messages. This is intended for usage
 455                                 by developers who need a new
 456                                 identifier for a new message they
 457                                 introduce and want to make
 458                                 recognizable. Will print the new ID in
 459                                 three different formats which can be
 460                                 copied into source code or
 461                                 similar.</para></listitem>
 462                         </varlistentry>
 463
 464                         <varlistentry>
 465                                 <term><option>--header</option></term>
 466
 467                                 <listitem><para>Instead of showing
 468                                 journal contents show internal header
 469                                 information of the journal fields
 470                                 accessed.</para></listitem>
 471                         </varlistentry>
 472
 473                         <varlistentry>
 474                                 <term><option>--disk-usage</option></term>
 475
 476                                 <listitem><para>Shows the current disk
 477                                 usage of all
 478                                 journal files.</para></listitem>
 479                         </varlistentry>
 480
 481                         <varlistentry>
 482                                 <term><option>--list-catalog</option></term>
 483
 484                                 <listitem><para>List the contents of
 485                                 the message catalog, as table of
 486                                 message IDs plus their short
 487                                 description strings.</para></listitem>
 488                         </varlistentry>
 489
 490                         <varlistentry>
 491                                 <term><option>--update-catalog</option></term>
 492
 493                                 <listitem><para>Update the message
 494                                 catalog index. This command needs to
 495                                 be executed each time new catalog
 496                                 files are installed, removed or
 497                                 updated to rebuild the binary catalog
 498                                 index.</para></listitem>
 499                         </varlistentry>
 500
 501                         <varlistentry>
 502                                 <term><option>--setup-keys</option></term>
 503
 504                                 <listitem><para>Instead of showing
 505                                 journal contents generate a new key
 506                                 pair for Forward Secure Sealing
 507                                 (FSS). This will generate a sealing
 508                                 key and a verification key. The
 509                                 sealing key is stored in the journal
 510                                 data directory and shall remain on the
 511                                 host. The verification key should be
 512                                 stored externally.</para></listitem>
 513                         </varlistentry>
 514
 515                         <varlistentry>
 516                                 <term><option>--interval=</option></term>
 517
 518                                 <listitem><para>Specifies the change
 519                                 interval for the sealing key, when
 520                                 generating an FSS key pair with
 521                                 <option>--setup-keys</option>. Shorter
 522                                 intervals increase CPU consumption but
 523                                 shorten the time range of
 524                                 undetectable journal
 525                                 alterations. Defaults to
 526                                 15min.</para></listitem>
 527                         </varlistentry>
 528
 529                         <varlistentry>
 530                                 <term><option>--verify</option></term>
 531
 532                                 <listitem><para>Check the journal file
 533                                 for internal consistency. If the
 534                                 file has been generated with FSS
 535                                 enabled, and the FSS verification key
 536                                 has been specified with
 537                                 <option>--verify-key=</option>
 538                                 authenticity of the journal file is
 539                                 verified.</para></listitem>
 540                         </varlistentry>
 541
 542                         <varlistentry>
 543                                 <term><option>--verify-key=</option></term>
 544
 545                                 <listitem><para>Specifies the FSS
 546                                 verification key to use for the
 547                                 <option>--verify</option>
 548                                 operation.</para></listitem>
 549                         </varlistentry>
 550
 551                 </variablelist>
 552         </refsect1>
 553
 554         <refsect1>
 555                 <title>Exit status</title>
 556
 557                 <para>On success 0 is returned, a non-zero failure
 558                 code otherwise.</para>
 559         </refsect1>
 560
 561         <refsect1>
 562                 <title>Environment</title>
 563
 564                 <variablelist class='environment-variables'>
 565                         <varlistentry>
 566                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 567                                 <listitem><para>Pager to use when
 568                                 <option>--no-pager</option> is not given;
 569                                 overrides <varname>$PAGER</varname>.  Setting
 570                                 this to an empty string or the value
 571                                 <literal>cat</literal> is equivalent to passing
 572                                 <option>--no-pager</option>.</para></listitem>
 573                         </varlistentry>
 574                 </variablelist>
 575         </refsect1>
 576
 577         <refsect1>
 578                 <title>Examples</title>
 579
 580                 <para>Without arguments all collected logs are shown
 581                 unfiltered:</para>
 582
 583                 <programlisting>journalctl</programlisting>
 584
 585                 <para>With one match specified all entries with a field matching the expression are shown:</para>
 586
 587                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
 588
 589                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
 590
 591                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
 592
 593                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
 594
 595                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
 596
 597                 <para>If the separator "<literal>+</literal>" is used
 598                 two expressions may be combined in a logical OR. The
 599                 following will show all messages from the Avahi
 600                 service process with the PID 28097 plus all messages
 601                 from the D-Bus service (from any of its
 602                 processes):</para>
 603
 604                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
 605
 606                 <para>Show all logs generated by the D-Bus executable:</para>
 607
 608                 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
 609
 610                 <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
 611
 612                 <programlisting>journalctl /dev/sda</programlisting>
 613
 614         </refsect1>
 615
 616         <refsect1>
 617                 <title>See Also</title>
 618                 <para>
 619                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 620                         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 621                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 622                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 623                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 624                 </para>
 625         </refsect1>
 626
 627 </refentry>