Agent Management

Agents submit jobs for execution on the host, monitor jobs, and perform post-processing analysis of completed jobs. The job completion status and the post-processing analysis results are transmitted back to the Server.

You can install multiple Agents, which are managed by a Control-M/Server that assigns jobs to an Agent name that identifies the host.

You can also run and execute jobs on hosts where Control-M/Agent is not installed, as described in Agentless Hosts.

If the Agent is installed on Linux, BMC recommends you use non-root mode. For more information, see set_agent_mode.

In the Configuration domain, you can install, monitor, search, and manage Agents in your environment.

The following describes the specific Agent actions you can perform:

Install: Installs the Agent on your environment, as described in Agent Installation.
Add: Adds an Agent to your environment, as described in Adding an Agent.
Edit: Enables you to configure the following Agent parameters, as described in Configuring Agent Parameters.
Ping: Tests the connectivity to the Agent.
Recycle: Shuts down and starts up the Agent.
Disable: Disables all Agent actions.
Delete: Deletes the Agent from your environment. To fully remove it, you must uninstall the Agent from the host.

Automatic Agent and Agentless Host Discovery

Automatic discovery enables you to automatically discover an Agent that was installed but not added to the Agent list in the Configuration domain. Control-M searches for existing Agents in your environment when you run a job with a user-defined hostname. If Control-M cannot find an Agent in your environment with the defined hostname, Control-M then automatically discovers and adds this Agent to the Agents list in the Configuration domain after it verifies that Control-M/Agent is installed. However, if Control-M/Agent is not installed on the defined hostname, Control-M then automatically applies the default Agentless Host settings to the host and adds it as an Agentless Host.

This option is enabled by default. To disable this ability, you must set the HOST_AUTODISCOVER system parameter to N, as described in Scheduling and Execution Parameters.

To define default Agentless Host settings, see Defining Default Agentless Host Settings.

Adding an Agent

This procedure describes how to add an Agent component, which enables you to connect it to a self-hosted Control-M/Server via specific communication parameters. After you add the Agent to your environment, you can define and run jobs on the Agent through the Control-M/Server that manages it.

Before You Begin

Install the Agent, as described in Agent Installation.

Begin

From the icon, select Configuration.

The Configuration domain opens.
From the drop-down list, select Agents.

The Agents tab ppears.
Click Add Agent.

The Add Agent dialogue box appears.
For each field, define the required parameters, as described in Agent General Parameters.
(Optional) Click Test to test the Agent connection.

The test completes successfully.
Click Add.

The Agent appears in the Agents tab table.

Configuring Agent Parameters

This procedure describes how to configure all Agent parameters.

Begin

From the icon, select Configuration.

The Configuration domain opens.
From the drop-down list, select Agents.

The Agents tab appears.
Click the Agent you want to edit.

The Edit Agent dialogue tab appears.
Select the Advanced tab.
In each field, define the required parameters, as described in the following:

Agent General Parameters

The following table describes Agent General parameters.

Parameter	Description
Server	Defines the name of the Server that sends job requests to the Agent. You cannot modify this parameter.
Agent Name	Defines the name of the host where the Agent is installed. You cannot modify this parameter. The Agent name is defined during the Agent installation and cannot be changed later. Latin-1 special characters are not supported.
Tag	Defines a logical name that is used to label specific Agents into a group with a specific authorization level. You can apply a specific tag to an Agent, as described in Installing an Agent, or you can define your own tag with the * character if you have the correct permissions.

Parameter

Description

Server

Defines the name of the Server that sends job requests to the Agent.

You cannot modify this parameter.

Agent Name

Defines the name of the host where the Agent is installed.

You cannot modify this parameter. The Agent name is defined during the Agent installation and cannot be changed later.

Latin-1 special characters are not supported.

Tag

Defines a logical name that is used to label specific Agents into a group with a specific authorization level. You can apply a specific tag to an Agent, as described in Installing an Agent, or you can define your own tag with the * character if you have the correct permissions.

Communication Parameters

The following table describes the Agent communication parameters.

