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>--help</option></term>
 118                                 <term><option>-h</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>--all</option></term>
 140                                 <term><option>-a</option></term>
 141
 142                                 <listitem><para>Show all fields in
 143                                 full, even if they include unprintable
 144                                 characters or are very
 145                                 long.</para></listitem>
 146                         </varlistentry>
 147
 148                         <varlistentry>
 149                                 <term><option>--follow</option></term>
 150                                 <term><option>-f</option></term>
 151
 152                                 <listitem><para>Show only the most recent
 153                                 journal entries, and continuously print
 154                                 new entries as they are appended to
 155                                 the journal.</para></listitem>
 156                         </varlistentry>
 157
 158                         <varlistentry>
 159                                 <term><option>--lines=</option></term>
 160                                 <term><option>-n</option></term>
 161
 162                                 <listitem><para>Show the most recent
 163                                 journal events and limit the number of
 164                                 events shown. If
 165                                 <option>--follow</option> is used,
 166                                 this option is implied. The argument,
 167                                 a positive integer, is optional, and
 168                                 defaults to 10. </para></listitem>
 169                         </varlistentry>
 170
 171                         <varlistentry>
 172                                 <term><option>--no-tail</option></term>
 173
 174                                 <listitem><para>Show all stored output
 175                                 lines, even in follow mode. Undoes the
 176                                 effect of
 177                                 <option>--lines=</option>.</para></listitem>
 178                         </varlistentry>
 179
 180                         <varlistentry>
 181                                 <term><option>--output=</option></term>
 182                                 <term><option>-o</option></term>
 183
 184                                 <listitem><para>Controls the
 185                                 formatting of the journal entries that
 186                                 are shown. Takes one of
 187                                 <literal>short</literal>,
 188                                 <literal>short-monotonic</literal>,
 189                                 <literal>verbose</literal>,
 190                                 <literal>export</literal>,
 191                                 <literal>json</literal>,
 192                                 <literal>json-pretty</literal>,
 193                                 <literal>json-sse</literal>,
 194                                 <literal>cat</literal>. <literal>short</literal>
 195                                 is the default and generates an output
 196                                 that is mostly identical to the
 197                                 formatting of classic syslog log
 198                                 files, showing one line per journal
 199                                 entry. <literal>short-monotonic</literal>
 200                                 is very similar but shows monotonic
 201                                 timestamps instead of wallclock
 202                                 timestamps. <literal>verbose</literal>
 203                                 shows the full structured entry items
 204                                 with all
 205                                 fields. <literal>export</literal>
 206                                 serializes the journal into a binary
 207                                 (but mostly text-based) stream
 208                                 suitable for backups and network
 209                                 transfer (see <ulink
 210                                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 211                                 Export Format</ulink> for more
 212                                 information). <literal>json</literal>
 213                                 formats entries as JSON data
 214                                 structures, one per
 215                                 line (see <ulink
 216                                 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
 217                                 JSON Format</ulink> for more
 218                                 information). <literal>json-pretty</literal>
 219                                 also formats entries as JSON data
 220                                 structures, but formats them in
 221                                 multiple lines in order to make them
 222                                 more readable for
 223                                 humans. <literal>json-sse</literal>
 224                                 also formats entries as JSON data
 225                                 structures, but wraps them in a format
 226                                 suitable for <ulink
 227                                 url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent
 228                                 Events</ulink>. <literal>cat</literal>
 229                                 generates a very terse output only
 230                                 showing the actual message of each
 231                                 journal entry with no meta data, not
 232                                 even a timestamp.</para></listitem>
 233                         </varlistentry>
 234
 235                         <varlistentry>
 236                                 <term><option>--catalog</option></term>
 237                                 <term><option>-x</option></term>
 238
 239                                 <listitem><para>Augment log lines with
 240                                 explanation texts from the message
 241                                 catalog. This will add explanatory
 242                                 help texts to log messages in the
 243                                 output where this is available. These
 244                                 short help texts will explain the
 245                                 context of an error or log event,
 246                                 possible solutions, as well as
 247                                 pointers to support forums, developer
 248                                 documentation and any other relevant
 249                                 manuals. Note that help texts are not
 250                                 available for all messages, but only
 251                                 for selected ones. For more
 252                                 information on the message catalog
 253                                 please refer to the <ulink
 254                                 url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Message
 255                                 Catalog Developer
 256                                 Documentation</ulink>.</para></listitem>
 257                         </varlistentry>
 258
 259                         <varlistentry>
 260                                 <term><option>--quiet</option></term>
 261                                 <term><option>-q</option></term>
 262
 263                                 <listitem><para>Suppresses any warning
 264                                 message regarding inaccessible system
 265                                 journals when run as normal
 266                                 user.</para></listitem>
 267                         </varlistentry>
 268
 269                         <varlistentry>
 270                                 <term><option>--merge</option></term>
 271                                 <term><option>-m</option></term>
 272
 273                                 <listitem><para>Show entries
 274                                 interleaved from all available
 275                                 journals, including remote
 276                                 ones.</para></listitem>
 277                         </varlistentry>
 278
 279                         <varlistentry>
 280                                 <term><option>--this-boot</option></term>
 281                                 <term><option>-b</option></term>
 282
 283                                 <listitem><para>Show data only from
 284                                 current boot. This will add a match
 285                                 for <literal>_BOOT_ID=</literal> for
 286                                 the current boot ID of the
 287                                 kernel.</para></listitem>
 288                         </varlistentry>
 289
 290                         <varlistentry>
 291                                 <term><option>--unit=</option></term>
 292                                 <term><option>-u</option></term>
 293
 294                                 <listitem><para>Show data only of the
 295                                 specified unit. This will add a match
 296                                 for <literal>_SYSTEMD_UNIT=</literal>
 297                                 for the specified
 298                                 unit.</para></listitem>
 299                         </varlistentry>
 300
 301                         <varlistentry>
 302                                 <term><option>-p</option></term>
 303                                 <term><option>--priority=</option></term>
 304
 305                                 <listitem><para>Filter output by
 306                                 message priorities or priority
 307                                 ranges. Takes either a single numeric
 308                                 or textual log level (i.e. between
 309                                 0/<literal>emerg</literal> and
 310                                 7/<literal>debug</literal>), or a
 311                                 range of numeric/text log levels in
 312                                 the form FROM..TO. The log levels are
 313                                 the usual syslog log levels as
 314                                 documented in
 315                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 316                                 i.e. <literal>emerg</literal> (0),
 317                                 <literal>alert</literal> (1),
 318                                 <literal>crit</literal> (2),
 319                                 <literal>err</literal> (3),
 320                                 <literal>warning</literal> (4),
 321                                 <literal>notice</literal> (5),
 322                                 <literal>info</literal> (6),
 323                                 <literal>debug</literal> (7). If a
 324                                 single log level is specified all
 325                                 messages with this log level or a
 326                                 lower (hence more important) log level
 327                                 are shown. If a range is specified all
 328                                 messages within the range are shown,
 329                                 including both the start and the end
 330                                 value of the range. This will add
 331                                 <literal>PRIORITY=</literal> matches
 332                                 for the specified
 333                                 priorities.</para></listitem>
 334                         </varlistentry>
 335
 336                         <varlistentry>
 337                                 <term><option>--cursor=</option></term>
 338                                 <term><option>-c</option></term>
 339
 340                                 <listitem><para>Start showing entries
 341                                 from the location in the journal
 342                                 specified by the passed
 343                                 cursor.</para></listitem>
 344                         </varlistentry>
 345
 346                         <varlistentry>
 347                                 <term><option>--since=</option></term>
 348                                 <term><option>--until=</option></term>
 349
 350                                 <listitem><para>Start showing entries
 351                                 on or newer than the specified date,
 352                                 or on or older than the specified
 353                                 date, respectively. Date specifications should be of
 354                                 the format "2012-10-30 18:17:16". If
 355                                 the time part is omitted, 00:00:00 is
 356                                 assumed. If only the seconds component
 357                                 is omitted, :00 is assumed. If the
 358                                 date component is ommitted, the
 359                                 current day is assumed. Alternatively
 360                                 the strings
 361                                 <literal>yesterday</literal>,
 362                                 <literal>today</literal>,
 363                                 <literal>tomorrow</literal> are
 364                                 understood, which refer to 00:00:00 of
 365                                 the day before the current day, the
 366                                 current day, or the day after the
 367                                 current day, respectively. <literal>now</literal>
 368                                 refers to the current time. Finally,
 369                                 relative times may be specified,
 370                                 prefixed with <literal>-</literal> or
 371                                 <literal>+</literal>, referring to
 372                                 times before or after the current
 373                                 time, respectively.</para></listitem>
 374                         </varlistentry>
 375
 376                         <varlistentry>
 377                                 <term><option>--field=</option></term>
 378                                 <term><option>-F</option></term>
 379
 380                                 <listitem><para>Print all possible
 381                                 data values the specified field can
 382                                 take in all entries of the
 383                                 journal.</para></listitem>
 384                         </varlistentry>
 385
 386                         <varlistentry>
 387                                 <term><option>--directory=</option></term>
 388                                 <term><option>-D</option></term>
 389
 390                                 <listitem><para>Takes an absolute
 391                                 directory path as argument. If
 392                                 specified journalctl will operate on the
 393                                 specified journal directory instead of
 394                                 the default runtime and system journal
 395                                 paths.</para></listitem>
 396                         </varlistentry>
 397
 398                         <varlistentry>
 399                                 <term><option>--new-id128</option></term>
 400
 401                                 <listitem><para>Instead of showing
 402                                 journal contents generate a new 128
 403                                 bit ID suitable for identifying
 404                                 messages. This is intended for usage
 405                                 by developers who need a new
 406                                 identifier for a new message they
 407                                 introduce and want to make
 408                                 recognizable. Will print the new ID in
 409                                 three different formats which can be
 410                                 copied into source code or
 411                                 similar.</para></listitem>
 412                         </varlistentry>
 413
 414                         <varlistentry>
 415                                 <term><option>--header</option></term>
 416
 417                                 <listitem><para>Instead of showing
 418                                 journal contents show internal header
 419                                 information of the journal fields
 420                                 accessed.</para></listitem>
 421                         </varlistentry>
 422
 423                         <varlistentry>
 424                                 <term><option>--disk-usage</option></term>
 425
 426                                 <listitem><para>Shows the current disk
 427                                 usage of all
 428                                 journal files.</para></listitem>
 429                         </varlistentry>
 430
 431                         <varlistentry>
 432                                 <term><option>--list-catalog</option></term>
 433
 434                                 <listitem><para>List the contents of
 435                                 the message catalog, as table of
 436                                 message IDs plus their short
 437                                 description strings.</para></listitem>
 438                         </varlistentry>
 439
 440                         <varlistentry>
 441                                 <term><option>--update-catalog</option></term>
 442
 443                                 <listitem><para>Update the message
 444                                 catalog index. This command needs to
 445                                 be executed each time new catalog
 446                                 files are installed, removed or
 447                                 updated to rebuild the binary catalog
 448                                 index.</para></listitem>
 449                         </varlistentry>
 450
 451                         <varlistentry>
 452                                 <term><option>--setup-keys</option></term>
 453
 454                                 <listitem><para>Instead of showing
 455                                 journal contents generate a new key
 456                                 pair for Forward Secure Sealing
 457                                 (FSS). This will generate a sealing
 458                                 key and a verification key. The
 459                                 sealing key is stored in the journal
 460                                 data directory and shall remain on the
 461                                 host. The verification key should be
 462                                 stored externally.</para></listitem>
 463                         </varlistentry>
 464
 465                         <varlistentry>
 466                                 <term><option>--interval=</option></term>
 467
 468                                 <listitem><para>Specifies the change
 469                                 interval for the sealing key, when
 470                                 generating an FSS key pair with
 471                                 <option>--setup-keys</option>. Shorter
 472                                 intervals increase CPU consumption but
 473                                 shorten the time range of
 474                                 undetectable journal
 475                                 alterations. Defaults to
 476                                 15min.</para></listitem>
 477                         </varlistentry>
 478
 479                         <varlistentry>
 480                                 <term><option>--verify</option></term>
 481
 482                                 <listitem><para>Check the journal file
 483                                 for internal consistency. If the
 484                                 file has been generated with FSS
 485                                 enabled, and the FSS verification key
 486                                 has been specified with
 487                                 <option>--verify-key=</option>
 488                                 authenticity of the journal file is
 489                                 verified.</para></listitem>
 490                         </varlistentry>
 491
 492                         <varlistentry>
 493                                 <term><option>--verify-key=</option></term>
 494
 495                                 <listitem><para>Specifies the FSS
 496                                 verification key to use for the
 497                                 <option>--verify</option>
 498                                 operation.</para></listitem>
 499                         </varlistentry>
 500
 501                 </variablelist>
 502         </refsect1>
 503
 504         <refsect1>
 505                 <title>Exit status</title>
 506
 507                 <para>On success 0 is returned, a non-zero failure
 508                 code otherwise.</para>
 509         </refsect1>
 510
 511         <refsect1>
 512                 <title>Environment</title>
 513
 514                 <variablelist>
 515                         <varlistentry>
 516                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 517                                 <listitem><para>Pager to use when
 518                                 <option>--no-pager</option> is not given;
 519                                 overrides <varname>$PAGER</varname>.  Setting
 520                                 this to an empty string or the value
 521                                 <literal>cat</literal> is equivalent to passing
 522                                 <option>--no-pager</option>.</para></listitem>
 523                         </varlistentry>
 524                 </variablelist>
 525         </refsect1>
 526
 527         <refsect1>
 528                 <title>Examples</title>
 529
 530                 <para>Without arguments all collected logs are shown
 531                 unfiltered:</para>
 532
 533                 <programlisting>journalctl</programlisting>
 534
 535                 <para>With one match specified all entries with a field matching the expression are shown:</para>
 536
 537                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
 538
 539                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
 540
 541                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
 542
 543                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
 544
 545                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
 546
 547                 <para>If the separator "<literal>+</literal>" is used
 548                 two expressions may be combined in a logical OR. The
 549                 following will show all messages from the Avahi
 550                 service process with the PID 28097 plus all messages
 551                 from the D-Bus service (from any of its
 552                 processes):</para>
 553
 554                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
 555
 556                 <para>Show all logs generated by the D-Bus executable:</para>
 557
 558                 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
 559
 560                 <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
 561
 562                 <programlisting>journalctl /dev/sda</programlisting>
 563
 564         </refsect1>
 565
 566         <refsect1>
 567                 <title>See Also</title>
 568                 <para>
 569                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 570                         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 571                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 572                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 573                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 574                 </para>
 575         </refsect1>
 576
 577 </refentry>