Agent Configuration Utilities

The following Agent utilities describe how to run various configurations on the Agent.

ctmag

The ctmag utility enables you manage Agent configuration parameters, and view and modify many operating system parameters. If the user that runs the utility is not an Administrator, changes to Agent configuration parameters are not saved.

If more than one Agent is installed on the same host, run the command, as follows:
ctmag <Agent_Name>

ctmagcfg

The ctmagcfg utility interactively configures the Agents.

ctmagcfg Parameters

The following table describes the ctmagcfg utility parameters.

Parameter

Description

Diagnostic Level

Determines the Agent debug level.

Valid values: 0–4 (4 is the highest debug level for the Agent).

Default: 0 (no debug information is printed).

Comm Trace

Determines whether the communication packets that the Agent sends and receives from the Server are written to a file. If this parameter is set to 1, separate files are created for each request (whether job submissions or pings are sent from the Server).

This parameter can only be changed after you complete the installation.

Valid Values:

  • 1: On

  • 0: Off

Default: 0 (Off)

Days To Retain Log Files

Determines the number of days to retain Agent proclog files. After this period, the files are deleted by the New DayClosed A Control-M process that begins every day at midnight, adds jobs and folders to the Run Queue for the day that is about to begin, and removes jobs and folders from previous days. procedure.

Valid values: 1–99

Default: 1

Daily Log File Enabled

Determines whether the Agent writes job information to a log file. If this parameter is set to Y, separate files are created for each day.

The daily log filename is daily_ctmag_<YYYYMMDD>.log.

Valid Values:

  • Y: On

  • N: Off

Default: Y (On)

Tracker Event Port

 Determines the internal port used by the Agent Tracker process.

Logical Agent Name

 Defines the alias name of the Agent.

Tracker Polling Interval

Determines the number of seconds the Agent tracker process waits for incoming events from plug-insClosed A Control-M component that extends functionality to third-party applications like Hadoop or SAP and can be integrated with other jobs in a single workflow. (such as Control-M for Databases) before it rescans the status directory.

Valid Values: 1–86,400

Default: 60

TCP/IP Timeout

Determines the time the Agent internal processes wait for incoming messages from other Agent internal processes before it times out.

Locale

 (LATIN-1 Only) Describes the locale settings supported on this environment.

Protocol Version

Determines the Control-M/Server-Agent communication protocol version.

Valid Values: 12–14

To synchronize the protocol version value between the Control-M/Server and the Agent, press one of the following:

  • Y: Enables the Agent to synchronize with the Control-M/Server protocol version that is supported by the Agent.

    Allow up to 2 hours for the protocol version to synchronize.

    Your Control-M/Server must be version 9.0.20 or higher.

  • N: Enables you to choose a specific protocol version value, even though synchronization with the Control-M/Server is available.

Default: Y

Timeout for Agent utilities

Determines the maximum number of seconds that the Agent waits after sending a request to the Server. The interval must be longer than the TCP/IP Timeout parameter.

Default: 120

AutoEdit Inline

Controls the use of environment variables defined in an OS job flow. If this parameters is set to Y, Auto Edits are set as environment variables in the job.

Default: Y

ctmunixcfg

The ctmunixcfg utility enables you to interactively view and modify most of the Plug-in configuration parameters in the OS.dat file. This utility can also be accessed as a Java application.

ctmunixcfg Parameters

The following table describes the ctmunixcfg utility parameters.

Parameter

Description
Bourne Shell Flags

Determines the shell flag that is used to run the job script. For more information, see Shell Switch Parameters.

Valid Values:

  • -x

  • -v

  • n

Default: -x
Korn Shell Flags

Determines the shell flag that is used to run the job script. For more information, see Shell Switch Parameters.

Valid Values:

  • -x

  • -v

  • n

Default: -x
Sysout Name

Defines the prefix for the output filename.

Valid Values: MEMNAME
Temporary Scripts Saving

Enables you to save temporary scripts. By default, temporary scripts that are generated from jobs are deleted at the end of a job execution. If this value is set to Yes, temporary scripts are not deleted.

