163 lines
4.9 KiB
Groff
163 lines
4.9 KiB
Groff
|
.\"
|
||
|
|
.\" Copyright (c) 2007 Robert N. M. Watson
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions
|
||
|
|
.\" are met:
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
|
.\" notice(s), this list of conditions and the following disclaimer as
|
||
|
|
.\" the first lines of this file unmodified other than the possible
|
||
|
|
.\" addition of one or more copyright notices.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
.\" notice(s), this list of conditions and the following disclaimer in the
|
||
|
|
.\" documentation and/or other materials provided with the distribution.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
|
||
|
|
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||
|
|
.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
|
||
|
|
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||
|
|
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||
|
|
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||
|
|
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
|
||
|
|
.\" DAMAGE.
|
||
|
|
.\"
|
||
|
|
.\" $FreeBSD$
|
||
|
|
.\"
|
||
|
|
.Dd 16 December, 2007
|
||
|
|
.Dt textdump 4
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm textdump
|
||
|
|
.Nd textdump kernel dumping facility
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.Cd options KDB
|
||
|
|
.Cd options DDB
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
facility allows the capture of kernel debugging information to disk in a
|
||
|
|
human-readable rather than the machine-readable form normally used with
|
||
|
|
kernel memory dumps and minidumps.
|
||
|
|
This representation, while less complete in that it does not capture full
|
||
|
|
kernel state, can provide debugging information in a more compact, portable,
|
||
|
|
and persistent form than a traditional dump.
|
||
|
|
By combining
|
||
|
|
.Nm
|
||
|
|
with other
|
||
|
|
.Xr DDB 4
|
||
|
|
facilities, such as scripting and output capture, detailed bug information
|
||
|
|
can be captured in a fully automated manner.
|
||
|
|
.Sh FORMAT
|
||
|
|
.Nm
|
||
|
|
data is stored in a dump partition in the same style as a regular memory
|
||
|
|
dump, and will be automatically extracted by
|
||
|
|
.Xr savecore 8
|
||
|
|
if present on boot.
|
||
|
|
.Pp
|
||
|
|
.Nm
|
||
|
|
files are stored in the
|
||
|
|
.Xr tar 5
|
||
|
|
format, and consist of one or more text files, each storing a particular type
|
||
|
|
of debugging output.
|
||
|
|
The following parts may be present:
|
||
|
|
.Bl -tag -width version.txt
|
||
|
|
.It Pa ddb.txt
|
||
|
|
Captured
|
||
|
|
.Xr DDB 4
|
||
|
|
output, if the capture facility has been used.
|
||
|
|
May be disabled by clearing the
|
||
|
|
.Dv debug.ddb.textdump.do_ddb
|
||
|
|
sysctl.
|
||
|
|
.It Pa config.txt
|
||
|
|
Kernel configuration, if
|
||
|
|
.Od options INCLUDE_CONFIG_FILE
|
||
|
|
has been compiled into the kernel.
|
||
|
|
May be disabled by clearing the
|
||
|
|
.Dv debug.ddb.textdump.do_config
|
||
|
|
sysctl.
|
||
|
|
.It Pa msgbuf.txt
|
||
|
|
Kernel message buffer, including recent console output if the capture
|
||
|
|
facility has been used.
|
||
|
|
May be disabled by clearing the
|
||
|
|
.Dv debug.ddb.textdump.do_msgbuf
|
||
|
|
sysctl.
|
||
|
|
.It Pa panic.txt
|
||
|
|
Kernel panic string, if the kernel panicked before the dump was generated.
|
||
|
|
May be disabled by clearing the
|
||
|
|
.Dv debug.ddb.textdump.do_panic
|
||
|
|
sysctl.
|
||
|
|
.It Pa version.txt
|
||
|
|
Kernel version string.
|
||
|
|
My be disabled by clearing the
|
||
|
|
.Dv dbeug.ddb.textdump.do_panic
|
||
|
|
sysctl.
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Kernel textdumps may be extracted using
|
||
|
|
.Xr bsdtar 1 .
|
||
|
|
.Sh CONFIGURATION
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
facility is enabled as part of the kernel debugger using
|
||
|
|
.Cd options KDB
|
||
|
|
and
|
||
|
|
.Cd options DDB .
|
||
|
|
By default, kernel dumps generated on panic or via explicit requests for a
|
||
|
|
dump will be regular memory dumps; however, by using the
|
||
|
|
.Ic textdump set
|
||
|
|
command in
|
||
|
|
.Xr DDB 4 ,
|
||
|
|
or by setting the
|
||
|
|
.Dv debug.ddb.textdump.pending
|
||
|
|
sysctl to 1 using
|
||
|
|
.Xr sysctl 8,
|
||
|
|
it is possible to request that the next dump be a textdump.
|
||
|
|
.Pp
|
||
|
|
If at the
|
||
|
|
.Xr DDB 4
|
||
|
|
command line, the commands
|
||
|
|
.Ic textdump set ,
|
||
|
|
.Ic textdump status ,
|
||
|
|
and
|
||
|
|
.Ic textdump unset
|
||
|
|
may be used to set, query, and clear the textdump pending flag.
|
||
|
|
.Pp
|
||
|
|
As with regular kernel dumps, a dump partition must be automatically or
|
||
|
|
manually configured using
|
||
|
|
.Xr dumpon 8 .
|
||
|
|
.Sh EXAMPLES
|
||
|
|
In the following example, the script
|
||
|
|
.Dv kdb.enter.panic
|
||
|
|
will run when the kernel debugger is entered as a result of a panic, enable
|
||
|
|
output capture, dump several useful pieces of debugging information, and then
|
||
|
|
invoke panic in order to force a kernel dump to be written out followed by a
|
||
|
|
reboot:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
script kdb.enter.panic=capture on;textdump set;bt;show allpcpu;
|
||
|
|
ps;alltrace;show alllock;panic
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
In the following example, the script
|
||
|
|
.Dv kdb.enter.witness
|
||
|
|
will run when the kernel debugger is entered as a result of a witness
|
||
|
|
violation, printing lock-related information for the user:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
script kdb.enter.witness=show locks
|
||
|
|
.Ed
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr bsdtar 1 ,
|
||
|
|
.Xr ddb 4 ,
|
||
|
|
.Xr tar 5 ,
|
||
|
|
.Xr dumpon 8 ,
|
||
|
|
.Xr savecore 8 ,
|
||
|
|
.Xr sysctl 8
|
||
|
|
.Sh AUTHORS
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
facility was created by
|
||
|
|
.An Robert N. M. Watson .
|