errctrl Command

Purpose

Modifies or displays the error-checking attributes of system components. Persistent attribute values can also be specified for components that have not yet been created.

Syntax

errctrl [ -n r u ] ComponentSelector ... subcommand ...

errctrl -p [ -r u ] ComponentSelector ... subcommand ...

errctrl -P [ -r u ] ComponentSelector ... subcommand ...

errctrl -x { -P | -p } [-r u ] ComponentSelector ...

errctrl -q [-r u p P] {ComponentSelector ...}

errctrl {-h | -?}

errctrl -P {errcheckon | errcheckoff}

Description

The errctrl command modifies or displays the error-checking attribute values of some or all components. Components are selected by name, by alias, or by type or subtype.

The supported value of a ComponentSelector is as follows:

-c: componentPatternList
-l: aliasPatternList
-t: typePatternList

Each list consists of one or more patterns separated by quoted spaces or commas. Patterns can contain special characters as described by the fnmatch subroutine. The pattern characters question mark (?), asterisk (*), and brackets ([ ]) are supported, but character classes and collation sequences are not allowed inside brackets ([ ]). Specifying -c all selects all components, if no other ComponentSelector is used.

The errctrl command can also be used with the -p or -P flag to specify persistent attribute customizations. For more information about persistent attribute customizations, see Persistent Customizations.

To enable or disable error checking for all components immediately and persistently, specify the errcheckon or errcheckoff subcommand with the -P flag. No other flags or subcommands are allowed with this form of the command. A bosboot command is required to make settings persistent across restarts.

The modified attributes depend on the subcommand specified on the command line. Multiple subcommands can be specified in a single invocation. The following subcommands are available:

Item	Description
errcheckon	Turns on error checking.
errcheckoff	Turns off error checking.
errcheckminimal	Sets the error checking level to 1.
errchecknormal	Sets the error checking level to 3.
errcheckdetail	Sets the error checking level to 7.
errchecklevel={0-9}	Sets the error checking level to the specified value.
lowsevdisposition={disp}	Sets the disposition for low-severity errors to the specified value.
medsevdisposition={disp}	Sets the disposition for medium-severity errors to the specified value.

The disp error disposition is one of the following values:

ignore (or 48)
log (or 64)
livedump (or 80)
isolate (or 96)
sysdump (or 112)

Other subcommands can be recognized by individual components. A subcommand that is not recognized by a component is ignored.

Current attribute values can be displayed with the -q flag. If no ComponentSelector is used, attribute values are displayed for all components for which error-checking is supported.

Memory overlay detection system for network memory can be enabled by setting the detailed error level for the netmalloc component. Raise the errlevel for the netmalloc component to five or more (default: 3(normal)) to collect complete network memory police buffer information for all network memory allocation and free events. Note that raising the error level to seven (detail) or more also enables network memory overlay detection system. To enable only the net_malloc_police option and outstanding memory allocation (OSTD) logging for all network memory allocations and free events, raise the error level to five.

For more information about modifying the errlevel, see the Examples . For more information about raising the trace level to collect trace data in the netmalloc component, see the ctctrl command.

This command can be used to set the probability (frequency) and values to the following netmalloc functions.

police_frequency
frag_mask

Probability is the numerator out of 1024 (for example, 10%: 102, 5%: 51, 1%: 10, 0.1%: 1)

Persistent Customizations

The -p and -P flags allow attribute values to be specified for system components that have not been created yet. Thus, attributes for newly created components can be customized before the components become active. The -p flag is used to specify customizations for components that will be created in the future, but before you restart AIX®. The -P flag is used to specify customizations that will take effect after the next restart. These customizations are added to the /var/adm/ras/raspertune file. You must run the bosboot command to save these customizations in the boot image and restart AIX for the customizations to take effect.

The ComponentSelectors can contain pattern-matching characters. Thus, a persistent customization can apply to more than one component. In addition, multiple customizations can apply to the same component, if different ComponentSelectors are used. If conflicting attribute values are specified in multiple customizations, the last customization takes precedence. If a customization already exists for a specified ComponentSelector, the new customization replaces the old one.

Multiple ComponentSelectors are allowed when persistent customizations are specified, but in all cases, using multiple selectors is equivalent to specifying multiple commands, each with a single component selector. For example, the customization "errctrl -p -l hdisk0 -l hdisk1 errchecknormal" is equivalent to the following two customizations:

errctrl -p -l hdisk0 errchecknormal
errctrl -p -l hdisk1 errchecknormal

Customizations specified with the -p or -P flag are not deleted after they are used. Therefore, a single customization can affect multiple new components. Persistent customization can be deleted with the -x flag. The ComponentSelector must be specified identically to the way it was specified when the customization was created. For example, if a customization is created with the ComponentSelector -l hdisk0, the customization cannot be deleted with the ComponentSelector -l hdisk[0], even though both ComponentSelectors match the same component alias. When a persistent customization is deleted, no change is made to the attributes of components that were created when the customization was active.