Valid Values: Yes or No

Default: No
Temporary Scripts Directory

Defines the default path for saving temporary scripts.

Valid Values: Any valid path on the Agent computer.

Default: $CONTROLM/runtime
Replace $0 by Filename

The $0 reserved variable is used in a script to retrieve the name of the script. This variable is automatically replaced by a filename before the script is run. For more information, see Reserved Variable $0.

Valid Values:

  • Y: Reserved variable $0 specifies whether instances of $0 in the job script should be replaced before the script is run.

  • N: Functionality is disabled

Default Printer

Defines the default printer for the job output.

Shell Switch Parameters

The following table describes the Shell switch parameters, which affect Agent processing.

Parameter

Description

-x

Enables Agent to submit the script as is. The script runs under the specified shell and prints commands and related arguments as they are executed.

In the output file, the command arguments contain the value of the variable and not the variable name. Each command is prefixed by the + (plus) sign, which is later used during an On statement post-processing phase of the job's output to distinguish between the different commands and their output.

-v

Enables Agent to parse the original script to a temporary script. The script commands are appended with an identifying string. This temporary script is then executed, where the -v switch causes the shell to print each command before its output.

The added identifying string is later used during an On statement post-processing phase of the job's output to distinguish between commands and their output.

n

Indicates that the script must be executed as is and no commands are included in the job’s output. As a result no On-statement processing is possible.

Shell Script Type Switch Examples

The following script uses the app, dbadmin, and stx111 parameters. The app parameter sets an environment variable. The script uses the dbadmin and stx111 parameters to call a utility that performs an action. The output of the job varies depending on the shell flag.

#!/bin/sh

DBNAME=$1

export DBNAME

dbrefresh -U $2 -P $3

exit $?

  • If the -x flag was set when running the sample script, the job produces the following output:

    DBNAME=app

    + export DBNAME

    DB refreshed

    + dbrefresh -U dbadmin -P stx111

    + exit 0

  • If the -v flag was set when running the sample script, the job produces the following output:

    #! /bin/sh -v

    CTM_RSVD=

    CTM_RSVD_START=

    CTM_RSVD_END=

    CTM0='/home2/ag620/refreshDB.sh'

    CTM00=$0

    DBNAME=$1 $CTM_RSVD

    export DBNAME $CTM_RSVD

    dbrefresh -U $2 -P $3 $CTM_RSVD

    DB refreshed

    exit $? $CTM_RSVD

  • If the n flag was set when running the sample script, the job produces the following output:

    DB refreshed

Reserved Variable $0

The $0 reserved variable can be used in a script to retrieve the name of the script, which is automatically replaced by a filename before the script runs. When a script runs as a job using the –v flag, it is parsed into a temporary script. For more information, see Shell Switch Parameters.

Any reference to $0 in the script is resolved to the temporary script name rather than the original script name, and the name of the original script is saved in the CTM0 variable. This differentiates between a script run from the command line and a script run from a job. To ensure that the $0 variable resolves to the original name when run from the command line and not the temporary script name, set the Translate_$0 flag using ctmunixcfg.

Setting the flag causes the Agent to replace any occurrence of $0 in the original script with $CTM0 when it parses the original script to the temporary script. This restores the original functionality of the script as if it ran from the command line.

The following example shows the dollar0.sh script, which is supposed to print out the script name.

#!/bin/sh

echo $0

When the script runs as part of a job using the -v flag, the name of the temporary script is printed.

#! /bin/sh -v

CTM_RSVD=

CTM_RSVD_START=

CTM_RSVD_END=

CTM0='/home/ag900/dollar0.sh'

CTM00=$0

echo $0 $CTM_RSVD

/tmp/ctm/CM_SH.11939

When the script runs in a Control-M/Server job using the -v flag and the Translate_$0 flag is set, the name of the original script is printed.

#! /bin/sh -v

CTM_RSVD=

CTM_RSVD_START=

CTM_RSVD_END=

CTM0='/home/ag900/dollar0.sh'

CTM00=$0

echo $CTM0 $CTM_RSVD

