Reference Guide › Utilities › secons Utility › secons -v Function—Control Instrumentation Run-time Settings on Windows

secons -v Function—Control Instrumentation Run-time Settings on Windows

Valid on Windows

The secons utility controls CA Access Control instrumentation run-time settings. You can use the utility to load an external DLL library into an active process and modify the run-time tracing configuration of CA Access Control instrumentation plug-ins. You must have the ADMIN or OPERATOR attribute to execute this command.

This command has the following format to load a DLL library:

secons -v target load "dll_name"

This command has the following format to enable or disable the trace on a CA Access Control instrumentation plug-in:

secons -v target trace plugin_name {trace:enable|trace:disable}:{file:"tracefile_path"|debug}

Note: CA Access Control does not start the trace until the trace is correctly configured.

This command has the following format to configure the trace on a CA Access Control instrumentation plug-in:

secons -v target trace plugin_name trace:option:{sources:{1 | 4} | filtering:value | filecyclic:{0 | 1} | filelimit:value }

debug

Specifies that the command enables or disables tracing to the debug output channel.

file:"tracefile_path"

Defines the full path to the file that CA Access Control writes the trace to.

Note: If you specify the trace:disable parameter, CA Access Control ignores any value that you specify for the file:"tracefile_path" parameter.

filecyclic:{0 | 1}

Specifies if cyclic file tracing is enabled. If you enable cyclic file tracing, when the size of the trace file reaches the specified maximum size, CA Access Control returns to the start of the trace file and continues writing the trace.

This parameter has the following values:

0-Disable cyclic file tracing

1-Enable cyclic file tracing

filelimit:value

Defines the maximum size, in bytes, of the trace file. A value of 0 means the trace file has no maximum size.

filtering:value

Defines the bitwise filter mask that filters the trace for the specified instrumentation plug-in. CA Access Control does not write filtered events to the trace file.

Note: To specify no filtering, that is, to specify that CA Access Control writes all events to the trace, use the following value: 0xFFFFFFFF. All other values for this parameter depend on the plug-in that you specify.

load "dll_name"

Specifies to load the specified DLL into the target process. The DLL operating environment and the target process operating environment must be identical. For example, if you specify a 32-bit process as the target process, the DLL must also be 32-bit.

Important! The DLL must be located in the ACInstallDir\bin folder.

sources:{1 | 4}

Specifies where CA Access Control outputs the trace.

This parameter has the following values:

1-Output to file

4-Output to debug API trace

target

Defines the target process or processes. This parameter has one of the following values:

all_32bit

Specifies to send the command to all 32-bit processes running on the computer.

all_64bit

Specifies to send the command to all 64-bit processes running on the computer.

PID

Defines the process ID of the target process. The target process must be running on the computer.

process_name

Defines a mask that identifies the names of the target process. The target process must be running on the computer. For example, if you specify cmd.exe for this parameter and there are three instances of cmd.exe running on the computer, CA Access Control applies the command to all three processes.

trace plugin_name

Specifies to modify the run-time tracing configuration for the CA Access Control instrumentation plug-in named module_name, for example, cainstrm or stopplg.

Note: You must specify the DLL name of the plug-in. If you upgrade an instrumentation plug-in and the name of the DLL for the plug-in changes, you must specify the name of the new DLL in the command. For example, if you upgrade the cainstrm plug-in and the name of the upgraded DLL for the plug-in is cainstrm2.dll, you must specify cainstrm2 as plugin_name.

trace:disable

Specifies to enable the trace on the target plug-in.

trace:enable

Specifies to disable the trace on the target plug-in.

Note: This parameter changes the status of the trace enabled flag in run time. CA Access Control does not begin the trace until the trace is correctly configured.

trace:option

Specifies to configure the trace on the target plug-in.

Example: Enable Tracing to the Debug Output Channel

The following command changes the status of the trace enabled flag in run time for all files in the stopplg plug-in that are in 32-bit processes running on the computer. CA Access Control does not begin the trace until the trace is correctly configured:

secons -v all_32bit trace stopplg trace:enable:debug

Example: Apply a Trace Filtering Mask to a Plug-in

The following command applies a trace filtering mask to all files in the cainstrm plug-in that are in the process with PID 362:

secons -v 362 trace "cainstrm trace:option:filtering:4294967295"