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