Persistent customizations deleted with the -x and -P flags will remain in effect unless you run the bosboot command and restart AIX. A persistent customization that was created with the -P flag can be deleted after the restart by using the -x and -p flags. In this case, the customization will be active again if you restart AIX.

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 as shown in example 6. Run the bosboot command and restart AIX.

The -r and -u flags can be used when specifying persistent customizations. Using one flag specifies a different name space for the specified component selectors. Using both flags at the same time is equivalent to two separate command invocations, each with one of the flags. For example, the persistent customization "errctrl -p -l hdisk0 -u -r errcheckdetail" is equivalent to the following two separate customizations:

errctrl -p -l hdisk0 -u errcheckdetail
errctrl -p -l hdisk0 -r errcheckdetail

The following persistent customizations are all distinct, and can be modified or deleted independently.

errctrl -p -l hdisk0 errcheckdetail
errctrl -p -l hdisk0 -r errcheckdetail
errctrl -p -l hdisk0 -u errcheckdetail

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.

Persistent customizations can be queried by using the -q flag with either the -P or -p flag. Specifying the -q flag with the -P flag displays lines from the /var/adm/ras/raspertune file. Specifying the -q flag with the -p and -r flags displays the persistent customizations originally specified with the -r flag. Without the -r flag, the -q and -p flags display the persistent customizations specified with or without the -u flag.

A persistent customization allows multiple subcommands to be specified. If conflicting subcommands are used, the last subcommand is used. For example, the errchecknormal and errcheckdetail subcommands specify different values for the same error-checking attribute, so the last specified subcommand will be used.

Flags

Item	Description
-c ComponentList	Specifies a comma-separated or space-separated list of component names. The -c all flag selects all components if it is the only ComponentSelector.
-h or -?	Displays a usage message.
-l aliasList	Specifies a comma-separated or space-separated list of component aliases.
-n	Applies subcommands immediately. This flag is the default if neither the -p nor the -P flag is used.
-P	Specifies the subcommands that will persist across restarts. You must run the bosboot command and restart AIX for these subcommands to be active.
-x	Deletes the persistent customization for the specified components. The ComponentSelector must be entered exactly as they were entered when the customization was originally specified.
-p	Specifies persistent subcommands. The specified subcommands will be applied to newly-created components.
-q	Queries the attribute settings of selected components. This flag can also be used with the -p or the -P flag to display persistent customizations.
-r	Applies the subcommands recursively to all subcomponents of the selected components.
-t type_subtypeList	Specifies a space-separated or a comma-separated list of type or type_subtype names. Valid type names include `device`, `filesystem`, `network`, `services`, `storage`, and `ui`. A complete list of type and type_subtype names is located in the /usr/include/sys/ras_base.h header file.
-u	Applies the subcommands recursively to the ancestors of the specified components.

Note: The -u and -r flags can be used together. Multiple -c, -l and -t flags can be used on the command line.

Exit Status

Item	Description
0	Successful completion.
>0	An error occurred.

Security

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations that are associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To turn on detailed error checking for all JFS2 userdata components, enter:
```
errctrl -c 'jfs2.filesystem.*.userdata' errcheckdetail
```
To specify a persistent customization for the userdata component of new JFS2 file systems, enter:
```
errctrl -p -c 'jfs2.filesystem.*.userdata' errcheckminimal
```
The existing userdata components are not affected.
To specify a customization that will persist across restarts, enter:
```
errctrl -P -c 'jfs2.filesystem.*.userdata' errcheckminimal
```
If you run the bosboot command and restart AIX, minimal error checking will be in effect for all JFS2 userdata components.
To set minimal error checking for all current and future JFS2 userdata components., enter:
```
errctrl -npP -c 'jfs2.filesystem.*.userdata' errcheckminimal
```
To specify multiple persistent attribute values for the ethernet component, enter:
```
errctrl -P -c ethernet errcheckminimal medsevdisposition=80
```
To delete the customization specified in Example 2, enter:
```
errctrl -p -x -c 'jfs2.filesystem.*.userdata'
```
To list all persistent, recursive-down attribute customizations, enter:
```
errctrl -q -p -r
```
To list the current error-checking attribute values for the JFS2 components and its descendants, enter:
```
errctrl -q -c jfs2 -r
```
To enable memory overlay detection system (MODS) for network memory (raise the error level to detailed level for the netmalloc component), enter:
```
errctrl errcheckdetail -c netmalloc
```
or
```
errctrl errchecklevel=7 -c netmalloc
```
Note: This also enables the net_malloc_police option for all network memory allocations and free events.
To enable the net_malloc_police option for all network memory allocations and free events, raise the netmalloc component error level to five or greater, enter:
```
errctrl errchecklevel=5 -c netmalloc
```
This command also enables outstanding memory allocation (OSTD) logging for network memory.
To change the frequency of netmalloc police allocation and free events to 25%, change the probability of police_frequency function to 256, enter:
```
errctrl police_frequency=256 –c netmalloc.police 
```

Location

/usr/sbin/errctrl

Files

Item	Description
/var/adm/ras/raspertune	File containing persistent attribute customization that will apply after a restart, if you run the bosboot command first.