DUMPADM(8) Maintenance Commands and Procedures DUMPADM(8)

NAME

dumpadm - configure operating system crash dump

SYNOPSIS

/usr/sbin/dumpadm [-enuy] [-c content-type] [-d dump-device]
[-k key-file] [-m mink | minm | min%] [-s savecore-dir]
[-r root-dir] [-z on | off]

DESCRIPTION

The dumpadm 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 dumpadm. Once the crash dump has
been written to the dump device, the system will reboot.


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 savecore(8)
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
dumpadm.


A crash dump is always compressed on the dump device. The dump is
decompressed by the savecore(8) utility, which can optionally store the
dump in its compressed state, thereby deferring decompression to a
subsequent invocation of savecore. This behavior is controlled by the -z
option. When compression is turned on, the savecore(8) utility writes
one file to the file system named vmdump.X. If compression is disabled,
it instead writes two files named unix.X and vmcore.X. In the
uncompressed case, both data files form the saved crash dump. In both
cases X is an integer identifying the dump.


Crash dump encryption may be optionally enabled via the -k 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 savecore (to which the encryption
key must be separately provided). Decompression can only occur on a
decrypted dump; when dump encryption is enabled, savecore must store the
dump in its compressed state. Note that savecore cannot extract an
encrypted dump without also decrypting it; when dump encryption is
enabled, the operator should be sure to only operate savecore on a
directory that is separately encrypted or otherwise secured. Finally,
note that dumpadm does not store the crash dump encryption key
persistently: upon system reset, crash dump encryption is always
disabled.


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 swap(8). 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 ZFS
Administration Guide. To view the current dump configuration, use the
dumpadm command with no arguments:

example# dumpadm

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


When no options are specified, dumpadm 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 savecore files is set to
/var/crash/hostname, savecore is set to run automatically on reboot, and
compression is turned on.


When one or more options are specified, dumpadm verifies that your
changes are valid, and if so, reconfigures the crash dump parameters and
displays the resulting configuration. You must be root to view or change
dump parameters.

OPTIONS

The following options are supported:

-c content-type

Modify the dump configuration so that the crash dump consists of the
specified dump content. The content should be one of the following:

kernel

Kernel memory pages only.


all

All memory pages.


curproc

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.


-d dump-device

Modify the dump configuration to use the specified dump device. The
dump device may be one of the following:

dump-device

A specific dump device specified as an absolute pathname, such as
/dev/dsk/cNtNdNsN when the system is running a UFS root file
system. Or, specify a ZFS volume, such as
/dev/zvol/dsk/rpool/dump, when the system is running a ZFS root
file system.


swap

If the special token swap is specified as the dump device,
dumpadm examines the active swap entries and selects the most
appropriate entry to configure as the dump device. See swap(8).
Refer to the NOTES 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, dumpadm uses the value for
swap to determine the initial dump device setting. A given ZFS
volume cannot be configured for both the swap area and the dump
device.


none

If the special token none is specified, the active dump device is
removed and crash dumps are disabled.


-e

Estimates the size of the dump for the current running system.


-k key-file

Specifies that the dump should be encrypted based on the key found in
key-file. Note that any invocations of savecore will need to specify
the same key to be able to correctly retrieve the dump.


-m mink | minm | min%

Create a minfree file in the current savecore directory indicating
that savecore should maintain at least the specified amount of free
space in the file system where the savecore directory is located. The
min argument can be one of the following:

k

A positive integer suffixed with the unit k specifying kilobytes.


m

A positive integer suffixed with the unit m specifying megabytes.


%

A % symbol, indicating that the minfree value should be computed
as the specified percentage of the total current size of the file
system containing the savecore directory.

The savecore command will consult the minfree 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 minfree 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 savecore command manually.
The administrator can also specify an alternate directory on the
savecore command-line.


-n

Modify the dump configuration to not run savecore 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 savecore is not executed shortly after
boot, crash dump retrieval may not be possible.


-r root-dir

Specify an alternate root directory relative to which dumpadm should
create files. If no -r argument is specified, the default root
directory / is used.


-s savecore-dir

Modify the dump configuration to use the specified directory to save
files written by savecore. 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 savecore. See the NOTES
section below for a discussion of security issues relating to access
to the savecore directory. The default savecore directory is
/var/crash/hostname where hostname is the output of the -n option to
the uname(1) command.


-u

Forcibly update the kernel dump configuration based on the contents
of /etc/dumpadm.conf. Normally this option is used only on reboot
when starting svc:/system/dumpadm:default, when the dumpadm 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.


-y

Modify the dump configuration to automatically run savecore on
reboot. This is the default for this dump setting.


-z on | off

Turns crash dump compression on or off.

EXAMPLES

Example 1: Reconfiguring The Dump Device To A Dedicated Dump Device:

The following command reconfigures the dump device to a dedicated dump
device:


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

EXIT STATUS

The following exit values are returned:

0

Dump configuration is valid and the specified modifications, if any,
were made successfully.


1

A fatal error occurred in either obtaining or modifying the dump
configuration.


2

Invalid command line options were specified.

FILES

/dev/dump

Dump device.


/etc/dumpadm.conf

Contains configuration parameters for dumpadm. Modifiable only
through that command.


savecore-directory/minfree

Contains minimum amount of free space for savecore-directory. See
savecore(8).

SEE ALSO

svcs(1), uname(1), attributes(7), smf(7), savecore(8), svcadm(8), swap(8)

NOTES

The system crash dump service is managed by the service management
facility, smf(7), under the service identifier:

svc:/system/dumpadm:default


Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using svcadm(8). The service's
status can be queried using the svcs(1) command.

Dump Device Selection

When the special swap token is specified as the argument to dumpadm -d
the utility will attempt to configure the most appropriate swap device as
the dump device. dumpadm 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.

Dump Device/Swap Device Interaction (UFS File Systems Only)
In the event that the dump device is also a swap device, and the swap
device is deleted by the administrator using the swap -d command, the
swap command will automatically invoke dumpadm -d swap 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 swap -a command, dumpadm -d swap will be invoked to
re-enable the crash dump using the new swap device.


Once dumpadm -d swap 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 dumpadm -d swap to
reselect the most appropriate device fom the new list of swap devices.

Minimum Free Space

If the dumpadm -m option is used to create a minfree 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 dumpadm -m to recompute the minfree value. If no such file exists
in the savecore directory, savecore 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.

Security Issues

If, upon reboot, the specified savecore directory is not present, it will
be created prior to the execution of savecore with permissions 0700
(read, write, execute by owner only) and owner root. 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.

June 15, 2019 DUMPADM(8)