[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, however 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.</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>_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>

                                <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)
                                        and the owner UID of the
                                        systemd session (if any) of
                                        the process the journal entry
                                        originates from.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>_SELINUX_CONTEXT=</varname></term>
                                <listitem>
                                        <para>The SELinux security
                                        context 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 the interface index,
                                        prefixed by <literal>n</literal>. For all other
                                        devices <literal>+</literal> followed by the
                                        subsystem name, 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>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 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>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>
                                        described above, except that
                                        process <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 aren't proper fields when
                stored in the journal but for addressing meta data 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>systemd-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
	54	block in their syntax, however with fields that can
	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
bdfb9e7f LP	61	optional. In some cases fields may appear more than
bdfb9e7f LP	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
	159	PID.</para>
	160	</listitem>
	161
	162	</varlistentry>
	163	</variablelist>
	164	</refsect1>
	165
	166	<refsect1>
	167	<title>Trusted Journal Fields</title>
	168
	169	<para>Fields prefixed with an underscore are trusted
	170	fields, i.e. fields that are implicitly added by the
	171	journal and cannot be altered by client code.</para>
	172
f6c2e28b	173	<variablelist class='journal-directives'>
ffa16db0	174	<varlistentry>
f6c2e28b ZJS	175	<term><varname>_PID=</varname></term>
	176	<term><varname>_UID=</varname></term>
	177	<term><varname>_GID=</varname></term>
ffa16db0 LP	178	<listitem>
	179	<para>The process, user and
	180	group ID of the process the
	181	journal entry originates from
e9dd9f95	182	formatted as a decimal
ffa16db0 LP	183	string.</para>
	184	</listitem>
	185	</varlistentry>
	186
	187	<varlistentry>
f6c2e28b ZJS	188	<term><varname>_COMM=</varname></term>
	189	<term><varname>_EXE=</varname></term>
	190	<term><varname>_CMDLINE=</varname></term>
ffa16db0 LP	191	<listitem>
	192	<para>The name, the executable
	193	path and the command line of
	194	the process the journal entry
	195	originates from.</para>
	196	</listitem>
	197	</varlistentry>
	198
	199	<varlistentry>
f6c2e28b ZJS	200	<term><varname>_AUDIT_SESSION=</varname></term>
f6c2e28b ZJS	201	<term><varname>_AUDIT_LOGINUID=</varname></term>
ffa16db0 LP	202	<listitem>
	203	<para>The session and login
	204	UID of the process the journal
	205	entry originates from, as
	206	maintained by the kernel audit
	207	subsystem.</para>
	208	</listitem>
	209	</varlistentry>
	210
	211	<varlistentry>
f6c2e28b ZJS	212	<term><varname>_SYSTEMD_CGROUP=</varname></term>
	213	<term><varname>_SYSTEMD_SESSION=</varname></term>
	214	<term><varname>_SYSTEMD_UNIT=</varname></term>
64abe9aa	215	<term><varname>_SYSTEMD_USER_UNIT=</varname></term>
f6c2e28b	216	<term><varname>_SYSTEMD_OWNER_UID=</varname></term>
ffa16db0 LP	217
ffa16db0 LP	218	<listitem>
bb31a4ac	219	<para>The control group path in
ffa16db0 LP	220	the systemd hierarchy, the
ffa16db0 LP	221	systemd session ID (if any),
64abe9aa MT	222	the systemd unit name (if any),
64abe9aa MT	223	the systemd user session unit name (if any)
ffa16db0 LP	224	and the owner UID of the
	225	systemd session (if any) of
	226	the process the journal entry
	227	originates from.</para>
	228	</listitem>
	229	</varlistentry>
	230
	231	<varlistentry>
f6c2e28b	232	<term><varname>_SELINUX_CONTEXT=</varname></term>
ffa16db0 LP	233	<listitem>
	234	<para>The SELinux security
	235	context of the process the
	236	journal entry originates
	237	from.</para>
	238	</listitem>
	239	</varlistentry>
	240
	241	<varlistentry>
f6c2e28b	242	<term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
ffa16db0 LP	243	<listitem>
	244	<para>The earliest trusted
	245	timestamp of the message, if
	246	any is known that is different
	247	from the reception time of the
