mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-24 01:23:36 +08:00
Code Issues Packages Projects Releases Wiki Activity
66ad93e86d
systemd/man/coredump.conf.xml

139 lines
5.6 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 05:15:39 +08:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
man: standarize on one-line license header No need to waste space, and uniformity is good. $ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
2019-03-14 21:29:37 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
coredump: Support coredump.conf.d directories in the usual search paths
2014-11-29 17:06:48 +08:00
<refentry id="coredump.conf" conditional="ENABLE_COREDUMP"
xmlns:xi="http://www.w3.org/2001/XInclude">
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
<refentryinfo>
<title>coredump.conf</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>coredump.conf</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>coredump.conf</refname>
coredump: Support coredump.conf.d directories in the usual search paths
2014-11-29 17:06:48 +08:00
<refname>coredump.conf.d</refname>
coredump: Improve man pages
2016-05-16 17:56:04 +08:00
<refpurpose>Core dump storage configuration files</refpurpose>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</refnamediv>
<refsynopsisdiv>
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-19 01:47:44 +08:00
<para><filename>/etc/systemd/coredump.conf</filename></para>
<para><filename>/etc/systemd/coredump.conf.d/*.conf</filename></para>
coredump: Support coredump.conf.d directories in the usual search paths
2014-11-29 17:06:48 +08:00
<para><filename>/run/systemd/coredump.conf.d/*.conf</filename></para>
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-19 01:47:44 +08:00
<para><filename>/usr/lib/systemd/coredump.conf.d/*.conf</filename></para>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</refsynopsisdiv>
<refsect1>
<title>Description</title>
man: typo fixes
2015-07-26 05:15:05 +08:00
<para>These files configure the behavior of
man: add a link to systemd-coredump(8) in Description of coredump.conf(5)
2014-11-30 22:45:29 +08:00
<citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
man: add more cross-references to coredump.conf(5) and systemd-coredump(8) Fixes #2901.
2016-04-02 22:40:09 +08:00
a handler for core dumps invoked by the kernel. Whether <command>systemd-coredump</command> is used
is determined by the kernel's
<varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
setting. See
<citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and
<citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>
pages for the details.</para>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</refsect1>
Do not advertise .d snippets over main config file For daemons which have a main configuration file, there's little reason for the administrator to use configuration snippets. They are useful for packagers which need to override settings, but we shouldn't advertise that as the main way of configuring those services. https://bugs.freedesktop.org/show_bug.cgi?id=89397
2015-03-04 08:10:21 +08:00
<xi:include href="standard-conf.xml" xpointer="main-conf" />
coredump: Support coredump.conf.d directories in the usual search paths
2014-11-29 17:06:48 +08:00
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
<refsect1>
<title>Options</title>
<para>All options are configured in the
tree-wide: drop quotes from around [section] For users, the square brackets already serve as markup and clearly delineate the section name from surrounding text. Putting additional markup around that only adds clutter. Also, we were very inconsistent in using the quotes. Let's just drop them altogether.
2020-07-06 17:00:06 +08:00
[Coredump] section:</para>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
man: move all config file options to one section We had "SYSTEM MANAGER DIRECTIVES" which was a misnomer already, because it also listed user manager stuff. Let's make this a more general section and move the items for other services there too (from "MISCELANENOUS").
2019-02-13 17:49:47 +08:00
<variablelist class='config-directives'>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
<varlistentry>
<term><varname>Storage=</varname></term>
coredump: remove Storage=both option Back when external storage was initially added in 34c10968cb, this mode of storage was added. This could have made some sense back when XZ compression was used, and an uncompressed core on disk could be used as short-lived cache file which does require costly decompression. But now fast LZ4 compression is used (by default) both internally and externally, so we have duplicated storage, using the same compression and same default maximum core size in both cases, but with different expiration lifetimes. Even the uncompressed-external, compressed-internal mode is not very useful: for small files, decompression with LZ4 is fast enough not to matter, and for large files, decompression is still relatively fast, but the disk-usage penalty is very big. An additional problem with the two modes of storage is that it complicates the code and makes it much harder to return a useful error message to the user if we cannot find the core file, since if we cannot find the file we have to check the internal storage first. This patch drops "both" storage mode. Effectively this means that if somebody configured coredump this way, they will get a warning about an unsupported value for Storage, and the default of "external" will be used. I'm pretty sure that this mode is very rarely used anyway.
2016-09-27 05:40:20 +08:00
<listitem><para>Controls where to store cores. One of <literal>none</literal>,
<literal>external</literal>, and <literal>journal</literal>. When
man: fix ProcessSizeMax= description, describe how to disable coredumps What the man page said was different than what the code did. save_external_coredump() will store the core temporarily for backtrace generation, and will delete if afterwards if it is too large. So to disable processing, it's necessary to both set Storage=none/Storage=journal+JournalSizeMax=0/Storage=external+ExternalSizeMax=0 and ProcessSizeMax=0. This updates the man page to reflect the code. The man pages are extended to describe that Storage=none + ProcessSizeMax=0 is the simplest way to disable coredump processing. All the storage and processing options make this quite complicated, so let's add a copy-and-pasteable example of how to disable coredump. Doing it through coredump.conf has the advantage that we still log, and the effect is immediate, unlike masking the sysconf file. Fixes #8788.
2018-05-17 23:08:31 +08:00
<literal>none</literal>, the core dumps may be logged (including the backtrace if
coredump: remove Storage=both option Back when external storage was initially added in 34c10968cb, this mode of storage was added. This could have made some sense back when XZ compression was used, and an uncompressed core on disk could be used as short-lived cache file which does require costly decompression. But now fast LZ4 compression is used (by default) both internally and externally, so we have duplicated storage, using the same compression and same default maximum core size in both cases, but with different expiration lifetimes. Even the uncompressed-external, compressed-internal mode is not very useful: for small files, decompression with LZ4 is fast enough not to matter, and for large files, decompression is still relatively fast, but the disk-usage penalty is very big. An additional problem with the two modes of storage is that it complicates the code and makes it much harder to return a useful error message to the user if we cannot find the core file, since if we cannot find the file we have to check the internal storage first. This patch drops "both" storage mode. Effectively this means that if somebody configured coredump this way, they will get a warning about an unsupported value for Storage, and the default of "external" will be used. I'm pretty sure that this mode is very rarely used anyway.
2016-09-27 05:40:20 +08:00
possible), but not stored permanently. When <literal>external</literal> (the
default), cores will be stored in <filename>/var/lib/systemd/coredump/</filename>.
When <literal>journal</literal>, cores will be stored in the journal and rotated
following normal journal rotation patterns.</para>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
<para>When cores are stored in the journal, they might be
compressed following journal compression settings, see
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
When cores are stored externally, they will be compressed
by default, see below.</para></listitem>
</varlistentry>
<varlistentry>
coredump: replace Compression= setting by simpler Compress= boolean setting Let's move things closer to journald's configuration settings, which knows Compress= already, as a boolean. This makes things more uniform, but also gives us more freedom to possibly swap out the used compression algorithm one day.
2014-06-28 01:09:22 +08:00
<term><varname>Compress=</varname></term>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
man: delete ZX as sole compression; "Compress=" as boolean In man journald.conf, removes reference to XZ as sole form of compression. See commit d89c8fdf48c7bad5816b9f2e77e8361721f22517. In man coredump.conf, clarifies that "Compression=" controls existence, not type, of compression.
2014-12-01 11:13:06 +08:00
<listitem><para>Controls compression for external
doc: correct orthography, word forms and missing/extraneous words
2014-08-03 13:11:37 +08:00
storage. Takes a boolean argument, which defaults to
coredump: replace Compression= setting by simpler Compress= boolean setting Let's move things closer to journald's configuration settings, which knows Compress= already, as a boolean. This makes things more uniform, but also gives us more freedom to possibly swap out the used compression algorithm one day.
2014-06-28 01:09:22 +08:00
<literal>yes</literal>.</para>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ProcessSizeMax=</varname></term>
<listitem><para>The maximum size in bytes of a core
coredump: Improve man pages
2016-05-16 17:56:04 +08:00
which will be processed. Core dumps exceeding this size
man: fix ProcessSizeMax= description, describe how to disable coredumps What the man page said was different than what the code did. save_external_coredump() will store the core temporarily for backtrace generation, and will delete if afterwards if it is too large. So to disable processing, it's necessary to both set Storage=none/Storage=journal+JournalSizeMax=0/Storage=external+ExternalSizeMax=0 and ProcessSizeMax=0. This updates the man page to reflect the code. The man pages are extended to describe that Storage=none + ProcessSizeMax=0 is the simplest way to disable coredump processing. All the storage and processing options make this quite complicated, so let's add a copy-and-pasteable example of how to disable coredump. Doing it through coredump.conf has the advantage that we still log, and the effect is immediate, unlike masking the sysconf file. Fixes #8788.
2018-05-17 23:08:31 +08:00
may be stored, but the backtrace will not be generated.
</para>
<para>Setting <varname>Storage=none</varname> and <varname>ProcessSizeMax=0</varname>
disables all coredump handling except for a log entry.</para>
</listitem>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</varlistentry>
<varlistentry>
<term><varname>ExternalSizeMax=</varname></term>
<term><varname>JournalSizeMax=</varname></term>
<listitem><para>The maximum (uncompressed) size in bytes of a
core to be saved.</para></listitem>
</varlistentry>
coredump: add simple coredump vacuuming When disk space taken up by coredumps grows beyond a configured limit start removing the oldest coredump of the user with the most coredumps, until we get below the limit again.
2014-06-28 00:57:24 +08:00
<varlistentry>
<term><varname>MaxUse=</varname></term>
<term><varname>KeepFree=</varname></term>
<listitem><para>Enforce limits on the disk space taken up by
coredump: Improve man pages
2016-05-16 17:56:04 +08:00
externally stored core dumps. <option>MaxUse=</option> makes
sure that old core dumps are removed as soon as the total disk
space taken up by core dumps grows beyond this limit (defaults
coredump: add simple coredump vacuuming When disk space taken up by coredumps grows beyond a configured limit start removing the oldest coredump of the user with the most coredumps, until we get below the limit again.
2014-06-28 00:57:24 +08:00
to 10% of the total disk size). <option>KeepFree=</option>
controls how much disk space to keep free at least (defaults
to 15% of the total disk size). Note that the disk space used
coredump: Improve man pages
2016-05-16 17:56:04 +08:00
by core dumps might temporarily exceed these limits while
core dumps are processed. Note that old core dumps are also
docs: remove repeating words from man/*xml
2014-07-23 18:40:07 +08:00
removed based on time via
coredump: make sure we vacuum by default Only if both keep_free and max_use are actually 0 we can shortcut things and avoid vacuuming. If either are positive or -1 we need to execute the vacuuming. http://lists.freedesktop.org/archives/systemd-devel/2015-April/031382.html
2015-05-16 02:56:55 +08:00
<citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Set
doc: correct punctuation and improve typography in documentation
2014-08-03 13:11:12 +08:00
either value to 0 to turn off size-based
coredump: make sure we vacuum by default Only if both keep_free and max_use are actually 0 we can shortcut things and avoid vacuuming. If either are positive or -1 we need to execute the vacuuming. http://lists.freedesktop.org/archives/systemd-devel/2015-April/031382.html
2015-05-16 02:56:55 +08:00
clean-up.</para></listitem>
coredump: add simple coredump vacuuming When disk space taken up by coredumps grows beyond a configured limit start removing the oldest coredump of the user with the most coredumps, until we get below the limit again.
2014-06-28 00:57:24 +08:00
</varlistentry>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</variablelist>
man: add a note where coredump default values are I don't want to include all the default values in the man page because that's bound to get out of date…
2018-01-20 07:27:46 +08:00
<para>The defaults for all values are listed as comments in the
template <filename>/etc/systemd/coredump.conf</filename> file that
is installed by default.</para>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
coredump: add simple coredump vacuuming When disk space taken up by coredumps grows beyond a configured limit start removing the oldest coredump of the user with the most coredumps, until we get below the limit again.
2014-06-28 00:57:24 +08:00
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>
man: add coredump.conf(5)
2014-06-26 13:02:48 +08:00
</para>
</refsect1>
</refentry>
Reference in New Issue Copy Permalink