2012-04-04 00:31:48 +04:00
<?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
2012-04-12 02:20:58 +04:00
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
2012-04-04 00:31:48 +04:00
(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
2012-04-12 02:20:58 +04:00
Lesser General Public License for more details.
2012-04-04 00:31:48 +04:00
2012-04-12 02:20:58 +04:00
You should have received a copy of the GNU Lesser General Public License
2012-04-04 00:31:48 +04:00
along with systemd; If not, see <http: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<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
2012-07-09 17:46:21 +04:00
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
2012-08-22 04:49:17 +04:00
optional. In some cases fields may appear more than
once per entry.</para>
2012-04-04 00:31:48 +04:00
</refsect1>
<refsect1 >
<title > User Journal Fields</title>
<para > User fields are fields that are directly passed
from clients and stored in the journal.</para>
2012-08-10 21:35:43 +04:00
<variablelist class= 'journal-directives' >
2012-04-04 00:31:48 +04:00
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > MESSAGE=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
2013-06-27 23:51:44 +04:00
<para > The human-readable
2012-04-04 00:31:48 +04:00
message string for this
entry. This is supposed to be
the primary text shown to the
2012-05-22 03:12:46 +04:00
user. It is usually not
translated (but might be in
some cases), and is not
supposed to be parsed for meta
data.</para>
2012-04-04 00:31:48 +04:00
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > MESSAGE_ID=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
2013-06-27 23:51:44 +04:00
<para > A 128-bit message
2012-04-04 00:31:48 +04:00
identifier ID for recognizing
certain message types, if this
is desirable. This should
2013-06-27 23:51:44 +04:00
contain a 128-bit ID formatted
as a lower-case hexadecimal
2012-04-04 00:31:48 +04:00
string, without any separating
dashes or suchlike. This is
2013-06-27 23:51:44 +04:00
recommended to be a
UUID-compatible ID, but this is not
2012-04-04 00:31:48 +04:00
enforced, and formatted
differently. Developers can
generate a new ID for this
2013-06-27 03:47:34 +04:00
purpose with <command > journalctl
<option > --new-id</option> </command> .
</para>
2012-04-04 00:31:48 +04:00
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > PRIORITY=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > A priority value between
0 (<literal > emerg</literal> )
and 7
(<literal > debug</literal> )
2013-06-27 23:51:44 +04:00
formatted as a decimal
2012-04-04 00:31:48 +04:00
string. This field is
compatible with syslog's
priority concept.</para>
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > CODE_FILE=</varname> </term>
<term > <varname > CODE_LINE=</varname> </term>
<term > <varname > CODE_FUNC=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The code location
generating this message, if
known. Contains the source
2013-06-27 23:51:44 +04:00
filename, the line number and
2012-04-04 00:31:48 +04:00
the function name.</para>
</listitem>
</varlistentry>
2012-07-31 18:09:01 +04:00
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > ERRNO=</varname> </term>
2012-07-31 18:09:01 +04:00
<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>
2013-06-27 23:51:44 +04:00
formatted as a decimal
2012-07-31 18:09:01 +04:00
string.</para>
</listitem>
</varlistentry>
2012-04-04 00:31:48 +04:00
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > SYSLOG_FACILITY=</varname> </term>
<term > <varname > SYSLOG_IDENTIFIER=</varname> </term>
<term > <varname > SYSLOG_PID=</varname> </term>
2012-04-04 00:31:48 +04:00
<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>
2012-08-10 21:35:43 +04:00
<variablelist class= 'journal-directives' >
2012-04-04 00:31:48 +04:00
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _PID=</varname> </term>
<term > <varname > _UID=</varname> </term>
<term > <varname > _GID=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The process, user and
group ID of the process the
journal entry originates from
2013-06-27 23:51:44 +04:00
formatted as a decimal
2012-04-04 00:31:48 +04:00
string.</para>
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _COMM=</varname> </term>
<term > <varname > _EXE=</varname> </term>
<term > <varname > _CMDLINE=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The name, the executable
path and the command line of
the process the journal entry
originates from.</para>
</listitem>
</varlistentry>
2013-07-16 05:10:56 +04:00
<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>
2012-04-04 00:31:48 +04:00
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _AUDIT_SESSION=</varname> </term>
<term > <varname > _AUDIT_LOGINUID=</varname> </term>
2012-04-04 00:31:48 +04:00
<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 >
2012-08-10 21:35:43 +04:00
<term > <varname > _SYSTEMD_CGROUP=</varname> </term>
<term > <varname > _SYSTEMD_SESSION=</varname> </term>
<term > <varname > _SYSTEMD_UNIT=</varname> </term>
2013-01-17 21:55:09 +04:00
<term > <varname > _SYSTEMD_USER_UNIT=</varname> </term>
2012-08-10 21:35:43 +04:00
<term > <varname > _SYSTEMD_OWNER_UID=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
2012-10-26 02:16:47 +04:00
<para > The control group path in
2012-04-04 00:31:48 +04:00
the systemd hierarchy, the
systemd session ID (if any),
2013-01-17 21:55:09 +04:00
the systemd unit name (if any),
the systemd user session unit name (if any)
2012-04-04 00:31:48 +04:00
and the owner UID of the
systemd session (if any) of
the process the journal entry
originates from.</para>
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _SELINUX_CONTEXT=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The SELinux security
context of the process the
journal entry originates
from.</para>
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _SOURCE_REALTIME_TIMESTAMP=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The earliest trusted
timestamp of the message, if
any is known that is different
from the reception time of the
2012-04-04 01:08:04 +04:00
journal. This is the time in
2013-06-27 23:51:44 +04:00
microseconds since the epoch UTC,
formatted as a decimal
2012-04-04 01:08:04 +04:00
string.</para>
2012-04-04 00:31:48 +04:00
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _BOOT_ID=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The kernel boot ID for
the boot the message was
generated in, formatted as
2013-06-27 23:51:44 +04:00
a 128-bit hexadecimal
2012-04-04 00:31:48 +04:00
string.</para>
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _MACHINE_ID=</varname> </term>
2012-04-04 00:31:48 +04:00
<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 >
2012-08-10 21:35:43 +04:00
<term > <varname > _HOSTNAME=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The name of the
originating host.</para>
</listitem>
</varlistentry>
2012-04-04 02:43:40 +04:00
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > _TRANSPORT=</varname> </term>
2012-04-04 02:43:40 +04:00
<listitem >
<para > How the entry was
received by the journal
2013-06-12 21:45:14 +04:00
service. Valid transports are:
2012-04-04 02:43:40 +04:00
</para>
2013-06-12 21:45:14 +04:00
<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>
2012-04-04 02:43:40 +04:00
</listitem>
</varlistentry>
2012-04-04 00:31:48 +04:00
</variablelist>
</refsect1>
2012-08-09 19:12:07 +04:00
<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>
2013-02-07 09:50:37 +04:00
<variablelist class= 'journal-directives' >
2012-08-09 19:12:07 +04:00
<varlistentry >
2013-02-07 09:50:37 +04:00
<term > <varname > _KERNEL_DEVICE=</varname> </term>
2012-08-09 19:12:07 +04:00
<listitem >
<para > The kernel device
name. If the entry is
associated to a block device,
the major and minor of the
2013-06-26 16:03:53 +04:00
device node, separated by <literal > :</literal>
and prefixed by <literal > b</literal> . Similar
2012-08-09 19:12:07 +04:00
for character devices, but
2013-06-26 16:03:53 +04:00
prefixed by <literal > c</literal> . For network
2012-08-09 19:12:07 +04:00
devices the interface index,
2013-06-26 16:03:53 +04:00
prefixed by <literal > n</literal> . For all other
devices <literal > +</literal> followed by the
2012-08-09 19:12:07 +04:00
subsystem name, followed by
2013-06-26 16:03:53 +04:00
<literal > :</literal> , followed by the kernel
2012-08-09 19:12:07 +04:00
device name.</para>
</listitem>
</varlistentry>
<varlistentry >
2013-02-07 09:50:37 +04:00
<term > <varname > _KERNEL_SUBSYSTEM=</varname> </term>
2012-08-09 19:12:07 +04:00
<listitem >
<para > The kernel subsystem name.</para>
</listitem>
</varlistentry>
2012-08-22 04:49:17 +04:00
<varlistentry >
2013-02-07 09:50:37 +04:00
<term > <varname > _UDEV_SYSNAME=</varname> </term>
2012-08-22 04:49:17 +04:00
<listitem >
<para > The kernel device name
as it shows up in the device
tree below
<filename > /sys</filename> .</para>
</listitem>
</varlistentry>
<varlistentry >
2013-02-07 09:50:37 +04:00
<term > <varname > _UDEV_DEVNODE=</varname> </term>
2012-08-22 04:49:17 +04:00
<listitem >
<para > The device node path of
this device in
<filename > /dev</filename> .</para>
</listitem>
</varlistentry>
<varlistentry >
2013-02-07 09:50:37 +04:00
<term > <varname > _UDEV_DEVLINK=</varname> </term>
2012-08-22 04:49:17 +04:00
<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>
2012-08-09 19:12:07 +04:00
</variablelist>
</refsect1>
2013-02-07 09:50:37 +04:00
<refsect1 >
2013-07-03 07:35:20 +04:00
<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>
2013-02-07 09:50:37 +04:00
<para > Fields used by the <command > systemd-coredump</command>
2013-07-03 07:35:20 +04:00
coredump kernel helper:
2013-02-07 09:50:37 +04:00
</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>
2013-07-03 07:35:20 +04:00
<para > Priviledged programs (currently UID 0) may
attach <varname > OBJECT_PID=</varname> to a
message. This will instruct
<command > systemd-journald</command> to attach
2013-07-08 20:19:02 +04:00
additional fields on behalf of the caller:</para>
2013-07-03 07:35:20 +04:00
<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 >
2013-07-08 20:19:02 +04:00
<para > These are additional fields added automatically
2013-07-03 07:35:20 +04:00
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>
2013-07-08 20:19:02 +04:00
as described above, except that the
process identified by <replaceable > PID</replaceable>
2013-07-03 07:35:20 +04:00
is described, instead of the process
which logged the message.</para>
</listitem>
</varlistentry>
</variablelist>
2013-02-07 09:50:37 +04:00
</refsect1>
2012-04-04 00:31:48 +04:00
<refsect1 >
<title > Address Fields</title>
2012-10-26 03:07:07 +04:00
<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
2013-06-27 23:51:44 +04:00
stored in the journal but for addressing meta data of
2012-10-26 03:07:07 +04:00
entries. They cannot be written as part of structured
log entries via calls such as
2012-07-13 02:29:26 +04:00
<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>
2012-04-04 00:31:48 +04:00
2012-08-10 21:35:43 +04:00
<variablelist class= 'journal-directives' >
2012-04-04 00:31:48 +04:00
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > __CURSOR=</varname> </term>
2012-04-04 00:31:48 +04:00
<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,
2013-06-27 03:47:34 +04:00
platforms and journal files.
</para>
2012-04-04 00:31:48 +04:00
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > __REALTIME_TIMESTAMP=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The wallclock time
2013-06-27 03:47:34 +04:00
(<constant > CLOCK_REALTIME</constant> )
at the point in time the entry
was received by the journal,
2013-06-27 23:51:44 +04:00
in microseconds since the epoch
UTC, formatted as a decimal
2013-06-27 03:47:34 +04:00
string. This has different
properties from
2013-06-27 23:51:44 +04:00
<literal > _SOURCE_REALTIME_TIMESTAMP=</literal> ,
2012-04-04 00:31:48 +04:00
as it is usually a bit later
2013-06-27 03:47:34 +04:00
but more likely to be monotonic.
</para>
2012-04-04 00:31:48 +04:00
</listitem>
</varlistentry>
<varlistentry >
2012-08-10 21:35:43 +04:00
<term > <varname > __MONOTONIC_TIMESTAMP=</varname> </term>
2012-04-04 00:31:48 +04:00
<listitem >
<para > The monotonic time
2013-06-27 03:47:34 +04:00
(<constant > CLOCK_MONOTONIC</constant> )
at the point in time the entry
was received by the journal in
2013-06-27 23:51:44 +04:00
microseconds, formatted as a decimal
2012-04-04 01:08:04 +04:00
string. To be useful as an
2013-06-27 23:51:44 +04:00
address for the entry, this
should be combined with with the
2013-06-27 03:47:34 +04:00
boot ID in <literal > _BOOT_ID=</literal> .
</para>
2012-04-04 00:31:48 +04:00
</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> ,
2012-07-09 17:46:21 +04:00
<citerefentry > <refentrytitle > journald.conf</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
2013-01-15 07:08:33 +04:00
<citerefentry > <refentrytitle > sd-journal</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2013-02-07 09:50:37 +04:00
<citerefentry > <refentrytitle > systemd-coredumpctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2013-01-15 07:08:33 +04:00
<citerefentry > <refentrytitle > systemd.directives</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry>
2012-04-04 00:31:48 +04:00
</para>
</refsect1>
</refentry>