41048afa	248	journal. This is the time in
e9dd9f95 JSJ	249	microseconds since the epoch UTC,
e9dd9f95 JSJ	250	formatted as a decimal
41048afa	251	string.</para>
ffa16db0 LP	252	</listitem>
	253	</varlistentry>
	254
	255	<varlistentry>
f6c2e28b	256	<term><varname>_BOOT_ID=</varname></term>
ffa16db0 LP	257	<listitem>
	258	<para>The kernel boot ID for
	259	the boot the message was
	260	generated in, formatted as
e9dd9f95	261	a 128-bit hexadecimal
ffa16db0 LP	262	string.</para>
	263	</listitem>
	264	</varlistentry>
	265
	266	<varlistentry>
f6c2e28b	267	<term><varname>_MACHINE_ID=</varname></term>
ffa16db0 LP	268	<listitem>
	269	<para>The machine ID of the
	270	originating host, as available
	271	in
	272	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
	273	</listitem>
	274	</varlistentry>
	275
	276	<varlistentry>
f6c2e28b	277	<term><varname>_HOSTNAME=</varname></term>
ffa16db0 LP	278	<listitem>
	279	<para>The name of the
	280	originating host.</para>
	281	</listitem>
	282	</varlistentry>
6bc3bf5b LP	283
6bc3bf5b LP	284	<varlistentry>
f6c2e28b	285	<term><varname>_TRANSPORT=</varname></term>
6bc3bf5b LP	286	<listitem>
	287	<para>How the entry was
	288	received by the journal
3ae83f98	289	service. Valid transports are:
6bc3bf5b	290	</para>
3ae83f98 JSJ	291	<variablelist>
	292	<varlistentry>
	293	<term>
	294	<option>driver</option>
	295	</term>
	296	<listitem>
	297	<para>for
	298	internally
	299	generated
	300	messages
	301	</para>
	302	</listitem>
	303	</varlistentry>
	304
	305	<varlistentry>
	306	<term>
	307	<option>syslog</option>
	308	</term>
	309	<listitem>
	310	<para>for those
	311	received via the
	312	local syslog
	313	socket with the
	314	syslog protocol
	315	</para>
	316	</listitem>
	317	</varlistentry>
	318
	319	<varlistentry>
	320	<term>
	321	<option>journal</option>
	322	</term>
	323	<listitem>
	324	<para>for those
	325	received via the
	326	native journal
	327	protocol
	328	</para>
	329	</listitem>
	330	</varlistentry>
	331
	332	<varlistentry>
	333	<term>
	334	<option>stdout</option>
	335	</term>
	336	<listitem>
	337	<para>for those
	338	read from a
	339	service's
	340	standard output
	341	or error output
	342	</para>
	343	</listitem>
	344	</varlistentry>
	345
	346	<varlistentry>
	347	<term>
	348	<option>kernel</option>
	349	</term>
	350	<listitem>
	351	<para>for those
	352	read from the
	353	kernel
	354	</para>
355	</listitem>
356	</varlistentry>
357	</variablelist>
6bc3bf5b LP	358	</listitem>
6bc3bf5b LP	359	</varlistentry>
ffa16db0 LP	360	</variablelist>
	361	</refsect1>
	362
6f7ea7df LP	363	<refsect1>
	364	<title>Kernel Journal Fields</title>
	365
	366	<para>Kernel fields are fields that are used by
	367	messages originating in the kernel and stored in the
	368	journal.</para>
	369
53057ef9	370	<variablelist class='journal-directives'>
6f7ea7df	371	<varlistentry>
53057ef9	372	<term><varname>_KERNEL_DEVICE=</varname></term>
6f7ea7df LP	373	<listitem>
	374	<para>The kernel device
	375	name. If the entry is
	376	associated to a block device,
	377	the major and minor of the
