<title>Description</title>
<para>Entries in the journal resemble an environment
- block in their syntax, however with fields that can
+ block in their syntax but with fields that can
include binary data. Primarily, fields are formatted
UTF-8 text strings, and binary formatting is used only
where formatting as UTF-8 text strings makes little
sense. New fields may freely be defined by
applications, but a few fields have special
meaning. All fields with special meanings are
- optional. In some cases fields may appear more than
+ optional. In some cases, fields may appear more than
once per entry.</para>
</refsect1>
<para>User fields are fields that are directly passed
from clients and stored in the journal.</para>
- <variablelist>
+ <variablelist class='journal-directives'>
<varlistentry>
- <term>MESSAGE=</term>
+ <term><varname>MESSAGE=</varname></term>
<listitem>
- <para>The human readable
+ <para>The human-readable
message string for this
entry. This is supposed to be
the primary text shown to the
</varlistentry>
<varlistentry>
- <term>MESSAGE_ID=</term>
+ <term><varname>MESSAGE_ID=</varname></term>
<listitem>
- <para>A 128bit message
+ <para>A 128-bit message
identifier ID for recognizing
certain message types, if this
is desirable. This should
- contain a 128bit id formatted
- as lower-case hexadecimal
+ contain a 128-bit ID formatted
+ as a lower-case hexadecimal
string, without any separating
dashes or suchlike. This is
- recommended to be a UUID
- compatible ID, but this is not
+ recommended to be a
+ UUID-compatible ID, but this is not
enforced, and formatted
differently. Developers can
generate a new ID for this
- purpose with
- <command>journalctl
- --new-id</command>.</para>
+ purpose with <command>journalctl
+ <option>--new-id</option></command>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>PRIORITY=</term>
+ <term><varname>PRIORITY=</varname></term>
<listitem>
<para>A priority value between
0 (<literal>emerg</literal>)
and 7
(<literal>debug</literal>)
- formatted as decimal
+ formatted as a decimal
string. This field is
compatible with syslog's
priority concept.</para>
</varlistentry>
<varlistentry>
- <term>CODE_FILE=</term>
- <term>CODE_LINE=</term>
- <term>CODE_FUNC=</term>
+ <term><varname>CODE_FILE=</varname></term>
+ <term><varname>CODE_LINE=</varname></term>
+ <term><varname>CODE_FUNC=</varname></term>
<listitem>
<para>The code location
generating this message, if
known. Contains the source
- file name, the line number and
+ filename, the line number and
the function name.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>ERRNO=</term>
+ <term><varname>ERRNO=</varname></term>
<listitem>
<para>The low-level Unix error
number causing this entry, if
any. Contains the numeric
value of
<citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- formatted as decimal
+ formatted as a decimal
string.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>SYSLOG_FACILITY=</term>
- <term>SYSLOG_IDENTIFIER=</term>
- <term>SYSLOG_PID=</term>
+ <term><varname>SYSLOG_FACILITY=</varname></term>
+ <term><varname>SYSLOG_IDENTIFIER=</varname></term>
+ <term><varname>SYSLOG_PID=</varname></term>
<listitem>
<para>Syslog compatibility
fields containing the facility
(formatted as decimal string),
the identifier string
(i.e. "tag"), and the client
- PID.</para>
+ PID. (Note that the tag is
+ usually derived from glibc's
+ <varname>program_invocation_short_name</varname>
+ variable, see <citerefentry><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para>
</listitem>
</varlistentry>
fields, i.e. fields that are implicitly added by the
journal and cannot be altered by client code.</para>
- <variablelist>
+ <variablelist class='journal-directives'>
<varlistentry>
- <term>_PID=</term>
- <term>_UID=</term>
- <term>_GID=</term>
+ <term><varname>_PID=</varname></term>
+ <term><varname>_UID=</varname></term>
+ <term><varname>_GID=</varname></term>
<listitem>
- <para>The process, user and
+ <para>The process, user, and
group ID of the process the
journal entry originates from
- formatted as decimal
+ formatted as a decimal
string.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_COMM=</term>
- <term>_EXE=</term>
- <term>_CMDLINE=</term>
+ <term><varname>_COMM=</varname></term>
+ <term><varname>_EXE=</varname></term>
+ <term><varname>_CMDLINE=</varname></term>
<listitem>
<para>The name, the executable
- path and the command line of
+ path, and the command line of
the process the journal entry
originates from.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_AUDIT_SESSION=</term>
- <term>_AUDIT_LOGINUID=</term>
+ <term><varname>_CAP_EFFECTIVE=</varname></term>
+ <listitem>
+ <para>The effective <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of
+ the process the journal entry
+ originates from.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>_AUDIT_SESSION=</varname></term>
+ <term><varname>_AUDIT_LOGINUID=</varname></term>
<listitem>
<para>The session and login
UID of the process the journal
</varlistentry>
<varlistentry>
- <term>_SYSTEMD_CGROUP=</term>
- <term>_SYSTEMD_SESSION=</term>
- <term>_SYSTEMD_UNIT=</term>
- <term>_SYSTEMD_OWNER_UID=</term>
+ <term><varname>_SYSTEMD_CGROUP=</varname></term>
+ <term><varname>_SYSTEMD_SESSION=</varname></term>
+ <term><varname>_SYSTEMD_UNIT=</varname></term>
+ <term><varname>_SYSTEMD_USER_UNIT=</varname></term>
+ <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
+ <term><varname>_SYSTEMD_SLICE=</varname></term>
<listitem>
- <para>The contol group path in
- the systemd hierarchy, the
+ <para>The control group path
+ in the systemd hierarchy, the
systemd session ID (if any),
- the systemd unit name (if any)
- and the owner UID of the
- systemd session (if any) of
- the process the journal entry
- originates from.</para>
+ the systemd unit name (if
+ any), the systemd user session
+ unit name (if any), the owner
+ UID of the systemd session (if
+ any) and the systemd slice
+ unit of the process the
+ journal entry originates
+ from.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_SELINUX_CONTEXT=</term>
+ <term><varname>_SELINUX_CONTEXT=</varname></term>
<listitem>
<para>The SELinux security
- context of the process the
- journal entry originates
+ context (label) of the process
+ the journal entry originates
from.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_SOURCE_REALTIME_TIMESTAMP=</term>
+ <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
<listitem>
<para>The earliest trusted
timestamp of the message, if
any is known that is different
from the reception time of the
journal. This is the time in
- usec since the epoch UTC
- formatted as decimal
+ microseconds since the epoch UTC,
+ formatted as a decimal
string.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_BOOT_ID=</term>
+ <term><varname>_BOOT_ID=</varname></term>
<listitem>
<para>The kernel boot ID for
the boot the message was
generated in, formatted as
- 128bit hexadecimal
+ a 128-bit hexadecimal
string.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_MACHINE_ID=</term>
+ <term><varname>_MACHINE_ID=</varname></term>
<listitem>
<para>The machine ID of the
originating host, as available
</varlistentry>
<varlistentry>
- <term>_HOSTNAME=</term>
+ <term><varname>_HOSTNAME=</varname></term>
<listitem>
<para>The name of the
originating host.</para>
</varlistentry>
<varlistentry>
- <term>_TRANSPORT=</term>
+ <term><varname>_TRANSPORT=</varname></term>
<listitem>
<para>How the entry was
received by the journal
- service. One of
- <literal>driver</literal>,
- <literal>syslog</literal>,
- <literal>journal</literal>,
- <literal>stdout</literal>,
- <literal>kernel</literal> for
- internally generated messages,
- for those received via the
- local syslog socket with the
- syslog protocol, for those
- received via the native
- journal protocol, for the
- those read from a services'
- standard output or error
- output, and for those read
- from the kernel, resp.
+ service. Valid transports are:
</para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>driver</option>
+ </term>
+ <listitem>
+ <para>for
+ internally
+ generated
+ messages
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>syslog</option>
+ </term>
+ <listitem>
+ <para>for those
+ received via the
+ local syslog
+ socket with the
+ syslog protocol
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>journal</option>
+ </term>
+ <listitem>
+ <para>for those
+ received via the
+ native journal
+ protocol
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>stdout</option>
+ </term>
+ <listitem>
+ <para>for those
+ read from a
+ service's
+ standard output
+ or error output
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>kernel</option>
+ </term>
+ <listitem>
+ <para>for those
+ read from the
+ kernel
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
messages originating in the kernel and stored in the
journal.</para>
- <variablelist>
+ <variablelist class='journal-directives'>
<varlistentry>
- <term>_KERNEL_DEVICE=</term>
+ <term><varname>_KERNEL_DEVICE=</varname></term>
<listitem>
<para>The kernel device
name. If the entry is
associated to a block device,
the major and minor of the
- device node, separated by ':'
- and prefixed by 'b'. Similar
- for character devices, but
- prefixed by 'c'. For network
- devices the interface index,
- prefixed by 'n'. For all other
- devices '+' followed by the
- subsystem name, followed by
- ':', followed by the kernel
+ device node, separated by <literal>:</literal>
+ and prefixed by <literal>b</literal>. Similar
+ for character devices but
+ prefixed by <literal>c</literal>. For network
+ devices, this is the interface index
+ prefixed by <literal>n</literal>. For all other
+ devices, this is the subsystem name
+ prefixed by <literal>+</literal>, followed by
+ <literal>:</literal>, followed by the kernel
device name.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_KERNEL_SUBSYSTEM=</term>
+ <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
<listitem>
<para>The kernel subsystem name.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>_UDEV_SYSNAME=</term>
+ <term><varname>_UDEV_SYSNAME=</varname></term>
<listitem>
<para>The kernel device name
as it shows up in the device
</listitem>
</varlistentry>
<varlistentry>
- <term>_UDEV_DEVNODE=</term>
+ <term><varname>_UDEV_DEVNODE=</varname></term>
<listitem>
<para>The device node path of
this device in
</listitem>
</varlistentry>
<varlistentry>
- <term>_UDEV_DEVLINK=</term>
+ <term><varname>_UDEV_DEVLINK=</varname></term>
<listitem>
<para>Additional symlink names
pointing to the device node in
</variablelist>
</refsect1>
+ <refsect1>
+ <title>Fields to log on behalf of a different program</title>
+
+ <para>Fields in this section are used by programs
+ to specify that they are logging on behalf of another
+ program or unit.
+ </para>
+
+ <para>Fields used by the <command>systemd-coredump</command>
+ coredump kernel helper:
+ </para>
+
+ <variablelist class='journal-directives'>
+ <varlistentry>
+ <term><varname>COREDUMP_UNIT=</varname></term>
+ <term><varname>COREDUMP_USER_UNIT=</varname></term>
+ <listitem>
+ <para>Used to annotate
+ messages containing coredumps from
+ system and session units.
+ See
+ <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Priviledged programs (currently UID 0) may
+ attach <varname>OBJECT_PID=</varname> to a
+ message. This will instruct
+ <command>systemd-journald</command> to attach
+ additional fields on behalf of the caller:</para>
+
+ <variablelist class='journal-directives'>
+ <varlistentry>
+ <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
+ <listitem>
+ <para>PID of the program that this
+ message pertains to.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>OBJECT_UID=</varname></term>
+ <term><varname>OBJECT_GID=</varname></term>
+ <term><varname>OBJECT_COMM=</varname></term>
+ <term><varname>OBJECT_EXE=</varname></term>
+ <term><varname>OBJECT_CMDLINE=</varname></term>
+ <term><varname>OBJECT_AUDIT_SESSION=</varname></term>
+ <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
+ <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
+ <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
+ <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
+ <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
+ <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
+ <listitem>
+ <para>These are additional fields added automatically
+ by <command>systemd-journald</command>.
+ Their meaning is the same as
+ <varname>_UID=</varname>,
+ <varname>_GID=</varname>,
+ <varname>_COMM=</varname>,
+ <varname>_EXE=</varname>,
+ <varname>_CMDLINE=</varname>,
+ <varname>_AUDIT_SESSION=</varname>,
+ <varname>_AUDIT_LOGINUID=</varname>,
+ <varname>_SYSTEMD_CGROUP=</varname>,
+ <varname>_SYSTEMD_SESSION=</varname>,
+ <varname>_SYSTEMD_UNIT=</varname>,
+ <varname>_SYSTEMD_USER_UNIT=</varname>, and
+ <varname>_SYSTEMD_OWNER_UID=</varname>
+ as described above, except that the
+ process identified by <replaceable>PID</replaceable>
+ is described, instead of the process
+ which logged the message.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+
+ </refsect1>
+
<refsect1>
<title>Address Fields</title>
- <para>During serialization into external formats the
- addresses of journal entries are serialized into
- fields prefixed with double underscores. Note that
- these aren't proper fields when stored in the journal,
- but addressing meta data of entries. They cannot be
- written as part of structured log entries via calls
- such as
+ <para>During serialization into external formats, such
+ as the <ulink
+ url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
+ Export Format</ulink> or the <ulink
+ url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
+ JSON Format</ulink>, the addresses of journal entries
+ are serialized into fields prefixed with double
+ underscores. Note that these are not proper fields when
+ stored in the journal but for addressing metadata of
+ entries. They cannot be written as part of structured
+ log entries via calls such as
<citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
may also not be used as matches for
<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
- <variablelist>
+ <variablelist class='journal-directives'>
<varlistentry>
- <term>__CURSOR=</term>
+ <term><varname>__CURSOR=</varname></term>
<listitem>
<para>The cursor for the
entry. A cursor is an opaque
describes the position of an
entry in the journal and is
portable across machines,
- platforms and journal
- files.</para>
+ platforms and journal files.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>__REALTIME_TIMESTAMP=</term>
+ <term><varname>__REALTIME_TIMESTAMP=</varname></term>
<listitem>
<para>The wallclock time
- (CLOCK_REALTIME) at the point
- in time the entry was received
- by the journal, in usec since
- the epoch UTC formatted as
- decimal string. This has
- different properties from
- <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>
+ (<constant>CLOCK_REALTIME</constant>)
+ at the point in time the entry
+ was received by the journal,
+ in microseconds since the epoch
+ UTC, formatted as a decimal
+ string. This has different
+ properties from
+ <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
as it is usually a bit later
- but more likely to be
- monotonic.</para>
+ but more likely to be monotonic.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>__MONOTONIC_TIMESTAMP=</term>
+ <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
<listitem>
<para>The monotonic time
- (CLOCK_MONOTONIC) at the point
- in time the entry was received
- by the journal in usec
- formatted as decimal
+ (<constant>CLOCK_MONOTONIC</constant>)
+ at the point in time the entry
+ was received by the journal in
+ microseconds, formatted as a decimal
string. To be useful as an
- address for the entry this
- should be combined with with
- boot ID in
- <literal>_BOOT_ID=</literal>.</para>
+ address for the entry, this
+ should be combined with with the
+ boot ID in <literal>_BOOT_ID=</literal>.
+ </para>
</listitem>
</varlistentry>
</variablelist>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff