1MAKEDUMPFILE(8) Linux System Administrator's Manual MAKEDUMPFILE(8)
2
6 makedumpfile - make a small dumpfile of kdump
7
9 makedumpfile [OPTION] [-x VMLINUX|-i VMCOREINFO] VMCORE DUMPFILE
10 makedumpfile -F [OPTION] [-x VMLINUX|-i VMCOREINFO] VMCORE
11 makedumpfile [OPTION] -x VMLINUX [--config FILTERCONFIGFILE] [--eppic
12 EPPICMACRO] VMCORE DUMPFILE
13 makedumpfile -R DUMPFILE
14 makedumpfile --split [OPTION] [-x VMLINUX|-i VMCOREINFO] VMCORE DUMP‐
15 FILE1 DUMPFILE2 [DUMPFILE3 ..]
16 makedumpfile [OPTION] [-x VMLINUX|-i VMCOREINFO] --num-threads THREAD‐
17 NUM VMCORE DUMPFILE
18 makedumpfile --reassemble DUMPFILE1 DUMPFILE2 [DUMPFILE3 ..] DUMPFILE
19 makedumpfile -g VMCOREINFO -x VMLINUX
20 makedumpfile [OPTION] [--xen-syms XEN-SYMS|--xen-vmcoreinfo VMCORE‐
21 INFO] VMCORE DUMPFILE
22 makedumpfile --dump-dmesg [--partial-dmesg] [-x VMLINUX|-i VMCOREINFO]
23 VMCORE LOGFILE
24 makedumpfile [OPTION] -x VMLINUX --diskset=VMCORE1 --diskset=VMCORE2
25 [--diskset=VMCORE3 ..] DUMPFILE
26 makedumpfile -h
27 makedumpfile -v
28
30 With kdump, the memory image of the first kernel (called "panicked ker‐
31 nel") can be taken as /proc/vmcore while the second kernel (called
32 "kdump kernel" or "capture kernel") is running. This document repre‐
33 sents /proc/vmcore as VMCORE. makedumpfile makes a small DUMPFILE by
34 compressing dump data or by excluding unnecessary pages for analysis,
35 or both. makedumpfile needs the first kernel's debug information, so
36 that it can distinguish unnecessary pages by analyzing how the first
37 kernel uses the memory. The information can be taken from VMLINUX or
38 VMCOREINFO.
39 makedumpfile can exclude the following types of pages while copying VM‐
41 CORE to DUMPFILE, and a user can choose which type of pages will be ex‐
42 cluded.
43 - Pages filled with zero
44 - Cache pages without private flag (non-private cache)
45 - Cache pages with private flag (private cache)
46 - User process data pages
47 - Free pages
48 makedumpfile provides two DUMPFILE formats (the ELF format and the
50 kdump-compressed format). By default, makedumpfile makes a DUMPFILE in
51 the kdump-compressed format. The kdump-compressed format is readable
52 only with the crash utility, and it can be smaller than the ELF format
53 because of the compression support. The ELF format is readable with GDB
54 and the crash utility. If a user wants to use GDB, DUMPFILE format has
55 to be explicitly specified to be the ELF format.
56 Apart from the exclusion of unnecessary pages mentioned above, make‐
58 dumpfile allows user to filter out targeted kernel data. The filter
59 config file can be used to specify kernel/module symbols and its mem‐
60 bers that need to be filtered out through the erase command syntax.
61 makedumpfile reads the filter config and builds the list of memory ad‐
62 dresses and its sizes after processing filter commands. The memory lo‐
63 cations that require to be filtered out are then poisoned with charac‐
64 ter 'X' (58 in Hex). Refer to makedumpfile.conf(5) for file format.
65 Eppic macros can also be used to specify kernel symbols and its members
67 that need to be filtered. Eppic provides C semantics including language
68 constructs such as conditional statements, logical and arithmetic oper‐
69 ators, functions, nested loops to traverse and erase kernel data. --ep‐
70 pic requires eppic_makedumpfile.so and eppic library. eppic_makedump‐
71 file.so can be built from makedumpfile source. Refer to
72 http://code.google.com/p/eppic/ to build eppic library libeppic.a and
73 for more information on writing eppic macros.
74 To analyze the first kernel's memory usage, makedumpfile can refer to
76 VMCOREINFO instead of VMLINUX. VMCOREINFO contains the first kernel's
77 information (structure size, field offset, etc.), and VMCOREINFO is
78 small enough to be included into the second kernel's initrd.
79 If the second kernel is running on its initrd without mounting a root
80 file system, makedumpfile cannot refer to VMLINUX because the second
81 kernel's initrd cannot include a large file like VMLINUX. To solve the
82 problem, makedumpfile makes VMCOREINFO beforehand, and it refers to VM‐
83 COREINFO instead of VMLINUX while the second kernel is running.
84 VMCORE has contained VMCOREINFO since linux-2.6.24, and a user does not
85 need to specify neither -x nor -i option.
86 If the second kernel is running on its initrd without mounting any file
88 system, a user needs to transport the dump data to a remote host. To
89 transport the dump data by SSH, makedumpfile outputs the dump data in
90 the intermediate format (the flattened format) to the standard output.
91 By piping the output data to SSH, a user can transport the dump data to
92 a remote host. Note that analysis tools (crash utility before version
93 5.1.2 or GDB) cannot read the flattened format directly, so on a remote
94 host the received data in the flattened format needs to be rearranged
95 to a readable DUMPFILE format by makedumpfile (or makedumpfile-R.pl).
96 makedumpfile can read a DUMPFILE in the kdump-compressed format instead
98 of VMCORE and re-filter it. This feature is useful in situation that
99 users need to reduce the file size of DUMPFILE for sending it somewhere
100 by ftp/scp/etc. (If all of the page types, which are specified by a new
101 dump_level, are excluded from an original DUMPFILE already, a new DUMP‐
102 FILE is the same as an original DUMPFILE.)
103 For example, makedumpfile can create a DUMPFILE of dump_level 31 from
104 the one of dump_level 3 like the following:
105 Example:
106 # makedumpfile -c -d 3 /proc/vmcore dumpfile.1
107 # makedumpfile -c -d 31 dumpfile.1 dumpfile.2
108 makedumpfile can read VMCORE(s) in three kinds of sadump formats: sin‐
110 gle partition format, diskset format and media backup format, and can
111 convert each of them into kdump-compressed format with filtering and
112 compression processing. Note that for VMCORE(s) created by sadump, you
113 always need to pass VMLINUX with -x option. Also, to pass multiple VM‐
114 COREs created on diskset configuration, you need to use --diskset op‐
115 tion.
116
119 -c,-l,-p,-z
120 Compress dump data by the page using the following compression
121 library respectively:
122 -c : zlib
123 -l : lzo
124 -p : snappy
125 -z : zstd
126 (-l, -p and -z option need USELZO=on, USESNAPPY=on and
127 USEZSTD=on respectively when building makedumpfile)
128 A user cannot specify this option with -E option, because the
129 ELF format does not support compressed data.
130 Example:
131 # makedumpfile -c -d 31 -x vmlinux /proc/vmcore dumpfile
132 -d dump_level
135 Specify the type of unnecessary page for analysis.
136 Pages of the specified type are not copied to DUMPFILE. The page
137 type marked in the following table is excluded. A user can spec‐
138 ify multiple page types by setting the sum of each page type for
139 dump_level. The maximum of dump_level is 31. Note that a
140 dump_level for Xen dump filtering is 0 or 1 on a machine other
141 than x86_64. On a x86_64 machine, even 2 or bigger dump level
142 will be effective if you specify domain-0's vmlinux with -x op‐
143 tion. Then the pages are excluded only from domain-0.
144 If specifying multiple dump_levels with the delimiter ',', make‐
145 dumpfile retries to create DUMPFILE using the next dump_level
146 when the size of a dumpfile exceeds the limit specified with
147 '-L' or when a "No space on device" error happens. For example,
148 if dump_level is "11,31" and makedumpfile fails with dump_level
149 11, makedumpfile retries with dump_level 31.
150 Example:
151 # makedumpfile -d 11 -x vmlinux /proc/vmcore dumpfile
152 # makedumpfile -d 11,31 -x vmlinux /proc/vmcore dumpfile
153 Base level:
154 dump_level consists of five bits, so there are five base levels
155 to specify the type of unnecessary page.
156 1 : Exclude the pages filled with zero.
157 2 : Exclude the non-private cache pages.
158 4 : Exclude all cache pages.
159 8 : Exclude the user process data pages.
160 16 : Exclude the free pages.
161 Here is the all combinations of the bits.
163 | |non- | | |
165 dump | zero |private|private| user | free
166 level | page |cache |cache | data | page
167 -------+------+-------+-------+------+------
168 0 | | | | |
169 1 | X | | | |
170 2 | | X | | |
171 3 | X | X | | |
172 4 | | X | X | |
173 5 | X | X | X | |
174 6 | | X | X | |
175 7 | X | X | X | |
176 8 | | | | X |
177 9 | X | | | X |
178 10 | | X | | X |
179 11 | X | X | | X |
180 12 | | X | X | X |
181 13 | X | X | X | X |
182 14 | | X | X | X |
183 15 | X | X | X | X |
184 16 | | | | | X
185 17 | X | | | | X
186 18 | | X | | | X
187 19 | X | X | | | X
188 20 | | X | X | | X
189 21 | X | X | X | | X
190 22 | | X | X | | X
191 23 | X | X | X | | X
192 24 | | | | X | X
193 25 | X | | | X | X
194 26 | | X | | X | X
195 27 | X | X | | X | X
196 28 | | X | X | X | X
197 29 | X | X | X | X | X
198 30 | | X | X | X | X
199 31 | X | X | X | X | X
200 -L SIZE
203 Limit the size of the output file to SIZE bytes. An incomplete
204 DUMPFILE or LOGFILE is written if the size would otherwise ex‐
205 ceed SIZE.
206 -E Create DUMPFILE in the ELF format.
209 This option cannot be specified with the -c, -l or -p options,
210 because the ELF format does not support compressed data.
211 Example:
212 # makedumpfile -E -d 31 -x vmlinux /proc/vmcore dumpfile
213 -f Force existing DUMPFILE to be overwritten and mem-usage to work
216 with older kernel as well.
217 Example:
218 # makedumpfile -f -d 31 -x vmlinux /proc/vmcore dumpfile
219 This command overwrites DUMPFILE even if it already exists.
220 # makedumpfile -f --mem-usage /proc/kcore
221 Kernel version lesser than v4.11 will not work with --mem-usage
222 functionality until it has been patched with upstream commit
223 464920104bf7. Therefore if you have patched your older kernel
224 then use -f.
225 -x VMLINUX
228 Specify the first kernel's VMLINUX with debug information to an‐
229 alyze the first kernel's memory usage.
230 This option is necessary if VMCORE does not contain VMCOREINFO,
231 [-i VMCOREINFO] is not specified, and dump_level is 2 or more.
232 The page size of the first kernel and the second kernel should
233 match.
234 Example:
235 # makedumpfile -d 31 -x vmlinux /proc/vmcore dumpfile
236 -i VMCOREINFO
239 Specify VMCOREINFO instead of VMLINUX for analyzing the first
240 kernel's memory usage.
241 VMCOREINFO should be made beforehand by makedumpfile with -g op‐
242 tion, and it contains the first kernel's information.
243 This option is necessary if VMCORE does not contain VMCOREINFO,
244 [-x VMLINUX] is not specified, and dump_level is 2 or more.
245 Example:
246 # makedumpfile -d 31 -i vmcoreinfo /proc/vmcore dumpfile
247 -g VMCOREINFO
250 Generate VMCOREINFO from the first kernel's VMLINUX with debug
251 information.
252 VMCOREINFO must be generated on the system that is running the
253 first kernel. With -i option, a user can specify VMCOREINFO gen‐
254 erated on the other system that is running the same first ker‐
255 nel. [-x VMLINUX] must be specified.
256 Example:
257 # makedumpfile -g vmcoreinfo -x vmlinux
258 --config FILTERCONFIGFILE
261 Used in conjunction with -x VMLINUX option, to specify the fil‐
262 ter config file FILTERCONFIGFILE that contains erase commands to
263 filter out desired kernel data from vmcore while creating DUMP‐
264 FILE. For filter command syntax please refer to makedump‐
265 file.conf(5).
266 --eppic EPPICMACRO
269 Used in conjunction with -x VMLINUX option, to specify the eppic
270 macro file that contains filter rules or directory that contains
271 eppic macro files to filter out desired kernel data from vmcore
272 while creating DUMPFILE. When directory is specified, all the
273 eppic macros in the directory are processed.
274 -F Output the dump data in the flattened format to the standard
277 output for transporting the dump data by SSH.
278 Analysis tools (crash utility before version 5.1.2 or GDB) can‐
279 not read the flattened format directly. For analysis, the dump
280 data in the flattened format should be rearranged to a normal
281 DUMPFILE (readable with analysis tools) by -R option. By which
282 option is specified with -F option, the format of the rearranged
283 DUMPFILE is fixed. In other words, it is impossible to specify
284 the DUMPFILE format when the dump data is rearranged with -R op‐
285 tion. If specifying -E option with -F option, the format of the
286 rearranged DUMPFILE is the ELF format. Otherwise, it is the
287 kdump-compressed format. All the messages are output to standard
288 error output by -F option because standard output is used for
289 the dump data.
290 Example:
291 # makedumpfile -F -c -d 31 -x vmlinux /proc/vmcore \
292 | ssh user@host "cat > dumpfile.tmp"
293 # makedumpfile -F -c -d 31 -x vmlinux /proc/vmcore \
294 | ssh user@host "makedumpfile -R dumpfile"
295 # makedumpfile -F -E -d 31 -i vmcoreinfo /proc/vmcore \
296 | ssh user@host "makedumpfile -R dumpfile"
297 # makedumpfile -F -E --xen-vmcoreinfo VMCOREINFO /proc/vmcore \
298 | ssh user@host "makedumpfile -R dumpfile"
299 -R Rearrange the dump data in the flattened format from the stan‐
302 dard input to a normal DUMPFILE (readable with analysis tools).
303 Example:
304 # makedumpfile -R dumpfile < dumpfile.tmp
305 # makedumpfile -F -d 31 -x vmlinux /proc/vmcore \
306 | ssh user@host "makedumpfile -R dumpfile"
307 Instead of using -R option, a perl script "makedumpfile-R.pl"
309 rearranges the dump data in the flattened format to a normal
310 DUMPFILE, too. The perl script does not depend on architecture,
311 and most systems have perl command. Even if a remote host does
312 not have makedumpfile, it is possible to rearrange the dump data
313 in the flattened format to a readable DUMPFILE on a remote host
314 by running this script.
315 Example:
316 # makedumpfile -F -d 31 -x vmlinux /proc/vmcore \
317 | ssh user@host "makedumpfile-R.pl dumpfile"
318 --split
321 Split the dump data to multiple DUMPFILEs in parallel. If speci‐
322 fying DUMPFILEs on different storage devices, a device can share
323 I/O load with other devices and it reduces time for saving the
324 dump data. The file size of each DUMPFILE is smaller than the
325 system memory size which is divided by the number of DUMPFILEs.
326 This feature supports only the kdump-compressed format.
327 Example:
328 # makedumpfile --split -d 31 -x vmlinux /proc/vmcore dumpfile1
329 dumpfile2
330 --num-threads THREADNUM
333 Using multiple threads to read and compress data of each page in
334 parallel. And it will reduces time for saving DUMPFILE. Note
335 that if the usable cpu number is less than the thread number, it
336 may lead to great performance degradation. This feature only
337 supports creating DUMPFILE in kdump-comressed format from VMCORE
338 in kdump-compressed format or elf format.
339 Example:
340 # makedumpfile -d 31 --num-threads 4 /proc/vmcore dumpfile
341 --reassemble
344 Reassemble multiple DUMPFILEs, which are created by --split op‐
345 tion, into one DUMPFILE. dumpfile1 and dumpfile2 are reassembled
346 into dumpfile on the following example.
347 Example:
348 # makedumpfile --reassemble dumpfile1 dumpfile2 dumpfile
349 -b <order>
352 Cache 2^order pages in ram when generating DUMPFILE before writ‐
353 ing to output. The default value is 4.
354 --cyclic-buffer buffer_size
357 Specify the buffer size in kilo bytes for bitmap data. Filter‐
358 ing processing will be divided into multi cycles to fix the mem‐
359 ory consumption, the number of cycles is represented as:
360 num_of_cycles = system_memory / (buffer_size * 1024 *
362 bit_per_bytes * page_size )
363 The lesser number of cycles, the faster working speed is ex‐
365 pected. By default, buffer_size will be calculated automati‐
366 cally depending on system memory size, so ordinary users don't
367 need to specify this option.
368 Example:
370 # makedumpfile --cyclic-buffer 1024 -d 31 -x vmlinux /proc/vm‐
371 core dumpfile
372 --splitblock-size splitblock_size
375 Specify the splitblock size in kilo bytes for analysis with
376 --split. If --splitblock N is specified, difference of each
377 splitted dumpfile size is at most N kilo bytes.
378 Example:
379 # makedumpfile --splitblock-size 1024 -d 31 -x vmlinux --split
380 /proc/vmcore dumpfile1 dumpfile2
381 --work-dir
385 Specify the working directory for the temporary bitmap file. If
386 this option isn't specified, the bitmap will be saved on memory.
387 Filtering processing has to do 2 pass scanning to fix the memory
388 consumption, but it can be avoided by using working directory on
389 file system. So if you specify this option, the filtering speed
390 may be bit faster.
391 Example:
393 # makedumpfile --work-dir /tmp -d 31 -x vmlinux /proc/vmcore
394 dumpfile
395 --non-mmap
398 Never use mmap(2) to read VMCORE even if it supports mmap(2).
399 Generally, reading VMCORE with mmap(2) is faster than without
400 it, so ordinary users don't need to specify this option. This
401 option is mainly for debugging.
402 Example:
403 # makedumpfile --non-mmap -d 31 -x vmlinux /proc/vmcore dumpfile
404 --xen-syms XEN-SYMS
407 Specify the XEN-SYMS with debug information to analyze the xen's
408 memory usage. This option extracts the part of xen and do‐
409 main-0.
410 Example:
411 # makedumpfile -E --xen-syms xen-syms /proc/vmcore dumpfile
412 --xen-vmcoreinfo VMCOREINFO
415 Specify VMCOREINFO instead of XEN-SYMS for analyzing the xen's
416 memory usage.
417 VMCOREINFO should be made beforehand by makedumpfile with -g op‐
418 tion, and it contains the xen's information.
419 Example:
420 # makedumpfile -E --xen-vmcoreinfo VMCOREINFO /proc/vmcore dump‐
421 file
422 -X Exclude all the user domain pages from Xen kdump's VMCORE, and
425 extracts the part of xen and domain-0. If VMCORE contains VMCOR‐
426 EINFO for Xen, it is not necessary to specify --xen-syms and
427 --xen-vmcoreinfo.
428 Example:
429 # makedumpfile -E -X /proc/vmcore dumpfile
430 --xen_phys_start xen_phys_start_address
433 This option is only for x86_64. Specify the xen_phys_start_ad‐
434 dress, if the xen code/data is relocatable and VMCORE does not
435 contain xen_phys_start_address in the CRASHINFO.
436 xen_phys_start_address can be taken from the line of "Hypervisor
437 code and data" in /proc/iomem. For example, specify 0xcee00000
438 as xen_phys_start_address if /proc/iomem is the following:
439 -------------------------------------------------------
440 # cat /proc/iomem
441 ...
442 cee00000-cfd99999 : Hypervisor code and data
443 ...
444 -------------------------------------------------------
445 Example:
447 # makedumpfile -E -X --xen_phys_start 0xcee00000 /proc/vmcore
448 dumpfile
449 --message-level message_level
452 Specify the message types.
453 Users can restrict outputs printed by specifying message_level
454 with this option. The message type marked with an X in the fol‐
455 lowing table is printed. For example, according to the table,
456 specifying 7 as message_level means progress indicator, common
457 message, and error message are printed, and this is a default
458 value. Note that the maximum value of message_level is 31.
459 message | progress | common | error | debug | report
461 level | indicator| message | message | message | message
462 ---------+----------+---------+---------+---------+---------
463 0 | | | | |
464 1 | X | | | |
465 2 | | X | | |
466 3 | X | X | | |
467 4 | | | X | |
468 5 | X | | X | |
469 6 | | X | X | |
470 * 7 | X | X | X | |
471 8 | | | | X |
472 9 | X | | | X |
473 10 | | X | | X |
474 11 | X | X | | X |
475 12 | | | X | X |
476 13 | X | | X | X |
477 14 | | X | X | X |
478 15 | X | X | X | X |
479 16 | | | | | X
480 17 | X | | | | X
481 18 | | X | | | X
482 19 | X | X | | | X
483 20 | | | X | | X
484 21 | X | | X | | X
485 22 | | X | X | | X
486 23 | X | X | X | | X
487 24 | | | | X | X
488 25 | X | | | X | X
489 26 | | X | | X | X
490 27 | X | X | | X | X
491 28 | | | X | X | X
492 29 | X | | X | X | X
493 30 | | X | X | X | X
494 31 | X | X | X | X | X
495 --vtop virtual_address
498 This option is useful, when user debugs the translation problem
499 of virtual address. If specifing virtual_address, its physical
500 address is printed. It makes debugging easy by comparing the
501 output of this option with the one of "vtop" subcommand of the
502 crash utility. "--vtop" option only prints the translation out‐
503 put, and it does not affect the dumpfile creation.
504 --dump-dmesg
507 This option overrides the normal behavior of makedumpfile. In‐
508 stead of compressing and filtering a VMCORE to make it smaller,
509 it simply extracts the dmesg log from a VMCORE and writes it to
510 the specified LOGFILE. If a VMCORE does not contain VMCOREINFO
511 for dmesg, it is necessary to specfiy [-x VMLINUX] or [-i VMCOR‐
512 EINFO].
513 Example:
515 # makedumpfile --dump-dmesg /proc/vmcore dmesgfile
516 # makedumpfile --dump-dmesg -x vmlinux /proc/vmcore dmesgfile
517 --partial-dmesg
521 This option will make --dump-dmesg extract only dmesg logs since
522 that buffer was last cleared on the crashed kernel, through
523 "dmesg --clear" for example.
524 --mem-usage
528 This option is currently supported on x86_64, arm64, ppc64 and
529 s390x. This option is used to show the page numbers of current
530 system in different use. It should be executed in 1st kernel. By
531 the help of this, user can know how many pages is dumpable when
532 different dump_level is specified. It analyzes the 'System Ram'
533 and 'kernel text' program segment of /proc/kcore excluding the
534 crashkernel range, then calculates the page number of different
535 kind per vmcoreinfo. So currently /proc/kcore need be specified
536 explicitly.
537 Example:
539 # makedumpfile --mem-usage /proc/kcore
540 --diskset=VMCORE
544 Specify multiple VMCOREs created on sadump diskset configuration
545 the same number of times as the number of VMCOREs in increasing
546 order from left to right. VMCOREs are assembled into a single
547 DUMPFILE.
548 Example:
550 # makedumpfile -x vmlinux --diskset=vmcore1 --diskset=vmcore2
551 dumpfile
552 -D Print debugging message.
555 -h (--help)
558 Show help message and LZO/snappy support status (enabled/dis‐
559 abled).
560 -v Show the version of makedumpfile.
563 --check-params
566 Only check whether the command-line parameters are valid or not,
567 and exit. Preferable to be given as the first parameter.
568 --dry-run
571 Do not write the output dump file while still performing opera‐
572 tions specified by other options. This option cannot be used
573 with the --dump-dmesg, --reassemble and -g options.
574 --show-stats
577 Display report messages. This is an alternative to enabling bit
578 4 in the level provided to --message-level.
579
582 TMPDIR This environment variable is used in 1st kernel environment for
583 a temporary memory bitmap file. If your machine has a lots of
584 memory and you use small tmpfs on /tmp, makedumpfile can fail
585 for a little memory because makedumpfile makes a very large
586 temporary memory bitmap file in this case. To avoid this fail‐
587 ure, you should specify --work-dir option to use file system on
588 storage for the bitmap file.
589
592 makedumpfile exits with the following value.
593 0 : makedumpfile succeeded.
595 1 : makedumpfile failed without the following reasons.
597 2 : makedumpfile failed due to the different version between VMLINUX
599 and VMCORE.
600
603 Written by Masaki Tachibana, and Ken'ichi Ohmichi.
604
607 crash(8), gdb(1), kexec(8), makedumpfile.conf(5)
608makedumpfile v1.7.0 8 Nov 2021 MAKEDUMPFILE(8)