A recept configuration file defines the dump behavior of the
minicoredumper(1). minicoredumper.recept.json is a sample
recept file name. The actual name depends on the recept option in the
main configuration file minicoredumper.cfg.json(5).
The file uses the JSON format. The options are:
- stacks
- (list) A set of options specifying how and which stacks are to be dumped.
See STACKS for details about the available options.
- maps
- (list) A set of options specifying shared objects, whose virtual memory
areas should also be dumped. See MAPS for details about the
available options.
- buffers
- (array) A set of buffers, each specifying global data within the
application that should also be dumped. See BUFFERS for
configuration options for a buffer.
- compression
- (list) A set of options specifying if and what type of compression should
be used for the core(5) file. See COMPRESSION for details
about the available options.
- dump_auxv_so_list
- (boolean) Whether the shared object list should be dumped. This is used by
gdb(1) to determine which shared objects were linked and to which
address they were mapped.
- dump_pthread_list
- (boolean) Whether the pthread list should be dumped. This is used by
gdb(1) to identify and iterate through all the threads.
- dump_robust_mutex_list
- (boolean) Whether the list of robust mutexes should be dumped. This is
used by gdb(1) to identify mutex attributes and states in shared
memory.
- dump_scope
- (integer) Only registered dumps at or below this value will be
dumped.
- live_dumper
- (boolean) Whether the minicoredumper(1) should trigger all
registered libminicoredumper(7) applications when a dump
occurs.
- write_proc_info
- (boolean) Whether interesting /proc files should be copied to the dump
directory.
- write_debug_log
- (boolean) Whether minicoredumper(1) messages should be logged to
"debug.txt" in the dump directory. This is particularly useful
if syslog(3) is not available on the system.
- dump_fat_core
- (boolean) Whether all virtual memory areas should be dumped. This will
generate a separate "fatcore" file that is typically larger than
the default Linux core(5) files. This is really only useful for
debugging minicoredumper(1).
The stacks option specifies a set of options related to
dumping stacks. The options are:
- dump_stacks
- (boolean) Whether stack dumping should occur. If this option is false, all
other stacks options are ignored.
- first_thread_only
- (boolean) Whether only the stack of the crashing thread should be
dumped.
- max_stack_size
- (integer) The maximum stack size in bytes to dump. 0 for no limit.
The minicoredumper(1) only dumps the actual used part of a
stack area. If a stack is truncated because of the max_stack_size
option, the bottommost part of the used stack is dumped (i.e. the part of
the stack that includes the function that caused the core dump).
The maps option specifies a set of options for shared
objects, whose virtual memory areas should also be dumped. This is useful if
the shared objects maintain their own static off-stack data that will be
required during debugging. The options are:
- dump_by_name
- (array of strings) Shared object names to be dumped. The names can contain
the * character for wildcard matching.
Although not critical, gdb(1) often tries to access data
from the "[vdso]" virtual shared object. If this is not dumped,
gdb(1) may complain with the warning:
Failed to read a valid object file image from
memory.
The buffers option specifies an array of buffers, with each
buffer specifying global data within the application that should also be
dumped. The options for each specified buffer are:
- symname
- (string) The name of the global variable/symbol.
- follow_ptr
- (boolean) Whether the global variable is a pointer and the data pointed to
by that pointer should be dumped.
- data_len
- (integer) The size of the global variable in bytes. If follow_ptr
is true, this is the size of the data pointed to.
- ident
- (string) An optional string to identify the binary dump later. This
corresponds to the ident argument of the
mcd_dump_data_register_bin(3) function of
libminicoredumper(7). It must be unique! If specified, the data
will be dumped to an external file named ident instead of the
core(5) file. This data can be inserted into the core(5)
file later using the coreinject(1) tool.
The compression option specifies a set of options related
to compression of the core(5) file. The options are:
- compressor
- (string) Use a compressor to compress the core(5) file. The
compressor must support stdin as input and stdout as output. Examples of
such compressors are gzip(1), bzip2(1), xz(1),
cat(1). Either the full path to the compressor can be specified or
just the compressor filename if the compressor can be found in the default
search path. The uncompressed core(5) file and (if enabled) the
sparse tar archive are created in memory. Thus the compressor
option can be very useful if very limited dump space is available.
- extension
- (string) The file extension of the compressed tar archive. It is appended
to the filename "core.tar." as a convenience to the user. If not
specified, "compressed" will be appended.
- in_tar
- (boolean) Whether the core(5) file should be packed as a sparse
file into a tar(1) archive before being compressed. This preserves
the sparse properties of the core(5) file. If enabled, a
compressor must be specified.
The dump_auxv_so_list, dump_pthread_list,
dump_robust_mutex_list options should generally be set to true. They
provide important information to gdb(1) and require a relatively
small dump space.
Here is an example of a recept file:
{
"stacks": {
"dump_stacks": true,
"first_thread_only": true,
"max_stack_size": 16384
},
"maps": {
"dump_by_name": [
"*my_lib_to_debug*so*",
"[vdso]"
]
},
"buffers": [
{
"symname": "my_allocated_struct",
"follow_ptr": true,
"data_len": 42
},
{
"symname": "my_short",
"follow_ptr": false,
"data_len": 2,
"ident": "my_short_data.bin"
}
],
"compression": {
"compressor": "gzip",
"extension": "gz",
"in_tar": true
},
"dump_auxv_so_list": true,
"dump_pthread_list": true,
"dump_robust_mutex_list": true,
"dump_scope": 8,
"live_dumper": false,
"write_proc_info": true,
"write_debug_log": false,
"dump_fat_core": false
}