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 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 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>Controls the number of
 163                                 journal lines to show, counting from
 164                                 the most recent ones. Takes a positive
 165                                 integer argument. In follow mode
 166                                 defaults to 10, otherwise is unset
 167                                 thus not limiting how many lines are
 168                                 shown.</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>cat</literal>. <literal>short</literal>
 193                                 is the default and generates an output
 194                                 that is mostly identical to the
 195                                 formatting of classic syslog log
 196                                 files, showing one line per journal
 197                                 entry. <literal>short-monotonic</literal>
 198                                 is very similar but shows monotonic
 199                                 timestamps instead of wallclock
 200                                 timestamps. <literal>verbose</literal>
 201                                 shows the full structured entry items
 202                                 with all
 203                                 fields. <literal>export</literal>
 204                                 serializes the journal into a binary
 205                                 (but mostly text-based) stream
 206                                 suitable for backups and network
 207                                 transfer (see <ulink
 208                                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 209                                 Export Format</ulink> for more
 210                                 information). <literal>json</literal>
 211                                 formats entries as JSON data
 212                                 structures. <literal>cat</literal>
 213                                 generates a very terse output only
 214                                 showing the actual message of each
 215                                 journal entry with no meta data, not
 216                                 even a timestamp.</para></listitem>
 217                         </varlistentry>
 218
 219                         <varlistentry>
 220                                 <term><option>--quiet</option></term>
 221                                 <term><option>-q</option></term>
 222
 223                                 <listitem><para>Suppresses any warning
 224                                 message regarding inaccessible system
 225                                 journals when run as normal
 226                                 user.</para></listitem>
 227                         </varlistentry>
 228
 229                         <varlistentry>
 230                                 <term><option>--local</option></term>
 231                                 <term><option>-l</option></term>
 232
 233                                 <listitem><para>Show only locally
 234                                 generated messages.</para></listitem>
 235                         </varlistentry>
 236
 237                         <varlistentry>
 238                                 <term><option>--this-boot</option></term>
 239                                 <term><option>-b</option></term>
 240
 241                                 <listitem><para>Show data only from
 242                                 current boot.</para></listitem>
 243                         </varlistentry>
 244
 245                         <varlistentry>
 246                                 <term><option>--directory=</option></term>
 247                                 <term><option>-D</option></term>
 248
 249                                 <listitem><para>Takes an absolute
 250                                 directory path as argument. If
 251                                 specified will operate on the
 252                                 specified journal directory instead of
 253                                 the default runtime and system journal
 254                                 paths.</para></listitem>
 255                         </varlistentry>
 256
 257                         <varlistentry>
 258                                 <term><option>--new-id128</option></term>
 259
 260                                 <listitem><para>Instead of showing
 261                                 journal contents generate a new 128
 262                                 bit ID suitable for identifying
 263                                 messages. This is intended for usage
 264                                 by developers who need a new
 265                                 identifier for a new message they
 266                                 introduce and want to make
 267                                 recognizable. Will print the new ID in
 268                                 three different formats which can be
 269                                 copied into source code or
 270                                 similar.</para></listitem>
 271                         </varlistentry>
 272
 273                         <varlistentry>
 274                                 <term><option>--header</option></term>
 275
 276                                 <listitem><para>Instead of showing
 277                                 journal contents show internal header
 278                                 information of the journal fiels
 279                                 accessed.</para></listitem>
 280                         </varlistentry>
 281
 282                         <varlistentry>
 283                                 <term><option>-p</option></term>
 284                                 <term><option>--priority=</option></term>
 285
 286                                 <listitem><para>Filter output by
 287                                 message priorities or priority
 288                                 ranges. Takes either a single numeric
 289                                 or textual log level (i.e. between
 290                                 0/<literal>emerg</literal> and
 291                                 7/<literal>debug</literal>), or a
 292                                 range of numeric/text log levels in
 293                                 the form FROM..TO. The log levels are
 294                                 the usual syslog log levels as
 295                                 documented in
 296                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 297                                 i.e. <literal>emerg</literal> (0),
 298                                 <literal>alert</literal> (1),
 299                                 <literal>crit</literal> (2),
 300                                 <literal>err</literal> (3),
 301                                 <literal>warning</literal> (4),
 302                                 <literal>notice</literal> (5),
 303                                 <literal>info</literal> (6),
 304                                 <literal>debug</literal> (7). If a
 305                                 single log level is specified all
 306                                 messages with this log levels or a
 307                                 lower (hence more important) log level
 308                                 are shown. If a range is specified all
 309                                 messages within the range are shown,
 310                                 including both the start and the end
 311                                 value of the range.</para></listitem>
 312                         </varlistentry>
 313
 314                 </variablelist>
 315         </refsect1>
 316
 317         <refsect1>
 318                 <title>Exit status</title>
 319
 320                 <para>On success 0 is returned, a non-zero failure
 321                 code otherwise.</para>
 322         </refsect1>
 323
 324         <refsect1>
 325                 <title>Environment</title>
 326
 327                 <variablelist>
 328                         <varlistentry>
 329                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 330                                 <listitem><para>Pager to use when
 331                                 <option>--no-pager</option> is not given;
 332                                 overrides <varname>$PAGER</varname>.  Setting
 333                                 this to an empty string or the value
 334                                 <literal>cat</literal> is equivalent to passing
 335                                 <option>--no-pager</option>.</para></listitem>
 336                         </varlistentry>
 337                 </variablelist>
 338         </refsect1>
 339
 340         <refsect1>
 341                 <title>Examples</title>
 342
 343                 <para>Without arguments all collected logs are shown
 344                 unfiltered:</para>
 345
 346                 <programlisting>journalctl</programlisting>
 347
 348                 <para>With one match specified all entries with a field matching the expression are shown:</para>
 349
 350                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
 351
 352                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
 353
 354                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
 355
 356                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
 357
 358                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
 359
 360                 <para>If the separator "<literal>+</literal>" is used
 361                 two expression may be combined in a logical OR. The
 362                 following will show all messages from the Avahi
 363                 service process with the PID 28097 plus all messages
 364                 from the D-Bus service (from any of its
 365                 processes):</para>
 366
 367                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
 368
 369                 <para>Show all logs generated by the D-Bus executable:</para>
 370
 371                 <programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
 372
 373                 <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
 374
 375                 <programlisting>journalctl /dev/sda</programlisting>
 376
 377         </refsect1>
 378
 379         <refsect1>
 380                 <title>See Also</title>
 381                 <para>
 382                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 383                         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 384                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 385                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 386                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 387                 </para>
 388         </refsect1>
 389
 390 </refentry>