/home/ag90000/dollar0.sh

ctmwincfg

The ctmwincfg utility enables you to view and modify Application plug-in configuration parameters on Windows.

ctmwincfg Parameters

The following table describes the ctmwincfg utility parameters.

Parameter

Description

Logon as User

Determines which user account is used for the services to log into.

You must manually grant Logon as a Batch Job privileges to a new user.

Valid Values:

  • Y: Jobs are submitted with the permissions and environment variables of the specified user.

  • N: Jobs are submitted with the permissions and environment variables of the local system account.

Default: N

Logon Domain

The domain is determined by the value of this parameter if <domain> is not specified in <domain>\<username> in the Run_As parameter of the job definitionClosed The set of parameters that defines what the job does, when it runs, its prerequisites, and the post-processing actions that Control-M performs after the job completes execution.. If the domain is not specified in the Run_As parameter or this parameter, the user profile is searched in the trusted domains.

BMC recommends that you do not specify a value for Log in Domain.

Valid Values: Text

Default: Blank

Job Children Inside Job Object

Determines whether procedures invoked by a job are run outside the Job Object. If so, this prevents a situation in which the original job remains in executing mode until the invoked procedure completes.

Valid Values:

  • Y: All procedures invoked by the job are run inside the job object.

  • N: All procedures invoked by the job are run outside the job object.

Default: Y

Add Job Object Statistics to Output

Determines how to handle job object processing statistics.

Valid Values:

  • Y: Statistics are added to the end of the Output file.

  • N: Statistics are not added to the Output file.

Default: Y

Job Output Name

Determines the prefix for the Output filename.

Valid Values:

  • MEMNAME: The Output file prefix is the MEMNAME of the job.

  • JOBNAME: The Output file prefix is the JOBNAME of the job. This parameter can only be changed after completing the installation.

Wrap Parameters with Double Quotes

Determines how parameter values (%%PARMn....%%PARMx) are handled by the Agent on Windows.

Valid Values:

  • 1: This parameter is no longer relevant.

  • 2: Parameter values are always passed to the operating system without quotes. If quotes were specified in the job definition, they are removed before the parameter is passed by the Agent. If a parameter value contains a blank, the operating system may consider each string as a separate parameter.

  • 3: This parameter is no longer relevant.

  • 4: Parameters are passed to the operating system in exactly the same way that they were specified in the job definition. No quotes are added or removed.

Default: 4

Run User 'Logon Script'

Determines whether a user-defined logon script should be run by the Agent before running the standard user logon script.

Valid Values:

  • Y: The user-defined logon script runs, if it exists.

  • N: The user-defined logon script does not run.

Default: N

CJK Encoding

Determines the CJK encoding that the Agent uses to run jobs.

Valid Values: UTF-8, JAPANESE EUC, JAPANESE SHIFT-JIS, KOREAN EUC, SIMPLIFIED CHINESE GBK, SIMPLIFIED CHINESE GB, TRADITIONAL CHINESE EUC, TRADITIONAL CHINESE BIG5.

Default: UTF-8

For more information, see East Asian (CJK) Language Support Configuration.

Default Printer

Defines the default printer for job Output files.

Default: Blank space.

Echo Job Commands into Job Output

Determines whether to print commands in the Output of a job.

Valid Values:

  • Y: Implements ECHO_ON, which prints commands in the job Output.

  • N: Implements ECHO_OFF, which does not print commands in the job Output.

Default: Y

SMTP Parameters

 

ctmagcpk

The ctmagcpk utility enables you to change a password for a key and apply the new key to job owner credentials and keystores for every installed plug-in that supports the AES encryption algorithm.

You cannot execute this utility when the Agent is running (except when you use the -p option).

The command is as follows:
ctmagcpk [-f]|[-r]|[-i]|[-n]

Where:

  • -f: Forces FIPS-compliant algorithms for key and password generation.

  • -r: Enables a roll-back and restore action of a previously failed attempt to generate a password key.

  • -i: Install/upgrade flag. Must not be used unless instructed by BMC.

  • -n: No option. This is the same as executing without any command line option.

