freebsd-dev/sbin/dumpon/dumpon.8

.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  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, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
.\"
.\"     From: @(#)swapon.8	8.1 (Berkeley) 6/5/93
.\" $FreeBSD$
.\"
.Dd April 29, 2013
.Dt DUMPON 8
.Os
.Sh NAME
.Nm dumpon
.Nd "specify a device for crash dumps"
.Sh SYNOPSIS
.Nm
.Op Fl v
.Ar special_file
.Nm
.Op Fl v
.Cm off
.Nm
.Op Fl v
.Fl l
.Sh DESCRIPTION
The
.Nm
utility is used to specify a device where the kernel can save a crash
dump in the case of a panic.
.Pp
Calls to
.Nm
normally occur from the system multi-user initialization file
.Pa /etc/rc ,
controlled by the
.Dq dumpdev
variable in the boot time configuration file
.Pa /etc/rc.conf .
.Pp
The default type of kernel crash dump is the mini crash dump.
Mini crash dumps hold only memory pages in use by the kernel.
Alternatively, full memory dumps can be enabled by setting the
.Va debug.minidump
.Xr sysctl 8
variable to 0.
.Pp
For systems using full memory dumps, the size of the specified dump
device must be at
least the size of physical memory.
Even though an additional 64 kB header is added to the dump, the BIOS for a
platform typically holds back some memory, so it is not usually
necessary to size the dump device larger than the actual amount of RAM
available in the machine.
Also, when using full memory dumps, the
.Nm
utility will refuse to enable a dump device which is smaller than the
total amount of physical memory as reported by the
.Va hw.physmem
.Xr sysctl 8
variable.
.Pp
The
.Fl l
flag causes
.Nm
to print the current dump device or _PATH_DEVNULL ("/dev/null") if no device is
configured.
.Pp
The
.Fl v
flag causes
.Nm
to be verbose about its activity.
.Sh IMPLEMENTATION NOTES
Since a
.Xr panic 9
condition may occur in a situation
where the kernel cannot trust its internal representation
of the state of any given file system,
one of the system swap devices,
and
.Em not
a device containing a file system,
should be used as the dump device.
.Pp
The
.Nm
utility operates by opening
.Ar special_file
and making a
.Dv DIOCSKERNELDUMP
.Xr ioctl 2
request on it to save kernel crash dumps.
If
.Ar special_file
is the text string:
.Dq Li off ,
.Nm
performs a
.Dv DIOCSKERNELDUMP
.Xr ioctl 2
on
.Pa /dev/null
and thus instructs the kernel not to save crash dumps.
.Sh FILES
.Bl -tag -width "/dev/{ad,da}?s?b" -compact
.It Pa /dev/{ad,da}?s?b
standard swap areas
.It Pa /etc/rc.conf
boot-time system configuration
.El
.Sh SEE ALSO
.Xr fstab 5 ,
.Xr rc.conf 5 ,
.Xr config 8 ,
.Xr init 8 ,
.Xr rc 8 ,
.Xr savecore 8 ,
.Xr swapon 8 ,
.Xr panic 9
.Sh HISTORY
The
.Nm
utility appeared in
.Fx 2.1 .
.Sh BUGS
Because the file system layer is already dead by the time a crash dump
is taken, it is not possible to send crash dumps directly to a file.
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.\" Copyright (c) 1980, 1991, 1993`
			`.\" The Regents of the University of California. 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, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
			`.\" 4. Neither the name of the University nor the names of its contributors`
			`.\" may be used to endorse or promote products derived from this software`
			`.\" without specific prior written permission.`
			`.\"`
			.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.`
			`.\"`
			`.\" From: @(#)swapon.8 8.1 (Berkeley) 6/5/93`
