<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="journalctl"
xmlns:xi="http://www.w3.org/2001/XInclude">
<para>When outputting to a tty, lines are colored according to
priority: lines of level ERROR and higher are colored red; lines
- of level NOTICE and higher are highlighted; other lines are
- displayed normally.</para>
+ of level NOTICE and higher are highlighted; lines of level DEBUG
+ are colored lighter grey; other lines are displayed normally.</para>
</refsect1>
<refsect1>
<term><option>-a</option></term>
<term><option>--all</option></term>
- <listitem><para>Show all fields in full, even if they
- include unprintable characters or are very
- long.</para></listitem>
+ <listitem><para>Show all fields in full, even if they include unprintable characters or are very long. By
+ default, fields with unprintable characters are abbreviated as "blob data". (Note that the pager may escape
+ unprintable characters again.)</para></listitem>
</varlistentry>
<varlistentry>
</varlistentry>
<varlistentry>
- <term><option>-b <optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional></option></term>
- <term><option>--boot=<optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional></option></term>
+ <term><option>-b <optional><optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional>|<constant>all</constant></optional></option></term>
+ <term><option>--boot<optional>=<optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional>|<constant>all</constant></optional></option></term>
<listitem><para>Show messages from a specific boot. This will
add a match for <literal>_BOOT_ID=</literal>.</para>
<replaceable>offset</replaceable> is not specified, a value of
zero is assumed, and the logs for the boot given by
<replaceable>ID</replaceable> are shown.</para>
+
+ <para>The special argument <constant>all</constant> can be
+ used to negate the effect of an earlier use of
+ <option>-b</option>.</para>
</listitem>
</varlistentry>
journal specified by the passed cursor.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--cursor-file=<replaceable>FILE</replaceable></option></term>
+
+ <listitem><para>If <replaceable>FILE</replaceable> exists and contains a
+ cursor, start showing entries <emphasis>after</emphasis> this location.
+ Otherwise the show entries according the other given options. At the end,
+ write the cursor of the last entry to <replaceable>FILE</replaceable>. Use
+ this option to continually read the journal by sequentially calling
+ <command>journalctl</command>.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--after-cursor=</option></term>
<term><option>--vacuum-time=</option></term>
<term><option>--vacuum-files=</option></term>
- <listitem><para>Removes the oldest archived journal files until the disk
- space they use falls below the specified size (specified with
- the usual <literal>K</literal>, <literal>M</literal>,
- <literal>G</literal> and <literal>T</literal> suffixes), or all
- archived journal files contain no data older than the specified
- timespan (specified with the usual <literal>s</literal>,
- <literal>m</literal>, <literal>h</literal>,
- <literal>days</literal>, <literal>months</literal>,
- <literal>weeks</literal> and <literal>years</literal> suffixes),
- or no more than the specified number of separate journal files
- remain. Note that running <option>--vacuum-size=</option> has
- only an indirect effect on the output shown by
- <option>--disk-usage</option>, as the latter includes active
- journal files, while the vacuuming operation only operates
- on archived journal files. Similarly,
- <option>--vacuum-files=</option> might not actually reduce the
- number of journal files to below the specified number, as it
- will not remove active journal
- files. <option>--vacuum-size=</option>,
- <option>--vacuum-time=</option> and
- <option>--vacuum-files=</option> may be combined in a single
- invocation to enforce any combination of a size, a time and a
- number of files limit on the archived journal
- files. Specifying any of these three parameters as zero is
- equivalent to not enforcing the specific limit, and is thus
- redundant.</para></listitem>
+ <listitem><para>Removes the oldest archived journal files until the disk space they use falls below the
+ specified size (specified with the usual <literal>K</literal>, <literal>M</literal>, <literal>G</literal> and
+ <literal>T</literal> suffixes), or all archived journal files contain no data older than the specified timespan
+ (specified with the usual <literal>s</literal>, <literal>m</literal>, <literal>h</literal>,
+ <literal>days</literal>, <literal>months</literal>, <literal>weeks</literal> and <literal>years</literal>
+ suffixes), or no more than the specified number of separate journal files remain. Note that running
+ <option>--vacuum-size=</option> has only an indirect effect on the output shown by
+ <option>--disk-usage</option>, as the latter includes active journal files, while the vacuuming operation only
+ operates on archived journal files. Similarly, <option>--vacuum-files=</option> might not actually reduce the
+ number of journal files to below the specified number, as it will not remove active journal
+ files.</para>
+
+ <para><option>--vacuum-size=</option>, <option>--vacuum-time=</option> and <option>--vacuum-files=</option>
+ may be combined in a single invocation to enforce any combination of a size, a time and a number of files limit
+ on the archived journal files. Specifying any of these three parameters as zero is equivalent to not enforcing
+ the specific limit, and is thus redundant.</para>
+
+ <para>These three switches may also be combined with <option>--rotate</option> into one command. If so, all
+ active files are rotated first, and the requested vacuuming operation is executed right after. The rotation has
+ the effect that all currently active files are archived (and potentially new, empty journal files opened as
+ replacement), and hence the vacuuming operation has the greatest effect as it can take all log data written so
+ far into account.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>--flush</option></term>
- <listitem><para>Asks the journal daemon to flush any log data
- stored in <filename>/run/log/journal</filename> into
- <filename>/var/log/journal</filename>, if persistent storage
- is enabled. This call does not return until the operation is
- complete. Note that this call is idempotent: the data is only
- flushed from <filename>/run/log/journal</filename> into
- <filename>/var/log/journal</filename> once during system
- runtime, and this command exits cleanly without executing any
- operation if this has already happened. This command
- effectively guarantees that all data is flushed to
- <filename>/var/log/journal</filename> at the time it
- returns.</para></listitem>
+ <listitem><para>Asks the journal daemon to flush any log data stored in
+ <filename>/run/log/journal/</filename> into <filename>/var/log/journal/</filename>, if persistent
+ storage is enabled. This call does not return until the operation is complete. Note that this call is
+ idempotent: the data is only flushed from <filename>/run/log/journal/</filename> into
+ <filename>/var/log/journal</filename> once during system runtime (but see
+ <option>--relinquish-var</option> below), and this command exits cleanly without executing any
+ operation if this has already happened. This command effectively guarantees that all data is flushed
+ to <filename>/var/log/journal</filename> at the time it returns.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--relinquish-var</option></term>
+
+ <listitem><para>Asks the journal daemon for the reverse operation to <option>--flush</option>: if
+ requested the daemon will write further log data to <filename>/run/log/journal/</filename> and stops
+ writing to <filename>/var/log/journal/</filename>. A subsequent call to <option>--flush</option>
+ causes the log output to switch back to <filename>/var/log/journal/</filename>, see
+ above.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--smart-relinquish-var</option></term>
+
+ <listitem><para>Similar to <option>--relinquish-var</option> but executes no operation if the root file
+ system and <filename>/var/lib/journal/</filename> reside on the same mount point. This operation is
+ used during system shutdown in order to make the journal daemon stop writing data to
+ <filename>/var/log/journal/</filename> in case that directory is located on a mount point that needs
+ to be unmounted.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--rotate</option></term>
- <listitem><para>Asks the journal daemon to rotate journal
- files. This call does not return until the rotation operation
- is complete.</para></listitem>
+ <listitem><para>Asks the journal daemon to rotate journal files. This call does not return until the rotation
+ operation is complete. Journal file rotation has the effect that all currently active journal files are marked
+ as archived and renamed, so that they are never written to in future. New (empty) journal files are then
+ created in their place. This operation may be combined with <option>--vacuum-size=</option>,
+ <option>--vacuum-time=</option> and <option>--vacuum-file=</option> into a single command, see
+ above.</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />