Debian Codegraph @

upstream/debian-unstable/man5/coredump.conf.5

raw
1 '\" t
2 .TH "COREDUMP\&.CONF" "5" "" "systemd 261~rc3" "coredump.conf"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 coredump.conf, coredump.conf.d \- Core dump storage configuration files
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /etc/systemd/coredump\&.conf
28 .RE
29 .RS 4
30 /run/systemd/coredump\&.conf
31 .RE
32 .RS 4
33 /usr/local/lib/systemd/coredump\&.conf
34 .RE
35 .RS 4
36 /usr/lib/systemd/coredump\&.conf
37 .RE
38 .RS 4
39 /etc/systemd/coredump\&.conf\&.d/*\&.conf
40 .RE
41 .RS 4
42 /run/systemd/coredump\&.conf\&.d/*\&.conf
43 .RE
44 .RS 4
45 /usr/local/lib/systemd/coredump\&.conf\&.d/*\&.conf
46 .RE
47 .RS 4
48 /usr/lib/systemd/coredump\&.conf\&.d/*\&.conf
49 .RE
50 .SH "DESCRIPTION"
51 .PP
52 These files configure the behavior of
53 \fBsystemd-coredump\fR(8), a handler for core dumps invoked by the kernel\&. Whether
54 \fBsystemd\-coredump\fR
55 is used is determined by the kernel\*(Aqs
56 \fIkernel\&.core_pattern\fR
57 \fBsysctl\fR(8)
58 setting\&. See
59 \fBsystemd-coredump\fR(8)
60 and
61 \fBcore\fR(5)
62 pages for the details\&.
63 .SH "CONFIGURATION DIRECTORIES AND PRECEDENCE"
64 .PP
65 The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used:
66 /etc/systemd/,
67 /run/systemd/,
68 /usr/local/lib/systemd/
69 \&\s-2\u[1]\d\s+2,
70 /usr/lib/systemd/\&. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can also be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in
71 /etc/
72 if it is shipped under
73 /usr/), however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&.
74 .PP
75 In addition to the main configuration file, drop\-in configuration snippets are read from
76 /usr/lib/systemd/*\&.conf\&.d/,
77 /usr/local/lib/systemd/*\&.conf\&.d/, and
78 /etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the
79 *\&.conf\&.d/
80 configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&.
81 .PP
82 When packages need to customize the configuration, they can install drop\-ins under
83 /usr/\&. Files in
84 /etc/
85 are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering\&. This also defines a concept of drop\-in priorities to allow OS vendors to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. It is recommended to use the range 10\-40 for drop\-ins in
86 /usr/
87 and the range 60\-90 for drop\-ins in
88 /etc/
89 and
90 /run/, to make sure that local and transient drop\-ins take priority over drop\-ins shipped by the OS vendor\&.
91 .PP
92 To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to
93 /dev/null
94 in the configuration directory in
95 /etc/, with the same filename as the vendor configuration file\&.
96 .SH "OPTIONS"
97 .PP
98 All options are configured in the [Coredump] section:
99 .PP
100 \fIStorage=\fR
101 .RS 4
102 Controls where to store cores\&. One of
103 "none",
104 "external", and
105 "journal"\&. When
106 "none", the core dumps may be logged (including the backtrace if possible), but not stored permanently\&. When
107 "external"
108 (the default), cores will be stored in
109 /var/lib/systemd/coredump/\&. When
110 "journal", cores will be stored in the journal and rotated following normal journal rotation patterns\&.
111 .sp
112 When cores are stored in the journal, they might be compressed following journal compression settings, see
113 \fBjournald.conf\fR(5)\&. When cores are stored externally, they will be compressed by default, see below\&.
114 .sp
115 Note that in order to process a coredump (i\&.e\&. extract a stack trace) the core must be written to disk first\&. Thus, unless
116 \fIProcessSizeMax=\fR
117 is set to 0 (see below), the core will be written to
118 /var/lib/systemd/coredump/
119 either way (under a temporary filename, or even in an unlinked file),
120 \fIStorage=\fR
121 thus only controls whether to leave it there even after it was processed\&.
122 .sp
123 Added in version 215\&.
124 .RE
125 .PP
126 \fICompress=\fR
127 .RS 4
128 Controls compression for external storage\&. Takes a boolean argument, which defaults to
129 "yes"\&.
130 .sp
131 Added in version 215\&.
132 .RE
133 .PP
134 \fIProcessSizeMax=\fR
135 .RS 4
136 The maximum size in bytes of a core which will be processed\&. Core dumps exceeding this size may be stored, but the stack trace will not be generated\&. Like other sizes in this same config file, the usual suffixes to the base of 1024 are allowed (B, K, M, G, T, P, and E)\&. Defaults to 1G on 32\-bit systems, 32G on 64\-bit systems\&.
137 .sp
138 Setting
139 \fIStorage=none\fR
140 and
141 \fIProcessSizeMax=0\fR
142 disables all coredump handling except for a log entry\&.
143 .sp
144 Added in version 215\&.
145 .RE
146 .PP
147 \fIEnterNamespace=\fR
148 .RS 4
149 For processes belonging to a PID namespace, controls whether
150 \fBsystemd-coredump\fR(8)
151 shall attempt to process core dumps on the host, using debug information from the file system hierarchy (i\&.e\&. the mount namespace) of the process that crashed\&. Access to the process\*(Aq file system hierarchy might be necessary to generate a fully symbolized backtrace\&. If set to
152 "yes",
153 \fBsystemd\-coredump\fR
154 will obtain the tree of mounts from the crashing process\*(Aq mount namespace and will try to generate the stack trace in host context using the debug information of binaries and libraries contained in the crashing process\*(Aq hierarchy\&. Defaults to
155 "no", i\&.e\&. no attempt is made to acquire external debug information from the process\*(Aq mount namespace, in order to maximize security\&. This option has no effect on processes that are part of the host\*(Aqs PID namespace\&.
156 .sp
157 Note that the coredump of the namespaced process is still saved in
158 /var/lib/systemd/coredump/
159 on the host even if
160 \fIEnterNamespace=\fR
161 is set to
162 "no"
163 (subject to
164 \fIStorage=\fR)\&.
165 .sp
166 Note that
167 \fIEnterNamespace=\fR
168 only has an effect if a core dump is generated by a container whose unit does not have
169 \fICoredumpReceive=\fR
170 enabled\&.
171 .sp
172 Note that it\*(Aqs typically preferable to let containers and other namespace\-based sandboxes process their own coredumps, if possible, for best security\&. This may be enabled on the container\*(Aqs unit via the
173 \fICoredumpReceive=\fR
174 setting, see
175 \fBsystemd.resource-control\fR(5)
176 for details\&.
177 .sp
178 Added in version 257\&.
179 .RE
180 .PP
181 \fIExternalSizeMax=\fR, \fIJournalSizeMax=\fR
182 .RS 4
183 The maximum (compressed or uncompressed) size in bytes of a coredump to be saved in separate files on disk (default: 1G on 32\-bit systems, 32G on 64\-bit systems) or in the journal (default: 767M)\&. Note that the journal service enforces a hard limit on journal log records of 767M, and will ignore larger submitted log records\&. Hence,
184 \fIJournalSizeMax=\fR
185 may be lowered relative to the default, but not increased\&. Unit suffixes are allowed just as in
186 \fBProcessSizeMax=\fR\&.
187 .sp
188 \fIExternalSizeMax=infinity\fR
189 sets the core size to unlimited\&.
190 .sp
191 Added in version 215\&.
192 .RE
193 .PP
194 \fIMaxUse=\fR, \fIKeepFree=\fR
195 .RS 4
196 Enforce limits on the disk space, specified in bytes, taken up by externally stored core dumps\&. Unit suffixes are allowed just as in
197 \fBProcessSizeMax=\fR\&.
198 \fBMaxUse=\fR
199 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 to 10% of the total disk size, capped at 4GiB, minimum 1MiB)\&.
200 \fBKeepFree=\fR
201 controls how much disk space to keep free at least (defaults to 15% of the total disk size, limited to a maximum of 4GiB)\&. Note that the disk space used by core dumps might temporarily exceed these limits while core dumps are processed\&.
202 \fBMaxUse=\fR
203 takes precedence\&. Note that old core dumps are also removed based on time via
204 \fBsystemd-tmpfiles\fR(8)\&. Set either value to 0 to turn off size\-based cleanup\&.
205 .sp
206 Added in version 215\&.
207 .RE
208 .PP
209 Use
210 .sp
211 .if n \{\
212 .RS 4
213 .\}
214 .nf
215 systemd\-analyze cat\-config systemd/coredump\&.conf
216 .fi
217 .if n \{\
218 .RE
219 .\}
220 .sp
221 to display the full config\&.
222 .SH "SEE ALSO"
223 .PP
224 \fBsystemd-journald.service\fR(8), \fBcoredumpctl\fR(1), \fBsystemd-tmpfiles\fR(8)
225 .SH "NOTES"
226 .IP " 1." 4
227 💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If
228 /usr/local/
229 is a separate partition, it may not be available during early boot, and must not be used for configuration.
230