Agent Configuration Utilities

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

ctmag

The Agent Configuration (ctmag) utility is a Java application used to maintain Agent configuration parameters, and to view and modify most of the operating system parameters. If the user running the utility is not an administrator, changes made to Agent configuration parameters will not be saved.

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

ctmag <agentName>.

ctmagcfg

The ctmagcfg interactively configures the Agents.

ctmagcfg Parameters

The following table describes ctmagcfg parameters.

Parameter

Description

Diagnostic Level

Determines the Agent debug level.

Valid values: 0-4 (4: highest debug level for the Agent)

Default: 0, (no debug information is printed)

Comm Trace

Determines whether communication packets that the Agent sends to and receives from the Server are written to a file. If set to 1, separate files are created for each request (job submission or ping sent from the Server). This parameter can only be changed after completing 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 DayClosedA Control-M process that occurs at midnight at the beginning of each day, which adds the 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 set to Y, separate files are created for each day. Daily log file name 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-insClosedA Control-M component that extends functionality to third-party applications like Hadoop or SAP and integrates plug-in jobs with other jobs into a single workflow that send events (such as Databases) before going back to scan the status directory.

Valid values: 1-86400

Default: 60

TCP/IP Timeout

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

Locale

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

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 supported by the Agent.

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

    The 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 the Agent waits after sending a request to Server. The interval must be longer than the TCP/IP Timeout.

Default: 120

AutoEdit Inline

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

Default: Y

ctmunixcfg

The ctmunixcfg 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 file name.

Valid values: MEMNAME
Temporary Scripts Saving

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

Valid values: Yes

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:

  • 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 Default printer for 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 + 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 for Windows.

ctmwincfg parameters

The following table describes the ctmwincfg utility parameters.

Parameter

Description

Logon As User

Flag that specifies which user account is used for the services to log into.

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 definitionClosedThe set of parameters that defines what the job does, when it must run, its prerequisites to run, and post-processing actions for Control-M to perform after its completion (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

Flag that specifies if 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. Default.

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

Default: Y

Add Job Object Statistics to Output

Flag that indicates how to handle job object processing statistics.

Valid values:

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

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

Default: Y

Job Output Name

Flag that determines the prefix for the Output file name.

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

Indication of how parameter values (%%PARMn....%%PARMx) are handled by the Agent for Microsoft 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 onward by the agent. In this case, 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 in this case.

Default: 4

Run user 'Logon Script'

Indication if a user-defined logon script should be run by the Control-M/Agent before running the standard user logon script.

Valid values:

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

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

Default: N

CJK Encoding

Determines the CJK encoding used by Control-M/Agent 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

Default Printer

Default printer for job Output files. Type a printer name in the field box or select a name from the list box.

Default: Blank

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 key's password and apply the new key to job owners credentials and keystores for all installed plug-ins that support the AES algorithm.

This utility cannot be executed when the Agent is running (except when using the -p option).

The command is as follows:

ctmagcpk [-f]|[-r]|[-i]|[-p]|[-n]

Where:

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

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

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

  • -p Print encryption attributes.

  • -n No option. Same as executing without any command line option.

ag_change_password

The ag_change_password utility enables you to automate password changes of Application Plug-ins Connection Profiles.

Running the ag_change_password utility

This procedure describes how to run the ag_change_password utility, which enables you to automate password changes of Application Plug-Ins Connection Profiles.

Begin

  • From a command line, type the following:

    ag_change_password -application_type <application_type>

    [-account <connection_profile_name>]

    [-host <host_name>]

    -user <user_name>

    -old_password <old_password>

    -new_password <new_password>

    [-agent <agent_instance_name>]

ag_change_password parameters

The following table describes the parameters in the ag_change_password utility:

Wildcards must be enclosed with single quotations (' ') or with double quotations " " according to the requirements of the Linux shell where the ag_change_password utility is activated.

Parameter

Description

-application_type

The type of Application Add-on installed on this agent. Valid values are:

  • CLOUD – Control-M for Cloud

  • DATABASE – Control-M for Database

  • ETL_INFA – Control-M for Informatica

  • PS8 – Control-M for PeopleSoft

  • SAP – Control-M for SAP

  • BACKUP: Control-M for Backup

  • DATASTAGE: Control-M for Datastage

  • JAVA MSG WS: Control-M for Web Services, Java and Messaging

-account

 The Application Add-on changes the password in the connection_profile_name connection profile. Optional. If no account is specified, all accounts are checked. The * wildcard is supported..

-host

 Match an account where host field is applicable. This parameter is relevant only when -application FILE_TRANS is specified. Optional. The * wildcard is supported.

-user

 User account name. The * wildcard is supported. See the note below this table. When the value for the -application parameter is CLOUD and the application is Amazon Elastic Compute Cloud (Amazon EC2), then use Amazon Access Key instead of the user name.

-old_password

 User password.

-new_password

 New user password.

-agent

 (Windows only) Name of the Control-M/Agent. If not specified, the default agent is used. Optional.

ctmgetcm

The ctmgetcm utility is used to collect, store and display application server information from Agents.

  • When the action parameter is set to GET, application server information is collected, stored in a folder in the Control-M/Server database, and displayed.

  • When the action parameter is set to VIEW, previously stored application server information is displayed.

Control-M information is updated only after ctmgetcm runs, or each time ctmgetcm is reconfigured.

Running the ctmgetcm utility

This procedure describes how to collect, store and display application server information from Control‑M/Agents using the ctmgetcm utility.

Begin

  • Do one of the following:

    • To run the utility interactively, type the following command:

      ctmgetcm

    • To run the utility as a single prompt, type the following command:

      ctmgetcm -HOST agent -APPLTYPE OS -ACTION <get|view>

ctmgetcm parameters

The following table lists the ctmgetcm utility parameters:

Parameter

Description

-HOST

 Defines the host name of the agent computer.

-APPLTYPE

Defines the name of the application server, such as SAP.

A wildcard character can be used to specify more than one application:

  • Specify * to retrieve information for all applications.

  • Specify O* to retrieve information for all applications beginning with O (for example, ORA or OS).

  • OS can be specified to return information about the Application Add-on for the current operating system.

-ACTION

Indicates the action that the ctmgetcm utility should perform.

Valid values are:

  • GET: Collect and display updated application information from the specified Agent.

  • VIEW: Display application server information that was previously collected from the specified Agent computer. This action displays only information that was retrieved previously using a GET action.

set_agent_mode

The Agent works in one of the following modes on Linux:

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

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

    BMC recommends using non-root mode.

Use the set_agent_mode utility to enable root, non-root and Sudo mode on Linux. The utility changes the permissions of several Agent files and directories to allow the Agent to work in the mode that is selected. This utility must be run by the root user and only needs to run once to set a mode.

The Agent uses the same mode until it is changed, regardless of whether the Agent is started or restarted.

Running the set_agent_mode Utility

This procedure describes how to run the set_agent_mode utility, which enables you to enable or disable the non-root mode of the Agent on Linux

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 <agentOwner> -o <Options> -r <restart Y|N>

      For more information, see set_agent_mode silent parameters.

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, 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