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

Valid on Windows
capamsc141
Valid on Windows
The secons utility controls 
Privileged Access Manager
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 
Privileged Access Manager
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 
Privileged Access Manager
instrumentation plug-in:
secons -v target trace plugin_name {trace:enable|trace:disable}:{file:"tracefile_path"|debug}
 
Privileged Access Manager
does not start the trace until the trace is correctly configured.
This command has the following format to configure the trace on a 
Privileged Access Manager
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 
    Privileged Access Manager
    writes the trace to.
    If you specify the trace:disable parameter,
    Privileged Access Manager
    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, 
    Privileged Access Manager
    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. 
    Privileged Access Manager
    does not write filtered events to the trace file.
    To specify no filtering, that is, to specify that
    Privileged Access Manager
    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.
    The DLL must be located in the
    ACInstallDir
    \bin folder.
  • sources:{1 | 4}
    Specifies where 
    Privileged Access Manager
    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, 
      Privileged Access Manager
      applies the command to all three processes.
  • trace
    plugin_name
    Specifies to modify the run-time tracing configuration for the 
    Privileged Access Manager
    instrumentation plug-in named
    module_name
    , for example, cainstrm or stopplg.
    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.
    This parameter changes the status of the trace enabled flag in run time. 
    Privileged Access Manager
    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. 
Privileged Access Manager
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"