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 DDB
  38 .Cd options KDB
  39 .Pp
  40 .Cd options TEXTDUMP_PREFERRED
  41 .Cd options TEXTDUMP_VERBOSE
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 facility allows the capture of kernel debugging information to disk in a
  46 human-readable rather than the machine-readable form normally used with
  47 kernel memory dumps and minidumps.
  48 This representation, while less complete in that it does not capture full
  49 kernel state, can provide debugging information in a more compact, portable,
  50 and persistent form than a traditional dump.
  51 By combining
  52 .Nm
  53 with other
  54 .Xr ddb 4
  55 facilities, such as scripting and output capture, detailed bug information
  56 can be captured in a fully automated manner.
  57 .Sh FORMAT
  58 .Nm
  59 data is stored in a dump partition in the same style as a regular memory
  60 dump, and will be automatically extracted by
  61 .Xr savecore 8
  62 if present on boot.
  63 .Pp
  64 .Nm
  65 files are stored in the
  66 .Xr tar 5
  67 format, and consist of one or more text files, each storing a particular type
  68 of debugging output.
  69 The following parts may be present:
  70 .Bl -tag -width version.txt
  71 .It Pa ddb.txt
  72 Captured
  73 .Xr ddb 4
  74 output, if the capture facility has been used.
  75 May be disabled by clearing the
  76 .Dv debug.ddb.textdump.do_ddb
  77 sysctl.
  78 .It Pa config.txt
  79 Kernel configuration, if
  80 .Cd options INCLUDE_CONFIG_FILE
  81 has been compiled into the kernel.
  82 May be disabled by clearing the
  83 .Dv debug.ddb.textdump.do_config
  84 sysctl.
  85 .It Pa msgbuf.txt
  86 Kernel message buffer, including recent console output if the capture
  87 facility has been used.
  88 May be disabled by clearing the
  89 .Dv debug.ddb.textdump.do_msgbuf
  90 sysctl.
  91 .It Pa panic.txt
  92 Kernel panic string, if the kernel panicked before the dump was generated.
  93 May be disabled by clearing the
  94 .Dv debug.ddb.textdump.do_panic
  95 sysctl.
  96 .It Pa version.txt
  97 Kernel version string.
  98 My be disabled by clearing the
  99 .Dv debug.ddb.textdump.do_version
 100 sysctl.
 101 .El
 102 .Pp
 103 Kernel textdumps may be extracted using
 104 .Xr tar 1 .
 105 .Sh CONFIGURATION
 106 The
 107 .Nm
 108 facility is enabled as part of the kernel debugger using
 109 .Cd options KDB
 110 and
 111 .Cd options DDB .
 112 By default, kernel dumps generated on panic or via explicit requests for a
 113 dump will be regular memory dumps; however, by using the
 114 .Ic textdump set
 115 command in
 116 .Xr ddb 4 ,
 117 or by setting the
 118 .Dv debug.ddb.textdump.pending
 119 sysctl to 1 using
 120 .Xr sysctl 8 ,
 121 it is possible to request that the next dump be a textdump.
 122 One may also directly trigger a textdump in
 123 .Xr ddb 4
 124 by running the command
 125 .Ic textdump dump .
 126 .Pp
 127 If at the
 128 .Xr ddb 4
 129 command line, the commands
 130 .Ic textdump set ,
 131 .Ic textdump status ,
 132 and
 133 .Ic textdump unset
 134 may be used to set, query, and clear the textdump pending flag.
 135 .Pp
 136 As with regular kernel dumps, a dump partition must be automatically or
 137 manually configured using
 138 .Xr dumpon 8 .
 139 .Pp
 140 Additional kernel
 141 .Xr config 8
 142 options:
 143 .Bl -tag -width TEXTDUMP_PREFERRED
 144 .It Cd TEXTDUMP_PREFERRED
 145 sets textdumps to be the default manner of doing dumps.
 146 This means there will be no need to
 147 .Xr sysctl 8
 148 or use the
 149 .Ic textdump set
 150 .Xr ddb 8
 151 commands.
 152 .It Cd TEXTDUMP_VERBOSE
 153 will have the textdump facility be more verbose about each file it is emitting
 154 as well as other diagnostics useful to debug the textdump facility itself.
 155 .El
 156 .Sh EXAMPLES
 157 In the following example, the script
 158 .Dv kdb.enter.panic
 159 will run when the kernel debugger is entered as a result of a panic, enable
 160 output capture, dump several useful pieces of debugging information, and then
 161 invoke panic in order to force a kernel dump to be written out followed by a
 162 reboot:
 163 .Bd -literal -offset indent
 164 script kdb.enter.panic=textdump set; capture on; show allpcpu; bt;
 165   ps; alltrace; show alllocks; call doadump; reset
 166 .Ed
 167 .Pp
 168 In the following example, the script
 169 .Dv kdb.enter.witness
 170 will run when the kernel debugger is entered as a result of a witness
 171 violation, printing lock-related information for the user:
 172 .Bd -literal -offset indent
 173 script kdb.enter.witness=show locks
 174 .Ed
 175 .Pp
 176 These scripts may also be configured using the
 177 .Xr ddb 8
 178 utility.
 179 .Sh SEE ALSO
 180 .Xr tar 1 ,
 181 .Xr ddb 4 ,
 182 .Xr tar 5 ,
 183 .Xr ddb 8 ,
 184 .Xr dumpon 8 ,
 185 .Xr savecore 8 ,
 186 .Xr sysctl 8
 187 .Sh HISTORY
 188 The
 189 .Nm
 190 facility first appeared in
 191 .Fx 7.1 .
 192 .Sh AUTHORS
 193 The
 194 .Nm
 195 facility was created by
 196 .An Robert N. M. Watson .