path: root/usr/src/man/man1m/dumpadm.1m

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2015 Nexenta Systems, Inc.  All Rights Reserved.
.\" Copyright (c) 2013 by Delphix. All rights reserved.
.\" Copyright 2019 Joyent, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DUMPADM 1M "Jun 15, 2019"
.SH NAME
dumpadm \- configure operating system crash dump
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/dumpadm\fR [\fB-enuy\fR] [\fB-c\fR \fIcontent-type\fR] [\fB-d\fR \fIdump-device\fR]
     [\fB-k\fR \fIkey-file\fR] [\fB-m\fR \fImin\fRk | \fImin\fRm | \fImin\fR%] [\fB-s\fR \fIsavecore-dir\fR]
     [\fB-r\fR \fIroot-dir\fR] [\fB-z\fR on | off]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBdumpadm\fR program is an administrative command that manages the
configuration of the operating system crash dump facility. A crash dump is a
disk copy of the physical memory of the computer at the time of a fatal system
error. When a fatal operating system error occurs, a message describing the
error is printed to the console. The operating system then generates a crash
dump by writing the contents of physical memory to a predetermined dump device,
which is typically a local disk partition. The dump device can be configured by
way of \fBdumpadm\fR. Once the crash dump has been written to the dump device,
the system will reboot.
.sp
.LP
Fatal operating system errors can be caused by bugs in the operating system,
its associated device drivers and loadable modules, or by faulty hardware.
Whatever the cause, the crash dump itself provides invaluable information to
your support engineer to aid in diagnosing the problem. As such, it is vital
that the crash dump be retrieved and given to your support provider. Following
an operating system crash, the \fBsavecore\fR(1M) utility is executed
automatically during boot to retrieve the crash dump from the dump device, and
write it to the file system. The directory in which the crash
dump is saved on reboot can also be configured using \fBdumpadm\fR.
.sp
.LP
A crash dump is always compressed on the dump device. The dump is decompressed
by the \fBsavecore\fR(1M) utility, which can optionally store the dump in its
compressed state, thereby deferring decompression to a subsequent invocation
of \fBsavecore\fR. This behavior is controlled by the \fB-z\fR option.
When compression is turned on, the \fBsavecore\fR(1M) utility writes one file
to the file system named \fIvmdump.X\fR. If compression is disabled, it instead
writes two files named \fIunix.X\fR and \fIvmcore.X\fR. In the uncompressed
case, both data files form the \fIsaved crash dump\fR. In both cases X is an
integer identifying the dump.
.sp
.LP
Crash dump encryption may be optionally enabled via the \fB-k\fR option, which
specifies a file that contains an encryption key. When crash dump encryption
is enabled, the contents of kernel memory as stored in the dump device will be
encrypted. Decryption of a kernel crash dump must occur when the dump is
extracted via \fBsavecore\fR (to which the encryption key must be separately
provided). Decompression can only occur on a decrypted dump; when dump
encryption is enabled, \fBsavecore\fR must store the dump in its compressed
state. Note that \fBsavecore\fR cannot extract an encrypted dump without also
decrypting it; when dump encryption is enabled, the operator should be sure
to only operate \fBsavecore\fR on a directory that is separately encrypted
or otherwise secured. Finally, note that \fBdumpadm\fR does not store the
crash dump encryption key persistently: upon system reset, crash dump
encryption is always disabled.
.sp
.LP
For systems with a UFS root file system, the default dump device is  configured
to be an appropriate swap partition. Swap partitions are disk partitions
reserved as virtual memory backing store for the operating system. Thus, no
permanent information resides in swap to be overwritten by the dump. See
\fBswap\fR(1M). For systems with a ZFS root file system, dedicated ZFS volumes
are used for swap and dump areas. For further information about setting up a
dump area with ZFS,  see the \fIZFS Administration Guide\fR. To view the
current dump  configuration, use the \fBdumpadm\fR command with no arguments:
.sp
.in +2
.nf
example# \fBdumpadm\fR

      Dump content: kernel pages
       Dump device: /dev/dsk/c0t0d0s1 (swap)
Savecore directory: /var/crash/saturn
  Savecore enabled: yes
   Save compressed: on
    Dump encrypted: no
.fi
.in -2
.sp

.sp
.LP
When no options are specified, \fBdumpadm\fR prints the current crash dump
configuration. The example shows the set of default values: the dump content is
set to kernel memory pages only, the dump device is a swap disk partition, the
directory for \fBsavecore\fR files is set to
\fB/var/crash/\fR\fIhostname\fR\fB,\fR \fBsavecore\fR is set to run
automatically on reboot, and compression is turned on.
.sp
.LP
When one or more options are specified, \fBdumpadm\fR verifies that your
changes are valid, and if so, reconfigures the crash dump parameters and
displays the resulting configuration. You must be \fBroot\fR to view or change
dump parameters.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIcontent-type\fR\fR
.ad
.sp .6
.RS 4n
Modify the dump configuration so that the crash dump consists of the specified
dump content. The content should be one of the following:
.sp
.ne 2
.na
\fB\fBkernel\fR\fR
.ad
.sp .6
.RS 4n
Kernel memory pages only.
.RE

