minicoredumper

NAME

minicoredumper.recept.json - a recept file used by the minicoredumper(1)

DESCRIPTION

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).

FILE FORMAT

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).

STACKS

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).

MAPS

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.

BUFFERS

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.

COMPRESSION

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.

NOTES

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.

EXAMPLE

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
}