From f6940bc34a6128af3f867326d8dd5948e19b4bf5 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Sun, 6 Nov 2016 10:48:15 -0500 Subject: man: describe systemd-coredump --backtrace --- man/systemd-coredump.xml | 47 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 13 deletions(-) (limited to 'man') diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index 4a1bc8b296..7243467dc2 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -52,14 +52,26 @@ /usr/lib/systemd/systemd-coredump + /usr/lib/systemd/systemd-coredump systemd-coredump@.service systemd-coredump.socket Description - systemd-coredump is a system service that can acquire core dumps - from the kernel and handle them in various ways. + systemd-coredump@.service is a system service that can acquire core + dumps from the kernel and handle them in various ways. The systemd-coredump + executable does the actual work. It is invoked twice: once as the handler by the kernel, and the + second time in the systemd-coredump@.service to actually write the data to + the journal. + + When the kernel invokes systemd-coredump to handle a core dump, it runs + in privileged mode, and will connect to the socket created by the + systemd-coredump.socket unit, which in turn will spawn an unprivileged + systemd-coredump@.service instance to process the core dump. Hence + systemd-coredump.socket and systemd-coredump@.service + are helper units which do the actual processing of core dumps and are subject to normal service + management. Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved for further processing, for example in @@ -70,18 +82,20 @@ if possible to the journal and store the core dump itself in an external file in /var/lib/systemd/coredump. - When the kernel invokes systemd-coredump to handle a core dump, - it will connect to the socket created by the systemd-coredump.socket - unit, which in turn will spawn a systemd-coredump@.service instance - to process the core dump. Hence systemd-coredump.socket - and systemd-coredump@.service are helper units which do the actual - processing of core dumps and are subject to normal service management. - The behavior of a specific program upon reception of a signal is governed by a few factors which are described in detail in core5. In particular, the core dump will only be processed when the related resource limits are sufficient. + + It is also possible to invoke systemd-coredump with + option. In this case, systemd-coredump expects + a journal entry in the journal + Journal Export Format + on standard input. The entry should contain a MESSAGE= field and any additional + metadata fields the caller deems reasonable. systemd-coredump will append + additional metadata fields in the same way it does for core dumps received from the kernel. In + this mode, no core dump is stored in the journal. @@ -91,7 +105,8 @@ systemd.exec5. - In order to be used systemd-coredump must be configured in + In order to be used by the kernel to handle core dumps, + systemd-coredump must be configured in sysctl8 parameter kernel.core_pattern. The syntax of this parameter is explained in core5. @@ -99,14 +114,20 @@ kernel.core_pattern accordingly. This file may be masked or overridden to use a different setting following normal sysctl.d5 - rules. - If the sysctl configuration is modified, it must be updated in the kernel before - it takes effect, see + rules. If the sysctl configuration is modified, it must be updated in the kernel before it + takes effect, see sysctl8 and systemd-sysctl8. + In order to by used in the mode, an appropriate backtrace + handler must be installed on the sender side. For example, in case of + python1, this + means a sys.excepthook must installed, see + systemd-coredump-python. + + The behavior of systemd-coredump itself is configured through the configuration file /etc/systemd/coredump.conf and corresponding snippets /etc/systemd/coredump.conf.d/*.conf, see -- cgit v1.2.3-54-g00ecf