.sp
.ne 2
.na
\fB\fBall\fR\fR
.ad
.sp .6
.RS 4n
All memory pages.
.RE

.sp
.ne 2
.na
\fB\fBcurproc\fR\fR
.ad
.sp .6
.RS 4n
Kernel memory pages, and the memory pages of the process whose thread was
currently executing on the CPU on which the crash dump was initiated. If the
thread executing on that CPU is a kernel thread not associated with any user
process, only kernel pages will be dumped.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIdump-device\fR\fR
.ad
.sp .6
.RS 4n
Modify the dump configuration to use the specified dump device. The dump device
may be one of the following:
.sp
.ne 2
.na
\fB\fIdump-device\fR\fR
.ad
.sp .6
.RS 4n
A specific dump device specified as an absolute pathname, such as
\fB/dev/dsk/\fR\fIcNtNdNsN\fR when the system is running a UFS root file
system. Or, specify a ZFS volume, such as \fB/dev/zvol/dsk/rpool/dump\fR, when
the system is running a ZFS root file system.
.RE

.sp
.ne 2
.na
\fB\fBswap\fR\fR
.ad
.sp .6
.RS 4n
If the special token \fBswap\fR is specified as the dump device, \fBdumpadm\fR
examines the  active swap entries and selects the most appropriate entry to
configure as the dump device. See \fBswap\fR(1M). Refer to the \fBNOTES\fR
below for details of the algorithm  used to select an appropriate swap entry.
When the system is first installed with a UFS root file system, \fBdumpadm\fR
uses the value for \fBswap\fR to determine the initial dump device setting. A
given ZFS volume cannot be configured for both the swap area and the dump
device.
.RE

.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.sp .6
.RS 4n
If the special token \fBnone\fR is specified, the active dump device is removed
and crash dumps are disabled.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.sp .6
.RS 4n
Estimates the size of the dump for the current running system.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR \fIkey-file\fR\fR
.ad
.sp .6
.RS 4n
Specifies that the dump should be encrypted based on the key found in
\fIkey-file\fR. Note that any invocations of \fBsavecore\fR will need to
specify the same key to be able to correctly retrieve the dump.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR \fImin\fR\fBk\fR | \fImin\fR\fBm\fR | \fImin\fR\fB%\fR\fR
.ad
.sp .6
.RS 4n
Create a \fBminfree\fR file in the current savecore directory indicating that
\fBsavecore\fR should maintain at least the specified amount of free space in
the file system where the savecore directory is located. The \fBmin\fR argument
can be one of the following:
.sp
.ne 2
.na
\fB\fBk\fR\fR
.ad
.sp .6
.RS 4n
A positive integer suffixed with the unit \fBk\fR specifying kilobytes.
.RE

.sp
.ne 2
.na
\fB\fBm\fR\fR
.ad
.sp .6
.RS 4n
A positive integer suffixed with the unit \fBm\fR specifying megabytes.
.RE

.sp
.ne 2
.na
\fB\fB%\fR\fR
.ad
.sp .6
.RS 4n
A % symbol, indicating that the \fBminfree\fR value should be computed as the
specified percentage of the total current size of the file system containing
the savecore directory.
.RE

The \fBsavecore\fR command will consult the \fBminfree\fR file, if present,
prior to writing the dump files. If the size of these files would decrease the
amount of free disk space below the \fBminfree\fR threshold, no dump files are
written and an error message is logged. The administrator should immediately
clean up the savecore directory to provide adequate free space, and re-execute
the \fBsavecore\fR command manually. The administrator can also specify an
alternate directory on the \fBsavecore\fR command-line.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Modify the dump configuration to not run \fBsavecore\fR automatically on
reboot. This is not the recommended system configuration; if the dump device is
a swap partition, the dump data will be overwritten as the system begins to
swap. If \fBsavecore\fR is not executed shortly after boot, crash dump
retrieval may not be possible.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIroot-dir\fR\fR
.ad
.sp .6
.RS 4n
Specify an alternate root directory relative to which \fBdumpadm\fR should
create files. If no \fB-r\fR argument is specified, the default root directory
\fB/\fR is used.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIsavecore-dir\fR\fR
.ad
.sp .6
.RS 4n
Modify the dump configuration to use the specified directory to save files
written by \fBsavecore\fR. The directory should be an absolute path and exist
on the system. If upon reboot the directory does not exist, it will be created
prior to the execution of \fBsavecore\fR. See the \fBNOTES\fR section below for
a discussion of security issues relating to access to the savecore directory.
The default savecore directory is \fB/var/crash/\fIhostname\fR\fR where
\fIhostname\fR is the output of the \fB-n\fR option to the \fBuname\fR(1)
command.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.sp .6
.RS 4n
Forcibly update the kernel dump configuration based on the contents of
\fB/etc/dumpadm.conf\fR. Normally this option is used only on reboot when
starting \fBsvc:/system/dumpadm:default\fR, when the \fBdumpadm\fR settings
from the previous boot must be restored. Your dump configuration is saved in
the configuration file for this purpose. If the configuration file is missing
or contains invalid values for any dump properties, the default values are
substituted. Following the update, the configuration file is resynchronized
with the kernel dump configuration.
.RE

