ctctrl Command

Purpose

Modifies or displays the trace attributes of system components. You can specify persistent attribute values for components that have not yet been created.

Syntax

To modify the trace attributes of some or all components, use the following command:

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

To dump component buffers into files, use the following command:

ctctrl [-r u] {-D [-d dirName] } ComponentSelector ...

To specify persistent attribute values for components that have not been created yet, use the following command:

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

To specify persistent attribute values that will take effect after the next restart, use the following command:

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

To delete persistent attribute customizations, use the following command:

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

To query trace attributes of existing components or to query existing persistent attribute customization, use the following command:

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

To display a usage message, use the following command:

ctctrl {-h | -?}

To enable or disable memory tracing for all components persistently, use the following command:

ctctrl -P {memtraceon | memtraceoff}

The values of the ComponentSelector parameter are as follows:

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

Each list consists of one or more patterns that are separated by blank spaces or commas. Patterns can contain special characters as described by the fnmatch subroutine. You can use the following pattern characters:

?
*
[ ]

You cannot use character classes and collation sequences inside brackets ([ ]). Specifying -c all selects all components, if no other ComponentSelector parameter is specified.

Description

The ctctrl command modifies or displays the trace settings of some or all components. Components are selected by name, by alias, or by type or subtype. The ctctrl command can also be used with the -p or -P flag to specify persistent attribute customization. See the Persistent Customizations section.

To enable or disable component-level tracing for all components immediately and persistently, specify the memtraceon or memtraceoff subcommand with the -P flag. You cannot specify other flags or subcommands with the -P flag. You must use the bosboot command to make settings persistent across boots.

The modified attribute depends on the subcommand that is passed to the ctctrl command. Multiple subcommands can be used in a single ctctrl invocation. You can specify the following subcommands:

Item	Description
memtraceon	Turns on memory trace mode.
memtraceoff	Turns off memory trace mode.
memtraceresume	Resumes memory trace mode.
memtracesuspend	Suspends the memory trace mode.
memtracebufsize=sz	Changes the size of the private buffer allocated in memory trace mode.
memtraceminimal	Changes memory trace mode level to `1`.
memtracenormal	Changes memory trace mode level to `3`.
memtracedetail	Changes memory trace mode level to `7`.
memtracemax	Changes the level of the memory trace mode to the maximum detail level `9`.
memtracelevel=d	Changes the level of trace of the memory trace mode. Sets it to the specified level.
memtracefilltime	Displays the data retention time (that is, the estimated time to fill the private memory buffer). This is available only if the memory trace mode is on.
systraceon	Turns on the tracing through the system trace.
systraceoff	Turns off the tracing through the system trace.
systraceminimal	Changes system trace mode level to `1`.
systracenormal	Changes system trace mode level to `3`.
systracedetail	Changes system trace mode level to `7`.
systracemax	Changes the level of system trace mode to the maximum detail level `9`.
systracelevel=d	Changes the level of trace used to trace through the system trace. Sets it to the specified value.

Note: The memtracesuspend, memtraceresume, and memtracefilltime subcommands cannot be used with the -p or the -P flag, because these subcommands cannot be used in persistent customizations.

Other subcommands that are not in the previous list can be recognized by individual components. A subcommand that is not recognized by a component is ignored.

Current attribute values can be displayed by using the -q flag. If you do not specify the ComponentSelector parameter, attribute values are displayed for all components that use component-level tracing.

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 the AIX® operating system. 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 the AIX operating system for the customizations to take effect.

The component specified by the ComponentSelectors parameter with the -p and -P flags 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 components are used. If conflicting attribute values are specified in multiple customizations, the last customization takes precedence. If a customization already exists for a specified component, the new customization replaces the old one.

You can specify multiple components with the ComponentSelectors parameter when persistent customizations are specified. In all cases, using multiple selectors is equivalent to specifying multiple commands, each with a single component selector. For example, the customization ctctrl -p -l hdisk0 -l hdisk1 memtracenormal is equivalent to the following two customizations:

ctctrl -p -l hdisk0 memtracenormal
ctctrl -p -l hdisk1 memtracenormal

When you use the -D flag, a snapshot of trace buffers for selected components is dumped into files. The default directory is /var/adm/ras/trc_ct, but you can specify an optional destination directory. One trace file per component is used; all files are named with the full components names. The files are generated and managed in the same way the trace command does for multiple processor files.

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

Persistent customizations that are deleted with the -x and -P flags remain in effect unless you run the bosboot command and restart the AIX operating system. You can delete a persistent customization that is created with the -P flag after the restart by using the -x and -p flags. In this case, the customization are active again if you restart the AIX operating system.

If you do not know the customizations that have been made but want to restore the default system setting, you can use one of the following ways:

In the /var/adm/ras/raspertune file, delete the lines relevant to the customizations. Then run the bosboot command and restart the AIX operating system.
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 11. Run the bosboot command and restart the AIX operating system.

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 ctctrl -p -l hdisk0 -u -r memtracedetail is equivalent to the following two separate customizations:

ctctrl -p -l hdisk0 -u memtracedetail
ctctrl -p -l hdisk0 -r memtracedetail

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

ctctrl -p -l hdisk0 memtracedetail
ctctrl -p -l hdisk0 -r memtracedetail
ctctrl -p -l hdisk0 -u memtracedetail

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.

You can query persistent customizations 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 that you originally specified with the -r flag. Without the -r flag, the -q and -p flags display the persistent customizations that you specify with or without the -u flag.

You can specify multiple subcommands for a persistent customization. If you specify conflicting subcommands, the last subcommand is used. For example, the memtracenormal and memtracedetail subcommands specify different values for the same error-checking attribute, so the last specified subcommand is used.

Flags

Item	Description
-n	Applies subcommands immediately. This flag is the default if neither the -p nor the -P flag is used.
-c componentList	Specifies a list of component names. Separate the names in the list using a comma or blank space. The -c all flag selects all components if it is the only ComponentSelector.
-D	Takes a snapshot of the component's private memory buffer and dumps it into files (one file per component). The default output directory can be changed with the -d flag.
-d dirName	Specifies the directory used for the dump. The default directory is /var/adm/ras/trc_ct. If some files already exist, they are overwritten by the new dump request. The -p and -P flags are mutually exclusive with the -d flag.
-h or -?	Displays a usage message.
-l aliasList	Specifies a list of component aliases. Separate the aliases using a comma or blank space.
-P	Specifies subcommands that will persist across restarts. You must run the bosboot command and restart AIX for these commands to be used.
-x	Deletes the persistent customization for the specified components. The ComponentSelector(s) must be entered exactly as they were entered when the customization was originally specified.
-p	Specifies persistent subcommands. The specified subcommands are applied to newly created components.
-q	Displays the component trace settings of the components. This flag can also be used with the -p or -P flag to display persistent customizations.
-r	Applies the subcommands recursively to all subcomponents of the selected components.
-t type_subtype	Specifies a list of type or type_subtype names. Separate the names using a comma or blank space. Valid type names include `device`, `filesystem`, `network`, `services`, `storage`, and `ui`. A complete list of type and type_subtype names is in the /usr/include/sys/ras_base.h header file.
-u	Applies the subcommands recursively to the ancestors of the specified components.

Note: You can use the -u and -r flags together. You can use multiple -c, -l, and -t flags on the command line.

Exit Status

Item	Description
0	The command completes successfully.
>0	An error occurs.

Examples

To dump the contents of all Component Trace buffers, use the following command:
```
ctctrl -D -c all
```
To dump the contents of the mbuf Component Trace buffer to /tmp, use the following command:
```
ctctrl -D -d /tmp -c mbuf
```
To query the state of all Component Trace aware components, use the following command:
```
ctctrl -q
```
To query the state of only the netinet components, use the following command:
```
ctctrl -c netinet -q -r
```
To turn on memory tracing mode for the socket component, use the following command:
```
ctctrl memtraceon -c socket
```
To persistently turn off component tracing for all components, use the following command:
```
ctctrl -P memtraceoff
```
Note: A bosboot is required to make the command persistent across boots.
To specify a persistent customization for the userdata component of new JFS2 file systems, use the following command:
```
ctctrl -p -c 'jfs2.filesystem.*.userdata' memtraceminimal
```
Note: The existing userdata components are not affected.
To specify a customization that will persist across restarts, use the following command:
```
ctctrl -P -c 'jfs2.filesystem.*.userdata' memtraceminimal
```
If you run the bosboot command and restart AIX, minimal component tracing will be in effect for all JFS2 userdata components.
To set minimal component tracing for all JFS2 userdata components, use the following command:
```
ctctrl -npP -c 'jfs2.filesystem.*.userdata' memtraceminimal
```
To specify multiple persistent attribute values for the ethernet component, use the following command:
```
ctctrl -P -c ethernet memtraceminimal memtracebufsize=1m
```
To delete the customization specified in example 7, use the following command:
```
ctctrl -p -x -c 'jfs2.filesystem.*.userdata'
```
To list all persistent, recursive-down attribute customization, use the following command:
```
ctctrl -q -p -r
```
To enable all component traces for the netmalloc component, use the following command:
```
ctctrl memtracedetail -c netmalloc
```
or
```
ctctrl memtracelevel=7 -c netmalloc
```
To collect net_malloc_police trace events in the component trace buffer, use the following command:
```
ctctrl  memtracedetail -c netmalloc.police
```
Note: On AIX 5.3 TL 5 and above, with the new RAS framework, for a 32 bit kernel, the component trace buffer space is limited to 8MB.

Location

/usr/sbin/ctctrl

Files

Item	Description
/var/adm/ras/raspertune	A file containing persistent attribute customization that will be applied after a restart, if you run the bosboot command first.
/var/adm/ras/trc_ct	The default directory where all snapshots of buffers are saved.
trc_ct.master	A master trace file that points to the trace files of all components.