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 <agentName>
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:
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 Day 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 file name is daily_ctmag_<YYYYMMDD>.log. Valid Values:
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-ins 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:
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:
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:
Default: -x |
Sysout Name |
Defines the prefix for the output file name. 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 File Name |
The $0 reserved variable is used in a script to retrieve the name of the script. This variable is automatically replaced by a file name before the script is run. For more information, see Reserved Variable $0. Valid Values:
|
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 file name 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:
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 definition The set of parameters that defines what the job does, when it runs, its prerequisites, and the post-processing actions Control-M performs after it ends (also called a job processing definition).. 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:
Default: Y |
Add Job Object Statistics to Output |
Determines how to handle job object processing statistics. Valid Values:
Default: Y |
Job Output Name |
Determines the prefix for the Output file name. Valid Values:
|
Wrap Parameters with Double Quotes |
Determines how parameter values (%%PARMn....%%PARMx) are handled by the Agent on Windows. Valid Values:
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:
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:
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.
The command is as follows:
ctmagcpk [-f]|[-r]
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 User 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_modeThe 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 <agentOwner> -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 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:
|
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:
For more information, see set_agent_mode Options. |
-r |
Enables you to restart the Agent. Valid Values:
|