dumpctrl Command

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]

dumcptrl -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 given.

Item Description
-c comp-path-list Specifies components by path name. Wildcards are allowed. Use -c all to specify all of the components.
-k Refreshes the list of dumps of the kernel. This is run every 5 minutes by default. This period can be changed by editing the crontab for the root user and changing the entry for /usr/sbin/dumpctrl -k. For more information, see the crontab command. You need to run the dumpctrl -k command after adding or removing 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 at this time.
-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 given. 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
     ...
  • -ql lists global live dump settings. -ql can be used with the -p or -P flag to query persistent global live dump settings.
  -qs type shows global system dump attributes. -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. This only resets the global dump settings. Individual components cannot be specified. The -P flag and a bosboot 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 shown contains only dumps with the specified components. If components are specified with the -C, -L, or -T flag, the list of dumps shown contains only dumps 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 only valid 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 created after the dumpctrl command runs.
-P Makes the specified changes permanent. Any changes made remain in effect across a restart. If a bosboot is required, a message is produced to this effect. 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. Note that the specification must be specified in the same manner as it was originally specified with the -P flag.

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

If you do not know the customizations that have been made but want to restore the default system setting, you can do one of the following:
  • In the /var/adm/ras/raspertune file, delete the lines relevant to the customizations and run the bosboot command to restart AIX®.
  • Read the /var/adm/ras/raspertune file to figure out the appropriate flags and parameters that have been specified. Then use the -x flag to delete the customizations. 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 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

See the following note 1 for more information.
dir Specifies a live dump directory name. /var/adm/ras/livedump
freespc Specifies live dump free space threshold using a decimal value from 0 to 99. 25 (means 25%)
ldmplevel Specifies the live dump level 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)

See the following note 1 for more information.
heapsz Specifies live dump heap size using a decimal value in megabytes. 0

See the following note 2 for more information.
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 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

See the following note 3 for more information.
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 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)

See the following note 4 for more information.
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
Note:
  1. The ldmpenable and ldmplevel attributes can be specified with or without components. If specified without components, the attributes apply to the corresponding global attributes.
  2. The heapsz attribute (heap size) can be set to 0, meaning that, at dump initialization time, the system calculates the live dump heap size based on the amount of real memory, which is the minimum of 64MB and 1/64 the size of real memory.
  3. 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 totally disabled.
  4. 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, bosboot 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, bosboot 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, bosboot required with the -P flag.
legacyenable dump legacy components Takes effect immediately, and upon system restart with the -P flag. No bosboot required with the -P flag.
sdmplevel system dump level Controlled by persistence flags, bosboot required with the -P flag.
copydir copy directory Takes effect immediately and upon system restart.
forcecopy brings up the boot time menu if cannot copy Takes effect immediately and upon system restart.
keyseq key sequences always cause a dump Takes effect immediately and upon system restart.
primary the primary dump device Takes effect immediately, and upon system restart with the -P flag. No bosboot required with the -P flag.
secondary the secondary dump device Takes effect immediately, and upon system restart with the -P flag. No bosboot 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 specified with the sysdumpdev -d, -D, -k/-K, -p and -s flags. For more information, see the sysdumpdev command in AIX Version 7.1 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. (This can occur with the -x flag.)

Security

Only the root user can use this command.