$Id$ -> $FreeBSD$ 1999-08-28 00:22:10 +00:00			`.\" $FreeBSD$`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.\"`
Adapt to the fact that minidumps are now on by default. PR: 177188 2013-04-30 07:22:03 +00:00			`.Dd April 29, 2013`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Dt DUMPON 8`
mdoc(7) police: removed HISTORY info from the .Os call. 2001-07-10 11:04:34 +00:00			`.Os`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Sh NAME`
			`.Nm dumpon`
			`.Nd "specify a device for crash dumps"`
			`.Sh SYNOPSIS`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 16:52:27 +00:00			`.Nm`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Op Fl v`
Correct manual page, based on feedback from Bruce Evans. Reviewed by: Bruce Evans <bde@freebsd.org> 1998-05-27 11:05:59 +00:00			`.Ar special_file`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 16:52:27 +00:00			`.Nm`
Correct manual page, based on feedback from Bruce Evans. Reviewed by: Bruce Evans <bde@freebsd.org> 1998-05-27 11:05:59 +00:00			`.Op Fl v`
`off' is a keyword, not a parameter name. Obtained from: DragonFly 2004-07-18 09:57:47 +00:00			`.Cm off`
Add an option to display the current dump device via dumpon -l. MFC after: 2 weeks 2012-11-01 18:59:19 +00:00			`.Nm`
Document that you can use -v along with -l. Noticed by: pjd 2012-11-02 17:30:08 +00:00			`.Op Fl v`
Add an option to display the current dump device via dumpon -l. MFC after: 2 weeks 2012-11-01 18:59:19 +00:00			`.Fl l`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Sh DESCRIPTION`
The .Nm utility 2002-07-06 19:34:18 +00:00			`The`
			`.Nm`
Wrap some long lines (no content changes) 2004-10-03 23:35:34 +00:00			`utility is used to specify a device where the kernel can save a crash`
			`dump in the case of a panic.`
Manual page fix: add cross references, refer to ``dumpdev'' variable in "/etc/rc.conf". PR: 6117 Submitted by: Mark Mayo <mark@vmunix.com> 1998-05-25 08:54:40 +00:00			`.Pp`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`Calls to`
Correct manual page, based on feedback from Bruce Evans. Reviewed by: Bruce Evans <bde@freebsd.org> 1998-05-27 11:05:59 +00:00			`.Nm`
			`normally occur from the system multi-user initialization file`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Pa /etc/rc ,`
Correct manual page, based on feedback from Bruce Evans. Reviewed by: Bruce Evans <bde@freebsd.org> 1998-05-27 11:05:59 +00:00			`controlled by the`
			`.Dq dumpdev`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`variable in the boot time configuration file`
Correct manual page, based on feedback from Bruce Evans. Reviewed by: Bruce Evans <bde@freebsd.org> 1998-05-27 11:05:59 +00:00			`.Pa /etc/rc.conf .`
			`.Pp`
Adapt to the fact that minidumps are now on by default. PR: 177188 2013-04-30 07:22:03 +00:00			`The default type of kernel crash dump is the mini crash dump.`
			`Mini crash dumps hold only memory pages in use by the kernel.`
			`Alternatively, full memory dumps can be enabled by setting the`
			`.Va debug.minidump`
			`.Xr sysctl 8`
			`variable to 0.`
			`.Pp`
			`For systems using full memory dumps, the size of the specified dump`
			`device must be at`
Wrap some long lines (no content changes) 2004-10-03 23:35:34 +00:00			`least the size of physical memory.`
- Mention the size of the additional header PR: docs/85867 Submitted by: dinoex MFC after: 1 week 2006-01-07 19:17:13 +00:00			`Even though an additional 64 kB header is added to the dump, the BIOS for a`
Wrap some long lines (no content changes) 2004-10-03 23:35:34 +00:00			`platform typically holds back some memory, so it is not usually`
Improve wording even more. 2002-08-13 11:39:38 +00:00			`necessary to size the dump device larger than the actual amount of RAM`
			`available in the machine.`
Adapt to the fact that minidumps are now on by default. PR: 177188 2013-04-30 07:22:03 +00:00			`Also, when using full memory dumps, the`
Verify that the specified device is at least as large as hw.physmem. 2004-10-03 23:38:49 +00:00			`.Nm`
			`utility will refuse to enable a dump device which is smaller than the`
			`total amount of physical memory as reported by the`
			`.Va hw.physmem`
			`.Xr sysctl 8`
			`variable.`
			`.Pp`
			`The`
