share/man/man4/textdump.4

   1 .\"
   2 .\" Copyright (c) 2007 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice(s), this list of conditions and the following disclaimer as
  10 .\"    the first lines of this file unmodified other than the possible
  11 .\"    addition of one or more copyright notices.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice(s), this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  20 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  22 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  23 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  26 .\" DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd December 24, 2008
  31 .Dt TEXTDUMP 4
  32 .Os
  33 .Sh NAME
  34 .Nm textdump
  35 .Nd textdump kernel dumping facility
  36 .Sh SYNOPSIS
  37 .Cd options KDB
  38 .Cd options DDB
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 facility allows the capture of kernel debugging information to disk in a
  43 human-readable rather than the machine-readable form normally used with
  44 kernel memory dumps and minidumps.
  45 This representation, while less complete in that it does not capture full
  46 kernel state, can provide debugging information in a more compact, portable,
  47 and persistent form than a traditional dump.
  48 By combining
  49 .Nm
  50 with other
  51 .Xr ddb 4
  52 facilities, such as scripting and output capture, detailed bug information
  53 can be captured in a fully automated manner.
  54 .Sh FORMAT
  55 .Nm
  56 data is stored in a dump partition in the same style as a regular memory
  57 dump, and will be automatically extracted by
  58 .Xr savecore 8
  59 if present on boot.
  60 .Pp
  61 .Nm
  62 files are stored in the
  63 .Xr tar 5
  64 format, and consist of one or more text files, each storing a particular type
  65 of debugging output.
  66 The following parts may be present:
  67 .Bl -tag -width version.txt
  68 .It Pa ddb.txt
  69 Captured
  70 .Xr ddb 4
  71 output, if the capture facility has been used.
  72 May be disabled by clearing the
  73 .Dv debug.ddb.textdump.do_ddb
  74 sysctl.
  75 .It Pa config.txt
  76 Kernel configuration, if
  77 .Cd options INCLUDE_CONFIG_FILE
  78 has been compiled into the kernel.
  79 May be disabled by clearing the
  80 .Dv debug.ddb.textdump.do_config
  81 sysctl.
  82 .It Pa msgbuf.txt
  83 Kernel message buffer, including recent console output if the capture
  84 facility has been used.
  85 May be disabled by clearing the
  86 .Dv debug.ddb.textdump.do_msgbuf
  87 sysctl.
  88 .It Pa panic.txt
  89 Kernel panic string, if the kernel panicked before the dump was generated.
  90 May be disabled by clearing the
  91 .Dv debug.ddb.textdump.do_panic
  92 sysctl.
  93 .It Pa version.txt
  94 Kernel version string.
  95 My be disabled by clearing the
  96 .Dv debug.ddb.textdump.do_version
  97 sysctl.
  98 .El
  99 .Pp
 100 Kernel textdumps may be extracted using
 101 .Xr tar 1 .
 102 .Sh CONFIGURATION
 103 The
 104 .Nm
 105 facility is enabled as part of the kernel debugger using
 106 .Cd options KDB
 107 and
 108 .Cd options DDB .
 109 By default, kernel dumps generated on panic or via explicit requests for a
 110 dump will be regular memory dumps; however, by using the
 111 .Ic textdump set
 112 command in
 113 .Xr ddb 4 ,
 114 or by setting the
 115 .Dv debug.ddb.textdump.pending
 116 sysctl to 1 using
 117 .Xr sysctl 8 ,
 118 it is possible to request that the next dump be a textdump.
 119 .Pp
 120 If at the
 121 .Xr ddb 4
 122 command line, the commands
 123 .Ic textdump set ,
 124 .Ic textdump status ,
 125 and
 126 .Ic textdump unset
 127 may be used to set, query, and clear the textdump pending flag.
 128 .Pp
 129 As with regular kernel dumps, a dump partition must be automatically or
 130 manually configured using
 131 .Xr dumpon 8 .
 132 .Sh EXAMPLES
 133 In the following example, the script
 134 .Dv kdb.enter.panic
 135 will run when the kernel debugger is entered as a result of a panic, enable
 136 output capture, dump several useful pieces of debugging information, and then
 137 invoke panic in order to force a kernel dump to be written out followed by a
 138 reboot:
 139 .Bd -literal -offset indent
 140 script kdb.enter.panic=textdump set; capture on; show allpcpu; bt;
 141   ps; alltrace; show alllocks; call doadump; reset
 142 .Ed
 143 .Pp
 144 In the following example, the script
 145 .Dv kdb.enter.witness
 146 will run when the kernel debugger is entered as a result of a witness
 147 violation, printing lock-related information for the user:
 148 .Bd -literal -offset indent
 149 script kdb.enter.witness=show locks
 150 .Ed
 151 .Pp
 152 These scripts may also be configured using the
 153 .Xr ddb 8
 154 utility.
 155 .Sh SEE ALSO
 156 .Xr tar 1 ,
 157 .Xr ddb 4 ,
 158 .Xr tar 5 ,
 159 .Xr ddb 8 ,
 160 .Xr dumpon 8 ,
 161 .Xr savecore 8 ,
 162 .Xr sysctl 8
 163 .Sh HISTORY
 164 The
 165 .Nm
 166 facility first appeared in
 167 .Fx 7.1 .
 168 .Sh AUTHORS
 169 The
 170 .Nm
 171 facility was created by
 172 .An Robert N. M. Watson .