chiark / gitweb /
man: be more explicit about option arguments that take 128-bit IDs in journalctl(1)
[elogind.git] / man / journalctl.xml
index 0e779b9..23bb960 100644 (file)
@@ -84,7 +84,7 @@
                 alternatives, i.e. the resulting output will show
                 entries matching any of the specified matches for the
                 same field. Finally, if the character
-                <literal>+</literal> appears as separate word on the
+                <literal>+</literal> appears as separate word on the
                 command line, all matches before and after are combined
                 in a disjunction (i.e. logical OR).</para>
 
 
                 <para>All users are granted access to their private
                 per-user journals. However, by default, only root and
-                users who are members of the <literal>adm</literal>
+                users who are members of the <literal>systemd-journal</literal>
                 group get access to the system journal and the
                 journals of other users.</para>
 
                 <command>less</command> by default, and long lines are
                 "truncated" to screen width. The hidden part can be
                 viewed by using the left-arrow and right-arrow
-                keys. Paging can be disabled, see
-                <option>--no-pager</option> and section Environment
-                below.</para>
+                keys. Paging can be disabled; see the
+                <option>--no-pager</option> option and the "Environment"
+                section below.</para>
 
                 <para>When outputing 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, and other lines are displayed normally.
+                are colored red; lines of level NOTICE and higher are
+                highlighted; and other lines are displayed normally.
                 </para>
         </refsect1>
 
                         </varlistentry>
 
                         <varlistentry>
-                                <term><option>-l</option></term>
+                                <term><option>--no-full</option></term>
                                 <term><option>--full</option></term>
+                                <term><option>-l</option></term>
 
-                                <listitem><para>Show all (printable) fields in
-                                full.</para></listitem>
+                                <listitem><para>Ellipsize fields when
+                                they do not fit in available columns.
+                                The default is to show full fields,
+                                allowing them to wrap or be truncated
+                                by the pager, if one is used.</para>
+
+                                <para>The old options
+                                <option>-l</option>/<option>--full</option>
+                                are not useful anymore, except to undo
+                                <option>--no-full</option>.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 <term><option>-r</option></term>
                                 <term><option>--reverse</option></term>
 
-                                <listitem><para>Reverse output, so the newest
+                                <listitem><para>Reverse output so the newest
                                 entries are displayed first.</para></listitem>
                         </varlistentry>
 
 
                                 <listitem><para>Controls the
                                 formatting of the journal entries that