909f413d ZJS	378	device node, separated by <literal>:</literal>
909f413d ZJS	379	and prefixed by <literal>b</literal>. Similar
6f7ea7df	380	for character devices, but
909f413d	381	prefixed by <literal>c</literal>. For network
6f7ea7df	382	devices the interface index,
909f413d ZJS	383	prefixed by <literal>n</literal>. For all other
909f413d ZJS	384	devices <literal>+</literal> followed by the
6f7ea7df	385	subsystem name, followed by
909f413d	386	<literal>:</literal>, followed by the kernel
6f7ea7df LP	387	device name.</para>
	388	</listitem>
	389	</varlistentry>
	390	<varlistentry>
53057ef9	391	<term><varname>_KERNEL_SUBSYSTEM=</varname></term>
6f7ea7df LP	392	<listitem>
	393	<para>The kernel subsystem name.</para>
	394	</listitem>
	395	</varlistentry>
bdfb9e7f	396	<varlistentry>
53057ef9	397	<term><varname>_UDEV_SYSNAME=</varname></term>
bdfb9e7f LP	398	<listitem>
	399	<para>The kernel device name
	400	as it shows up in the device
	401	tree below
	402	<filename>/sys</filename>.</para>
	403	</listitem>
	404	</varlistentry>
	405	<varlistentry>
53057ef9	406	<term><varname>_UDEV_DEVNODE=</varname></term>
bdfb9e7f LP	407	<listitem>
	408	<para>The device node path of
	409	this device in
	410	<filename>/dev</filename>.</para>
	411	</listitem>
	412	</varlistentry>
	413	<varlistentry>
53057ef9	414	<term><varname>_UDEV_DEVLINK=</varname></term>
bdfb9e7f LP	415	<listitem>
	416	<para>Additional symlink names
	417	pointing to the device node in
	418	<filename>/dev</filename>. This
	419	field is frequently set more
	420	than once per entry.</para>
	421	</listitem>
	422	</varlistentry>
6f7ea7df LP	423	</variablelist>
	424	</refsect1>
	425
53057ef9	426	<refsect1>
5199cbe4 ZJS	427	<title>Fields to log on behalf of a different program</title>
	428
	429	<para>Fields in this section are used by programs
	430	to specify that they are logging on behalf of another
	431	program or unit.
	432	</para>
53057ef9 ZJS	433
53057ef9 ZJS	434	<para>Fields used by the <command>systemd-coredump</command>
5199cbe4	435	coredump kernel helper:
53057ef9 ZJS	436	</para>
	437
	438	<variablelist class='journal-directives'>
	439	<varlistentry>
	440	<term><varname>COREDUMP_UNIT=</varname></term>
	441	<term><varname>COREDUMP_USER_UNIT=</varname></term>
	442	<listitem>
	443	<para>Used to annotate
	444	messages containing coredumps from
	445	system and session units.
	446	See
	447	<citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
	448	</para>
	449	</listitem>
	450	</varlistentry>
	451	</variablelist>
5199cbe4 ZJS	452
	453	<para>Priviledged programs (currently UID 0) may
	454	attach <varname>OBJECT_PID=</varname> to a
	455	message. This will instruct
	456	<command>systemd-journald</command> to attach
	457	additional fields on behalf of caller:</para>
	458
	459	<variablelist class='journal-directives'>
	460	<varlistentry>
	461	<term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
	462	<listitem>
	463	<para>PID of the program that this
	464	message pertains to.
	465	</para>
	466	</listitem>
	467	</varlistentry>
	468
	469	<varlistentry>
	470	<term><varname>OBJECT_UID=</varname></term>
	471	<term><varname>OBJECT_GID=</varname></term>
	472	<term><varname>OBJECT_COMM=</varname></term>
	473	<term><varname>OBJECT_EXE=</varname></term>
	474	<term><varname>OBJECT_CMDLINE=</varname></term>
	475	<term><varname>OBJECT_AUDIT_SESSION=</varname></term>
	476	<term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
	477	<term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
	478	<term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
	479	<term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
	480	<term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
	481	<term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
	482	<listitem>
	483	<para>Additional fields added automatically
	484	by <command>systemd-journald</command>.
	485	Their meaning is the same as
	486	<varname>_UID=</varname>,
	487	<varname>_GID=</varname>,
	488	<varname>_COMM=</varname>,
	489	<varname>_EXE=</varname>,
	490	<varname>_CMDLINE=</varname>,
	491	<varname>_AUDIT_SESSION=</varname>,
	492	<varname>_AUDIT_LOGINUID=</varname>,
	493	<varname>_SYSTEMD_CGROUP=</varname>,
	494	<varname>_SYSTEMD_SESSION=</varname>,
	495	<varname>_SYSTEMD_UNIT=</varname>,
	496	<varname>_SYSTEMD_USER_UNIT=</varname>, and
	497	<varname>_SYSTEMD_OWNER_UID=</varname>
	498	described above, except that
	499	process <replaceable>PID</replaceable>
	500	is described, instead of the process
	501	which logged the message.</para>
	502	</listitem>
	503	</varlistentry>
	504	</variablelist>
	505
	506