Add an option to display the current dump device via dumpon -l. MFC after: 2 weeks 2012-11-01 18:59:19 +00:00			`.Fl l`
			`flag causes`
			`.Nm`
			`to print the current dump device or _PATH_DEVNULL ("/dev/null") if no device is`
			`configured.`
			`.Pp`
			`The`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Fl v`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`flag causes`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Nm`
Correct manual page, based on feedback from Bruce Evans. Reviewed by: Bruce Evans <bde@freebsd.org> 1998-05-27 11:05:59 +00:00			`to be verbose about its activity.`
Bring the dumpon(8) man page closer to reality: - dumpon utility has not used kern.dumpdev sysctl since rev. 1.14 (sbin/dumpon/dumpon.c) when phk@ updated it to use the DIOCSKERNELDUMP ioctl [1] - remove obsolete reference to sysctl(3) While I am there, fix two style nits: - use .Nm instead of `dumpon' - change NOTES to IMPLEMENTATION NOTES, to bring it in line with recommended section headings in mdoc(7) Original patch by: Martin Faxer <gmh003532brfmasthugget.se> [1] PR: docs/39293 Approved and Reviewed by: des (mentor), re (scottl, bmah) 2003-05-07 19:37:51 +00:00			`.Sh IMPLEMENTATION NOTES`
* Clarify text on choosing a dump device * Remove the text which states only devices with minor number 1 can be used - this is no longer true. * Mention that dumpon(8) cannot be used to capture dumps from panics during kernel initialization. * /dev/wd -> /dev/ad PR: 19848 Submitted by: Udo Erdelhoff <ue@nathan.ruhr.de> Reviewed by: sheldonh 2000-07-14 18:04:39 +00:00			`Since a`
			`.Xr panic 9`
			`condition may occur in a situation`
			`where the kernel cannot trust its internal representation`
s/filesystem/file system/g as discussed on -developers 2002-08-21 18:11:48 +00:00			`of the state of any given file system,`
* Clarify text on choosing a dump device * Remove the text which states only devices with minor number 1 can be used - this is no longer true. * Mention that dumpon(8) cannot be used to capture dumps from panics during kernel initialization. * /dev/wd -> /dev/ad PR: 19848 Submitted by: Udo Erdelhoff <ue@nathan.ruhr.de> Reviewed by: sheldonh 2000-07-14 18:04:39 +00:00			`one of the system swap devices,`
			`and`
			`.Em not`
s/filesystem/file system/g as discussed on -developers 2002-08-21 18:11:48 +00:00			`a device containing a file system,`
* Clarify text on choosing a dump device * Remove the text which states only devices with minor number 1 can be used - this is no longer true. * Mention that dumpon(8) cannot be used to capture dumps from panics during kernel initialization. * /dev/wd -> /dev/ad PR: 19848 Submitted by: Udo Erdelhoff <ue@nathan.ruhr.de> Reviewed by: sheldonh 2000-07-14 18:04:39 +00:00			`should be used as the dump device.`
Manual page fix: add cross references, refer to ``dumpdev'' variable in "/etc/rc.conf". PR: 6117 Submitted by: Mark Mayo <mark@vmunix.com> 1998-05-25 08:54:40 +00:00			`.Pp`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`The`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Nm`
Bring the dumpon(8) man page closer to reality: - dumpon utility has not used kern.dumpdev sysctl since rev. 1.14 (sbin/dumpon/dumpon.c) when phk@ updated it to use the DIOCSKERNELDUMP ioctl [1] - remove obsolete reference to sysctl(3) While I am there, fix two style nits: - use .Nm instead of `dumpon' - change NOTES to IMPLEMENTATION NOTES, to bring it in line with recommended section headings in mdoc(7) Original patch by: Martin Faxer <gmh003532brfmasthugget.se> [1] PR: docs/39293 Approved and Reviewed by: des (mentor), re (scottl, bmah) 2003-05-07 19:37:51 +00:00			`utility operates by opening`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Ar special_file`
Bring the dumpon(8) man page closer to reality: - dumpon utility has not used kern.dumpdev sysctl since rev. 1.14 (sbin/dumpon/dumpon.c) when phk@ updated it to use the DIOCSKERNELDUMP ioctl [1] - remove obsolete reference to sysctl(3) While I am there, fix two style nits: - use .Nm instead of `dumpon' - change NOTES to IMPLEMENTATION NOTES, to bring it in line with recommended section headings in mdoc(7) Original patch by: Martin Faxer <gmh003532brfmasthugget.se> [1] PR: docs/39293 Approved and Reviewed by: des (mentor), re (scottl, bmah) 2003-05-07 19:37:51 +00:00			`and making a`
			`.Dv DIOCSKERNELDUMP`
			`.Xr ioctl 2`
			`request on it to save kernel crash dumps.`
			`If`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Ar special_file`