-                                are shown. Takes one of
-                                <literal>short</literal>,
-                                <literal>short-monotonic</literal>,
-                                <literal>verbose</literal>,
-                                <literal>export</literal>,
-                                <literal>json</literal>,
-                                <literal>json-pretty</literal>,
-                                <literal>json-sse</literal>,
-                                <literal>cat</literal>. <literal>short</literal>
-                                is the default and generates an output
-                                that is mostly identical to the
-                                formatting of classic syslog
-                                files, showing one line per journal
-                                entry. <literal>short-monotonic</literal>
-                                is very similar but shows monotonic
-                                timestamps instead of wallclock
-                                timestamps. <literal>verbose</literal>
-                                shows the full structured entry items
-                                with all
-                                fields. <literal>export</literal>
-                                serializes the journal into a binary
-                                (but mostly text-based) stream
-                                suitable for backups and network
-                                transfer (see <ulink
-                                url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
-                                Export Format</ulink> for more
-                                information). <literal>json</literal>
-                                formats entries as JSON data
-                                structures, one per
-                                line (see <ulink
-                                url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
-                                JSON Format</ulink> for more
-                                information). <literal>json-pretty</literal>
-                                also formats entries as JSON data
-                                structures, but formats them in
-                                multiple lines in order to make them
-                                more readable for
-                                humans. <literal>json-sse</literal>
-                                also formats entries as JSON data
-                                structures, but wraps them in a format
-                                suitable for <ulink
-                                url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent
-                                Events</ulink>. <literal>cat</literal>
-                                generates a very terse output only
-                                showing the actual message of each
-                                journal entry with no meta data, not
-                                even a timestamp.</para></listitem>
+                                are shown. Takes one of the following options:
+                                </para>
+                                <variablelist>
+                                        <varlistentry>
+                                                <term>
+                                                        <option>short</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>is the default
+                                                        and generates an output
+                                                        that is mostly identical
+                                                        to the formatting of
+                                                        classic syslog files,
+                                                        showing one line per
+                                                        journal entry.</para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>short-iso</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>is very similar,
+                                                        but shows ISO 8601
+                                                        wallclock timestamps.
+                                                        </para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>short-precise</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>is very similar,
+                                                        but shows timestamps
+                                                        with full microsecond
+                                                        precision.
+                                                        </para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>short-monotonic</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>is very similar,
+                                                        but shows monotonic
+                                                        timestamps instead of
+                                                        wallclock timestamps.
+                                                        </para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>verbose</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>shows the
+                                                        full-structured entry
+                                                        items with all fields.
+                                                        </para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>export</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>serializes the
+                                                        journal into a binary
+                                                        (but mostly text-based)
+                                                        stream suitable for
+                                                        backups and network
+                                                        transfer (see <ulink
+                                                        url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
+                                                        Export Format</ulink>
+                                                        for more
+                                                        information).</para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>json</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>formats entries
+                                                        as JSON data structures,
+                                                        one per line (see <ulink
+                                                        url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
+                                                        JSON Format</ulink> for
+                                                        more information).</para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>json-pretty</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>formats entries as
+                                                        JSON data structures,
+                                                        but formats them in
+                                                        multiple lines in order
+                                                        to make them more
+                                                        readable by humans.</para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>json-sse</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>formats entries as
+                                                        JSON data structures,
+                                                        but wraps them in a
+                                                        format suitable for <ulink
+                                                        url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent
+                                                        Events</ulink>.</para>
+                                                </listitem>
+                                        </varlistentry>
+
+                                        <varlistentry>
+                                                <term>
+                                                        <option>cat</option>
+                                                </term>
+                                                <listitem>
+                                                        <para>generates a very
+                                                        terse output, only
+                                                        showing the actual
+                                                        message of each journal
+                                                        entry with no meta data,
+                                                        not even a timestamp.
+                                                        </para>
+                                                </listitem>
+                                        </varlistentry>
+                                </variablelist>
+                                </listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 context of an error or log event,
                                 possible solutions, as well as
                                 pointers to support forums, developer
-                                documentation and any other relevant
+                                documentation, and any other relevant
                                 manuals. Note that help texts are not
                                 available for all messages, but only
                                 for selected ones. For more
                                 please refer to the <ulink
                                 url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Message
                                 Catalog Developer
-                                Documentation</ulink>.</para></listitem>
+                                Documentation</ulink>.</para>
+
+                                <para>Note: when attaching
+                                <command>journalctl</command> output
+                                to bug reports, please do
+                                <emphasis>not</emphasis> use
+                                <option>-x</option>.</para>
+                                </listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 <term><option>--quiet</option></term>
 
                                 <listitem><para>Suppresses any warning
-                                message regarding inaccessible system
-                                journals when run as normal
+                                messages regarding inaccessible system
+                                journals when run as normal
                                 user.</para></listitem>
                         </varlistentry>
 
                         </varlistentry>
 
                         <varlistentry>
-                                <term><option>-b <optional><replaceable>ID</replaceable></optional></option></term>
-                                <term><option>--boot=<optional><replaceable>ID</replaceable></optional></option></term>
+                                <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>
 
-                                <listitem><para>Show messages from the specified
-                                boot <replaceable>ID</replaceable> or from
-                                current boot if no <replaceable>ID</replaceable>
-                                is given. This will add a match for
+                                <listitem><para>Show messages from a specific
+                                boot. This will add a match for
                                 <literal>_BOOT_ID=</literal>.</para>
 
