dumpctrl Command

Edit online

Purpose

Manages system dumps and live dumps.

Syntax

dumpctrl -k

dumpctrl -R [ l | s ] [-P]

dumpctrl -s [-c | -C comp-path-list] [-l | -L comp-alias-list] [-t | -T type_subtype] [-r] [-u]

dumpctrl -qc [-c comp-path-list] [-l comp-alias-list] [-t type_subtype] [-r] [-u] [-p | -P]

dumpctrl -ql [-p | -P]

dumpctrl -qs [-p | -P]

dumpctrl [-P] [global_attribute]

dumpctrl [-c comp-path-list] [l comp-alias-list] [-t type_subtype] [-r] [-u] [-n | -p | -P | -x] [per-component_attribute]

Description

There are two types of dump components:

component: Refers to a component specified with the RAS infrastructure (one created with the ras_register() kernel service).
legacy component: Refers to a dump component specified with either the dmp_add() or the dmp_ctl() kernel service.

The dumpctrl command is used to obtain information about which components are registered for live dumps or system dumps, and to query and change dump characteristics.

Components are specified with the full path name, device logical alias, type or subtype. You can use multiple flags to specify multiple components or component lists.

Flags

At least one flag must be specified.

Item	Description
-c `comp-path-list`	Specifies components by path name. Wildcards are allowed. Use the -c all command to specify all of the components.
-k	Refreshes the list of dumps of the kernel. This flag is run every 5 minutes by default. This period can be changed by editing the crontab command for the root user and changing the entry for /usr/sbin/dumpctrl -k. For more information, see the crontab command. You must run the dumpctrl -k command after you add or remove dumps by hand. If the system is holding any dumps in the heap that it previously could not write to the file system, the system attempts to write those dumps and reclaim their storage space now.
-l `comp-alias-list`	Specifies components by alias. Wildcards are allowed.
-r	Dumps any subcomponents of the specified components.
-q `cmd`	Queries attributes for the live dump or system dump. The -qc flag shows component-specific live dump attributes and system dump attributes. The -qc flag can be used with the -p or -P flag to query persistent per-component attributes. The -qc flag shows the attributes for all components if neither the -c, -l, nor -t flag is specified. In other words, -c all is the default. The following is a sample output for this command: `dumpctrl -qc -r -l vmm -l proc -------------------------------------------------------------------------- Component name \| Have \| Live Dump \| System Dump \|Alias \| /level \| /level -------------------------------------------------------------------------- vmm \| no \| on/3 \| on/3 .pft \| no \| on/3 \| on/3 ... proc \| no \| on/4 \| on/3 ...` The -ql flag lists global live dump settings. The -ql flag can be used with the -p or -P flag to query persistent global live dump settings. The -qs `type` flag shows global system dump attributes. The -qs can be used with the -p or -P flag to query global system dump attributes.
-r	Includes components below the specified components in the component hierarchy.
-Rx	Restores dump settings to their defaults. `x` can be `l` for live dump settings, or `s` for system dump settings. It resets only the global dump settings. Individual components cannot be specified. The -P flag and a new boot image are required to ensure all of these settings remain in effect across a restart.
-t `type_subtype`	Specifies a component by `type_subtype` names.
-s	Lists the path names and titles of all live dumps in the dump repository. If components are specified with the -c, -l, or -t flag, the list of dumps that are shown contains dumps only with the specified components. If components are specified with the -C, -L, or -T flag, the list of dumps that are shown contains dumps only with the specified failing components.
-C `comp-path-list`	Specifies components by path name. Wildcards are allowed. The reserved name `all` is also allowed to indicate all components. The -C flag is only valid with the -s flag.
-L `comp-alias-list`	Specifies components by alias. Wildcards are allowed. The -L flag is only valid with the -s flag.
-T `type_subtype`	Specifies a component by `type_subtype` names. The -T flag is valid only with the -s flag.
-u	Includes components above the specified components in the component hierarchy.

Persistence flags

Item	Description
-p	Changes apply only to newly created components, which are RAS infrastructure components that are created after the dumpctrl command runs.
-P	Makes the specified changes permanent. Any changes that are made remain in effect across a restart. If a new boot image is required, a message is produced to notify you about it. The -P flag applies to component attributes, the global enabling or disabling of live dump, the global live dump level, the enabling or disabling of legacy components, and the system dump device specifications.
-n	Changes apply to existing components. The -n flag is the default if neither -p nor -P is specified. To apply changes to both current and newly created components, use the -n and -p flags.
-x	Deletes this persistence specification. The -x flag deletes a permanent (-P) persistence specification. The specification must be specified in the same manner as it was originally specified with the -P flag.

Recursive-down customization (specified by the -r flag) take precedence over all other customization, regardless of the order in which they are specified relative to other non-recursive-down customization.

If you do not know the customization that is made but want to restore the default system setting, you can do one of the following actions:

In the /var/adm/ras/raspertune file, delete the lines relevant to the customization and run the bosboot command to restart AIX®.
Read the /var/adm/ras/raspertune file to figure out the appropriate flags and parameters that are specified. Then, use the -x flag to delete the customization. Run the bosboot command and restart AIX.

For more information about how the various dump attributes interact with persistence, see the live dump and system dump attribute tables in Attributes.

Attributes

The dump attributes can take the form attribute=value. For example,

dumpctrl dir=/usr/dumps freespc=20

This example sets dump directory to /usr/dumps, and the free space threshold to 20%.

Some shortcuts are provided, such as the ldmpon attribute, which is the same as ldmpenable=yes.

If components are given, unrecognized attributes are passed to callbacks of those components by using RASCD_DMP_PASS_THROUGH.

