diff options
-rw-r--r-- | Makefile.am | 1 | ||||
-rw-r--r-- | man/journalctl.xml | 5 | ||||
-rw-r--r-- | man/journald.conf.xml | 1 | ||||
-rw-r--r-- | man/systemd.journal-fields.xml | 360 | ||||
-rw-r--r-- | man/systemd.special.xml | 162 | ||||
-rw-r--r-- | src/logs-show.c | 24 | ||||
-rw-r--r-- | src/special.h | 2 |
7 files changed, 469 insertions, 86 deletions
diff --git a/Makefile.am b/Makefile.am index 74e14d2f2a..d83a5a1df3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -692,6 +692,7 @@ MANPAGES = \ man/systemd.snapshot.5 \ man/systemd.exec.5 \ man/systemd.special.7 \ + man/systemd.journal-fields.7 \ man/daemon.7 \ man/runlevel.8 \ man/telinit.8 \ diff --git a/man/journalctl.xml b/man/journalctl.xml index f6e46cfbc7..4728d36e1c 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -68,7 +68,9 @@ <para>If a match argument is passed the output is filtered accordingly. A match is in the format <literal>FIELD=VALUE</literal>, - e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>.</para> + e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>. See + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for a list of well-known fields.</para> <para>Output is interleaved from all accessible journal files, whether they are rotated or currently @@ -253,6 +255,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/journald.conf.xml b/man/journald.conf.xml index a9b0f66de9..eb596eb3ab 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -247,6 +247,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml new file mode 100644 index 0000000000..e638893b63 --- /dev/null +++ b/man/systemd.journal-fields.xml @@ -0,0 +1,360 @@ +<?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 General Public License as published by + the Free Software Foundation; either version 2 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 + General Public License for more details. + + You should have received a copy of the GNU 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 + ASCII strings, and binary formatting is used only + where formatting as ASCII makes little sense. New + fields may be freely defined by applications, but a + few fields have special meaning. All fields with + special meaning are optional.</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> + <varlistentry> + <term>MESSAGE=</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 not translated, + and is not supposed to be + parsed for meta data.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MESSAGE_ID=</term> + <listitem> + <para>A 128bit message + identifier ID for recognizing + certain message types, if this + is desirable. This should + contain a 128bit id formatted + as 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 + --new-id</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>PRIORITY=</term> + <listitem> + <para>A priority value between + 0 (<literal>emerg</literal>) + and 7 + (<literal>debug</literal>) + formatted as decimal + string. This field is + compatible with syslog's + priority concept.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>CODE_FILE=</term> + <term>CODE_LINE=</term> + <term>CODE_FUNC=</term> + <listitem> + <para>The code location + generating this message, if + known. Contains the source + file name, the line number and + the function name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>SYSLOG_FACILITY=</term> + <term>SYSLOG_IDENTIFIER=</term> + <term>SYSLOG_PID=</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> + <varlistentry> + <term>_PID=</term> + <term>_UID=</term> + <term>_GID=</term> + <listitem> + <para>The process, user and + group ID of the process the + journal entry originates from + formatted as decimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>_COMM=</term> + <term>_EXE=</term> + <term>_CMDLINE=</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>_AUDIT_SESSION=</term> + <term>_AUDIT_LOGINUID=</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>_SYSTEMD_CGROUP=</term> + <term>_SYSTEMD_SESSION=</term> + <term>_SYSTEMD_UNIT=</term> + <term>_SYSTEMD_OWNER_UID=</term> + + <listitem> + <para>The contol group path in + the systemd hierarchy, the + systemd session ID (if any), + the systemd unit name (if any) + and the owner UID of the + systemd session (if any) of + the process the journal entry + originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>_SELINUX_CONTEXT=</term> + <listitem> + <para>The SELinux security + context of the process the + journal entry originates + from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>_SOURCE_REALTIME_TIMESTAMP=</term> + <listitem> + <para>The earliest trusted + timestamp of the message, if + any is known that is different + from the reception time of the + journal. This is the time in + usec since the epoch UTC + formatted as decimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>_BOOT_ID=</term> + <listitem> + <para>The kernel boot ID for + the boot the message was + generated in, formatted as + 128bit hexadecimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>_MACHINE_ID=</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>_HOSTNAME=</term> + <listitem> + <para>The name of the + originating host.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>_TRANSPORT=</term> + <listitem> + <para>How the entry was + received by the journal + service. One of + <literal>driver</literal>, + <literal>syslog</literal>, + <literal>journal</literal>, + <literal>stdout</literal>, + <literal>kernel</literal> for + internally generated messages, + for those received via the + local syslog socket with the + syslog protocol, for those + received via the native + journal protocol, for the + those read from a services' + standard output or error + output, resp. for those read + from the kernel. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Address Fields</title> + + <para>During serialization into external formats the + addresses of journal entries are serialized into + fields prefixed with double underscores. Note that + these aren't proper fields when stored in the journal, + but addressing meta data of entries.</para> + + <variablelist> + <varlistentry> + <term>__CURSOR=</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>__REALTIME_TIMESTAMP=</term> + <listitem> + <para>The wallclock time + (CLOCK_REALTIME) at the point + in time the entry was received + by the journal, in usec since + the epoch UTC formatted as + decimal string. This has + different properties from + <literal>_SOURCE_REALTIME_TIMESTAMP=</literal> + as it is usually a bit later + but more likely to be + monotonic.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>__MONOTONIC_TIMESTAMP=</term> + <listitem> + <para>The monotonic time + (CLOCK_MONOTONIC) at the point + in time the entry was received + by the journal in usec + formatted as decimal + string. To be useful as an + address for the entry this + should be combined with with + 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> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 116a43ccfb..fe85137ffe 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -44,20 +44,24 @@ <refnamediv> <refname>systemd.special</refname> - <refpurpose>special systemd units</refpurpose> + <refpurpose>Special systemd units</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>basic.target</filename>, <filename>ctrl-alt-del.target</filename>, <filename>dbus.service</filename>, + <filename>dbus.socket</filename>, <filename>default.target</filename>, <filename>display-manager.service</filename>, <filename>emergency.target</filename>, <filename>exit.service</filename>, + <filename>final.service</filename>, <filename>graphical.target</filename>, + <filename>http-daemon.target</filename>, <filename>halt.target</filename>, <filename>kbrequest.target</filename>, + <filename>kexec.target</filename>, <filename>local-fs.target</filename>, <filename>local-fs-pre.target</filename>, <filename>mail-transfer-agent.target</filename>, @@ -79,11 +83,9 @@ <filename>sockets.target</filename>, <filename>swap.target</filename>, <filename>sysinit.target</filename>, + <filename>syslog.service</filename>, + <filename>syslog.socket</filename>, <filename>syslog.target</filename>, - <filename>systemd-initctl.service</filename>, - <filename>systemd-initctl.socket</filename>, - <filename>systemd-stdout-syslog-bridge.service</filename>, - <filename>systemd-stdout-syslog-bridge.socket</filename>, <filename>time-sync.target</filename>, <filename>umount.target</filename></para> </refsynopsisdiv> @@ -146,6 +148,18 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>dbus.socket</filename></term> + <listitem> + <para>A special unit for the + D-Bus system bus socket. All + units with + <literal>Type=dbus</literal> + automatically gain a + dependency on this + unit.</para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>default.target</filename></term> <listitem> <para>The default unit systemd @@ -168,7 +182,7 @@ <para>The display manager service. Usually this should be aliased (symlinked) to - <filename>xdm.service</filename> + <filename>gdm.service</filename> or a similar display manager service.</para> <para>systemd automatically @@ -197,6 +211,19 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>final.target</filename></term> + <listitem> + <para>A special target unit + that is used during the + shutdown logic and may be used + to pull in late services after + all normal services are + already terminated and all + mounts unmounted. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>graphical.target</filename></term> <listitem> <para>A special target unit @@ -213,6 +240,22 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>http-daemon.target</filename></term> + <listitem> + <para>A target for pulling in + an HTTP server if there is + any.</para> + <para>systemd automatically + adds dependencies of type + After for this target unit to + all SysV init script service + units with a LSB header + referring to the + <literal>$httpd</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>halt.target</filename></term> <listitem> <para>A special target unit @@ -235,6 +278,17 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>kexec.target</filename></term> + <listitem> + <para>A special target unit + for shutting down and rebooting the system via kexec.</para> + + <para>Applications wanting to + reboot the system with kexec should start + this unit.</para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>local-fs.target</filename></term> <listitem> <para>systemd automatically @@ -555,6 +609,28 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>syslog.service</filename></term> + <listitem> + <para>The syslog service if + any. Implementations should + create a symlink from the + actual syslog implementation + to this generic name for + activating it.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>syslog.socket</filename></term> + <listitem> + <para>The socket unit where + syslog implementations should + listen on. All userspace log + messages will be made + available on this + socket.</para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>syslog.target</filename></term> <listitem> <para>systemd automatically @@ -568,74 +644,6 @@ </listitem> </varlistentry> <varlistentry> - <term><filename>systemd-initctl.service</filename></term> - <listitem> - <para>This provides - compatibility with the SysV - /dev/initctl file system FIFO - for communication with the - init system.</para> - <para>This is a - socket-activated service, see - <filename>system-initctl.socket</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>systemd-initctl.socket</filename></term> - <listitem> - <para>Socket activation unit - for - <filename>system-initctl.service</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>systemd-stdout-syslog-bridge.service</filename></term> - <listitem> - <para>This is internally used - by systemd to provide syslog - logging to the processes it - maintains.</para> - <para>This is a - socket-activated service, see - <filename>system-stdout-syslog-bridge.socket</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>systemd-stdout-syslog-bridge.socket</filename></term> - <listitem> - <para>Socket activation unit - for - <filename>system-stdout-syslog-bridge.service</filename>. systemd - will automatically add - dependencies of types Requires - and After to all units that - have been configured for - stdout or stderr to be - connected to syslog or the - kernel log buffer.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>systemd-shutdownd.service</filename></term> - <listitem> - <para>This is internally used - by - <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to implement delayed shutdowns.</para> - <para>This is a - socket-activated service, see - <filename>system-shutdownd.socket</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>systemd-shutdownd.socket</filename></term> - <listitem> - <para>Socket activation unit - for - <filename>system-shutdownd.service</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> <term><filename>time-sync.target</filename></term> <listitem> <para>systemd automatically @@ -676,11 +684,8 @@ following special units are available, which have similar definitions as their system counterparts: <filename>default.target</filename>, - <filename>local-fs.target</filename>, - <filename>remote-fs.target</filename>, <filename>shutdown.target</filename>, - <filename>sockets.target</filename>, - <filename>swap.target</filename>.</para> + <filename>sockets.target</filename></para> <para>In addition the following special unit is understood only when systemd runs as service instance:</para> @@ -715,6 +720,7 @@ <refsect1> <title>See Also</title> <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/src/logs-show.c b/src/logs-show.c index 0a07a77bed..a6220351b6 100644 --- a/src/logs-show.c +++ b/src/logs-show.c @@ -348,9 +348,9 @@ static int output_export(sd_journal *j, unsigned line, unsigned n_columns, bool } printf("__CURSOR=%s\n" - "__REALTIME=%llu\n" - "__MONOTONIC=%llu\n" - "__BOOT_ID=%s\n", + "__REALTIME_TIMESTAMP=%llu\n" + "__MONOTONIC_TIMESTAMP=%llu\n" + "_BOOT_ID=%s\n", cursor, (unsigned long long) realtime, (unsigned long long) monotonic, @@ -360,6 +360,12 @@ static int output_export(sd_journal *j, unsigned line, unsigned n_columns, bool SD_JOURNAL_FOREACH_DATA(j, data, length) { + /* We already printed the boot id, from the data in + * the header, hence let's suppress it here */ + if (length >= 9 && + memcmp(data, "_BOOT_ID=", 9) == 0) + continue; + if (contains_unprintable(data, length)) { const char *c; uint64_t le64; @@ -460,9 +466,9 @@ static int output_json(sd_journal *j, unsigned line, unsigned n_columns, bool sh printf("{\n" "\t\"__CURSOR\" : \"%s\",\n" - "\t\"__REALTIME\" : \"%llu\",\n" - "\t\"__MONOTONIC\" : \"%llu\",\n" - "\t\"__BOOT_ID\" : \"%s\"", + "\t\"__REALTIME_TIMESTAMP\" : \"%llu\",\n" + "\t\"__MONOTONIC_TIMESTAMP\" : \"%llu\",\n" + "\t\"_BOOT_ID\" : \"%s\"", cursor, (unsigned long long) realtime, (unsigned long long) monotonic, @@ -473,6 +479,12 @@ static int output_json(sd_journal *j, unsigned line, unsigned n_columns, bool sh SD_JOURNAL_FOREACH_DATA(j, data, length) { const char *c; + /* We already printed the boot id, from the data in + * the header, hence let's suppress it here */ + if (length >= 9 && + memcmp(data, "_BOOT_ID=", 9) == 0) + continue; + c = memchr(data, '=', length); if (!c) { log_error("Invalid field."); diff --git a/src/special.h b/src/special.h index 8185eaf60e..43e2e6f6d7 100644 --- a/src/special.h +++ b/src/special.h @@ -55,7 +55,7 @@ #define SPECIAL_NETWORK_TARGET "network.target" /* LSB's $network */ #define SPECIAL_NSS_LOOKUP_TARGET "nss-lookup.target" /* LSB's $named */ #define SPECIAL_RPCBIND_TARGET "rpcbind.target" /* LSB's $portmap */ -#define SPECIAL_SYSLOG_TARGET "syslog.target" /* LSB's $syslog; Should pull in syslog.socket or syslog.service */ +#define SPECIAL_SYSLOG_TARGET "syslog.target" /* LSB's $syslog */ #define SPECIAL_TIME_SYNC_TARGET "time-sync.target" /* LSB's $time */ #define SPECIAL_DISPLAY_MANAGER_SERVICE "display-manager.service" /* Debian's $x-display-manager */ #define SPECIAL_MAIL_TRANSFER_AGENT_TARGET "mail-transfer-agent.target" /* Debian's $mail-{transport|transfer-agent */ |