-                                <para>The argument is a 128 bit ID given in
-                                short or UUID form and optionally followed by
-                                <literal>:n</literal> which identifies the nth
-                                boot relative to the boot ID given to the left
-                                of <literal>:</literal>. Supplying a negative
-                                value for n will look for a past boot and a
-                                positive value for a future boot. The boot IDs
-                                are searched for in chronological order. If no
-                                number is provided after <literal>:</literal>,
-                                <literal>-1</literal> is assumed. A value of 0
-                                is valid and equivalent to omitting
-                                <literal>:0</literal>.</para>
-
-                                <para>Alternatively, the argument may constist
-                                only of <literal>:n</literal>. In this case, a
-                                positive value will look up the nth boot
-                                starting from the beginning of the jouranl, a
-                                negative value will look up a previous boot
-                                relative to the current boot. <literal>:0</literal>
-                                will look for the current boot ID. Thus,
-                                <literal>:1</literal> is the first boot found in
-                                the journal, <literal>:2</literal> the second
-                                and so on; while <literal>:-1</literal> is the
-                                previous boot, <literal>:-2</literal> the boot
-                                before that and so on. Omitting a value after
-                                <literal>:</literal> will look for the previous
-                                boot.</para></listitem>
+                                <para>The argument may be empty, in which case
+                                logs for the current boot will be shown.</para>
+
+                                <para>If the boot ID is omitted, a positive
+                                <replaceable>offset</replaceable> will look up
+                                the boots starting from the beginning of the
+                                journal, and a equal-or-less-than zero
+                                <replaceable>offset</replaceable> will look up
+                                boots starting from the end of the
+                                journal. Thus, <constant>1</constant> means the
+                                first boot found in the journal in
+                                chronological order, <constant>2</constant> the
+                                second and so on; while <constant>-0</constant>
+                                is the last boot, <constant>-1</constant> the
+                                boot before last, and so on. An empty
+                                <replaceable>offset</replaceable> is equivalent
+                                to specifying <constant>-0</constant>, except
+                                when the current boot is not the last boot
+                                (e.g. because <option>--directory</option> was
+                                specified to look at logs from a different
+                                machine).</para>
+
+                                <para>If the 32-character
+                                <replaceable>ID</replaceable> is specified, it
+                                may optionally be followed by
+                                <replaceable>offset</replaceable> which
+                                identifies the boot relative to the one given by
+                                boot <replaceable>ID</replaceable>. Negative
+                                values mean earlier boots and a positive values
+                                mean later boots. If
+                                <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>
+
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--list-boots</option></term>
+
+                                <listitem><para>Show a tabular list of
+                                boot numbers (relative to the current
+                                boot), their IDs, and the timestamps
+                                of the first and last message
+                                pertaining to the boot.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>
+                                <term><option>--after-cursor=</option></term>
+
+                                <listitem><para>Start showing entries
+                                from the location in the journal
+                                <emphasis>after</emphasis> the
+                                location specified by the this cursor.
+                                The cursor is shown when the
+                                <option>--show-cursor</option> option
+                                is used.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--show-cursor</option></term>
+
+                                <listitem><para>The cursor is shown after the last
+                                entry after two dashes:</para>
+                                <programlisting>-- cursor: s=0639...</programlisting>
+                                <para>The format of the cursor is private
+                                and subject to change.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
                                 <term><option>--since=</option></term>
                                 <term><option>--until=</option></term>
 
 
                                 <listitem><para>Show messages from
                                 system services and the kernel (with
-                                <option>--system</option>).  Show
+                                <option>--system</option>). Show
                                 messages from service of current user
                                 (with <option>--user</option>).
                                 If neither is specified, show all
                         </varlistentry>
 
                         <varlistentry>
+                                <term><option>-M</option></term>
+                                <term><option>--machine=</option></term>
+
+                                <listitem><para>Show messages from a
+                                running, local container. Specify a
+                                container name to connect
+                                to.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
                                 <term><option>-D <replaceable>DIR</replaceable></option></term>
                                 <term><option>--directory=<replaceable>DIR</replaceable></option></term>
 
                         <varlistentry>
                                 <term><option>--file=<replaceable>GLOB</replaceable></option></term>
 