Field	Description
Agent to Server Port Number	Determines the port number between 1024 and 65535 that receives data from the Agent host. Verify that this port is not used for any other purpose. This value must match the Agent-to-Server Port Number in Control-M/Server. The value is the COMTIMOUT communication job-tracking timeout in seconds. Valid Values: Between 1024 and 65535 inclusive Default: 7005 7005/30 Increasing the Timeout value reduces Agent performance.
Primary Server	Defines the hostname of the host where the current Control-M/Server submits jobs to the Agent.
Authorized Servers	Defines a list of backup servers which can replace the primary server if it fails. The Agent only accepts requests from servers on this list. You cannot submit jobs to the same Agent if there is more than one active Control-M/Server. Another Agent instance must be installed with unique ports to support this configuration or job status updates corrupt.
Check Interval	Determines the number of seconds between status checks for each Agent that communicates with the Control-M/Server. If you decrease the default value, it might impact Control-M/Server performance. Default: 7,200 (2 hours)
Retry Interval	Determines the number of seconds between attempts to communicate with an Agent host whose status is Unavailable. If you decrease the default value, it might impact Control-M/Server performance. Default: 90
Unavailability Shout Urgency	Defines the urgency level of a message sent with high priority when an Agent has an Unavailable status. Urgent messages are sent with a special indication so that the recipient of the message is aware of the urgency.
Communication Timeout	Determines the maximum number of seconds that the Control-M/Server attempts to connect to the Agent before the Agent is set to Unavailable. If you decrease the default value, it impact Control-M/Server performance. Default: 120
TCP/IP Timeout	Determines the timeout used by the Agent when listening on the Server to Agent port number before timing out and performing housekeeping tasks
Maximum Retries	Determines the number of times the Control-M/Server attempts to connect to the Agent before the Agent is set to Unavailable.
Logical Agent Name	Defines a logical or alias name for the Agent. If you have more than one Agent on the same host that connects to the same Control-M/Server, you must use this parameter to uniquely identify each Agent. The value must be the same as the value in the Control-M/Server host. The logical name is used when the Agent initiates the communication to the Control-M/Server with the output from Agent utilities and in messages sent to the Control-M/Server.
Listen to Network Interface	Determines which network interface the Agent is listening on. It can be set to a specific hostname or IP address so that the Agent port is not opened in the other interfaces.
Secure Socket Layer	Determines whether SSL is used to encrypt the communication between Control-M/Server and the Agent.

Persistent Connection Parameters

The following table describes the persistent connection parameters.

Field	Description
Persistent Connection	Determines whether to connect to a specific Agent with either a persistent or transient connection. The connection between Control-M/Server and Agent is constant and can be initiated by both. When the Agent starts up, the Agent Router process is started and acts as a broker between the other Agent components and Control-M/Server. The Agent Router process allows Control-M/Server to maintain a constant connection with the Agent. However, when Control-M/Server sits behind a firewall, the Agent Router cannot initiate the connection with Control-M/Server. After the Control-M/Server creates the connection to the Agent Router, the Agent Tracker and Agent Utilities processes use this connection to communicate with Control-M/Server.
Maximum Disconnect Time	Determines the maximum number of seconds that the Control-M/Server allows an Agent to be disconnected before it initiates a session. This parameter is relevant only if the Allow Agent to Initiate a Session parameter on the Agent is set to NO. Valid Values: 30–86,400 Default: 300
Session Idle Timeout	Determines the maximum number of seconds that a session can be idle before Control-M/Server terminates it. Valid Values: 30–86,400 Default: 900
Allow Agent Disconnection	Determines if the current connection to this Agent can be disconnected when the maximum number of concurrent sessions is reached. Allowing a persistent connection on a Agent to disconnect requires the connection to be reestablished before communication with the Agent can continue. If you run time-sensitive jobs on the Agent, you might want to select No. Default: Yes
Allow Agent to Initiate a Session	Determines if the Agent can open a connection to the Control-M/Server when working in Persistent Connection mode. If the Agent is outside a firewall and the Agent to Server port is blocked, set this parameter to No. Default: Yes

Windows Job Submission and Tracking Parameters

The following table describes the Windows job submission and tracking parameters.

