bionic (5) minicoredumper.recept.json.5.gz

Provided by: minicoredumper_2.0.0-3_amd64 bug

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
       }

SEE ALSO

       minicoredumper(1),         libminicoredumper(7),        minicoredumper.cfg.json(5),        coreinject(1),
       minicoredumper_regd(1)

       The DiaMon Workgroup: <http://www.diamon.org>