Correct manual page, based on feedback from Bruce Evans. Reviewed by: Bruce Evans <bde@freebsd.org> 1998-05-27 11:05:59 +00:00			`is the text string:`
Bring the dumpon(8) man page closer to reality: - dumpon utility has not used kern.dumpdev sysctl since rev. 1.14 (sbin/dumpon/dumpon.c) when phk@ updated it to use the DIOCSKERNELDUMP ioctl [1] - remove obsolete reference to sysctl(3) While I am there, fix two style nits: - use .Nm instead of `dumpon' - change NOTES to IMPLEMENTATION NOTES, to bring it in line with recommended section headings in mdoc(7) Original patch by: Martin Faxer <gmh003532brfmasthugget.se> [1] PR: docs/39293 Approved and Reviewed by: des (mentor), re (scottl, bmah) 2003-05-07 19:37:51 +00:00			`.Dq Li off ,`
			`.Nm`
			`performs a`
			`.Dv DIOCSKERNELDUMP`
			`.Xr ioctl 2`
			`on`
			`.Pa /dev/null`
			`and thus instructs the kernel not to save crash dumps.`
Sort sections. 2005-01-18 10:09:38 +00:00			`.Sh FILES`
			`.Bl -tag -width "/dev/{ad,da}?s?b" -compact`
			`.It Pa /dev/{ad,da}?s?b`
			`standard swap areas`
			`.It Pa /etc/rc.conf`
			`boot-time system configuration`
			`.El`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Sh SEE ALSO`
Manual page fix: add cross references, refer to ``dumpdev'' variable in "/etc/rc.conf". PR: 6117 Submitted by: Mark Mayo <mark@vmunix.com> 1998-05-25 08:54:40 +00:00			`.Xr fstab 5 ,`
			`.Xr rc.conf 5 ,`
			`.Xr config 8 ,`
Sort cross references. 1998-08-31 16:41:09 +00:00			`.Xr init 8 ,`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Xr rc 8 ,`
Manual page fix: add cross references, refer to ``dumpdev'' variable in "/etc/rc.conf". PR: 6117 Submitted by: Mark Mayo <mark@vmunix.com> 1998-05-25 08:54:40 +00:00			`.Xr savecore 8 ,`
			`.Xr swapon 8 ,`
			`.Xr panic 9`
My utility to specify where you want crash dumps to go. More user and kernel support to follow. 1995-05-12 19:10:09 +00:00			`.Sh HISTORY`
			`The`
			`.Nm`
The .Nm utility 2002-07-06 19:34:18 +00:00			`utility appeared in`
Use the .Fx macro where appropriate. 1996-08-23 00:57:08 +00:00			`.Fx 2.1 .`
Sort sections. 2005-01-18 10:09:38 +00:00			`.Sh BUGS`
			`Because the file system layer is already dead by the time a crash dump`
			`is taken, it is not possible to send crash dumps directly to a file.`