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
41 VMCORE to DUMPFILE, and a user can choose which type of pages will be
42 excluded.
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
62 addresses and its sizes after processing filter commands. The memory
63 locations that require to be filtered out are then poisoned with char‐
64 acter '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.
70 --eppic requires eppic_makedumpfile.so and eppic library. eppic_make‐
71 dumpfile.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
83 VMCOREINFO 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
114 VMCOREs created on diskset configuration, you need to use --diskset
115 option.
116
119 -c,-l,-p
120 Compress dump data by each page using zlib for -c option, lzo
121 for -l option or snappy for -p option. (-l option needs
122 USELZO=on and -p option needs USESNAPPY=on when building)
123 A user cannot specify this option with -E option, because the
124 ELF format does not support compressed data.
125 Example:
126 # makedumpfile -c -d 31 -x vmlinux /proc/vmcore dumpfile
127 -d dump_level
130 Specify the type of unnecessary page for analysis.
131 Pages of the specified type are not copied to DUMPFILE. The page
132 type marked in the following table is excluded. A user can spec‐
133 ify multiple page types by setting the sum of each page type for
134 dump_level. The maximum of dump_level is 31. Note that a
135 dump_level for Xen dump filtering is 0 or 1 on a machine other
136 than x86_64. On a x86_64 machine, even 2 or bigger dump level
137 will be effective if you specify domain-0's vmlinux with -x
138 option. Then the pages are excluded only from domain-0.
139 If specifying multiple dump_levels with the delimiter ',', make‐
140 dumpfile retries to create a DUMPFILE by other dump_level when
141 "No space on device" error happens. For example, if dump_level
142 is "11,31" and makedumpfile fails by dump_level 11, makedumpfile
143 retries it by dump_level 31.
144 Example:
145 # makedumpfile -d 11 -x vmlinux /proc/vmcore dumpfile
146 # makedumpfile -d 11,31 -x vmlinux /proc/vmcore dumpfile
147 Base level:
148 dump_level consists of five bits, so there are five base levels
149 to specify the type of unnecessary page.
150 1 : Exclude the pages filled with zero.
151 2 : Exclude the non-private cache pages.
152 4 : Exclude all cache pages.
153 8 : Exclude the user process data pages.
154 16 : Exclude the free pages.
155 Here is the all combinations of the bits.
157 | |non- | | |
159 dump | zero |private|private| user | free
160 level | page |cache |cache | data | page
161 -------+------+-------+-------+------+------
162 0 | | | | |
163 1 | X | | | |
164 2 | | X | | |
165 3 | X | X | | |
166 4 | | X | X | |
167 5 | X | X | X | |
168 6 | | X | X | |
169 7 | X | X | X | |
170 8 | | | | X |
171 9 | X | | | X |
172 10 | | X | | X |
173 11 | X | X | | X |
174 12 | | X | X | X |
175 13 | X | X | X | X |
176 14 | | X | X | X |
177 15 | X | X | X | X |
178 16 | | | | | X
179 17 | X | | | | X
180 18 | | X | | | X
181 19 | X | X | | | X
182 20 | | X | X | | X
183 21 | X | X | X | | X
184 22 | | X | X | | X
185 23 | X | X | X | | X
186 24 | | | | X | X
187 25 | X | | | X | X
188 26 | | X | | X | X
189 27 | X | X | | X | X
190 28 | | X | X | X | X
191 29 | X | X | X | X | X
192 30 | | X | X | X | X
193 31 | X | X | X | X | X
194 -E Create DUMPFILE in the ELF format.
198 This option cannot be specified with the -c, -l or -p options,
199 because the ELF format does not support compressed data.
200 Example:
201 # makedumpfile -E -d 31 -x vmlinux /proc/vmcore dumpfile
202 -f Force existing DUMPFILE to be overwritten and mem-usage to work
205 with older kernel as well.
206 Example:
207 # makedumpfile -f -d 31 -x vmlinux /proc/vmcore dumpfile
208 This command overwrites DUMPFILE even if it already exists.
209 # makedumpfile -f --mem-usage /proc/kcore
210 Kernel version lesser than v4.11 will not work with --mem-usage
211 functionality until it has been patched with upstream commit
212 464920104bf7. Therefore if you have patched your older kernel
213 then use -f.
214 -x VMLINUX
217 Specify the first kernel's VMLINUX with debug information to
218 analyze the first kernel's memory usage.
219 This option is necessary if VMCORE does not contain VMCOREINFO,
220 [-i VMCOREINFO] is not specified, and dump_level is 2 or more.
221 The page size of the first kernel and the second kernel should
222 match.
223 Example:
224 # makedumpfile -d 31 -x vmlinux /proc/vmcore dumpfile
225 -i VMCOREINFO
228 Specify VMCOREINFO instead of VMLINUX for analyzing the first
229 kernel's memory usage.
230 VMCOREINFO should be made beforehand by makedumpfile with -g
231 option, and it contains the first kernel's information.
232 This option is necessary if VMCORE does not contain VMCOREINFO,
233 [-x VMLINUX] is not specified, and dump_level is 2 or more.
234 Example:
235 # makedumpfile -d 31 -i vmcoreinfo /proc/vmcore dumpfile
236 -g VMCOREINFO
239 Generate VMCOREINFO from the first kernel's VMLINUX with debug
240 information.
241 VMCOREINFO must be generated on the system that is running the
242 first kernel. With -i option, a user can specify VMCOREINFO gen‐
243 erated on the other system that is running the same first ker‐
244 nel. [-x VMLINUX] must be specified.
245 Example:
246 # makedumpfile -g vmcoreinfo -x vmlinux
247 --config FILTERCONFIGFILE
250 Used in conjunction with -x VMLINUX option, to specify the fil‐
251 ter config file FILTERCONFIGFILE that contains erase commands to
252 filter out desired kernel data from vmcore while creating DUMP‐
253 FILE. For filter command syntax please refer to makedump‐
254 file.conf(5).
255 --eppic EPPICMACRO
258 Used in conjunction with -x VMLINUX option, to specify the eppic
259 macro file that contains filter rules or directory that contains
260 eppic macro files to filter out desired kernel data from vmcore
261 while creating DUMPFILE. When directory is specified, all the
262 eppic macros in the directory are processed.
263 -F Output the dump data in the flattened format to the standard
266 output for transporting the dump data by SSH.
267 Analysis tools (crash utility before version 5.1.2 or GDB) can‐
268 not read the flattened format directly. For analysis, the dump
269 data in the flattened format should be rearranged to a normal
270 DUMPFILE (readable with analysis tools) by -R option. By which
271 option is specified with -F option, the format of the rearranged
272 DUMPFILE is fixed. In other words, it is impossible to specify
273 the DUMPFILE format when the dump data is rearranged with -R
274 option. If specifying -E option with -F option, the format of
275 the rearranged DUMPFILE is the ELF format. Otherwise, it is the
276 kdump-compressed format. All the messages are output to standard
277 error output by -F option because standard output is used for
278 the dump data.
279 Example:
280 # makedumpfile -F -c -d 31 -x vmlinux /proc/vmcore \
281 | ssh user@host "cat > dumpfile.tmp"
282 # makedumpfile -F -c -d 31 -x vmlinux /proc/vmcore \
283 | ssh user@host "makedumpfile -R dumpfile"
284 # makedumpfile -F -E -d 31 -i vmcoreinfo /proc/vmcore \
285 | ssh user@host "makedumpfile -R dumpfile"
286 # makedumpfile -F -E --xen-vmcoreinfo VMCOREINFO /proc/vmcore \
287 | ssh user@host "makedumpfile -R dumpfile"
288 -R Rearrange the dump data in the flattened format from the stan‐
291 dard input to a normal DUMPFILE (readable with analysis tools).
292 Example:
293 # makedumpfile -R dumpfile < dumpfile.tmp
294 # makedumpfile -F -d 31 -x vmlinux /proc/vmcore \
295 | ssh user@host "makedumpfile -R dumpfile"
296 Instead of using -R option, a perl script "makedumpfile-R.pl"
298 rearranges the dump data in the flattened format to a normal
299 DUMPFILE, too. The perl script does not depend on architecture,
300 and most systems have perl command. Even if a remote host does
301 not have makedumpfile, it is possible to rearrange the dump data
302 in the flattened format to a readable DUMPFILE on a remote host
303 by running this script.
304 Example:
305 # makedumpfile -F -d 31 -x vmlinux /proc/vmcore \
306 | ssh user@host "makedumpfile-R.pl dumpfile"
307 --split
310 Split the dump data to multiple DUMPFILEs in parallel. If speci‐
311 fying DUMPFILEs on different storage devices, a device can share
312 I/O load with other devices and it reduces time for saving the
313 dump data. The file size of each DUMPFILE is smaller than the
314 system memory size which is divided by the number of DUMPFILEs.
315 This feature supports only the kdump-compressed format.
316 Example:
317 # makedumpfile --split -d 31 -x vmlinux /proc/vmcore dumpfile1
318 dumpfile2
319 --num-threads THREADNUM
322 Using multiple threads to read and compress data of each page in
323 parallel. And it will reduces time for saving DUMPFILE. Note
324 that if the usable cpu number is less than the thread number, it
325 may lead to great performance degradation. This feature only
326 supports creating DUMPFILE in kdump-comressed format from VMCORE
327 in kdump-compressed format or elf format.
328 Example:
329 # makedumpfile -d 31 --num-threads 4 /proc/vmcore dumpfile
330 --reassemble
333 Reassemble multiple DUMPFILEs, which are created by --split
334 option, into one DUMPFILE. dumpfile1 and dumpfile2 are reassem‐
335 bled into dumpfile on the following example.
336 Example:
337 # makedumpfile --reassemble dumpfile1 dumpfile2 dumpfile
338 -b <order>
341 Cache 2^order pages in ram when generating DUMPFILE before writ‐
342 ing to output. The default value is 4.
343 --cyclic-buffer buffer_size
346 Specify the buffer size in kilo bytes for bitmap data. Filter‐
347 ing processing will be divided into multi cycles to fix the mem‐
348 ory consumption, the number of cycles is represented as:
349 num_of_cycles = system_memory / (buffer_size * 1024 *
351 bit_per_bytes * page_size )
352 The lesser number of cycles, the faster working speed is
354 expected. By default, buffer_size will be calculated automati‐
355 cally depending on system memory size, so ordinary users don't
356 need to specify this option.
357 Example:
359 # makedumpfile --cyclic-buffer 1024 -d 31 -x vmlinux
360 /proc/vmcore dumpfile
361 --splitblock-size splitblock_size
364 Specify the splitblock size in kilo bytes for analysis with
365 --split. If --splitblock N is specified, difference of each
366 splitted dumpfile size is at most N kilo bytes.
367 Example:
368 # makedumpfile --splitblock-size 1024 -d 31 -x vmlinux --split
369 /proc/vmcore dumpfile1 dumpfile2
370 --work-dir
374 Specify the working directory for the temporary bitmap file. If
375 this option isn't specified, the bitmap will be saved on memory.
376 Filtering processing has to do 2 pass scanning to fix the memory
377 consumption, but it can be avoided by using working directory on
378 file system. So if you specify this option, the filtering speed
379 may be bit faster.
380 Example:
382 # makedumpfile --work-dir /tmp -d 31 -x vmlinux /proc/vmcore
383 dumpfile
384 --non-mmap
387 Never use mmap(2) to read VMCORE even if it supports mmap(2).
388 Generally, reading VMCORE with mmap(2) is faster than without
389 it, so ordinary users don't need to specify this option. This
390 option is mainly for debugging.
391 Example:
392 # makedumpfile --non-mmap -d 31 -x vmlinux /proc/vmcore dumpfile
393 --xen-syms XEN-SYMS
396 Specify the XEN-SYMS with debug information to analyze the xen's
397 memory usage. This option extracts the part of xen and
398 domain-0.
399 Example:
400 # makedumpfile -E --xen-syms xen-syms /proc/vmcore dumpfile
401 --xen-vmcoreinfo VMCOREINFO
404 Specify VMCOREINFO instead of XEN-SYMS for analyzing the xen's
405 memory usage.
406 VMCOREINFO should be made beforehand by makedumpfile with -g
407 option, and it contains the xen's information.
408 Example:
409 # makedumpfile -E --xen-vmcoreinfo VMCOREINFO /proc/vmcore dump‐
410 file
411 -X Exclude all the user domain pages from Xen kdump's VMCORE, and
414 extracts the part of xen and domain-0. If VMCORE contains VMCOR‐
415 EINFO for Xen, it is not necessary to specify --xen-syms and
416 --xen-vmcoreinfo.
417 Example:
418 # makedumpfile -E -X /proc/vmcore dumpfile
419 --xen_phys_start xen_phys_start_address
422 This option is only for x86_64. Specify the
423 xen_phys_start_address, if the xen code/data is relocatable and
424 VMCORE does not contain xen_phys_start_address in the CRASHINFO.
425 xen_phys_start_address can be taken from the line of "Hypervisor
426 code and data" in /proc/iomem. For example, specify 0xcee00000
427 as xen_phys_start_address if /proc/iomem is the following:
428 -------------------------------------------------------
429 # cat /proc/iomem
430 ...
431 cee00000-cfd99999 : Hypervisor code and data
432 ...
433 -------------------------------------------------------
434 Example:
436 # makedumpfile -E -X --xen_phys_start 0xcee00000 /proc/vmcore
437 dumpfile
438 --message-level message_level
441 Specify the message types.
442 Users can restrict outputs printed by specifying message_level
443 with this option. The message type marked with an X in the fol‐
444 lowing table is printed. For example, according to the table,
445 specifying 7 as message_level means progress indicator, common
446 message, and error message are printed, and this is a default
447 value. Note that the maximum value of message_level is 31.
448 message | progress | common | error | debug | report
450 level | indicator| message | message | message | message
451 ---------+----------+---------+---------+---------+---------
452 0 | | | | |
453 1 | X | | | |
454 2 | | X | | |
455 3 | X | X | | |
456 4 | | | X | |
457 5 | X | | X | |
458 6 | | X | X | |
459 * 7 | X | X | X | |
460 8 | | | | X |
461 9 | X | | | X |
462 10 | | X | | X |
463 11 | X | X | | X |
464 12 | | | X | X |
465 13 | X | | X | X |
466 14 | | X | X | X |
467 15 | X | X | X | X |
468 16 | | | | | X
469 17 | X | | | | X
470 18 | | X | | | X
471 19 | X | X | | | X
472 20 | | | X | | X
473 21 | X | | X | | X
474 22 | | X | X | | X
475 23 | X | X | X | | X
476 24 | | | | X | X
477 25 | X | | | X | X
478 26 | | X | | X | X
479 27 | X | X | | X | X
480 28 | | | X | X | X
481 29 | X | | X | X | X
482 30 | | X | X | X | X
483 31 | X | X | X | X | X
484 --vtop virtual_address
487 This option is useful, when user debugs the translation problem
488 of virtual address. If specifing virtual_address, its physical
489 address is printed. It makes debugging easy by comparing the
490 output of this option with the one of "vtop" subcommand of the
491 crash utility. "--vtop" option only prints the translation out‐
492 put, and it does not affect the dumpfile creation.
493 --dump-dmesg
496 This option overrides the normal behavior of makedumpfile.
497 Instead of compressing and filtering a VMCORE to make it
498 smaller, it simply extracts the dmesg log from a VMCORE and
499 writes it to the specified LOGFILE. If a VMCORE does not contain
500 VMCOREINFO for dmesg, it is necessary to specfiy [-x VMLINUX] or
501 [-i VMCOREINFO].
502 Example:
504 # makedumpfile --dump-dmesg /proc/vmcore dmesgfile
505 # makedumpfile --dump-dmesg -x vmlinux /proc/vmcore dmesgfile
506 --partial-dmesg
510 This option will make --dump-dmesg extract only dmesg logs since
511 that buffer was last cleared on the crashed kernel, through
512 "dmesg --clear" for example.
513 --mem-usage
517 This option is currently supported on x86_64, arm64, ppc64 and
518 s390x. This option is used to show the page numbers of current
519 system in different use. It should be executed in 1st kernel. By
520 the help of this, user can know how many pages is dumpable when
521 different dump_level is specified. It analyzes the 'System Ram'
522 and 'kernel text' program segment of /proc/kcore excluding the
523 crashkernel range, then calculates the page number of different
524 kind per vmcoreinfo. So currently /proc/kcore need be specified
525 explicitly.
526 Example:
528 # makedumpfile --mem-usage /proc/kcore
529 --diskset=VMCORE
533 Specify multiple VMCOREs created on sadump diskset configuration
534 the same number of times as the number of VMCOREs in increasing
535 order from left to right. VMCOREs are assembled into a single
536 DUMPFILE.
537 Example:
539 # makedumpfile -x vmlinux --diskset=vmcore1 --diskset=vmcore2
540 dumpfile
541 -D Print debugging message.
544 -h (--help)
547 Show help message and LZO/snappy support status (enabled/dis‐
548 abled).
549 -v Show the version of makedumpfile.
552 --check-params
555 Only check whether the command-line parameters are valid or not,
556 and exit. Preferable to be given as the first parameter.
557
560 TMPDIR This environment variable is used in 1st kernel environment for
561 a temporary memory bitmap file. If your machine has a lots of
562 memory and you use small tmpfs on /tmp, makedumpfile can fail
563 for a little memory because makedumpfile makes a very large
564 temporary memory bitmap file in this case. To avoid this fail‐
565 ure, you should specify --work-dir option to use file system on
566 storage for the bitmap file.
567
570 makedumpfile exits with the following value.
571 0 : makedumpfile succeeded.
573 1 : makedumpfile failed without the following reasons.
575 2 : makedumpfile failed due to the different version between VMLINUX
577 and VMCORE.
578
581 Written by Masaki Tachibana, and Ken'ichi Ohmichi.
582
585 crash(8), gdb(1), kexec(8), makedumpfile.conf(5)
586makedumpfile v1.6.7 16 Jan 2020 MAKEDUMPFILE(8)