From ffa16db02673ffa155ffb2649e72a935a1ff70f5 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 3 Apr 2012 22:31:48 +0200 Subject: man: document special journal fields --- man/journalctl.xml | 5 +- man/journald.conf.xml | 1 + man/systemd.journal-fields.xml | 330 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 335 insertions(+), 1 deletion(-) create mode 100644 man/systemd.journal-fields.xml (limited to 'man') 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 @@ If a match argument is passed the output is filtered accordingly. A match is in the format FIELD=VALUE, - e.g. _SYSTEMD_UNIT=httpd.service. + e.g. _SYSTEMD_UNIT=httpd.service. See + systemd.journal-fields7 + for a list of well-known fields. Output is interleaved from all accessible journal files, whether they are rotated or currently @@ -253,6 +255,7 @@ systemd1, systemctl1, + systemd.journal-fields7, journald.conf5 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 @@ systemd1, journalctl1, + systemd.journal-fields7, systemd.conf5 diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml new file mode 100644 index 0000000000..5f2a32cb00 --- /dev/null +++ b/man/systemd.journal-fields.xml @@ -0,0 +1,330 @@ + + + + + + + + + systemd.journal-fields + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.journal-fields + 7 + + + + systemd.journal-fields + Special journal fields + + + + Description + + 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. + + + + User Journal Fields + + User fields are fields that are directly passed + from clients and stored in the journal. + + + + MESSAGE= + + 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. + + + + + MESSAGE_ID= + + 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 + journalctl + --new-id. + + + + + PRIORITY= + + A priority value between + 0 (emerg) + and 7 + (debug) + formatted as decimal + string. This field is + compatible with syslog's + priority concept. + + + + + CODE_FILE= + CODE_LINE= + CODE_FUNC= + + The code location + generating this message, if + known. Contains the source + file name, the line number and + the function name. + + + + + SYSLOG_FACILITY= + SYSLOG_IDENTIFIER= + SYSLOG_PID= + + Syslog compatibility + fields containing the facility + (formatted as decimal string), + the identifier string + (i.e. "tag"), and the client + PID. + + + + + + + + Trusted Journal Fields + + 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. + + + + _PID= + _UID= + _GID= + + The process, user and + group ID of the process the + journal entry originates from + formatted as decimal + string. + + + + + _COMM= + _EXE= + _CMDLINE= + + The name, the executable + path and the command line of + the process the journal entry + originates from. + + + + + _AUDIT_SESSION= + _AUDIT_LOGINUID= + + The session and login + UID of the process the journal + entry originates from, as + maintained by the kernel audit + subsystem. + + + + + _SYSTEMD_CGROUP= + _SYSTEMD_SESSION= + _SYSTEMD_UNIT= + _SYSTEMD_OWNER_UID= + + + 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. + + + + + _SELINUX_CONTEXT= + + The SELinux security + context of the process the + journal entry originates + from. + + + + + _SOURCE_REALTIME_TIMESTAMP= + + The earliest trusted + timestamp of the message, if + any is known that is different + from the reception time of the + journal. The time in usec + since the epoch formatted as + decimal string. + + + + + _BOOT_ID= + + The kernel boot ID for + the boot the message was + generated in, formatted as + 128bit hexadecimal + string. + + + + + _MACHINE_ID= + + The machine ID of the + originating host, as available + in + machine-id5. + + + + + _HOSTNAME= + + The name of the + originating host. + + + + + + + Address Fields + + 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. + + + + __CURSOR= + + 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. + + + + + __REALTIME_TIMESTAMP= + + The wallclock time + (CLOCK_REALTIME) at the point + in time the entry was received + by the journal. This has + different properties from + _SOURCE_REALTIME_TIMESTAMP= + as it is usually a bit later + but more likely to be + monotonic. + + + + + __MONOTONIC_TIMESTAMP= + + The monotonic time + (CLOCK_MONOTONIC) at the point + in time the entry was received + by the journal. To be useful + as an address for the entry + this should be combined with + with boot ID in + _BOOT_ID=. + + + + + + + See Also + + systemd1, + journalctl1, + journald.conf5 + + + + -- cgit v1.2.3-54-g00ecf From feb88c9ff52b52a1fc0f075cba1215e4c2a82545 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 3 Apr 2012 22:32:05 +0200 Subject: man: update documentation of special units --- man/systemd.special.xml | 162 +++++++++++++++++++++++++----------------------- src/special.h | 2 +- 2 files changed, 85 insertions(+), 79 deletions(-) (limited to 'man') 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 @@ systemd.special - special systemd units + Special systemd units basic.target, ctrl-alt-del.target, dbus.service, + dbus.socket, default.target, display-manager.service, emergency.target, exit.service, + final.service, graphical.target, + http-daemon.target, halt.target, kbrequest.target, + kexec.target, local-fs.target, local-fs-pre.target, mail-transfer-agent.target, @@ -79,11 +83,9 @@ sockets.target, swap.target, sysinit.target, + syslog.service, + syslog.socket, syslog.target, - systemd-initctl.service, - systemd-initctl.socket, - systemd-stdout-syslog-bridge.service, - systemd-stdout-syslog-bridge.socket, time-sync.target, umount.target @@ -145,6 +147,18 @@ service. + + dbus.socket + + A special unit for the + D-Bus system bus socket. All + units with + Type=dbus + automatically gain a + dependency on this + unit. + + default.target @@ -168,7 +182,7 @@ The display manager service. Usually this should be aliased (symlinked) to - xdm.service + gdm.service or a similar display manager service. systemd automatically @@ -196,6 +210,19 @@ + + final.target + + 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. + + + graphical.target @@ -212,6 +239,22 @@ during installation. + + http-daemon.target + + A target for pulling in + an HTTP server if there is + any. + 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 + $httpd + facility. + + halt.target @@ -234,6 +277,17 @@ rescue.target. + + kexec.target + + A special target unit + for shutting down and rebooting the system via kexec. + + Applications wanting to + reboot the system with kexec should start + this unit. + + local-fs.target @@ -554,6 +608,28 @@ or b. + + syslog.service + + The syslog service if + any. Implementations should + create a symlink from the + actual syslog implementation + to this generic name for + activating it. + + + + syslog.socket + + The socket unit where + syslog implementations should + listen on. All userspace log + messages will be made + available on this + socket. + + syslog.target @@ -567,74 +643,6 @@ facility. - - systemd-initctl.service - - This provides - compatibility with the SysV - /dev/initctl file system FIFO - for communication with the - init system. - This is a - socket-activated service, see - system-initctl.socket. - - - - systemd-initctl.socket - - Socket activation unit - for - system-initctl.service. - - - - systemd-stdout-syslog-bridge.service - - This is internally used - by systemd to provide syslog - logging to the processes it - maintains. - This is a - socket-activated service, see - system-stdout-syslog-bridge.socket. - - - - systemd-stdout-syslog-bridge.socket - - Socket activation unit - for - system-stdout-syslog-bridge.service. 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. - - - - systemd-shutdownd.service - - This is internally used - by - shutdown8 - to implement delayed shutdowns. - This is a - socket-activated service, see - system-shutdownd.socket. - - - - systemd-shutdownd.socket - - Socket activation unit - for - system-shutdownd.service. - - time-sync.target @@ -676,11 +684,8 @@ following special units are available, which have similar definitions as their system counterparts: default.target, - local-fs.target, - remote-fs.target, shutdown.target, - sockets.target, - swap.target. + sockets.target In addition the following special unit is understood only when systemd runs as service instance: @@ -715,6 +720,7 @@ See Also + systemd1, systemd.unit5, systemd.service5, systemd.socket5, 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 */ -- cgit v1.2.3-54-g00ecf From 41048afabb9af1db50af88647a5b93eb8168082c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 3 Apr 2012 23:08:04 +0200 Subject: man: clarify the formatting of timestamps --- man/systemd.journal-fields.xml | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'man') diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index 5f2a32cb00..becffc738a 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -226,9 +226,10 @@ timestamp of the message, if any is known that is different from the reception time of the - journal. The time in usec - since the epoch formatted as - decimal string. + journal. This is the time in + usec since the epoch UTC + formatted as decimal + string. @@ -293,7 +294,9 @@ The wallclock time (CLOCK_REALTIME) at the point in time the entry was received - by the journal. This has + by the journal, in usec since + the epoch UTC formatted as + decimal string. This has different properties from _SOURCE_REALTIME_TIMESTAMP= as it is usually a bit later @@ -308,10 +311,12 @@ The monotonic time (CLOCK_MONOTONIC) at the point in time the entry was received - by the journal. To be useful - as an address for the entry - this should be combined with - with boot ID in + 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 _BOOT_ID=. -- cgit v1.2.3-54-g00ecf From 6bc3bf5b05f4e79f9d6e42b7fb877b60070e048b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 4 Apr 2012 00:43:40 +0200 Subject: man: document the _TRANSPORT journal field --- man/systemd.journal-fields.xml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'man') diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index becffc738a..e638893b63 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -261,6 +261,31 @@ originating host. + + + _TRANSPORT= + + How the entry was + received by the journal + service. One of + driver, + syslog, + journal, + stdout, + kernel 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. + + + -- cgit v1.2.3-54-g00ecf