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>Output is interleaved from all accessible
  90                 journal files, whether they are rotated or currently
  91                 being written, and regardless whether they belong to the
  92                 system itself or are accessible user journals.</para>
  93
  94                 <para>All users are granted access to their private
  95                 per-user journals. However, by default only root and
  96                 users who are members of the <literal>adm</literal>
  97                 group get access to the system journal and the
  98                 journals of other users.</para>
  99         </refsect1>
 100
 101         <refsect1>
 102                 <title>Options</title>
 103
 104                 <para>The following options are understood:</para>
 105
 106                 <variablelist>
 107                         <varlistentry>
 108                                 <term><option>--help</option></term>
 109                                 <term><option>-h</option></term>
 110
 111                                 <listitem><para>Prints a short help
 112                                 text and exits.</para></listitem>
 113                         </varlistentry>
 114
 115                         <varlistentry>
 116                                 <term><option>--version</option></term>
 117
 118                                 <listitem><para>Prints a short version
 119                                 string and exits.</para></listitem>
 120                         </varlistentry>
 121
 122                         <varlistentry>
 123                                 <term><option>--no-pager</option></term>
 124
 125                                 <listitem><para>Do not pipe output into a
 126                                 pager.</para></listitem>
 127                         </varlistentry>
 128
 129                         <varlistentry>
 130                                 <term><option>--all</option></term>
 131                                 <term><option>-a</option></term>
 132
 133                                 <listitem><para>Show all fields in
 134                                 full, even if they include unprintable
 135                                 characters or are very
 136                                 long.</para></listitem>
 137                         </varlistentry>
 138
 139                         <varlistentry>
 140                                 <term><option>--follow</option></term>
 141                                 <term><option>-f</option></term>
 142
 143                                 <listitem><para>Show only most recent
 144                                 journal entries, and continuously print
 145                                 new entries as they are appended to
 146                                 the journal.</para></listitem>
 147                         </varlistentry>
 148
 149                         <varlistentry>
 150                                 <term><option>--lines=</option></term>
 151                                 <term><option>-n</option></term>
 152
 153                                 <listitem><para>Controls the number of
 154                                 journal lines to show, counting from
 155                                 the most recent ones. Takes a positive
 156                                 integer argument. In follow mode
 157                                 defaults to 10, otherwise is unset
 158                                 thus not limiting how many lines are
 159                                 shown.</para></listitem>
 160                         </varlistentry>
 161
 162                         <varlistentry>
 163                                 <term><option>--no-tail</option></term>
 164
 165                                 <listitem><para>Show all stored output
 166                                 lines, even in follow mode. Undoes the
 167                                 effect of
 168                                 <option>--lines=</option>.</para></listitem>
 169                         </varlistentry>
 170
 171                         <varlistentry>
 172                                 <term><option>--output=</option></term>
 173                                 <term><option>-o</option></term>
 174
 175                                 <listitem><para>Controls the
 176                                 formatting of the journal entries that
 177                                 are shown. Takes one of
 178                                 <literal>short</literal>,
 179                                 <literal>short-monotonic</literal>,
 180                                 <literal>verbose</literal>,
 181                                 <literal>export</literal>,
 182                                 <literal>json</literal>,
 183                                 <literal>cat</literal>. <literal>short</literal>
 184                                 is the default and generates an output
 185                                 that is mostly identical to the
 186                                 formatting of classic syslog log
 187                                 files, showing one line per journal
 188                                 entry. <literal>short-monotonic</literal>
 189                                 is very similar but shows monotonic
 190                                 timestamps instead of wallclock
 191                                 timestamps. <literal>verbose</literal>
 192                                 shows the full structured entry items
 193                                 with all
 194                                 fields. <literal>export</literal>
 195                                 serializes the journal into a binary
 196                                 (but mostly text-based) stream
 197                                 suitable for backups and network
 198                                 transfer (see <ulink
 199                                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 200                                 Export Format</ulink> for more
 201                                 information). <literal>json</literal>
 202                                 formats entries as JSON data
 203                                 structures. <literal>cat</literal>
 204                                 generates a very terse output only
 205                                 showing the actual message of each
 206                                 journal entry with no meta data, not
 207                                 even a timestamp.</para></listitem>
 208                         </varlistentry>
 209
 210                         <varlistentry>
 211                                 <term><option>--quiet</option></term>
 212                                 <term><option>-q</option></term>
 213
 214                                 <listitem><para>Suppresses any warning
 215                                 message regarding inaccessible system
 216                                 journals when run as normal
 217                                 user.</para></listitem>
 218                         </varlistentry>
 219
 220                         <varlistentry>
 221                                 <term><option>--local</option></term>
 222                                 <term><option>-l</option></term>
 223
 224                                 <listitem><para>Show only locally
 225                                 generated messages.</para></listitem>
 226                         </varlistentry>
 227
 228                         <varlistentry>
 229                                 <term><option>--this-boot</option></term>
 230                                 <term><option>-b</option></term>
 231
 232                                 <listitem><para>Show data only from
 233                                 current boot.</para></listitem>
 234                         </varlistentry>
 235
 236                         <varlistentry>
 237                                 <term><option>--directory=</option></term>
 238                                 <term><option>-D</option></term>
 239
 240                                 <listitem><para>Takes an absolute
 241                                 directory path as argument. If
 242                                 specified will operate on the
 243                                 specified journal directory instead of
 244                                 the default runtime and system journal
 245                                 paths.</para></listitem>
 246                         </varlistentry>
 247
 248                         <varlistentry>
 249                                 <term><option>--new-id128</option></term>
 250
 251                                 <listitem><para>Instead of showing
 252                                 journal contents generate a new 128
 253                                 bit ID suitable for identifying
 254                                 messages. This is intended for usage
 255                                 by developers who need a new
 256                                 identifier for a new message they
 257                                 introduce and want to make
 258                                 recognizable. Will print the new ID in
 259                                 three different formats which can be
 260                                 copied into source code or
 261                                 similar.</para></listitem>
 262                         </varlistentry>
 263
 264                         <varlistentry>
 265                                 <term><option>--header</option></term>
 266
 267                                 <listitem><para>Instead of showing
 268                                 journal contents show internal header
 269                                 information of the journal fiels
 270                                 accessed.</para></listitem>
 271                         </varlistentry>
 272
 273                         <varlistentry>
 274                                 <term><option>-p</option></term>
 275                                 <term><option>--priority=</option></term>
 276
 277                                 <listitem><para>Filter output by
 278                                 message priorities or priority
 279                                 ranges. Takes either a single numeric
 280                                 or textual log level (i.e. between
 281                                 0/<literal>emerg</literal> and
 282                                 7/<literal>debug</literal>), or a
 283                                 range of numeric/text log levels in
 284                                 the form FROM..TO. The log levels are
 285                                 the usual syslog log levels as
 286                                 documented in
 287                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 288                                 i.e. <literal>emerg</literal> (0),
 289                                 <literal>alert</literal> (1),
 290                                 <literal>crit</literal> (2),
 291                                 <literal>err</literal> (3),
 292                                 <literal>warning</literal> (4),
 293                                 <literal>notice</literal> (5),
 294                                 <literal>info</literal> (6),
 295                                 <literal>debug</literal> (7). If a
 296                                 single log level is specified all
 297                                 messages with this log levels or a
 298                                 lower (hence more important) log level
 299                                 are shown. If a range is specified all
 300                                 messages within the range are shown,
 301                                 including both the start and the end
 302                                 value of the range.</para></listitem>
 303                         </varlistentry>
 304
 305                 </variablelist>
 306         </refsect1>
 307
 308         <refsect1>
 309                 <title>Exit status</title>
 310
 311                 <para>On success 0 is returned, a non-zero failure
 312                 code otherwise.</para>
 313         </refsect1>
 314
 315         <refsect1>
 316                 <title>Environment</title>
 317
 318                 <variablelist>
 319                         <varlistentry>
 320                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 321                                 <listitem><para>Pager to use when
 322                                 <option>--no-pager</option> is not given;
 323                                 overrides <varname>$PAGER</varname>.  Setting
 324                                 this to an empty string or the value
 325                                 <literal>cat</literal> is equivalent to passing
 326                                 <option>--no-pager</option>.</para></listitem>
 327                         </varlistentry>
 328                 </variablelist>
 329         </refsect1>
 330
 331         <refsect1>
 332                 <title>Examples</title>
 333
 334                 <para>Without arguments all collected logs are shown
 335                 unfiltered:</para>
 336
 337                 <programlisting>journalctl</programlisting>
 338
 339                 <para>With one match specified all entries with a field matching the expression are shown:</para>
 340
 341                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting>
 342
 343                 <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para>
 344
 345                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting>
 346
 347                 <para>If two matches refer to the same field all entries matching either expression are shown:</para>
 348
 349                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting>
 350
 351                 <para>If the separator "<literal>+</literal>" is used
 352                 two expression may be combined in a logical OR. The
 353                 following will show all messages from the Avahi
 354                 service process with the PID 28097 plus all messages
 355                 from the D-Bus service (from any of its
 356                 processes):</para>
 357
 358                 <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting>
 359
 360         </refsect1>
 361
 362         <refsect1>
 363                 <title>See Also</title>
 364                 <para>
 365                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 366                         <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 367                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 368                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 369                         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 370                 </para>
 371         </refsect1>
 372
 373 </refentry>