set_agent_mode

The set_agent_mode utility changes the permissions in several Agent files and directories, which enables you to run in one of the following modes on Linux:

  • Root Mode: Agent executes all submitted jobs without the need for the Run as UserClosed An OS account name that is used to execute jobs on the host. password.
  • Non-root Mode: Agent processes run with Agent account permissions. To run a job with a different Run as User, you must define the Run as User authentication settings, as described in Adding a Run as User

  • Sudo Mode: Agent processes run with Agent account permissions. To run a job with a different Run as User, you must define the Run as User in the operation system sudoers file.

    BMC recommends that you run the Agent in non-root mode.

Running the set_agent_mode Utility

This procedure describes how to run the set_agent_mode utility, which enables you to run the Agent in root, non-root, and sudo mode on Linux. You must run this utility as the root user.

Begin

  • Do one of the following:

    • Type the following command:
      set_agent_mode

      The menu appears.

      Select one of the options as described in set_agent_mode Options.

    • To run the utility silently, type the following command:
      set_agent_mode –u <Agent_Owner> -o <Options> -r <restart Y|N>

      For more information, see set_agent_mode Silent Parameters.

    The Agent runs in the mode you selected until you change it, even after the Agent is restarted.

set_agent_mode Options

The following table lists the set_agent_mode options.

Option

Description

Enable Root Mode

Enables the Agent to run jobs by any user without a password.

The Agent process is started under Root.

The su OS command is used.

Enable Non-root Mode

Enables the Agent to run jobs by any user with the requirement to enter a password.

The Agent process is started under the Agent account.

The BMC su command is used.

Enable Sudo Mode

Enables the Agent to run jobs by any user.

The Agent process is started under the Agent account.

  • You must have sudo version 1.7 or above.

  • The user needs to be granted the appropriate sudo permissions in the /etc/sudoers file.

  • NOPASSWD must be added to Agent account in the /etc/sudoers file.

  • All commands must be directed to all target job owner accounts.

  • The Defaults requiretty entry should be remarked in the /etc/sudoers file.

  • To enable the Agent owner to run jobs only on target accounts target_user_1 and target_user_2, set the following row in the /etc/sudoers file:
    <Agent_owner_account> ALL=(target_user_1, target_user_2) NOPASSWD: ALL

  • To enable the Agent owner to run jobs on all target accounts, set the following row in the /etc/sudoers file:

    <Agent_owner_account> ALL=(ALL) NOPASSWD: ALL

You can restrict the executables that can be run using sudo.

To restrict sudo to run only Control-M jobs and not require a password, do the following:

  • Allow restrictions to be made in the Agent with the following command:
    ctmcfg -TABLE OS -ACTION update -PARAMETER SUDO_RESTRICT -VALUE Y

  • To allow the Agent to run executables as a different user, add the following line to the /etc/sudoers file:
    <Agent_owner_account> ALL=(ALL) NOPASSWD: <Agent Path>/ctm/runtime/*

    By default, an Agent uses the -i flag with sudo to load user environment settings, such as the .profile setting.

    If sudo is executed by an Agent with a restriction, you must disable the -i flag.

    To disable the -i flag, set the SUDO_USE_I_FLAG parameter to N with the following command:
    ctmcfg -TABLE OS -ACTION update -PARAMETER SUDO_USE_I_FLAG -VALUE N

Prepare the Agent for Non-root Uninstall

Returns the Agent to the state it was in after the installation, and removes it from the /etc/ctm.conf file.

set_agent_mode Silent Parameters

The following table describes the set_agent_mode silent parameters.

Parameter

Description

-u

 Defines the name of the Agent owner user.

-o

Enables you to select one of the following options:

  • 1: Enables non-root mode.

  • 2: Enables root mode.

  • 3: Enables sudo mode.

  • 4: Prepares the Agent for non-root uninstall.

For more information, see set_agent_mode Options.

-r

Enables you to restart the Agent.

Valid Values:

  • Y: Restarts the Agent.

  • N: Does not restart the Agent.