Field	Description
Run Job Owner's Logon Script	Determines whether the Agent runs the Log in script defined by the system Administrator before each job. Default: No
Wait for Child Processes to Complete	Determines whether the job ends when all sub-processes exit or waits until the main job process exits. BMC recommends you select Yes, when the Agent is used to start background applications. Default: Yes
Echo Job Commands into Output	Determines whether to print commands in the job output. Default: Yes
Foreign Language Support	Determines whether CJK or LATIN-1 is supported.
Application Locale	Determines the LATIN-1encoding used by the Agent to run jobs.
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. that send events, such as Control-M for Databases, before going back to scan the status directory. Default: 60

Linux Job Submission and Tracking Parameters

The following table describes the Linux job submission and tracking parameters.

Field	Description
Korn Shell (ksh) Flags	Determines the shell flag that is used to run the job script. Valid Values: -x, -v, n Default: -x
Bourne Shell Flags	Determines the shell flag that is used to run the job script Valid Values: -x, -v, n Default: -x
Temporary Scripts Saving	Determines whether 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 No Default: No
Tracker Polling Interval	Determines the number of seconds the Agent tracker process waits for incoming events from plug-ins that send events, such as Control-M for Databases, before going back to scan the status directory. Default: 60
Agent's Account Owner	Determines whether jobs are submitted as the Agent account owner or root.

Output Parameters

The following table describes the output parameters.

Field	Description
Days to Retain OUTPUT files	Determines the number of days that job output files are retained for jobs executed by Agent hosts. After this period, the New Day A Control-M process that begins every day at 7:00 AM, 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 deletes all expired job output files. This parameter also affects the number of days that archived Viewpoints A customizable view of job flows in the Monitoring domain. are saved.
Default Printer	Defines the default printer for job output (OUTPUT)
OUTPUT Name	Determines one of the following prefix options for the output filename: memname Jobname

Field

Description

Days to Retain OUTPUT files

Determines the number of days that job output files are retained for jobs executed by Agent hosts. After this period, the New Day A Control-M process that begins every day at 7:00 AM, 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 deletes all expired job output files.

This parameter also affects the number of days that archived Viewpoints A customizable view of job flows in the Monitoring domain. are saved.

Default Printer

Defines the default printer for job output (OUTPUT)

OUTPUT Name

Determines one of the following prefix options for the output filename:

memname
Jobname

Security Parameters

The following table describes the Windows security parameters.

Field	Description
Logon Domain	Defines the logon domain name if <domain> is not defined 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 that Control-M performs after the job completes execution..
Logon as User	Determines whether jobs are submitted with the permissions and environment variables of the specified user or the local system account: Yes: Specified User No: Local System Account Default: No

Field

Description

Logon Domain

Defines the logon domain name if <domain> is not defined 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 that Control-M performs after the job completes execution..

Logon as User

Determines whether jobs are submitted with the permissions and environment variables of the specified user or the local system account:

Yes: Specified User
No: Local System Account

Default: No

Agentless Parameters

The following table describes the Agentless parameters.

Field	Description
SSH Connection Mode	Determines one of the following connection modes: SSH Only SSH with SFTP - One Connection SSH with SFTP - Two Connections
Connection Retries	Determines the maximum number of attempts to restore the connection between Control-M/Server and the Agentless Host.
Connection Timeout	Determines the maximum number of seconds that Control-M/Server attempts to connect to the Agentless Host before the Agentless Host is set to Unavailable.
Temporary Directory	Defines a directory to store temporary files that are removed from Agent when the jobs end and the network connection is available or restored. Default: Job Owners (Run As) home directory. The . (period) represents this directory.
Print Details to OUTPUT	Determines whether to include details related to the remote connection in the job output of jobs executed on an Agentless Host.

Email Parameters

The following table describes the email parameters.

Field	Description
SMTP Server Name	Defines the name of the SMTP server.
SMTP Port Number	Determines the port number where the SMTP server communicates. Valid Values: 0–65535 Default: 25
Sender Email	Determines the email address of the sender (max 99 characters). Default: control@m
Sender Friendly Name	Defines the name or alias that appears on the sent email.
Reply to Email	Defines the email address where to send replies. If this field is left empty, the sender's email address is used.