53057ef9 ZJS	507	</refsect1>
53057ef9 ZJS	508
ffa16db0 LP	509	<refsect1>
	510	<title>Address Fields</title>
	511
df688b23 LP	512	<para>During serialization into external formats, such
	513	as the <ulink
	514	url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
	515	Export Format</ulink> or the <ulink
	516	url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
	517	JSON Format</ulink>, the addresses of journal entries
	518	are serialized into fields prefixed with double
	519	underscores. Note that these aren't proper fields when
e9dd9f95	520	stored in the journal but for addressing meta data of
df688b23 LP	521	entries. They cannot be written as part of structured
df688b23 LP	522	log entries via calls such as
cbdca852 LP	523	<citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
	524	may also not be used as matches for
	525	<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
ffa16db0	526
f6c2e28b	527	<variablelist class='journal-directives'>
ffa16db0	528	<varlistentry>
f6c2e28b	529	<term><varname>__CURSOR=</varname></term>
ffa16db0 LP	530	<listitem>
	531	<para>The cursor for the
	532	entry. A cursor is an opaque
	533	text string that uniquely
	534	describes the position of an
	535	entry in the journal and is
	536	portable across machines,
74d00578 ZJS	537	platforms and journal files.
74d00578 ZJS	538	</para>
ffa16db0 LP	539	</listitem>
	540	</varlistentry>
	541
	542	<varlistentry>
f6c2e28b	543	<term><varname>__REALTIME_TIMESTAMP=</varname></term>
ffa16db0 LP	544	<listitem>
ffa16db0 LP	545	<para>The wallclock time
74d00578 ZJS	546	(<constant>CLOCK_REALTIME</constant>)
	547	at the point in time the entry
	548	was received by the journal,
e9dd9f95 JSJ	549	in microseconds since the epoch
e9dd9f95 JSJ	550	UTC, formatted as a decimal
74d00578 ZJS	551	string. This has different
74d00578 ZJS	552	properties from
e9dd9f95	553	<literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
ffa16db0	554	as it is usually a bit later
74d00578 ZJS	555	but more likely to be monotonic.
74d00578 ZJS	556	</para>
ffa16db0 LP	557	</listitem>
	558	</varlistentry>
	559
	560	<varlistentry>
f6c2e28b	561	<term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
ffa16db0 LP	562	<listitem>
ffa16db0 LP	563	<para>The monotonic time
74d00578 ZJS	564	(<constant>CLOCK_MONOTONIC</constant>)
	565	at the point in time the entry
	566	was received by the journal in
e9dd9f95	567	microseconds, formatted as a decimal
41048afa	568	string. To be useful as an
e9dd9f95 JSJ	569	address for the entry, this
e9dd9f95 JSJ	570	should be combined with with the
74d00578 ZJS	571	boot ID in <literal>_BOOT_ID=</literal>.
74d00578 ZJS	572	</para>
ffa16db0 LP	573	</listitem>
	574	</varlistentry>
	575	</variablelist>
	576	</refsect1>
	577
	578	<refsect1>
	579	<title>See Also</title>
	580	<para>
	581	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	582	<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
a8eedf49	583	<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
9cc2c8b7	584	<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
53057ef9	585	<citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
9cc2c8b7	586	<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
ffa16db0 LP	587	</para>
	588	</refsect1>
	589
	590	</refentry>