.sp
.ne 2
.na
\fB\fB-y\fR\fR
.ad
.sp .6
.RS 4n
Modify the dump configuration to automatically run \fBsavecore\fR on reboot.
This is the default for this dump setting.
.RE

.sp
.ne 2
.na
\fB\fB-z on | off\fR\fR
.ad
.sp .6
.RS 4n
Turns crash dump compression \fBon\fR or \fBoff\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRReconfiguring The Dump Device To A Dedicated Dump Device:
.sp
.LP
The following command reconfigures the dump device to a dedicated dump device:

.sp
.in +2
.nf
example# dumpadm -d /dev/dsk/c0t2d0s2

           Dump content: kernel pages
            Dump device: /dev/dsk/c0t2d0s2 (dedicated)
     Savecore directory: /var/crash/saturn
       Savecore enabled: yes
        Save compressed: on
         Dump encrypted: no
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Dump configuration is valid and the specified modifications, if any, were made
successfully.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.sp .6
.RS 4n
A fatal error occurred in either obtaining or modifying the dump configuration.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.sp .6
.RS 4n
Invalid command line options were specified.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/dump\fR\fR
.ad
.sp .6
.RS 4n
Dump device.
.RE

.sp
.ne 2
.na
\fB\fB/etc/dumpadm.conf\fR\fR
.ad
.sp .6
.RS 4n
Contains configuration parameters for \fBdumpadm\fR. Modifiable only through
that command.
.RE

.sp
.ne 2
.na
\fB\fIsavecore-directory\fR\fB/minfree\fR\fR
.ad
.sp .6
.RS 4n
Contains minimum amount of free space for \fIsavecore-directory\fR. See
\fBsavecore\fR(1M).
.RE

.SH SEE ALSO
.sp
.LP
\fBsvcs\fR(1), \fBuname\fR(1), \fBsavecore\fR(1M), \fBsvcadm\fR(1M),
\fBswap\fR(1M), \fBattributes\fR(5), \fBsmf\fR(5)
.SH NOTES
.sp
.LP
The system crash dump service is managed by the service management facility,
\fBsmf\fR(5), under the service identifier:
.sp
.in +2
.nf
svc:/system/dumpadm:default
.fi
.in -2
.sp

.sp
.LP
Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
status can be queried using the \fBsvcs\fR(1) command.
.SS "Dump Device Selection"
.sp
.LP
When the special \fBswap\fR token is specified as the argument to \fBdumpadm\fR
\fB-d\fR the utility will attempt to configure the most appropriate swap device
as the dump device. \fBdumpadm\fR configures the largest swap block device as
the dump device; if no block devices are available for swap, the largest swap
entry is configured as the dump device. If no swap entries are present, or none
can be configured as the dump device, a warning message will be displayed.
While local and remote swap files can be configured as the dump device, this is
not recommended.
.SS "Dump Device/Swap Device Interaction (UFS File Systems Only)"
.sp
.LP
In the event that the dump device is also a swap device, and the swap device is
deleted by the administrator using the \fBswap\fR \fB-d\fR command, the
\fBswap\fR command will automatically invoke \fBdumpadm\fR \fB-d\fR \fBswap\fR
in order to attempt to configure another appropriate swap device as the dump
device. If no swap devices remain or none can be configured as the dump device,
the crash dump will be disabled and a warning message will be displayed.
Similarly, if the crash dump is disabled and the administrator adds a new swap
device using the \fBswap\fR \fB-a\fR command, \fBdumpadm\fR \fB-d\fR \fBswap\fR
will be invoked to re-enable the crash dump using the new swap device.
.sp
.LP
Once \fBdumpadm\fR \fB-d\fR \fBswap\fR has been issued, the new dump device is
stored in the configuration file for subsequent reboots. If a larger or more
appropriate swap device is added by the administrator, the dump device is not
changed; the administrator must re-execute \fBdumpadm\fR \fB-d\fR \fBswap\fR to
reselect the most appropriate device fom the new list of swap devices.
.SS "Minimum Free Space"
.sp
.LP
If the \fBdumpadm\fR \fB-m\fR option is used to create a \fBminfree\fR file
based on a percentage of the total size of the file system containing the
savecore directory, this value is not automatically recomputed if the file
system subsequently changes size.  In this case, the administrator must
re-execute \fBdumpadm\fR \fB-m\fR to recompute the \fBminfree\fR value. If no
such file exists in the savecore directory, \fBsavecore\fR will default to a
free space threshold of one megabyte. If no free space threshold is desired, a
minfree file containing size 0 can be created.
.SS "Security Issues"
.sp
.LP
If, upon reboot, the specified savecore directory is not present, it will be
created prior to the execution of \fBsavecore\fR with permissions 0700 (read,
write, execute by owner only) and owner \fBroot\fR. It is recommended that
alternate savecore directories also be created with similar permissions, as the
operating system crash dump files themselves may contain secure information.