[thirdparty/systemd.git] / man / systemd.journal-fields.xml

<?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">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd.journal-fields">

        <refentryinfo>
                <title>systemd.journal-fields</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd.journal-fields</refentrytitle>
                <manvolnum>7</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd.journal-fields</refname>
                <refpurpose>Special journal fields</refpurpose>
        </refnamediv>

        <refsect1>
                <title>Description</title>

                <para>Entries in the journal resemble an environment
                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
                once per entry.</para>
        </refsect1>

        <refsect1>
                <title>User Journal Fields</title>

                <para>User fields are fields that are directly passed
                from clients and stored in the journal.</para>

                <variablelist class='journal-directives'>
                        <varlistentry>
                                <term><varname>MESSAGE=</varname></term>
                                <listitem>
                                        <para>The human-readable
                                        message string for this
                                        entry. This is supposed to be
                                        the primary text shown to the
                                        user. It is usually not
                                        translated (but might be in
                                        some cases), and is not
                                        supposed to be parsed for meta
                                        data.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>MESSAGE_ID=</varname></term>
                                <listitem>
                                        <para>A 128-bit message
                                        identifier ID for recognizing
                                        certain message types, if this
                                        is desirable. This should
                                        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
                                        enforced, and formatted
                                        differently. Developers can
                                        generate a new ID for this
                                        purpose with <command>journalctl
                                        <option>--new-id</option></command>.
                                        </para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PRIORITY=</varname></term>
                                <listitem>
                                        <para>A priority value between
                                        0 (<literal>emerg</literal>)
                                        and 7
                                        (<literal>debug</literal>)
                                        formatted as a decimal
                                        string. This field is
                                        compatible with syslog's
                                        priority concept.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <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
                                        filename, the line number and
                                        the function name.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <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 a decimal
                                        string.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <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. (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>
                </variablelist>
        </refsect1>

        <refsect1>
                <title>Trusted Journal Fields</title>

                <para>Fields prefixed with an underscore are trusted
                fields, i.e. fields that are implicitly added by the
                journal and cannot be altered by client code.</para>

                <variablelist class='journal-directives'>
                        <varlistentry>
                                <term><varname>_PID=</varname></term>
                                <term><varname>_UID=</varname></term>
                                <term><varname>_GID=</varname></term>
                                <listitem>
                                        <para>The process, user, and
                                        group ID of the process the
                                        journal entry originates from
                                        formatted as a decimal
                                        string.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <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
                                        the process the journal entry
                                        originates from.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <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
                                        entry originates from, as
                                        maintained by the kernel audit
                                        subsystem.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <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 control group path
                                        in the systemd hierarchy, the
                                        systemd session ID (if any),
                                        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><varname>_SELINUX_CONTEXT=</varname></term>
                                <listitem>
                                        <para>The SELinux security
                                        context (label) of the process
                                        the journal entry originates
                                        from.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <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
                                        microseconds since the epoch UTC,
                                        formatted as a decimal
                                        string.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>_BOOT_ID=</varname></term>
                                <listitem>
                                        <para>The kernel boot ID for
                                        the boot the message was
                                        generated in, formatted as
                                        a 128-bit hexadecimal
                                        string.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>_MACHINE_ID=</varname></term>
                                <listitem>
                                        <para>The machine ID of the
                                        originating host, as available
                                        in
                                        <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>_HOSTNAME=</varname></term>
                                <listitem>
                                        <para>The name of the
                                        originating host.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>_TRANSPORT=</varname></term>
                                <listitem>
                                        <para>How the entry was
                                        received by the journal
                                        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>
        </refsect1>

        <refsect1>
                <title>Kernel Journal Fields</title>

                <para>Kernel fields are fields that are used by
                messages originating in the kernel and stored in the
                journal.</para>

                <variablelist class='journal-directives'>
                        <varlistentry>
                                <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 <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><varname>_KERNEL_SUBSYSTEM=</varname></term>
                                <listitem>
                                        <para>The kernel subsystem name.</para>
                                </listitem>
                        </varlistentry>
                        <varlistentry>
                                <term><varname>_UDEV_SYSNAME=</varname></term>
                                <listitem>
                                        <para>The kernel device name
                                        as it shows up in the device
                                        tree below
                                        <filename>/sys</filename>.</para>
                                </listitem>
                        </varlistentry>
                        <varlistentry>
                                <term><varname>_UDEV_DEVNODE=</varname></term>
                                <listitem>
                                        <para>The device node path of
                                        this device in
                                        <filename>/dev</filename>.</para>
                                </listitem>
                        </varlistentry>
                        <varlistentry>
                                <term><varname>_UDEV_DEVLINK=</varname></term>
                                <listitem>
                                        <para>Additional symlink names
                                        pointing to the device node in
                                        <filename>/dev</filename>. This
                                        field is frequently set more
                                        than once per entry.</para>
                                </listitem>
                        </varlistentry>
                </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>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, 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 class='journal-directives'>
                        <varlistentry>
                                <term><varname>__CURSOR=</varname></term>
                                <listitem>
                                        <para>The cursor for the
                                        entry. A cursor is an opaque
                                        text string that uniquely
                                        describes the position of an
                                        entry in the journal and is
                                        portable across machines,
                                        platforms and journal files.
                                        </para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>__REALTIME_TIMESTAMP=</varname></term>
                                <listitem>
                                        <para>The wallclock time
                                        (<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>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
                                <listitem>
                                        <para>The monotonic time
                                        (<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 the
                                        boot ID in <literal>_BOOT_ID=</literal>.
                                        </para>
                                </listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <refsect1>
                  <title>See Also</title>
                  <para>
                          <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>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                  </para>
        </refsect1>

</refentry>
Commit	Line	Data
ffa16db0 LP	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 2010 Lennart Poettering
	9
	10	systemd is free software; you can redistribute it and/or modify it
5430f7f2 LP	11	under the terms of the GNU Lesser General Public License as published by
5430f7f2 LP	12	the Free Software Foundation; either version 2.1 of the License, or
ffa16db0 LP	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
5430f7f2	18	Lesser General Public License for more details.
ffa16db0	19
5430f7f2	20	You should have received a copy of the GNU Lesser General Public License
ffa16db0 LP	21	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	22	-->
	23
	24	<refentry id="systemd.journal-fields">
	25
	26	<refentryinfo>
	27	<title>systemd.journal-fields</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>systemd.journal-fields</refentrytitle>
	42	<manvolnum>7</manvolnum>
	43	</refmeta>
	44
	45	<refnamediv>
	46	<refname>systemd.journal-fields</refname>
	47	<refpurpose>Special journal fields</refpurpose>
	48	</refnamediv>
	49
	50	<refsect1>
	51	<title>Description</title>
	52
	53	<para>Entries in the journal resemble an environment
8c9552c6	54	block in their syntax but with fields that can
ffa16db0	55	include binary data. Primarily, fields are formatted
a8eedf49 LP	56	UTF-8 text strings, and binary formatting is used only
	57	where formatting as UTF-8 text strings makes little
	58	sense. New fields may freely be defined by
	59	applications, but a few fields have special
	60	meaning. All fields with special meanings are
8c9552c6	61	optional. In some cases, fields may appear more than
bdfb9e7f	62	once per entry.</para>
ffa16db0 LP	63	</refsect1>
	64
	65	<refsect1>
	66	<title>User Journal Fields</title>
	67
	68	<para>User fields are fields that are directly passed
	69	from clients and stored in the journal.</para>
	70
f6c2e28b	71	<variablelist class='journal-directives'>
ffa16db0	72	<varlistentry>
f6c2e28b	73	<term><varname>MESSAGE=</varname></term>
ffa16db0	74	<listitem>
e9dd9f95	75	<para>The human-readable
ffa16db0 LP	76	message string for this
	77	entry. This is supposed to be
	78	the primary text shown to the
33ba4c4b LP	79	user. It is usually not
	80	translated (but might be in
	81	some cases), and is not
	82	supposed to be parsed for meta
	83	data.</para>
ffa16db0 LP	84	</listitem>
	85	</varlistentry>
	86
	87	<varlistentry>
f6c2e28b	88	<term><varname>MESSAGE_ID=</varname></term>
ffa16db0	89	<listitem>
e9dd9f95	90	<para>A 128-bit message
ffa16db0 LP	91	identifier ID for recognizing
	92	certain message types, if this
	93	is desirable. This should
e9dd9f95 JSJ	94	contain a 128-bit ID formatted
e9dd9f95 JSJ	95	as a lower-case hexadecimal
ffa16db0 LP	96	string, without any separating
ffa16db0 LP	97	dashes or suchlike. This is
e9dd9f95 JSJ	98	recommended to be a
e9dd9f95 JSJ	99	UUID-compatible ID, but this is not
ffa16db0 LP	100	enforced, and formatted
	101	differently. Developers can
	102	generate a new ID for this
74d00578 ZJS	103	purpose with <command>journalctl
	104	<option>--new-id</option></command>.
	105	</para>
ffa16db0 LP	106	</listitem>
	107	</varlistentry>
	108
	109	<varlistentry>
f6c2e28b	110	<term><varname>PRIORITY=</varname></term>
ffa16db0 LP	111	<listitem>
	112	<para>A priority value between
	113	0 (<literal>emerg</literal>)
	114	and 7
	115	(<literal>debug</literal>)
e9dd9f95	116	formatted as a decimal
ffa16db0 LP	117	string. This field is
	118	compatible with syslog's
	119	priority concept.</para>
	120	</listitem>
	121	</varlistentry>
	122
	123	<varlistentry>
f6c2e28b ZJS	124	<term><varname>CODE_FILE=</varname></term>
	125	<term><varname>CODE_LINE=</varname></term>
	126	<term><varname>CODE_FUNC=</varname></term>
ffa16db0 LP	127	<listitem>
	128	<para>The code location
	129	generating this message, if
	130	known. Contains the source
e9dd9f95	131	filename, the line number and
ffa16db0 LP	132	the function name.</para>
	133	</listitem>
	134	</varlistentry>
18c7ed18 LP	135
18c7ed18 LP	136	<varlistentry>
f6c2e28b	137	<term><varname>ERRNO=</varname></term>
18c7ed18 LP	138	<listitem>
	139	<para>The low-level Unix error
	140	number causing this entry, if
	141	any. Contains the numeric
	142	value of
	143	<citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
e9dd9f95	144	formatted as a decimal
18c7ed18 LP	145	string.</para>
	146	</listitem>
	147	</varlistentry>
ffa16db0 LP	148
ffa16db0 LP	149	<varlistentry>
f6c2e28b ZJS	150	<term><varname>SYSLOG_FACILITY=</varname></term>
	151	<term><varname>SYSLOG_IDENTIFIER=</varname></term>
	152	<term><varname>SYSLOG_PID=</varname></term>
ffa16db0 LP	153	<listitem>
	154	<para>Syslog compatibility
	155	fields containing the facility
	156	(formatted as decimal string),
	157	the identifier string
	158	(i.e. "tag"), and the client
d2753d22 LP	159	PID. (Note that the tag is
	160	usually derived from glibc's
	161	<varname>program_invocation_short_name</varname>
	162	variable, see <citerefentry><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para>
ffa16db0 LP	163	</listitem>
	164
	165	</varlistentry>
	166	</variablelist>
	167	</refsect1>
	168
	169	<refsect1>
	170	<title>Trusted Journal Fields</title>
	171
	172	<para>Fields prefixed with an underscore are trusted
	173	fields, i.e. fields that are implicitly added by the
	174	journal and cannot be altered by client code.</para>
	175
f6c2e28b	176	<variablelist class='journal-directives'>
ffa16db0	177	<varlistentry>
f6c2e28b ZJS	178	<term><varname>_PID=</varname></term>
	179	<term><varname>_UID=</varname></term>
	180	<term><varname>_GID=</varname></term>
ffa16db0	181	<listitem>
8c9552c6	182	<para>The process, user, and
ffa16db0 LP	183	group ID of the process the
ffa16db0 LP	184	journal entry originates from
e9dd9f95	185	formatted as a decimal
ffa16db0 LP	186	string.</para>
	187	</listitem>
	188	</varlistentry>
	189
	190	<varlistentry>
f6c2e28b ZJS	191	<term><varname>_COMM=</varname></term>
	192	<term><varname>_EXE=</varname></term>
	193	<term><varname>_CMDLINE=</varname></term>
ffa16db0 LP	194	<listitem>
ffa16db0 LP	195	<para>The name, the executable
8c9552c6	196	path, and the command line of
ffa16db0 LP	197	the process the journal entry
	198	originates from.</para>
	199	</listitem>
	200	</varlistentry>
	201
3a832116 SL	202	<varlistentry>
	203	<term><varname>_CAP_EFFECTIVE=</varname></term>
	204	<listitem>
	205	<para>The effective <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of
	206	the process the journal entry
	207	originates from.</para>
	208	</listitem>
	209	</varlistentry>
	210
ffa16db0	211	<varlistentry>
f6c2e28b ZJS	212	<term><varname>_AUDIT_SESSION=</varname></term>
f6c2e28b ZJS	213	<term><varname>_AUDIT_LOGINUID=</varname></term>
ffa16db0 LP	214	<listitem>
	215	<para>The session and login
	216	UID of the process the journal
	217	entry originates from, as
	218	maintained by the kernel audit
	219	subsystem.</para>
	220	</listitem>
	221	</varlistentry>
	222
	223	<varlistentry>
f6c2e28b ZJS	224	<term><varname>_SYSTEMD_CGROUP=</varname></term>
	225	<term><varname>_SYSTEMD_SESSION=</varname></term>
	226	<term><varname>_SYSTEMD_UNIT=</varname></term>
64abe9aa	227	<term><varname>_SYSTEMD_USER_UNIT=</varname></term>
f6c2e28b	228	<term><varname>_SYSTEMD_OWNER_UID=</varname></term>
0a244b8e	229	<term><varname>_SYSTEMD_SLICE=</varname></term>
ffa16db0 LP	230
ffa16db0 LP	231	<listitem>
0a244b8e LP	232	<para>The control group path
0a244b8e LP	233	in the systemd hierarchy, the
ffa16db0	234	systemd session ID (if any),
0a244b8e LP	235	the systemd unit name (if
	236	any), the systemd user session
	237	unit name (if any), the owner
	238	UID of the systemd session (if
	239	any) and the systemd slice
	240	unit of the process the
	241	journal entry originates
	242	from.</para>
ffa16db0 LP	243	</listitem>
	244	</varlistentry>
	245
	246	<varlistentry>
f6c2e28b	247	<term><varname>_SELINUX_CONTEXT=</varname></term>
ffa16db0 LP	248	<listitem>
ffa16db0 LP	249	<para>The SELinux security
82adf6af LP	250	context (label) of the process
82adf6af LP	251	the journal entry originates
ffa16db0 LP	252	from.</para>
	253	</listitem>
	254	</varlistentry>
	255
	256	<varlistentry>
f6c2e28b	257	<term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
ffa16db0 LP	258	<listitem>
	259	<para>The earliest trusted
	260	timestamp of the message, if
	261	any is known that is different
	262	from the reception time of the
41048afa	263	journal. This is the time in
e9dd9f95 JSJ	264	microseconds since the epoch UTC,
e9dd9f95 JSJ	265	formatted as a decimal
41048afa	266	string.</para>
ffa16db0 LP	267	</listitem>
	268	</varlistentry>
	269
	270	<varlistentry>
f6c2e28b	271	<term><varname>_BOOT_ID=</varname></term>
ffa16db0 LP	272	<listitem>
	273	<para>The kernel boot ID for
	274	the boot the message was
	275	generated in, formatted as
e9dd9f95	276	a 128-bit hexadecimal
ffa16db0 LP	277	string.</para>
	278	</listitem>
	279	</varlistentry>
	280
	281	<varlistentry>
f6c2e28b	282	<term><varname>_MACHINE_ID=</varname></term>
ffa16db0 LP	283	<listitem>
	284	<para>The machine ID of the
	285	originating host, as available
	286	in
	287	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
	288	</listitem>
	289	</varlistentry>
	290
	291	<varlistentry>
f6c2e28b	292	<term><varname>_HOSTNAME=</varname></term>
ffa16db0 LP	293	<listitem>
	294	<para>The name of the
	295	originating host.</para>
	296	</listitem>
	297	</varlistentry>
6bc3bf5b LP	298
6bc3bf5b LP	299	<varlistentry>
f6c2e28b	300	<term><varname>_TRANSPORT=</varname></term>
6bc3bf5b LP	301	<listitem>
	302	<para>How the entry was
	303	received by the journal
3ae83f98	304	service. Valid transports are:
6bc3bf5b	305	</para>
3ae83f98 JSJ	306	<variablelist>
	307	<varlistentry>
	308	<term>
	309	<option>driver</option>
	310	</term>
	311	<listitem>
	312	<para>for
	313	internally
	314	generated
	315	messages
	316	</para>
	317	</listitem>
	318	</varlistentry>
	319
	320	<varlistentry>
	321	<term>
	322	<option>syslog</option>
	323	</term>
	324	<listitem>
	325	<para>for those
	326	received via the
	327	local syslog
	328	socket with the
	329	syslog protocol
	330	</para>
	331	</listitem>
	332	</varlistentry>
	333
	334	<varlistentry>
	335	<term>
	336	<option>journal</option>
	337	</term>
	338	<listitem>
	339	<para>for those
	340	received via the
	341	native journal
	342	protocol
	343	</para>
	344	</listitem>
	345	</varlistentry>
	346
	347	<varlistentry>
	348	<term>
	349	<option>stdout</option>
	350	</term>
	351	<listitem>
	352	<para>for those
	353	read from a
	354	service's
	355	standard output
	356	or error output
	357	</para>
	358	</listitem>
	359	</varlistentry>
	360
	361	<varlistentry>
	362	<term>
	363	<option>kernel</option>
	364	</term>
	365	<listitem>
	366	<para>for those
	367	read from the
	368	kernel
	369	</para>
370	</listitem>
371	</varlistentry>
372	</variablelist>
6bc3bf5b LP	373	</listitem>
6bc3bf5b LP	374	</varlistentry>
ffa16db0 LP	375	</variablelist>
	376	</refsect1>
	377
6f7ea7df LP	378	<refsect1>
	379	<title>Kernel Journal Fields</title>
	380
	381	<para>Kernel fields are fields that are used by
	382	messages originating in the kernel and stored in the
	383	journal.</para>
	384
53057ef9	385	<variablelist class='journal-directives'>
6f7ea7df	386	<varlistentry>
53057ef9	387	<term><varname>_KERNEL_DEVICE=</varname></term>
6f7ea7df LP	388	<listitem>
	389	<para>The kernel device
	390	name. If the entry is
	391	associated to a block device,
	392	the major and minor of the
909f413d ZJS	393	device node, separated by <literal>:</literal>
909f413d ZJS	394	and prefixed by <literal>b</literal>. Similar
8c9552c6	395	for character devices but
909f413d	396	prefixed by <literal>c</literal>. For network
8c9552c6	397	devices, this is the interface index
909f413d	398	prefixed by <literal>n</literal>. For all other
8c9552c6 JSJ	399	devices, this is the subsystem name
8c9552c6 JSJ	400	prefixed by <literal>+</literal>, followed by
909f413d	401	<literal>:</literal>, followed by the kernel
6f7ea7df LP	402	device name.</para>
	403	</listitem>
	404	</varlistentry>
	405	<varlistentry>
53057ef9	406	<term><varname>_KERNEL_SUBSYSTEM=</varname></term>
6f7ea7df LP	407	<listitem>
	408	<para>The kernel subsystem name.</para>
	409	</listitem>
	410	</varlistentry>
bdfb9e7f	411	<varlistentry>
53057ef9	412	<term><varname>_UDEV_SYSNAME=</varname></term>
bdfb9e7f LP	413	<listitem>
	414	<para>The kernel device name
	415	as it shows up in the device
	416	tree below
	417	<filename>/sys</filename>.</para>
	418	</listitem>
	419	</varlistentry>
	420	<varlistentry>
53057ef9	421	<term><varname>_UDEV_DEVNODE=</varname></term>
bdfb9e7f LP	422	<listitem>
	423	<para>The device node path of
	424	this device in
	425	<filename>/dev</filename>.</para>
	426	</listitem>
	427	</varlistentry>
	428	<varlistentry>
53057ef9	429	<term><varname>_UDEV_DEVLINK=</varname></term>
bdfb9e7f LP	430	<listitem>
	431	<para>Additional symlink names
	432	pointing to the device node in
	433	<filename>/dev</filename>. This
	434	field is frequently set more
	435	than once per entry.</para>
	436	</listitem>
	437	</varlistentry>
6f7ea7df LP	438	</variablelist>
	439	</refsect1>
	440
53057ef9	441	<refsect1>
5199cbe4 ZJS	442	<title>Fields to log on behalf of a different program</title>
	443
	444	<para>Fields in this section are used by programs
	445	to specify that they are logging on behalf of another
	446	program or unit.
	447	</para>
53057ef9 ZJS	448
53057ef9 ZJS	449	<para>Fields used by the <command>systemd-coredump</command>
5199cbe4	450	coredump kernel helper:
53057ef9 ZJS	451	</para>
	452
	453	<variablelist class='journal-directives'>
	454	<varlistentry>
	455	<term><varname>COREDUMP_UNIT=</varname></term>
	456	<term><varname>COREDUMP_USER_UNIT=</varname></term>
	457	<listitem>
	458	<para>Used to annotate
	459	messages containing coredumps from
	460	system and session units.
	461	See
f4bab169	462	<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
53057ef9 ZJS	463	</para>
	464	</listitem>
	465	</varlistentry>
	466	</variablelist>
5199cbe4 ZJS	467
	468	<para>Priviledged programs (currently UID 0) may
	469	attach <varname>OBJECT_PID=</varname> to a
	470	message. This will instruct
	471	<command>systemd-journald</command> to attach
7b870f60	472	additional fields on behalf of the caller:</para>
5199cbe4 ZJS	473
	474	<variablelist class='journal-directives'>
	475	<varlistentry>
	476	<term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
	477	<listitem>
	478	<para>PID of the program that this
	479	message pertains to.
	480	</para>
	481	</listitem>
	482	</varlistentry>
	483
	484	<varlistentry>
	485	<term><varname>OBJECT_UID=</varname></term>
	486	<term><varname>OBJECT_GID=</varname></term>
	487	<term><varname>OBJECT_COMM=</varname></term>
	488	<term><varname>OBJECT_EXE=</varname></term>
	489	<term><varname>OBJECT_CMDLINE=</varname></term>
	490	<term><varname>OBJECT_AUDIT_SESSION=</varname></term>
	491	<term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
	492	<term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
	493	<term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
	494	<term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
	495	<term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
	496	<term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
	497	<listitem>
7b870f60	498	<para>These are additional fields added automatically
5199cbe4 ZJS	499	by <command>systemd-journald</command>.
	500	Their meaning is the same as
	501	<varname>_UID=</varname>,
	502	<varname>_GID=</varname>,
	503	<varname>_COMM=</varname>,
	504	<varname>_EXE=</varname>,
	505	<varname>_CMDLINE=</varname>,
	506	<varname>_AUDIT_SESSION=</varname>,
	507	<varname>_AUDIT_LOGINUID=</varname>,
	508	<varname>_SYSTEMD_CGROUP=</varname>,
	509	<varname>_SYSTEMD_SESSION=</varname>,
	510	<varname>_SYSTEMD_UNIT=</varname>,
	511	<varname>_SYSTEMD_USER_UNIT=</varname>, and
	512	<varname>_SYSTEMD_OWNER_UID=</varname>
7b870f60 JE	513	as described above, except that the
7b870f60 JE	514	process identified by <replaceable>PID</replaceable>
5199cbe4 ZJS	515	is described, instead of the process
	516	which logged the message.</para>
	517	</listitem>
	518	</varlistentry>
	519	</variablelist>
	520
	521
53057ef9 ZJS	522	</refsect1>
53057ef9 ZJS	523
ffa16db0 LP	524	<refsect1>
	525	<title>Address Fields</title>
	526
df688b23 LP	527	<para>During serialization into external formats, such
	528	as the <ulink
	529	url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
	530	Export Format</ulink> or the <ulink
	531	url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
	532	JSON Format</ulink>, the addresses of journal entries
	533	are serialized into fields prefixed with double
6b4991cf	534	underscores. Note that these are not proper fields when
66f756d4	535	stored in the journal but for addressing metadata of
df688b23 LP	536	entries. They cannot be written as part of structured
df688b23 LP	537	log entries via calls such as
cbdca852 LP	538	<citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
	539	may also not be used as matches for
	540	<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
ffa16db0	541
f6c2e28b	542	<variablelist class='journal-directives'>
ffa16db0	543	<varlistentry>
f6c2e28b	544	<term><varname>__CURSOR=</varname></term>
ffa16db0 LP	545	<listitem>
	546	<para>The cursor for the
	547	entry. A cursor is an opaque
	548	text string that uniquely
	549	describes the position of an
	550	entry in the journal and is
	551	portable across machines,
74d00578 ZJS	552	platforms and journal files.
74d00578 ZJS	553	</para>
ffa16db0 LP	554	</listitem>
	555	</varlistentry>
	556
	557	<varlistentry>
f6c2e28b	558	<term><varname>__REALTIME_TIMESTAMP=</varname></term>
ffa16db0 LP	559	<listitem>
ffa16db0 LP	560	<para>The wallclock time
74d00578 ZJS	561	(<constant>CLOCK_REALTIME</constant>)
	562	at the point in time the entry
	563	was received by the journal,
e9dd9f95 JSJ	564	in microseconds since the epoch
e9dd9f95 JSJ	565	UTC, formatted as a decimal
74d00578 ZJS	566	string. This has different
74d00578 ZJS	567	properties from
e9dd9f95	568	<literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
ffa16db0	569	as it is usually a bit later
74d00578 ZJS	570	but more likely to be monotonic.
74d00578 ZJS	571	</para>
ffa16db0 LP	572	</listitem>
	573	</varlistentry>
	574
	575	<varlistentry>
f6c2e28b	576	<term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
ffa16db0 LP	577	<listitem>
ffa16db0 LP	578	<para>The monotonic time
74d00578 ZJS	579	(<constant>CLOCK_MONOTONIC</constant>)
	580	at the point in time the entry
	581	was received by the journal in
e9dd9f95	582	microseconds, formatted as a decimal
41048afa	583	string. To be useful as an
e9dd9f95 JSJ	584	address for the entry, this
e9dd9f95 JSJ	585	should be combined with with the
74d00578 ZJS	586	boot ID in <literal>_BOOT_ID=</literal>.
74d00578 ZJS	587	</para>
ffa16db0 LP	588	</listitem>
	589	</varlistentry>
	590	</variablelist>
	591	</refsect1>
	592
	593	<refsect1>
	594	<title>See Also</title>
	595	<para>
	596	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	597	<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
a8eedf49	598	<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
9cc2c8b7	599	<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f4bab169	600	<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
9cc2c8b7	601	<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
ffa16db0 LP	602	</para>
	603	</refsect1>
	604
	605	</refentry>