The following table lists live dump attributes.

Table 1. Live dump attributes and defaults
Attribute	Specification	Default value
ldmpenable	Specifies whether live dump is enabled. The possible values are yes and no. You can use the ldmpon attribute instead of `ldmpenable=yes`, and the ldmpoff attribute instead of `ldmpenable=no`.	yes For more information, see the following note 1.
dir	Specifies a live dump directory name.	/var/adm/ras/livedump
freespc	Specifies live dump free space threshold by using a decimal value from 0 to 99.	25 (means 25%)
ldmplevel	Specifies the live dump level by using a decimal value from 0 to 9. You can specify the ldmpminimal, ldmpnormal, or ldmpdetail attribute instead of `ldmplevel=1, 3, 7`	3 (normal) For more information, see the following note 1.
heapsz	Specifies live dump heap size by using a decimal value in megabytes.	0 For more information, see the following note 2.
duptype	Specifies duplicate dump suppression type. The following are the possible values: all pre post none	all
maxfreeze	Specifies the maximum recommended system freeze interval by using a decimal number in milliseconds.	100 ms

The following table lists system dump attributes.

Table 2. System dump attributes and defaults
Attribute	Specification	Default value
sdmpenable	Specifies whether system dump is enabled. The possible values are yes and no. You can also specify the sdmpon or sdmpoff instead of `sdmpenable=yes` or `sdmpenable=no`.	yes For more information, see the following note 3.
legacyenable	Specifies whether dump legacy components are enabled. The possible values are yes and no. You can also specify the legacyon or legacyoff instead of `legacyenable=yes` or `legacyenable=no`.	yes
sdmplevel	Specifies the system dump level by using a decimal value from 0 to 9. You can specify the sdmpminimal, sdmpnormal, or sdmpdetail attribute instead of `sdmplevel=1, 3, 7`	3 (normal) For more information, see the following note 4.
copydir	Specifies a copy directory path name.	/var/adm/ras
forcecopy	Specifies whether the forcecopy attribute is enabled. The possible values are yes and no. If a dump must be copied from paging space at boot time, and there is not enough space in the copy directory, you are prompted to copy the dump to removable media if the forcecopy value is yes. If the value is no, the dump is not copied and the system boots normally, although the dump might be lost.	yes
keyseq	Specifies whether the key sequences always cause a dump. The possible values are yes and no.	no
primary	Specifies the primary dump device path name.	/dev/hd6 or /dev/lg_dumplv
secondary	Specifies the secondary dump device path name.	/dev/sysdumpnull

Notes:

The ldmpenable and ldmplevel attributes can be specified with or without components. If specified without components, the attributes apply to the corresponding global attributes.
The heapsz attribute (heap size) can be set to 0, meaning that, at dump initialization time, the system calculates the live dump heap size that is based on the amount of real memory, which is the minimum of 64 MB and 1/64 the size of real memory.
Individual components must be specified when the sdmpenable attribute is given. If no components are given, the sdmpenable attribute cannot be specified because the system dump cannot be disabled.
The sdmplevel attribute can be specified with or without components. If specified without components, it applies to the system default level. The components with sdmplevel that are greater than the global sdmplevel value are not included in a system dump.

The following table lists live dump attributes and their persistence.

Table 3. Live dump attributes and persistence
Attribute	Description	Persistence
ldmpenable	Live dump enabled	Controlled by persistence flags, new boot image is required with the -P flag.
dir	Live dump directory	Takes effect immediately and upon system restart.
freespc	Live dump free space threshold	Takes effect immediately and upon system restart.
ldmplevel	Live dump level	Controlled by persistence flags, new boot image is required with the -P flag.
heapsz	Live dump heap size	Takes effect immediately and upon system restart.
duptype	Duplicate dump suppression type	Takes effect immediately and upon system restart.
maxfreeze	Maximum recommended system freeze interval	Takes effect immediately and upon system restart.

Note: Persistence affects the attributes only when they apply to RAS infrastructure components. Persistence also controls the global live dump level and global enabled or disabled status.

The following table lists system dump attributes and their persistence.

Table 4. System dump attributes and persistence
Attribute	Description	Persistence
sdmpenable	System dump enabled	Controlled by persistence flags, new boot image is required with the -P flag.
legacyenable	Dump legacy components	Takes effect immediately, and upon system restart with the -P flag. No new boot image is required with the -P flag.
sdmplevel	System dump level	Controlled by persistence flags, new boot image is required with the -P flag.
copydir	Copy directory	Takes effect immediately and upon system restart.
forcecopy	Brings up the boot time menu if it cannot copy	Takes effect immediately and upon system restart.
keyseq	Key sequences always cause a dump	Takes effect immediately and upon system restart.
primary	Primary dump device	Takes effect immediately, and upon system restart with the -P flag. No new boot image is required with the -P flag.
secondary	Secondary dump device	Takes effect immediately, and upon system restart with the -P flag. No new boot image is required with the -P flag.

Note: Persistence affects the attributes when they apply to components.

The copydir, forcecopy, keyseq, primary, and secondary attributes behave like their sysdumpdev command counterparts that are specified with the -d, -D, -k, -K, -p, and -s flags. For more information, see the sysdumpdev command in Commands Reference, Volume 5.

Exit Status

This command returns the following exit values:

Item	Description
0	Successful completion.
non-zero	An error occurred. This command fails under the following conditions: One or more parameters are invalid. One or more attributes are invalid. A component cannot be specified. At least one component must be specified. The persistent specification cannot be found. (It can occur with the -x flag.)

Security

Only the root user can use this command.