-                                <listitem><para>Takes a file glob as
+                                <listitem><para>Takes a file glob as an
                                 argument. If specified, journalctl will
                                 operate on the specified journal files
                                 matching <replaceable>GLOB</replaceable>
                                 instead of the default runtime and
                                 system journal paths. May be specified
-                                multiple times, in which case files will
+                                multiple times, in which case, files will
                                 be suitably interleaved.</para></listitem>
                         </varlistentry>
 
                                 <term><option>--root=<replaceable>ROOT</replaceable></option></term>
 
                                 <listitem><para>Takes a directory path
-                                as argument. If specified, journalctl
+                                as an argument. If specified, journalctl
                                 will operate on catalog file hierarchy
                                 underneath the specified directory
                                 instead of the root directory
                                 <term><option>--new-id128</option></term>
 
                                 <listitem><para>Instead of showing
-                                journal contents, generate a new 128
-                                bit ID suitable for identifying
+                                journal contents, generate a new 128-bit
+                                ID suitable for identifying
                                 messages. This is intended for usage
                                 by developers who need a new
                                 identifier for a new message they
 
                         <varlistentry>
                                 <term><option>--list-catalog
-                                <optional><replaceable>ID128...</replaceable></optional>
+                                <optional><replaceable>128-bit-ID...</replaceable></optional>
                                 </option></term>
 
                                 <listitem><para>List the contents of
-                                the message catalog, as table of
-                                message IDs plus their short
+                                the message catalog as a table of
+                                message IDs, plus their short
                                 description strings.</para>
 
                                 <para>If any
-                                <replaceable>ID128</replaceable>s are
+                                <replaceable>128-bit-ID</replaceable>s are
                                 specified, only those entries are shown.
                                 </para>
                                 </listitem>
 
                         <varlistentry>
                                 <term><option>--dump-catalog
-                                <optional><replaceable>ID128...</replaceable></optional>
+                                <optional><replaceable>128-bit-ID...</replaceable></optional>
                                 </option></term>
 
                                 <listitem><para>Show the contents of
                                 the message catalog, with entries
                                 separated by a line consisting of two
-                                dashes and the id (the format is the
+                                dashes and the ID (the format is the
                                 same as <filename>.catalog</filename>
-                                files.</para>
+                                files).</para>
 
                                 <para>If any
-                                <replaceable>ID128</replaceable>s are
+                                <replaceable>128-bit-ID</replaceable>s are
                                 specified, only those entries are shown.
                                 </para>
                                 </listitem>
                                 <listitem><para>Update the message
                                 catalog index. This command needs to
                                 be executed each time new catalog
-                                files are installed, removed or
+                                files are installed, removed, or
                                 updated to rebuild the binary catalog
                                 index.</para></listitem>
                         </varlistentry>
                         <varlistentry>
                                 <term><option>--force</option></term>
 
-                                <listitem><para>When --setup-keys is passed and
-                                Forward Secure Sealing has already been set up,
-                                recreate FSS keys.</para></listitem>
+                                <listitem><para>When
+                                <option>--setup-keys</option> is passed and
+                                Forward Secure Sealing (FSS) has already been
+                                configured, recreate FSS keys.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
         <refsect1>
                 <title>Exit status</title>
 
-                <para>On success, 0 is returned, a non-zero failure
-                code otherwise.</para>
+                <para>On success, 0 is returned; otherwise, a non-zero
+                failure code is returned.</para>
         </refsect1>
 
         <refsect1>
 
                 <programlisting>journalctl /dev/sda</programlisting>
 
-                <para>Show all kernel logs from last boot:</para>
+                <para>Show all kernel logs from previous boot:</para>
 
-                <programlisting>journalctl -k -b :</programlisting>
+                <programlisting>journalctl -k -b -1</programlisting>
 
         </refsect1>