Control-M

9.0.20
Administrator Guide

July 2020
Contacting BMC Software
You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain
information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada

Address BMC SOFTWARE INC Telephone  713 918 8800 Fax 713 918 8000
2103 CITYWEST BLVD  800 841 2031
HOUSTON TX
77042-2827
USA

Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000

© Copyright 1999-2020 BMC Software, Inc.

Your use of this information is subject to the terms and conditions of the applicable End User License
Agreement for the product and the proprietary and restricted rights notices included in this
documentation. No part of this publication may be reproduced, stored in a retrieval system, or transmitted
in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the
prior written permission of BMC Software, Inc.
BMC, BMC Software, the BMC logo, the BMC Software logo, and other BMC marks, and the tagline “Bring
IT to Life” are the exclusive properties of BMC Software, Inc., or its affiliates or subsidiaries and are
registered or may be registered with the U.S. Patent and Trademark Office and in other countries. All
other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or
in other countries. All other trademarks or registered trademarks are the property of their respective
owners.
For BMC Control-M Products that are licensed on the “per CPU – Full Capacity” unit of measurement and
installed in an Amazon Web Services (“AWS”), Microsoft Azure (“Azure”), or Google Cloud Platform
("GCP") cloud environment, a license is required for the total number of CPUs in each AWS, Azure, or GCP
instance upon which the Product is installed or which the Product manages, either remotely or locally. For
AWS and GCP, one CPU is equivalent to one vCPU, as defined by AWS. For Azure, one CPU is equivalent
to up to four Virtual Cores (as defined by Azure), rounded up to the closest multiple of four.
IBM® Tivoli® Business Service Manager, IBM Tivoli Workload Scheduler, IBM Cognos, IBM InfoSphere
DataStage, IBM i (AS/400), IBM Websphere, and AIX® are the trademarks or registered trademarks of
International Business Machines Corporation in the United States, other countries, or both.
UNIX® is the registered trademark of The Open Group in the US and other countries.
Linux is the registered trademark of Linus Torvalds.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks
of their respective owners.
SAP® R/2 and SAP R/3, SAP Business Objects, and SAP NetWeaver are trademarks or registered
trademarks of SAP AG in Germany and in several other countries.

2
Restricted rights legend
U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER
THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and
computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Field
52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025,
as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD,
HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.
Customer support
You can obtain technical support by using the BMC Software Customer Support website or by contacting
Customer Support by telephone or e-mail. To expedite your inquiry, see “Before contacting BMC.”
Support website
You can obtain technical support from BMC 24 hours a day, 7 days a week at
(http://www.bmc.com/support). From this website, you can:
 Read overviews about support services and programs that BMC offers
 Find the most current information about BMC products
 Search a database for issues similar to yours and possible solutions
 Order or download product documentation
 Download products and maintenance
 Report an issue or ask a question
 Subscribe to receive proactive e-mail alerts when new product notices are released
 Find worldwide BMC support center locations and contact information, including e-mail addresses, fax
numbers, and telephone numbers
Support by telephone or e-mail
In the United States and Canada, if you need technical support and do not have access to the web, call
800 537 1813 or send an e-mail message to customer_support@bmc.com. (In the subject line, enter
SupID:<yourSupportContractID>, such as SupID:12345). Outside the United States and Canada,
contact your local support center for assistance.
Before contacting BMC
Have the following information available so that Customer Support can begin working on your issue
immediately:
 Product information
• Product name
• Product version (release number)
• License number and password (trial or permanent)
 Operating system and environment information
• Machine type
• Operating system type, version, and service pack or other maintenance level such as PUT or PTF

3
 • System hardware configuration
• Serial numbers
• Related software (database, application, and communication) including type, version, and service
pack or maintenance level
 Sequence of events leading to the issue
 Commands and options that you used
 Messages received (and the time and date that you received them)
• Product error messages
• Messages from the operating system, such as file system full
• Messages from related software
License key and password information
If you have questions about your license key or password, contact BMC as follows:
 (USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an e-mail
message to ContractsPasswordAdministration@bmc.com.
 (Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20
354 8702, or send an e-mail message to password@bmc.com.
 (Asia-Pacific) Contact your BMC sales representative or your local BMC office.
Third party Software
For the provisions described in the BMC License Agreement and Order related to third party products or
technologies included in the BMC Product,
seehttps://docs.bmc.com/docs/display/workloadautomation/Control-M+Workload+Automation+Document
ation and click Third-party software (TPS).

4
Contents
Introduction to Control-M Configuration Manager ............................................................. 10
Logging in to CCM ..................................................................................................................... 11
Configuring CCM options ............................................................................................................ 11

Component management ................................................................................................ 13

Defining a Control-M/EM component ........................................................................................... 13
Control-M/EM component parameters ......................................................................................... 15
Defining a Control-M/Server component ...................................................................................... 16
Control-M/Server component parameters .................................................................................... 17
Renaming a Control-M/Server component.................................................................................... 20
Pausing Control-M/Server........................................................................................................... 21
Defining a Control-M/Agent component ....................................................................................... 21
Remote Hosts ........................................................................................................................... 31
Defining a Network Load Balancer Router .................................................................................... 35
Network Load Balancer Router parameters .................................................................................. 36
Database management .............................................................................................................. 37
Editing a component .................................................................................................................. 39
Deleting a component ................................................................................................................ 39
Configuring Control-M/Server synchronization .............................................................................. 40
Component status ..................................................................................................................... 41
Synchronizing Control-M/Server in the CCM ................................................................................. 43
Elevate parameters.................................................................................................................... 44

System configuration ...................................................................................................... 45

Control-M/EM system parameters ............................................................................................... 45
Control-M/Server parameters ....................................................................................................141
Control-M/Agent parameters .....................................................................................................188
Defining Control-M for z/OS system parameters ..........................................................................213
Connecting to Control-M/EM behind a firewall .............................................................................214
Configuring Control-M/EM server with High-Availability or Control-M/EM Distributed behind a firewall215
Connecting to Control-M/EM behind a firewall from Control-M clients ............................................216
Connecting to an Apache Kafka server behind a firewall ..............................................................216
Defining Daylight Savings Time support .....................................................................................216
Control-M Automation API configuration .....................................................................................219
Configuring CORBA components ................................................................................................236

5
Configuring CE logging parameters ............................................................................................238
Configuring Control-M Reports in a Control-M/EM Distributed environment ....................................239
Connecting a load balancer to Control-M/EM ...............................................................................239
Configuring an Nginx Load Balancer with BMC provided certificate ................................................240

Control-M security ........................................................................................................ 242

Control-M/Server security..........................................................................................................242
Control-M/Agent security ..........................................................................................................246
Agentless SSH key management ................................................................................................249
Configuring SSO authentication for Control-M Web ......................................................................251
Configuring SSO authentication for Control-M clients ...................................................................257
Configuring RSA authentication with Control-M ...........................................................................258
Configuring the RSA Authentication Agent ..................................................................................259
Changing the encryption type between Control-M/Server and Control-M/Agent ..............................259
Replacing the Control-M encryption keys ....................................................................................260
Control-M encryption keys .........................................................................................................261
Configuring security filters .........................................................................................................262

Control-M/EM Authorizations ......................................................................................... 263

Defining a Control-M/EM user/role .............................................................................................264
LDAP Groups authorization ........................................................................................................264
Defining LDAP Groups...............................................................................................................264
Editing a Control-M/EM user/role ...............................................................................................265
Copying a Control-M/EM user/role..............................................................................................265
Deleting a Control-M/EM user/role .............................................................................................266
Control-M/EM user and role authorizations .................................................................................266
Creating an administrator user ..................................................................................................303
Changing the DBO password .....................................................................................................304
Authorizing non-administrators to manage application plug-in connection profiles ..........................304
cm_admin.xml parameters ........................................................................................................305

High availability ............................................................................................................ 306

Control-M high availability on one host .......................................................................................306
Control-M/EM and Control-M/Server high availability with Oracle/MSSQL/External PostgreSQL ........307
Control-M/Server high availability with a dedicated BMC PostgreSQL .............................................314
High availability scenarios .........................................................................................................319

6
Alerts ........................................................................................................................... 321
Shout destination management .................................................................................................321
Managing exception alerts.........................................................................................................324
Removing old alerts ..................................................................................................................325
Sending alerts and xAlerts to an event management system ........................................................325
SNMP trap format .....................................................................................................................326
Sending Alerts and xAlerts to a script .........................................................................................328
Usage alerts.............................................................................................................................328

Host group management .............................................................................................. 332

Host groups .............................................................................................................................332
Host group restrictions..............................................................................................................334

Control-M deployment .................................................................................................. 337

Control-M/Agent deployment .....................................................................................................337
Control-M MFT deployment .......................................................................................................342
Application Pack deployment .....................................................................................................344
Client Distribution .....................................................................................................................350

Workload Archiving configuration .................................................................................. 354

Starting up the Workload Archiving Server ..................................................................................355
Defining Workload Archiving policies ..........................................................................................355
Workload Archiving policy rule parameters .................................................................................356
Configuring Workload Archiving disk space and cleanup settings ..................................................357
Workload Archiving Server Configuration parameters...................................................................358
Deleting data from the Workload Archiving server .......................................................................358
Shutting down the Workload Archiving Server .............................................................................359
Configuring the Workload Archiving cyclic log collection ...............................................................359
Configuring retention parameters to prevent loss of archive data..................................................359
Workload Archiving command line utilities ..................................................................................361

Control-M for MFT configuration .................................................................................... 362

Connection profile management ................................................................................................362
Silent mode connection profile management ...............................................................................378
MVS file template management .................................................................................................383
PGP template management .......................................................................................................387
Generating SSH keys ................................................................................................................391
Authorizing an SSH host............................................................................................................392
Configuring Control-M for MFT parameters .................................................................................393

7
Control-M for MFT configuration parameters ...............................................................................394
Editing mass connection profiles ................................................................................................395
Mass connection profile update parameters ................................................................................397
Configuring the File Transfer Server ...........................................................................................397
Control-M MFT Enterprise B2B ...................................................................................................403
Configuration procedures ..........................................................................................................430

Control-M diagnostics ................................................................................................... 454

Debug levels ............................................................................................................................454
Defining Web Server log levels ..................................................................................................457
Generating diagnostic data ........................................................................................................458
Troubleshooting diagnostic data collection failure ........................................................................459
Sending commands to Control-M/EM server components .............................................................459
Monitoring the Control-M/EM Configuration Agents Log ...............................................................459
Usage Reporting Tool ...............................................................................................................460
Generating a usage report ........................................................................................................460
Configuring persistent source level debugging diagnostics............................................................461
Persistent diagnostic record file parameters ................................................................................462
Troubleshooting scenarios .........................................................................................................465
GCS condition issues.................................................................................................................467

Database operation and maintenance ............................................................................ 468

Accessing the Control-M/EM database maintenance menu ...........................................................468
Control-M/EM Database Maintenance menu options ....................................................................469
DBUMonitor .............................................................................................................................469
Database backup and restore ....................................................................................................471
Database maintenance and cleanup ...........................................................................................478
Configuring Control-M/EM Always On .........................................................................................488
Configuring Control-M/Server with MSSQL Always On ..................................................................489

User Exits .................................................................................................................... 490

Implementing User Exits in Control-M/Server ..............................................................................490
Control-M general user exits ......................................................................................................491
Job Order Exit (CTMUE101) .......................................................................................................491
Job Submission Exit (CTMUE102)...............................................................................................493
Before New Day Procedure Exit (CTMUE103) ..............................................................................495
After New Day Procedure Exit (CTMUE104) ................................................................................496
Before User Daily Exit (CTMUE105) ............................................................................................496
After User Daily Exit (CTMUE106) ..............................................................................................496

8
Scripts ......................................................................................................................... 497
Shell Scripts on UNIX ................................................................................................................497
Scripts on Windows ..................................................................................................................502

BSM configuration procedures ....................................................................................... 505

BMC Service Impact Manager configuration ................................................................................505
Purging obsolete periodic statistics entries ..................................................................................507

Remedy configuration ........................................................................................................ i

Configuring Remedy connection parameters ................................................................................... i
Remedy incident information configuration ..................................................................................... i
Creating an incident form ............................................................................................................. iii

9
1
1
Introduction to Control-M Configuration
Manager
The Control-M Configuration Manager (CCM) is a GUI application that enables you to administer, manage,
monitor, configure, and maintain all Control-M components, as well as defining security settings and user
authorizations.
The CCM enables you to configure the following:
 Control-M components: Enables you to define Control-M/Enterprise Manager (EM),
Control-M/Server, Control-M/Agent components including databases, remote hosts, and Control-M for
z/OS components, as described in Component management (on page 13).
 System parameters: Enables you to define Control-M/EM, Control-M/Server, Control-M for z/OS,
and Control-M/Agent system parameters, as described in System configuration (on page 45).
 Security settings: Enables you to define user authorizations in Control-M/Server, Run as
authentication in SSH or password mode, and encrypt data between Control-M/Agent and a remote
host with SSH, as described in Control-M security (on page 242).
 Control-M/EM authorizations: Enables you to assign LDAP, Global and Prerequisite Conditions,
Quantitative and Control Resources, Calendar, Folder, Workload Policy, and Run as User
authorizations for Control-M/EM users, as described in Control-M/EM Authorizations (on page 263).
 High Availability: Enables you to to fail over Control-M/EM or Control-M/Server to a secondary host,
as described in High availability (on page 306).
 Alerts: Enables you to create shout destination tables and manage exception alerts, as described in
Alerts (on page 321).
 Host groups: Enables you to define and run jobs on any host in a group and limit the number of
jobs submitted to a specific host according to a defined CPU usage limit and the number of
concurrently running jobs on a host, as described in Host group management (on page 332).
 Control-M Deployment: Enables you to upgrade or downgrade Control-M/Agents from the CCM
and distribute the Control-M/EM client to every supported Windows computer in your organization, as
described in Control-M deployment (on page 337).
 Workload Archiving: Enables you create Archive policies and configure Archive settings, as
described in Workload Archiving configuration (on page 354).
 Diagnostics: Enables you to define Control-M/EM, Control-M/Server, and Control-M/Agent debug
levels, generate diagnostic data, and send commands to Control-M/EM server components, as
described in Control-M diagnostics (on page 454).
NOTE: You can perform many of the CCM tasks from a command prompt of any computer where
Control-M components are installed. For more information, see Introduction to Utilities.

10
Control-M Administrator Guide

Logging in to CCM
This procedure describes how to log in to CCM, which enables you to perform component and system
configuration, enable security parameters and authorizations, and manage system alerts and host group
management.
 To log in to CCM:
1. From the Start menu, select All Programs > BMC Software Control-M 9.0.20 > Control-M
Configuration Manager.
The Control-M Configuration Manager login window appears.
2. In the User Name field, type the username that you want to use to log in to CCM.
3. In the Password field, type the password of the username.
4. From the Server drop-down list, select the CMS server that you want to connect.
NOTE: If the Local User checkbox appears and is selected, you can log in without typing a
username and password. If you want to log in as a different user, uncheck the checkbox and type a
different username and password.
5. To change the Naming Service server and select the CMS server related to that environment, do the
following:
a. Click Advanced.
b. In the Host Name field, type the hostname where the Naming Service server is located.
c. In the Port Number field, type the port number for the Naming Service server.
d. The Using SSL checkbox indicates the SSL mode. To change the mode, see Introduction to SSL
for Control-M.
e. From the Domain drop-down list, select an LDAP domain or the Local_EM domain.
This field only appears if there is a defined LDAP domain, as described in Defining LDAP system
parameters (on page 47).
f. Click Apply.
6. Click Login.

Configuring CCM options

This procedure describes how to configure CCM options, such as when to start, stop, enable, and disable
components and determine what options are shown in the CCM.
 To configure CCM options:
1. From the drop-down list in the top left-hand corner, select Options.
The Options dialog box appears.
2. Select the required options and click Confirmations.
The Confirmation options determines which actions raise a confirmation dialog before executing.
3. Select the required options and click OK.

11
Control-M Administrator Guide

The CCM options are updated.

12
2
2
Component management
After you have installed Control-M, the initial configuration automatically defines and starts up the
required components. However, you might want to define additional components for one or more of the
following reasons:
 Load balancing
 Organizational structure
 Geographic distances
In most configurations, two or more Control-M/Servers are required with multiple Control-M/Agents to
handle the load balancing of jobs. For more information about Control-M configuration, see Control-M
architecture.
You can install more than one Control-M/Agent on the same computer. With multiple agents, more than
one Control-M/Server can request jobs on the same computer. In this type of configuration, each
Control-M/Agent is associates with a different Control-M/Server.
The following procedures describe how to define, edit, and delete Control-M/EM, Control-M/Server,
Control-M/Agent and remote host components:
 Defining a Control-M/EM component (on page 13)
 Defining a Control-M/Server component (on page 16)
 Renaming a Control-M/Server component (on page 20)
 Pausing Control-M/Server (on page 21)
 Defining a Control-M/Agent component (on page 21)
 Defining a remote host (on page 31)
 Defining a Network Load Balancer Router (on page 35)
 Editing a component (on page 39)
 Deleting a component (on page 39)
To change the status of a component, see Component status (on page 41).
To set the synchronization mode for a Control-M/Server component, see Configuring Control-M/Server
synchronization (on page 40).

Defining a Control-M/EM component

This procedure describes how to define a Control-M/EM component, which enables you to divide your
workflows based on load balancing requirements to ensure resources are allocated appropriately.

 To define a Control-M component:

1. From the Home tab, in the General group, select New and then click Control-M/EM Component.

13
Control-M Administrator Guide

The Control-M/EM Component dialog box appears.

2. For each field, type or select the required value, as described in Control-M/EM component parameters
(on page 15).
3. Click OK.
The new component appears in the CCM.

14
Control-M Administrator Guide

Control-M/EM component parameters

The following table describes parameters that enable you to define a Control-M/EM component.

Field Description

Desired State Determines the state of the component after it is defined. For
more details, about component status, see Component status
(on page 41).

Type Determines which of the following Control-M/EM components

to define:
 SLA Management (BIM)
 GCS
 GUI Server
 Forecast Server
 Workload Archiving Server
 Self Service Server
 Web Server

Name Defines the logical name of the component or the name of the
computer where the Control-M/EM component is located.
You can define multiple GUI servers to run simultaneously.
(These capabilities enable you to balance job loads in your
environment.) These servers can run on the same host or
different hosts. Each instance of a GUI server must have a
unique name.

GUI Server Name Defines the name of the GUI Server that connects with the
component.
By default, the GUI Server is named according to its host
name. If more than one GUI Server is on the same host, each
instance must have a unique name.

Host Name Defines the hostname of the computer where the Control-M/EM
component is located

Check Interval Determines the number of seconds between intervals when the
CCM checks the status of the component

Additional Startup Flags: Defines alternative parameters to start up the component.

There is no need to change this value unless directed by BMC
Software.

15
Control-M Administrator Guide

Defining a Control-M/Server component

This procedure describes how to define a Control-M/Server component, which enables you to divide your
job workflows based on load balancing requirements, geographic distribution, or organizational structure
of your business.

 To define a Control-M/Server component:

1. From the Home tab, in the General group, select New and then click Control-M/Server.
The Control-M/Server definition dialog box appears.
2. Select of the following options and then click OK:
• Discover: Enables you to automatically define a Control-M/Server for a specific host.
• Define: Enables you to manually define a Control-M/Server for a specific host.
3. Do one of the following:
• If you selected Discover, type the required values for each field and then click OK.
• If you selected Define, type the required values for each field, as described in Control-M/Server
component parameters (on page 17) and then click OK:
The Control-M/Server appears in the CCM.

16
Control-M Administrator Guide

Control-M/Server component parameters

The following table describes parameters that enable you to define a Control-M/Server component, as
described in Defining a Control-M/Server component (on page 16).

Field Description

Name Defines the name of the Control-M/Server.

The name can be a maximum of 20 alphanumeric characters
long. Symbols, such as (%,*,&,$,(),<>,"",'' and blank
spaces are not valid.

Platform Determines whether the Control-M/Server is installed on a

distributed or z/OS operating system.
If your operating system is UNIX or Windows select
Distributed.

ID Defines a unique 3-character code (such as 999 or NYC) that

Control-M/EM uses to identify each Control-M/Server

Version Determines the version number of the Control-M/Server

Description Provides a description of the Control-M/Server

Contact Defines the name of the contact person who is responsible for
Control-M/Server maintenance

EM Statistics Defines the job attribute which is used as the key for statistics
collection according to Jobname or Memname.
The settings on the Control-M/Server computer must match
these settings.

17
Control-M Administrator Guide

Field Description

Synchronization mode Determines when, if, and how to synchronize data between
Control-M/Server and Control-M/EM, as follows:
 No Synchronization: No synchronization between
Control-M/EM and Control-M/Server takes place. To
synchronize manually, you can download the
Control-M/Server data to Control-M/EM, upload the
Control-M/EM data to Control-M/Servers, or Create a
regular calendar.
 Update Control-M/Server definition during
Check-in: Synchronizes only Control-M/EM Workspace and
Calendar changes with Control-M/Server during Check-in.
Other Control-M/EM definition changes are not
synchronized with Control-M/Server. Control-M/Server
changes are not synchronized with Control-M/EM. For more
information on checking in, see Workspaces or Creating a
regular calendar.
 Update Control-M/Server only: Synchronizes
Control-M/EM changes with Control-M/Server.
Control-M/Server changes are not synchronized with
Control-M/EM.
 Update Control-M/Server and Control-M/EM:
Synchronizes all Control-M/EM and Control-M/Server
changes with each other, for full synchronization.

Protocol Determines which protocol Control-M/Server uses to

communicate with Control-M/EM

Host Defines the name of Control-M/Server host

Control-M/EM Port Defines the TCP/IP port number that Control-M/Server uses to
connect to Control-M/EM

Gateway Defines a new Gateway that is used to connect to

Control-M/EM, as described in Defining a Control-M/EM
component (on page 13).

18
Control-M Administrator Guide

Field Description

Time Zone Determines the time zone where the Control-M/Server is

located.
NOTE: Although time zone definitions in the northern
hemisphere are set to summer Daylight Saving Time,
definitions in the southern hemisphere are set to winter. In
Sydney, Australia, winter time (GMT+10:00) is from March 25
at 03:00 until October 1 at 02:00. All other dates are
GMT+11:00 (summer time). The time label for Sydney is
defined as follows:
SYD (GMT+11:00) FROM 25.03 03:00 TO 01.10. 02:00
(GMT+10:00)
NOTE: This parameter is only enabled if the Control-M/Server
is set to Un-Managed.

Start Day Determines the first day of the business week.

The settings on the Control-M/Server computer must match
these settings.
NOTE: This parameter is only enabled if the Control-M/Server
is set to Un-Managed.

New Day Time Determines the time of day that the New Day procedure is
performed on the Control-M/Server.
The settings on the Control-M/Server computer must match
these settings.
NOTE: This parameter is only enabled if the Control-M/Server
is set to Un-Managed.

Daylight Savings Time Determines the following:

 Determines whether the Control-M/Server will schedule
jobs based on Daylight Savings Time and when it starts
and ends
 Determine how to show forecasts during times when
Daylight Savings Time (DST) is active and inactive
 Determines whether or not to consider which ODAT is used
during the time when the New Day occurs and after the
time that DST occurs.
NOTE: This parameter is only enabled if the Control-M/Server
is set to Un-Managed.

Control-M/Tape Determines whether Control-M/Tape is installed on this

computer with Control-M/Server (z/OS only)

19
Control-M Administrator Guide

Field Description

Control-M/Restart Determines whether Control-Restart is installed on this

computer with Control-M/Server (z/OS only)

Control-M/Analyzer Determines whether Control-Analyzer is installed on this

computer with Control-M/Server (z/OS only)

Upper Case Determines whether to restrict user input to upper case letters
only in job attributes.
If you select this option, you cannot change it without fixing all
the job attributes.

Enable Determines whether the Control-M/Server is enabled

Renaming a Control-M/Server component

This procedure describes how to rename a Control-M/Server component in the Control-M Configuration
Manager, which automatically updates all associated definition tables in the database (not the active
jobs).
Before you begin
 Back up Control-M/Server, as described in Control-M/Server database backup and restore (on page
471).
 Do not run any utilities that update job or calendar definitions during the rename.
 Save and close any open workspaces.

 To rename a Control-M/Server component:

1. Shut down the following components, as described in Shutting down a component (on page 42):
• GCS
• GUI Server
• BIM
• Forecast Server
• Self Service Server
• Gateway (associated to the Control-M/Server)
2. Right-click a Control-M/Server that you want to rename and select Rename.
The Rename Control-M dialog box appears.
3. In the New Name field, type the new name of the Control-M/Server and click OK.

20
Control-M Administrator Guide

If there are database fields that contain regular expressions, such as Global Condition Prefixes,
warnings might appear if one of the following is identified:
• The pattern used to match the old Control-M/Server name does not match the new name.
• The pattern used to exclude the old Control-M/Server name now matches the new name.
4. Do one of the following:
• Fix the definitions found in each warning.
• Click Ignore and Continue and fix the definitions after the rename.
The renamed Control-M/Server appears in the CCM component list and the list of warnings are saved
in the following directory:
<Control-M/EM_Home_Dir>\Log\<original_name>_to_<new_name>_<timestamp>.log

Pausing Control-M/Server
This procedure describes how to pause Control-M/Server, which stops Control-M/Server from submitting
jobs.
NOTE: Activities such as New Day and job tracking continue to be active in pause state.
EXAMPLE: You might want to pause submitting new jobs when you want to investigate abnormal
behavior in Control-M/Server, without shutting it down, or if you want to start it up after its
upgraded.

 To pause Control-M/Server:
1. Select the Control-M/Server component that you want to pause.
2. Right-click and select Pause.
A confirmation message appears.
3. Click Yes and one of the following occurs:
• If the Control-M/Server state was up, then the state changes to Up and Pause. After you restart
Control-M/Server, Pause is canceled, and new jobs are submitted.
• If the Control-M/Server state was down, then the state changes to Down and Pause. After you
restart Control-M/Server, Pause remains in effect and new jobs are not submitted.

Defining a Control-M/Agent component

This procedure describes how to define a Control-M/Agent component, which enables you to connect it to
a Control-M/Server using specific communication parameters. After the Control-M/Agent is defined you
can use the Control-M/Server to run jobs on this Control-M/Agent.
 To define a Control-M/Agent component:
1. From the Home tab, in the General group, select New and then click Control-M/Agent.
The Add Control-M/Agent dialog box appears.

21
Control-M Administrator Guide

2. From the Control-M/Server Name drop-down list, select the Control-M/Server that you want to
connect the Control-M/Agent.
3. In the Control-M/Agent Host Name field, type the name of the host where the Control-M/Server is
located.
4. Accept the default values, or type or select the required value, as described in the following:
• Communication parameters (on page 23)
• Persistent connection parameters (on page 26)
• Job submission and tracking parameters (on page 27)
• Output parameters (on page 28)
• Security parameters (on page 28)
• Agentless parameters (on page 29)
• Email parameters (on page 30)
5. Click Test.
The test completes successfully.
6. Click OK.
The new Control-M/Agent appears in the CCM.

22
Control-M Administrator Guide

Communication parameters
The following table describes the Control-M/Agent Communication parameters:

Field Description

Server to Agent Port Number Defines the port number in the Control-M/Agent computer
where data is received from the Control-M/Server computer.
The value assigned to this parameter must correspond to
the value assigned to the Server-to-Agent Port Number field
in the configuration file on the corresponding
Control-M/Agent computer.
Default: 7005

Agent to Server Port Number Defines the port number between 1024 and 65535 that
receives data from the Control-M/Agent computer.
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.
Example: 7005/30.
Note: Increasing the Timeout value reduces agent
performance.
Valid values: Between 1024 and 65535 inclusive
Default: 7005

Primary Server Defines the hostname of the computer where the current
Control-M/Server submits Jobs to the Control-M/Agent

Authorized Servers Defines a list of backup servers which can replace the
primary server if it fails. The Control-M/Agent only accept
requests from servers on this list.
NOTE: You cannot submit Jobs to the same
Control-M/Agent if there is more than one active
Control-M/Server. Another Control-M/Agent instance must
be installed with unique ports to support this configuration
or Job status updates corrupt.

Check Interval (Available Defines the number of seconds between status checks for
Agent) each Control-M/Agent that communicates with
Control-M/Server.
If you decrease the default value, it might impact
Control-M/Server performance.
Default: 7200 (2 hours)

23
Control-M Administrator Guide

Field Description

Retry Interval (Unavailable Defines the number of seconds between attempts to

Agent) communicate with a Control-M/Agent computer whose
status is Unavailable.
If you decrease the default value, it might impact
Control-M/Server performance.
Default: 90

Unavailability Shout Urgency Determines the urgency level of a message sent with high
priority sent from a Control-M/Agent with an Unavailable
status.
Urgent message 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

Control-M/Server attempts to connect to Control-M/Agent
before the Control-M/Agent is set to Unavailable.
If you decrease the default value, it might impact
Control-M/Server performance.
Default: 120

Agent TCP/IP Timeout Defines the timeout used by the Control-M/Agent when
listening on the Server to agent port number before timing
out and performing housekeeping tasks

Maximum Retries Defines the number of times Control-M/Server attempts to

connect to Control-M/Agent before the Control-M/Agent is
set to Unavailable.

Logical Agent Name Defines a logical or alias name for the Control-M/Agent.
NOTE: If you have more than one Control-M/Agent on the
same host that connects to the same Control-M/Sever, you
must use this parameter to uniquely identify each
Control-M/Agent.
The value must be the same as the value in
Control-M/Server computer.
The logical name is used when the Control-M/Agent initiates
the communication to Control-M/Server with the output
from Control-M/Agent utilities and in messages sent to
Control-M/Server.

24
Control-M Administrator Guide

Field Description

Listen to Network Interface Determines which network interface the Control-M/Agent is

listening on.
It can be set to a specific hostname or IP address so that
the Control-M/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
Control-M/Agent. For more information, see Introduction to
SSL for Control-M.

Tag Defines a logical name that is used to label specific

Control-M/Agents into a group with a specific authorization
level. You can apply a specific tag to a Control-M/Agent, as
described in Agents Management (on page 300), or you can
define your own tag with the asterisk character if you have
the correct permissions.

25
Control-M Administrator Guide

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 Control-M/Agent
agent is constant and can be initiated by both. When the
Control-M/Agent starts up, the Agent Router process is started
and acts as a broker between the other Control-M/Agent
components and Control-M/Server.
The Agent Router process allows Control-M/Server to maintain
a constant connection with the Control-M/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 between 30 -

86400 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.
Default: 300

Session Idle Timeout Determines the maximum number of seconds between 30 -

86400 that a session can be idle before Control-M/Server
terminates it.
Default: 900

Allow Agent Disconnection Determines if the current connection to this Control-M/Agent

can be disconnected when the maximum number of concurrent
sessions is reached.
Allowing a persistent connection on a Control-M/Agent to
disconnect requires the connection to be reestablished before
communication with the Control-M/Agent can continue. If
you run time-sensitive jobs on the Control-M/Agent, you might
want to select No.

Allow agent to initiate a Determines if the Control-M/Agent can open a connection to

session the Control-M/Server when working in Persistent Connection
mode.
If the Control-M/Agent is outside a firewall and the Agent to
Server port is blocked, set this parameter to No.

26
Control-M Administrator Guide

NOTE: You can change most of the parameters from ctm_menu, as described in ctm_menu.

Job submission and tracking parameters

The following table describes the Job submission and tracking parameters:

Field Description

Run Job Owner's Logon Script Determines whether the Control-M/Agent runs the log on
script defined by the system administrator before each Job

Wait for child processes to Determines whether the Job ends when all sub processes exit
complete or waits until the main Job process exits. It is recommended
to select Yes, when the Control-M/Agent is used to start
background applications.

Echo Job commands into Output Defines whether to print commands in the output of a Job

Foreign Language Support Determines whether CJK or LATIN-1 is supported.

Application Locale Determines the CJK encoding used by Control-M/Agent to run

Jobs.

Tracker Polling Interval Determines the time the Control-M/Agent tracker process
waits for incoming events from Control-M application support
modules before going back to scan the status directory

27
Control-M Administrator Guide

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 Control-M/Agent computers.
After this period, the New Day procedure deletes all expired
Job output files.
This parameter also affects the number of days that archived
viewpoints are saved.

Default Printer Defines the default printer for Job output (OUTPUT)

OUTPUT Name Determines one of the following prefix options for the output
file name:
 memname
 Jobname

Security parameters
The following table describes the 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.

Logon as User Defines which user account is used for the services (Windows
only).

Owner's Authenticate Settings See Control-M/Agent security (on page 246).

28
Control-M Administrator Guide

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 Defines the maximum number of attempts to restore the

connection between Control-M/Server and the remote host

Connection Timeout Determines the maximum number of seconds that

Control-M/Server attempts to connect to the remote host
before the remote host is set to Unavailable.

Temporary Directory Defines a directory to store temporary files that are

automatically removed from Control-M/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 a remote
host.

Default Queue Defines the default batch queue where the Control-M/Agent
submits Jobs to an OpenVMS remote host.
If this parameter is not specified, the Control-M/Agent submits
Jobs to sys$batch (the system’s default batch queue).
Valid values: String consisting of 1 to 31 characters, including
any uppercase and lowercase alphanumeric digits, the dollar
sign ($), the underscore (_), and includes at least one
alphabetic character.

29
Control-M Administrator Guide

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 between 0-65535 where the
SMTP server communicates

Sender Email Defines the e-mail address of the sender (max 99 characters)

Sender Friendly Name Defines the name or alias that appears on the sent e-mail

Reply to Email Defines the e-mail address where to send replies. If this field
is left empty, the sender e-mail address is used.

Troubleshooting Control-M/Agents
This procedure describes how to troubleshoot Control-M/Agents to determine why Control-M/Agents are
unavailable. The troubleshooting process runs a series of checks and provides a detailed explanation of
the checks and results.
This enables you to understand if the problem is a network/firewall issue or whether the Control-M/Server
is unable to connect to the Agent after opening and using a real connection. When Control-M/Server fails
to connect to the Control-M/Agent and the network and firewall are working correctly, the port number
might be defined incorrectly in the Control-M/Server definition or the Control-M/Agent is down.
 To troubleshoot Control-M/Agents:
1. From the Components Tree, select a Control-M/Agent that you want to troubleshoot.
2. Right-click and select Agent Troubleshooting.
The Agent Troubleshooting window appears.
3. Review the troubleshooting results and follow the on-screen instructions to resolve the issue.

30
Control-M Administrator Guide

Remote Hosts
A Remote Host is a Control-M component that enables you to submit and execute jobs on a computer
without installing a Control-M/Agent. The remote host runs all jobs assigned to its specific host ID and
does not require version updates. This reduces the need to install, update, and maintain Control-M/Agents
in your organization.
Remote hosts are connected to and managed by a specific Control-M/Agent. You can define multiple
remote hosts from one Control-M/Agent.
The remote host connects to the Control-M/Agent using one of the following connection methods:
 SSH: Supports UNIX, Windows, OpenVMS, z/OS USS, and PASE on AS/400. If you will be using more
simultaneous connections than your current SSH server settings allows, you must increase the value
for these settings accordingly. To configure the OpenVMS remote host , see 00091179
https://bmcsites.force.com/casemgmt/sc_KnowledgeArticle?sfdcid=00091179.
 WMI: Supports Windows. For more information, see WMI requirements (on page 33).
The following procedures describe how to set up remote hosts in your Control-M environment:
 Defining a remote host (on page 31)
 Converting a Control-M/Agent to a Remote Host (on page 33)
 Converting multiple Control-M/Agents to remote hosts (on page 34)
If you want to convert a Remote Host to Control-M/Agent, delete the remote host and then define the
Agent, as described in Defining a Control-M/Agent component (on page 21). You can also use the
ctm_menu utility as described in Converting a remote host to a Control-M/Agent using the ctm_menu.
You can map remote hosts to Control-M/Agents and define default connection settings in the CCM, by
right clicking the Control-M/Server and clicking Default Remote Settings. You can also use the
ctmhostmap utility, as described in ctmhostmap. To list remote hosts which a Control-M/Agent can route,
use the ctm_diag_comm utilty as described in ctm_diag_comm.
NOTE: If you upgraded Control-M/Agent to 9.0.20 and want to run jobs on a remote host on OpenVMS,
you must define the following system parameters, in the OS.dat (UNIX) or in the Windows registry as
follows:
 RJX_SSH_COURIER_ENABLED - N
 RJX_SFTP_COURIER_ENABLED - Y
This configuration disables the new and advanced security support with remote hosts (see CAR00118299)

Defining a remote host

This procedure describes how to define a remote host, which enables you to run jobs on a computer
without having to install a Control-M/Agent.
 To define a remote host:
1. From the Home tab, in the General group, select New and then click Remote Host.
The Step 1: Set Remote host and Agent list window appears.

31
Control-M Administrator Guide

2. From the Control-M/Server Name drop-down list, select the Control-M/Server where the remote
host will reside.
3. In the Remote Host Name field, type the name of the remote host.
4. Select the Control-M/Agent that you want to use to access the remote host.
5. Click Next.
The Step 2: Set connection parameters window appears.
6. Select one of the following encryption methods:
• SSH: Encrypts access to the remote host with SSH and determines the SSH server port,
encryption algorithm, and compression.
• WMI: Encrypts access to the remote host with WMI and defines the output directory (Windows
only). For more information, see WMI requirements (on page 33).
7. To test the connection to remote host, click Test. Otherwise, click Next.
The Step 3: Define an owner dialog box appears.
8. Do one of the following:
• If you have a defined Run as users for this host, select I already have owners defined for
this host.
• If you want to define a new Run as user for this host, select I want to define a new owner for
this host, and in the 'Run as' User Properties area, type the required values for each field and
click Test.
9. Click Next.
The Step 4: Summary window appears.
10. Review the remote host connection parameters and then click Finish.

32
Control-M Administrator Guide

WMI requirements
WMI is a Windows communication protocol that is used to connect a Control-M/Agent to a remote host.
The following table describes the necessary requirements to use WMI.

Requirement Description

Log on as  The Log On as option for the Control-M/Agent service is set to

This account.
 The user account that is running the Control-M/Agent service is
Administrator and is defined as a Domain user.
 This account requires read and write permission on the
Sharing tab of the directory that is used as the SYSOUT share.

Run As User The Run As user must have the following permissions:
 Member of the Administrator group on the remote host or have
access to the home directory and any other location that is
needed by the job's command.
 Full permission on the SECURITY tab of the directory that is
used as the SYSOUT share.
 Execute permission on the <windows>\system32\cmd.exe
 The SYSOUT directory has to be a network SHARE and the share
name needs to be called 'SYSOUT.

Trusted for Delegation The following requires Trusted for Delegation:

 The computer running the Control-M/Agent.
 The Run As user.
 If the command running on the remote host needs to access
another host.

Converting a Control-M/Agent to a Remote Host

This procedure describes how to convert a Control-M/Agent to a remote host, which enables you to
submit and execute jobs on the remote host without maintaining and updating a Control-M/Agent.
NOTE: If you want to convert a remote host to a Control-M/Agent, you need to delete the remote host
component, and then install a Control-M/Agent on the host.
Before you begin
 Verify that there are not any jobs running on the Control-M/Agent.

33
Control-M Administrator Guide

 To convert a Control-M/Agent to a remote host:

1. Shut down the Control-M/Agent.
2. Select the Control-M/Agent that you want convert, right-click and select Convert to Remote Host.
3. Define the remote host, as described in Defining a remote host (on page 31).

Converting multiple Control-M/Agents to remote hosts

This procedure describes how to convert multiple Control-M/Agents to remote hosts.
Before you begin
 Verify that no jobs are running on the required Control-M/Agents.

 To convert multiple Control-M/Agents to remote hosts:

1. Log in to the database server and run the following SQL commands to define all the run as users on
the Control-M/Agent computers:
select OWNER from CMR_AJF where lower(NODEID)='<agentNameToBeConverted>'
union
select OWNER from CMS_JOBDEF where
lower(NODEGRP)='<agentNameToBeConverted>' or exists
(select 1 from CMS_NODGRP where GRPNAME=CMS_JOBDEF.NODEGRP and
lower(NODEID)='<agentNameToBeConverted>')
: (PosgreSQL/Oracle) go (MSSQL)
NOTE: The <agentNameToBeConverted> variable must be in lower case.
2. Define the run as users that were defined in the SQL command, as described in Defining run as user
authentication settings (on page 247) or ctmsetown.
3. Shut down the required Control-M/Agents, as described in Shutting down a component (on page 42).
4. Convert each Control-M/Agent to a remote host, as described in Converting a Control-M/Agent to a
Remote Host (on page 33) or ctmhostmap.

Remote host network disconnections

Control-M/Agent requires an open connection to a remote host from the time of job submission until the
end of the job. If a network disconnection occurs, Control-M/Agent attempts to restore the connection.
During the reconnection attempts, jobs running on the remote host, through the specified
Control-M/Agent, remain in executing status.
If the connection is restored, the status of jobs is updated to reflect their current status, either completed
or still running. If the connection is not restored after the specified number of attempts, the jobs end with
NOT OK status.
The OUTPUT and exit code for jobs are stored in files on the remote host. The files reside in the user
home directory of the job’s run as user, in the directory defined by the RJX_OUTPUT_DIR system
parameter, as described in Application support parameters for UNIX.

34
Control-M Administrator Guide

If network connections are restored, these files are deleted, by default, when the jobs end. If network
connections are not restored, you can check these files to see if the jobs completed successfully or failed.

Defining a Network Load Balancer Router

This procedure describes how to define a Network Load Balancer Router, which automatically routes jobs
to the required Control-M/Agent based on a pre-defined configuration.
NOTE: The Network Load Balancer Router is a third party component. You need to configure it according
to manufacture instructions.
 To define a Network Load Balancer Router:
1. From the Home tab, in the Definitions group, click System Parameters.
The Control-M/EM System Parameters window appears.
2. In the left pane, click Advanced.
3. In the Name column, type EnableLoadBalancerRouter and double-click the parameter.
The Control-M/EM-Update System Parameter window appears.
4. In the Value field, change the value to True, and then click Save.
5. Click Close.
6. Restart the Control-M Configuration Server.
7. From the Home tab, in the General group, select New > Network Load Balancer Router.
The Add Network Load Balancer Router window appears.
8. In the Control-M/Server Name field, type the name of the Control-M/Server that connects to the
Network Load Balancer.
9. In the Network Load Balancer Router Host Name field, type the hostname of the Network Load
Balancer.
10. In the Communication tab, for each field, type the correct value, as described in Network Load
Balancer Router parameters (on page 36).

35
Control-M Administrator Guide

Network Load Balancer Router parameters

The following table describes Network Load Balancer parameters that are used in Defining a Network
Load Balancer Router (on page 35).
NOTE: Verify that all fields marked with an *have the same value in all Control-M/Agents that are
connected to the Network Load Balancer Router.

Field Description

*Server to Agent Port Number Defines the port number in the Control-M/Agent computer
where data is received from the Control-M/Server computer.
The value assigned to this parameter must correspond to
the value assigned to the Server-to-Agent Port Number field
in the configuration file on the corresponding
Control-M/Agent computer.
Default: 7006

Check Interval (Available Defines the number of seconds between status checks for
Agent) each Control-M/Agent that communicates with
Control-M/Server.
If you decrease the default value, it might impact
Control-M/Server performance.
Default: 7200 (2 hours)

Retry Interval (Unavailable Defines the number of seconds between attempts to

Agent) communicate with a Control-M/Agent computer whose
status is Unavailable.
If you decrease the default value, it might impact
Control-M/Server performance.
Default: 90

Unavailability Shout Urgency Determines the urgency level of a message sent with high
priority sent from a Control-M/Agent with an Unavailable
status.
Urgent message 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

Control-M/Server attempts to connect to Control-M/Agent
before the Control-M/Agent is set to Unavailable.
If you decrease the default value, it might impact
Control-M/Server performance.
Default: 120

36
Control-M Administrator Guide

Field Description

Agent TCP/IP Timeout Defines the timeout used by the Control-M/Agent when
listening on the Server to agent port number before timing
out and performing housekeeping tasks

Maximum Retries Defines the number of times Control-M/Server attempts to

connect to Control-M/Agent before the Control-M/Agent is
set to Unavailable.

*Secure Socket Layer Determines whether SSL is used to encrypt the

communication between Control-M/Server and the
Control-M/Agent. For more information, see Introduction to
SSL for Control-M.

Database management
Each Control-M/Server has its own database. Each Server database contains the job processing definitions
(organized by folders) for which that Server is responsible. In addition to the Definitions file, the
Control-M/Server database also maintains an Active Jobs database, a Resources a Conditions table.
Control-M/EM has its own database, which enables you to control your entire batch production enterprise.
The Definition file of the Control-M/EM database contains a copy of all job processing definitions from all
of your Control-M/Server databases. This database also includes Active Jobs.
The following procedures describe how to check database space and location and extend the size of an
Oracle or MSSQL database:
 Checking Database space (on page 37): Describes how to check the size of the database server.
 Checking Database location (on page 38): Describes how to verify the location of the database.
 Extending the Oracle database (on page 38): Describes how to extend the table space names of a
data file in the Oracle database.
 Extending the MSSQL database (on page 38): Describes how to extend the MSSQL database, which
enables you to extend the size of the data or log files in the database.
Many of the database maintenance functions can also be performed from the database maintenance
menus and sub menus, as described in Database maintenance.

Checking Database space

This procedure describes how to check database space in the CCM.

 To check database space:

1. From the Components Tree pane, under the Control-M/EM component, right-click Database:
<schema name@database host:database port> and select Check Space.
The Control-M/EM Database space use report window appears.

37
Control-M Administrator Guide

If the available space falls below 20%, either extend the database or reduce the existing data, as
described in Extending the Oracle database (on page 38) or Extending the MSSQL database (on page
38).
2. To reduce the data, cleanup the database error log files.

Checking Database location

This procedure describes how to check database location in the CCM.

 To check database location:

1. From the Components Tree pane, under the Control-M/EM component, select Database:
<schema name@database host:database port>.
2. From the Manage tab, in the Reporting Facility group, click Database Location.
The Database Hostname and Port window appears.

Extending the Oracle database

This procedure describes how to extend the table space names of a data file in the Oracle database.
 To extend the Oracle database
1. From the Components Tree pane, under the Control-M/EM component, right-click Database:
<schema name@database host:database port> and select Extend Database.
2. Log in to the Control-M/EM database as an administrator with your username and password.
The Control-M/EM Extend Database window appears.
3. From the Table Space Name drop-down list, select the table space name that you want to extend:
4. In the Extension Size field, type the extension size in MB.
5. Select one of the following options:
• Extend existing file
• Add new file
6. In the Data file name field, select the data file that you want to extend or type the name of the new
data file that you want to extend.
7. Click OK.
The database file size is extended.

Extending the MSSQL database

This procedure describes how to extend the MSSQL database, which enables you to extend the size of the
data or log files in the database.
 To extend the MSSQL database
1. From the Components Tree pane, under the Control-M/EM component, right-click Database:
<schema name@database host:database port> and select Extend Database.

38
Control-M Administrator Guide

2. Log in to the Control-M/EM database as an administrator with your username and password.
The Control-M/EM Extend Database window appears.
3. Select one of the following database file types that you want to extend:
• Data
• Log
4. In the Size field, type the extension size in MB.
5. Do one of the following:
• In the Current Files area, select the required file.
• In the New File area, type the name of the file.
6. Click OK.
The database file size is extended.

Editing a component
This procedure describes how to edit a Control-M/EM, Control-M/Server, or a Control-M/Agent component
from the CCM.
 To edit a component:
1. Select the component that you want to edit.
2. From the Home tab, in the General group, click Properties.
The Control-M <component type> dialog box appears.
3. Do one of the following:
• If you are editing a Control-M/EM component, edit the required enabled fields, as described in
Defining a Control-M/EM component (on page 13).
• If you are editing a Control-M/Server component, edit the required enabled fields, as described in
Defining a Control-M/Server component (on page 16).
• If you are editing a Control-M/Agent component, edit the required enabled fields, as described in
Defining a Control-M/Agent component (on page 21).
4. Click OK.
The component is updated.

Deleting a component
This procedure describes how to delete a Control-M/EM, Control-M/Server, or a Control-M/Agent
component from the CCM.
 To delete a component:
1. Select the component that you want to delete.

39
Control-M Administrator Guide

2. Right-click the component and select Desired State > Down.

Wait until the component is shut down before continuing.
3. From the Home tab, in the General Group, click Delete.
A confirmation message appears.
4. Click Yes.
The component is deleted.

Configuring Control-M/Server synchronization

This procedure describes how to configure Control-M/Server synchronization, which enables you to
determine how Control-M/Server synchronizes definition changes with Control-M/EM.
 To configure Control-M/Server synchronization:
1. Set the Control-M/Server component, as described in Editing a component (on page 39).
2. In the Control-M/Server component parameters (on page 17), set the Synchronization mode select
one of the following:
• No Synchronization: No synchronization between Control-M/EM and Control-M/Server takes
place. To synchronize manually, you can do any of the following:
o Download the Control-M/Server data to Control-M/EM
o Upload the Control-M/EM data to Control-M/Servers
o Create a regular calendar
• Update Control-M/Server definition during Check-in: Synchronizes only Control-M/EM
Workspace and Calendar changes with Control-M/Server during Check-in. Other Control-M/EM
definition changes are not synchronized with Control-M/Server. Control-M/Server changes are not
synchronized with Control-M/EM. For more information on checking in, see Workspaces or
Creating a regular calendar.
• Update Control-M/Server only: Synchronizes Control-M/EM changes with Control-M/Server.
Control-M/Server changes are not synchronized with Control-M/EM.
• Update Control-M/Server and Control-M/EM: Synchronizes all Control-M/EM and
Control-M/Server changes with each other, for full synchronization. This is the default option.
The selected Control-M/Server is set according to the selection.

40
Control-M Administrator Guide

Component status
You can set Control-M components to one of the following desired states:
 Up: Enables the component to communicate with other components
 Down: Disables communication from other components
 Ignore: The Configuration Agent does not attempt to start up or shut down components
 Recycle: The Configuration Agent restarts a component to solve server issues
The Configuration Agent attempts to start up or shut down components, depending on the desired state
and defined intervals. The CMS and Naming Service components can only be recycled from the CCM.
NOTE: In a high availability environment, the secondary host only starts up components that have the
desired state set to Up. If the desired state is set to Down, Ignore, or Recycle, those components remain
the same state as the primary.
The following procedures describe how to start up, shut down, ignore, and recycle Control-M
components:
 Starting up a component (on page 41)
 Shutting down a component (on page 42)
 Ignoring a component (on page 42)
 Recycling a component (on page 42)
To disable a Control-M/Server or Control-M/Agent component, see Disabling a component (on page 42).
NOTE: You can also manually shutdown and startup infrastructure components using the following
utilities:
 ctm_menu utility (The Control-M Manager menu), as described in ctm_menu.
 The shut down and start up utilities, as described in Communication, start up, and troubleshooting.
To change the status of a Control-M/Server, see Changing the status of Control-M/Server (on page 43).

Starting up a component
This procedure describes how to start up a Control-M/EM, Control-M/Server, or Control-M/Agent
component.
 To start up a component:
1. Select the component that you want to start up.
2. From the Home tab, select Up.
The desired state of the selected component is now set to Up.

41
Control-M Administrator Guide

Shutting down a component

This procedure describes how to shut down a Control-M/EM, Control-M/Server, or Control-M/Agent
component.
 To shut down a component:
1. Select the component that you want to shut down.
2. From the Home tab, select Down.
The desired state of the selected component is now in now set to Down.

Ignoring a component
This procedure describes how to ignore a Control-M/EM, Control-M/Server, or Control-M/Agent
component. This procedure is used in certain cluster configurations.
 To ignore a component:
1. Select the component that you want to ignore.
2. From the Home tab, select Ignore.
The desired state of the selected component is now set to Ignored.

Recycling a component
This procedure describes how to recycle a Control-M/EM, Control-M/Server, or Control-M/Agent
component.
 To recycle a component:
1. Select the component that you want to recycle.
2. From the Home tab, select Recycle.
The desired state of the selected component is now set to Recycle.

Disabling a component
This procedure describes how to disable a Control-M/Server or Control-M/Agent component. This enables
you to perform maintenance procedures, such as a backup.
 To disable a component:
1. Select a Control-M/Server or Control-M/Agent component.
2. Right-click and select Disable.
The component is disabled.

42
Control-M Administrator Guide

Changing the status of Control-M/Server

This procedure describes how to change the status of Control-M/Server, which enables you to determine
whether a Control-M/Server can be connected to one Control-M/EM or can used from multiple
Control-M/EMs.
 To change the status of Control-M/Server:
 Do one of the following:
• If the Control-M/Server is connected to one Control-M/EM and you want to disable this function,
do the following:
a. Select the Control-M/Server that you want change.
b. Right-click and select Set to Un-Managed.
• If the Control-M/Server is available to all Control-M/EMs and you want to designate it for one
Control-M/EM, do the following:
c. Select the Control-M/Server that you want change.
d. Right-click and select Set to Managed.

Synchronizing Control-M/Server in the CCM

This procedure describes how to synchronize Control-M/Server data formats in the Control-M/EM
database from the old to the new 9.0.20 data formats by running the Elevate action in the Control-M/EM
environment in the CCM.
Before You Begin
Verify that you have met the following requirements:
 Control-M/Server Upgrade
 If both Control-M/EM and Control-M/Server were migrated, you need to rename the Control-M/Server,
as described in Renaming the Control-M/Server in Control Configuration Manager (CCM).
 Ensure that the new Control-M/Server status is set to Un-Managed. Setting the Control-M/Server to
Managed before the elevation process can cause corruption.
 Do not start up the corresponding gateway until after you complete this procedure. The
synchronization procedure only affects the Control-M/Server data that is in the Control-M/EM
database. The gateway does not need to connect to the Control-M/Server to perform this procedure.
NOTE: This procedure is required only after you migrate the Control-M/Server to 9.0.20. If only the
Control-M/EM was migrated and not the Control-M/Server, do not perform these steps.
 To synchronize Control-M/Server in Control Configuration Manager (CCM):
1. Log in to the CCM from Control-M/EM version 9.0.20.
NOTE: Do not change the version of the Control-M/Server component in the CCM, as this action
performs the change automatically.
2. From CCM, select the Control-M/Server that you want to synchronize with Control-M/EM and check
the Version column.

43
Control-M Administrator Guide

NOTE: If the Control-M/Server version for the selected server is an earlier version than the version of
the server that is actually installed (because the server was migrated), then continue with this
procedure. Otherwise, there is no need to synchronize.
3. From the CCM, select the Control-M/Server that was migrated, right-click and select Elevate.
4. In the Version field, select version 9.0.20
5. Set the fields, as described in Elevate parameters (on page 44).
6. Click OK.
7. Right-click Gateway and select Desired State > Up.

Elevate parameters
The following table describes the Elevate fields:

Fields Description

Elevate Whether to update the data for a Control-M/Server in the Control-M/EM

Control-M database to a new version.

Version Select the new version of the migrated Control-M/Server.

All job definitions will be converted to a format that is consistent with the
standards for the new version.
If you migrated the Control-M/Server on UNIX, Windows or z/OS to a version
lower than 9.0.20, select the version that the Control-M/Server was migrated
to.

Host The name of the Control-M/Server machine (maximum length: 255 characters).

Port Defines either:

 The port number of the Control-M/Server Configuration Agent
or
 The port number of the Control-M/Server listening port
NOTE: Only one can be selected. If this Control-M/Server is being managed by
the CCM, select and set the Control-M/Server Configuration Agent Port number.

Synchronization Determines how to synchronize data between Control-M/Server and

Mode Control-M/EM, as described in Configuring Control-M/Server synchronization.

44
3
3
System configuration
In CCM, you can change the default values of the Control-M/EM system parameters or each component
without having to access each individual computer.
Before a modified parameter value can take effect, the component that uses the value needs to be
refreshed.
To define system configuration parameters, see the following:
 Control-M/EM system parameters (on page 45)
 Control-M/Server parameters (on page 141)
 Control-M/Agent parameters (on page 188)

Control-M/EM system parameters

In the CCM, you can change the default component system parameter values of Control-M/EM system
parameters without having to access each individual computer.
Before a modified parameter value can take effect, the component that uses the value needs to be
refreshed.
The following procedures describe how to define Control-M/EM, LDAP, Audit and Annotation, and
Control-M Self Service system parameters:
 Defining Control-M/EM system parameters (on page 45)
 Defining LDAP system parameters (on page 47)
 Defining Audit and Annotation parameters (on page 50)
 Defining Control-M Self Service parameters (on page 54)
 Defining Control-M Workload Change Manager system parameters (on page 55)
 Control-M Web parameters (on page 52)
 Defining SSL system parameters (on page 57)

Defining Control-M/EM system parameters

This procedure describes how to define Control-M/EM system parameters in the CCM.

 To define Control-M/EM system parameters:

1. From the Components Tree pane, select the Control-M/EM component and from the Home tab,
in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click Advanced.

45
Control-M Administrator Guide

3. From the system parameters table, filter for the required parameter from one of the following column
headings:
• Type
• Name
• Description
• Value
• Default Value
• Refresh Type
o Automatic: Automatically refreshes the component. In general, an Automatic parameter is
called by a utility, which accesses the current value each time it runs.
o Recycle: You need to recycle (stop and restart) the component (for example,
Control-M/Server) for the change to take effect.
o Manual: You need to perform an action that refreshes the parameter value (with no need for
recycling the component).
• Last Updated
4. Double-click the required parameter.
The Control-M/EM - Update System Parameter dialog box appears.
5. In the Value field, change the value of the parameter, as required, and then click Save.
You can use the Type, Name, and Host fields for specific components running on a specific
computer. For example: Type:BIM Name:BIM1 Host:HH12.
The Control-M/EM system parameter is defined.

Customizing the Welcome window

This procedure describes how to customize an HTML page in the Welcome window called myHomePage
that can reside on any location accessible by the Control-M client computer. This section is a customized
area where you can create your own links by mapping it to the relevant HTML file and adding your HTML
content.
 To customize the Welcome window:
1. Access the Control-M/EM system parameters window, as described in Defining Control-M/EM system
parameters (on page 45).
2. In the name column, type GettingStartedCustomizedURL.
3. Double-click the parameter.
The Control-M/EM - Update System Parameter window appears.
4. In the Value field, type the full URL of the customized HTML page.
5. Click Save.

46
Control-M Administrator Guide

Defining LDAP system parameters

This procedure describes how to define LDAP system parameters for different domains, which enables
you to authenticate Control-M/EM users with the LDAP protocol.
 To define LDAP system parameters:
1. From the Components Tree pane, select the Control-M/EM component and from the Home tab,
in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click LDAP.
3. Select Enable LDAP Authentication.
If LDAP authentication is enabled, the AuthenticationMethod system parameter is ignored and the
PasswordEncode system parameter is set to 0 . For information on configuring LDAP with SSL, see
Configuring communication with LDAP or Active Directory servers using SSL.
4. In the Add New Domain field, type the domain name that hosts the LDAP servers that authenticates
the Control-M/EM users, and then click .
Repeat this step to connect to multiple LDAP servers in other domains.
5. For each domain, type the required values, as described in LDAP system parameters (on page 48).
6. Click Activate Changes.

Setting the environment attributes

This procedure describes how to set the banner background color, title and description of your EM
environments which enables you to identify which EM environment you are connected to. If the
environment attribute fields are empty, the default banner background color is blue and the
environment's host name is used as the title.

 To set the environment attributes:

1. From the Home tab, select the Control-M/EM component and click System Parameters.
2. In the left pane, click General.
3. From the Banner Color drop-down list, select the color for the banner.
4. In the Environment Title field, type an environment name for the Control-M client applications.
5. In the Description field, type a description for the enviromment of the Control-M client applications.
6. Click Activate Changes.
NOTE: To view the updated color, environment title and description, you must log out and log in
again.

47
Control-M Administrator Guide

LDAP system parameters

The following table describes LDAP system parameters, which enables you to authenticate Control-M/EM
users with the LDAP protocol, as described in Defining LDAP system parameters (on page 47).

Field Description

LDAP Directory Server Type Determines which LDAP configuration is used for
authentication.
The values in the drop-down list are taken from the
DirectoryServiceType.cfg configuration file located in the
ctm_em/etc directory. This file contains the names of the
default types used by the system parameters, including a set of
default parameters that define the standard configuration of
the specific type. For more information, see
DirectoryServiceType.cfg parameters (on page 49).

LDAP Directory Search User Defines the name of the user that runs the search action for
users that log on. For example,
cn=admin,dc=company,dc=us,dc=com.
If this field is not defined, then the LDAP Directory Search Base
field must have a value.

LDAP Directory Search Password Defines the password of the user specified in the LDAP
Directory Search User field. The value of this field can be left
blank if the Search user does not have a defined password.

Transmission Protocol Determines one of the following transmission protocols that

LDAP uses to connect to Control-M/EM:
 TCP
 SSL
BMC recommends that you configure the SSL mode between
Control-M/EM clients and Control-M/EM servers before you
define the LDAP system parameters, as described in
Introduction to SSL for Control-M.

Server Host Name and Port Defines hostname and port number values for the computer
where the LDAP Directory Server is located.
It is not mandatory to set the port value for this system
parameter. If the port is left blank, the default value 389 (or
636 for SSL communication) is used.
Multiple active directory servers can also be defined. This
enables Control-M/EM to perform authentication against
backup active directory servers when the primary server is
unavailable.

48
Control-M Administrator Guide

Field Description

LDAP Directory Search Base Defines the starting domain name for the user search in the
directory tree structure. For example, sales.company.us.com
or dc=sales,dc=company,dc=us,dc=com.
This field must have a value if the LDAP Directory Search
User field is left blank. Otherwise the default value is the
domain where the search user is located.

DirectoryServiceType.cfg parameters
The following table describes the parameters listed in the DirectoryServiceType.cfg file.
After you edit any of the parameters in this table and save the DirectoryServiceType.cfg configuration file
located in the ctm_em/etc directory, you must refresh the various components and servers with the
changes.

Parameter Description Default Value

DirectoryUsersDnAttr Defines the LDAP users  AD: distinguishedName

distinguished name attribute
name defined in the directory  Other: dn
schema

DirectoryUsersIDAttr Defines the LDAP user attribute  AD: sAMAccountName

required to log onto
Control-M/EM  Other: cn

DirectoryGroupIDAttr Defines the LDAP attribute used  AD: sAMAccountName

when looking for group names.
 Other: cn
The values of this attribute are
entered in the first part of the
LDAP Groups Reference field, as
described in Defining LDAP
Groups (on page 264).

DirectoryGroupMembersAttr Defines the LDAP attributes of  AD: member

groups that stores its members
 Other: uniqueMember

49
Control-M Administrator Guide

Parameter Description Default Value

DirectoryGroupMembersIDAttr Defines the users that are  AD: distinguishedName

assigned within the members
attribute of groups  Other: dn

DirectoryGroupsObjectClassAttr Defines the object class attribute  AD: group

that defines the LDAP entry for
groups  Other:
groupOfUniqueNames

Defining Audit and Annotation parameters

This procedure describes how to define Audit and Annotation parameters, which determines the user
categories that is audited in the Control-M/EM database each time an audited action occurs. For each
audited action, you can define whether to prompt the user to provide an annotation to justify the user
action.

 To define Audit and Annotation parameters:

1. From the Components Tree pane, select the Control-M/EM component and from the Home tab,
in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click Audit and Annotation.
3. For each field, type the required value, as described in Audit and Annotation parameters (on page 50)
and Audit and annotation user categories (on page 51).
4. Click Activate Changes.

Audit and Annotation parameters

The following table describes audit and annotation parameters, which determine the user categories that
will be audited in the Control-M/EM database each time an audited action occurs, as described in Defining
Audit and Annotation parameters (on page 50).

Field Description

Enable audit Determines whether to enable auditing for the CCM categories

Enable annotation Determines whether to enable annotation for CCM categories

Enable automatic cleanup Determines whether to automatically delete audit information in

the Control-M/EM server database

Days to retain audit information Determines the number of days to retain audit information before
automatically deleting it from the Control-M/EM server database

50
Control-M Administrator Guide

Audit and annotation user categories

The following table describes the user categories that can be audited or annotated in the Control-M/EM
database.

Category Description

Authentication Login/logout attempts, password actions.

Scheduling definitions Job scheduling

Active network Intervention actions such as hold, free, rerun.

AJF get job information Active job information such as log, output, and statistics

Independent AJF entities Resource activities (add, delete, or update resources and global
prefixes)

Alerts handling Managing alerts

Account management Control-M/EM user and role authorizations (on page 266)

Component operations Setting the Desired State of components in the CCM to Up, Down,
Ignore, or Recycle, as described in Component status (on page
41).

Configuration management  System parameters (see System configuration (on page 45))
 Control-M Application Integrator

Control-M security  Define Control-M/Server user permissions, as described in

Control-M/Server security (on page 242).
 Connection profiles for Application Plug-ins.

Database maintenance Check database space and extend databases, as described in

Database management (on page 37).

High availability High availability (on page 306)

51
Control-M Administrator Guide

Control-M Web parameters

The following table describes Control-M Web parameters.

Parameter Description

Common

Site Logo Path Defines the location of your organization’s logo that is displayed in
the Control-M Self Service site.
Example: D:\images\logos\SLS_Custom_Logo.png
Note the following:
 The maximum size is 100w X 20h pixels.
 The logo file must be in png or jpg format.

Site Login Logo Path Defines the Login Logo path, where the site login logo is located.

Site Interface Language Determines the language of the Control-M Self Service site

User Inactivity Timeout Determines the number of minutes that Control-M Self Service
remains idle before the user is automatically logged out.

Administrator Mail Defines the Control-M Self service administrator email address that
appears in login page

Support/Helpdesk Info Describes general support information, such as help desk phone
number and administrator extension that appears in the Control-M
Self Service login page

End User's Site Portal URL Defines a URL or a network path that contains an internal site
(myhomepage) portal that is referenced by Control-M Workload Change Manager
end users. The file type can be one of the following:
 HTML
 PDF
 Microsoft Word
 Any text supported file format

52
Control-M Administrator Guide

Parameter Description

Planning

Maximum Number of Jobs in Determines the maximum number of jobs to load into a flow
Flow Diagram View diagram view. If this number is exceeded, job view automatically
changes into list view.

Order Method Default Settings: Determines whether Control-M Workload Change Manager jobs
are ordered according to specific date and time or automatically.

Automatic Save Interval Determines the number of seconds between each workspace save
(seconds): when the Auto Save preference is checked.

Monitoring

Jobs view refresh rate Determines the number of seconds to wait before automatically
refreshing the jobs

Services view refresh rate Determines the number of seconds to wait before automatically
refreshing the services

Maximum jobs in jobs view Determines the maximum number of jobs that can appear in the
Jobs view.
If there are more jobs in the service than the number defined
here, you might experience low performance. When the number
of jobs exceed its limitation, a warning message appears and the
user is prompted to select Simple Tile view.

Maximum number of services Determines the maximum number of services that can appear in
the Map view of the Services view.
If there are more services than the number defined, you might
experience low performance. When the number of services exceed
its limitation, a warning message appears and the user is
prompted to select List view.

Output file automatic load limit Determines the size of the output (in bytes) that determines
whether Control-M Self Service sends an output download
confirmation message to the user.
This occurs when the user attempts to download an output.

Job Primary Field Determines whether the JobName or MemName is displayed as

the title of the job.
Note: If JobNameMemName is selected, then Control-M Self
Service displays JobName for Distributed jobs and MemName

53
Control-M Administrator Guide

Parameter Description

for Control-M for z/OS jobs.

Maximum results in job search Determines the number of jobs that appear in a search result

Maximum viewpoints a user can Determines the maximum number of viewpoints a user can
define define

Days to keep unused viewpoints Determines the number of days to keep unused viewpoints

Enabled Job Actions Determines whether the following job actions are enabled in the
Control-M Self Service site:
 Hold
 Release
 Confirm
 Rerun
 Restart
 Kill
 Order Now
 Set to OK
 Update
 Archive Search

Defining Control-M Self Service parameters

This procedure describes how to define Control-M Self Service system parameters, such as site language,
color, and logo path.

 To define Control-M Self Service parameters:

1. Open the Control-M Configuration Manager.
2. From the Components Tree pane, select the Control-M/EM component and from the Home tab,
in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
3. In the left pane, click Self Service.
4. For each field, type the required value, as described in Control-M Self Service system parameters (on
page 55) and Control-M Web parameters (on page 52).
5. Click Activate Changes.

54
Control-M Administrator Guide

Control-M Self Service system parameters

The following table describes Control-M Self Service system parameters. To define these parameters, see
Defining Control-M Self Service parameters (on page 54).

Parameter Description

Service Rule Review Source Determines whether the Service Rule wizard inspects one
or more of the following for review in the Review and
Generate Services window:
 Jobs Definition: Inspects the job definitions in the
Control-M/EM server
 Jobs on Active Jobs database: Inspects the jobs in
Active Jobs

Defining Control-M Workload Change Manager system parameters

This procedure describes how to define Control-M Workload Change Manager system parameters.

 To define Control-M Workload Change Manager system parameters:

1. From the Components Tree pane, select the Control-M/EM component and from the Home tab,
in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click Control-M Workload Change Manager.
3. For each field, type the required value, as described in Control-M Workload Change Manager system
parameters (on page 56) and Control-M Web parameters (on page 52).
4. Click Activate Changes.

55
Control-M Administrator Guide

Control-M Workload Change Manager system parameters

The following table describes Control-M Workload Change Manager system parameters. To define these
parameters, see Defining Control-M Workload Change Manager system parameters (on page 55).

Parameter Description

E-Mail Sender Defines the sender email address that is used to send notifications
to Control-M Workload Change Manager end users.

New Folder Default Strictness Determines whether to enforce validation on a new folder or not.
Level:

Enable Site Standard Admin Determines whether a Control-M Administrator can set the
Mode Enforce Validations checkbox for a Site Standard in Folders. If
this parameter is selected, the checkbox is disabled for other
users. You must also set the New Folder Default Strictness
Level parameter to Strict.

Enable Change Management Enables the integration between Control-M Workload Change
Integration Manager and a third party change management system. If
disabled, it does not affect the other Workload Change Manager
system parameters.

REST Service URL Defines a URL for the third party change management system
REST service that is used to be integrated with Workload Change
Manager. For more information see Workload Change Manager
integration with a change management system.
If you want to use an HTTPS URL, see Configuring secure
communication between Control-M Workload Change Manager
and a REST Service.
Note: To use an HTTPS URL the web server must be configured
to work with HTTPS.

REST Service Timeout Determines the time, in seconds, for the REST Service invocation
to be considered not responsive when connecting Control-M
Workload Change Manager to the REST service.

Change Management Status Determines whether the Change Management Status button is
Button visible or hidden in the Control-M application. If enabled, users
can click the button to view the status of a request in the change
management system.

Change Ticket Field Editable Determines whether or not the Change Ticket field in Control-M
Workload Change Manager and in Control-M can be edited.

56
Control-M Administrator Guide

Defining SSL system parameters

This procedure describes how to define SSL system parameters.
 To define SSL system parameters:
1. From the Components Tree pane, select the Control-M/EM component and from the Home tab,
in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click Manage SSL.
3. For each field, type the required value, as described in SSL system parameters (on page 58).
4. Click Activate Changes.
Changes take affect after the new CA is generated, as described in Generating new certificates.

57
Control-M Administrator Guide

SSL system parameters

The following table describes SSL system parameters.

Parameter Description

SSL CA Certificate expiration Determines the expiration duration of a site CA in the Manage
duration in days SSL Generate Certificate Wizard
Default: 7300

SSL certificate expiration in days Determines the expiration duration of a certificate in the Manage
SSL Generate Certificate Wizard
Default: 7300

SSL Certificate key length Determines the number of bits of the certificate key in the
Manage SSL Generate Certificate Wizard
Default: 1024
NOTE:
 To use 4096 certificate key length, you need
Control-M/Server and Control-M/Agent version 8.0.00.300 or
higher.
 To use 2048 certificate key length, you need
Control-M/Server and Control-M/Agent version 7.0.00 or
higher.

SSL Message digest Determines one of the following cryptographic hash functions :
 sha1
 sha256
Default: sha1
NOTE: To use SHA-256 you need to install the following:
 Control-M/Server 8.0.00.401, 8.0.00.500, 9.0.00.100 or
higher .
 Control-M/Agent 8.0.00.303, 8.0.00.400, 9.0.00.100 or
higher.

58
Control-M Administrator Guide

Control-M/EM general parameters

The following table describes Control-M/EM general system parameters in the Advanced section of the
CCM.

Parameter Description

act_chk_inpermitt_gcs_gui Do not modify this parameter unless requested by BMC Software

Customer Support.
Default: N

ActivateApplications4NonAdmin Determines whether to activate applications for users who do not

have administrator rights.
Valid Values:
 1: On
 0: Off
Default: 1

AlertsLimit Limits the number of alerts

NOTE: If the value is set to 0, the Control-M client shows unlimited
number of alerts.

AllowListEMUserNames Determines whether users can view a list of user names (used by
Control-M for AFT configuration plug-in).
Valid values:
 0 - Not permitted
 1 - Permitted (default)

AllowLoginWithNonTrustedSSLCe Determines whether to enable users to log in to the Control-M client

rtificate and and CLI utilities when the SSL certificate is not trusted.
NOTE: This parameter does not affect the CCM. If the SSL
certificate is not trusted, a warning message appears but the login
process continues.
Valid values:
 1: Disabled
 0: Enabled
Default: 1

AnnotationDefaultCategory Sets the default value when an annotation description is missing.

Default: Utility

59
Control-M Administrator Guide

Parameter Description

AnnotationDefaultNote Sets the default value when an annotation note is missing

Default: Command line utility invocation

ApplicationFieldIsMandatory Determines whether the Application field is mandatory for job

definition.
Valid values:
 0 - Not mandatory
 1 - Mandatory
Default: 0

ApplyAnnotationForAuditContext Specifies the activities that require user annotations.

Valid values:
 ALL – All of the activities listed below
 NONE – None of the activities listed below
 AUTH – Authentication (logon tries, logouts, password actions)
 SCHED – Scheduling definition activities
 J_CONT – Active network activities (control requests)
 J_INFO – Active job information activities (order, force, hold ...)
 RES – Quantitative and Control resource activities
 ALERT – Alerts
 ACCOUNT – Account management activities
 OPER – Start and stop components using the Control-M
 Configuration Manager
 CONFIG – Configuration operations from Control-M
Configuration
 Manager
 CTMSEC – Control-M/Server security interface using Control-M
 Configuration Manager
 DB_MAINT – Database maintenance operations using Control-M
 Configuration Manager
Default: AUTH SCHED J_CONT J_INFO RES ALERT ACCOUNT
OPER CONFIG CTMSEC DB_MAINT

60
Control-M Administrator Guide

Parameter Description

AuditCleanupIntervalMinutes When cleanup of audit information from the Control-M/EM database

is automatic, this parameter specifies the interval, in minutes, at
which the GUI Server performs its cleanup operations.
Valid values: 60 and up
Default: 360 (minutes)

AuditCleanupOn Specifies whether cleanup of audit information from the

Control-M/EM database should occur automatically.
Note: When automatic cleanup of audit information is activated, the
GUI Server first waits the specified number of minutes (as specified
in the AuditCleanupIntervalMinutes system parameter) before
cleaning the auditing table the first time.
Valid values:
 0: Cleanup is performed manually by the user as necessary
 1: Cleanup is automatic
Default: 1

AuditFullDefinitionChanges Determines whether to audit all changes to the job definition when
it is updated.
Valid values: 0,1
Default: 1 - Audit all changes when job definition is updated

AuditHistoryDays When cleanup of audit information from the Control-M/EM database

is automatic, this parameter specifies the number of days that audit
information is retained before being cleaned from the Control-M/EM
database.
Minimum values: 1
Default: 7

AuthenticationMethod Name of the external authentication plug-in.

Default: null (for internal Control-M/EM authentication)

AutomaticOrderMethodByDefault Determines whether the default for folders that are created by Order
Method is automatic or manual.
Valid values:
 1: Automatic Order Method (Daily)
 0: None (Manual Order)
Default: 1

61
Control-M Administrator Guide

Parameter Description

bulk_def_size Default bulk size for database bulk operation.

Valid values: 10-10000
Default: 100

bulk_def_storage_len Default value for storage length in bulk operation. Must be at least
as long as the longest field involved in the bulk operation.
Default: 264

CentralDeployLocation Defines a network location where the installation packages for Agent
Deployment are saved.
NOTE: After you defined the value for this parameter, restart the
Control-M/EM Configuration Agent.
Default: Empty

ChallengeResponseTimeout Time interval in seconds after the server issues a request and
receives a response from the client. If a response is not received
during this interval, the server sends a FAILURE message and
terminates the communication.
Default: 60

CheckDifferentHosts Identifies if the component with the same name should be checked
on other machines when registering in the Database.
Valid Values:
 1: The component is checked
 0: The component is not checked
Default: 1

CheckLimitsSwitch Determines whether to check if OS resource limits are set

appropriately.
Valid values:
 1: On
 0:Off
Default: 1

CGSCommUserIGd Defines the ID that GCS uses to identify itself to Convrol-M. This
user must be defined in the Control-M with add or delete condition
privileges.
Valid values: <String expression>.
Default: GCSERV

62
Control-M Administrator Guide

Parameter Description

ClientSSO Determines whether the Disable SSO mode checkbox appears in

the Control-M login window.
Default: Off
Valid values:
 On
 Off

CollectEMStatistics Determines whether the Control-M/EM Statistics collection

mechanism is on or off.
Valid values:
 0: Off
 1: On
Default: 1

CollectStatisticsByField Specifies the job field by which statistics are collected for distributed
jobs.
Valid values: Control-M job definition fields
Default: Jobname

CollectzOSUserDaily Specifies whether the Gateway automatically requests updates from

Control-M for z/OS for the following information:
 ordered jobs
 table list
 user daily list
The information is saved in the Control-M/EM database.
Valid values:
 0 - No requests are sent
 1 - Requests are sent
Default: 1

63
Control-M Administrator Guide

Parameter Description

ConsiderDSN Specifies whether the ordering job and table keys (used when
sending job ordering information from Control-M for z/OS to the
Gateway) includes dataset names. Typically, the dataset name is
changed for each job order.
Valid values:
 0 - Do not include the dataset name
 1 - Include the dataset name
Default: 1

ControlM_EM_Version Specifies the Control-M/Enterprise Manager version.

ControlResourceForSMARTTable Enables definition of Control Resources for SMART and Sub folders
in Control-M Servers from release 7.0.00.200, however
Control-M/EM clients of versions lower than 7.0.00.300 , can not
login to the Control-M/Enterprise Manager.
Valid values:
 1: On
 0: Off
Default: 0

CTMSyncExceptions Excludes folders from automatic synchronization

(upload/download/delete) by the Gateway where the
synchronization mode is set to No Synchronization.
EXAMPLE: If the Control-M synchronization mode is set to Update
Control-M/Server and Control-M/EM and this
parameter is defined as "A*,B*" folders that start with A
or B are not downloaded automatically from
Control-M/Server to Control-M/EM and are not uploaded
automatically from Control-M/EM to Control-M/Server.
You can set this parameter for each Control-M/Server separately or
for all (*).
Valid values: A valid regular expression (see Pattern matching
strings).
Default: Empty (no exceptions).
If you modify the value, you must recycle the GUI Server and the
Gateway components.

64
Control-M Administrator Guide

Parameter Description

DatabaseCheckInterval Amount of time between database availability checks by certain

server components.
Valid values: Do not change this parameter unless instructed to do
so by BMC Software Customer Support.
Default: 10

DatabasePoolSize Determines the maximum number of connections to the database

retained in the connection pool of each server component.
Valid values: Do not change this parameter unless instructed to do
so by BMC Software Customer Support.
Default: 5

DatabaseRetries The maximum number of attempts by a server component to

perform certain actions with the database.
Valid values: Do not change this parameter unless instructed to do
so by BMC Software Customer Support.
Default: 10

DatabaseRetryInterval The amount of time between the attempts set in DatabaseRetries.

Valid values: Do not change this parameter unless instructed to do
so by BMC Software Customer Support.
Default: 10

DataSegmentLimitGB Specifies the data segment size limit in GB.

Default: 2

DefaultAverageTime Average run time for jobs with no statistics. This value is often used
if no statistics are available.
Valid values: Any valid time, entered in the following format:
MM:SS
Default: 00:05

65
Control-M Administrator Guide

Parameter Description

DefaultCTMExcludeRBC Determines Excluded Rule-based Calendar (RBC) support in a newly

defined Control-M/Server. The value is overridden by the value set
in the Control-M/Server system parameter EXCLUDE_RBC_ENABLED.
Valid values:
 Y - Supports Excluded RBC in a defined Control-M/Server
 N - Does not support Excluded RBC in a defined
Control-M/Server
Default: Y
If this feature was disabled during the fix pack installation, you need
to change RBC names that start with ! and run the
enable_exclude_rbc.pl perl script from the <scripts> directory.

DeleteChunkSize Maximum number of rows to be deleted by a single SQL statement,

used by purge_runinfo and erase_audit_data scripts.
Default: 10,000
Valid values: A whole number equal to or greater than 1.

DirectoryConnRefreshTime Specifies the time interval, in seconds, passed from last refresh,
after which EM refreshes LDAP connection during authentication.
Valid values: 1-60 seconds
Default: 45

DirectoryDefaultDomain Specifies the default LDAP directory domain name for user
authentication

DirectoryServiceAuth Determines the Directory Service mode for authentication purposes.

Valid values:
 On - LDAP authentication is used
 Off - Control-M/EM authentication is used
Default: Off

DirectoryServerChaseRef Determines if LDAP search action should chase referrals suggested

by the server.
Valid values:
 1:On
 0:Off
Default: 0

66
Control-M Administrator Guide

Parameter Description

DirectoryServerConnAttempts Specifies the maximum unsuccessful connection attempts allowed to

the LDAP server.
Default: 3

DirectoryServerConnNetworkTim Specifies the connection network timeout to LDAP server in seconds.

eout
Valid values: 5-120
Default: 20

DirectoryServerHostPort The full domain name of the host on which the LDAP server is
installed and the port on which to communicate with the LDAP
server.
Format: full domain name:port number
Example: CTMhost1.DOMAIN1.level1:389
Default: <null>
Note: Multiple LDAP servers can be defined. This enables
Control-M/EM to perform authentication against backup LDAP
servers when the primary server is unavailable.

DirectoryServiceSpecialChar Sets the list of characters considered to be special in LDAP.

Default: \()

DirectoryServiceTimeout Sets the time interval in seconds for which EM waits for LDAP
actions return.
Valid values: 1-60 seconds
Default:10

DirectoryServiceUseEscChar Determines if the escape character should be overridden in Directory

Service when sending the search string.
Valid values:
 1: On
 0: Off
Default: 1

67
Control-M Administrator Guide

Parameter Description

DirectorySearchUserDN Stores the LDAP Domain Name (DN) credentials for a special user
who has read access to the directory. This parameter is mandatory if
the value of the DirectoryServiceType parameter is Active
Directory, otherwise it is optional.
If no value is used, the parameter value is interpreted as an
anonymous user (Default).
Valid values:Either the URL notated definition of the user ID or its
DN.
EXAMPLE:
 jsmith@PRODUCTION.bmc.com
 cn=Schemp Anderson, o=family, c=US, dc=hotmail, dc=com

DirectorySearchUserPwd Stores the LDAP password for the search user defined in the
DirectorySearchUserDN parameter who has read access to the
directory. Optional if the value of the DirectorySearchUserID
parameter is empty or anonymous.
Valid Values: The value is an encrypted password string. which is
entered into the parameter value field as regular text and is then
converted to an encrypted string before being stored in the
database. Thereafter, the displayed value is the encrypted string
whenever the parameter is accessed in the System Parameters
window. If no value is used, the parameter value is interpreted as
blank (Default).

DirectoryServiceType Defines the LDAP directory type or vendor that is available to the
enterprise, for example, Active Directory, iPlanet, Apache Directory.
This definition points to the relevant parameter load section in the
DirectoryServiceType.cfg configuration file in the ctm_em/etc.
The value of this parameter should be listed in this file. By default,
two default directory service types (Active Directory and iPlanet) are
provided in the configuration file. The default value of this
parameter is Active Directory.

68
Control-M Administrator Guide

Parameter Description

DirectoryServiceValidation Determines the validation level of Directory Service parameters

when connecting to LDAP.
Valid values:
 0: Specifies that validation is not performed
 1: Specifies that only the fields defined in the CCM LDAP
configuration window should be validated for existence.
When LDAP authentication is applied directly on users defined in
Control-M/EM Authorizations (on page 263), LDAP Directory
Search User and LDAP Directory Search Base parameters are
optional. In all other cases, at least one of these parameters
must be used.
 2: Specifies that all the fields defined in the CCM LDAP
configuration window and the parameters defined in the
DirectoryServiceType.cfg file should be validated for successful
LDAP access and implementation.
Default: 1
Refresh type: manual
The best configuration duration time can be achieved by setting this
parameter to bypass validation actions during Control-M/EM startup
or LDAP activation. This can be done after validating your
configuration at least once to ascertain that all the configuration
values are valid.

DirectoryServerProtocol Determines the security level of communication with the Directory

Server.
Valid values:
 TCP
 SSL
Default: TCP

69
Control-M Administrator Guide

Parameter Description

DirectoryUsersSearchRoot Defines the starting point (domain, country, and so on) in the
directory tree structure. The domain name values in this field
supports both dot separated or DN format, For example,
"PRODUCTION.bmc.com" or "c=us, o=acme, dc=root". You can
define multiple starting leafs by separating them with colons (":").
The lookup order is from left to right, according to the domain list
order.
If the value of this parameter is NULL then a default value will be
used, only if the DirectorySearchUserDN parameter is not blank. The
DirectoryUsersSearchRoot parameter can only be left blank if the
DirectorySearchUserDN has a configured value. The default value of
DirectoryUsersSearchRoot is the domain of the search user. For
example, if the DirectorySearchUserDN parameter value is
"jsmith@PRODUCTION.bmc.com", then the default value of
DirectoryUsersSearchRoot parameter would be
"PRODUCTION.bmc.com".

EmailSender Defines the email address that issues the high availability alert.

EmailServer Defines the E-mail server that is used to send notifications emails to
Control-M Workload Change Manager end users.

EmailRecipients Defines the email addresses that receive the high availability alerts.
The email addresses must be separated by a comma.

EmdefValidationVersion Sets the validation version used by the emdef utilities.

Valid Values:
 1: Validation version 1
 2: Validation version 2 (default)

EnableLoadBalancerRouter Enables you to define a third party Network Load Balancer Router,
which sends the jobs to specific Control-M/Agents according to its
own load balancing definitions.
Valid Values:
 True
 False
Default: False

70
Control-M Administrator Guide

Parameter Description

EnableRemoteBrowsing Enables you to browse for a script in a file system on a

Control-M/Agent node from the job properties pane.
Valid values:
 Y
 N
Default: Y

Environment Title Defines the logical name for the Control-M/EM environment, which
appears in the Control-M title bar.
Valid values: Any. Free Text field

GCSCommUserId Defines the ID that GCS uses to identify itself to Control-M. This
user must be defined in the Control-M/Server with Add or Delete
permissions.
Default: GCSERV

GlobalCondsTimestampActivation Sends a Timestamp with every Global condition action (Add or

Delete condition).
Valid Values:
 0: Disables the feature
 1: Enables the feature
Default: 0
NOTE: You should only enable the feature if is supported by
Control-M/Server.

HandleAlertsOnRerun Determines how to handle alerts when a job is rerun.

Valid values:
 0: Alerts for this job that are in the Alerts window before the job
is rerun are not automatically changed to HANDLED. If the rerun
fails, a new alert is displayed in the Alerts window.
 1: Alerts for this job that are in the Alerts window before the job
is rerun are automatically changed to HANDLED.
Default: 0

71
Control-M Administrator Guide

Parameter Description

HostPort Defines the hostname and port number or a port range for all
components.
NOTE: If you want to define a different host and port/port range for
each component instance, you need create additional HostPort
system parameters, as described in Defining Control-M/EM system
parameters (on page 45).
Format:
 Port:<hostname>:<port number> (CTMhost1:1530)
 Port range:<hostname>:<fromPort-toPort>
(CTMhost1:1520-1540)

I18N Indicates whether the system is configured for CJK languages or

Latin1 languages.
Warning: This parameter is automatically set during installation,
according to the specified choices, and must not be changed
manually.
For more information, see Control-M Installation
Valid values:
 cjk
 latin1
Default: latin1 or cjk

IPV_MODE Determines whether to enable IPV6.

Valid Values:
 IPV4
 DUAL (Enables IPV6)
Default: IPV4
How / where to set: In the config.dat file of Control-M/Server
and the CONFIG.dat file of Control-M/Agent, set the IPV_MODE
parameter to DUAL and then restart both Control-M/Server and
Control-M/Agent.
NOTE: If Control-M/Server and/or Control-M/Agent are installed on
AIX, verify that the fix for APAR IV23320 is installed.
If you want to enable IPV6 before installation, see Setting
environment variables in UNIX.

72
Control-M Administrator Guide

Parameter Description

Language Language for the Control-M/EM application. These values are not
case-sensitive.
Valid values:
 use_account_locale — language set for the account and
computer us_english
 english
 german
 french
 spanish
Default: use_account_locale

LimitGCDistribActivate Enables and disables limitations on the distribution of global

conditions using the Global Conditions Distribution facility.
Valid values:
 _ 1 – The Global Conditions Distribution facility distributes
global
conditions according to limitations defined using the
LimitGCSDistribMaxDays and LimitGCSDistribExcludeDates
parameters.
 _ 0 – The Global Conditions Distribution facility imposes no
limitations on the distribution of global conditions.
Default: _1

LimitGCDistribExcludeDates Dates for which global conditions are distributed, regardless of

limitations specified using the LimitGCSDistribMaxDays parameter.
Dates are specified in mmdd format and separated with commas.
Default: STAT

LimitGCDistribMaxDays The range of days within which conditions can be distributed.

Valid values: 1-28
Default: 7

LMGUI_Communication_Cfg License Manager address. Not yet implemented.

Default: null

73
Control-M Administrator Guide

Parameter Description

LockAccountForMinutes Time interval, in minutes, after which an account that was

automatically locked is automatically unlocked. (Accounts locked by
an administrator are not unlocked automatically.) If set to 0, the
account is not automatically unlocked but an administrator can
manually unlock it.
Valid values:Positive integer values
Default: 0

MainEMServiceContext Determines the logical name context of GUI Server that the
Control-M Self Service Web server must connect to.
Valid values: GUI Server logical name
Default: Empty

MaxAuditsToDelete When cleanup of audit information from the Control-M/EM database

is automatic, this parameter specifies the maximum number of audit
records to delete during each automatic cleanup operation. If the
number of audit records to clean is higher than this number, no
records are deleted and a message is issued to the GUI Server
diagnostic log asking you to clean audit records manually using the
erase_audit_data script.
Valid values:Positive integer values
Default: 2000

MaxDaysAlertRetained Defines the number of days the alert is retained in the database.
Default: 30

MaxRecentItemsInList Defines the number of recent items in any list.

Default: 40

MaxPasswordLength The maximum number of characters for user passwords.

Note: If a Control-M administrator uses the Control-M/EM
Authorization to set a password, this parameter is ignored.
Valid values: Any value between the MinPasswordLength and 32
(inclusive).
Default: 32

MaxTableJobsToAudit The maximum number of jobs in the table to be audited.

Valid values: Any whole number that is equal to or greater than 1.
Default: 1000

74
Control-M Administrator Guide

Parameter Description

MeasurementDaysToKeep Defines the number of days to keep collected metrics data.

Default: 90 days

MFTActiveConnectionsChartUnits Determines the units that appear in the Bit Rate tab in the Active
Connections area.
Valid values:
 B
 KB
 MB
 GB
Default: KB

MFTRefreshRate Determines the number of seconds between each refresh in the MFT
dashboard.
Default: 60

MFTTrafficLoadChartUnits Determines the units that appear in the Volume tab in the Traffic
Load area.
Valid values:
 B
 KB
 MB
 GB
Default: KB

MinPasswordLength The minimum number of characters for user passwords.

Note: If a Control-M administrator uses the Control-M/EM
Authorization window to set a password, this parameter is ignored.
Valid values: Any value between 1 and the MaxPasswordLength
(inclusive).
Default: 6

75
Control-M Administrator Guide

Parameter Description

ModifyJobFieldsBlock Determines whether to disable editing of the Command line and

Node ID Group fields for all non-admin users in the Monitoring
domain.
Valid values:
 CMD_LINE
 NODE_ID

NrHandledAlarms The maximum number of handled alerts saved in the database (in
addition to not-yet-handled alerts).
Valid Values:Positive integer values
Default: 2000
Note: When set to 0, there is no maximum number of handled
alerts, and they will be deleted if they pass the threshold defined in
MaxDaysAlertRetained parameter value.

NumberofConnectionAttempts Defines the number of connection attempts between the client (CCM
or Control-M) and the GUI Server for connection recovery.
Default: 5

NumberOfEstimationRunTime Defines the maximum number of estimated run times sent from
Control-M/EM Server to the client for one cyclic job.
Default: 50

NumberOfPastRunTimes Defines the maximum number of past run times sent from
Control-M/EM Server to the client for one cyclic job.
Default: 50

NumberOfFailedLogins The number of sequential failed logins after which an account is

locked.
Valid values: 0-100
Default: 0 (indicates that “automatic account locking” is not
enabled and accounts are never automatically locked).

NumberOfPasswordReplacement The number of password changes that must occur before a

s password can be reused (if PasswordHistoryOnOff is set to 1).
Note: If a Control-M administrator uses the Authorization facility to
set a password, this parameter is ignored.
Valid values: 1-20
Default: 10

76
Control-M Administrator Guide

Parameter Description

NumberOfReportDays Determines the number of days to keep report data in the database
for generating reports about services.
Valid values: 2 and higher
Default: 90

NumberOfReportDaysHistory Determines the number of days to keep history report data in the
database for generating history of services.
Valid values: 2 and higher
Default: 90

OutputAutoLoadLimit Determines the size of output data that Control-M loads

automatically. If the output data size exceeds the threshold, then
the user is prompted to save the output data in a separate
temporary file.
Default: 10000000

PasswordComplexityOnOff Indicates if passwords need to comply with complexity rules.

Note: If a Control-M administrator uses the Authorization facility to
set a password, this parameter is ignored.
Valid values:
 0 (no = off)
 1 (yes = on)
Default: 0

PasswordComplexityRules One, some, or all of the following values separated by a blank

space. Multiple values are joined by AND logic.
Note: If a Control-M administrator uses the Authorization facility to
set a password, this parameter is ignored.
Valid values:
 PWD_DIGIT: using digits is mandatory
 PWD_UPPER: using letters in upper case is mandatory
 PWD_LOW: using letters in lower case is mandatory
 PWD_NON_LETDIG: non-alphanumeric characters are
mandatory
 PWD_DIGIT PWD_UPPER PWD_LOW
PWD_NON_LETDIG: all of these rules to be satisfied.
(Default)

77
Control-M Administrator Guide

Parameter Description

PasswordEncode Indicates how user passwords are transmitted by clients to the

server.
Valid values:
 0 - Two-way encryption (encoded). Often used with External
Authentication.
When using the AES algorithm, you can use the default
hard-coded string, or the string in the aes_key.txt file, if it exists
in the etc directory.
 2 - One way encryption.EM local authentication
Default: 2

PasswordExpirationOnOff Determines whether password expiration parameters should be

checked.
Valid values:
 0 (off, password expiration is not checked).
Note: When set to 0, other password expiration parameters can be
edited but are ignored.
 1 (on, password expiration is checked).
Default: 0

PasswordHistoryOnOff Determines whether password history is recorded.

Note: If a Control-M administrator uses the Authorization facility to
set a password, this parameter is ignored.
Valid values:
 0 (no). If set to 0, new passwords are not checked against
previous passwords.
 1 (yes)
Default: 0

PasswordLifetimeDays Determines the number of days before the password expires. Used
in the password expiration date computation by the
set_pwd_def_lifetime script.
Valid values: 1 - 365
Default: 60

78
Control-M Administrator Guide

Parameter Description

PermitManualUnlock This parameter specifies whether non-administrators can manually

unlock their own tables (for example, if tables are locked during an
abnormal disconnect from the GUI Server).
NOTE: Non-administrators will not be able to unlock other users’
tables.
Valid values:
 1 - Users can unlock their own tables
 0 - Only administrators can unlock the table
Default: 1

ProxyNewsfeedHostPort Determines the host and port of the proxy server for all users
connecting to the Newsfeed through a proxy server.
Valid values: <host>:<port>
EXAMPLE: Venus:13888
Default: Empty

RecentItemsRetainDays Defines the maximum number of days recent items are retained in
the database.
Default: 60

RemoteBrowseEntriesMaxLimit Determines the maximum number of objects (files-directories) that

are allowed for a Remote Browsing request.
Valid values: Any whole integer
Default: 1000

restricted_cm_admin Determines how to manage privileges for users and groups to

access and update application plug-in connection profiles.
Valid values:
 0: Privileges managed by the CCM (see Privileges (on page
273))
 1: Privileges managed by the cm_admin.xml file.
Default: 0
For more information see Authorizing non-administrators to manage
application plug-in connection profiles (on page 304).

79
Control-M Administrator Guide

Parameter Description

RFAllowReportForJobLevelAuth Determines whether to allow users with job level authorizations to

generate reports from Control-M Reports.
Valid values:
 Y
 N
Default: Y

RFPGUseDeclareFetch Determines whether to enable the UseDeclareFetch option in

Control-M Reports with PostgreSQL database.
Valid values:
 0: Not enabled
 1: Enabled
Default: 1

RunTimeDeleteHistChunkSize Indicates the maximum number of rows in the database of historical

data to be deleted, each time a deletion is performed.
Valid values:Positive integer values
Default: 25000
Note: This system parameter is relevant only if Control-M/Forecast
is installed.

RunTimeDeleteHistInterval Interval in seconds between the deletion of historical records.

Valid values:Positive integer values
Default: 21600
NOTE: This system parameter is relevant only if Control-M/Forecast
is installed.

SecondsBetweenConnAttempts Defines the time interval in seconds between connection attempts.

Default: 5

80
Control-M Administrator Guide

Parameter Description

SendAlarmToScript Full path name of the script that is activated when an alert is
generated.
This script is activated only if the value of SendSnmp is either 1 or
2.
Valid values:Full path name of the script that is activated when an
alert is generated.
Default: script_name
When Alert data is sent as input to a script, the parameters are sent
in the following format:
call_type: "<call_type>" alert_id: "<alert_id> "
data_center: "<data_center> " memname: "<memname> "
order_id: "<order_id>" severity: "<severity>" status:
"<status> " send_time: "<send_time>" last_user:
"<last_user> " last_time: "<last_time> " message:
"<message>" run_as: "<run_as>" sub_application:
"<sub_application> "
application: "<application> " job_name: "<job_name> "
host_id: "<host_id> " alert_type: "<alert_type>"
closed_from_em: "<closed_from_em> " ticket_number:
"<ticket_number> " run_counter: "<run_counter> "
notes: “<notes>”
NOTE: The last data field is visible only if the SendAlertNotesSnmp
parameter is set to 1, and in Control-M/EM 7.0.00 fix pack 2 and
later.
EXAMPLE: for testing SNMP traps when enabling this parameter
On UNIX:
#!/bin/sh
echo $* > /tmp/snmptest.out
On Windows:
echo %* > c:\snmptest.out
NOTE: On Windows, double back-slashes should be used as a
delimiter.

81
Control-M Administrator Guide

Parameter Description

SendAlertNotesSnmp Specifies whether Alerts NOTES data field text should be sent to
SNMP and script.
Valid values:
 0 - field is not sent to SNMP and script
 1 - field is sent to SNMP and script
Default: 0
NOTE: The SendAlertNotesSnmp parameter is available for
Control-M/EM 7.0.00 fix pack 2 and later.

SendPre800NamesAlarmScript Enables you to set alert field names and to send alarm exit scripts
written before Version 8.0.00.
Valid values:
 0: Does not enable you to set alert field names and alarm exit
scripts written before version 8.0.00
 1: Enables you to set alert field names and alarm exit scripts
written before version 8.0.00
Default: 0

SendRuntimeEstimations Specifies whether BIM runtime information updates are sent to the
GUI.
Valid values:
 0 - disables the Show/Hide Time field from the View tab in
the Montoring domain
 1 - enables the Show/Hide Time field from the View tab in the
Monitoring domain
Default: 0

SendSnmp Indicates where Alert data is to be sent.

Valid values:
 0 - SNMP only
 1 - User-defined script only
 2 - SNMP and user-defined script
Default: 0
NOTE: Alert data is sent to SNMP (values 0 or 2) only if the value of
the SnmpSendActive parameter is set to 1.

82
Control-M Administrator Guide

Parameter Description

ShowNewsfeedDomain Determines whether the Newsfeed domain appears in the Control-M

client.
Valid values:
 0 - Hide
 1 - Show
Default: 1

SnmpHost Host name or list of host names (if a list, using semi-colons (;) as
delimiters) to send the SNMP trap on an alert. Specific ports can be
set using a colon (:) as a delimiter.
Valid values:Valid hostname or ip address
Default: <no_host>
Example: dhost1;jhost2;myhost3:2000

SnmpSendActive Determines whether SNMP messages for Active Alerts are

generated. Valid values.
Valid values:
 0—SNMP messages for Active alerts are not generated
 1—SNMP messages for Active alerts are generated
Default: 0

SubApplicationFieldIsMandatory Enables you to set a mandatory Sub Application field for job
definition.
Valid Values:
 0: Not mandatory
 1: Mandatory
Default: 0

UnsupportedClientVersions For BMC Software Customer Support use only.

Valid values: List of releases separated by semicolons. For
example, 7.0.00.100;7.0.00.200
Default: 0

83
Control-M Administrator Guide

Parameter Description

UserAuditOn Indicates if the user will be required to enter details about the type
of operation being performed and the reason for its performance,
which will be saved as an annotation to the audit report, before
completing the operation. UserAuditOn must be defined as 1 for
UserAuditAnnotationOn to activate.
Valid values:
 0 (no) - When 0, the UserAuditAnnotation parameter is ignored.
 1 (yes)
Default: 0
Refresh Type: Manual

UseAutoReconnect Defines the reconnection invocation method.

Valid values:
 1: Automatic
 0: Manual
Default: 1

UsezOSTimeZone Enables the to user to override the GMT value and ignore the value
sent by Control-M/Server. Relevant to Control-M/Server for z/OS.
Valid values:
 1: Override values
 0: Cannot override values
Default: 0

ViewSysoutHeadSizeKB Displays the first KB of the output file.

Valid values:
 1: First KB of the output file
 0: Whole file
Default: 0

ViewSysoutTailSizeKB Displays the last KB of the output file.

Valid values:
 1: Last KB of the output file
 0: Whole file
Default: 0

84
Control-M Administrator Guide

Parameter Description

VMAdditionalJobsRelateFields Additional job related key fields to be defined by a user.

BMC Software recommends that you not use the same job name (or
mem name, in Control-M for z/OS) for multiple jobs. If you use the
same name for multiple jobs, use this field to identify additional key
fields that Control-M/EM can use to distinguish between different
jobs with the same name/mem name, so as not to confuse or switch
their job histories.
A space must be used as a delimiter between key field values:
HOST_ID OWNER CMD_LINE
Recommended Values: DESCRIPTION, MEM_LIB, HOST_ID,
OWNER, DAYS_CAL, WEEKS_CAL, CONF_CAL, CMD_LINE,
FROM_TIME, TO_TIME, ACTIVE_FROM, ACTIVE_TILL
Valid values: Do not change this parameter unless instructed to do
so by BMC Software Customer Support.
Default: <empty>
Refresh Type: Manual

VMVersionsNumberToKeep The number of versions of the job to keep, including the current
version.
NOTE: A job version is deleted only when all of the following are
true:
 The version exceeds VMVersionsNumberToKeep.
 The version exceeds VMMaxDaysRetainCurJobsHistory.
 Automatic cleanup has run, as determined by
VMCleanupIntervalMinutes.
BMC Software recommends not setting a value greater than 30
because of possible performance degradation.
To deactivate version history, set the parameter to 1 (keep current
version only).
Valid values: Any whole number that is equal to or greater than 0.
Default: 2 (current version, and one history version)
Refresh Type: Manual

WarningPasswordExpirationDays Number of days prior to password expiration during which a warning

message is generated when certain utilities or scripts are run or a
successful logon occurs.
Valid values: 0-90
Default: 0 (no warning is generated)

85
Control-M Administrator Guide

Parameter Description

WarningSSLExpirationDays Number of days prior to certificate expiration during which the GUI
server generates a warning message in the CCM.
Valid values: 1-365
Default: 60

WebServersLoadBalanceEnabled Enables Web Server load balance by allowing emThrift web app to
retrieve servers.
Valid values:
 0: Disables Web Server load balance
 1. Enables Web Server load balance
Default: 0

WorkloadHistoryMaximumNum Defines the Maximum number of workload versions in the database.

Default: 100

WorkspaceSharing Enables users to view a Workspace owned by other users.

Valid values:
 0: Disables users to view a Workspace owned by other users
 1: Enables users to view a Workspace owned by other users
Default: 1

XAlertsEnableSending Determines whether the option to send exception alerts is enabled

or disabled.
Valid values:
 1 - Enable
 0 - Disable
Default: 1

XCTMDoForceAudit Enables a XCTM Do Force Audit

Valid values:
 Yes: Enables you to perform a Cross Control-M Job Order audit.
 No
Default: No

XCTMDoForceRetryIntSeconds Defines the number of seconds that Control-M/EM waits in case of

temporary failure, before trying to perform the force request.
Default: 300

86
Control-M Administrator Guide

Parameter Description

XCTMDoForceRetryTimeoutMinut Defines the number of minutes in which Control-M/EM tries to

s perform a force request.
Default: 1440

XCTMDoForceUser Defines a user ID where authorization is enforced.

Default: use_job_owner

87
Control-M Administrator Guide

Gateway parameters
The following table lists the Gateway parameters:

Parameter Description

AlertOnAbend Indicates whether alerts are (1) or are not (0) sent for jobs that end
NOTOK.
Valid Values:
0 - Alerts are not created.
1 - Alerts are created
Default: 1

AlertOnAbendTableEntity Determines whether to create an alert for a SMART folder that ended NOT
OK.
Valid Values:
 N: Alerts are not created.
 Y: Alerts are created
Default: N

AlertOnAbendUrgency Defines the urgency level for Gateway alerts for jobs that end with the
status Ended Not OK.
NOTE: Recycle the gateway for new settings to take effect
Default: Very Urgent

CollectzOSUserDaily Specifies whether the Gateway automatically requests updates from

Control-M for z/OS for the following information:
ordered jobs
table list
user daily list
The information is saved in the Control-M/EM database.
Valid Values:
0 - No requests are sent.
1 - Requests are sent
Default: 1

88
Control-M Administrator Guide

Parameter Description

CommCtmBufferSize The number of bytes buffered in Gateway that are waiting to be sent to
the Control/M Server. If the number of bytes are exceeded, communication
with Control/M Server is terminated.
Valid values: Any whole number that is equal to or greater than
1000000.
Default: 50000000

CommEMBufferSize The number of bytes buffered in Gateway that are waiting to be sent to
other EM Servers. If the number of bytes are exceeded in GSR or GCS
components, communication with Control/M Server is terminated.
Valid values: Any whole number that is equal to or greater than
1000000.
Default: 50000000

ConsiderDSN Specifies whether the ordering job and table keys (used when sending job
ordering information from Control-M for z/OS to the Gateway) includes
dataset names. Typically, the dataset name is changed for each job order.
Valid values:
0 - Do not include the dataset name
1 - Include the dataset name
Default: 1

CTMSyncInterval Determine the number of seconds between for each automatic

synchronization interval per Control-M.
Default: 1800

DeltaMaxActMinutes Age, in minutes, for a net to be considered valid for distribution of Global
Conditions.
Valid values: Any whole number that is equal to or greater than 300.
Default: 2160

DownCreAlerts Flag that indicates whether to send alerts for downloaded jobs that end
NOTOK when they are run. Note: AlertOnAbend must be set to 1 for
DownCreAlert to be operational.
Valid values:
0 - Alerts are not sent.
1 - Alerts are sent.
Default: 1

89
Control-M Administrator Guide

Parameter Description

EBCDIC_cp For MVS data centers: This parameter defines the EBCDIC code page to
which ASCII data is translated.
Valid values:
0 - Instructs the gateway to use the translation table that was used by the
previous version.
1047 for English (USA)
285 for English (British)
273 for German
297 for French
284 for Spanish
Default: 0

GatewayDefaultTraceOptio Enables you to set command line trace options for multiple gateways.
ns
NOTE: If a gateway already has a trace option specified, the
GatewayDefaultTraceOptions parameter value is ignored.
Valid values: All Gateway trace option parameters
Default: <empty>

GtwCondDispatchErr Valid values:Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: CTM5050 CTM5301 CTM5311 CTM5312 CTM5323

HostPortList List of logical names of CONTROL-M data centers that are connected to
Control-M/EM.
Valid values: The host name and port number, entered in the following
format:<host>:<port>.
Default: null

GtwNumUpdateThreads Only available if GtwParallelProcessingMode is on (see below).

The number of threads in the multi-thread processing mode is indicated by
the value of this parameter.
Valid values: 2-16
Default: 2

90
Control-M Administrator Guide

Parameter Description

GtwParallelProcessingMode Enables multi-threading processing mode. The value off indicates

single-thread processing.
Valid values:
on
off
Default: 0

HostPortList Listening port host name and port number for gateways.
Valid values: The host name and port number, entered in the following
format:<host>:<port>.
Default: null

InsertAlertTries Number of times that the gateway attempts to insert an alert into
Control-M/EM. The number includes the initial attempt and can be any
whole number equal to or greater than 1.
Valid values: Do not change this parameter unless instucted to do so by
BMC Software Customer Support.
Default: 10

MaxDownHistDays Number of days that the list of downloads is saved. This list contains
abbreviated information about each download, such as date and time, net
name, and number of downloaded jobs and resources.
Valid values: Any whole number that is equal to or greater than 0.
Default: 100

MaxDailyRerunInfo Defines the number of runs per day the gateway will keep in the history
table for each job. Default: -1 (No limit
Valid values: Any whole number equal to or greater than 1

MaxOldDay Downloads are kept in the Control-M/EM database for not more than the
number of days specified in this parameter.
Valid values: Any whole number that is greater than 0.
Default: 2
NOTE: The number of downloads stored in the database is never more
than the smaller of the MaxOldDay value and the MaxOldTotal value.

MaxOldTotal Number of downloads that can be stored in a Control-M/EM database. If

this number is exceeded, the oldest download is deleted.
Valid values: Any number that is greater than 0.
Default: 4

91
Control-M Administrator Guide

Parameter Description

MaxUploadBufferMPM Valid values:Do not change this paramater unless instructed to do so by

BMC Software Customer Support.
Default: 60000

MaxUploadBufferMVS For Customer Support use only.

Default: 60000

MultiByte_cp Determines what MultiByte code page Gateway uses to translate when
sending data to a Control-M/Server of type z/OS.
Valid values: Any valid CJK EBCDIC code page

RunInfoErrorLevel Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 0

RunInfoIgnoreDevCnt Indicates the maximum and minimum length of elapsed run time between
calculation discards.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 2

RunInfoMaxSamples Indicates the maximum number of run samples to be kept per job.
Valid values:Do not change this parameter unless instructed to do so by
BMC Customer Support.
Default: 20

RunInfoProcRecords Maximum number of run detail records processed in one loop.

Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 100

RunInfoUpdCtx Configures the context in which run information is processed.

Valid values:
0 - Gateway main thread
1 - Separate thread
Default: 1

92
Control-M Administrator Guide

Parameter Description

RunInfoWaitInterval Interval in seconds between processing of run details in the Gateway.

Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 10

SSLRetries Number of times Control-M/EM attempts to establish communication with

the gateway before turning SSL on or off. SSL can either be enabled or
disabled when Control-M/EM initially tries to connect to the gateway. After
making the specified number of attempts, SSL is toggled on or off (as
required). This parameter is relevant only when SSL Enabled
communication is selected. It does not work when only TCP/IP is selected
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 2

SSLSyncTime Replaces the value of the Sync_Timeout parameter (in the Defaults.rsc
file) that determines the period of time between attempts to establish
communication with the gateway when changing the communication
protocol to SSL Enabled.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 90

StatCollection4Distributed Determines which job properties field is used to collect statistics for
distributed jobs.
Default:JOBNAME

93
Control-M Administrator Guide

Global Conditions Server administration parameters

The following table refers to Global Conditions Server administration parameters.

Parameter Description

BulkSendIntSecs Interval (in seconds) between sending groups of conditions to a reconnecting

data center.
Valid values: Do not change this parameter unless instructed to do so by BMC
Software Customer Support
Default: 0

BulkSendMax Maximum number of messages to send in a group to a reconnected data center.

Valid values: Do not change this parameter unless requested to do so by BMC
Software Customer Support.
Default: 1000000

CleanOldIntSecs Interval, in seconds, when the GCS deletes unused conditions from the
database. These conditions may have no data center destinations.
Valid values: 601 seconds (10 minutes)
Default: 900 (15 minutes)

CleanOldTimeSecs Maximum time, in seconds, unused conditions wait in the database before they
are removed. These conditions may have no data center destinations.
Valid values: 601 or higher
Default: 86400 (24 hours)

DispatchThreadsNum Determines the number of threads dispatching updates to destinations.

Default: 1

DoneGcDelIntSecs Determines the number of seconds before GCS cleans already handled
conditions from memory and the database.
Valid values: Do not change this parameter unless instructed to do so by BMC
Software Customer Support.
Default: 120

94
Control-M Administrator Guide

Parameter Description

GcDistributionPolicy Determines how to handle conflicting add or delete requests for global
conditions when the requests are received within the interval specified in
GcDoneWaitSecs.
Valid values:
 ALL: Handle all requests, in the order they arrived, until they are sent to
all destinations
 TOGGLE: Each time a new request conflicts with the current request, stop
processing the current request and start processing the new request.
 NO_TOGGLING: Continue processing the current request and ignore all
conflicting requests.
Default: TOGGLE

GcDoneWaitSecs Minimum time (in seconds) global conditions wait in memory, after they have
been sent to all connected data centers, before they are removed. This "waiting
period" prevents conditions from being sent again.
Valid values: Do not change this parameter unless instructed to do so by BMC
Software Customer Support.
Default: 120

GcMaxRetries Maximum number of retries to send conditions to a data center that had
previously returned a temporary error.
Valid values : Do not change this parameter unless instructed to do so by BMC
Software Customer Support.
Default: 5

GcRetryIntSecs Interval (in seconds) between attempts to send conditions to a data center that
had previously returned a temporary error.
Valid values: Do not change this parameter unless instructed to do so by BMC
Software Customer Support.
Default: 180
NOTE: In Control-M/EM environments with high workloads, the Global
Conditions server might not respond to life check requests because it is busy
communicating with gateways and re-sending messages. It is reccomended to
change the value to 360 or more to avoid overloading the Global Conditions
server and help it respond to the Maintenance Agent.
Refreh type: Manual

95
Control-M Administrator Guide

Parameter Description

GcTogglingForSameOp Indicates whether to activate toggling policies for identical operations (like
eration COND X ADD after COND X ADD).
Valid values:
 1: All operations
 0: For different operations (COND X DELETE after COND X ADD).
Default: 1

GcXAlertSending Determines whether to enable or disable sending xalerts when a condition is not
sent.
Valid values:
 ON
 OFF
Default: ON

MaintThreadPoolSize Determines the size of GCS maintenance thread pool.

Default: 1

PortNum Default port where GCS waits for requests from clients (such as ctl commands
or life check messages). This value is used only if a port has not been defined
using the HostPort system parameter. Furthermore, this port is used only if it is
not busy; otherwise GCS selects a free port at random.
Valid values: Do not change this parameter unless instructed to do so by BMC
Software Customer Support.
Default: 10,000

SrvrsPollIntSecs Interval (in seconds) between attempts to communicate with a gateway.

Valid values: Do not change this parameter unless instructed to do so by BMC
Software Customer Support.
Default: 60

ThreadPoolSize Determines the size of main GCS thread pool.

Default: 2

UpdCommIntSecs Interval (in seconds) between readings of the Communication Table in the
Control-M/EM database for new data centers.
Valid values: Do not change this parameter unless instructed to do so by BMC
Software Customer Support.
Default: 60

96
Control-M Administrator Guide

Global Conditions Server (GCS) logging parameters

The following table lists Global Conditions Server (GCS) logging parameters.

Parameter Description

CondLogLvl Logging information level for condition transfer activities. Information is displayed
for conditions received (In), conditions sent (Out), transfer confirmation and
rejection actions, and communication problems.
Valid values:
0 – No diagnostics
1 – Condition transfer, problem, and information received
2 – Condition transfer, problem, and information sent
3 – Value 1 + value 2 (Default)

DbLogLvl Logging information level for messages related to database activities. Diagnostic
information is displayed about condition transfer requests inserted or deleted in
the database or read from the database for recovery operations.
Valid values:
0 – No diagnostics
1 – Messages about database writing (insert, update, delete)
2 – Value 1 plus database reading (recovery operations) activity (Default)

IntLogLvl Determines the logging information level for messages related to internal GCS
actions involving temporary problems and rebound situations. The information is
displayed about GCS condition handling activities.
Valid values:
0 – No diagnostics
1 – Condition actions based on conflict handling policies
Default: 1

LogSize Maximum number of record lines in the GCS_LOG file. When the number of record
lines in the currently open GCS_LOG file reaches the value specified in this
parameter, the file is closed and a new GCS_LOG file is opened.
Valid values: Any whole number that is equal to or greater than 0. If the value is
0, the file never closes, because there is no maximum size.
Default: 15000 KB

97
Control-M Administrator Guide

Parameter Description

MaxLogs Maximum number of log files to be managed cyclically. When the number of
GCS_LOG files reaches the value specified in this parameter, the oldest file is
deleted, in order for a new GCS_LOG file to be created.
Valid values: Any whole number that is equal to or greater than 0.
Default: 5

ShowMsgIDLog Determines whether to display the new Message ID in the GCS Log.
Valid values:
 Y
 N
Default: N

Control-M Self Service parameters

After modifying Control-M Self Service parameters, stop and restart the Self Service Server component for
the changes to take effect.
For a description of all other Control-M Self Service system parameters, see Defining Control-M Self
Service parameters (on page 54).

Parameter Description

DetectInterval Determines the interval for recalculating the status of a

service.
Valid values: Time in the format of HH:MM:SS
Default: 00:01:00

MftSearchResponseTimeo Determines the number of seconds before a timeout for an

ut MFT search request.
Default: 60

SLSUserName Defines the username of the Control-M Self Service server

when it connects to the GUI server.
Valid values: String expression.
Default: slsuser

98
Control-M Administrator Guide

Parameter Description

ControlDRepository Defines the host name of Control-D/WebAccess Server

where reports are stored.

ControlDWaURL Defines the URL of Control-D/WebAccess Server.

Valid values: URL in the following format:
protocol://<Control-D/WebAccess Server Virtual
Directory>/Control-M.html
EXAMPLE: https://vw-tlv-ctm-dv22/wa/ControlM.html

DisplayOrderAsIndepende Determines if a flow in a folder is ordered uniquely. A unique

ntFlow suffix is added to every condition name. Order as
independent flow checkbox appears in the Service
Ordering window.
Valid values: Checkbox
Default: No

Control-M Workload Change Manager advanced system

parameters
The following table describes Control-M Workload Change Manager system parameters from the
Control-M/EM system parameters Advanced window. For a description of all other Control-M Workload
Change Manager system parameters, see Defining Control-M Workload Change Manager system
parameters (on page 55).

Parameter Description

NumDaysKeepApprovedReq Determines the number of days to keep approved requests data in

s the Control-M/EM database.
Default:14 days
Valid values: 0-28 days

SiteBackgroundColor Determines the site background color.

Default: SolidBlue

SiteBackgroundColorsValue Determines the site background color values.

s
Default:
SolidBlue,SolidGray,SolidBrown,SolidOrange,PatternBlue,PatternGra
y,PatternBrown,PatternOrange

99
Control-M Administrator Guide

Parameter Description

WCMEmailSubjectTemplate Defines the template for the e-mail’s subject field that is sent to the
End users after the request state changes to one of the following:
 Returned
 Approved
Default:Your request <REQUEST_NAME> for Ticket ID
<CHANGE_ID> has been <ACTION>

WCMLoginLogoPath Defines the location of your organization’s logo that is displayed in

the Control-M Workload Change Manager login page.

SiteLogoPath Defines the location of your organization’s logo that is displayed in

the Control-M Workload Change Manager interface.
c:\Control-M Workload Change Manager.jpg
Note the following:
 The maximum size is 100w X 20h pixels.
 The logo file must be in png or jpg format.

SiteInterfaceLanguage Determines one of the following as the default language for the
Control-M Workload Change Manager interface for all users:
 English
 German
 French
Control-M Workload Change Manager users can customize the
language settings from the Control-M Workload Change Manager
interface.

SiteInterfaceLanguageValu Enables you to add other possible languages as options.

es

WCMCallbackResponseTime Determines the maximum number of seconds for a job flow to

out check-in or synchronize before connection timeout.The following
error message is displayed:
Connection timeout, please check your request
status in the Home page.
Default: 60 seconds

100
Control-M Administrator Guide

Parameter Description

WCMEnforceSiteStandard Enables you to enforce the assignment of a Site Standard to a job

flow, which prevents Control-M Workload Change Manager web
users from creating a job flow without a site standard assigned.
Note: You must set the New Folder Default Strictness Level
to Strict to enable Site Standard enforcement for a new job flow.
The Enforce validations of a folder must be set to true to enable
Site Standard enforcement on existing folders.

WcmCheckInEnabled Enables the Control-M Workload Change Manager web user to

check-in a job flow without having to submit a request to the
Control-M Scheduler. If enabled, a Check-in button appears in the
Control-M Workload Change Manager web application.

Maintenance parameters
The following table describes Maintenance parameters.

Parameter Description

CheckHAinDistribuitedEM Enables the Configuration Agent to automatically recycle

components in a Distributed environment when a Failover or a
Fallback has occurred.
Valid Values:
 0: On
 1: Off
Default: 1

ComponentShowState Some Control-M/EM components, such as the GUI Server, the

gateways, and the Global Conditions server, operate hidden from
the user. These components can be displayed in command prompt
windows by setting this parameter to 1, stopping the
Configuration Agent, and restarting the agent.
Valid values: 0 and 1
Default: 0

101
Control-M Administrator Guide

Parameter Description

DelCommregAfterActivateTri Determines the number of consecutive failed activations before

es the component commreg record is deleted.
Default: 6

DiagOutputBufferSizeDefault Determines the default size limit in KB that is read from the output
KB file
Default: 100

DiagOutputBufferSizeMaxKB Determines maximum size in KB that you can set

forDiagOutputBufferSizeDefaultKB.
Default: 100

FOTimeOutMinutes Determines the number of minutes to wait for a manual Failover

or Fallback before a timeout.
Default: 5

HADBLifeCheckTries Determines the number of consecutive life check requests to the

database server without getting a response.
Default:3

HADBMaxStartupTries (PostgreSQL only) Determines the number of unsuccessful

attempts that Configuration Agent tries to start up the database
server.
Default:20

HADBTimeBetweenLifeCheck Determines the number of seconds to wait between sending life

check requests to the database server.
Default:5

HADBTimeToWaitAfterStartU (PostgreSQL only) Determines the number of seconds to wait after

p the Configuration Agent started up the database server.
Default:10

HALifeCheckTries Determines the number of consecutive failed life check requests

between the the Configuration Agent and the Control-M/EM
components before the Configuration Agent tries to start it up.
Default:3

102
Control-M Administrator Guide

Parameter Description

HAMaxStartupTries Determines the number of unsuccessful attempts that the

Configuration Agent tries to start up a component and then
crashes.
Default:50

HATimeBetweenLifeCheck Determines the number of seconds to wait between sending life

check requests to the primary Configuration Agent.
Default:15

HATimeToWaitAfterStartup Determines the number of seconds to wait after the Configuration

Agent started up a component.
Default:180

LogCleanInterval Interval, in minutes, between LogReg log cleaning operations by

the Configuration Agent.
NOTE: The Configuration Agent cleans the LogReg log every
time it is activated.
Valid values: Any whole number greater than 0
Default: 360

LogCleanLevel Amount of detail the clean operation erases from the LogReg log.
Valid values:
 0 - No deletion
 1 - Cleans only the agent’s own log messages
 2 - Cleans all log messages
Default: 1

LogHistoryDays Number of days that log entries are retained before they can be
cleaned from the log.
Valid values: Minimum of 0
Default: 1

103
Control-M Administrator Guide

Parameter Description

LogInfoLevel Level of detail in LogReg log entries recorded by the

Configuration Agent.
Valid values:
 0 - No entry
 1 - Configuration Agent-related messages
 2 - Brief component and agent related messages
 3 - Detailed component and agent related messages
Default: 2

SockRecrMaxAtmp Valid values: Maximum number of times that the Configuration

Agent can attempt to create a socket.
Default: -1 (no limit)

SockRecrWtIntr Interval, in seconds between successive attempts to create a

socket.
Valid values: Any whole number greater than 0.
Default: 10

StdoutLogInfoLevel Level of detail in standard output messages reported by the

Configuration Agent.
Valid values:
 0 - No entry
 1 - Configuration Agent-related messages
 2 - Brief component and agent related messages
 3 - Detailed component and agent related messages
Default: 2

StopGracePeriodSec Time, in seconds, that a component is given to shut down

following a Stop command. When this time is exceeded, the
Configuration Agent again tries to stop the component. If the
number of retries specified by the StopTries parameter is
exceeded, the agent kills the component.
Valid values: Any whole number greater than 0.
Default: 45

104
Control-M Administrator Guide

Parameter Description

StopTries Number of times that the Configuration Agent tries to stop the
component using the Stop command before performing a kill
operation.
Valid values: Minimum of 1
Default: 2

SyncCFGFilesCycleInterval Determines the number of seconds for the Configuration Agent to

wait between each check action of a configuration file for changes
to update in the database.
Default: 3600

GUI parameters
After modifying GUI parameters, stop and restart the relevant GUI components for the changes to take
effect.

Parameter Description

ClientRestrictions Applies restriction rules to prevent ordering unnecessary jobs.

Valid values:
 Default_Selected_jobs:Sets Selected Jobs as the default value in
the Jobs field in the Order window
 Order_confirmation: Displays a confirmation window when ordering
job
 Perceive_scheduling_Criteria: Changes the default behavior of the
Ignore Scheduling Criteria checkbox to not selected.
NOTE: Separate values with a comma.

GettingStartedCustomized Defines the URL of the customized HTML page that is used for the Welcome
URL window in the Control-M client. For more information, see Customizing the
Welcome window (on page 46).

105
Control-M Administrator Guide

Parameter Description

OrbShutdownWait For Customer Support use only. In Control-M/EM and Control M wait for
acknowledgment from the CORBA Object Request Broker (ORB) before
shutting it down.
Valid values:
 0 (No) - Control-M/EM and Control M do not wait for confirmation that
the ORB was shut down.
 1 (Yes) - Control-M/EM and Control M wait for confirmation that the ORB
was shut down.
Default: 1

OrderForceWithHoldAlway Sets the Hold option in the Order/Force window to always selected and
sOn ignores the last user selection.
Default: 0

ProcessCommandsPerVP For Customer Support use only.

Number of GUI Server commands that Control-M/EM can process at a time
for each ViewPoint. These commands include submitting, adding, and
updating jobs, and making refresh requests.
Default: 1

ProcessMFCommands For Customer Support use only.

Number of GUI Server commands Control-M/EM can process at a time.
These commands are not related to specific ViewPoints and include
displaying pop-up windows and task bar messages in the Control-M
window.
Default: 10

ProcessVPsCommands For Customer Support use only.

Number of GUI Server commands Control-M/EM can process at a time for all
ViewPoints. These commands include submitting jobs, adding jobs, updating
jobs, and refresh requests.
Default: 10

106
Control-M Administrator Guide

Parameter Description

UserChangePassword Determines if a user can change his or her own password.

Valid values:
 0 - Only users who have Full or Update permission to modify security
definitions can change their own password.
 1 - All users can change their own password.
Default: 1

allowCheckinWithValidati Enables you to Check In your workspace with validation errors.

onErrors
Valid values:
 Y
 N
Default: N

Report parameters
The following table describes the Report parameters.

Parameter Description

GeneratedReportRetention Determines the number of days to retain the report on the

Control-M/EM server computer
Default: 10

MaxResourcesAvailable Determines the maximum number of concurrent reports that can

generate
Default: 5

PreviewRowsNumber Determines the number of rows that appear in the preview report
Default: 25

ResourceMaxWaitTime Determines the number of seconds to wait before sending a

notification that the report is not generating
Default: 60000

107
Control-M Administrator Guide

GUI Server parameters

The following table describes the GUI Server parameters.

Parameter Description

Action_OrderForce_AuthLev Indicates if users with Browse access for Folder authorizations (on page
el 286) can order or force jobs.
Valid values:
 UPDATE_ACCESS – Only users with Update access can order or
force a job.
 BROWSE_ACCESS – Users with Browse access or Update access
can order and force jobs.
Default: UPDATE_ACCESS

AddJobsChunkSize Chunk size of jobs during View Point opening.

Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 1000

AlertsEnabled Determines whether Alerts Management window is enabled.

Valid values:
 0: Disabled
 1:Enabled
Default: 1

AllowQueryDBFieldValues Indicates whether Available Values options are displayed for certain
fields in the Properties Pane.
Valid values: 0 or 1.
Default: 1 (On)

AuthenticationLevel NOTE: Do not change this parameter unless requested to do so by BMC

Software.
Valid values: 0, 1, or 2.
Default: 2

108
Control-M Administrator Guide

Parameter Description

AuthorSecurity Indicates whether a very strict (restrictive), strict, or lenient (permissive)

security policy is enforced for submitting jobs during New Day processing.
The Control-M security mechanism uses the Created By parameter and
the AuthorSecurity system parameter to ensure that only authorized users
can submit jobs during New Day processing. In all modes, the
administrator is authorized to change the author.
NOTE: If this parameter is modified, Control-M users who are offline
must log on to become synchronized with the new setting.
Valid values:
 1 (Permissive mode) - Editing the author is enabled. Users can retain
the original Author when running utilities or performing a Write to
Control-M/EM, or, alternatively, change the author to another user.
 2 (Restrictive mode) - Author is the user currently performing a Write
to Control-M/EM. However, the original author can be retained for
existing job processing definitions (whose associated tables are
locked).
 3 (Very restrictive mode) - The author is set to the user currently
performing a Write to Control-M/EM for all job processing definitions.
Default: 1

BIMCommLoopInterval Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 45

BIMThreadPoolIdleTime Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 30

BIMThreadPoolMaxSize Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 10

BIMThreadPoolMinSize Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 1

bulk_act_cond Bulk size in bulk operation for retrieve conditions.

NOTE: Do not change any of the four bulk_act_xxx parameters unless
requested to do so by BMC Software.
Valid values: 10 -10000
Default: 250

109
Control-M Administrator Guide

Parameter Description

bulk_act_grp Bulk size in bulk operation for retrieve tables.

Valid values: 10- 10000
Default: 100

bulk_act_job Bulk size in bulk operation for retrieve jobs.

Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 250

bulk_act_res Bulk size in bulk operation for retrieving control or quantitative resources.
Valid values: 10 - 10000
Default: 50

bulk_bim_svc Determines the bulk size in bulk operation to retrieve jobs in BIM services
Default: 100
NOTE:: Do not change this parameter unless instructed to do so by BMC
Software Customer Support.

CloseOldDownloads NOTE:: Do not change this parameter unless instructed to do so by BMC

Software Customer Support.
Valid alues: 0 or 1
Default: 1

ConcurrentCollections The number of collections that can be read in parallel.

If set to 1, collections are read serially. Increasing this number improves
response time but may use more CPU resources.
NOTE: If you increase the value of this parameter, monitor the system
for several days, especially during periods of heavy usage, to ensure that
performance is not degraded. You may want to increase the value of this
parameter gradually (for example, by one or two at a time), to avoid CPU
bottlenecks.
After modifying this parameter, stop and restart all GUI Server
components for the change to take effect.
Valid values: 1-10
Default: 4

110
Control-M Administrator Guide

Parameter Description

ControlResourceLoadLimit The maximum number of control resources that can be loaded into
memory from the Control-M/EM database at the same time. This
parameter can help control memory usage. However, if this parameter is
set to -1, there is no maximum limit.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support
Default: -1

DelayBeforePinning The number of seconds before the GUI Server begins processing the
pin_collection.ini file.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 10

EMAPIActiveJobsLoadLimit The number of jobs in the Active Jobs database that are checked by the
GUI Server when processing the request_act_retrieve_jobs request, and
included in the request response.
Valid values: from 10 to -1 (unlimited)
Default: 1000

EMThreadPoolIdleTime Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 30

EMThreadPoolMaxSize Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 100

EMThreadPoolMinSize Valid values: Do not change this parameter unless instructed to do so by

BMC Software Customer Support.
Default: 5

111
Control-M Administrator Guide

Parameter Description

ExcludedJobFields Identifies fields (database columns) that should not be downloaded from
the database when retrieving collections, thereby decreasing memory load
and improving response time.
Any or all of the following fields can be excluded. Use spaces, commas,
colons, or semicolons to separate multiple entries.
Warning: BMC Software recommends that you not exclude data (change
the value of this parameter to 1) without first consulting BMC Software
Customer Support. If you do change the value to 1, be sure to modify job
processing definitions do that they do no contain excluded data.
NOTE: Control-M Workload Authorization users cannot perform a find or
query on excluded fields. You can modify fields to exclude by adding or
removing fields in this parameter. After modifying this parameter, stop
and restart all GUI Server components for the change to take effect.
Valid values:
 Database Column - Description
 MAX_WAIT- Maximum Wait
 ODATE - Order date
 OWNER - Owner
 DESCRIPTION- Description
 CPU_ID - Host ID
Default: null (no fields are excluded)

ExcludeJobControlRes Determines whether control resources are (0) or are not (1) downloaded
from the database when retrieving collections. If unneeded control
resources are not downloaded, memory requirements are reduced and
response time is improved.
Warning: BMC Software recommends that you not exclude data (change
the value of this parameter to 1) without first consulting BMC Software
Customer Support. If you do change the value to 1, be sure to modify job
processing definitions do that they do no contain excluded data.
NOTE: Control-M users cannot perform a find or query on excluded
control resources. After modifying this parameter, stop and restart all GUI
Server components for the change to take effect.
Valid values:
 0 – Do not exclude control resources.
 1 – Exclude control resources.
Default: 0

112
Control-M Administrator Guide

Parameter Description

ExcludeJobQuantRes Determines whether quantitative resources are downloaded from the

database when retrieving collections. If unneeded quantitative resources
are not downloaded, memory requirements are reduced and response
time is improved.
Warning: BMC Software recommends that you not exclude data (change
the value of this parameter to 1) without first consulting BMC Software
Customer Support. If you do change the value to 1, be sure to modify job
processing definitions do that they do no contain excluded data.
NOTE: Control-M users cannot perform a find or query on excluded
quantitative resources. After modifying this parameter, stop and restart all
GUI Server components for the change to take effect.
Valid values:
 0 – Do not exclude quantitative resources.
 1 – Exclude quantitative resources.
Default: 0

FailCheckDBTimeOut Time, in seconds, until the GUI Server checks the communication status
of the database server. If communication is still down, communication is
considered to be disrupted and the action specified in
StopIfDBConnectionFail is implemented.
NOTE: This parameter is relevant only after the GUI Server determines
that communication with the database server is disrupted. After modifying
this parameter, stop and restart all GUI Server components for the
change to take effect.
Valid values: 1-60
Default: 5

LimitArchiveJobsInMem The maximum number of archive jobs in memory per GUI Server.
Valid values: Any number greater than 0.
Default: 40000

LimitPlaybackQueueSize Determines the queue size limit for history playback

Default: 60000

MaxObsoleteJobs NOTE: Do not change this parameter unless instructed to do so by BMC

Software Customer Support.
Valid values: Any number greater than 0.
Default: 100000

113
Control-M Administrator Guide

Parameter Description

MaxUserTimeoutSec Time, in seconds, that a Control-M/EM API client user token can be valid.
Afterwards, the GUI Server can invalidate the token.
NOTE: After modifying this parameter, stop and restart all GUI Server
components for the change to take effect.
Valid values: Any number greater than 0.
Default: 10800

MFTDefaultSearchDayRange Determines the number of days back you can search for file transfers in
MFT.
Default: 2

MFTRequesterThreadPoolSiz Determines the number of threads that execute MFT requests.

e
Default: 2

MFTSearchLimit Determines the maximum number of File Transfer search results from an
an MFT search.
Default: 1000

MFTSearchMode Determines whether the MFT search is collected from memory (CACHE) or
from the database (SQL).
Valid values:
 CACHE
 SQL
Default: CACHE

NumberOfMyWorldJobs Total number of job hosts that are displayed when Local View is used.
NOTE:After modifying this parameter, stop and restart all GUI Server
components for the change to take effect.
Valid values: 2-30,000
Default: 100

OnPromtReqCheckInScript Defines a script that runs when a promotion request is checked in.

114
Control-M Administrator Guide

Parameter Description

OpenCollByScanAllJobsColl Determines whether jobs are read from the cache in the GUI Server or
from the database when you open a ViewPoint.
Valid values:
 0: Read from the database
 1: Read from the GUI Server cache
Default: 1

PinAllJobsCollection Determines whether the All Jobs collection is loaded and pinned when the
GUI Server starts up.
Valid values:
0 – The All Jobs collection is not loaded and pinned when the GUI Server
starts up.
1 – The All Jobs collection is loaded and pinned when the GUI Server
starts up.
Default: 1

PrereqConditionsLoadLimit The maximum number of prerequisite conditions that can be loaded into
memory from the Control-M/EM database at the same time. This
parameter helps control memory usage.
Valid values: Any number greater than 0.
Default: 15000

QuantResourceLoadLimit The maximum number of quantitative resources that can be loaded into
memory from the Control-M/EM database at the same time. This
parameter helps control memory usage.
Valid values: Any number greater than -1.
Default: -1 (no limit)

QueriedCollection Collection of jobs to include in the Network Neighborhood Collection.

Valid values:
 CURRENT – The collection of jobs in the ViewPoint from which the
user opened the Network Neighborhood.
 All Jobs – The collection includes all jobs, not only the jobs in the
current ViewPoint.
Default: CURRENT

115
Control-M Administrator Guide

Parameter Description

SecuredExcludedFields Determines if the GUI Server is in Secure mode. If the GUI Server is in
Secure mode, user requests to view or modify fields that are included in
the Security filter of a ViewPoint are rejected.
Warning: BMC Software recommends that you not exclude data (change
the value of this parameter to 1) without first consulting BMC Software
Customer Support.
Valid values:
 0 - The GUI Server is not in Secure mode; it prompts the user for
confirmation whether to continue processing the request.
 1 - The GUI Server is in Secure mode; it denies the request because
opening any ViewPoint might involve a security breach. The user
cannot open any ViewPoint until the Authorization Filter for the user is
changed by the system administrator so that it no longer contains
excluded fields.
If the GUI Server prompts for confirmation, carefully consider the
following factors before confirming the request:
 If a ViewPoint hierarchy definition contains an excluded field, the
ViewPoint groups the jobs as if they all have the same empty value
("") and the hierarchy is incorrect.
 If a Collection, Filter, or User Authorization filter contains criteria that
match excluded fields, a match is assumed for those filtering criteria,
yielding unwanted filtering results.
 If a User Authorization filter includes only jobs for which the user is
the owner, but Owner is an excluded field, then a match on Owner is
assumed for every job in the Active Jobs database. This could cause
every job in the Active Jobs database to be loaded (if there are no
other exclusion criteria).
Default: 0

SendRequestToScript Allows administrators to define a script that runs when a Control-M

Workload Change Manager request changes state.
EXAMPLE: An administrator wants to monitor submitted requests and
verify that a change ticket with the ticket ID that was
assigned to the request exists in Control-M Workload Change
Manager and is approved.
To activate an external application for a Control-M Workload Change
Manager request, see Activating an external application for a Control-M
Workload Change Manager request.
Valid values:Full path to the script
Default:Empty

116
Control-M Administrator Guide

Parameter Description

ServicesCacheRefreshInterv Determines the number of seconds to build another cache for the Services
al window
Default:15

SockRecrMaxAtmp Maximum number of times that the GUI Server can attempt to create a
socket.
NOTE: After modifying this parameter, stop and restart all GUI Server
components for the change to take effect.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: -1 (no limit)

SockRecrWtIntr Interval, in seconds between successive attempts to create a socket.

NOTE: After modifying this parameter, stop and restart all GUI Server
components for the change to take effect.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 10

StandartCheckDBTimeOut Determines the number of seconds to wait between intervals to confirm

that communication with the database server is still alive

StopIFDBConnectionFail Action to take if communication between the GUI Server and the database
server is disrupted.
NOTE: After modifying this parameter, stop and restart all GUI Server
components for the change to take effect.
Valid values:
 0 – The GUI Server is shut down until communication with the
database server is restored. When communication is restored, the
Configuration Agent restarts the GUI Server.
 1 – The GUI Server remains operational. However, its status is
Warning (as displayed in the CCM) and it may not function.
Default: 0

TopologyCacheRefreshInterv Determines the number of seconds to wait for the GUI Server to send
al requests to the CMS for the topology (Control-M/Server and Agents)
Default: 15

117
Control-M Administrator Guide

Parameter Description

UseQueriedCollectionForFind Determines the collection of jobs to be searched when performing a find

from within a ViewPoint screen.
Valid values:
 1 (Yes) - When performing a find from within a ViewPoint, limit the
search to jobs that satisfy the QueriedCollection system parameter.
 0 (No) - Perform the search using all jobs.
Default: 1

ViewpointPolicy Determines which SMART Folders are passed to the ViewPoint.

Valid values:
 SELECT_JOBS - Filtering criteria are applied only to the jobs. Only
jobs satisfying the filtering criteria, and only SMART Folders
containing at least one such job, are passed and displayed. (No empty
folders are passed.)
 SELECT_JOBS_AND_SG - Filtering criteria are applied both to jobs and
SMART Folders. In addition to passing the same jobs and SMART
Folders that are passed for the SELECT_JOBS value, the Server also
passes any SMART Folders that match the filtering criteria (and pass
the security criteria) even if they are empty.
Default: SELECT_JOBS

ViewpointPullQueueWeightL Determines the number of Viewpoints that can be open simultaneously in

imit Self Service web application
Default: 30000

ViewPointTimeoutForBIM The number of milliseconds within which the Control-M/EM GUI Server
should receive a reply from the BMC Batch Impact Manager after sending
a request.
Valid values: Any whole number greater than 0 .
Default: 600000

UpdatesQueueLimit Default size of the updates queue for a ViewPoint.

Valid values: Any number greater than 0 and smaller than
UpdatesQueueMaxLimit.
Default: 5000

UpdatesQueueMaxLimit The maximum possible size of the updates queue for a ViewPoint.
Valid values: Any number greater than 0.
Default:59000

118
Control-M Administrator Guide

Parameter Description

AlertsMapRefreshInterval Frequency, in seconds, at which the Global Alerts updates its database
about which Alerts were deleted and why. The update occurs only when
both the specified time has passed and one or more alerts have been
deleted.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 60

GatewayOutgoingQueueSize Maximum number of bytes buffered in the GUI server waiting to be sent
to Control-M/Server. For example, as a result of a Save JCL request.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 25000000

RemedyCloseTicketMode Indicates in which mode a Remedy ticket is closed, and what effect that
has on the alert status.
Valid values:
 HANDLE_ON_CLOSE - The alert status is updated to Handled
automatically when the ticket is closed.
 CLOSE_ON_HANDLE -When the alert status is Handled, the ticket
is automatically closed.
 BIDIRECTION_CLOSE_HANDLE - Either an alert becoming
Handled closes a ticket, or closing a ticket causes the alert status to
be Handled.
 SEPERATE_CLOSE_HANDLE - Close and Handle are two separate
actions that do not affect each other.
Default: HANDLE_ON_CLOSE

SockRecrWtIntr Interval, in seconds, between successive attempts to create a socket.

Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support.
Default: 10

119
Control-M Administrator Guide

CMS parameters
The following table lists the CMS parameters.

Parameter Description

AdminRequestTimeout NOTE: Do not change this parameter unless instructed to do so by

BMC Software Customer Support. If you are instructed to change this
parameter, you must restart the CMS for the change to take effect.
Valid values: Any whole number that is equal to or greater than 20.

CmsCommMode The mode with which the Configuration Management Server connects
to the Control-M/Server Configuration Agent.
Valid values:
 TCP - A non-secure connection is established.
 SSL - Connect using SSL only.
 Auto - The system automatically detects the type of connection
that is established.
Default: TCP

CmsCtmNGRefreshInterval Sets the refresh interval in seconds for collecting host group data.
Valid values: 0-10000 (0 -host group data is not collected)
Default: 900

CmsCtmRefreshInterval The Configuration Management Server (CMS) refreshes the status and
topology of the Control-M/Servers on a regular basis. This system
parameter governs the length of time in seconds between each refresh
episode.
Valid values: Any whole number that is equal to or greater than 30.
Default: 60

CmsEmRefreshInterval The CMS refreshes its internal image of Control-M/EM component

status on a regular basis. This system parameter governs the length of
time in seconds between each refresh episode.
Valid values: Any whole number that is equal to or greater than 30.
Default: 30

CmsGateAdditionalParams Valid values: Do not change this parameter unless instructed to do so

by BMC Software Customer Support.

CmsHostSpecRetrieverInterval Determines the number of times in 24 hours to send internal requests

to obtain computer specification (used for MANAGED Servers report).
Default: 60

120
Control-M Administrator Guide

Parameter Description

CmsMaxPluggableOutput Determines the maximum size in KB of stdout and stderr that is read
from the pluggable request
Default: 100

CmsXAlertsHost Specify the host or IP address on which the CMS is forced to receive
XAlerts.
Valid values: Any valid host name or IP address.
NOTE: If no value is entered for this parameter, the host name on
which the CMS is installed is used.
Default: null

CmsXAlertsPort Specify the port through which the XAlerts are received.
Valid values: Any valid port.
Default: 0
NOTE: The default value 0 means that any random port is used.

DBCheckSpaceIntervalSeconds Determines the number of seconds to wait to before checking the

database space usage
Default: 36000

DBCheckSpaceWarningPct Determines the maximum percentage of allowed database space use.

NOTE: An Xalert is issued if the threshold is exceeded.
Default: 90

DiagOutputTimeout Determines the number of seconds to wait for a response from

Control-M/Agent before a timeout occurs for the Get_diag_output
request
Default: 30

HAProgressDataRetentionInterv Determines the number of seconds that the failover or fallback

al progress information is available after the process completes.
Default: 604800

121
Control-M Administrator Guide

Parameter Description

HandledXAlertHandling Determines whether handled alerts are sent as an SNMP trap or to a

script.
Valid values:
 1 - Handled alerts are sent as an SNMP trap and to a script.
 0 - Handled alerts are not sent as an SNMP trap and to a script.
NOTE: This parameter is only valid when the XAlertsSendSnmp system
parameter has a value of 1, 2, or 3.
Default: 0

IdenticalXAlertTimeDelta Determines the interval, in minutes, within which an alert is defined as

identical to a previous matching alert.
Valid values: Any whole number that is equal to or greater than 0.
Default: 30 minutes

IdenticalXAlertCompareDesc Determines whether the MESSAGE field is used to compare identical

alerts.
Valid values:
 1 - Compare the MESSAGE field
 0 - Do not compare the MESSAGE field
Default: 0

IdenticalXAlertHandling Determines whether identical alerts are sent as an SNMP trap or to a

script.
Valid values:
 1 - Identical alerts are sent as an SNMP trap and to a script
 0 - Identical alerts are not sent as an SNMP trap and to a script
NOTE: This parameter is only valid when the XAlertsSendSnmp system
parameter has a value of 1, 2, or 3.
Default: 0

ManageSSL_CertExpirDays Determines the expiration duration of a certificate in the Manage SSL

Generate Certificate Wizard.
Valid values: Any whole number that is equal to or greater than 1.
Default: 7300

122
Control-M Administrator Guide

Parameter Description

ManageSSL_CACertExpirDays Determines the expiration duration of a site CA in the Manage SSL

Generate Certificate Wizard.
Valid values: Any whole number that is equal to or greater than 2.
Default: 7300

ManageSSL_CertKeyLengthBits Determines the number of bits of the certificate key in the Manage SSL
Generate Certificate Wizard.
Valid values: 1024, 2048, 3072, 4096
Default: 1024

MaxXAlerts2Send2Client Valid values: Do not change this parameter unless instructed to do so

by BMC Software Customer Support.
Determines the maximum number of exception alerts sent from the
CMS to the Exception Alerts window.
Default: 2000

RemoteCmdTimeout The amount of time, in seconds, that the CMS will wait for a reply to a
remote request sent through the Configuration Management Server to
Control-M/Server, Control-M/Agent, and Application Plug-Ins, before
timing out.
An example of such a request is a ping agent request.
Valid values: Any whole number that is equal to or greater than 30.
Default: 300

RunInfoStatsPurgeDays The number of days to retain deleted statistics, after which the
statistics will be deleted when automatic purge is performed.
Valid values: Any whole number that is equal to or greater than 1.
Default: 100 days

RunInfoStatsPurgeInterval Interval, in minutes, between activations of automatic purging of

periodic statistics by the CMS.
NOTE: To disable automatic purging, set the value to 0.
Valid values: Any whole number that is equal to or greater than 1.
Default: 30

123
Control-M Administrator Guide

Parameter Description

UsageAlertsState Determines whether Usage Alerts are enabled.

Valid values:
 0 - Disabled
 1 - Enabled
Default: 0

UsageCollectionDisabled Determines whether to automatically activate the usage collection tool.

Valid values:
 0 - Enabled
 1 - Disabled
Default: 0

VMCleanupIntervalMinutes Interval, in minutes, between activations of automatic job history

cleanup by the CMS.
NOTE: To disable automatic cleanup, set the value to 0.
Valid values: Any whole number that is equal to or greater than 30.
Default: 30

VMMaxDaysRetainCurJobsHistor The number of days after which the history of the current jobs should
y be deleted automatically.
NOTE: A job version is deleted only when all of the following are true:
 The version exceeds VMVersionsNumberToKeep.
 The version exceeds VMMaxDaysRetainCurJobsHistory.
 Automatic cleanup has run, as determined by
VMCleanupIntervalMinutes.
Valid values: Any whole number that is equal to or greater than 0.
Default: 0

VMNumDaysRetainDeletedJobs The number of days to retain deleted jobs and their history. Deleted
tables will also be deleted according to this value.
Valid values: Any whole number that is equal to or greater than 1.
Default: 180

124
Control-M Administrator Guide

Parameter Description

XAlertsSendSnmp Determines whether an alert will be sent as an SNMP trap, to a script,

both, or neither.
Valid values:
 0 - Not active
 1 - Sent as an SNMP trap
 2 - Sent to a script
 3 Sent as an SNMP trap and to a script
Default: 0

XAlertsMaxAge Determines, in days, how long XAlerts are saved before they are
deleted by the Configuration Management Server.
Valid values: Any whole number that is equal to or greater than 0.
Default: 180 days

XAlertsMaxHandled The maximum number of handled XAlerts that are displayed in the
Exception Alerts window.
Valid values: Any whole number that is equal to or greater than 0.
Default: 100

XAlertsSnmpHosts Specifies the host names of the machines to which you want to send
the SNMP trap.
Valid values: Any host name or IP address. Separate multiple hosts
with a semicolon. To add a specific port for each host, enter the host
name followed by a colon and the port number.
EXAMPLE:XAlertsmachine:7000;SNMPmachine;Scriptsmachine:7001
Default: null

XAlertsSend2Script Specify the full path and file name of the script to be sent. This
parameter is used only when the XAlertsSendSnmp system parameter
is set to either 2 or 3.
Valid values: Any full path and file name.
Default: null

XAlertsDisableMsgIDs Specify the message IDs for which no XAlerts are sent. By default, no
message IDs are listed. Use a comma to separate multiple message
IDs.
Default: none

125
Control-M Administrator Guide

Parameter Description

XAlertsMinSeverityFilter Specify the severity level filter. XAlerts with a value equal to or greater
than the specified severity level are sent to the Exception Alerts
window.
Valid Values:
 Warning
 Error
 Severe
Default: Warning

Control-M/EM parameters in the Defaults.rsc file

The following table lists the parameters located in the Defaults.rsc file.

Parameter Description

bulk_batch_size Indicates how many job and resource details the gateway should load into
memory at a time before saving the entities in the Control-M/EM database
when performing a download from Control-M. A larger number causes the
download to occur faster and more efficiently, at the expense of virtual
memory.
Valid values: Any whole number that is equal to or greater than 10.
Default: 100

continue_not_respondin Indicates how the new gateway handles multiple gateway instances for the
g same Control-M installation if all attempts to stop and kill the original gateway
are unsuccessful.
Valid values:
 Y- Both gateway occurrences are allowed to run concurrently. This is not
recommended.
 N- The original gateway continues in its "hung" state. The new gateway
stops running.
Default: N

126
Control-M Administrator Guide

Parameter Description

dal_rel_cache_size Valid values:Do not change this parameter unless instructed to do so BMC
Software Technical Support.

dal_select_min_bulksize These parameters indicate the bulk size being used by the database access
layer during bulk insert and choose SQL operation. Larger numbers cause the
dal_select_max_bulksiz
insert and choose SQL operations to occur faster and more efficiently, at the
e
expense of virtual memory.
dal_insert_min_bulksize
Valid values: Any whole number that is equal to or greater than 10.
dal_insert_max_bulksize
Defaults:
 dal_select_min_bulksize: 10
 dal_select_max_bulksize:
 Oracle: 50
 MSSQL: 20
 dal_insert_min_bulksize: 10
 dal_insert_max_bulksize:
 Oracle: 100
 MSSQL: 10

em_connect_method Indicates in which mode the gateway opens communication connections.

Valid values:
 1 - The gateway establishes connections in blocking mode.
 2 - The gateway establishes connections in non-blocking mode.

gtw_send_ctl_timeout Timeout period, in seconds, for determining if the original gateway is

responsive (up).
Valid values: Any whole number that is equal to or greater than 20.
Default: 45

127
Control-M Administrator Guide

Parameter Description

kill_not_responding Indicates whether a new gateway stops or kills existing gateway instances for
the same Control-M installation.
Valid values:
 Y - The new gateway tries to kill the original gateway and, if successful,
continues to run. If the original gateway cannot be killed, the new gateway
handles the original gateway according to the continue_not_responding
parameter.
 N - The new gateway tries to stop the original gateway (using the ctl
utility) and, if successful, continues to run. If the original gateway is not
stopped after 3 attempts, the new gateway handles the original gateway
according to the continue_not_responding parameter.
Default: N

nonBlockTimeout If a gateway is in non-block mode and part of a message is not received during
the number of seconds specified in this parameter, the gateway assumes
communication is down.
Valid values: Do not change this parameter unless instructed to do so by
BMC Software Customer Support
Default: 40.
This parameter is relevant only if the useNonBlock parameter is set to Y.

useNonBlock Indicates whether the gateway operates in blocking mode or non-blocking

mode. This mode determines whether the gateway receives entire messages or
parts of messages.
Valid values:
 N - The gateway waits and receives for the entire message to arrive in
blocking mode, regardless of length of time.
 Y - The gateway receives parts of messages (non-blocking mode).
Communication is assumed to be down if part of a message is not received
within the time interval specified in the nonBlockTimeout field.
Default: N

Batch Impact Manager parameters

System variables influence the behavior of Batch Impact Manager components and features. The
following table describes the function of each Batch Impact Manager-related system parameter and lists
its default, if one exists.

128
Control-M Administrator Guide

Batch Impact Manager administrators can change the value of most of these system parameters. If,
however, a system parameter is to be modified only upon instruction of Customer Support, this is noted in
the description of that system parameter.
NOTE: After modifying any of these system parameters, you must stop and restart the Batch Impact
Manager Server.

Parameter Description

AddAllOrphanConditions Enables you to add external or orphan conditions.

Manual conditions are specified as In Conditions for jobs but do not exist
at the time Batch Impact Manager estimates the completion time of the
services and jobs. This may be because:
 The job relies on a condition from a previous day.
 The job relies on a condition that has to be manually added.
Valid values:
 0- Do not add conditions.
 1- At conditions at New Day.
 2- Add conditions at the average start time of the first job waiting
for the condition.
Default: 2

AddVirtualOrphanCondition Ignores delete conditions if needed by other jobs and there are no other
s jobs that add them.
Valid values:
 0: All delete conditions are performed
 1: Delete conditions are not performed if there are no jobs in the
same Control-M
 2: Delete conditions are not performed if there are no jobs in all
Control-M/Servers
 4: Almost all delete conditions are ignored
Default: 0

AlertConsolidationMode Determines whether the BMC Batch Impact Manager consolidates email
alerts, BMC Remedy ITSM incidents, and shout messages.
Valid values:
 0- Disables consolidation.
 1- Alerts are consolidated in one line with some exceptions regarding

129
Control-M Administrator Guide

Parameter Description
alerts recorded in separated lines and or with added spaces.
 2- Alerts are consolidated with a space between the message text
for each service.
Default: 1

AllowReportViewing Allows service report viewing from web for users that are not
administrators.
Valid values: The number 1
Default: 0

BackupGUIServers GUI Servers to use in case there is a problem with the primary GUI
Server (as indicated in the Control-M Configuration Manager). The value
of this parameter can be one GUI Server or list of GUI Servers separated
by commas ( , ).
Valid values: String expression.

BIMUserName The user name that Batch Impact Manager uses when connecting to
Control-M/EM.
Valid values: bimuser
Default: bimuser
NOTE: Before changing this value, ensure that the new user name value
already exists in Control-M/EM. (If it does not exist, create it before
changing the value.) The Batch Impact Manager user name is a hidden
user, so if a new user name is indicated here it will also become hidden.

ConditionDaysToLoad Defines the number of days of active conditions Batch Impact Manager
loads for service calculations.
Valid values: The number of days equal to or greater than 1 .
Default: 7 days

ConnectToGsrRetryDelay The delay, in seconds, Batch Impact Manager waits before reconnecting
to the Control-M/EM GUI Server, if the connection has failed.
Valid values: Any whole number equal to or greater than 1.
Default: 30

DateFormat Format in which dates are displayed in BIM alert messages.

Valid values: DD/MM and MM/DD.
Default: DD/MM

130
Control-M Administrator Guide

Parameter Description

DefaultAverageTime Average run time for jobs with no statistics. In the format HH:MM. This
value is often used if no statistics are available.
Valid values: Time in the format of HH:MM.
Default: 00:05

DetectProblemsInterval Interval at which Batch Impact Manager checks for problems in the
service.
Valid values: Time in the format of HH:MM:SS.
Default: 00:01:00

DiscardOrphanConditions Ignores missing conditions if it relates to an OR condition.

Valid values:
 0: Add all conditions
 1: Ignore OR conditions if missing.
Default: 1

EmailSender Valid values: E-mail address from which alerts are being sent.
Default: bim@bmc.com

EmailServer This value must be set after installation.

Valid values: Name of the e-mail server for alert notifications.
Default: mail

ExecuteConfirmedJobs Enables you to execute jobs that are waiting confirmation.

Valid values:
 0: Do not execute jobs
 1: Execute at New Day
 2: Execute at the job’s average start time
Default: 0

FailoverMaxRetry Maximum number of times the Batch Impact Manager Server should
reconnect to the Control-M/EM GUI Server, if this connection repeatedly
fails. This parameter is reset by the FailoverMinUptime parameter.
Valid values: Any whole number equal to or greater than 1.
Default: 10

131
Control-M Administrator Guide

Parameter Description

FailoverMinUptime The amount of time that the Batch Impact Manager Server must be
connected to the Control M/EM GUI Server, before the counter used by
the FailoverMaxRetry parameter is reset to zero. For example, if this
value is 30 minutes and the connection has been maintained for more
than 30 minutes, the counter is reset.
Valid values: Time in the format of HH:MM:SS
Default: 00:30:00

JobNameMode The field is used to identify a job in Control-M. Batch Impact Manager
uses this parameter when processing the PROBLEMATIC-JOBS auto edit
variable.
Valid Values:
 1. JOBNAME/MEMNAME- Search according to the name of the job or
the member.
 2. JOBNAME- Search according to the name of the job.
 3. MEMNAME- Search according to the name of the member.
Default: JOBNAME/MEMNAME

MailCorrectionMessage Defines the correction message of a problematic service that has

become OK.
Valid values: String expression.

MaxNumDetectThreads Maximum number of threads for recalculating the status of the service.
Valid values: Any whole number equal to or greater than 1.
Default: 2

MaxNumOfVpsWithScenario Determines the maximum number of Analysis ViewPoints with What-If

scenarios that can be opened simultaneously.
Default: 3

MaxSimulationDays Number of days to simulate the running of the services to calculate

estimated end times. Each additional day takes more CPU time during
the calculation process.
Valid values: Any whole number equal to or greater than 1.
Default: 2

132
Control-M Administrator Guide

Parameter Description

MinGapToJobParents Determines the minimum interval (in seconds) between jobs reported as
the gap.
Default: 60

NewJobsInterval Interval at which Batch Impact Manager will check to see if new jobs
have been added to the critical service.
Valid values: Time in the format HH:MM:SS.
Default: 00:01:00

NumberOfReportDays NOTE: Determines the number of days to keep report data in the
database for generating reports about services.If you update this
parameter, you need to update this same parameter with type general.
Valid values: The number of days equal to or greater than 1
Default: 90

PrevDaysCyclicOnly Determines if the parameter PrevDaysOrphanConditions is for Cyclic

jobs or for all jobs.
Valid Values:
 0: All jobs are affected by PrevDaysOrphanConditions
 1: Only cyclic jobs are affected by PrevDaysOrphanConditions
Default: 0

PrevDaysOrphanConditions Determines the number of previous ODATs not to raise Orphan

conditions
Valid Values:
 0: All jobs from all ODATs are submitted in the Simulation by BIM.
 1: All Orphan conditions, that the jobs waiting for this condition are
of an ODAT that is 1 day or more prior to the CTM Server ODATwill
not be raised, so the jobs waiting for this condition, will not run.
Default: 0

SendMailCorrectionMessage Determines whether to send the correction message or not.

Valid values:
 0: Do not send
 1: Send
Default: 1 (send)

133
Control-M Administrator Guide

Parameter Description

SupportWorkLoadResource Determines if load balancing of quantitative resources is supported.

s
Valid values:
 0: Not supported
 1: Supported
Default: 1

UseDoCondition Add conditions created by On Do Actions.

Valid values:
 0: Do not add conditions
 1: Add only added conditions
 2: Add added and deleted conditions
Default: 1

Control-M Forecast parameters

System variables influence the behavior of Control-M/Forecast components and features. The table
describes the function of each Control-M/Forecast -related system parameter and lists its default, if one
exists.
Control-M/Forecast administrators can change the value of most of these system parameters. If, however,
a system parameter is to be modified only upon instruction of Customer Support, this is noted in the
description of that system parameter.

134
Control-M Administrator Guide

NOTE: After modifying any of these system parameters, you must stop and restart the Forecast server.

System parameter Description

AddAllOrphanConditions Enables you to add external or orphan conditions.

Manual conditions are conditions that are specified as in conditions for
jobs but will not exist at the time Control-M/Forecast generates its
forecast. This may be because:
 The job relies on a condition from a previous day. (Forecasts are
only generated for a specific day.)
 The job relies on a condition that has to be manually added or
removed.
Valid values:
 0: Do not add conditions
 1: Add conditions at New Day.
 2: Conditions are added at the average start time of the first job
waiting for the condition.
Default: 2

AddVirtualOrphanConditions Ignores delete conditions if needed by other jobs and there are no
other jobs that add them.
Valid values:
 0: All delete conditions are performed
 1: Delete conditions are not performed if there are no jobs in the
same Control-M
 2: Delete conditions are not performed if there are no jobs in all
Control-M/Servers
 4: Almost all delete conditions are ignored
Default: 0

AllowQueryFieldValues Determines whether the drop-down lists of available values are

displayed for fields in the What-If event definition dialog boxes.
Valid values:
 0 - drop-down lists are not displayed
 1 - drop-down lists are displayed
Default: 1

135
Control-M Administrator Guide

System parameter Description

DiscardOrphanConditions Ignores missing conditions if it relates to an OR condition.

Valid values:
 0: Add all conditions
 1: Ignore OR conditions if missing.
Default: 1

DisplayControlMTimeStartDay Determines the Control-M/Server start of day time in the

Control-M/Forecast domain. This parameter is relevant for all jobs that
do not have From time defined and are scheduled to run when they
are ordered.
Valid values:
 ctm_new_day
 midnight (00:00)
Default: ctm_new_day
EXAMPLE: This parameter is set to ctm_new_day and the new day is
at 07:00 and the time is 23:00.There is a job that needs to
run from 06:00 to 06:30. In Forecast, it shows that it will
run today at 06:00 (because it's before the new day).
If the system parameter set to midnight then it will run tomorrow
(+1)06:00 because it's after midnight.

ExecuteConfirmedJobs Enables you to execute jobs that are waiting confirmation.

Valid values:
 0: Do not execute jobs
 1: Execute at New Day
 2: Execute at the job’s average start time
Default: 0

IgnoreDeviationSampleCount Defines how many exceptional historical samples should be ignored

when calculating the average runtime for reporting purposes. Default:
2

MaxForecastJobsInMem Determines the maximum number of jobs that can be simulated by the
Forecast Server in one request.
Valid values: 1 or higher.
Default: 20,000
NOTE: This parameter affects the Forecast domain in the Control-M
client and requests submitted via the Forecast utility.

136
Control-M Administrator Guide

System parameter Description

MaxForecastRunningRequests Maximum number of Forecast requests that can run simultaneously.

Valid values: The number of forecasts requested equal to or greater
than 1.
Default: 5

max_futureplan_cb_seq_size Sets the minimum chunk size for jobs when generating the forecast.
Valid values: The number of jobs equal to or greater than 1.
Default: 1000

MaxSimulationDays Number of days to simulate the running of the services to calculate

estimated end times. Each additional day takes more CPU time during
the calculation process.
Valid values: The number of days equal to or greater than 1.
Default: 2

ScenarioMaxSize Maximum size (in KB) of the XML files that hold forecast What-If
scenarios.
Valid values: The number of KB greater than 1.
Default: 64

SimulatorEngineStep Interval, in seconds, the simulation advances its calculation of the

estimated end time.
Valid values:
 1 - Improves accuracy
 10 - Default
 60 - Improves performance

SockRecrMaxAtmp Valid values: Maximum number of times that the Configuration Agent
can attempt to create a socket.
Default: -1 (no limit)

SockRecrWtIntr Interval, in seconds between successive attempts to create a socket.

Valid values: Any whole number greater than 0.
Default: 10

137
Control-M Administrator Guide

System parameter Description

SupportWorkLoadResources Determines if load balancing of quantitative resources is supported.

Valid values:
 0: Not supported
 1: Supported
Default: 1

UseDoCondition Add conditions created by On Do Actions.

Valid values:
 0: Do not add conditions
 1: Add only added conditions
 2: Add added and deleted conditions
Default: 1

upd_progress_interval_sec If Control-M/Forecast should send updates when loading a forecast.

Valid values:
 0 - No
 1 - Yes
Default: 1

UserDailyCmdRegexp Regular expression that identifies Command-type jobs that use the
ctmudly user daily job to order tables. If the command specified in the
Command field in a job editing form matches the expression,
Control-M/Forecast assumes that the job uses ctmudly.
Valid values: <string expression>
Default: ^.*ctmudly[^ ]*
NOTE: The regular expression, ^.*ctmudly[^ ]*, identifies jobs that
call ctmudly, regardless of the specified path or file extension.

UserDailyFileNameRegexp Regular expression that identifies Job-type jobs that use a particular
user daily job (usually ctmudly) to order tables. If the name specified
in the File Name field in a job editing form matches the expression,
Control-M/Forecast assumes that the job uses the user daily.
Valid values: <string expression>
Default: ^.*ctmudly.*
NOTE: If you use this system parameter, you must also use the
UserDailyParamNO system parameter so that Control-M/Forecast can
access the name of the user daily.

138
Control-M Administrator Guide

System parameter Description

UserDailyParamNO Numeric suffix of the AutoEdit variable, %%PARAMn, which contains

the name of the user daily. For example, if this system parameter is set
to 2, Control-M/Forecast reads the name of the user daily from
%%PARAM2.
Valid values: Any whole number equal to or greater than 1.
Default: 1

Control-M Workload Archiving parameters

The following table describes the Control-M Workload Archiving parameters.

Parameter Description

ArchiveLastRead Determines the last time the Workload Archiving Server read
data from Control-M/EM.

ArchiveRetentionPeriod Determines the number of days to keep Archive data on the

Workload Archiving Server before it is removed.
NOTE: If the value of today's date is bigger than value of
ArchiveLastRead and the number defined for this
parameter, then jobs are not archived and an Xalert is sent.
Default: 30

ArchiveUserName Defines the name of the Archive user that connects from the
Workload Archiving Server to Control-M/EM.
Default: arcuser

ArchiveSearchRequestJobsLimit Sets the maximum number of jobs to return in response to an

archive search.
Default: 10000
Valid values: 1–10000

Changing the Gateway user

This procedure describes how to change the Gateway user from the default CTMSYNC. This user is used
to synchronize scheduling definitions between Control-M/EM and Control-M for z/OS or Control-M/Server.

139
Control-M Administrator Guide

 To change the Gateway user:

1. From the Components Tree pane, select the Control-M/EM component and from the Home tab,
in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click Advanced.

3. Click .
The Control-M/EM - New System Parameter window appears.
4. Do the following:
a. In the Type field, type gtw.
b. In the Name field, type CTMSyncUser.
c. In the Value field, type the user that you want to use to override CTMSyncUser.
d. In the Component area, from the Type drop-down list, select Gateway.
e. In the Name field, type the user that you want to use to override CTMSyncUser.
f. If you want to apply this parameter to specific Control-M/Servers, in the Host field, type the
name(s) of the Control-M/Server(s).
g. Click Save.
5. Recycle the Gateway, as described in Recycling a component (on page 42).

Mapping the Control-M Help to the Control-M Web Server

This procedure describes how to map the location of the Control-M Help from documents.bmc.com to the
Control-M Web Server. This allows users to access the Control-M Help within your organization without
providing access to the Internet.

 To map the Control-M Help to the Control-M Web Server:

1. Select a Control-M/EM component,and then click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click Advanced.
3. In the Name column, type ForceWebServerOLH.
4. Double-click the parameter and in the Value field, type 1.
5. Click Save.
The Control-M Help is now accessed from the Control-M Web Server.

Enabling Control-D/WebAccess Server output in Control-M Web

This procedure describes how to enable Control-D/WebAccess Server output in Control-M Web, which
allows you to view Control-D/WebAccess reports from the Monitoring domain in Control-M Web.
NOTE: Relevant for Control-M for z/OS only.

140
Control-M Administrator Guide

Before you begin

Ensure that you do the following:
 Compile the IOAX016E user exit and create the member EMREQUSR in the IOA PARM library.
NOTE: Comments in the source of the User exit IOAX016E contain a description of the member’s
EMREQUSR structure.
For more information, see Exits and Running the ICE Automatic Exit Installation Tool in the
INCONTROL for z/OS Administrator Guide.
 In Control-D/WebAccess Server, add the Verify user and user token parameters, as described in
Automatic Login in Control-D/Desktop for Control-D/WebAccess Server Administrator Guide.
 To Enable Control-D/WebAccess Server output in Control-M Web:
 In the CCM, add the following Control-M/EM system parameters:
• ControlDWaURL
• ControlDRepository
For more information, about the parameters, see Control-M Self Service parameters (on page 98).
You are now able to view Control-D/WebAccess Server output in Control-M Web. For more
information, see Viewing job output in the Control-M Web documentation.

Control-M/Server parameters
In the CCM, you can change the default component system parameter values of Control-M/Server system
parameters without having to access each individual computer.
Before a modified parameter value can take effect, the component that uses the value needs to be
refreshed.
To define Control-M/Server parameters, see Defining Control-M/Server system parameters (on page 141).

Defining Control-M/Server system parameters

This procedure describes how to define Control-M/Server system parameters in the CCM.
 To define Control-M/Server system parameters:
1. From the Components Tree pane, select the Control-M/Server component and from the Home
tab, in the Definitions group, click System Parameters.
The Control-M/Server - System Parameters dialog box appears.
2. From the Control-M/Server drop-down list, select the computer where the Control-M/Server is
installed.
3. From the system parameters table, filter for the required parameter from one of the following column
headings:
• Category
• Name

141
Control-M Administrator Guide

• Description
• Value
• Default Value
• Refresh Type
4. Double-click the required parameter.
The Update System Parameter dialog box appears.
5. In the Value field, change the value of the parameter, as required, and then click Save.
6. Click Activate Changes.
The Control-M/Server system parameter is defined.

Control-M/Server general parameters

The following table lists the Control-M/Server system parameters. These parameters are assigned default
values during installation. For some of the parameters, you can use the ctmsys utility to change the
parameter value.

Parameter Name Description

ARCHIVING_CHECK_IN Determines the number of days to wait before sending a warning that
TERVAL_DAYS Workload Archiving is not enabled on a PostgreSQL database.
Valid values: 0 (unlimited) -365.
Default: 7

Executable Path Location where Control-M/Server expects to find all of its executable
programs (for example, /usr/controlm/ctm_server/exe_Solaris).

Maximum Number of Determines the maximum number of worker threads that the tracker can
Tracker Worker Threads create.
(TRACKER_MAX_WORK
Valid values:
ERS_NUM)
Minimum: TRACKER_WORKERS_NUM
Maximum: 100
Default: 20
Refresh Type: Recycle (by shutting down the Control-M/Server and then
re-starting it)

NO_BACKUP_WARNING Determines the number of days before a warning is sent for not activating a
_DAYS HOT backup on a PostgreSQL database.
Valid values: 0 (unlimited)–365
Default: 4

142
Control-M Administrator Guide

Parameter Name Description

Number of Tracker This parameter determines the number of worker threads available for the
Worker Threads tracker process at startup.
(TRACKER_WORKERS_
Valid values: 1–100
NUM)
Default: 5
Refresh Type: Recycle (by shutting down the Control-M/Server and then
re-starting it)

Secure Sockets Layer Handshake protocol for communications between Control-M/Server and
Control-M/EM, and between Control-M/Server and Control-M/Agent.
Valid Values:
 INACTIVE—Control-M/Server works in non-SSL mode. If
Control-M/Agent is in SSL mode, the server tries to switch that agent to
non-SSL mode.
 DISABLED—Control-M/Server works in non-SSL mode. If
Control-M/Agent is in SSL mode, the server does not try to switch that
agent to non-SSL mode.
 ENABLED—Control-M/Server works in SSL mode.
Default: Disabled
How / where to set: In the Control-M Main Menu, choose Parameter
Customization => System Parameters and Shout Destination
Tables => System Parameters => Next Page => Secure Sockets
Layer. The parameter that is updated is the
CTM_CONFIG_AGENT_SSL_ENBL parameter.
Refresh Type: manual

Start Day of the Week Day on which the work week starts at your site
(SWEEK)
NOTE: This parameter affects the Weekdays job processing parameter.
Valid Values: 0 (Saturday) through 6 (Friday)
Default: 2 (Monday)
How / where to set: Use the ctmsys utility to change the parameter value.
Refresh Type: Automatic

Statistics Whether job statistics should be written to the Control-M/Server database

Y tells Control-M to record job statistics.
N tells Control-M not to record job statistics.
Default: Y
How / where to set: Use the ctmsys utility to change the parameter value.
Refresh Type: Automatic

143
Control-M Administrator Guide

Parameter Name Description

EMAIL_CC Determines which email addresses receive notifications about events.

The e-mails are sent using the SMTP parameters, as described in SMTP
parameters (on page 174).

EMAIL_RECIPIENTS Determines which email addresses receive notifications about events.

The e-mails are sent using the SMTP parameters, as described in SMTP
parameters (on page 174).

Deployment parameters
The following table describes deployment parameters.

Parameter Description

AUTODEPLOY_DEPLOYING_TIMEOU Determines the number of seconds for the upgrade or

T downgrade to complete before a timeout.
Default: 3600

AD_FETCH_LOG_TIMEOUT Determines the number of seconds to wait to retrieve

output information from the Control-M/Agent to display
in the Control-M/Agent upgrade/downgrade log before a
timeout.
Default: 60

AUTODEPLOY_RUNNING_JOBS_TIM Determines the number of seconds to wait for jobs to

EOUT complete prior to deployment before a timeout occurs.
NOTE: This parameter is only relevant for
Control/Agents that do not support upgrade with no
downtime.
Default: 600

AD_MAX_BANDWIDTH Determines the maximum bandwidth (KB/second) limit to

transfer the installation packages from Control-M/Server
to Control-M/Agent.
Default: 1024

144
Control-M Administrator Guide

Parameter Description

DEPLOYMENT_THREADS Determines the maximum number of upgrade or

downgrade processes that can run simultaneously.
Default: 5

AD_REQUIRED_DISK_SPACE Determines the minimum number of MB required in the

Control-M/Server computer to perform an upgrade.
Default: 2048

AD_RETAIN_PACKAGES Determines the number of days that the installation

package is saved in the Control-M/Server cache.
Valid Values:
 0: Never remove
 1-365
Default: 30

High Availability parameters

The following table describes Control-M/Server High Availability system parameters.

Parameter Description

HA_DB_LIFECHECK_TIMEOU Determines the maximum time to wait for a response from the
T database server. If the maximum time has passed, and there is no
response, it is considered a failure.
Default:5

HA_DB_LIFECHECK_TRIES Determines the number of consecutive life check requests to the

database server without getting a response.
Default:3

HA_DB_MAX_STARTUP_TRI (PostgreSQL only) Determines the number of unsuccessful

ES attempts that Configuration Agent tries to start up the database
server.
Default:20

HA_DB_TIME_BETWEEN_LIF Determines the number of seconds to wait between sending life

ECHECKS check requests to the database server.
Default:5

145
Control-M Administrator Guide

Parameter Description

HA_DB_TIME_TO_WAIT_AF (PostgreSQL only) Determines the number of seconds to wait after

TER_STARTUP the Configuration Agent started up the database server.
Default:10

HA_LIFECHECK_TIMEOUT Determines the maximum number of seconds to wait for a life

check response before a timeout.
Default:5

HA_LIFECHECK_TRIES Determines the number of consecutive failed life check requests

between the the Configuration Agent and Control-M/Server before
the Configuration Agent tries to start it up.
Default:3

HA_MAX_STARTUP_TRIES Determines the number of unsuccessful attempts that SU process

tries to start up a process and then crashes before shutting down
Control-M/Server.
Default:20

HA_TIME_BETWEEN_LIFECH Determines the number of seconds to wait between sending life

ECKS check requests to the primary Configuration Agent.
Default:15

HA_TIME_TO_WAIT_AFTER_ Determines the number of seconds to wait after the Configuration

STARTUP Agent started up a component.
Default:10

WARN_LOW_SHARED_DIR_ Determines when to send a warning that the shared directory disk
SPACE space is lower than the value defined here in MB.
Valid Values: 0-1000000
Default:1048

146
Control-M Administrator Guide

Communication parameters
The following table list the Control-M/Server communication parameters.

Parameter Description

AGENT_TO_SERVER_HOSTNAME Determines the hostname used by the Control-M/Agent to

communicate with the Control-M/Server
Control-M/Server can be connected to the Control-M/EM through an
IP/specific network and to the Control-M/Agents through a different
segment of network using a different IPs to have more secure
communication: <Administration IP> to connect to Control-M/EM
and <Services IP> to connect to Control-M/Agents.
This parameter is used to separate the listening interface from
Control-M/EM and Control-M/Agents.
NOTE: If you define this parameter on a non-active high availability
environment, the changes take affect within 10 minutes from the
time they were saved.
How / where to set:
In the config.dat file of Control-M/Server and the CONFIG.dat file
of Control-M/Agent, set the IPV_MODE parameter to DUAL and
then restart both Control-M/Server and Control-M/Agent.

Agent-to-Server Port Number The listening port number of the NS process (not to be used for any
(CTMS_PORT_NUM) other purpose in the server computer). Control-M/Server
communicates with Control-M/Agent using two TCP/IP ports.
CTMS_PORT_NUM specifies the port for data flowing from
Control-M/Server to Control-M/Agent. The other port is specified
using Server-to-Agent Port Number parameter.
NOTE: This number must match the value assigned to the
Agent-to-Server Port Number parameter on the agent
computer.
Valid Values: 1024–65534
Default: 7005 (On UNIX, the default value is overridden, using the
value given during installation.)
How: ctm_menu > Parameter Customization > Basic
Communication and Operational Parameters > Agent to
Server Port.
Refresh Type: Recycle

147
Control-M Administrator Guide

Parameter Description

AGENT_SERVICE_TIMEOUT Determines the number of seconds for the Control-M/Server to wait

for an agent to respond to a request (all requests excluding submit,
ping and save script requests).
Valid Values: 1-7200
Default: 3600

Allow Agent Disconnection Set the ALLOW_ AG_DISCONNECTION parameter to determine if

(ALLOW_AG_DISCONNECTION) the current connection to this AGT can be disconnected when
MAX_CONCURRENT_SESSIONS is reached.
Valid Values: Y and N
Default: Y

CA_HA_PORT_NUMBER Determines the communication port number between the

Control-M/Server Configuration Agents on the primary and
secondary host in a High availability environment.
Default: 2368
How: ctm_menu > Parameter Customization > Basic
Communication and Operational Parameters > High
Availability Port Number.

Check Interval (AVPOLTIM) Interval (in seconds) between status checks for each
Control-M/Agent that communicates with Control-M/Server.
Valid Values: 30-65534
Default: 7200 (2 hours)

Communication Protocol Protocol used to communicate with the agent computers. (The
protocol specified here must be the same as that specified on the
agent computer.)
Valid Values: TCP
Default: TCP It is recommended that you use TCP when there are
many jobs running simultaneously reporting to Control-M/Server.
Refresh Type: Recycle

Communication trace Determines whether communication packets that Control-M/Agent

(COMM_TRACE) sends to and receives from Control-M/Server are written to a file. If
set to 1, separate files are created for each session (job, ping, and
so forth). This parameter can only be changed after completing the
installation.
Valid values: 1 (on), 0 (off)
Default: 0 (off)

148
Control-M Administrator Guide

Parameter Description

COMM_TRACE_PARSED Determines whether communication packets that Control-M/Agent

sends to and receives from Control-M/Server are written to a file
with a parsed value (the packets information).
This parameter can only be changed after completing the
installation.
NOTE: You can only set this parameter to 1 if the COMM_TRACE
parameter is enabled.
Valid values: 1 (on), 0 (off)
Default: 0 (off)

Configuration Agent Port Number The Control-M/Server Configuration Agent listening port number.
(CTM_CONFIG_AGENT_PORT_NU
Valid values: 1025–32767
MBER)
Default: 2369
How / where to set: In the Control-M Main Menu, choose
Parameter Customization => Basic Communication and
Operational Parameters => Configuration agent Port.
Refresh Type: Recycle

CONTROL-M/Configuration Determines the mode of the Control-M/Server Configuration Agent.

Agent operation mode
Valid values:
(CTM_CONFIG_AGENT_MODE)
 0 (OFF_MODE): Disable Configuration Agent process, no
communication with CMS is allowed.
 1 (READ_MODE): Only life check and information requests are
honored, any modifying request is rejected.
 2 (ALL_MODE) Any CMS request is honored.
Default: 2
Refresh Type: Recycle

CTM_CONFIG_AGENT_AGENT_U The Control-M/Server Configuration Agent issues the following

NAVAIL_THRESHOLD message when the number of unavailable agents is equal to or
greater than the threshold:
Some of the Control-M/Agents are unavailable.
Valid values: 1–2^31
Default: 1
Refresh Type: Manual

149
Control-M Administrator Guide

Parameter Description

CTM_CONFIG_AGENT_INITIAL_ For Control-M/Agents and remote hosts for which Control-M/Server

GET_HOSTNAME_INTERVAL has not previously identified the operating system and Agent
version, the frequency, in seconds, with which Control-M/Server will
try to retrieve that information so that it is available to the end user
via CCM.
Default: 5 (seconds)

Control-M/EM TCP/IP Port The port number that Control-M/Server uses to listen for
Number communication from Control-M/EM. Verify that the port number is
(GATEWAY_TO_SERVER_PORT) not used for any other purpose on the server computer.
Valid values: between 1025 and 32767 inclusive.
Default: 2370
Refresh Type: Recycle

Inter Process Communication The listening port number of the RT process.

(IPC) Port Number
Valid Values: 1025–32767
(CTM_RT_PORT_NUMBER)
Default: 6005
How / where to set: In the Control-M Main Menu, choose
Parameter Customization => Basic Communication and
Operational Parameters => IPC Port.
Refresh Type: Recycle

EM_SOCK_RCVBUF Determines the number of bytes of the receive buffer of the TCP/IP
socket connected to the Control-M/EM gateway.
Valid Values:
 -1
 1024–10000000
NOTE: -1 indicates using the machine's configured default.
Default: -1

EM_SOCK_SNDBUF Determines the number of bytes of the send buffer of the TCP/IP
socket connected to the Control-M/EM gateway.
Valid Values:
 -1
 1024–10000000
NOTE: -1 indicates using the machine's configured default.
Default: -1

150
Control-M Administrator Guide

Parameter Description

Local IP Host Interface Name Host interface name of the TCP/IP network interface card on the
server computer to use for communication with Control-M/EM.
This name is typically the host name of the server computer. You
should modify this parameter only if the server computer contains
more than one network interface card (for example, Ethernet and
Token-Ring) or use another name for external communication (AWS
public name).
NOTE: If you define this parameter on a non-active high availability
environment, the changes take affect within 10 minutes from the
time they were saved.
Valid Values: host name, or host IP address (for example,
192.123.186.20)
Default: the default host interface name defined in the server
computer operating environment.

Configuration Agent Port Port number for the Control-M/Server Configuration Agent.
Valid Values: 1025–32767
Default: 2369
Refresh Type: Recycle

Maximum Concurrent Sessions Indicates the maximum number of concurrent sessions that the NS
(CTM_MAX_CONCURRENT_SESSI process will hold.
ONS)
Once the maximum of the MAX_CONCURRENT_SESSIONS
parameter is reached, the session with the maximum idle time will
be terminated in order to open a new connection. If this agent
connection is marked as not allowed to be disconnected (see the
ALLOW_ AG_DISCONNECTION parameter) then the next one in line
will be disconnected.
Valid Values: All integers in the range of 16 to the maximum
available according to the operating system.
Default: 256

CMN_PRM_CD_MAX_SERVICES Maximum number of requests (originating from CONTROL-M/EM

gateways) that Control-M/Server can queue.
Valid Values: 60–32000
Default: 60
How / where to set:
Refresh Type:

151
Control-M Administrator Guide

Parameter Description

CTM_VARIABLE_SHOUT_ON_ Enables alerts to be sent when variables have not been resolved
ERROR_URGENCY during job submission. You can set this parameter in the config.dat
file.
The format for the parameter is:
CTM_VARIABLE_SHOUT_ON_ERROR_URGENCY <urgency>
Valid values:
 N – Do not send alert
 R – Regular (default value)
 U – Urgent
 V – Very urgent
For changes to take effect, restart Control-M/Server or run the
following command:
ctmipc -dest ALL -msgid CFG

COMTIMOUT Communication timeout in seconds.

Valid Values: 10–2^31
Default: 60 (seconds)
How / where to set: In the Control-M Main Menu, choose
Parameter Customization => Default Parameters for
Communicating with Agent Platforms => Communication
Timeout.
Refresh Type: Recycle

COMTRYNO Communication retry value.

Valid Values: 1–2^31 (seconds)
Default: 5
How / where to set: In the Control-M Main Menu, choose
Parameter Customization => Default Parameters for
Communicating with Agent Platforms => Maximum Retries.
Refresh Type: Recycle

152
Control-M Administrator Guide

Parameter Description

Communication Protocol Version Version of Control-M/Agent.

(COMVERSION)
Valid values:
 09 - 7.0.00
 10 – 8.0.00
 11 - 9.0.00
Default: 11

IPC_SOCK_RCVBUF Determines the number of bytes of the receive buffer of the TCP/IP
socket used by the CE process for internal communication.
Valid Values:
 -1
 1024–10000000
NOTE: -1 indicates using the machine's configured default.
Default: -1

IPC_SOCK_SNDBUF Determines the number of bytes of the send buffer of the TCP/IP
socket used by the CE process for internal communication.
Valid Values:
 -1
 1024–10000000
NOTE: -1 indicates using the machine's configured default.
Default: -1

IPV_MODE Determines whether to enable IPV6.

Valid Values:
 IPV4
 DUAL (Enables IPV6)
Default: IPV4
How / where to set: In the config.dat file of Control-M/Server
and the CONFIG.dat file of Control-M/Agent, set the IPV_MODE
parameter to DUAL and then restart both Control-M/Server and
Control-M/Agent.
NOTE: If Control-M/Server and/or Control-M/Agent.are installed on
AIX, verify that the fix for APAR IV23320 is installed.
If you want to enable IPV6 before installation, see Setting
environment variables in UNIX.

153
Control-M Administrator Guide

Parameter Description

Maximum Disconnect Time Sets the maximum time in which the NS allows an agent to be
(MAX_DISCONNECT_TIME) disconnected before it will initiate a session with it (although there's
nothing to submit to it). The MAX_DISCONNECT_TIME parameter is
relevant only if the ALLOW_COMM_INIT parameter on the agent is
set to NO.
Valid Values: integers in the range 30 - 86400 (in seconds)
Default: 300

OS_PRM_HOSTNAME Used in various ways, for example, the name of the server to be
sent to the Agent, for later comparison with the Agent's permitted
server list.
Valid Values: 85 characters
NOTE: Contact your system administrator to learn about the DNS
restrictions and limitations relevant to your environment.
Default: gethostname
How / where to set:
(UNIX) In the Control-M Main Menu, choose Parameter
Customization => Basic Communication and Operational
Parameters => Local IP host interface name.
Refresh Type: Recycle

OUTGOING_ADDR Enables you to define an IP address for Server to Agent

connections. Update this parameter in the local_config.dat file.
Valid Values: IP address or hostname
Default: hostname
Refresh Type: Recycle

Persistent Connection Indicates the persistent connection setting. Set the

(PERSISTENT_CONNECTION) PERSISTENT_CONNECTION parameter to connect to a specific
agent with either a persistent or transient connection.
When Persistent Connection is set to Y (for example, with an
agent version 6.2.01), the NS process creates a persistent
connection with the agent and manages the session with this agent.
If the connection is broken with an agent or NS is unable to connect
with an agent, the agent is marked as Unavailable. When the
connection with the agent is resumed, the NS recreates a persistent
connection with the agent and marks the agent as Available.
Valid Values: Y or N
Default: N for a new agent installation and N for an agent that is
known to Control-M/Server before upgrading to version 6.2.01 and
above.

154
Control-M Administrator Guide

Parameter Description

Polling Interval (POLLTIME) Time interval (in seconds) between requests from Control-M/Server
for status updates from agent computers that are executing jobs.
Valid Values: 60-65534
Default: 900

PORTNUM Determines the Server to Agent port number.

Valid Values: 1024 to 65534

Retry Interval (UNAVPOLTIM) Length of time to wait (in seconds) between attempts to
communicate with an agent computer whose status is Unavailable.
Valid Values: 30-65534
Default: 90

Session Idle Timeout Indicates the maximum time a session can be in idle before NS
(SESSION_IDLE_TIMEOUT) terminates it.
Valid Values: integers in the range 30 - 86400 (in seconds)
Default: 900

SOCKET_SNDBUF Determines the number of bytes of the send buffer of TCP/IP

sockets created by the C processes of Control-M/Server.
Valid Values:
 0
 1024-10000000
NOTE: 0 indicates using the machine's configured default
Default: 0

SUBMIT_TIMEOUT Determines the number of seconds for the Control-M/Server to wait

for an agent to respond to a submit request before a timeout.
Valid Values: 1-3600
Default: 240

Unavailability Shout Urgency Indicates messages with a high priority sent from an agent assigned
(UNAV_URGENCY) Unavailable status. Urgent message are sent with a special
indication so that the recipient of the message is aware of the
urgency.
Valid values: R, U, or V
Default: R

155
Control-M Administrator Guide

Scheduling and execution parameters

The following table describes scheduling and execution parameters.

Parameter Description

ACCEPT_UNFAMILIAR_ Determines which Hosts that are not defined in the Control-M/Server are
HOSTS allowed to initiate communication with it
Valid values: N, Y
Default: Y

CD_MAX_DBU When there is no current Control-M/EM session, Control-M accumulates

database updates before downloading them to Control-M/EM. CD_MAX_DBU
determines the maximum number of updates to accumulate before requesting a
download.
Valid Values: 100–2^31
Default: 1000
How / where to set: In the Control-M Main Menu, choose Parameter
Customization => Advanced Communication and Operational
Parameters => Maximum Job State Changes.
Refresh Type: Manual

CTM_AJF_ADJUST_CO Determines whether to ignore the prerequisite conditions of a SMART folder

ND_INCLUDE_SMART_ entity, when the predecessor jobs that normally set these conditions are not
FOLDER_ENTITY scheduled.
Valid values are:
 Y: Ignore relevant prerequisite conditions.
 N: Do not ignore relevant prerequisite conditions.
Default: N
Refresh Type: Recycle
NOTE: This parameter is relevant only when ADJUST_COND is set to Y and
the parameter CTM_ADJUST_COND_SCOPE is set to AJF. For more
information, see Adjust Condition.

156
Control-M Administrator Guide

Parameter Description

CTM_ADJUST_COND_S For jobs in the SMART Folder, determines conditions of which unscheduled
COPE predecessor jobs to ignore.
Valid values:
 AJF – Ignore predecessor jobs in the Active Jobs level. When selected, jobs
in the SMART Folder ignore conditions set by jobs in Active Jobs that are
not scheduled.
 GROUP – Ignore predecessor jobs in the group level. When selected, jobs
in the SMART Folder ignore conditions set by jobs in the SMART Folder that
are not scheduled. Default.
NOTE: This parameter is relevant only when ADJUST_COND is set to Y. For
more information, see ADJUST_COND in Control-M Parameter.
Default: GROUP
Refresh Type: Manual

CTM_VARIABLE_ALLO Enables user-defined variables to contain the - (hyphen) character.

W_HYPHEN
Valid values: N, Y
Default: N
Refresh Type: Manual
NOTE: If a job has an variable that includes a hyphen in the variable name, it
will fail when submitted to an agent that is running on UNIX.

CTM_GD_FORWARD Indicates if job with a time zone specified should be ordered according to the
current Odate, or tomorrow’s Odate.
Valid values:
 Y – During the New Day Procedure, jobs with a specified time zone are
ordered only if they are scheduled for tomorrow’s Odate.
 N – During the New Day Procedure, jobs with a specified time zone are
ordered only if they are scheduled for the current Odate.
Default: Y
Refresh Type: Recycle

157
Control-M Administrator Guide

Parameter Description

CTM_MULTIP_LIB_REP Indicates if AutoEdit variable %%MEMLIB overrides the MEMLIB value for all
LACE jobs in a folder with a command such as:
ctmorder -schedtab test2...-jobname "*" -autoedit %%MEMLIB d:/testdir
If you use the same command for a specific jobname, this parameter is ignored.
Valid values: Y, N
Default: N
Refresh Type: Manual

CTM_FOLDER_ADJUST Controls creation of dummy jobs that run in place of unscheduled prerequisite
_DUMMY jobs.
Valid values:
 Y—A dummy job waits for the prerequisite conditions expected by the job it
is replacing, and performs the post processing of the job. When a SMART
Folder is ordered, jobs in the folder that should not be ordered at this time
are ordered as DUMMY jobs. This functionality is useful for data centers that
require identical job flow regardless of whether certain jobs in a folder are
ordered for a specific instance of the folder.
 N—Out conditions of the jobs that were not ordered are ignored by the
ordered jobs in the SMART Folder.
NOTE: This parameter is relevant only when ADJUST_COND is set to Y. For
more information, see ADJUST_COND in Control-M Parameters.
Default: N
Refresh Type: Manual

CTM_FOLDER_RECHEC Indicates if SMART Folder or Sub-folder conditions should be checked for each
K job in a SMART Folder or Sub-folder after the SMART Folder or Sub-folder
conditions have been satisfied.
Valid values:
 N— SMART Folder or Sub-folder conditions are ignored when ordering
specific jobs in a folder.
 Y— SMART Folder or Sub-folder conditions are checked for each job in the
folder (in addition to conditions specified for the job).
NOTE: If N is specified for this parameter, SMART Folders or Sub-folders are
activated when the necessary conditions exist, and remain active regardless of
whether or not any of those conditions are deleted.
Default: N
Refresh Type: Recycle

158
Control-M Administrator Guide

Parameter Description

CTMORDER_FORCE The default action of the utility is to order, not force, jobs in Active Jobs. This
action can be modified by adding keyword Force to the command that invokes
the utility. To change the default to force, set this parameter to Y.
Valid values: Y, N
Default: N
Refresh Type: Automatic

CTM_UDAILY_LOCK_TI Determines the number of seconds to wait before releasing a lock on all folders
MEOUT in a user daily.
Default: 900
Refresh Type: Manual (ctmipc -dest all -msgid CFG)
EXAMPLE: If the user daily duration is 8 minutes, change the
CTM_UDAILY_LOCK_TIMEOUT parameter to 480 or more.

CYCLIC_MAXWAIT Indicates when Cyclic jobs/SMART Folders that have previously executed at
least once, are removed from Active Jobs by the New Day procedure.
Valid values:
 KEEP – each job is removed when MAXWAIT days have passed regardless
of whether it ended OK.
 NOT_KEEP – each job (non-cyclic and cyclic) is removed from Active Jobs
at the next run of the New Day procedure. Cyclic jobs/SMART Folders are
not removed if they are executing when the New Day procedure begins.
Instead, they are removed at the run of the following New Day procedure.
Default: KEEP
Refresh Type: Recycle

CYCLIC_RERUN If a Cyclic job/SMART Folder ends NOTOK and this parameter is set to OK, the
Cyclic job/SMART Folder will be rerun. If set to NOTOK, the Cyclic job/SMART
Folder will not be rerun.
Valid values: OK, NOTOK
Default: OK
Refresh Type: Manual

159
Control-M Administrator Guide

Parameter Description

HOST_AUTODISCOVER Determines whether a Control-M/Agent is automatically discovered using an

unfamiliar host.
Valid values:
 Y
 N
Default: Y

NOT_ORDERED_JOB_A Type of Alert message to send to Control-M/EM when a job is not ordered due
LERT to scheduling criteria.
Valid values:
 0 – One General Alert per User Daily: ONE OR MORE JOBS IN DAILY
<daily_name> WERE NOT ORDERED
 1 – One Alert message per job: DAILY <daily_name> FAILED TO ORDER
JOBNAME <jobname>
 2 – Do not issue Alert messages
Default: 0
Refresh Type: Recycle

SCHED_NEGATIVE_SC Determines whether negative values take precedence over positive values in
OPE Week or Day parameters when defining a job schedule
Valid values:
 0
 1
Default: 1

SCHED_NON_EXIST_D When DAYS is >n, or <n, should we order the job on the next (>n), or previous
AY (<n) working day, if n is a non-existing day for the specific month? If the
parameter is set to Y, then we should order the job
Valid values: N, Y
Default: N
Refresh Type: Manual

SHOUT_TO_PROGRAM Determines the maximum number of seconds to wait for a shout to program to
_TIMEOUT complete before continuing to process the job
Valid values: 0 (unlimited) - 2147483648
Default: 20

160
Control-M Administrator Guide

Parameter Description

UDLY_PARTCOPY_ERR Error code returned by ctmudly utility if one or more jobs in a folder are not
ordered by a User Daily job (due to scheduling criteria or security settings).
Valid values:
 0 – User Daily job ends with an exit code of 0 even if not all jobs are
ordered.
 1 – User Daily job ends with an exit code of 14 if not all jobs are ordered.
Default: 0
Refresh Type: Automatic

VARIABLE_INC_SEC Indicates which variables are sent to the agent for each submitted job.
Valid values:
 SYSTEM—All the variables for each submitted job are sent to the agent.
These include System, Global, Group, and Local variables.
 GLOBAL—Global, Group, and Local variables are sent to the agent for each
submitted job. System variables are not sent.
 GROUP—Group and Local variables are sent to the agent for each
submitted job. System and Global variables are not sent.
 LOCAL—Only Local variables are sent to the agent.
Default: LOCAL
Refresh Type: Manual

161
Control-M Administrator Guide

Performance parameters
The following table describes the performance parameters.

Parameter Description

WARN_SLOW_DNS_MIL Determines the number of milliseconds to wait before a warning is issued

LIS stating that that DNS is performing too slow.
Default: 3000
To disable, set to 0.

WARN_SLOW_DISK_MI Determines the number of milliseconds to wait before a warning is issued

LLIS stating that the disk is performing too slow.
Default: 180
NOTE: This parameter is not generated when the debug level is set to 4.
To disable, set to 0.

WARN_SLOW_CONNEC Determines the number of milliseconds to wait before a warning is issued

T_MILLIS stating that the connection between Control-M/Server and Control-M/Agent is
too slow.
Default: 3000
To disable, set to 0.

WARN_SLOW_FAILED_ Determines the number of milliseconds to wait before a warning is issued

CONNECT_MILLIS stating that the connection attempt after a failure between Control-M/Server
and Control-M/Agent is too slow.
Default: 30000
To disable, set to 0.

162
Control-M Administrator Guide

Input/Output parameters
The following table describes Control-M/Server Input/Output parameters.

Parameter Description

ALARM_DEST Logical name of the Shout destination for critical Alert messages.
Valid values:
 EM—Control-M/EM GUI
 IOALOG—Control-M IOALOG files
 CONSOLE—Server console
Default: EM
Refresh Type: Manual

CTM_TIMEZONE_DISPLAY Indicates if job run time is adjusted to time zone.

Valid values:
 N – the Next Run time of a job is in local computer time, not
adjusted to time zone.
 Y – the Next Run time of a job is adjusted to the correct time
zone.
Default: N
Refresh Type: Manual

CTM_WRITE_CONSOLE If this parameter is set, critical alerts are sent to the console of
the server in addition to being sent as Shout messages to
Control-M/EM.
Valid values: YES, NO
Default: NO
Refresh Type: Recycle

163
Control-M Administrator Guide

Parameter Description

OUTPUT_LIMIT_SIZE Maximum OUTPUT size that can be viewed by the output

command from Control-M/Server and Control-M/EM. The value is
set in Kilobytes.
If a OUTPUT file exceeds the value specified by the
OUTPUT_LIMIT_SIZE configuration parameter, it cannot be
viewed from Control-M/Server or Control-M/EM, and the following
message is displayed:
OUTPUT FILE EXCEEDED LIMIT SIZE (CAN BE VIEWED FROM
FILE SYSTEM)
Valid values: 0–2^31
Default: 0 (unlimited)
Refresh Type: Manual

OUTPUT_WINDOW_SIZE Specifies the maximum number of characters for a OUTPUT file

line.
Valid values: 80–132 characters
Default: 80
Refresh Type: Manual

OS_DIAG_LIMIT_LOG_VERS Number of generations of diagnostic log information to keep for a

IONS process or a thread.
Valid values:
 -1 (no limit to the number of files)
 1–2^31
Default: -1 (In the shipped config.dat, the default value is
overridden by 10.)
Refresh Type: Recycle

OS_DIAG_LIMIT_LOG_FILE_ Maximum size (MB) of diagnostic log files for a process or a

SIZE thread.
Valid values:
 -1 (no filesize limit)
 1–2^31
Default: -1 (In the shipped config.dat, the default value is
overridden by 10.)
Refresh Type: Recycle

164
Control-M Administrator Guide

Logging parameters
The following table describes Control-M/Server Logging parameters.

Parameter Description

Max. Days to Retain Output Number of days that job OUTPUT files are retained for jobs
Files (OUTPUTRETN) executed by agent computers
After this period, the New Day procedure deletes all job OUTPUT
files.
This parameter also affects the number of days that old nets are
saved. To view OUTPUT files of jobs in old nets, in some cases
OUTPUT files must be saved for an extra calendar day.
Valid values: Any number greater than 0.
Default: 1
How / where to set: Use the ctmsys utility to change the
parameter value.
Refresh Type: Automatic

Maximum Days Retained by The maximum number of days that entries are retained in the
Control-M Log (IOALOGLM) Control-M log before the New Day cleanup procedure deletes
them
NOTE:
If this value exceeds 2, the syslogs might run out of space. Either
delete the transaction log or use ALTER DATABASE to increase the
size of the segment.
For example, if the data device size is 400 MB and you want to
retain history for 10 days, enlarge the temporary database to
240 MB.
Valid values: Any number greater than 0.
Default: 2
How / where to set: Use the ctmsys utility to change the
parameter value.
Refresh Type: Automatic

CTMLOG_DEL_CHK When set to Y, the use of the ctmlog utility for delete operation to
Control-M is restricted. Administrator only.
Valid values: Y, N
Default: N
Refresh Type: Automatic

165
Control-M Administrator Guide

New Day parameters

The following table describes Control-M/Server New Day parameters.

166
Control-M Administrator Guide

NOTE: If you change the Ignore New Day Conditions to Y, edit or create a file in the home directory
of the Control-M owner account: ~<controlm_owner>/ctm_server/data/dbs_ignrcond.dat.

Parameter Description

AGENTS_CLEANUP_IN_NEW Specifies whether the New Day procedure sends a request to

DAY Control-M/Agents to remove OUTPUT files and exit status files
that are no longer needed.
Valid values: Y, N
 Y—The New Day procedure sends a request to
Control-M/Agents to remove OUTPUT files and exit status files
that are no longer needed.
 N —The New Day procedure does not send a request to the
Control-M/Agents to remove OUTPUT files and exit status files
that are no longer needed.
NOTE: You can speed up the New Day procedure by specifying N
for this parameter and running the ctmagcln utility. For more
information, see Control-M Utilities.
Default: Y
Refresh Type: Recycle

CTM_DB_TIMEOUT Timeout value for long New Day database transactions.

Valid values: 300–3600 (seconds)
Default: 300 (seconds)
Refresh Type: Recycle

167
Control-M Administrator Guide

Parameter Description

Day Time Start-of-day time that Control-M uses

(DAYTIME) This time is when the Control-M date (Odate) changes and the
New Day procedure runs.
Valid Values: either of the following formats (where hh indicates
hours and mm indicates minutes):
 +hhmm changes the Control-M date at the specified time
after midnight.
 -hhmm changes the Control-M date at the specified time
before midnight.
These values reflect 24-hour time. For example, 2200 is equivalent
to 10 P.M.
EXAMPLE:
If you use +0600, the hours between midnight and
6:00 A.M. are considered part of the previous date’s
work day. Thus, system date February 10, 5:59 A.M.
is considered part of the February 9 work day.
If you use -2200, the hours between 10 P.M. and
midnight are considered part of the next date’s work
day. Thus, at 10:00 P.M. on system date February 10,
the Control-M date changes to February 11.
Default: +0700
How / where to set: Use the ctmsys utility to change the
parameter value.
Refresh Type: Automatic

DOWNLOAD_THREADS Specifies the number of threads that would handle the download
process in case parallel download is enabled (NEWDAY_MODE =
1).
Valid values: 1–100
Default: 3

DOWNLOAD_CACHE_SIZE Determines the number of jobs that are cached in memory to

speed up the download. Increasing this number causes the
product to consume more memory.
Valid values: 100-100000
Default: 500

168
Control-M Administrator Guide

Parameter Description

FULL_CLEAN_AJF_BACKUP Determines whether to perform a Full backup when clean AJF is

enabled.
Valid values:
 Y–Enabled.
 N–Disabled.
Default: Y

Ignore New Day Conditions Whether the New Day procedure should ignore prerequisite
(C2) conditions if their reference date (day and month) matches the
Control-M date + 1.
How / where to set: Use the ctmsys utility to change the
parameter value.
Refresh Type: Automatic
Valid values: Y or N
Default: N

NEWDAY_MODE Determines whether New Day performance enhancements are

enabled.
Valid values:
 0: Disabled
 1:Enabled
Default: 1

STATISTICS_CLEANUP_IN_ Specifies whether the statistics cleanup action is executed during

NEWDAY the New Day procedure.
Valid values:
 Y—The statistics cleanup action is executed during New Day
procedure.
 N—The statistics cleanup action is not executed during New
Day procedure.
Note: You can speed up the New Day procedure by specifying N
for this parameter and running ctmruninf -PURGE.
Default: Y
Refresh Type: Recycle

169
Control-M Administrator Guide

Parameter Description

STOP_SUBMISSION_BEFORE Specifies the number of seconds preceding launch of the NewDay

_NEWDAY procedure during which jobs are not submitted.
Valid values: 0–3600 (seconds)
Default: 2 (seconds)
Refresh Type: Manual

SYSTEM_DAILY_THREADS Specifies the number of threads that would handle the SYSTEM
user daily when parallel system daily is enabled (NEWDAY_MODE
= 1)
Valid values: 1–100
Default: 4

170
Control-M Administrator Guide

Security parameters
The following table describes Control-M/Server security parameters.

Parameter Description

EM_BYPASS_CTMSEC When set to 'Y', EM users requests would not be checked against
Control-M/Server Security definition. Only the Control-M/EM
Authorization definition would be checked
Determines whether Control-M/EM users are authenticated against
Control-M/Server Security definitions.
Valid Values:
 Y: Not authenticated against Control-M/Server Security
definitions.
 N: Authenticated against Control-M/Server Security
definitions.
Default: N

Full Security Whether Control-M operates with a restricted or unrestricted level

of security
(SECURE)
NOTE: A user for whom one or more authorizations have been
assigned in the security database can perform only the actions for
which the user is specifically authorized.
Y (restricted) means a user who is not defined in the Control-M
security database does not have any application authorizations.
N (unrestricted) means a user who is not defined in the Control-M
security database is regarded as having all application
authorizations.
Default: N
Refresh Type: Automatic

STRONG_ORDER_SECURITY Determines whether to allow the following variables in order/force

commands: %%PRECMD, %%POSTCMD, %%MEMLIB,
%%OVERLIB
Valid Values:
 Y: Not allowed
 N: Allowed
Default: Y

171
Control-M Administrator Guide

Statistics parameters
The following table describes Control-M/Server Statistics parameters. You can also use the following
various utilities to display, compile, and delete statistical data, as described in Statistics and reporting.

Parameter Description

ONGOING_STATISTICS_CLE Determines whether to purge job statistics also during the day.
ANUP
NOTE: This parameter is not relevant if an MSSQL database is
used.
Valid Values:
 Y
 N
Default: Y

RUNINF_CUTOFF_NUMBER Affects the statistics cleanup algorithm that is performed during

New Day when the RUNINF_PURGE_MODE is set to 0 (default). If
the number of records to be deleted from the table is less than
the value of this parameter, then records are deleted directly from
the statistics table. Otherwise a temporary table is used to delete
the records.
Valid values: 0 - 65K
Default: 2000
Refresh Type: Recycle

RUNINF_CUTOFF_RATIO Affects the statistics cleanup algorithm that is performed during

New Day when the RUNINF_PURGE_MODE is set to 0. If the ratio
between the number of records to be deleted and the number of
records in the table is less than the value of this parameter, then
records are deleted directly from the statistics table. Otherwise a
temporary table is used to delete the records.
Valid values: decimal fraction between 0–1
Default: 0.33
Refresh Type: Recycle

RUNINF_PURGE_LIMIT Number of Run Information records to keep for a given

MemName/MemLib/HostID. If RUNINF_PURGE_MODE is
0, the New Day Procedure deletes all Run Information records for
each unique name except the last n records, where n is the value
of this parameter.
Valid values: 1–2^31
Default: 20
Refresh Type: Recycle

172
Control-M Administrator Guide

Parameter Description

RUNINF_PURGE_MODE Valid values: 0, 1

0 – Performs -PURGE cleanup. Statistics records per job are kept
according to the specified Statistics Mode (either MEMNAME or
JOBNAME). Default: 20 records of each MEMNAME or JOBNAME
are kept.
If the RUNINF_PURGE_LIMIT in the config.dat is specified, the
number of records that are kept is determined by this parameter.
1 – Performs -DELETE cleanup. Only the amount of days that are
specified are kept. Default: The number of days kept is specified
by the How Many Days to Retain ioalog parameter.
If the RUNINF_PURGE_LIMIT in the config.dat is specified, the
number of days that are kept is determined by this parameter.
Default: 0
Refresh Type: Recycle

STATIST Determines whether Control-M/Server collects job statistics

Valid Values:
 Y
 N
Default: Y
See Also: ctmruninf, ctmstats

STATISALG Specifies mode used to collect summary statistics by ctmjsa. In

addition it is used for actions on statistics such as average and
deletion.
Valid values:
 JOBNAME – compiles statistics for each Control-M Job
Name/Table and Host ID where the job was submitted
 MEMNAME – compiles statistics for each Control-M Mem
Name/Mem Lib and Host ID
Default: FILENAME
Refresh Type: Recycle
See Also: ctmruninf, ctmstats

173
Control-M Administrator Guide

Parameter Description

STATS_TIME For statistics calculation, indicates how the START TIME and END
TIME for a job should be set.
Valid values:
 SERVER – START TIME and END TIME are set by
Control-M/Server.
 AGENT – START TIME and END TIME are set using
information received from the Control-M/Agent.
Default: SERVER
Refresh Type: Manual

SMTP parameters
The following parameters are applicable to DOMAIL, -DOSHOUT (when shout destination is mail),
ctmshout, and –SHOUT (when shout destination is mail).
The OUPUT of a job can be attached to an e-mail message only if the job has completed processing.

Parameter Description

ADD_OUTPUT_TO_EMAIL Determines whether the OUTPUT of a job can be attached to e-mail

messages.
Valid values:
 N – No. When specified, the OUTPUT of a job is not attached. This
setting overrides any specification made elsewhere.
 A – Attachment. When specified, the OUTPUT of a job is attached. This
setting overrides any specification made elsewhere.
Default: N
Refresh Type: Manual

ADD_OUTPUT_TO_EMAIL_ Determines the maximum size of the attachment OUTPUT file in kilobytes.
LIMIT_SIZE You can specify the value 0 for unlimited size.
NOTE: If the OUTPUT file is larger than the specified maximum size, the
OUTPUT will not be attached to the e-mail message.
Valid values: 0–2^31
Default: 5120KB (5MB)
Refresh Type: Manual

174
Control-M Administrator Guide

Parameter Description

ADD_OUTPUT_TO_EMAIL_ When sending a mail request—with a OUTPUT file attached—to the SMTP
TIMEOUT_LIMIT server, determines the maximum time to wait.
Valid values: 1–300 (seconds)
Default: 30 (seconds)
Refresh Type: Manual

MAIL_ADD_SUBJECT_PRE Determines if the Control-M/Server Shout by orderno prefix must be

FIX added to the subject of the e-mail message.
Valid values: Y, N
Default: Y
Refresh Type: Manual

MAIL_TIMEOUT Determines the maximum time to send the mail request to the SMTP server
when no OUTPUT is attached.
Valid values: 1–30 (seconds)
Default: 10 (seconds)
Refresh Type: Manual

MAX_GET_HOST_RETRIES Number of attempts to get an Agent's network information

Valid values: 1-2048
Default: 5

SMTP_SERVER_NAME Specifies the name of the SMTP server relay.

Valid values: 0 - 50 characters
Default: "" (During installation, this is overridden by a null value.)
How / where to set: In the Control-M Main Menu, choose Parameter
Customization => Simple Mail Transfer Protocol Parameters =>
SMTP Server (Relay) Name.
To disable, use a dummy value.
EXAMPLE: do-not-send-mails
Refresh Type: Automatic

175
Control-M Administrator Guide

Parameter Description

SMTP_SENDER_EMAIL Specifies the e-mail address used by Control-M/Server.

Valid values: 0 - 99 characters
Default: "" (During installation, this is overridden by Control@M.)
How / where to set: In the Control-M Main Menu, choose Parameter
Customization => Simple Mail Transfer Protocol Parameters =>
Sender Email.
Refresh Type: Automatic

SMTP_PORT_NUMBER Specifies the port number to which the service is assigned.

Valid values: 1–65536
Default: 25
How / where to set: In the Control-M Main Menu, choose Parameter
Customization => Simple Mail Transfer Protocol Parameters =>
Port Number.
Refresh Type: Automatic

SMTP_SENDER_FRIENDLY Specifies the regular text name used to identify the sender.
_NAME
Valid values: 0 - 99 characters
Default: Control-M/Server (During installation, this is overridden by a
null value.)
How / where to set: In the Control-M Main Menu, choose Parameter
Customization => Simple Mail Transfer Protocol Parameters =>
Sender Friendly Name.
Refresh Type: Automatic

SMTP_REPLY_TO_EMAIL Specifies the email address to which messages are returned if a return
address is not otherwise specified. If this parameter is null, the sender’s
email address becomes the default.
Valid values: 0 - 99 characters
Default: "" (During installation, this is overridden by a null value.)
How / where to set: In the Control-M Main Menu, choose Parameter
Customization => Simple Mail Transfer Protocol Parameters =>
Reply–To Email.
Refresh Type: Manual

176
Control-M Administrator Guide

User exit parameters

The following table lists the Control-M/Server user exit parameters.

Parameter Description

CTM_PRM_ENABLE_U Indicates whether Control-M user exits and Watchdog process exits are enabled.
E
Valid values: Y, N
Default: Y
Refresh Type: Recycle

CTM_PRM_ENABLE_U Indicates whether the associated UExxx user exit is enabled.

Exxx (101-106)
Valid values: Y, N
Default: N

CTM_PRM_SCRIPT_U Name of the UExxx user exit script. These scripts must reside in the
Exxx (101–106) ~<controlm_owner>/ctm_server/ue_exit directory.
Valid values: 1024 characters
Default:
 UE101 Job Ordering User Exit—ctm_exit101.sh
 UE102 Job Submission User Exit—ctm_exit102.sh
 UE103 Before New Day Procedure User Exit—ctm_exit103.sh
 UE104 After New Day Procedure User Exit—ctm_exit104.sh
 UE105 Before User Daily User Exit—Ctm_exit105.sh
 UE106 After User Daily User Exit —Ctm_exit106.sh
Refresh Type:
 UE101 Job Ordering User Exit—Manual
 UE102 Job Submission User Exit—Manual
 UE103 Before New Day Procedure User Exit—Recycle
 UE104 After New Day Procedure User Exit—Recycle
 UE105 Before User Daily User Exit—Manual
 UE106 After User Daily User Exit —Manual

177
Control-M Administrator Guide

Parameter Description

CTM_PRM_TIMEOUT_ Time to wait for a user exit script to run before it is terminated.
UExxx (101–106)
For UNIX: Time is measured in units of seconds
For Windows: Time is measured in units of milliseconds
Valid values: 20–2^31
Default: 20
Refresh Type:
 UE101 Job Ordering User Exit—Manual
 UE102 Job Submission User Exit—Manual
 UE103 Before New Day Procedure User Exit—Recycle
 UE104 After New Day Procedure User Exit—Recycle
 UE105 Before User Daily User Exit—Manual
 UE106 After User Daily User Exit —Manual

WD_CTMEXIT_NUMB Total number of Control-M/Server system exits to run.

ER
Valid values: Any whole number.
Default: 0 (set to 2 during installation)
NOTE: Do not change the initial value unless instructed to do so by BMC
Software Customer Support.

WD_USEREXIT_NUMB Total number of user exits to run.

ER
Valid values: 0–2^31
Default: 0
Refresh Type: Recycle

178
Control-M Administrator Guide

Utility parameters
The following table describes Control-M/Server Utility parameters.

Parameter Description

CTM_SLP_SUSPEND During New Day or Download of Active Jobs to Control-M/EM, the

ctmcreate, ctmudly, ctmorder utilities and ctmac and CS
processes are suspended (when trying to order). They stay
suspended until the Download or New Day is completed. This
parameter indicates the maximum number of times to wait, where
each time is configured, in seconds, by the parameter
CTM_SUS_SLEEP_TIME.
Valid values: 1–120 (times)
Default: 30
Refresh Type: Manual

CTM_SUS_SLEEP_TIME During New Day or Download of Active Jobs to Control-M/EM, the

ctmcreate, ctmudly, and ctmorder utilities and the ctmac and
CS processes are suspended (when trying to order). They stay
suspended until the Download or New Day is complete. This
parameter indicates the specified number of seconds to wait
before initiating a download or the New Day procedure.
See also CTM_SLP_SUSPEND.
Valid values: 1–180 (seconds)
Default: 60 (seconds)
Refresh Type: Manual

CTMUDCHK_RETRIES Determines the number of retries to run the ctmudchk utility if

ctmudly is ordering the user daily.
Default: 10

CTMUDCHK_RETRIES_WAIT Determines the number of seconds to wait before attempting to

run the ctmudchk utility
Default: 20

Watchdog process parameters

To automatically monitor essential Control-M/Server processes and resources, Control-M/Server contains a
facility called Watchdog (WD).

179
Control-M Administrator Guide

The Watchdog facility uses a Heartbeat monitor to check that all the primary Control-M/Server processes
are functioning. If any of these processes do not respond to the check, the Watchdog facility sends a
message to an error handler. (The facility automatically logs messages to the Control-M IOALOG and
PROCLOG files.)
An error handler is an object that contains and performs instructions for handling errors about which it
was notified. Generally, error handlers are scripts.
To monitor Control-M/Server processes, the Watchdog facility can use the following built-in utilities:
ctmdiskspace: Checks the amount of free disk space on a specified device and sends an error message to
the error handler if it is below the threshold.
ctmdbspace: Checks data and log usage in the Control-M/Server database and sends an error message to
the error handler if it is above the threshold.
The following parameters are used for the Watchdog Process. The CTM_PRM_ENABLE_UE parameter
must be set to Y to enable the WD process.
 Watchdog and lifecheck parameters (on page 180)
 Control-M/Server system exit parameters (on page 183)
 Watchdog parameters user exit parameters (on page 185)

Watchdog and lifecheck parameters

The following table lists the General Watchdog Process parameters.

Parameter Description

CTM_PRM_KPA_ACTI Whether the Heartbeat monitor operates in active or passive mode.

VE
Valid Values: Y (for active) or N (for passive)
Default: Y
Refresh Type: Recycle

CTM_PRM_KPA_BET Time in seconds between heartbeat checks.

WEEN_MSGS
Valid Values: 1–2^31 (integer)
Default: 300
Refresh Type: Recycle

CTM_PRM_KPA_ROU Time in seconds to wait for a confirmation from Control-M/EM.

NDTRIP_TIMEOUT
If confirmation does not arrive, a timeout is generated and the connection is
severed.
Valid Values: any integer
Default: 300
Refresh Type: Recycle

180
Control-M Administrator Guide

Parameter Description

WD_ALIVE_MSG Indicates message to be sent in response to successful heartbeat checks.

Valid values: 1024 characters
Default: ""
Refresh Type: Recycle

WD_CTO_HOSTNAME Host name or IP address of the computer running CONTROL-O/Server. If this

parameter is specified, the Watchdog process sends all error messages to the
CONTROL-O/Server Central Message window.
Valid values:Up to 255 characters.
Refresh Type:Recycle

WD_CTO_TIMEOUT Maximum time (in second) to send messages to CONTROL-O/Server before

terminating the communication.
Valid values: 1-10
Default: 10 seconds
How / where to set:
Refresh Type: Recycle

WD_ERROR_HANDLE Full path name of a user defined script called by the Watchdog process as an
R_SCRIPT_FILE error handler. The error messages are included as arguments to the script.
Valid values: 1024 characters
Default: "" (In the shipped config.dat, the default is overridden by
./scripts/UE_handler.)
Refresh Type: Recycle

WD_ERROR_HANDLE Maximum time for the Watchdog facility to wait for the user-defined script to run.
S_TIMEOUT
Valid values: 5–2^31
Default: 5 (In the shipped config.dat, this is overridden by the value 10.)
Refresh Type: Recycle

WD_HEARTBEAT_INT The Watchdog process checks Control-M/Server processes by sending a

ERVAL message. If this parameter is set to 5, the Watchdog process sends a message to
each of the primary Control-M/Server processes every 5th interval and awaits a
response.
Valid values: 1–2^31
Default: 5 (In the shipped config.dat, this is overridden by the value 1.)
Refresh Type: Recycle

181
Control-M Administrator Guide

Parameter Description

WD_HEARTBEAT_LIM Maximum time (in seconds) to wait for a response from each of the
IT Control-M/Server processes, after issuing a Heartbeat check, before sending a
message to the error handlers.
Valid values: 1–2^31
Default: 360
Refresh Type: Recycle

WD_INTERVAL Basic time unit interval, in minutes. When the value in either the
WD_CTMEXIT_#_INTERVAL parameter or the WD_USEREXIT_#_INTERVAL
parameter is multiplied by the value in this parameter, the resulting value is the
number of minutes that must pass before reinvoking the exit script.
For example, if the value of this parameter is 6 (minutes), and the value of the
WD_CTMEXIT_1_INTERVAL parameter is 20, the script for system exit 1 will run
once every 120 minutes (20 x 6 minutes).
Valid values: 1–2^31
Default: 5 (In the shipped config.dat, this is overridden by the value 6.)
Refresh Type: Recycle

182
Control-M Administrator Guide

Control-M/Server system exit parameters

The # used in each of the following Control-M/Server system exit parameters represents the
corresponding Control-M/Server utility that can be included in the Control-M/Server Watchdog process:
Disk Space Utility (1) and Database Usage Utility (2).

Parameter Description

WD_CTMEXIT_#_CMD_L Contains parameters to be passed to the exit script. Arguments must start
INE with a ‘-’ sign. Values separated by either a space or a ‘-’ sign must be
enclosed in double quotation. Mandatory.
Valid values: 1024 characters
Default: ""
In the shipped config.dat on UNIX, the default values are overridden as
follows:
 wd_ctmexit_1: -LIMIT "10 M" -PATH ctm_em
 wd_ctmexit_2: -LIMIT "90 M"
In the shipped config.dat on Windows, the default values are overridden as
follows:
 wd_ctmexit_1: -LIMIT 10M -PATH C:\
 wd_ctmexit_2: -LIMIT 90
Refresh Type: Recycle

WD_CTMEXIT_#_ERROR Error message string to be passed to the error handler(s) if the utility returns
_MSG a "failed" status. Optional.
Valid values: 1024 characters
Default: "" (In the shipped config.dat, for wd_ctmexit_1 and
wd_ctmexit_2, the default is overridden by "Low on database space.")
Refresh Type: Recycle

WD_CTMEXIT_#_INTER Number of basic time interval units that should pass before reinvoking the
VAL exit script. The basic time interval unit is defined in parameter
WD_INTERVAL.
For example, if the value of this parameter is 20, and the basic time interval
unit (as defined in parameter WD_INTERVAL) is 5 minutes, the exit script will
be invoked every 100 minutes (20 x 5 minutes).
Valid values: 1–2^31
Default: 5 (In the shipped config.dat, this is overridden by the value 20.)
Refresh Type: Recycle

183
Control-M Administrator Guide

Parameter Description

WD_CTMEXIT_#_RUN_S Specify whether (Y) or not (N) to run the utility when Control-M/Server is
TATE running. A Y must be specified for either this parameter or for parameter
WD_CTMEXIT_#_SUSPEND _STATE for the utility to be run.
Valid values: Y, N
Default: N (In the shipped config.dat, this is overridden by the value Y.)
Refresh Type: Recycle

WD_CTMEXIT_#_SCRIPT Relative path of the script or binary from the

_FILE ~controlm\ctm_server\exe_<computer> directory.
Valid values: 1024 characters
Default: "" (In the shipped config.dat, for both wd_ctmexit_1 and
wd_ctmexit_2, this is overridden by the value CTMDISKSPACE.)
Refresh Type: Recycle

WD_CTMEXIT_#_SUSPE Specify whether (Y) or not (N) to run the utility in Suspend mode (that is,
ND_STATE during New Day procedure or download, when the database inaccessible). A
Y must be specified for either this parameter or for parameter
WD_CTMEXIT_#_RUN _STATE for the utility to be run.
Valid values: Y, N
Default: N
Refresh Type: Recycle

WD_CTMEXIT_#_TIMEO Time (milliseconds) allowed before the exit script is terminated.

UT
Valid values: 1–2^31 (ms)
Default: 5 ms (In the shipped config.dat, this is overridden by the value
30.)
Refresh Type: Recycle

184
Control-M Administrator Guide

Watchdog parameters user exit parameters

The # used in the following user exit parameters represents a separate number for each user exit that
can be included in the Control-M Watchdog process . A user exit can be either a user supplied
script/executable file or a Control-M utility.

Parameter Description

WD_USEREXIT_#_CMD_ Contains parameters to be passed to the exit script. Arguments must start
LINE with a ‘-’ sign. Values separated by either a space or a ‘-’ sign must be
enclosed in double quotation. Mandatory.
Valid values: 1024 characters
Default: ""
Refresh Type: Recycle

WD_USEREXIT_#_ERRO Error message string to be passed to the error handler(s) if the check returns
R_MSG a "failed" status. Optional.
Valid values: 1024 characters
Default: ""
Refresh Type: Recycle

WD_USEREXIT_#_INTE Number of basic time interval units that should pass before reinvoking the exit
RVAL script. The basic time interval unit is defined in parameter WD_INTERVAL.
For example, if the value of this parameter is 2, and the basic time interval
unit (as defined in parameter WD_INTERVAL) is 5 minutes, the exit script will
be invoked every 10 minutes (2 x 5 minutes).
Valid values: 1–2^31
Default: 5
Refresh Type: Recycle

WD_USEREXIT_#_RUN_ Specify whether (Y) or not (N) to run the utility when Control-M/Server is
STATE running. A Y must be specified for either this parameter or for parameter
WD_USEREXIT_#_SUSPEND _STATE for the utility to be run.
Valid values: Y, N
Default: N
Refresh Type: Recycle

WD_USEREXIT_#_SCRI Relative path of the script or binary from the

PT_FILE ~controlm\ctm_server\exe_<computer> directory.
Valid values: 1024 characters
Default: ""
Refresh Type: Recycle

185
Control-M Administrator Guide

Parameter Description

WD_USEREXIT_#_SUSP Specify whether (Y) or not (N) to run the script in Suspend mode (that is,
END_STATE during New Day procedure or download, when the database inaccessible).
This parameter or WD_CTMEXIT_#_RUN _STATE must be set to Y for the
script to be run.
Valid values: Y, N
Default: N
Refresh Type: Recycle

WD_USEREXIT_#_TIME Time (milliseconds) allowed before the exit script is terminated.

OUT
Valid values: 1–2^31 (ms)
Default: 5 ms
Refresh Type: Recycle

New Day procedure

The New Day procedure is the start of the Control-M/Server day and is performed once a day at a
predefined time (see Control-M/Server component parameters (on page 17)). The New Day process
performs clean-up, purges old jobs, and loads the new jobs for the day. For example, you can delete
unneeded prerequisite conditions that were not deleted. During the New Day procedure, the
Control-M/Server processes shut down and do not start up again until New is complete.
The New Day procedure performs the following:
 Cleans up server logs, statistics and job information, and Control-M/Agent output
 Removes the jobs that are no longer needed for the next day from the environment
 Loads the new jobs that are needed for the next day. The jobs are loaded based on the order method
that they reside in.
 Downloads the environment to Control-M/Enterprise manager.
After the New Day process is complete the Control-M/Server resumes processing.
Since the Control-M/Server processes shut down and no new processes take place during New day, it is
more efficient to have the New Day process utilize a mechanism called User Daily jobs. Instead of directly
scheduling production jobs, the New Day process can schedule User Daily jobs, and those User Daily jobs
can schedule the production jobs. A User Daily job executes the ctmudly utility and passes a User Daily
value to it. The utility orders all folders associated with a specific User Daily name.
The ctmorder utility performs job scheduling from a folder in the Control-M/Server database. You can
manually run this utility or define a job to run this utility. For more information, see ctmorder.
For more information on all utilities for the New Day process, see New day procedure and order methods
Control-M/Server utilities.

186
Control-M Administrator Guide

It is recommended that you define User Daily jobs to execute after New Day processing is completed to
minimize processing overload early in the day. In this case, the New Day process evaluates folders that
have automatic daily order method definitions and orders in folders that meet the scheduling criteria, and
then after New Day is completed, specific user daily order method folders are ordered in once they meet
their scheduling criteria.
To see a detailed video of the New Day process, see New day process
(https://www.youtube.com/watch?v=Fh5uOUm_ax4).
NOTE: Control-M/Server utilities that affect and modify the Active Jobs File, such as utilities that modify
running jobs, must not execute during New Day. Modifying the Active Jobs File can cause the New Day to
fail in cleaning and ordering new jobs.
NOTE: If you change the value of the Daytime system parameter, cyclic jobs in the Active environment
that are defined with a From Time value that is between the old Daytime value and the new Daytime
value, wait until the new From Time value is reached. The new From Time value is taken from the
definition of the job.

Automatic prerequisite condition cleanup

By default (the Ignore New Day Conditions system parameter is set to N), the New Day procedure cleans
up prerequisite conditions that are one year old (ODAT+1). BMC recommends that you do not modify the
value of this parameter. Changing the value of Ignore New Day Conditions to Y, so that the New Day
procedure does not clean up old conditions is useful if you have jobs that are triggered by prerequisite
jobs that ran the year before. Changing Ignore New Day Conditions to Y could greatly increase the risk
that jobs could be prematurely triggered (jobs that are waiting for a prerequisite job that runs in the
future can be triggered by a job that ran in the past).
Alternatively, you can retain prerequisite conditions for more than one year without changing the default
value of the Ignore New Day Conditions parameter. Those conditions are added to the Conditions file with
a date reference value of STAT (conditions with a STAT reference are not automatically cleaned by the
New Day procedure). However, as you can change the value of the Ignore New Day Conditions parameter
to Y, you need to identify the prefixes or masks of the conditions that should be ignored (not deleted) in
the Ignore Conditions file (dbs_ignrcond.dat). Any conditions whose prefixes or masks are not specified in
the file are treated as if you did not change the default. Therefore, if retain prerequisite conditions beyond
one year (ODAT+1), it is recommended that you provide them with a prefix not used by conditions that
should be deleted on time.
EXAMPLE:
Assume the Ignore New Day Conditions parameter is set to Y and the Ignore Conditions file contains the
following prefixes:
prq_rs_*rpt
pre_prn
srt_def_?

187
Control-M Administrator Guide

If the new Control-M working date is 15-01-16, the following table describes which prerequisite conditions
will be deleted from the Control-M/Server database by the New Day procedure:

Conditions existing before executing New Conditions remaining after executing New Day
Day Procedure Procedure

bra_fn_01 14/17 bra_fn_01 14/17

bra_fn_01 15/17

prq_rs_21rpts 14/17 prq_rs_21rpts 14/17

prq_rs_21rpts 15/17 prq_rs_21rpts 15/17

pre_prn 15/17 pre_prn 15/17

pre_prn_01 15/17

srt_def_a 15/17 srt_def_a 15/17

srt_def_a1 15/01

Control-M/Agent parameters
In the CCM, you can change the default component system parameter values of Control-M/Agent system
parameters without having to access each individual computer.
Before a modified parameter value can take effect, the component that uses the value needs to be
refreshed.
To define Control-M/Agent system parameters, see Defining Control-M/Agent system parameters (on
page 189).
Alternatively, you can run the following utilities:
 ctmag: All Agent and Application Plug-in configuration parameters
 ctmunixcfg: Application Plug-in parameters in the OS.dat file (UNIX)
 ctmwincfg: Application Plug-in parameters in the registry file (Windows)
The following topics describe the Control-M/Agent parameters:

188
Control-M Administrator Guide

 Control-M/Agent deployment parameters (on page 190)

 Account Availability parameters (on page 191)
 Agentless parameters (on page 192)
 Comm parameters (on page 196)
 Diagnostics parameters (on page 199)
 Email parameters (on page 200)
 Multitracker parameters (on page 201)
 Output parameters (on page 203)
 Security parameters (on page 204)
 Submission parameters (on page 205)
 Workload parameters (on page 209)
 Control-M application support configuration (on page 210)
 Control-M Agent services parameters (on page 212)

Defining Control-M/Agent system parameters

This procedure describes how to define Control-M/Agent system parameters in the CCM.

 To define Control-M/Agent system parameters:

1. From the Home tab, select one or more Control-M/Agent components, and in the Definitions
group, click System Parameters.
The Control-M/Agent - System Parameters dialog box appears.
NOTE: If you selected multiple Control-M/Agents, parameter changes are applied to all selected
Control-M/Agents (Control-M/Agent 6.4.01 and higher).
2. From the system parameters table, filter for the required parameter from one of the following column
headings:
• Category
• Name
• Description
• Value
• Default Value
3. Double-click the required parameter.
The Update System Parameter dialog box appears.
4. In the Value field, change the value of the parameter, as required, and then click Save.
5. Click Close.
The Control-M/Agent system parameter is defined.

189
Control-M Administrator Guide

Control-M/Agent deployment parameters

The following table describes the Control-M/Agent deployment parameters.

Parameter Description

AD_GA_RETAIN_DAYS Determines the number of days to keep the backup4restore

directory on the Control-M/Agent, which is used to downgrade to
the original version of the Control-M/Agent, after an upgrade has
occurred.
NOTE: If you do not plan to downgrade the Control-M/Agent, it is
recommended to delete the directory to save disk space.
Default: 30

AD_RETAIN_PACKAGES Determines the number of days that the installation package is

saved in the Control-M/Agent computer.
Valid Values:
 0: Never remove
 1-365
Default: 30

190
Control-M Administrator Guide

Account Availability parameters

The following table describes Control-M/Agent Account Availability parameters.

Parameter Description

AG_NOT_RESPONDING_TIME Determines the time in minutes for the main agent process to be
considered not responsive. A message is written to the daily log
file.
NOTE: Xalert messages are controlled by the
PROCESS_NOT_RESPONDING_ALERT_INTERVAL
parameter, which is influenced by
X_NOT_RESPONDING_TIME parameters.
Default: 3

AR_NOT_RESPONDING_TIME Determines the time in minutes for the agent router process to be
considered not responsive. A message is written to the daily log
file.
NOTE: Xalert messages are controlled by the
PROCESS_NOT_RESPONDING_ALERT_INTERVAL
parameter, which is influenced by
X_NOT_RESPONDING_TIME parameters.
Default: 3

AT_NOT_RESPONDING_TIME Determines the time in minutes that agent tracker process to be

considered does not responsive. A message is written to the daily
log file.
NOTE: Xalert messages are controlled by the
PROCESS_NOT_RESPONDING_ALERT_INTERVAL
parameter, which is influenced by
X_NOT_RESPONDING_TIME parameters.
Default: 3

CMACC_AV_INTERVAL Determines the interval in seconds between Account Availability

monitor operations.
Default: 3600

CMACC_UNAV_INTERVAL Determines the Interval in seconds between Account unavailability

monitor operations.
Default: 90

PROCESS_NOT_RESPONDING_A Determines the interval in minutes for the Agent to send an alert
LERT_INTERVAL when a process does not respond.
Default: 60

191
Control-M Administrator Guide

Agentless parameters
The following table describes Control-M/Agent Agentless parameters.

Parameter Description

RJX_CONN_MODE The SSH connection mode used in Agentless jobs.

(SSH Connection Mode) Valid values:
 0 - The agent uses only the SSH protocol to upload and
download files and to submit the job to the remote computer.
 1 - The agent uses both SFTP and SSH protocols. Only one
connection is opened during job execution.
 2 - The agent used both SFTP and SSH protocols. Two
connections are opened at the beginning of the job, but after
a while the SSH connection is closed.
Default: 2
Modifiable by ctmwincfg: No
Modifiable by ctmunixcfg: No

RJX_CONN_TRY Maximum number of attempts to be made to restore the

connection.
(AgentLess Connection
Retries) Valid values: Integer
Default: 15
Modifiable by ctmwincfg: No
Modifiable by ctmunixcfg: No

RJX_CONN_TOUT Time interval, in seconds, between attempts to restore the

connection.
(Time Interval between
Restore Connections) Valid values: Integer
Default: 120 seconds
Modifiable by ctmwincfg: No
Modifiable by ctmunixcfg: No

RJX_COPY_OUTPUT_REMOT Determines where the OUTPUT handling operations are performed

E on the remote host.
Valid values: Y, N
Default: N

192
Control-M Administrator Guide

Parameter Description

RJX_DETAILS_TO_OUTPUT Determines whether to include details related to the remote

connection in the job OUTPUT of jobs executed on a remote host.
(Print Details to OUTPUT)
Valid values: Y, N
Default: Y
Modifiable by ctmwincfg: No
Modifiable by ctmunixcfg: No

RJX_DOWNLOAD_OUTPUT Determines whether the post processing actions of move, copy, or

delete of the job OUTPUTs is performed from the remote host.
(Download Output from
Remote Host when job ends) Valid values: Y, N
Default: N

RJX_KEEP_OUTPUT Determines if the OUTPUT file is deleted from remote host

computers.
Valid values: Y, N
Default: N

RJX_OUTPUT_DIR A directory to store temporary files.

(AgentLess Temporary These files are automatically removed to Control-M/Agent when
Directory) the jobs end and the network connection is available or restored.
Default: period (.), which means that the files are stored in the
user home directory of the job’s owner in the remote host.
Modifiable by ctmwincfg: No

RJX_OVMS_SETVERIFY For a Control-M/Agent submitting jobs to an OpenVMS remote

host, this parameter specifies whether or not to print commands
(Save Commands in the
in the OUTPUT of a job.
OUTPUT in OpenVMS
Remote Host) Valid values:
 Y – Implements SET VERIFY, which prints commands in the
job OUTPUT
 N – Implements SET NOVERIFY, which does not print
commands in the job OUTPUT
 E – Specifies that the verification value is taken from the
environment
Modifiable by ctmwincfg: No
Modifiable by ctmunixcfg: No

193
Control-M Administrator Guide

Parameter Description

RJX_POOL_CONNECTION_LI Specifies how many jobs can make use of a single connection. The
MIT connections are monitored and unused ones (connections with
ended jobs) are released.
Valid values: 1 - 50. When set to 1, the Agent works as it does
for Control-M/Agent 6.4.01.
Default: 10

RJX_POOL_SLEEP_TIME The interval needed for a thread to monitor the connections and
release unused ones.
Valid values: 1 - 30 minutes
Default: 10 minutes

RJX_POOL_KEEP_UNUSED Sets the amount of time, in minutes, to check the status of open
connections.
Valid values: 1 - 30 minutes
Default: 10 minutes

SSH_VER_CMD SSH command to verify platform version.

Valid values: A valid command.
Default: cmd.exe /c ver
Modifiable by ctmwincfg: No

WMI_TCP_ONLY_PING Determines whether the WMI remote host availability will be

checked by TCP ping only (Y) or by checked both WMI and TCP
(N).
Valid values: Y, N
Default: N

WMI_WAIT_TIME_OUT Set the time to wait for WMI events.

Valid values: Positive integer (milliseconds)
Default: 50000 (milliseconds)

RJX_CLEAN_ENV Determines deleting of temporary files on remote host after job

execution.
Valid values: Y, N
Default: Y

194
Control-M Administrator Guide

Parameter Description

RJX_FORCE_OS_CHECKING Determines whether to check for the remote host platform for
every job.
Valid values: Y, N
Default: N

RJX_LIFE_CHK_INTERVAL The interval in seconds for job completion monitoring (SSH).

Valid values: 1-86400 seconds
Default: 30 seconds

RJX_MULTIPLE_HOST Determines whether to allow multiple remote hosts keys (for

clusters)
Valid values: Y, N
Default: N

RJX_OVMS_DEFAULT_QUEU Determines the default queue for OpenVMS Remote Host

E
Valid values: Y, N
Default: sys$batch

RJX_SSH_CLOSE_TOUT Determines the SSH connection timeout for job monitoring (Mode
2).
Valid values: 1 - 86400 seconds
Default: 300 seconds

RJX_SSH_RETRIES Determines the number of retries when communicating via the

SSH-courier.
Valid values: 1 - 1000
Default: 10

WMI_REMOTE_SHARED_NA Specifies the shared directory name used by the Agent for WMI
ME jobs.
Valid values: SYSOUT
Default: SYSOUT

195
Control-M Administrator Guide

Comm parameters
The following table describes Control-M/Agent Comm parameters.

Parameter Description

ALLOW_COMM_INIT Determines if the agent can open a connection to the server when
working in persistent connection mode.
(Allow Comm Init)
Valid values:
 Y: On
 N: Off
 A: Automatically connects to Control-M/Server in persistent
connection mode
Default: Y

ATCMNDATA <Port number>/<Timeout> for the Agent-to-Server port.

(Agent-to-Server Port Port number specifies the Server computer port that receives data
Number) from the agent computer. 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 Timeout value is the
COMTIMOUT communication job-tracking timeout in seconds.
Mandatory. Example: 7005/30. Note: Increasing the Timeout
value reduces agent performance.
Valid values: Between 1024 and 65533 inclusive
Default: 7005

AUTHORIZED_CTM_IP Defines the authorized Control-M/Server IP address.

CTMPERMHOSTS <one or more TCP/IP addresses or DNS names separated by |>.

Each value identifies an authorized Control-M/Server host where a
(Authorized
backup Control-M/Server is installed. Specify this parameter if one
Control-M/Server Hosts)
or more Control-M/Servers have been designated as backups and
can connect to this agent in case of failover. For information about
backup server configuration, see the Control-M Administration.
Mandatory. At least one primary host name should be specified.
Example:
192.138.28.121|aristo.isr.bmc.com/mybksys1|192.138.2
8.123

CTMS_ADDR_MODE {IP}
(CTMS Address Mode) If this parameter is set to IP, the IP address instead of the host
name is saved in CTMS_HOSTNAME. Use this parameter when
Control-M runs on a computer with more than one network card.

196
Control-M Administrator Guide

Parameter Description

CTMSHOST Control-M/Server host name. Name of the primary host running

Control-M/Server.
(Primary Control-M/Server
Host)

EVENT_TIMEOUT Job Tracking Timeout. Tracker event timeout in seconds.

(Tracker Polling Interval) Valid values: 1-86400
Default: 120 (UNIX) 60 (Windows)

LISTEN_INTERFACE The 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
(Listen to Network
opened in the other interfaces.
Interface)
Default: *ANY (the agent is listening on all available interfaces)

LOGICAL_AGENT_NAME Logical name of the agent. The value specified should match the
name the agent is defined by in Control-M/Server. The logical
(Logical Agent Name)
name is used only when the agent initiates the communication to
Control-M/Server.
Replies and job status updates are sent by the agent using the
name the Control-M/Server used to contact the agent. This allows
the server to use several aliases for the same agent.
Default: Agent host name
However, it can differ when either a cluster installation or the
agent host name has aliases.

PROTOCOL_VERSION Server-Agent communication protocol version.

(Protocol version) Valid values: 12 or lower.
Default: 12
NOTE: For HP-UX-ia64, Control-M supports protocol versions
7-11. Default: 11.

RU_COMM_PORT Defines the Remote Utilities port number.

Default: 8000

TCP_IP_TIMEOUT The COMTIMOUT communication job-tracking timeout in

seconds.
(TCP/IP Timeout)
When the value of ‘TCP/IP timeout’ is changed, using the
configuration utility or CCM, the timeout part of the AGCMNDATA
and ATCMNDATA parameters are changed.
Valid values: a number in the range 0-999999
Default: 120

197
Control-M Administrator Guide

Parameter Description

TRACKER_EVENT_PORT Number of the port for sending messages to the Tracker process
when jobs end.
(Tracker Event Port)
Valid values: 1025-65535

UPLOAD_REMOTE_UTILS Uploads agent utilities to remote hosts.

Valid Values:
 Disable: No support for remote utilities
 Once: Uploads the files once unless it changed (ongoing
mode)
 Always: Uploads the files before each job (zero footprint
mode)
Default: Disable

UTTIMEOUT Maximum time (in seconds) the agent waits after sending a
request to Control-M/Server. This timeout interval should be
(Timeout for Agent utilities)
longer than the TCP/IP Timeout.
Default: 120 (UNIX) 600 (Windows)

198
Control-M Administrator Guide

Diagnostics parameters
The following table describes Control-M/Agent Diagnostic parameters.

Parameter Description

AG_LOG_ON Indicates if the ctmag_<year><month><day>.log file is

generated (Y) or not (N).
(Daily Log File Enabled)
Valid values: Y, N
Default: Y

BUFFERED_DBGLVL Defines the First Failure Data Capture diagnostic level.

Default: 5

DGB_RESET_INTERVAL Defines the First Failure Data Capture reset interval in seconds.
Default: 600

GENERAL_CLEANUP_INTERV Determines the number of days to wait before STATUS, PROCID,

AL ONSTMT, RUNTIME and non-root files are deleted from the
<Control-M/Agent_home> directory after an Agent or host
malfunction occurred.

LIMIT_LOG_FILE_SIZE Maximum size (MB) of diagnostic log files for a process or a

thread.
(Maximum size of log file
MB) Valid values: 1 - 1000
NOTE: Restart the agent for the parameter to take effect.
Default: 10

LIMIT_LOG_VERSIONS Number of generations of diagnostic log information to keep for a

process or a thread.
(Number of log file versions)
Valid values: 0 - 99
NOTE: Restart the agent for the parameter to take effect.
Default: 10

LOGKEEPDAYS Number of days to retain agent proclog files. After this period,
agent proclog files are deleted by the New Day procedure.
(Days To Retain Log Files)
Valid values: 1-99
Default: 1

ONSTMT_BUFFERED_DBGLV Defines the First Failure Data Capture diagnostic level for ON
L Statement processing.
Default: 1

199
Control-M Administrator Guide

Parameter Description

MEASURE_USAGE_DAYS Determines the number of days to retain the files in the dailylog
directory. These files contain the information about jobs that is
(Days To Retain Daily Log
used to calculate the metrics for the usage measurement report.
Files)
Valid values: 1-99
Default: 7 days

RH_KEEPDAYS Determines the number of days to retain the files in the

DATA\rhdetails directory. These files contain the CPU
(Days To Retain Host
specifications for agent, remote hosts and application plug-in
Specification Files)
server hosts.
Valid values: 1-99

Email parameters
The following table describes Control-M/Agent Email parameters.

Parameter Description

SMTP_PORT_NUMBER The port number on which the SMTP server communicates.

(Port Number) Valid values: 0-65535
Default: 25
Modifiable by ctmwincfg: Yes
Modifiable by ctmunixcfg: Yes

SMTP_REPLY_TO_EMAIL The e-mail address to which to send replies. If this field is left
empty, the sender e-mail address is used.
(Reply-To Email)
Modifiable by ctmwincfg: Yes
Modifiable by ctmunixcfg: Yes

SMTP_SENDER_EMAIL The e-mail address of the sender.

(Sender Email) Valid values: Text up to 99 characters
Default: control@m
Modifiable by ctmwincfg: Yes
Modifiable by ctmunixcfg: Yes

200
Control-M Administrator Guide

Parameter Description

SMTP_SENDER_FRIENDLY_ The name or alias that appears on the e-mail sent.

NAME
Modifiable by ctmwincfg: Yes
(Sender Friendly Name)
Modifiable by ctmunixcfg: Yes

SMTP_SERVER_NAME The name of the SMTP server.

(SMTP Server (Relay) Name) Modifiable by ctmwincfg: Yes
Modifiable by ctmunixcfg: Yes

Multitracker parameters
The following parameters describe Control-M/Agent Multitracker parameters.

Parameter Description

MULTITRACK_ENABLED Enables Multiple Parallel Trackers

Valid values: Y|N
Default: Y
NOTE: In the previous versions it was one tracker process. If
MULTITRACK_ENABLED=Y, multiple parallel trackers/processes
enabled.

MULTITRACK_MAX_PROC Determines the maximum number of tracker-workers that can run

in parallel, in a normal situation of the tracker, that is, when there
is no starvation. Starvation might occur either by a job that causes
repeated tracker-worker crashes, or by a job that causes a
tracker-worker to hang.
Valid values: 1-100
Default: 10

201
Control-M Administrator Guide

Parameter Description

MULTITRACK_SKIP_INTERV Determines the amount of time (in seconds) when a job is said to
AL be tracker recently.
To avoid situations where a job is tracked by more than one
tracker-worker in a short period of time, define a time
interval, MULTITRACK_SKIP_INTERVAL, where a job is skipped by
tracker-workers. Before a tracker-worker tracks a job, it checks if
that job has recently been tracked, and if it is, the tracker-worker
does not track it.
Valid values: 1-60
Default: 15

MULTITRACK_JOBS_PER_W Determines the optimal ratio between the number of jobs and the
ORKER number of tracker-workers. In a normal situation, the tracker
spawns new tracker-workers if the number of jobs divided by the
number of running tracker-workers (actual ratio) is more than this
optimal ratio. It shuts down tracker-workers if the actual ratio is
less than the optimal ratio.
Valid values: 5-300
Default: 30

MULTITRACK_LATE_PERIOD Determines the amount of time (in seconds) a job may wait to be
tracked before declared as starved.
Valid values: 30-300
Default: 120

MULTITRACK_MAIN_EVENT The main tracker works in iterations. In each iteration it first waits
_TIMEOUT for events that might be sent from completed jobs and track these
jobs, and then searches for completed jobs that do not send
events, and tracks them.
This parameter determines the amount of time (in seconds) the
main tracker process waits for events. Tracker-workers work in
the same manner, but still use the EVENT_TIMEOUT (tracker
polling interval) for the time they wait for events.
Valid values: 10-240
Default: 30

202
Control-M Administrator Guide

Output parameters
The following table describes Control-M/Agent Output parameters.

Parameter Description

DFTPRT Default printer for job Output files. Type a printer name in the
field box or select a name from the list box.
(Default Printer)
Valid values: Text
Default: Blank
Modifiable by ctmwincfg: Yes
Modifiable by ctmunixcfg: Yes

JOB_STATISTIC Flag that indicates how to manage job object processing statistics.
(Add Job Object statistics to Valid values:
Output)
 Y – Statistics are added to the end of the OUTPUT file.
 N – Statistics are not added to the OUTPUT file.
Default: Y
Modifiable by ctmwincfg: Yes

OUTPUT_NAME Determines the prefix for the OUTPUT file name.

(Output 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.
Default: MEMNAME
Modifiable by ctmwincfg: Yes
Modifiable by ctmunixcfg: Yes

OUTPUT_LIMIT_SIZE_END Determines the size in KB to display from the end of the job
output file.
Default: 0

OUTPUT_LIMIT_SIZE_STAR Determines the size in KB to display from the start of the job
T output file.
Default: 0

203
Control-M Administrator Guide

Security parameters
The following table describes Control-M/Agent Security parameters.

Parameter Description

DOMAIN The domain is determined by the value of this parameter if

<domain> is not specified in <domain>\<username> in the
(Logon Domain)
Run_As parameter of the job definition. If the domain is not
specified in the Run_As parameter or this parameter, the user
profile is searched in the trusted domains.
NOTE: BMC recommends that you do not specify a value for
Logon Domain.
Valid values: Text
Default: Blank
Modifiable by ctmwincfg: Yes

LOGON_AS_USER Flag that specifies which user account is used for the services to
log on to.
(Logon As 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: Not selected
Modifiable by ctmwincfg: Yes

204
Control-M Administrator Guide

Submission parameters
The following table describes Control-M/Agent Submission parameters.

Parameter Description

APPLICATION_LOCALE Determines the CJK encoding used by Control-M/Agent to run

jobs. For more information, see Control-M Language
(CJK Encoding)
Customization.
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
Modifiable by ctmwincfg: Yes
Modifiable by ctmunixcfg: Yes

CTM_PARM_ENC Character used to enclose job processing parameters passed to

jobs by Control-M/Server. Any character or string can be specified.
A blank space (in single or double quotes) is valid.
Valid values: Any character or string can be specified. A blank
space (in single or double quotes) is also valid.
Default: Double quotes
Modifiable by ctmunixcfg: No

ECHO_OUTPUT Specifies whether to print commands in the OUTPUT of a job.

(Echo Job Commands into Valid values:
Output)
 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
Modifiable by ctmwincfg: Yes

I18N Determines Control-M mode of support for foreign languages.

(Foreign Language Support) Valid values: Latin-1, CJK
Default: Latin-1

205
Control-M Administrator Guide

Parameter Description

JOB_WAIT Flag that specifies if procedures invoked by a job can be run

outside the Job Object. If so, this prevents a situation in which the
(Job children inside job
original job remains in executing mode until the invoked
object)
procedure completes.
Valid values:
 N – All procedures invoked by the job are run outside the job
object.
 Y – All procedures invoked by the job are run inside the job
object.
Default: Y
Modifiable by ctmwincfg: Yes

OUTPUT_MODE Octal value indicating file access mode of the OUTPUT file. 777
indicates the highest level of access.
Valid values: Valid values are 600 640 644 660 664 666
Default: 600
Modifiable by ctmunixcfg: No

OUTPUT_MODE_AS_USER Octal value indicating file access mode of the OUTPUT file for
non-root mode when the job owner is not the agent owner. 777
indicates the highest level of access.
Valid values: 660 664 666
Default: 660
Modifiable by ctmunixcfg: No

ONSTMT_CASE_SENSITIVE Determines whether the output is case sensitive for on statement

processing.
Default: Y

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.
(Run 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
Modifiable by ctmwincfg: Yes

206
Control-M Administrator Guide

Parameter Description

USE_JOB_VARIABLES Flag that indicates whether all variables will be set as environment
variables in the script.
(Convert Job Variables to
Environment variables) Valid values: Y (yes), N (no)
Default: Y

WRAP_PARAM_QUOTES Indication of how parameter values (%%PARMn....%%PARMx)

are managed by Control-M/Agent for Microsoft Windows.
(Wrap parameters with
double quotes) 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. This option is compatible with the way
that these parameters were managed in version 6.0.0x, or
6.1.01 with Fix Pack 1, 2, 3, or 4 installed. 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. This option is
compatible with the way that parameters were managed by
version 2.24.0x.
Default: 2
Modifiable by ctmwincfg: Yes

CODE_PAGE Determines the Code Page for job processing in Latin-1 mode
Values: 1252
Default: 1252

DELETE_BACKUP_FILES Determines if backup files should be deleted when the job output
file is moved or deleted.
Valid values: Y, N
Default: N

DISABLE_CM_ONSTMT If set to Y, then the ON statement is processed by the Agent

Tracker. If set to N, it's processed by Agent Monitor process.
Valid values: Y, N
Default: N

207
Control-M Administrator Guide

Parameter Description

ENABLE_RECOVERY Determines whether to enable jobs recovery when the agent

monitoring process terminates unexpectedly.
Valid values: Y, N
Default: Y

KILL_EXIT_CODE Defines the exit code to kill jobs.

Valid values: 1-9999
Default: N/A

MIN_FREE_SPACE Defines the minimum free disk space in MB required for job
submission.
Valid values: 1-100000
Default: 50

MIN_FREE_SPACE_WARN Defines the free disk space threshold in MB before sending agent
alerts.
Valid values: 1-100000
Default: 100

SLEEP_COUNT Defines the number of retries before checking the disk space.
Valid values: 1-120
Default: 5

UTIL_REAL_EXIT_CODE Determines whether to return the actual exit code from agent
utiliities.
Valid values: Y, N
Default: N

208
Control-M Administrator Guide

Workload parameters
The following table describes Control-M/Agent Workload parameters.

Parameter Description

WKL_CPU_SAMPLE_INTERV Interval in seconds between CPU samples, for calculating a single

AL average CPU usage.
(Interval between CPU Valid values: 5-60 (seconds)
samples (sec))
Default: 5 (seconds)

WKL_CPU_SAMPLE_NUM Number of CPU samples for calculating a single average CPU

usage.
(Number of CPU samples for
average CPU usage) Valid values: 3-60 samples
Default: 3 samples

WKL_HB_INTERVAL Periodic Heart Beat interval in minutes, after which CPU usage is
reported to Control-M/Server, regardless of actual need to report
(Interval between CPU
it.
usage sync updates (min))
Valid values: 1-180 (minutes)
Default: 15 (minutes)

WKL_SLEEP_INTERVAL Sleep interval in seconds between successive CPU monitor

operations.
(Interval between CPU
monitor operations (sec)) Valid values: 15-3600 (seconds)
Default: 30 (seconds)

209
Control-M Administrator Guide

Control-M application support configuration

The application support configuration parameters in the following table can be modified by using the
ctmwincfg utility. These parameters are used by the application support for Windows.

Parameter Description

Add Job Object Flag that indicates how to handle job object processing statistics.
Statistics to
Output
 Selected – Statistics are added to the end of the OUTPUT file. Default.
 Not selected – Statistics are not added to the OUTPUT file.

Connect only Flag that indicates whether CONTROL-M/Agent should maintain its connection to the
once to CM DLL application between events. Values: Y, N. Default: N.

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

Domain Name of server managing access to resources and the database. Specify the name of
Controller the server in the field box. Default: Blank

E-mail User Password for the e-mail user account. This parameter can only be changed after
Password completing the installation.

E-mail User User e-mail account which the Agent uses to send e-mail. This parameter can only be
Account Profile changed after completing the installation.

Job children Flag that specifies if procedures invoked by a job can be run outside the Job Object. If
inside job object so, this prevents a situation in which the original job remains in executing mode until
the invoked procedure completes.
Valid values:
 N – All procedures invoked by the job are run outside the job object.
 Y – All procedures invoked by the job are run inside the job object. Default.

Logon As User Flag that specifies which user account is used for the services to log on to.
Valid values:
 Selected – Jobs are submitted with the permissions and environment variables of
the specified user.
 Not selected – Jobs are submitted with the permissions and environment
variables of the local system account. Default.

210
Control-M Administrator Guide

Parameter Description

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. If the
domain is not specified in the Run_As parameter or this parameter, the user profile is
searched in the trusted domains.
NOTE: BMC recommends that you do not specify a value for Logon Domain.

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.

Run user ’Logon Indication if a user-defined logon script should be run by the CONTROL-M/Agent
Script’ 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.

Wrap parameters Indication of how parameter values (%%PARMn....%%PARMx) are handled in by

with double CONTROL-M/Agent for Microsoft Windows.
quotes
Valid values:
 1 – If a parameter value contains a blank, it is passed to the operating system
enclosed in double quotes. If no blank is in the parameter value, no quotes are
included.
 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. This option is compatible with the way
that these parameters were handled in version 6.0.0x, or 6.1.01 with Fix Pack 1,
2, 3, or 4 installed. In this case, if a parameter value contains a blank, the
operating system may consider each string as a separate parameter.
 3 – All parameters are passed to the operating system enclosed in double-quotes.
This causes the operating system to treat all parameter values as strings (not
numbers). This option is compatible with the way that parameters were handled
by version 6.1.01 with no Fix Pack installed.
 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. This option is compatible with the way that parameters were handled by
version 2.24.0x.

211
Control-M Administrator Guide

Control-M Agent services parameters

The following table lists parameters that affect the operation of the following Control-M/Agent services:
 Agent service
 FileWatcher service

Parameter Description

Log on as User account under which Control-M Agent service will run.
Valid values:
 Local System Account – Service logs on as the system account.
 Allow Service to Interact with Desktop – This option is valid only if the
service is running as a local system account.
Selected – the service provides a user interface on a desktop that can be used
by whoever is logged in when the service is started. Default.
Unselected – the service does not provide a user interface.
 This Account – User account under which Control-M Agent service will run.
NOTE: If the owner of any Control-M/Server jobs has a "roaming profile" or if
job output (OUTPUT) will be copied to or from other computers, the Log in
mode must be set to This Account.
Default: Local System Account

Startup Type How to install Control-M/Agent service.

Valid values:
 Automatic – Service should start when the system starts.
 Manual – User or a dependent service can start service.
 Disabled – User or a dependent service cannot start service.
Default: Automatic

212
Control-M Administrator Guide

OS parameters
The following table describes OS parameters.

Parameter Description

USE_JCL_AGENT_OWNER Determines whether the Control-M/Agent owner is used to access

the View Documentation function.
(UNIX/Linux only)
Valid values:
 Y: Enabled
 N: Disabled
Default: N

SU_LOAD_PAM_SESSION Determines whether to load other user limits.

(Linux only) Valid values:
 Y: Enabled
 N: Disabled
Default: N
NOTE:
 You need to define this parameter in the OS.dat file.
 You must rerun the set_agent_mode utility and enable
non-root mode.

OUTPUT_HANDLING_BY_USER Determines whether Output Handling of a job action is performed

by the Run as User of a job or by the Windows service account.
(Windows only)
Valid values:
 Y: Performed by Run as User
 N: Performed by Windows service account
Default: N

Defining Control-M for z/OS system parameters

This procedure describes how to define Control-M for z/OS system parameters in the CCM.
 To define Control-M for z/OS system parameters:
1. From the Components Tree pane, select the Control-M for z/OS component and from the Home
tab, in the Definitions group, click System Parameters.
The Control-M for z/OS - System Parameters dialog box appears.

213
Control-M Administrator Guide

2. From the Control-M Name drop-down list, select the computer where the Control-M for z/OS is
installed.
3. From the system parameters table, filter for the required parameter from one of the following column
headings:
• Type
• Category
• Name
• Value
• Default Value
• Description
• Refresh Type
4. Double-click the required parameter.
The Update System Parameter dialog box appears.
5. In the Value field, change the value of the parameter, as required, and then click Save.
6. Click Activate Changes.
The Control-M for z/OS system parameter is defined.

Connecting to Control-M/EM behind a firewall

This procedure describes how to connect to a Control-M/EM server behind a firewall by configuring ports
in the orbconfigure utility.
 To connect to Control-M/EM behind a firewall:
1. Open the orbconfigure utility.
2. From the Setup Listen Ports drop-down list, select Range.
3. In the Range of ports to use fields, define a range with at least 24 ports.
Valid ports are between 1024 and 65535.
NOTE: The port range cannot include the Naming Service port or the Web Server port.
4. Click Next.
5. Verify that the information is correct and click Next.
6. Click Finish.
The port settings are defined for the GUI, GSR, GSA, CMS, CLI , and Sweep, BIM, Forecast,and Self
Service are defined if they are installed.
7. Recycle all Control-M/EM components.

214
Control-M Administrator Guide

Configuring Control-M/EM server with High-Availability or

Control-M/EM Distributed behind a firewall
This procedure describes how to configure Control-M/EM server components with High Availability or with
a Control-M/EM Distributed on Control-M Workload Archiving behind a firewall.
Before you begin
 Complete Connecting to Control-M/EM behind a firewall (on page 214) on the primary, secondary,
and distributed hosts and verify that the port range is the same for all.
 To configure Control-M/EM server with High Availability and Control-M/EM
Distributed behind a firewall:
1. Verify that all Control-M/EM server components are not running on any Control-M/EM environment.
2. Navigate to the HostPort parameter, as described in Defining Control-M/EM system parameters (on
page 45).
If there are additional HostPort parameters defined for each component, delete the additional
HostPort parameters. In the original HostPort parameter, click Restore Default.

3. Select the HostPort parameter and click .

A New System Parameter dialog box appears.
4. Set the Value field to :<port1>-<port2>.
This represents the possible port range opened for Control-M/EM. 0 is not a valid port number. The
recommended minimum range is 20.
5. Click Save.

6. Select the HostPort parameter and click .

A New System Parameter dialog box appears.
7. Set the Value field to :<port3>-<port4>.
This represents the possible port range opened for Control-M/EM. 0 is not a valid port number. The
recommended minimum range is 10. If you have more than five Control-M/Servers, then the
minimum port range must be at least double the amount of Control-M/Servers.
8. From the Type drop-down list, select Gateway.
9. Click Save.
10. To configure the Kafka server component behind a firewall, you need to configure the Kafka server
ports, as described in Connecting to an Apache Kafka server behind a firewall (on page 216).
11. Start Control-M/EM server components on all Control-M/EM environments.
NOTE: The defined port ranges must not overlap each other and cannot contain the Web Server and
Naming Service ports. The Web Server and Naming Service ports must be open in the Firewall
settings.

215
Control-M Administrator Guide

Connecting to Control-M/EM behind a firewall from

Control-M clients
This procedure describes how to connect to Control-M/EM behind a firewall from Control-M clients.
 To connect:
1. From a Control-M/EM server computer, open a command line and type the following:
emweb_status
The following appears:
web server is running [ host:port/ ]
2. In your firewall definition, verify that this specific port is open.
NOTE: To use the Client Distribution (on page 350) feature and access the Help, the Control-M client
version 9.0.18 and higher must be installed to communicate with Control-M Web Server. The port is
configured in the ./etc/emweb/tomcat/conf/server.xml file.

Connecting to an Apache Kafka server behind a firewall

This procedure describes how to connect to an Apache Kafka server behind a firewall by configuring
ports. The firewall configuration is required to enable the Services Configuration Agent (SCA) in each
Control-M/EM distributed instance to have access to all distributed instances of Kafka.
You need to perform this procedure after you have configured the other Control-M/EM server components
behind a firewall, as described in Configuring Control-M/EM server with High-Availability or Control-M/EM
Distributed behind a firewall (on page 215).
 To connect to an Apache Kafka server:
 From a command line, define the Apache Kafka port by running one of the following:
• UNIX: em -no_wrap cha -set_field_val KAFKA_PORT <port>
• Windows: emcha -set_field_val KAFKA_PORT <port>

Defining Daylight Savings Time support

This procedure describes how to define Daylight Savings Time (DST) support from the TimeZone.dat file.
You only need to do this procedure if the Control-M/Server resides in a location where DST is used.
 To define Daylight Savings Time support:
1. Navigate to the following directories, and complete this procedure for each TimeZone.dat file:
• <ctm_server_home>/data
• *<*em_home>/ctm_em/data/
The standard format for the definition is timeZone (GMT±hh:mm), where timeZone represents
the time zone label.

216
Control-M Administrator Guide

EXAMPLE: The label EST represents the Eastern Standard time zone, and the regularly formatted
entry for the Eastern Standard Time time is EST GMT -05:00.
2. Change the relevant time zone definition so that it includes DST adjustments., as follows:
timeZone (GMT±hh:mm) FROM dd.mm hh:mm TO dd.mm hh:mm (GMT±hh:mm)
Where::
• timeZone (GMT±hh:mm) indicates the regular time zone value (for example, CET
(GMT+02:00) )
• FROM and TO values indicate the time frame during which DST is in effect. (For example, FROM
01.03 01:59 TO 24.10 02:00)
• The second GMT value indicates the DST time-offset relative to GMT (for
example,(GMT+03:00))
NOTE:
 This syntax is reversed for the southern hemisphere. The FROM and TO keywords specify the
start and end settings for daylight saving to take effect.
 There must be an empty line at the end of the file.
EXAMPLE: Bill needs to create a new time zone label for Japan, where the time is nine hours later
than Greenwich Mean Time (GMT). DST begins March 1 at 01:59 and ends October 24 at
02:00. Bill uses the following entry to create the new label (JST):
JST (GMT+09:00) FROM 01.03 01:59 TO 24.10 02:00 (GMT+10:00)
EXAMPLE: Although time zone definitions in the northern hemisphere are set to summer Daylight
Saving Time, definitions in the southern hemisphere are set to winter. In Sydney,
Australia, winter time (GMT+09:00) is from March 25 at 03:00 until October 1 at 02:00.
All other dates are GMT+10:00 (summer time). The time label for Sydney is defined as
follows:
SYD (GMT+11:00) FROM 25.03 03:00 TO 01.10. 02:00 (GMT+10:00)
NOTE: If a relevant time zone contains several countries, some observe DST and some do not (or if
they change the clock on different days) add additional time zone definitions to cover the variations.
3. Update the relevant job processing definitions, using the appropriate variations.
NOTE: If you delete a time zone from TimeZone.dat or modify a three-character name in that file,
change any job processing definitions that specify that time zone. Otherwise, those job processing
definitions are invalid.

Daylight Savings Time considerations (Spring)

The following examples assume that the clock is moved ahead at 02:00 A.M. (02:00 A.M. becomes 03:00
A.M.). If the computer is capable of changing the clock without restarting the system, do not bring down
Control-M when the clock is being advanced.

217
Control-M Administrator Guide

NOTE: If your data center includes multiple time zones, you may need to adjust the time zone
configuration file to reflect the different offsets that result from a switch to or from daylight saving time.
This adjustment is especially important because the switch to daylight saving time is often not made on
the same date in each time zone.
New Day procedure
 If the New Day procedure starts before you reset the clock, the New Day procedure will start working
before the clock is advanced, and will continue normally (even if the clock is advanced while the New
Day procedure is in process).
 If the New Day procedure is scheduled to begin at exactly 02:00 A.M., the same considerations apply.
It is possible that the New Day procedure will start execution before the clock is manually changed.
Otherwise, changing the clock will initiate New Day processing.
 If the New Day procedure is scheduled to begin between 02:00 A.M. and 03:00 A.M., after the
computer clock is advanced, Control-M will start the normal New Day processing.
 If the New Day procedure is scheduled to begin after 03:00 A.M., no action is required. Control-M will
start the standard New Day procedure.
Time-dependent shout messages
 Shout messages that are scheduled before 02:00 A.M. do not require any action.
 Shout messages that are scheduled between 02:00 A.M. and 03:00 A.M. will be issued, even though
there may not be a delay in production because the time frame for production is smaller.
 The above information also applies to jobs that have Shout messages scheduled at a later time (for
example, 06:00 A.M.). These jobs might be considered late because of the tighter production time
frame.
Time-dependent schedules
 FROM UNTIL: Jobs whose scheduled time overlaps the time gap created by the clock shift may need
manual intervention. For example, it is possible that a job with a FROM value of 02:15 A.M. and an
UNTIL value of 02:45 A.M. might not be submitted at all. These jobs should be manually adjusted.
 Cyclic Jobs or Cyclic SMART folder: The next run of cyclic jobs with an interval of more than one
hour runs one hour sooner than it was scheduled. Cyclic jobs with an interval of less than one hour
run immediately. A cyclic job may have to be deleted and then resubmitted to continue the processing
cycle during the current day.
Control-M/Server log file:The Control-M/Server log file will not contain entries with timestamps
between 02:00 A.M. and 03:00 A.M. Any scripts or programs that rely on log entry time should be
checked for possible discrepancies as a result of advancing the clock.

Daylight Savings Time considerations (Winter)

The following examples assume that the clock is moved back at 02:00 A.M. (02:00 A.M. becomes 01:00
A.M.):

218
Control-M Administrator Guide

New Day procedure

 If the New Day procedure starts before 01:00 A.M., no special action should be taken. The New Day
procedure will run only once (between 00:00 and 00:59).
 If the New Day procedure starts exactly at 01:00 A.M., computer time should not be turned back to
01:00 A.M. to avoid another New Day process. A second New Day procedure requires manual
intervention. It is advisable to wait until 02:01 A.M., for example, and turn the clock back to 01:01
A.M.
 If the New Day procedure is scheduled to begin between 01:00 A.M. and 02:00 A.M., do one of the
following actions:
• Wait at least a full hour after the daily run, and then turn the clock back as needed; the New Day
procedure will have ended.
• Update the clock before New Day processing begins.
EXAMPLE: If the New Day time is 01:45 A.M., the clock should be moved back one hour at no later
than 01:44 A.M. If the shift was not done by 01:44 A.M., the user should wait until 02:46
A.M. and then shift the time back.
 If the New Day procedure is scheduled to begin after 02:00 A.M., no special action should be taken.
Time-dependent shout messages:Shout messages scheduled between 01:00 A.M. and 02:00 A.M.
might be issued twice.
Time-dependent schedules
 FROM UNTIL: No special action should be taken for jobs with FROM-UNTIL or cyclic schedules. Jobs
scheduled to start between 01:00 A.M. and 02:00 A.M. will start at the first occurrence of the hour
(provided that other conditions, such as input conditions and resources are met). However, they can
be restarted after the clock is moved back.
 Cyclic Jobs or Cyclic SMART Folder:The next run of cyclic jobs run one hour later than it was
scheduled.
Control-M/Server log file:The Control-M/Server log file might contain entries with times earlier than
previous entries, due to the time shift. The same considerations that apply to advancing the clock
forward, should be applied to moving the clock backwards.

Control-M Automation API configuration

Control-M Automation API consists of the following components:
 Developer Kit: Contains REST API, CLI, and sample code. For more information, see Control-M
Automation API Getting Started Guide
https://docs.bmc.com/docs/display/workloadautomation/Control-M+Automation+API+-+Getting+Star
ted+Guide.
 Control-M Automation API server
The Control-M Automation API server is a Control-M/EM component that exposes Control-M REST API
over HTTPS and is managed by the Control-M Web Server. When the Web Server starts up and shuts
down, the emrestsrv process starts and stops with it. The default listening port is 8443, that is a reversed
proxy to localhost (127.0.0.1), port 48080.

219
Control-M Administrator Guide

Startup: > start_web_server

Shutdown: > stop_web_server
The following procedures describe how to configure Control-M Automation API:
 Changing the Automation API server port (on page 220)
 Limiting incoming traffic through an API gateway (on page 221)
 Limiting API connections to a specific GUI server (on page 221)
 Configuring Automation API session timeout (on page 221)
 Allowing session tokens to display in responses to API commands (on page 222)
 Configuring Control-M Web Server to HTTPS (on page 222)
 Setting annotations as optional in API commands (on page 223)
 Configuring maximum number of run IDs saved in the Control-M/EM database (on page 223)
Additional procedures related to the Provision service in the Control-M Automation API are discussed in
Control-M Automation API provisioning (on page 224).
You can apply authorizations to API services, as described in the following lists:
 API session service authorizations (on page 229)
 API Configuration and Provision services authorizations (on page 229)
 API build and deploy services authorizations (on page 232)
 API run services authorizations (on page 234)

Changing the Automation API server port

This procedure describes how to change the Automation API server port from the default 48080.
 To change the Automation API server port:
1. Run one of the following commands:
• UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config
• Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat
2. Do one of the following:
• To change the default port number, run the following command:
> automation_api_config --change_port 48081
• To change to port number 48081 or any available port above 48081, run the following command:
> automation_api_config --change_to_free_port 48081
Applying the change in configuration restarts the API process (the emrestsrv process).

220
Control-M Administrator Guide

Limiting incoming traffic through an API gateway

This procedure describes how to limit incoming traffic into the Automation API server through an API
gateway, allowing communication only from a specific port.
 To set the allowed port for incoming traffic:
1. Run one of the following commands:
• UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config
• Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat
2. Run the following command:
> automation_api_config --allowed_incoming_port <allowedPort>
where <allowedPort> is the number of the port from which incoming traffic is allowed to pass
through the API gateway to the Automation API Server.
Supported values range from 1025 to 65535. To allow traffic from all ports, use a value of 0 (the
default).
Applying the change in configuration redeploys the API gateway in the Tomcat web application.

Limiting API connections to a specific GUI server

This procedure describes how to limit Automation API connections to a specific Control-M/EM GUI Server.
By default, the Automation API connects with any available GUI server. You can set a specific GUI server
as the only GUI server to which the Automation API can connect.

 To limit API connections to a specific Control-M/EM GUI Server:

1. Run one of the following commands:
• UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config
• Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat
2. Do one of the following:
• To set a specific GUI server for association with the Automation API:
> automation_api_config --gui_server <server_name>
• To remove the limitation and revert to the default behavior, that is, Automation API connects to
any available GUI server:
> automation_api_config --gui_server
Applying the change in configuration restarts the API process (the emrestsrv process).

Configuring Automation API session timeout

This procedure describes how to configure the length of time that an Automation API session is allowed to
remain idle before the session token times out.
 To change the session timeout:
1. Run one of the following commands:

221
Control-M Administrator Guide

• UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config
• Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat
2. Run the following command:
> automation_api_config --token_timeout <session_token_timeout>
where <session_token_timeout> is the time in seconds until the session token expires when the
session has been idle. The default is 1800 seconds (30 minutes).
The maximum value that you can set is limited by the EM system parameter MaxUserTimeoutSec,
which has a default of 10800 seconds (3 hours).
NOTE: Due to internal processing controlled by the Sample Rate System environment variable
(EM_REFRESH_INTERVAL), timing out of the session token might be delayed by up to 10 minutes
(the default value of this environment variable).
Applying the change in configuration restarts the API process (the emrestsrv process).

Allowing session tokens to display in responses to API commands

This procedure describes how to enable the display of session tokens in URIs within responses to API
commands.
 To display session tokens in API command responses:
1. Run one of the following commands:
• UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config
• Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat
2. Run the following command:
> automation_api_config --allow_token_in_uri true
Applying the change in configuration restarts the API process (the emrestsrv process).
Note: To revert to the default display of API responses, which does not contain session tokens in
URIs, run the command with a value of false:
> automation_api_config --allow_token_in_uri false

Configuring Control-M Web Server to HTTPS

This procedure describes how to configure Control-M Web Server to HTTPS using your own signed
certificate. By default, a self-signed auto-generated certificate is used for HTTPS on port 8443. If you
have previously configured Control-M Web Server to HTTPS, your configuration and port remain the
same.
 To configure Control-M Web Server to HTTPS:
1. Navigate to <EM_HOME>\etc\emweb\tomcat\conf\server.xml.
2. Replace keystoreFile="conf\emweb_unsigned.keystore" with a reference to your own
certificate keystore, as described in Configuring Control-M/EM Web Server to work with HTTPS.

222
Control-M Administrator Guide

NOTE: You can harden the CLI by configuring the environment to disable communication using
self-signed certificates, as described in Environment Service
https://docs.bmc.com/docs/display/workloadautomation/API+Services+-+Environment+service.

Setting annotations as optional in API commands

This procedure describes how to set annotations as optional in API commands, even though annotations
have been enabled in Control-M.
Control over the requirement for annotations in API commands is useful, for example, in the following
scenario:
In earlier versions of Control-M Automation API (before support for annotations was introduced in version
9.0.19.000), you created many scripts. However, the API commands in these scripts do not specify any
annotations. You now want to upgrade to a more recent version of the Control-M Automation API, but
need more time to update your scripts and complete the migration.

 To set annotations as optional in API commands

1. From the Components Tree pane in the CCM, select the Control-M/EM component and from the
Home tab, in the Definitions group, click System Parameters.
The Control-M/EM System Parameters dialog box appears.
2. In the left pane, click Advanced.
A list of defined system parameters is displayed on the right.
3. If the list of system parameters is long, filter the list by typing aapi in the Type field in the filter row
at the top.
4. Double-click the SkipAnnotationValidation parameter.
The Control-M/EM - Update System Parameter dialog box appears.
5. In the Value field, change 0 (no skipping) to 1 (activate skipping).
6. Click Save.
Annotation is set as optional. Now, whenever an API command is run without an annotation specified,
a default annotation is used, with the subject "Automation API" and the description "Annotation was
not provided by the user."
NOTE: When you no longer want to skip annotation validation, you can change the value back to 0 in
this system parameter.

Configuring maximum number of run IDs saved in the

Control-M/EM database
This procedure describes how to configure the maximum number of run IDs from Control-M Automation
API commands that are stored in the Control-M/EM database. By default, a maximum of 2000 most recent
run IDs are saved in the Control-M/EM database, and you can raise this maximum, as necessary.
 To configure maximum number of run IDs saved in the database
1. From the Components Tree pane in the CCM, select the Control-M/EM component and from the
Home tab, in the Definitions group, click System Parameters.

223
Control-M Administrator Guide

The Control-M/EM System Parameters dialog box appears.

2. In the left pane, click Advanced.
A list of defined system parameters is displayed on the right.
3. If the list of system parameters is long, filter the list by typing aapi in the Type field in the filter row
at the top.
4. Double-click the MaxRecentRunIds parameter.
The Control-M/EM - Update System Parameter dialog box appears.
5. In the Value field, enter a new value (typically, a value higher than the default maximum of 2000 run
IDs).
6. Click Save.

Control-M Automation API provisioning

Control-M Automation API provides a Provision service for installation and setup of Control-M/Agents and
several agent plug-ins, as well as for installation of Control-M/Servers.
Provisioning of Control-M/Servers or of new Control-M/Agents is based on images, which are json files
that list the installation packages in the order that they are installed. Several default images are provided
by the API, and you can create additional custom images (for example, for a newer version of the
Control-M/Agent).
To prepare for provisioning, you must obtain the installation packages that are referenced within the
images. You can also (optionally) customize the location in which to save these packages.
The following procedures describe the preparatory tasks for enabling provisioning:
 Obtaining installation packages for provisioning (on page 224)
 Changing the location of the Provision service installation files (on page 227)
 Creating a custom image for provisioning (on page 227)
The Provision service in Control-M Automation API also enables you to upgrade an existing
Control-M/Agent, by deploying a new version of the Control-M/Agent or installing/upgrading Control-M
Managed File Transfer (MFT) or Control-M Application Pack. To prepare for this type of provisioning, see
the following procedure:
 Preparing installation packages for agent upgrades (on page 228)

Obtaining installation packages for provisioning

This procedure describes how to obtain the installation packages that are referenced from the
provisioning images.
For a list of installation packages that you must set up for the default provisioning images, see Installation
packages referenced by default images (on page 226).
You might need additional installation packages that you reference from your own custom images, as
discussed in Creating a custom image for provisioning (on page 227).

224
Control-M Administrator Guide

 To obtain installation packages for provisioning:

1. For each package that you want to download from the EPD site, perform the following steps:
a. Clickhttps://www.bmc.com/available/epd.html and follow the instructions on the EPD site until you
reach the Download Files page for the relevant product, version, and platform.
b. From the Products tab, click the relevant installation file and save it in the
<EM_HOME>/AUTO_DEPLOY directory.
NOTE: If you choose to save installation packages in a different location, ensure that you perform the
procedure described in Changing the location of the Provision service installation files (on page 227).
2. Prepare the installation package for Control-M for Advanced File Transfer (provided that you
have installed Control-M Managed File Transfer), by copying the relevant DRAFT*.zip or
DRAFT*.tar.Z file from <EM_HOME>/CM_DEPLOY to <EM_HOME>/AUTO_DEPLOY.

225
 Control-M Administrator Guide

Installation packages referenced by default images

The following table lists the installation packages that are referenced by the default provisioning images
provided in Control-M Automation API.

Table Header Table Header Table Header

DRKAI.9.0.18.100_Linux-x86_64.tar.Z Control-M/Agent 9.0.18.100 Agent_18.Linux

DRKAI.9.0.00_Linux-x86_64.tar.Z Control-M/Agent 9.0.00  Agent.Linux

 ApplicationsAgent.Linux
 BigDataAgent.Linux

PAKAI.9.0.00.100_Linux-x86_64_INSTALL Control-M/Agent 9.0.00  Agent.Linux

.BIN
Fix Pack 1  ApplicationsAgent.Linux
 BigDataAgent.Linux

DRMQL.9.0.00_Linux-x86_64.tar.Z Control-M for 9.0.00 ApplicationsAgent.Linux

Databases

DRAFT.9.0.00_Linux-x86_64.tar.Z Control-M for 9.0.00 ApplicationsAgent.Linux

Advanced File
Transfer

DRCBD.9.0.01_Linux-x86_64.tar.Z Control-M for Hadoop 9.0.01 BigDataAgent.Linux

DRCTV.9.0.18.200_Linux-x86_64.tar.Z Control-M/Server 9.0.18.200 Server.Linux

DRKAI.9.0.18.100_windows_x86_64.zip Control-M/Agent 9.0.18.100 Agent_18.Windows

DRKAI.9.0.00_windows_x86_64.zip Control-M/Agent 9.0.00  Agent.Windows

 ApplicationsAgent.Windows

PAKAI.9.0.00.100_windows_x86_64.zip Control-M/Agent 9.0.00  Agent.Windows

Fix Pack 1  ApplicationsAgent.Windows

DRMQL.9.0.00_windows_x86_64.zip Control-M for 9.0.00 ApplicationsAgent.Windows

Databases

DRAFT.9.0.00_windows_x86_64.zip Control-M for 9.0.00 ApplicationsAgent.Windows

Advanced File
Transfer

DRCTV.9.0.18.200_windows_x86_64.zip Control-M/Server 9.0.18.200 Server.Windows

226
Control-M Administrator Guide

Changing the location of the Provision service installation files

This procedure describes how to change the default location of the Provision service installation files that
are used in a fresh installation.

 To change the location of the Control-M API installation files:

1. Navigate to the following directory:
• UNIX: $HOME/ctm_em/etc/emweb/automation-api/downloads/descriptors
• Windows: <EM_HOME>\ctm_em\emweb\automation-api\downloads\descriptors
2. Open the ProvisionConfig.json file and change the ImagesLocation parameter to the new URI
location.
By default, the string is empty, which means it is set to <EM_HOME>/AUTO_DEPLOY.
EXAMPLE:
• https://somewhere.someplace.com/
• file:///home/controlm/installers

Creating a custom image for provisioning

This procedure describes how to create a custom image by copying and editing one of the provided
default images. This procedure is useful, for example, if you want to install a newer version of the
Control-M/Agent or Control-M/Server during provisioning, or if you want to install a new fix pack on top of
the base version.

 To create a custom image:

1. Navigate to the following directory:
• UNIX: $HOME/ctm_em/etc/emweb/automation-api/downloads/descriptors
• Windows: <EM_HOME>\ctm_em\emweb\automation-api\downloads\descriptors
2. Create a copy of one of the existing images and store it within the same directory.
Give your new image file a name according to its objective, followed by .Linux or .Windows, and
then the file extension .json.
3. Using any text editor, open the new image file that you created and edit the list of installation
packages within it. Then save the file.
4. Download any new installation packages that you referenced within your new image and have not yet
obtained. Store them in the proper location, as discussed in Obtaining installation packages for
provisioning (on page 224).
For a list of installation packages that are referenced by the default images, see Installation packages
referenced by default images (on page 226)

227
Control-M Administrator Guide

EXAMPLE: To prepare for provisioning of Control-M/Agent version 9.0.00 with Fix Pack 4 on a
Windows host, a copy of the Agent.Windows.json image was named
Agent_9FP4.Windows.json. The PAKAI.9.0.00.400_windows_x86_64.zip file
was downloaded from the EPD site (https://www.bmc.com/available/epd.html), and the
image file was edited to contain the following JSON code:
{
"OS": "windows-x86_64",
"Installers":
[
"DRKAI.9.0.00_windows_x86_64.zip",
"PAKAI.9.0.00.400_windows_x86_64.zip"
]
}
5. Ensure that your new image is detected by the API, by running the ctm provision images
command. Ensure that your new image is returned by the API command.
For more information about this command, see Automation API Services
https://docs.bmc.com/docs/display/workloadautomation/Control-M+Automation+API+-+Services.

Preparing installation packages for agent upgrades

This procedure describes how to prepare the installation packages that you need for Control-M/Agent
upgrades using the Control-M Automation API Provision service.

 To prepare installation packages for Control-M/Agent upgrades:

1. Ensure that the <EM_HOME>/AUTO_DEPLOY directory contains the relevant Control-M/Agent
packages to which you plan to upgrade.
If a package that you need is not yet located in this directory, obtain it from the EPD site:
a. Clickhttps://www.bmc.com/available/epd.html and follow the instructions on the EPD site until you
reach the download page for the relevant version and platform of the Control-M/Agent.
b. From the Products tab or the Patches tab, click the relevant Control-M/Agent package
(DRKAI* or PAKAI* file, respectively) and save it in the <EM_HOME>/AUTO_DEPLOY
directory.
2. Ensure that the <EM_HOME>/CM_DEPLOY directory contains the relevant installation packages
for Control-M Managed File Transfer (MFT) and Control-M Application Pack.
• If the directory does not yet contain the relevant package for Control-M Managed File Transfer,
download the relevant installation package (DRAFP* or PAAFP*) from the EPD site and run the
setup on Control-M/EM. During setup, MFT installation packages for the Agent (DRAFT* or
PAAFT*) are stored in the CM_DEPLOY directory.
• Control-M Application Pack installation packages (DR1CM* or PA1CM*) are stored in this
directory during installation of Control-M/EM.

228
Control-M Administrator Guide

API session service authorizations

The following table describes API Session service authorizations.

API functions Category in Privilege Access Comments

Privileges Level

Log in and get an access token Client Access Control-M Full For product version
Automation API 9.0.20 or later
 session login
 session logout Control-M Control-M Full For product versions
Configuration Configuration earlier than 9.0.20
Manager Manager or for Compatibility mode

Client Access Control-M WLA, Full

Utilities, EM API

API Configuration and Provision services authorizations

The following table lists the level of authorizations in Privileges of the Control-M Configuration Manager
(CCM) category required for the various API functions in the API Config service and API Provision service.

229
Control-M Administrator Guide

These required authorizations are in addition to the basic requirements for logging into Control-M
Automation API (described in API session service authorizations (on page 229)).

API functions Access Level

Access to configuration topology information Configuration: None

 config servers::get
 config server:agents::get
 config server:remotehosts::get

Access to detail configuration item information Configuration: Full

 config server:agent:params::get
 config server:agent:param::set
 config server:params::get
 config server:remotehost::get
 config server:hostgroups::get
 config server:hostgroup:agents::get

Adding, Updating configurations of major Control-M Configuration: Update

components
 config em:param::set
 config server::add
 config server:agent::add
 config server:agent::disable
 config server:agent::enable
 config server:agent::ping
 config server:hostgroup:agent::add
 config server:hostgroup:agent::delete
 config server:remotehost::add

Deleting configurations of major Control-M components Configuration: Full

 config server::delete
 config server:agent::delete
 config server:remotehost::delete

230
Control-M Administrator Guide

API functions Access Level

Access to detailed Job Archiving configuration Configuration: Browse

 config archive:rules::get
 config archive:statistics::get

Managing configurations of Job Archiving Configuration: Update

 config archive:rule::add
 config archive:rule::update
 config archive:rule::delete
 config archive::cleanup

Provisioning Configuration: Update

 provision install
 provision setup

Access to details of roles, users, and LDAP groups Authorizations: Browse

 config authorization:role::get
 config authorization:roles::get
 config authorization:user::get
 config authorization:users::get
 config authorization:ldap:roles::get
 config authorization:role:associates

Managing authorizations of roles, users, and LDAP groups Authorizations: Update

 config authorization:role::add
 config authorization:role::update
 config authorization:user::add
 config authorization:user::update
 config authorization:user:role::add
 config authorization:user:role::delete
 config authorization:ldap:role::add
 config authorization:ldap:role::delete
 config user:password::adminUpdate

231
Control-M Administrator Guide

API functions Access Level

Deleting authorizations of roles and users Authorizations: Full

 config authorization:role::delete
 config authorization:user::delete

API build and deploy services authorizations

The following table describes API build and deploy services authorizations.

API/API Service Authorization Access Level

Build jobs definitions Access token Authorizations are enough

build <definitionsFile>

Retrieve deployed job Folders Browse level on all retrieved folders

definitions
Access level: Browse,
deploy jobs::get
Control-M:*,
Folder: *

Deploy job definitions Folders Update level on all folders deployed

deploy <definitionsFile> Access level: Update,
Control-M:*,
Folder: *

Run As Users Grant permission to write jobs that Run as

use on specific hosts as required by all jobs
deployed.
Control-M:*,
Run As: *,
Node/Group : *

232
Control-M Administrator Guide

API/API Service Authorization Access Level

Delete deployed folder Folders Full access level on all folders to delete
deploy folder::delete Access level: Full,
Control-M:*,
Folder: *

Deploy AI job type Privileges Category: Client Access

deploy ai:jobtype Privilege: Control-M Application Integrator
Access level: Full
Retrieve details of deployed
AI job types
deploy ai:jobtypes::get

233
Control-M Administrator Guide

API run services authorizations

The following table describes API run services authorizations.

API Authorization Access Level

Accessing job status. Active The Active authorization filter

need to allow access to the jobs.
 run job:status::get <jobId>
Jobs Filter: off
 run jobs:status::get [limit]
-s <search query> Or

 run status <runId> Jobs Filter: Include all viewable

[startIndex] [-i] jobs

Performing job actions Active For job actions. In addition to

the Filter the specific job actions
 run job::confirm <jobId>
need to be allowed
 run job::delete <jobId> Jobs Filter: off , or includes all
 run job::free <jobId> viewable jobs

 run job::hold <jobId> Actions: Turn on all allowed

actions
 run job::kill <jobId>
 run job:log::get <jobId>
 run job:output::get <jobId>
[runNo]
 run job::rerun <jobId>
 run job::runNow <jobId>
 run job::setToOk <jobId>
 run job::undelete <jobId>

Run Jobs definition file Folders Update level on all folders

deployed
run <jobDefinitionsFile>
Access level: Update
Control-M:*,
Folder: *

234
Control-M Administrator Guide

API Authorization Access Level

Run As Grant permission to write jobs

that Run as use on specific hosts
as required by all jobs deployed.
Control-M:*,
Run As: *,
Node/Group : *

Order a deployed folder and Folders Update level on all folders

jobs ordered
run order <ctm> <folder> Access level: Update
[jobs]
Control-M:*
Folder: *

Retrieve events Prerequisite Conditions Browse level for events retrieved

run events::get -s <search Access Level: Browse,
query>
CONTROL-M:*,
Condition: *

Adding event Prerequisite Conditions Update level for Prerequisite

Conditions to add
run event::add <ctm> <name>
<date> Access Level: Update,
CONTROL-M:*,
Condition: *

Delete Event Prerequisite Conditions Full access level for Prerequisite

Conditions to delete
run event::delete <ctm>
<name> <date> Access Level: Full,
CONTROL-M:*,
Condition: *

235
Control-M Administrator Guide

API Authorization Access Level

Retrieve resources Quantitative Resource At lease Browse level for

Quantitative resources retrieved
run resources::get -s <search
query>
Access Level: Browse,
CONTROL-M:*,
Resource: *

Control Resource At lease Browse level for Control

Resource retrieved

Access Level: Browse,

CONTROL-M:*,
Resource: *

Adding /Updating resource Quantitative Resource Update level for Quantitative

resource updated
 run resource::add <ctm>
<name> <max> Access Level: Update,
 run resource::update <ctm> CONTROL-M:*,
<name> <max> Resource: *

Delete resource Quantitative Resource Full level for Quantitative

resource deleted
run resource::delete <ctm>
<name> Quantitative Resource:
Access Level: Full,
CONTROL-M:*,
Resource: *

Configuring CORBA components

This procedure describes how to use the Domain Configuration (orbconfigure) wizard to configure
Control-M/EM CORBA components.

236
Control-M Administrator Guide

CORBA clients obtain IORs to invoke requests on object references. The IOR contains endpoint
information, that is, the host and port number at which the server listens for requests. The host can be
encoded either in dotted-decimal notation (such as 234.234.234.234) or as a host name (such as
yoursite.com). By default, the hostname published in the IOR is the default hostname returned by system
call gethostbyaddr().

 To configure CORBA components:

1. From a command line, type one of the following:
• UNIX: orbconfigure
• Windows: orbconfigure.vbs
The Domain Configuration window appears.
2. From the Domain Name drop-down list, select an existing domain or create a new one.
3. In the Listening Address drop-down list, select one of the following hostname addresses:
• All: All CORBA servers listen on all available network interfaces. This policy is the default and is
recommended for computers with multiple network adapters.
• IP address: Select the IP address from the drop down list.
• Short hostname: The value appears in a read-only text box.
• Other: Defines the host/address in the adjacent text box.
4. In the Published Address drop-down list, select one of the following object address types:
• Default (hostname)
• IP address
• Short hostname: The value appears in a read only textbox.
• Fully qualified hostname: Define sthe fully qualified hostname
• Virtual hostname: Defines the virtual hostname
• localhost
• 127.0.0.1
5. Do one or more of the following:
• To enable one port to be used for communication in both directions, select the Bidirectional
IIOP (Internet Inter-ORB Protocol) check box.
If you use bidirectional IIOP, the client or server must also use this policy.
• If you are using Secure Sockets Layer (SSL) protocol instead of TCP/IP, select the SSL check box.
• To use an internal TAO configuration file to change the default behavior of TAO, select the Use
TAO internal configuration file check box and select the full path and name of the
(client-server) svc.conf file.
The default configuration file is called client_server.conf and is in the ctm_em/etc directory.
6. From the Setup Listen Ports drop-down list, select one of the following:
• Random: This is the default value and is recommended if the components are not behind a
firewall. The operating system selects an available port automatically.

237
Control-M Administrator Guide

• Range: Sets the values that is for all components that are behind a firewall.
Ensure that the range of ports is open in the firewall to permit the components to
communicate.Check that components were not active when you assigned their ports. If
components were active, stop and restart the components for changes to take effect.
7. Click Next.
The Naming Service window appears.
8. Do the following:
• In the Host field, define the name or IP address of the computer running the CORBA Naming
Service.
• In the Port field, define the listening port of the Naming Service.
• To check if communication with the CORBA Naming Service is enabled, click Test.
• To display and modify the local Naming Service settings, click Show local settings and do one
of the following:
o To save settings in repository files, click Repository files path and define an existing
Repository file directory. The default path is ctm_em/var.
o To save the settings in TAO internal configuration files, choose Use TAO internal
configuration file, you must define the configuration file to be used.
9. Click Next.
The Summary window appears.
10. If you want to install the Naming Service as a Windows service, select the Install as Windows
service checkbox and click Finish.

Configuring CE logging parameters

This procedure describes how to configure the maximum number of log files and memory allocation in the
Control-M/Server CE process.
NOTE: Verify that you have enough memory and disk space to use these parameters.
 To configure CE logging parameters:
1. Navigate to the following file:
/ctm_server/data/JAVA/CE.logging.properties
2. Change the following log limitation parameters:
• java.util.logging.FileHandler.count = 100
• java.util.logging.FileHandler.limit = 10240000 (bytes)
3. Change the value for the following CE memory limitation parameters:
• java.util.logging.MemFileHandler.limit = 10240000 (bytes)
• java.util.logging.MemFileHandler.count = 10
4. Run the following command:

238
Control-M Administrator Guide

ctmipc -DEST CE - MSGID CFG

Configuring Control-M Reports in a Control-M/EM

Distributed environment
This procedure describes how to configure Control-M Reports in a Control-M/EM Distributed environment.
By default, Control-M Reports and all its related files are saved in the primary Control-M/EM server and
not in a shared location where all Control-M/EM servers have access. You need to perform this procedure
if you have more than one Control-M/EM server with a load balancer with a virtual URL that routes
Control-M client requests to the Control-M/EM Distributed servers.
 To configure Control-M Reports in a Control-M/EM Distributed environment:
1. Define a shared File System with read/write permission for the Control-M Reports process.
2. From the CCM, add the RF_SHARED_FILE_SYSTEM_BASE_PATH system parameter and the
value must contain the shared file system location.
EXAMPLE:/p/bmc/reporting/

Connecting a load balancer to Control-M/EM

This procedure describes how to connect a load balancer to an environment with multiple Distributed
Control-M/EM components. This configuration enables you to provide continuous availability between
Control-M Web and the Control-M Web Server. Users access Control-M Web with the URL of the Load
Balancer, which then distributes requests between the available Web Servers in the Distributed
Control-M/EM environment. This ensures seamless connectivity even if one of the Web Servers are down
or if there are many connections running concurrently.
 To connect a load balancer to Control-M/EM:
1. Create the following two reverse proxy servers in the load balancer configuration file, which lists the
hosts of the connected Control-M Web Servers.
• HTTP: Host name of server
• HTTPS: FQDN of the server
EXAMPLE: upstream <NginX machine name> {
server <EM URL>:<web port>;
server <EM URL>:<web port>;}
upstream <FQDN of NginX machine> {
server <EM URL FQDN>:<HTTPS port>;
server <EM URL FQDN>:<HTTPS port>;}
NOTE: If you want to use the BMC provided certificate, you need to take the CSR file from the load
balancer server and copy it to <EM_HOME>/ini/ssl/ and sign it with the em_ssl_ca.pem and
em_ssl_cert.pem files using openssl. Afterwards, you need to save the certificate in the
configuration file of the load balancer. For an example of this configuration, see Configuring an Nginx
Load Balancer with BMC provided certificate (on page 240).

239
Control-M Administrator Guide

2. Recycle the load balancer.

3. Navigate to the following directory:
• Windows:<EM_HOME>\emweb\tomcat.conf\web.xml
• UNIX: <EM_HOME>/etc/emweb/tomcat.conf/web.xml
4. Search for the string corsfilter.
5. Add the following parameter to each Control-M/EM Distributed instance:
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value><https of load balancer server></param-value>
</init-param>
6. Recycle the Web Server.

Configuring an Nginx Load Balancer with BMC provided

certificate
This procedure describes how to configure an Nginx Load Balancer with BMC provided certificate.

 To configure an Nginx Load Balancer:

1. Log in as root in the NginX machine and create the openssl.cfg file and copy the following to the file
and update the details according to your environment.
[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn
[ dn ]
C=US
ST=Texas
L=Houston
O=BMC Software Inc
OU=Control-M
emailAddress=[Your email address]
CN =[Your server FQDN]
[ req_ext ]
subjectAltName = @alt_names

240
Control-M Administrator Guide

[ alt_names ]
DNS.1 = [Your server FQDN]
2. Run the following command to create a private key and CSR file:
openssl req -new -sha256 -nodes -out request.csr -newkey rsa:2048 -keyout
privatekey.pem -config openssl.cfg
The privatekey.pem and request.csr files are created.
3. Copy the private key to the NginX folder /etc/pki/nginx/private/.
4. From your Control-M/EM primary machine, navigate to <EM_HOME>/ini/ssl/ and copy the following
files to your NginX machine where the CSR file is created.
• - em_ssl_ca.pem
• - em_ssl_cert.pem
5. Run the openssl command to sign your CSR and move the file that is created to /etc/pki/nginx/.

241
4
4
Control-M security
As part of the logging in process, Control-M components send user name and password information to
Control-M/Server components for authentication. You can define security permissions for every Control-M
component to ensure maximum security. For every Control-M component you can define the following:
 Authorization security: Defines which users are allowed to view and which operations (including
data modification) that users can perform. At the Control-M/EM and Control-M/Server levels, you can
define security for individual users and for groups. For more information, see Control-M/Server
security (on page 242).
 Authentication security: Defines run as user authentication for Control-M/Agent. For more
information, see Control-M/Agent security (on page 246).

Control-M/Server security
Control-M/Server security allows you to define authorizations for each user/group. You authorize which
user/group can run a certain a job and which actions (for example, forcing another job or running a
utility) a user/group are authorized to perform in the Control-M/Server account.
Control-M/Server authorization security applies to the Active jobs database.
NOTE: To define the bimuser security settings for Control-M for z/OS, see INCONTROL for z/OS Security
Guide.
Authorizations are used to perform security checks each time one of the following actions is attempted in
Control-M/Server:
 Accessing a folder (add, delete, or modify a job definition)
 Ordering a job
 Selecting and submitting a job
 Running a command that affects jobs in the Active jobs database (Hold, Confirm, Rerun)
 Maintaining Control-M entities (calendars and prerequisite conditions)
The following procedures describe how to create, edit, delete, and define permissions for a user/group:
 Creating a user/group (on page 243)
 Editing a user/group (on page 243)
 Deleting a user/group (on page 243)
 User/group authorizations (on page 244)
Alternatively, you can use the ctmsec utility, as described in ctmsec.

242
Control-M Administrator Guide

Creating a user/group
This procedure describes how to create a user/group which enables you to define the Control-M/Server
users/groups.
 To create a user / group:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and
select Security > Control-M Server.
The Control-M/Server Security window appears.

2. From the drop-down list, select User or Group.

The New User/New Group window appears.
3. Define the following:
• Name: Type a name for the user/group.
• Description: Type a description for the user/group (optional).
• Group: Type the name of the group the user belongs to.
4. Click OK.
The user/group is created.

Editing a user/group
This procedure describes how to edit a Control-M/Server user/group which enables you to change the
user/group properties.
 To edit a user/group:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Control-M Server.
The Control-M/Server Security window appears.
2. From the User/Group Names list, select the user/group to edit.
3. Click .
The Update User/Update Group window appears.
4. Update the Description field and the Group field. For more information see Creating a user/group
(on page 243).
5. Click OK.
The user/group properties are updated.

Deleting a user/group
This procedure describes how to delete a Control-M/Server user/group.

243
Control-M Administrator Guide

 To delete a user/group:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Control-M Server.
The Control-M/Server Security window appears.
2. From the User/Group Names list, select the user/group to delete.

3. Click .
A confirmation message appears.
4. Click Yes.
The user/group is deleted.

User/group authorizations
In Control-M you can define permissions for Control-M/Server users and groups, which enables you to
limit the entities that a user is authorized to view or change. For example, a user can be authorized to
read a folder but not update a folder. Many operations require permissions in Control-M/Server. For
example, to hold a job, the user must be authorized in Control-M/Server to hold jobs for the job run as
user. You can define the following permissions:
 Defining folder authorizations (on page 244)
 Defining authorizations for Active Jobs (on page 245)
 Defining authorizations for Control-M entities (on page 245)
Users are granted permissions based on their associated group. You can add additional authorizations,
which supersede the authorizations defined for that user in the group.

Defining folder authorizations

This procedure describes how to define folder authorizations for specific users/groups and the actions
they are allowed to do for each folder.
 To define folder authorizations:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Control-M Server.
The Control-M/Server Security window appears.
2. From the User/Group Names box, select the user/group you want to define authorizations for.
3. Select the Folder tab, and do the following:

a. Click .
b. In the Folder field, type the name of the folder.
c. For each folder action, select one of the following to define the authorizations. For more
information, see Monitoring.
o Yes

244
Control-M Administrator Guide

o No
o Default
If you select Default for a user, the authorizations are inherited from the group the user belongs
to. If the user does not belong to a group, the action is not authorized.
4. Click Apply.
The folder authorizations for the user/group are defined.

Defining authorizations for Active Jobs

This procedure describes how to define authorizations for the Active Jobs, which enables you to give
authorizations for specific actions a user/group can do on the copies of the previously-defined folders that
are placed in Active Jobs.
 To Define authorizations for Active Jobs:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Control-M Server.
The Control-M/Server Security window appears.
2. From the User/Group Names box, select the user/group you want to define authorizations for.
3. From the Authorized AJF tab, do the following:

a. Click .
b. In the Run As field, type the name of the user.
c. Define the host where the run as user is authorized to perform actions on the folders in Active
Jobs.
d. For each action, select one of the following to indicate what actions the run as user is permitted to
perform on the folders in Active Jobs. For more information, see Monitoring.
o Yes
o No
o Default
If you select Default for a user, the authorizations are inherited from the group the user belongs
to. If the user does not belong to a group, the action is not authorized.
4. Click Apply.
The Active Jobs authorizations are defined for the user/group.

Defining authorizations for Control-M entities

This procedure describes how to define authorizations for Control-M entities on users/groups for the
specific entities in the Active Jobs database in Control-M.
 To define authorizations for Control-M entities:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Control-M Server.

245
Control-M Administrator Guide

The Control-M/Server Security window appears.

2. From the User/Group Names box, select the user/group you want to define authorizations for.
3. Select the Entities tab.
4. For each action and each entity, select one of the following to indicate what actions the owner is
permitted to perform on each entity. For more information, see Monitoring.
• Yes
• No
• Default
If you select Default for a user, the authorizations are inherited from the group the user belongs to.
If the user does not belong to a group, the action is not authorized.
5. Click Apply.
The authorizations for Control-M entities are defined for the user/group.

Authorizing Control-M/Server utilities for a Control-M/Agent

This procedure describes how to authorize Control-M/Server utilities for a Control-M/Agent to use. This
might occur when a job that runs on the Agent may contain a command to run the ctmcreate utility or a
user logs into the Agent account and manually runs the ctmcontb utility. To prevent Agent users from
submitting unauthorized commands and utility invocations to the Control-M/Server, you can define a
separate list of permitted Control-M/Server utilities for each Agent.
NOTE: The default Control-M/Server utility list (listing all utilities) is located in the AGUTILS_PERMIT
file in the Control-M/Server data/AGDEFS directory.
 To authorize Control-M/Server utilities for a Control-M/Agent:
1. In the Control-M/Server data/AGPERMIT_UTILS directory, create a file that has the same name as
the Agent (in lower case letters).
2. In the file, list the Control-M/Server utilities that are permitted to run on the Agent.
You can copy names from the list in the AGUTILS_PERMIT file in the Control-M/Server
data/AGDEFS directory.

Control-M/Agent security
Some of the jobs run by Control-M on a Control-M/Agent require job run as user authentications or SSH
key definitions. The security method is determined by whether the job runs on an agent or if the job is
executed from a remote host. SSH key authentication is only available for job run as users of remote host
jobs using the SSH communication protocol.
The following job types require job Run as authentication settings:

246
Control-M Administrator Guide

 Jobs that run on remote host computers

 Jobs that run on agents on Windows computers in Log on as user mode
 Jobs that run on agents on UNIX run in non-root mode
The following procedures describe how to define, edit, and delete run as user authentication settings:
 Defining run as user authentication settings (on page 247)
 Editing run as user authentication settings (on page 248)
 Deleting run as user authentication settings (on page 248)
NOTE: BMC recommends the following configurations:
 Run the Control-M/Agents in non-root mode (default).
 Run the Control-M/Agents in SSL/TLS configuration (non-default mode). Control M works with SSL and
TLS protocols, which ensures secure communication between the various Control-M components. To
configure SSL/TLS between Control-M/Server and Control-M/Agent, see Zone 2 and 3 SSL
configuration.

Defining run as user authentication settings

This procedure describes how to define run as user authentication settings, which enables you to add
authentication definitions for run as users.

 To define run as user authentication settings:

1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Run as.
The Run as User Authentication Settings window appears.
2. From the Control-M/Server drop-down list, select the Control-M/Server to create the owner on.

3. Click .
The New Run as User Definition window appears.
4. In the Run as user field, type the user.
5. From the Host drop-down list, select a host.
6. In the Authentication Properties section do one of the following:
• Select Use Password Authentication if you are running jobs on a host.
a. In the Enter Password field, type the password to use for authentication.
b. In the Confirm Password field, retype the password to confirm accuracy.
• Select Use Key Authentication (SSH only) if you are executing jobs on agentless technology.
c. From the Key Name drop-down list, select the key name.
d. In the Passphrase field, type the passphrase to use for authentication.
7. Click Test.
8. Click OK.

247
Control-M Administrator Guide

The run as user authentication settings are defined.

Editing run as user authentication settings

This procedure describes how to edit the run as user authentication settings, which enables you to modify
the run as user authentication definitions.
 To edit run as user authentication settings:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Run as.
The Run as User Authentication Settings window appears.
2. From the run as users list, select a run as user to edit.
3. In the Authentication Properties section, make changes to the necessary fields. For more
information, see Defining run as user authentication settings (on page 247).
4. Click Test.
5. Click Save.
The run as user authentication settings are updated.

Deleting run as user authentication settings

This procedure describes how to delete run as user authentication settings, which enables you to remove
authentication definitions that were set for the run as user.

 To delete run as user authentication settings:

1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > Run as.
The Run As User Authentication Settings window appears.
2. From the run as users list, select the run as user to delete.

3. Click .
A confirmation message appears.
4. Click Yes.
Wait for the message to be deleted successfully.
5. Click Close.
The run as user authentication settings are deleted.

248
Control-M Administrator Guide

Agentless SSH key management

Secured Shell (SSH) keys are communication protocols that enable secure data communication through a
secure channel. In Control-M, SSH keys are used when agents communicate with remote hosts.
Control-M/Agent uses the SSH protocol to upload and download files and to submit the job to the remote
host. SSH key authentication method is only available for job run as users of remote host jobs using the
SSH communication protocol.
The Manage Agentless SSH key option enables you to create, delete, or edit SSH keys for remote hosts
and to save public SSH keys on your local computer for further deployment on remote hosts of SSH
servers.
The following procedures describe how to create, edit, copy and delete SSH keys:
 Creating an SSH key (on page 249)
 Editing an SSH key (on page 250)
 Deleting an SSH key (on page 250)

Creating an SSH key

This procedure describes how to create an SSH key which enables you to create SSH keys for remote
hosts.
 To create an SSH key:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > SSH Keys.
The Manage Agentless SSH Keys window appears.

2. Click .
The Create SSH Key window appears.
3. In the Key Name field, type the name for the key.
4. In the Key Passphrase section, do the following:
a. In the Passphrase field, type the password for the key file.
b. In the Confirm Passphrase field, re-type the password to confirm.
5. In the Key generation parameters section, do the following:
a. In the Format of key to generate field, select the format of the SSH key to generate.
b. In the Type of key to generate field, select the type of the SSH key to generate.
c. From the Number of bits in generated key drop-down list, select the number of bits.
Generated keys defined with larger bits provides enhanced security.
6. Click Save.
A message appears asking if you wish to save the public key locally.
7. Click Yes.

249
Control-M Administrator Guide

8. Select the filename and location for the public key, which can be later distributed to the SSH server.
Private keys are generated and saved in the Control-M/Server database computer. Public keys are
generated and saved in the Control-M/Server computer in the following location:
<Control-M/Server_Home_Dir>\public_keys
After the public keys have been saved, copy them to the SSH server.

Editing an SSH key

This procedure describes how to edit an SSH key which enables you to modify the SSH key settings.
 To edit an SSH key:
1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > SSH Keys.
The Manage Agentless SSH Keys window appears.
2. From the list of SSH keys, select the SSH key to edit.
3. Click .
The Update SSH Key window appears.
4. Edit the required fields. For more information, see Creating an SSH key (on page 249).
5. Click Save.
The SSH key is updated.

Deleting an SSH key

This procedure describes how to delete an SSH key.

 To delete an SSH key:

1. From the Components Tree pane, right-click the Control-M Server: <name of server> and select
Security > SSH Keys.
The Manage Agentless SSH Keys window appears.
2. From the list of SSH keys, select the SSH key to delete.

3. Click .
The SSH Key Passphrase window appears.
4. Enter the passphrase, and click OK.
The SSH key is deleted.

250
Control-M Administrator Guide

Configuring SSO authentication for Control-M Web

Single Sign On (SSO) authentication for Control-M Web enables you to securely log in once to the
Control-M web server and gain access to all Control-M Web services and interfaces without separate
prompts to log in.
SSO is supported on Windows, Linux, and AIX.
The following sections present two different options for setting up SSO authentication for Control-M Web:
 Configuring SSO authentication through Control-M web server (on page 251)
 Configuring SSO authentication through a proxy server (on page 252)

Configuring SSO authentication through Control-M web server

This procedure describes how to download SSO authentication and integrate it with the Control-M web
server, a Tomcat server.
 To configure SSO authentication with Control-M web server:
1. Deploy one of the following SSO plug-ins provided by the SSO vendor:
• Valve:
a. Navigate to the following path:
o Windows: <EM_HOME>\emweb\Tomcat
o UNIX: <EM_HOME>/etc/emweb/Tomcat
b. Add the class in the Tomcat's classpath, in a jar file located under …/Tomcat/lib.
c. Register the Valve in the server.xml file within the localhost:
<Host name="localhost" ...>
<Valve className="com.you.YourValve"/>
</Host>
• Filter:
d. Navigate to the following path:
o Windows: <EM_HOME>\emweb\Tomcat
o UNIX: <EM_HOME>/etc/emweb/Tomcat
e. Add the class in the Tomcat's classpath, in a jar file located under …/Tomcat/lib.
f. Extract the controlm-web.war file located under <EM_HOME>/services/classes to a
temporary folder.
g. Modify the web.xml located under ControlM/WEB-INF, and add a filter node and its mapping:
<filter>
<filter-name>SSO</filter-name>
<filter-class>com.you.YourFilter</filter-class>

251
Control-M Administrator Guide

</filter>
<filter-mapping>
<filter-name>SSO</filter-name>
<url-pattern>*</url-pattern>
</filter-mapping>
h. Zip the files from the temporary directory back in to a war file and place it back under
<EM_HOME>/services/classes.
2. In Control-M Configuration Manager, refresh the Web Server component.
3. Right-click the Control-M EM component and select System Parameters, and then configure the
following system parameters:
a. In the Advanced category, set the value of SSO to ON.
b. In the Advanced category, modify SSOUserIdParamName to the name that your plug-in uses.
c. In the LDAP category, add a domain for SSO authentication and define its LDAP system
parameters, as described in Defining LDAP system parameters (on page 47).
4. Define an LDAP group for SSO authentication, as described in Defining LDAP Groups (on page 264).

Configuring SSO authentication through a proxy server

This procedure describes how to set up SSO authentication for Control-M Web through an Apache proxy
server and an integration with Okta that uses the Shibboleth module and the SAML protocol.
This procedure involves the following major tasks:
1. Configuring the Apache proxy server for SSO (on page 252)
2. Configuring the Shibboleth module for SSO (on page 255)
3. Configuring SSO in Control-M (on page 256)
For additional troubleshooting information and configuration examples, see Knowledge Base article
000171811 https://bmcsites.force.com/casemgmt/sc_KnowledgeArticle?sfdcid=000171811 on the BMC
Customer Support website http://www.bmc.com/support.

Configuring the Apache proxy server for SSO

This procedure describes how to configure an Apache proxy server for SSO authentication in Control-M
Web.
NOTE: All paths in this procedure are based on /etc/httpd as the location of the home directory of the
Apache HTTP Web server. If you installed the Apache server in a different location, adjust all paths
accordingly.
Before you begin
 Install an Apache HTTP Web server, preferably on a dedicated VM (for optimal performance).
 Install the following modules to support integration with Okta and Shibboleth:
• mod_ssl.so

252
Control-M Administrator Guide

• mod_proxy.so
• mod_shib_24.so
• mod_php.so
Note: To avoid compatibility issues, ensure that the Shibboleth library that you install is
mod_shib_24.so. In BMC testing, the shibboleth-3.0.3-1.1.x86_64 installation package was used and
was found to contain the appropriate Shibboleth module.
 To configure the Apache proxy server for SSO:
1. Use the vi command to edit the httpd.conf file, located in /etc/httpd/conf/. Apply the following
edits and save the file:
• Update the ServerName variable with host and port, as in the following example:
ServerName host-apache.myorg.com:80
• Specify the Listen IP of the Apache server host:
Listen xxx.xxx.xxx.xxx:80
• Update the DocumentRoot variable, as in the following example:
DocumentRoot "/var/www/html"
2. Use the following command to receive a list of the available configuration files:
ls -tl /etc/httpd/conf.d/*.conf
3. Ensure that the following configuration files are listed in the output from the previous step.
• shib.conf — Context root settings. For the configuration required in this file, see step 4.
• httpd-ssl.conf — SSL settings. For the configuration required in this file, see step 5.
• httpd-default.conf — Default configuration
• php.conf — PHP module configuration. Ensure that the PHP package is installed on this server.
NOTE: File names might vary, depending on the module version installed. For example, php.conf
might appear as rh-php_72.conf.
4. In shib.conf, perform the following edits:
a. Verify that LoadModule mod_shib points to the correct path of the shared library:
LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_24.so
b. Verify that the Location section does not include a relative path and that the following elements
are included:
<Location />
AuthType shibboleth
ShibRequestSetting requireSession 1
ShibUseHeaders On
require shibboleth
</Location>
5. Configure SSL settings by performing the following steps:

253
Control-M Administrator Guide

a. Generate a Certificate Signing Request (CSR) and key file and provide the CSR file to the
Certificate Authority (CA) to be signed.
The CA entity provides you with a root CA certificate and intermediate CA certificate, to be
specified in the next step. Ensure that these files are in PEM format. Self-signed certificates are
not supported in this configuration.
The CN that you provide to the CA entity is also used as the ServerName in the next step.
b. In the httpd-ssl.conf file, provide updated values for the SSL settings that are highlighted in
bold below:
SSLSessionCache shmcb:/etc/httpd/run/ssl_scache(512000)
SSLSessionCacheTimeout 300
SSLPassPhraseDialog exec:conf/ssl.crt/passwd.sh
Listen *:443
<VirtualHost *:443>
DocumentRoot "/var/www/http"
ServerAlias host-apache.myorg.com:443
ServerName host-apache.myorg.com:443
ServerAdmin ai@myorg.com
LimitRequestFieldsize 65535

SSLEngine on
SSLCipherSuite
ALL:!ADH:!EXPORT56:+HIGH:+MEDIUM:-LOW:-SSLv2:-RC4:-EX
SSLProtocol +SSLv3 +TLSv1.2
SSLCertificateFile /etc/httpd/conf/ssl/host-apache.crt
SSLCertificateKeyFile /etc/httpd/conf/ssl/host-apache.key
SSLCACertificateFile
/etc/httpd/conf/ssl/host-apache-intermediate.crt
SSLOptions +StdEnvVars +ExportCertData

</VirtualHost>
6. In the httpd-proxy.conf file, replace the parameters highlighted in bold below with the location of
the Control-M Web server (the Tomcat server), and verify that all other parameter values appear as in
the following example:
SSLProxyEngine on
SSLProxyVerify none
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLProxyCheckPeerExpire off

254
Control-M Administrator Guide

ProxyRequests off
ProxyPreserveHost On
ProxyPass /Shibboleth.sso/ !
ProxyPass /uname !
ProxyPass /ControlM https://control-m.myorg.com:8443/ControlM
ProxyPass /Reports https://control-m.myorg.com:8443/Reports
ProxyPass /RF-Server https://control-m.myorg.com:8443/RF-Server
ProxyPass /automation-api https://control-m.myorg.com:8443/automation-api
ProxyPassReverse /ControlM https://control-m.myorg.com:8443/ControlM
ProxyPassReverse /Reports https://control-m.myorg.com:8443/Reports
ProxyPassReverse /RF-Server https://control-m.myorg.com:8443/RF-Server
ProxyPassReverse /automation-api
https://control-m.myorg.com:8443/automation-api
7. Recycle the Apache HTTP Web server.
On a Linux host, you can run the following commands from /etc/httpd/sbin:
./apachectl stop
./apachectl start
Alternatively, if an Apache service is configured, you can use the following commands:
systemctl stop apache
systemctl start apache

Configuring the Shibboleth module for SSO

This procedure describes how to configure the Shibboleth module for SSO authentication in Control-M
Web.
 To configure the Shibboleth module for SSO:
1. Use the following command to receive a list of available Shibboleth configuration files:
ls -tl /etc/shibboleth/*.xml
2. Ensure that the following configuration files are listed in the output from the previous step.
• example-metadata.xml — Okta entity ID configuration. For the configuration required in this
file, see step 3.
• shibboleth2.xml — Okta application configuration. For the configuration required in this file, see
step 4.
• attribute-map.xml — Okta header configuration. For the configuration required in this file, see
step 5.
3. Rename the example-metadata.xml file to a more meaningful name (such as
ApacheHost-metadata.xml), and update the parameters in this file with local values from your
Okta administrator:

255
Control-M Administrator Guide

• “entityID="http://www.okta.com/MY-OKTA-ID"”
• HTTP-POST:
Location="https://myorg.okta.com/app/bindingaddress/MY-OKTA-ID/sso/saml"
/>
• HTTP:Redirect:
Location="https://myorg.okta.com/app/bindingaddress/MY-OKTA-ID/sso/saml"
/>
4. In the shibboleth2.xml file, provide appropriate values for the parameters highlighted in bold
below:
<ApplicationDefaults entityID=”https://host-apche.MYORG.com/shibboleth”>
...
<SSO entityID=”http://www.okta.com/MY-OKTA-ID”>
...
<MetadataProvider type="XML" validate="true"
path="ApacheHost-metadata.xml"/>
...
</ApplicationDefaults>
5. In the attribute-map.xml file, ensure that SSO user ID values are specified as in the following
sample:
<Attribute
name="SSOUSERID"
nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
id="SSOUSERID"> <AttributeDecoder xsi:type=" StringAttributeDecoder"
caseSensitive="false"/>
</Attribute>
6. Recycle the Shibboleth service by running the following commands:
service shibd stop
service shibd start

Configuring SSO in Control-M

This procedure describes how to complete the configuration of SSO authentication through a proxy server
in Control-M.

 To configure SSO authentication in Control-M:

1. In Control-M Configuration Manager, right-click the Control-M EM component and select System
Parameters.
2. Configure the following system parameters:
a. In the Advanced category, set the value of SSO to ON.
b. In the Advanced category, modify SSOUserIdParamName to SSOUSERID, the name used in
the Okta setup.

256
Control-M Administrator Guide

c. In the LDAP category, add a domain for SSO authentication and define its LDAP system
parameters, as described in Defining LDAP system parameters (on page 47).
3. Define an LDAP group for SSO authentication, as described in Defining LDAP Groups (on page 264).

Configuring SSO authentication for Control-M clients

The following procedures enable you to configure Single Sign On (SSO) authentication for Control-M
clients:
 Configuring Active Directory Kerberos SSO (on page 257)
 Troubleshooting CMS connections failures with SSO (on page 258)

Configuring Active Directory Kerberos SSO

This procedure describes how to configure Kereboros authentication with Active Directory to enable SSO
login to Control-M and CCM clients.

 To configure Active Directory Kerberos SSO:

1. From the Active Directory computer, create a user with one service principal and a keytab (with the
assistance of your Active Directory System Administrator), which allows Control-M/EM to authenticate
users, as follows:
• Service principal: HTTP/<EM FQDN>@<DOMAIN CAPITAL LETTERS>
The domain is listed under Computer>Properties in the Domain field and the FQDN is listed
in the Name field by running nslookup <Control-M/EM host>.
• Keytab: Run the following commands:
o setspn -A HTTP/<EM fqdn> <USER>
The <USER> value must be a unique user in the Active Directory that does not have any
other service principle. Verify with the command setspn -L account-name.
The service principal that connects to the FQDN of the Web Server can only have one
<USER>. Verify with the command setspn -L account-name.
o ktpass /out <keytabFile> /mapuser <USER>@<DOMAIN> /princ HTTP/<EM
FQDN>@<DOMAIN CAPITAL LETTERS> /pass <pass> /ptype
KRB5_NT_PRINCIPAL /crypto All
2. From the Control-M/EM server computer, do the following:
a. Navigate to the following directory:
<Control-M/EM_HOME>/etc/webcommon/SSO/
b. Open the krbDetails.ini file and replace the existing service principal with HTTP/<EM
FQDN>@<DOMAIN CAPITAL LETTERS>.
c. Replace the keytab value with the generated keytab file from the Active directory computer (see
step 1).
The keytab file must have minimum access privileges. The Keytab value is the fullpath to the
keytab file that is accessible by EM GUI server.

257
Control-M Administrator Guide

3. From the CCM, do the following:

a. Set the ClientSSO system parameter value to On, as described in Control-M/EM general
parameters (on page 59).
b. Recycle the CMS and GUi Server components.
c. Stop and start the Control-M Web Server, as described in Component status (on page 41).
Users can now log into the Control-M and CCM clients with SSO and are authenticated with Kerberos.
NOTE:
 SSO is supported on Windows, Linux, and Solaris.
 When users log in, the username is the same as the Windows computer login .
 If the user logged in from a computer that is not in the Active Directory domain or from the
Control-M/EM server computer, the user is not authenticated.
 Control-M/EM Authorizations are the same with or without Kerberos configuration.
 If LDAP is also defined in the CCM with the domain of the same Active Directory as the Kerberos
configuration, then permissions are based on the CCM configuration.

Troubleshooting CMS connections failures with SSO

This procedure describes how to define the location of the correct CMS when SSO can't find it in the
Naming Service. You might need to do this procedure if the Tomcat Web Server fails to communicate with
the CMS when a user attempts to log in with SSO from the CCM.
 To troubleshoot SSO for CCM:
1. From the Control-M/EM server, run the following command:
orbadmin ns list
A list of elements that the Naming Service contains appears.
2. Locate the element that holds the correct CMS.
3. Rename the file <ECS_HOME>\etc\clientsso.cfg.unused to
<ECS_HOME>\etc\clientsso.cfg.
4. In the file, set the parameter CMSFather to the value of the element that holds the correct CMS.

Configuring RSA authentication with Control-M

This procedure describes how to configure RSA authentication with Control-M, which enables users to log
in into all Control-M/EM clients with an RSA username, password, and token ID.
 To configure RSA authentication with Control-M:
1. Contact the RSA Administrator to configure the RSA authentication agent, as described in Configuring
the RSA Authentication Agent (on page 259).
2. Define the PasswordEncode system parameter value to 0, as described in Defining Control-M/EM
system parameters (on page 45).

258
Control-M Administrator Guide

3. Define the AuthenticationMethod system parameter value to RSAAuthenticationAgent, as

described in Defining Control-M/EM system parameters (on page 45).
4. Recycle the GUI Server.
5. Validate the authentication by doing the following:
a. Log in to a Control-M client with the RSA username, password, and token ID, as described in
Logging in to Control-M Workload Automation.
The RSA username must be the same as the username in LDAP or the Control-M/EM database.
b. Verify that the users authorizations are based on the LDAP groups (see LDAP Groups authorization
(on page 264)) or Control-M/EM gropus (see Control-M/EM user and role authorizations (on page
266)).
NOTE: If there is a problem with the authentication, and you want to revert to the previous method,
reset AuthenticationMethod and PasswordEncode to their original values and recycle the GUI
Server.
6. Restart the Control-M Configuration Server.

Configuring the RSA Authentication Agent

This procedure describes how to configure the RSA Authentication Agent. This procedure must be done
by the RSA Administrator.
 To configure the RSA Authentication Agent:
1. Log in in to RSA Authentication Manager security console, and do the following:
a. Register the Control-M/EM server as an RSA Authentication Agent.
You do not need to generate a node secret. If one exists, you need to clear it.
b. Download the RSA authentication agent client configuration file and extract sdconf.rec.
c. Copy the sdconf.rec file to $HOME/ctm_em/plugins
2. If you want to place the configuration files (sdconf.rec) in a different location, do the following:
a. Navigate to the following directory:
$HOME/ctm_em/plugins/
b. Copy the example property file RSAAuthenticationAgent.prop.example to
RSAAuthenticationAgent.prop.
c. Set configFileLocation to the path where you placed sdconf.rec.

Changing the encryption type between Control-M/Server

and Control-M/Agent
This procedure describes how to change the encryption type from Blowfish to AES 256 between
Control-M/Server and Control-M/Agent, which encrypts the passwords between them.

259
Control-M Administrator Guide

Before you begin

 Install Control-M/Server 9.0.00.400 or higher
 Install Control-M/Agent 9.0.00.300 or higher

 To change the encryption protocol:

1. Open the PROTOCOL_VERSION parameter, as described in Defining Control-M/Agent system
parameters (on page 189).
2. Change the value to 12.
3. Select the Control-M/Agent, right-click, and select Ping.
The Control-M/Agent's protocol version is entered in the Control-M/Server's Communication Protocol
Version and now uses AES 256 encryption.

Replacing the Control-M encryption keys

This procedure describes how to replace the Control-M factory encryption keys from the installation for all
components.
NOTE:
 To replace the transient_key.txt, see Control-M encryption keys (on page 261).
 You can also change the encryption key in Control-M/Server using the ctmkeystore_mng utility and in
Control-M/Agent using the agkeystore utility.
 To replace the Control-M encryption keys:
1. Create a new key using the keygen script, as follows:
• UNIX:
o ./ctm_agent/ctm/scripts/keygen.sh -keyoutput <file path>
o ./ctm_server/scripts/keygen.sh -keyoutput <file path>
• Windows:
o <AGENT_HOME>\keygen.bat -keyoutput <file path>
o <CTM_SERVER_HOME>\ctm_server\scripts\ keygen.bat -keyoutput <file path>
2. Replace the following keys with the same name in the required locations at the same time, as
described in Control-M encryption keys (on page 261).
• ctm_key.txt
• transfer_key.txt
• storage_key.txt
• Local.key
• new_local.txt (Requires a restart of Control-MFT)

260
Control-M Administrator Guide

Control-M encryption keys

The following table lists the Control-M encryption keys and their locations.

Key Components Key usage Replace

ctm_key.txt  CCM Encrypts the following:  CCM, CM_PLU

<EM_HOME>\in
 CM_PLUGIN  run_as_user password
 CTM
 Control-M/Server  run_as in the Remote Host
Server:ctm_se
 Control-M/Agent
 CTM Agent:
 CM ctm_agent\ctmd

security_aes_key.txt Control-M/Server Encrypts passwords and  UNIX:

passphrases that are stored in replace_encrypt
the database
 Windows:
replace_encrypt

db_aes_key.txt Control-M/Server Encrypts the database password You cannot update

transfer_key.txt  Control-M/EM clients Encrypts local Control-M/EM files <EM_HOME>\ini\fip

 Control-M/EM Server

transient_key.txt  Control-M/EM clients Encrypts local Control-M/EM files  UNIX: /ctm_em

with a key unique to the specific the em
 Control-M/EM Server installation. change_trans
utility)
NOTE: Do not copy this file or
the files that it encrypts  Windows:
<EM_HOME>\c
ent_key.bat

storage_key.txt Control-M/EM Server Encrypts passwords in the local <EM_HOME>\ini\fip

Control-M/EM

Local.key Control-M/Agent Encrypts local passwords in the Run the ctmagcpk u

Control-M/Agent

261
Control-M Administrator Guide

Key Components Key usage Replace

new_local.txt Control-M MFT Encrypts passwords and <Agent_Home>\CM

passphrases in the following
NOTE: If you want
files:
such as accounts.xm
 accounts.xml two hosts with Cont
the same key must
 Pgp_templates.dat host.
 aft_configurable.properties
 ftpssl_config.properties
 fts_config.properties

NOTE: Stored passwords refer to both passwords for remote hosts and non-default Control-M/Agent
users and the ssh key passphrase. The Remote Hosts and Non-Default Control-M/Agent users are stored
in the database encrypted with the encryption key data\keys\security_aes_key.txt. Replacing the
key generates a new key and re-encrypts all passwords stored in the database.
The replace_encryption_key script performs the key replacement. The previous key and database tables
containing the previous encrypted passwords are saved in the following locations:
 Windows: <installation dir>\bcp_backup_<time_stamp> directory
 UNIX: <installation dir>/backup_db_<time_stamp> directory
The previous key is saved in the <installation dir>
/data/keys/security_aes_key_<time_stamp>.txt file.
You must delete the backups after verifying the conversion has completed successfully and new jobs can
be submitted to Remote Hosts and Control-M/Agents running as a not-default user.

Configuring security filters

This procedure describes how to configure security filters in the Control-M Web Server. Security filters
provide enhanced browser security. By default, a set of filters are enabled. You can add, edit, delete or
disable security filters.
 To configure security filters:
1. From a command line, type the following:
manage_webserver
2. Press 2. Security Filter Configuration.
3. Do one of the following:
• To disable security filters, press 1
• To disable secure cookies, press 2.
• To add, edit, or delete security filters, press 3. Security Filters Configuration.

262
5
5
Control-M/EM Authorizations
In Control-M you can create, edit, copy, and delete Control-M/EM users and roles, which enables you to
limit the entities that a user is authorized to view or change. For example, a user can be limited to
modifying resources and jobs that relate to a specific Control-M/Server installation.
Users are granted permissions based on their associated role. You can add additional authorizations,
which supersede the authorizations defined for that user in the role.
EXAMPLE: User JimA belongs to role Acct. Role Acct has Browse authority for all folders. JimA has
Update authority for Control-M Figaro and Marius folders. In addition, JimA has Update
authority for jobs on Control-M Figaro and Marius where Bob is the Run as user and the
NodeID or Group is Finance. JimA can update folders for Figaro and Marius that have jobs
whose Run as user is Bob and Node ID or Group field is Finance, but can only view folders
for other Control-M installations.
Usernames are authenticated in Control-M/EM according to the AuthenticationMethod system
parameter and the DirectoryServiceAuth system parameter settings. These parameters determine
whether Control-M/EM uses internal or external authentication. If the DirectoryServiceAuth system
parameter is set to On, the AuthenticationMethod system parameter is ignored. The login procedure must
authenticate the identifiers of the user against external LDAP directories. Users who are not defined in the
Control-M/EM must belong to groups in the LDAP directory. These groups must be associated with
Control-M/EM authorization roles, as described in LDAP Groups authorization (on page 264). For more
information about these parameters and other LDAP parameters, see Control-M/EM general parameters
(on page 59).
Many operations require authorizations in both Control-M/EM and Control-M/Server. For example, to hold
a job, the user must be authorized in Control-M/EM to access that job and authorized in Control-M/Server
to hold jobs for the job run as user. For more information, see Control-M/Server security (on page 242).
The following procedures describe how to define, edit, copy, and delete Control-M/EM users and roles in
the CCM:
 Defining a Control-M/EM user/role (on page 264)
 Editing a Control-M/EM user/role (on page 265)
 Copying a Control-M/EM user/role (on page 265)
 Deleting a Control-M/EM user/role (on page 266)
For a list of available authorizations for Control-M/EM users and roles, see Control-M/EM user and role
authorizations (on page 266).
NOTE: Configuration of authorizations can also be done through the Control-M Automation API. For more
information, see Config Authorization
https://docs.bmc.com/docs/automation-api/919/services-817914516.html#Services-ConfigAuthorization in
the Control-M Automation API online documentation.

263
Control-M Administrator Guide

Defining a Control-M/EM user/role

This procedure describes how to define a Control-M/EM user or role.
 To define a Control-M/EM user/role:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:

• If you want to define a Control-M/EM user, select the Users tab and click .

• If you want to define a Control-M/EM role, select the Roles tab and click .
• If you want to define an LDAP Group to associate to a role, select the LDAP Groups tab. For
more information, see LDAP Groups authorization (on page 264).
3. Type the name of the user or role and click OK.
The User or Role Authorizations window appears.
4. For each tab, type or select the required values for each field, as described in Control-M/EM user and
role authorizations (on page 266).

LDAP Groups authorization

An LDAP group in Control-M/EM authorizations is mapped to the corresponding group in the LDAP server.
This eliminates the need of creating users in Control-M/EM, and instead authenticates the users in the
LDAP server.
In addition, a user who logs into Control-M/EM with LDAP credentials does not need to be a direct
member of one of the LDAP groups that are mapped to Control-M/EM. Control-M/EM checks the
descendants of the LDAP groups mapped to Control-M/EM. If the user is a member of one or more of the
descendant groups, the user is authorized in Control-M/EM, and inherits the combined authorizations of
all of the parental groups.
The login procedure must authenticate the identifiers of the user against external LDAP directories. Users
who are not defined in the Control-M/EM users must belong to groups in the LDAP directory. These LDAP
groups must be associated with Control-M/EM authorization, as described in Defining LDAP Groups (on
page 264).

Defining LDAP Groups

This procedure describes how to define LDAP Groups, which enable you to authorize users who are not
Control-M/EM users or part of a Control-M/EM role.
 To define LDAP Groups:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.

264
Control-M Administrator Guide

2. Select the LDAP Groups tab and click .

3. Type a name for the LDAP Group and then click OK.
4. In the Role Assignment window, select the roles that you want to assign to the LDAP group, and then
click Add.
The LDAP Group is created.

Editing a Control-M/EM user/role

This procedure describes how to edit a Control-M/EM user or role.
 To edit a Control-M/EM user/role:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Control-M/EM user, select the Users tab.
• If you want to edit a Control-M/EM role, select the Roles tab.

3. Select the user or role that you want to edit and click .
The User or Role Authorizations window appears.
4. For each tab, edit the required values for each field, as described in Control-M/EM user and role
authorizations (on page 266).
The changes do not take affect until the user logs out of all Control-M/EM sessions.

Copying a Control-M/EM user/role

This procedure describes how to copy a Control-M/EM user or role. If you copy an existing role, the users
that belonged to the existing role are not associated with the new role. If you copy an existing user, the
roles that the existing user belongs to are associated with the new user but the existing password is not
copied. You can define the new password in the General tab.

 To copy a Control-M/EM user/role:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to copy a Control-M/EM user, select the Users tab.
• If you want to copy a Control-M/EM role, select the Roles tab.

3. Select the user or role that you want to copy and click .
4. Type a new name for the user or role and click OK.

265
Control-M Administrator Guide

5. For each tab, edit the values for each field as necessary, as described in Control-M/EM user and role
authorizations (on page 266).
The changes do not take affect until the user logs out of all Control-M/EM sessions.

Deleting a Control-M/EM user/role

This procedure describes how to delete a Control-M/EM user or role.

 To delete a Control-M/EM user/role

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Control-M/EM user, select the Users tab.
• If you want to delete a Control-M/EM role, select the Roles tab.

3. Select the user or role that you want to delete and click .
4. A confirmation message appears.
5. Click Yes.

Control-M/EM user and role authorizations

You can limit the access to the following entities and actions on Control-M/EM users and roles:

266
Control-M Administrator Guide

 Jobs that the user can view or modify. This affects usage of all windows that rely on access to
information originating in the active jobs database. For example, limiting the view to jobs from a
single Control-M/Server installation limits the view in a Control-M/EM ViewPoint. For more
information, see Active authorizations (on page 269).
 Control resources, quantitative resources, global conditions, and prerequisite conditions that the user
can view or change. This does not relate to resources and conditions displayed in the Job Details
window. For example, a user might see that a job is waiting for a prerequisite condition in the Job
Details window, but not be authorized to create this condition using the Prerequisite Condition
window. For more information, see Global Condition authorizations (on page 277), Prerequisite
Conditions authorizations (on page 279), or Quantitative and Control Resource authorizations (on
page 281).
 Calendars and folders that the user can view. Limiting access to folders also determines which folders
and jobs the user can order or force. For more information, see Calendar authorizations (on page
284) or Folder authorizations (on page 286).
 CCM, Administration and Monitoring Tools, and ViewPoint Manager, as described in Privileges (on
page 273).
 Site Standards and User Views that the user can view or change. For more information, see Site
authorizations.
 Role Based Administration allows Control-M Administrators to delegate control to users to carry out
specific administrative tasks, as described in Role Based Administration authorizations (on page 297).

267
Control-M Administrator Guide

User general permissions

The following table describes login data about users (or lists members of a group):

Field Description

User Name Defines the username of the authorized user

Full Name Defines the full name of the authorized user

Description Provides a description of the authorized user

Password Defines the password of the authorized user

The Password field is disabled when Active Directory
authentication is used.
NOTE: If the UserChangePassword system parameter is set
to 1 (its default value), all users can change their own
password (see Changing the password). If this parameter is set
to 0, only users who have Full or Update permission to modify
security definitions can change their own password.

Confirm Password Confirms the password of the authorized user

Password Expiration Determines when the password expires by selecting one of the
following options:
 Password never expires
 Password will expire every n days
 User must change password at next login

Lock Account Determines whether the user account is locked and disables
the user from performing actions in Control-M.

Adding users to roles

This procedure describes how to add users to roles, which enables you to grant access to multiple users
through role authorizations.
 To add users to roles:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Select the Users tab and double-click the user that you want to add to a role.
3. Select the Assigned Roles tab.
4. In the Available table, select the role that you want this user to join and click Add.

268
Control-M Administrator Guide

The user is now a member of the role that you selected and appears in the Assigned table.

Active authorizations
The authorizations in the Active tab enable you to grant users access to browse specific job output and
perform specific actions on a job in the Monitoring domain based on job and folder filters, as described in
Assigning Active authorizations (on page 270).
The Browse, Control, and Update actions that you apply for a user are only applicable to the jobs and
folders that you filtered.
EXAMPLE: User Bob has authorization to see jobs starting with a*, and is authorized to perform Free
and Hold actions on those jobs. He also belongs to the Tech Support role, which have
permission to see jobs starting with b*, and are authorized to perform Rerun and Confirm
actions on those jobs. User Bob also belongs to the DBA role, which have authorization to see
jobs starting with c*, and are authorized to use the Log and Documentation browse features
and perform Confirm actions on those jobs.
When Bob logs into Control-M/EM, he sees all jobs starting with the letter a, b, and c. For all
jobs starting with the letter a, he can perform Hold and Free actions. For jobs starting with
the letter b, he can perform Rerun and Confirm actions. For jobs starting with the letter c he
can view the Log and Documentation and perform Confirm actions.

269
Control-M Administrator Guide

The following table lists the Browse, Control, and Update actions that you can apply to a user for specific
jobs and folders:

Field Description

Filter Enables you to filter jobs and folders based on simple or

advanced filtering criteria.
NOTE: The following fields are not supported by MFT:
 Application Type
 Command
 Critical
 Cyclic
 Description
 Path/Mem Lib
 NJE Node
 Order Date
 Run as
 RBA
 Task Type
 Embedded Script/JCL

Browse Enables you to assign browse authorizations for Properties,

Documentation, Log, Statistics, View Output List, View JCL, and
Waiting Info

Control Enables you to assign control authorizations for Hold, Release,

Confirm, Rerun, React, Restart, Terminate, and Bypass

Update Enables you to assign update authorizations for Delete,

Undelete, Set to OK, Edit Properties, and Edit JCL (JCL Verify
included.)

Assigning Active authorizations

This procedure describes how to assign Active authorizations for a Control-M/EM user or role, which
enable you to limit the browse, control, and update actions on specific jobs and folders.
 To assign Active authorizations:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.

270
Control-M Administrator Guide

2. Do one of the following:

• If you want to define an Action authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to apply an authorization.
• If you want to define an Action authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to apply an authorization.
3. Select the Active tab.
The User Authorizations: Active dialog box appears.
4. To add a filter, which includes or excludes jobs, do the following in the Including Terms or
Excluding Terms area:
a. In the Field column, select a job property.
b. In the Operator column, select the operator that you want to use.
c. In the Value column, type a value for the job property.
d. Repeat step a through step c as necessary.
e. If you want to add another group of fields which, when met, can include more fields, even if the

other group of fields do not meet the conditions, click .

EXAMPLE: The Jobs filter definition includes jobs that meet both of the following inclusion criteria:
• The job Member name must end with e.
• The job must run on a Control-M installation whose name begins with o or job is
cyclic.
Even if a job meets the preceding inclusion criteria, the filter excludes the job if it runs on
a Control-M installation whose name is omega-ctm3.
5. Select the Browse, Control, and Update actions for this user, as described in Active authorizations (on
page 269), and then click OK.
The Active authorizations for this user are enabled.

Editing Active authorizations

This procedure describes how to edit Active authorizations for a Control-M/EM user or role, which enable
you to limit the browse, control, and update actions on specific jobs and folders.

 To edit Active authorizations:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit an Action authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to apply an authorization.
• If you want to edit an Action authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to apply an authorization.
3. Select the Active tab.

271
Control-M Administrator Guide

4. Edit the job and folder filter and or edit the Browse, Control, and Update actions for this user, as
described in Active authorizations (on page 269), and then click OK.
The Active authorizations for this user are updated.

272
Control-M Administrator Guide

Privileges
Privileges enables you to grant users access to the CCM, Monitoring and Administration Tools, and
ViewPoint Manager and perform actions based on the defined access level. To activate privileges for the
user, you must define each privilege with at least a Browse access level, as described in the following
table:

Access Level Description

None Disables the user from viewing, adding, editing, and deleting
objects in Control-M

Browse Enables the user to view and refresh objects in Control-M

Update Enables the user to add and edit objects in Control-M

Full Enables the user to add, edit, and delete objects in Control-M

Default Inherits the authorizations from the associated role. (Valid for user
authorizations. Not valid for role authorizations.)

EXAMPLE: User JimA has Full privileges for all Collections, Hierarchies, Filters, and ViewPoints, which
means he can create, modify, and delete Collections, Hierarchies, Filters, and ViewPoints.
The following table describes each privilege component and determines the actions that a user or member
of a role can perform on different parts of Control-M/EM:

Privilege Category Description

CLI Client Access Enables the user to perform

administration tasks from a
Command Line Interface.
For more information, see
cli utility.

Control-M Configuration Client Access Enables the user to log in to

Manager the Control-M Configuration
Manager (on page 10).

Control-M Self Service Client Access Enables the user to log in to

Control-M Self Service.

Control-M Workload Client Access Enables the user to log in to

Change Manager the Control-M Workload
Change Manager.

273
Control-M Administrator Guide

Privilege Category Description

Control-M, Utilities, EM API Client Access Enables the user to access

the Control-M client,
Utilities, and API.

Authorizations Control-M Configuration Enables the user to apply

Manager authorizations on other
users in Control-M/EM, such
as Calendars and Folders, as
described in Control-M/EM
Authorizations (on page
263)

Configuration Control-M Configuration Enables the user to create,

Manager edit, and delete,
Control-M/EM,
Control-M/Server, and
Control-M/Agent
components, as described in
Component management
(on page 13)

Operation Control-M Configuration Enables the user to start,

Manager stop, recycle, and ignore
components, as described in
Component status (on page
41)

Database Maintenance Control-M Configuration Enables the user to check

Manager database space and extend
the database size, as
described in Checking
Database space (on page
37)

274
Control-M Administrator Guide

Privilege Category Description

Security Control-M Configuration Enables the user to create,

Manager update, view, and delete
user and role security
records, as described in
Control-M security (on page
242) as well create, edit,
copy, export, test, and
delete connection profiles
for an external application.
For more details about
connection profile
management, see the
Control-M Application
Plug-in documentation.

Archived ViewPoints Monitoring and Enables the user to access

Administration Tools Archived ViewPoints

Alerts Monitoring and Enables the user to handle

Administration Tools and unhandle alerts

SLA Management (BIM) Monitoring and Enables the user to

Reports Administration Tools generate BIM reports

Forecast Reports Monitoring and Enables the user to

Administration Tools generate Forecast reports

Periodical Statistics Monitoring and Enables the user to use

Administration Tools Periodical Statistics on a job

Forecast/SLA Management Monitoring and Enables the user to

(BIM) Configuration Administration Tools configure BMC Batch Impact
Manager and
Control-M/Forecast

Promotion Rules Monitoring and Enables the user to define

Administration Tools promotion rules.

275
Control-M Administrator Guide

Privilege Category Description

Promotion Action Monitoring and Enables the user to set the

Administration Tools following authorization
levels for a promotion
action.
 None: The user is
unable promote
 Update: The user can
create a promotion
request but the
immediate promotion
option is disabled.
 Full: The user can use
promotion request and
immediate promote

Site Standard and User Monitoring and Enables the user to do the
View Administration Tools following:
 Define settings that
ensure Control-M
Workload Change
Manager web users and
Control-M schedulers
follow your
organization's
standards.
 Simplify job properties
and restrict creation of
job types.

Collections Viewpoint Manager Enables the user to create

Collections

Hierarchies Viewpoint Manager Enables the user to create

Hierarchies

Filters Viewpoint Manager Enables the user to create

Filters

Viewpoints Viewpoint Manager Enables the user to create

Viewpoints

276
Control-M Administrator Guide

Global Condition authorizations

Global Condition authorizations grant users access to specific Global Conditions in Control-M and an
authorization level for each condition, as described in the following table:

Field Description

Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Prefix Defines the name of the global condition prefix that the user
has access to based on the access level.

The following procedures describe how to assign, edit, and delete Global Condition authorizations:
 Assigning a Global Condition authorization (on page 277)
 Editing a Global Condition authorization (on page 278)
 Deleting a Global Condition authorization (on page 278)

Assigning a Global Condition authorization

This procedure describes how to assign a Global Condition authorization for a Control-M/EM user or role,
which enables you to limit access to a condition.
 To assign a Global Condition authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to define a Global Condition authorization for a Control-M/EM user, select the Users
tab and double-click the user that you want to apply an authorization.
• If you want to define a Global Condition authorization for a Control-M/EM role, select the Role
tab and double-click the role that you want to apply an authorization.

3. Select the Global Conditions tab and click .

The User Authorizations: Global Conditions dialog box appears.
4. For each field, type or select the required value, as described in Global Condition authorizations (on
page 277) and then click OK.

277
Control-M Administrator Guide

NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The Global Condition authorization appears in the User Authorization: <Control-M/EM user>
window.

Editing a Global Condition authorization

This procedure describes how to edit a Global Condition authorization for a Control-M/EM user or role,
which enables you to limit the access to a Global Condition.

 To edit a Global Condition authorization:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Global Condition authorization for a Control-M/EM user, select the Users tab
and double-click the user that you want to edit.
• If you want to edit a Global Condition authorization for a Control-M/EM role, select the Role tab
and double-click the role that you want to edit.
3. Select the Global Conditions tab and then select the Global Condition authorization that you want to
edit.

4. Click .
The User Authorizations: Global Conditions dialog box appears.
5. Edit the required fields, as described in Global Condition authorizations (on page 277) and then click
OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The updated Global Condition authorization appears in the User Authorization: <Control-M/EM
user> window.

Deleting a Global Condition authorization

This procedure describes how to delete a Global Condition authorization for a Control-M/EM user or role.
 To delete a Global Condition authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Global Condition authorization for a Control-M/EM user, select the Users
tab and double-click the user contains the authorization that you want to delete.
• If you want to delete a Global Condition authorization for a Control-M/EM role, select the Role
tab and double-click the role contains the authorization that you want to delete.

278
Control-M Administrator Guide

3. Select the Global Conditions tab and then select the Global Condition authorization that you want to
delete.

4. Click .
A confirmation message appears.
5. Click Yes.

Prerequisite Conditions authorizations

Prerequisite condition authorizations grant users access to specific conditions in Control-M and an
authorization level for each condition, as described in the following table:

Field Description

Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Control-M Server Defines the name of the Control-M/Server (or Control-M for
z/OS) that processes the job.

Condition Defines the name of the condition that the user has access to
based on the access level

The following procedures describe how to assign, edit, and delete Prerequisite conditions authorizations:
 Assigning a Prerequisite Condition authorization (on page 279)
 Editing a Prerequisite Condition authorization (on page 280)
 Deleting a Prerequisite Condition authorization (on page 280)

Assigning a Prerequisite Condition authorization

This procedure describes how to assign a Prerequisite Condition authorization for a Control-M/EM user or
role, which enables you to limit the actions a user can perform on a Prerequisite Condition.
 To assign a Prerequisite Condition authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:

279
Control-M Administrator Guide

• If you want to define a Prerequisite Condition authorization for a Control-M/EM user, select the
Users tab and double-click the user that you want to apply an authorization.
• If you want to define a Prerequisite Condition authorization for a Control-M/EM role, select the
Role tab and double-click the role that you want to apply an authorization.

3. Select the Prerequisite Conditions tab and click .

The User Authorizations: Prerequisite Conditions dialog box appears.
4. For each field, type or select the required value, as described in Prerequisite Conditions authorizations
(on page 279) and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The Prerequisite Condition authorization appears in the User Authorization: <Control-M/EM user>
window.

Editing a Prerequisite Condition authorization

This procedure describes how to edit a Prerequisite Condition authorization for a Control-M/EM user or
role, which enables you to limit the actions a user can perform on a Prerequisite Condition.
 To edit a Prerequisite Condition authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Prerequisite Condition authorization for a Control-M/EM user, select the
Users tab and double-click the user that you want to edit.
• If you want to edit a Prerequisite Condition authorization for a Control-M/EM role, select the Role
tab and double-click the role that you want to edit.
3. Select the Prerequisite Conditions tab and then select the Prerequisite Condition authorization that
you want to edit.
4. Click .
The User Authorizations: Prerequisite Conditions dialog box appears.
5. Edit the required fields, as described in Prerequisite Conditions authorizations (on page 279), and then
click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The updated Prerequisite Condition authorization appears in the User Authorization:
<Control-M/EM user> window.

Deleting a Prerequisite Condition authorization

This procedure describes how to delete a Prerequisite Condition authorization for a Control-M/EM user or
role.

280
Control-M Administrator Guide

 To delete a Prerequisite Condition authorization:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Prerequisite Condition authorization for a Control-M/EM user, select the
Users tab and double-click the user contains the authorization that you want to delete.
• If you want to delete a Prerequisite Condition authorization for a Control-M/EM role, select the
Role tab and double-click the role contains the authorization that you want to delete.
3. Select the Prerequisite Conditions tab and then select the Prerequisite Condition authorization that
you want to delete.

4. Click .
A confirmation message appears.
5. Click Yes.

Quantitative and Control Resource authorizations

Quantitative and Control Resource authorizations grant users access to specific Quantitative and Control
Resources in Control-M and an authorization level for each resource, as described in the following table:

Field Description

Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Control-M Server Defines the name of the Control-M/Server (or Control-M for
z/OS) that processes the job.

Resource Define the name of the quantitative or control resource that

the user has access to based on the access level

The following procedures describe how to assign, edit, and delete Quantitative and Control Resource
authorizations:
 Assigning a Quantitative or Control Resource authorization (on page 282)
 Editing a Quantitative or Control Resource authorization (on page 282)
 Deleting a Quantitative or Control Resource authorization (on page 283)

281
Control-M Administrator Guide

Assigning a Quantitative or Control Resource authorization

This procedure describes how to assign a Quantitative or Control Resource authorization for a
Control-M/EM user or role, which enables you to limit the actions a user can perform on a resource.

 To assign a Quantitative or Control Resource authorization:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to define a Quantitative or Control Resource authorization for a Control-M/EM user,
select the Users tab and double-click the user that you want to apply an authorization.
• If you want to define a Quantitative or Control Resource authorization for a Control-M/EM role,
select the Role tab and double-click the role that you want to apply an authorization.
3. Do one of the following:
• If you want to assign a Quantitative Resource, select the Quantitative Resources tab and click
.

• If you want to assign a Control Resource, select the Control Resources tab and click .
The User Authorizations: Quantitative Resources dialog box or the User Authorizations:
Control Resources appears.
4. For each field, type or select the required value, as described in Quantitative and Control Resource
authorizations (on page 281) and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The Quantitative or Control Resource authorization appears in the User Authorization:
<Control-M/EM user> window.

Editing a Quantitative or Control Resource authorization

This procedure describes how to edit a Quantitative or Control Resource authorization for a Control-M/EM
user or role, which enables you to limit the actions a user can perform on a resource.
 To edit a Quantitative or Control Resource authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Quantitative or Control Resource authorization for a Control-M/EM user,
select the Users tab and double-click the user that you want to edit.
• If you want to edit a Quantitative or Control Resource authorization for a Control-M/EM role,
select the Role tab and double-click the role that you want to edit.
3. Do one of the following:
• If you want to edit a Quantitative Resource, select the Quantitative Resources tab .

282
Control-M Administrator Guide

• If you want to edit a Control Resource, select the Control Resources tab.
The User Authorizations: Quantitative Resources dialog box or the User Authorizations:
Control Resources appears.
4. Select the authorization that you want to edit and click .
5. Edit the required fields, as described in Quantitative and Control Resource authorizations (on page
281) and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The updated Calendar authorization appears in the User Authorization: <Control-M/EM user>
window.

Deleting a Quantitative or Control Resource authorization

This procedure describes how to delete a Quantitative or Control Resource authorization for a
Control-M/EM user or role.
 To delete a Quantitative or Control Resource authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Quantitative or Control Resource authorization for a Control-M/EM user,
select the Users tab and double-click the user contains the authorization that you want to delete.
• If you want to delete a Quantitative or Control Resource authorization for a Control-M/EM role,
select the Role tab and double-click the role contains the authorization that you want to delete.
3. Do one of the following:
• If you want to delete a Quantitative Resource, select the Quantitative Resources tab .
• If you want to delete a Control Resource, select the Control Resources tab.

4. Select the authorization that you want to delete and then click .
A confirmation message appears.
5. Click Yes.

283
Control-M Administrator Guide

Calendar authorizations
Calendar authorizations grant users access to specific calendars in Control-M and an authorization level
for each calendar, as described in the following table:

Field Description

Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Control-M Server Defines the name of the Control-M/Server (or Control-M for
z/OS) that processes the job.

Calendar Define the name of the calendar that the user has access to
based on the access level.

The following procedures describe how to assign, edit, and delete Calendar authorizations:
 Assigning a Calendar authorization (on page 284)
 Editing a Calendar authorization (on page 285)
 Deleting a Calendar authorization (on page 285)

Assigning a Calendar authorization

This procedure describes how to assign a Calendar authorization for a Control-M/EM user or role, which
enables you to limit the actions a user can perform on a calendar.
 To assign a Calendar authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to define a Calendar authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to apply an authorization.
• If you want to define a Calendar authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to apply an authorization.

3. Select the Calendars tab and click .

The User Authorizations: Calendars dialog box appears.

284
Control-M Administrator Guide

4. For each field, type or select the required value, as described in Calendar authorizations (on page
284) and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The Calendar authorization appears in the User Authorization: <Control-M/EM user> window.

Editing a Calendar authorization

This procedure describes how to edit a Calendar authorization for a Control-M/EM user or role, which
enables you to limit the actions a user can perform on a calendar.
 To edit a Calendar authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Calendar authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to edit.
• If you want to edit a Calendar authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to edit.
3. Select the Calendars tab and then select the Calendar authorization that you want to edit.

4. Click .
The User Authorizations: Calendars dialog box appears.
5. Edit the required fields, as described in Calendar authorizations (on page 284) and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The updated Calendar authorization appears in the User Authorization: <Control-M/EM user>
window.

Deleting a Calendar authorization

This procedure describes how to delete a Calendar authorization for a Control-M/EM user or role.

 To delete a Calendar authorization:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Calendar authorization for a Control-M/EM user, select the Users tab and
double-click the user contains the authorization that you want to delete.
• If you want to delete a Calendar authorization for a Control-M/EM role, select the Role tab and
double-click the role contains the authorization that you want to delete.
3. Select the Calendars tab and then select the Calendar authorization that you want to delete.

285
Control-M Administrator Guide

4. Click .
A confirmation message appears.
5. Click Yes.

Folder authorizations
Folder authorizations grant users access to specific folders in the Planning domain and an authorization
level for each folder. In addition, you can define different authorizations per job within a specific folder
based on Application and Sub Application criteria.
EXAMPLE: If you want to allow the user to update jobs that belong to Application App1 but restrict this
user from changing the Folder Properties, such as User Daily, Site Standards, and Business
field values, define the fields, as follows:
• Access Level=Browse
• Control-M, Library, and Folder fields=*
• Job Access Level=Update

286
Control-M Administrator Guide

• Application=App1

Field Description

Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Allow ordering Determines whether this user or role can order specific folders
and jobs.
NOTE: This option is independent of the user's access level.
EXAMPLE: Bob has Browse access to all folders that start with
the letter b. Bob can only view the properties of all
folders (and their jobs) that start with the letter b.
If Allow ordering is selected,he can order/force
these folders and their jobs.

Control-M Server Defines the name of the Control-M/Server (or Control-M for
z/OS) that processes the job.

Library Defines the name of the library that contains the job’s folder.

287
Control-M Administrator Guide

Field Description

Folder Defines the name of the folder. In the Properties pane, this
parameter indicates the folder where the job belongs.

Job Level Authorization Determines whether to enable authorizations on jobs in a

specific folder based on Application and Sub Application
criteria.
NOTE: You can only define job level authorizations if Control-M
Workload Change Manager was installed (see Control-M
Workload Change Manager installation). If Control-M Workload
Change Manager was uninstalled, you can still define job level
authorizations.

Job Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Application Provides a logical name for sorting groups of jobs. This

parameter is used to supply a common descriptive name to a
set of related job groups.

288
Control-M Administrator Guide

Field Description

Sub Application Indicates the name of the Sub Application where the job
belongs logically. It is a sub-category of the Application
parameter. For example, the Application is Finances, and the
Sub Application is Payroll.

The following procedures describe how to assign, edit, and delete folder authorizations:
 Assigning a Folder authorization (on page 289)
 Editing a Folder authorization (on page 290)
 Deleting a Folder authorization (on page 290)

Assigning a Folder authorization

This procedure describes how to assign a Folder authorization for a Control-M/EM user or role, which
enables you to grant users access to specific folders in Control-M and an authorization level for each
folder.
 To assign a Folder authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to define a Folder authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to apply an authorization.
• If you want to define a Folder authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to apply an authorization.

3. Select the Folders tab and click .

The User Authorizations: Folders dialog box appears.
4. For each field, type or select the required value, as described in Folder authorizations (on page 286)
and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The folder authorization appears in the User Authorization: <Control-M/EM user> window.

289
Control-M Administrator Guide

Editing a Folder authorization

This procedure describes how to edit a Folder authorization for a Control-M/EM user or role, which
enables you to grant users access to specific folders in Control-M and an authorization level for each
folder.
 To edit a Folder authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Folder authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to edit.
• If you want to edit a Folder authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to edit.
3. Select the Folders tab and then select the Folder authorization that you want to edit.

4. Click .
The User Authorizations: Folders dialog box appears.
5. Edit the required fields, as described in Folder authorizations (on page 286) and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The updated Folder authorization appears in the User Authorization: <Control-M/EM user>
window.

Deleting a Folder authorization

This procedure describes how to delete a Folder authorization for a Control-M/EM user or role.
 To delete a Folder authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Folder authorization for a Control-M/EM user, select the Users tab and
double-click the user contains the authorization that you want to delete.
• If you want to delete a Folder authorization for a Control-M/EM role, select the Role tab and
double-click the role contains the authorization that you want to delete.
3. Select the Folders tab and then select the Folder authorization that you want to delete.

4. Click .
A confirmation message appears.
5. Click Yes.

290
Control-M Administrator Guide

Run as user authorizations

Run as user authorizations grant users access to create and update job definitions for specific jobs in
Control-M and an authorization level for each run as user, as described in the following table:

Field Description

Control-M Server Defines the name of the Control-M/Server (or Control-M for
z/OS) that processes the job.

Run As Identifies the user name with the authorization to execute the
job. This parameter is used by the Control-M security
mechanism.
To exclude multiple users with an Or relationship at the same
line, use regular expressions, as described in Pattern matching
strings.
EXAMPLE: !(root|Oracle)
!(a*|b[1-9]*)
!(*cde|m[a-z]*)

Host ID/Group Defines the name of a Control-M/Agent computer, remote host

computer, or host group where the job is submitted.

NOTE: The definitions in the Run as Users tab only apply to users who have at least the Update access
level in the Folders tab. The definitions in the Run as Users tab apply to the jobs in the SMART folders,
not the SMART folders themselves.
The following procedures describe how assign, edit, and delete run as user authorizations:
 Assigning a Run as user authorization (on page 291)
 Editing a Run as user authorization (on page 292)
 Deleting a Run as user authorization (on page 292)

Assigning a Run as user authorization

This procedure describes how to assign a Run as User authorization for a Control-M/EM user or role,
which enables you to grant the user authorization to create and update job definitions for specific jobs in
Control-M and the XML utilities.
 To assign a Run as user authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to define a Run as user authorization for a Control-M/EM user, select the Users tab
and double-click the user that you want to apply an authorization.

291
Control-M Administrator Guide

• If you want to define a Run as user authorization for a Control-M/EM role, select the Role tab
and double-click the role that you want to apply an authorization.

3. Select the Run as Users tab and click .

The User Authorizations: Run As User dialog box appears.
4. For each field, type or select the required value, as described in Run as user authorizations (on page
291) and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The Run as user authorization appears in the User Authorization: <Control-M/EM user> window.

Editing a Run as user authorization

This procedure describes how to edit a Run as user authorization for a Control-M/EM user or role, which
enables you to grant the user authorization to create and update job definitions for specific jobs in
Control-M and the XML utilities.
 To edit a Run as user authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Run as user authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to edit.
• If you want to edit a Run as user authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to edit.
3. Select the Run as Users tab and then select the Run as user authorization that you want to edit.

4. Click .
The User Authorizations: Run as Users dialog box appears.
5. Edit the required fields, as described in Run as user authorizations (on page 291), and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The updated Run as user authorization appears in the User Authorization: <Control-M/EM user>
window.

Deleting a Run as user authorization

This procedure describes how to delete a Run as user authorization for a Control-M/EM user or role.
 To delete a Run as user authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:

292
Control-M Administrator Guide

• If you want to delete a Run as user authorization for a Control-M/EM user, select the Users tab
and double-click the user that contains the authorization that you want to delete.
• If you want to delete a Run as user authorization for a Control-M/EM role, select the Role tab and
double-click the role contains the authorization that you want to delete.
3. Select the Run as Users tab and then select the Run as user authorization that you want to delete.

4. Click .
A confirmation message appears.
5. Click Yes.

Workload Policy authorizations

Workload Policy authorizations grant users access to specific Workloads in Control-M and an authorization
level for each Workload Policy, as described in the following table:

Field Description

Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Workload Policy Defines the name of the workload policy that the user has
access to based on the access level

The following procedures describe how to assign, edit, and delete Workload Policy authorizations:
 Assigning a Workload Policy authorizations (on page 293)
 Editing a Workload Policy authorizations (on page 294)
 Deleting a Workload Policy authorizations (on page 294)

Assigning a Workload Policy authorizations

This procedure describes how to assign a Workload Policy authorization for a Control-M/EM user or role,
which enables you to limit the actions a user can perform on a Workload Policy.

 To assign Workload Policy authorizations:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:

293
Control-M Administrator Guide

• If you want to define a Workload Policy authorization for a Control-M/EM user, select the Users
tab and double-click the user that you want to apply an authorization.
• If you want to define a Workload Policy authorization for a Control-M/EM role, select the Role tab
and double-click the role that you want to apply an authorization.

3. Select the Workload Policies tab and click .

The User Authorizations: Workloads dialog box appears.
4. For each field, type or select the required value, as described in Workload Policy authorizations (on
page 293), and then click OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The Workload Policy authorization appears in the User Authorization: <Control-M/EM user>
window.

Editing a Workload Policy authorizations

This procedure describes how to edit a Workload Policy authorization for a Control-M/EM user or role,
which enables you to limit the actions a user can perform on a Workload Policy.
 To edit Workload Policy authorizations:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Workload Policy authorization for a Control-M/EM user, select the Users tab
and double-click the user that you want to edit.
• If you want to edit a Workload Policy authorization for a Control-M/EM role, select the Role tab
and double-click the role that you want to edit.
3. Select the Workload Policies tab and then select the Workload authorization that you want to edit.

4. Click .
The User Authorizations: Workloads dialog box appears.
5. Edit the required fields, as described in Workload Policy authorizations (on page 293), and then click
OK.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
The updated Workload Policy authorization appears in the User Authorization: <Control-M/EM
user> window.

Deleting a Workload Policy authorizations

This procedure describes how to delete a Workload Policy authorization for a Control-M/EM user or role.

294
Control-M Administrator Guide

 To delete Workload Policy authorizations:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Workload Policy authorization for a Control-M/EM user, select the Users
tab and double-click the user contains the authorization that you want to delete.
• If you want to delete a Workload Policy authorization for a Control-M/EM role, select the Role tab
and double-click the role contains the authorization that you want to delete.
3. Select the Workload Policies tab and then select the Workload Policy authorization that you want to
delete.

4. Click .
A confirmation message appears.
5. Click Yes.

Service authorizations
Service authorizations grant users or groups of users access to view services, perform job actions, order,
hold, and release services.
When you add a service user authorization, the user automatically receives permission to view orderable
and non-orderable services that the user ordered.
NOTE: BMC Batch Impact Manager services appear by default in the Control-M Self Service GUI
application and override any service authorization limitation.
NOTE: If you want to utilize LDAP/active directory for adding your users, see Defining LDAP system
parameters (on page 47).
The following procedures describe how to assign, edit, and delete service authorizations:
 Assigning a Service authorization (on page 295)
 Editing a Service authorization (on page 296)
 Deleting a Service authorization (on page 296)

Assigning a Service authorization

This procedure describes how to assign a Service authorization for a Control-M/EM user or role, which
enables you to limit the actions a user can perform on a Service.
The options in the Active area of the Services window define the permissions that the specified
user/user role can perform on a service in the Control-M Web application. The options in the Definitions
area of the Services window determines the access level on a service in the Service definition manager.
 To assign a Service authorization:
1. Open the Control-M Configuration Manager.
2. From the Security tab, in the Security group, click Authorizations.

295
Control-M Administrator Guide

The Control-M/EM Authorizations window appears.

3. Do one of the following:
• If you want to define a Service authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to apply an authorization.
• If you want to define a Service authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to apply an authorization.

4. Select the Services tab and click .

The User Authorizations: Services dialog box appears.
5. In the Service field, type the names or name patterns for services.
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
6. In the Active area, select all the permissions and access level that apply to this user, as described in
Service authorizations field descriptions.and then click OK.
When you add a service user authorization, the user automatically receives permission to view
non-orderable services and orderable services that the user ordered.
The Service authorization appears in the User Authorization: <Control-M/EM user> window.

Editing a Service authorization

This procedure describes how to edit a Service authorization for a Control-M/EM user or role, which
enables you to limit the actions a user can perform on a Service.
 To edit a Service authorization:
1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to edit a Service authorization for a Control-M/EM user, select the Users tab and
double-click the user that you want to edit.
• If you want to edit a Service authorization for a Control-M/EM role, select the Role tab and
double-click the role that you want to edit.
3. Select the Services tab and then select the Service authorization that you want to edit.

4. Click .
The User Authorizations: Services dialog box appears.
5. Edit the required fields, as described in Service authorizations (on page 295), and then click OK.
The updated Service authorization appears in the User Authorization: <Control-M/EM user>
window.

Deleting a Service authorization

This procedure describes how to delete a Service authorization for a Control-M/EM user or role.

296
Control-M Administrator Guide

 To delete a Service authorization:

1. From the Security tab, in the Security group, click Authorizations.
The Control-M/EM Authorizations window appears.
2. Do one of the following:
• If you want to delete a Service authorization for a Control-M/EM user, select the Users tab and
double-click the user contains the authorization that you want to delete.
• If you want to delete a Service authorization for a Control-M/EM role, select the Role tab and
double-click the role contains the authorization that you want to delete.
3. Select the Services tab and then select the Service authorization that you want to delete.

4. Click .
A confirmation message appears.
5. Click Yes.

Role Based Administration authorizations

Role Based Administration allows Control-M Administrators to delegate control to users to carry out
specific administrative tasks on Control-M/Agents, Application Plug-ins,and Connection Profiles. Users can
create, configure, and monitor their resources from AAPI and Control-M Web, which eliminates the
dependencies on the Control-M Administrator. The Control-M Administrator can restrict access and control
to the users to their defined resources, without exposing other resources in the environment.
A Control-M Administrator can authorize the following capabilities to the user:
 Control-M/Agents: Control-M/Agents are assigned to users by a tag. A tag is a logical name that is
used to label specific Control-M/Agents into a group with a specific authorization level. You can only
define one tag per Agent.You can create and then apply a tag to a Control-M/Agent when it is defined
or after it is already connected. Users can define their own tags with the asterisk character if they
have the correct permissions. For example, if users have been assigned the Agent tag with the value
Fin*, they can define their own tag names when they add Control-M/Agents, such as FinDev or
FinOps.
 Application Plug-ins: Users are authorized to manage specific Application Plug-ins independently.
 Connection Profiles: Users are authorized to manage specific local or centralized connection
profiles without having access to the entire configuration of the organization.
 Run as Users: Users are authorized to define Run as Users based on specific Control-M/Servers.
For a detailed example of this concept, see Role Based Authorization scenario (on page 297).

Role Based Authorization scenario

The Big Data team uses Control-M for Hadoop and Application Integrator, spread across several
Control-M/Agents. The team has been granted the Full access level to Control-M/Agents with the tag
big_data. On these Control-M/Agents, the team is granted the permission to view and manage specific
Application Plug-ins and do not have access to any other. In addition, the team is granted access to
Hadoop and Application Integrator connection profiles, but only if the connection profile name starts with
BIGDATA. The team does not have access to AWS and Azure.

297
Control-M Administrator Guide

The Cloud team uses Control-M for AWS and Control-M for Azure spread across several Control-M/Agents.
The team has been granted the Full access level to Control-M/Agents with the tags AWS and Azure. On
these Control-M/Agents, the team is granted the permission to view and manage specific Application
Plug-ins and do not have access to any other. In addition, the team is granted access to AWS and Azure
connection profiles, but only if the connection profile name starts with AWS or Azure. The team does not
have access to BIGDATA.
The following tables illustrate the authorization differences between the two teams:
Agents

Control-M Agent Tag Access Level

* big_data Full

* Cloud Full

Application Plug-ins

Control-M Agent Tag Plug-in Type Access Level

* big_data Hadoop Full

* big_data myAIJob1 Full

* Cloud AWS Full

* Cloud Azure Full

298
Control-M Administrator Guide

Local Connection Profiles

Local connection profiles can use the tags that appear in the following example because they can be
mapped to specific local connection profiles that reside on the Control-M/Agents.

Name Control-M Agent Tag Plug-in Type

BIGDATA* Server1 big_data Hadoop

BIGDATA* Server1 big_data myAIJob1

* Server1 big_data Hadoop

AWS* Server1 Cloud AWS

Azure* Server1 Cloud Azure

* Server1 Cloud AWS, Azure

Centralized Connection Profiles

Centralized connection profiles are deployed to all Control-M/Agents. Therefore, you need to verify that
the Control-M and Agent Tag fields are set to *.

Name Control-M Agent Tag Plug-in Type

BIGDATA* * * Hadoop

BIGDATA* * * myAIJob1

* * * Hadoop

AWS* * * AWS

Azure* * * Azure

* * * AWS, Azure

Assigning a Role Based Administration authorization

This procedure describes how to assign a Role Based Administration authorization for a Control-M/EM
user or role, which enables you to limit the actions a user can perform in Control-M Web.
 To assign a Role Based Administration authorization:
1. Open the Control-M Configuration Manager.
2. From the Security tab, in the Security group, click Authorizations.

299
Control-M Administrator Guide

The Control-M/EM Authorizations window appears.

3. Do one of the following:
• If you want to define a Role Based Administration authorization for a Control-M/EM user, select
the Users tab and double-click the user that you want to apply an authorization.
• If you want to define a Role Based Administration authorization for a Control-M/EM role, select
the Role tab and double-click the role that you want to apply an authorization.

4. Select the Role Based Administration tab and click .

The User Authorizations dialog box appears.

5. In each section, click and define the parameters, as described in the following:
• Agents Management (on page 300)
• Plugins Management (on page 301)
• Connection Profile Management (on page 302)
• Run As Definition Management (on page 303)
NOTE: You can use pattern matching strings and an * to denote all values, as described in Pattern
matching strings.
6. Click OK.

Agents Management
The following table describes the parameters that define which Control-M/Agents a user has access to in
Control-M Web.

Parameter Description

Access Level Determines one of the following access levels for each user and
role.
 Browse: Enables the user to view and refresh objects in
Control-M Web
 Update: Enables the user to add, recycle, ping, disable, and
enable Control-M/Agents in Control-M Web.
 Full: Enables you to edit Control-M/Agents in Control-M Web,
in addition to all actions for Update.

Control-M/Server Defines the name of the Control-M/Server that is connected to the

selected Control-M/Agents.

Agent Tag Determines which Control-M/Agent tags the user has access to in
Control-M Web.

300
Control-M Administrator Guide

Plugins Management
The following table describes the parameters that define which Application Plug-ins a user has access to
in Control-M Web.

Parameter Description

Access Level Determines one of the following access levels for each user and
role.
 Browse: Enables the user to view and refresh objects in
Control-M Web
 Update: Enables the user to add, recycle, ping, disable, and
enable Application Plug-ins in Control-M Web.
 Full: Enables you to edit Application Plug-ins in Control-M
Web, in addition to all actions for Update.

Control-M/Server Defines the name of the Control-M/Server that is connected to the

selected Control-M/Agents.

Agent Tag Determines which Control-M/Agent tags the user has access to in
Control-M Web.

Plug-in Type Determines which Application Plug-ins a user has access to in

Control-M Web such as AWS or Database.

301
Control-M Administrator Guide

Connection Profile Management

The following table describes the parameters that define which Connection Profiles a user has access to in
Control-M Web.

Parameter Description

Access Level Determines one of the following access levels for each user and
role:
 Browse: Enables the user to view and refresh objects in
Control-M
 Update: Enables the user to add and edit objects in
Control-M
 Full: Enables the user to add, edit, and delete objects in
Control-M

Connection Profile Name Determines which connection profiles a user has access to in
Control-M Web.

Control-M/Server Defines the name of the Control-M/Server that is connected to the

selected Control-M/Agents.

Agent Tag Determines which Control-M/Agent tags the user has access to in
Control-M Web.

Plug-in Type Determines which Application Plug-ins a user has access to in

Control-M Web such as AWS or Database.

302
Control-M Administrator Guide

Run As Definition Management

The following table lists the Control-M/Servers that user has authorizations to create Run as users in the
Run as Users Authentication Settings in the CCM.

Parameter Description

Access Level Determines one of the following access levels for each user and
role.
 Browse: Enables the user to view and refresh objects in
Control-M Web
 Update: Enables the user to add, recycle, ping, disable, and
enable Run as Users in Control-M Web.
 Full: Enables you to edit Run as Users in Control-M Web, in
addition to all actions for Update.

Control-M/Server Lists the name of the Control-M/Server that the user has
authorizations to create Run as users in the Run as Users
Authentication Settings in the CCM.

Creating an administrator user

This procedure describes how to create a Control-M/EM administrator user when the external
authentication server is not available. If the LDAP or Active Directory can not be connected and an
emergency user is not defined, the new administrator can log in and have the authorizations and
privileges of a default administrator user.
 To create an administrator user:
1. Log in to the Control-M/EM server account and run the following script:
create_admin_account
2. In the Control-M/EM DBO name prompt, type the Control-M/EM database name (maximum length
is 30 characters).
3. In the Control-M/EM DBO password prompt, type the Control-M/EM password.
NOTE: If verification of the Control-M/EM DBO password fails, an error message is issued and the
script is aborted.
4. In the Control-M/EM administrator name prompt, type the name of the new user.
5. In the Control-M/EM administrator password prompt, type the new user password.
6. In the Control-M/EM administrator password verification prompt, type the same password again.

303
Control-M Administrator Guide

Changing the DBO password

This procedure describe how to change the Oracle, MSSQL, or PostgreSQL DBO password on UNIX and
Windows. You must perform this procedure on all Control-M/EM installations (primary, secondary, and
Control-M/EM Distributed) because they use the same database.
NOTE: If you are working in a High Availability environment, you must perform this procedure on the
active Control-M/EM first and then on all other Control-M/EM servers. The first time you perform this
procedure on the primary, you need the database administrator username and password.
 To change the DBO password:
1. Shut down all Control-M/EM components on all Control-M/EM installations (primary, secondary, and
Control-M/EM Distributed).
2. Run one of the following on the primary host and then on all the other host:
• UNIX:
{BMC_Install_folder}/ctm_em/bin/change_em_database_owner_password.sh
• Windows: {BMC_Install_folder}\Control-M
EM\Default\bin\change_em_database_owner_password.bat

Authorizing non-administrators to manage application

plug-in connection profiles
This procedure describes how to to define users or groups who can manage application plug-in
connection profiles without granting them unlimited configuration privileges.
NOTE: The permissions set using this procedure supersede the privileges defined in the User
Authorization window.
 To authorize non-administrators to manage application plug-in connection profiles:
1. Change the value of the restricted_cm_admin system parameter to 1, as described in Defining
Control-M/EM system parameters (on page 45).
2. Navigate to the following directory on where the CMS is running:
<emHome>\<instanceName>\ini
3. Type the required value for each tag, as described in cm_admin.xml parameters (on page 305).
You can use expressions such as a* or LIKE Bob for any of the fields.
For an example, see the sample_cm_admin.xml in the ini directory.
4. Save the file as cm_admin.xml.
5. Run the following command:
Ctl.exe -U EM_DBO -P EM_DBO_password -C CMS -name CMS -cmdstr
“REFRESH_CM_ADMIN_AUTH”
You must execute the above command every time the cm_admin.xml file is modified.

304
Control-M Administrator Guide

cm_admin.xml parameters
The following table describes parameters that are used in the cm_admin.xml file. To define these
parameters, see Authorizing non-administrators to manage application plug-in connection profiles (on
page 304).

Parameter Description

Name Defines the name of the Control-M/EM group or user that is

granted admin authorizations to the application plug-in

control_m Defines the Control-M server that interacts with the application
plug-in

node_id Defines the name of the Control-M/Agent node where the

application plug-in is installed

application_type Determines which application plug-in is used

NOTE: The relationship between more than one filter in the file uses OR logic. This means that groups or
users can manage application plug ins that answer any of the criteria in the list of filters.

305
6
6
High availability
Control-M High Availability enables you to maximize your production environment uptime and prevent
data loss in the event of hardware maintenance or failure.
Control-M supports the following high availability solutions:
 Control-M/EM and Control-M/Server high availability with Oracle/MSSQL/External PostgreSQL (on
page 307): Enables you to set up a secondary host with Control-M/EM or Control-M/Server. If there is
a hardware failure or if all Control-M/EM or Control-M/Server processes are down unexpectedly, the
secondary automatically (by default) or manually assumes control and resumes production.
 Control-M/Server high availability with a dedicated BMC PostgreSQL (on page 314): Enables you to
set up a secondary Control-M/Server and a secondary PostgreSQL database server for database
replication. If the primary Control-M/Server and database server are down, you can manually fail over
to the secondary host.
To set up your high availability environment, you must do the following:
 Install or use an existing Control-M/EM, Control-M/Server, or a Control-M full installation, as described
in Control-M full installation, Control-M/Enterprise Manager installation, and Control-M/Server
installation. If you want to configure High Availability using an External PostrgeSQL server, you must
install a fresh installation of Control-M/EM or Control-M/Server. You cannot upgrade because the
previous installations are using a dedicated PostreSQL server and BMC does not provide a way to
remove it.
 Install a secondary Control-M/EM, Control-M/Server, or a Control-M full installation, as described in
High availability installation.

Control-M high availability on one host

To ensure that Control-M continues to run when it is installed on one host, the Control-M/EM and
Control-M/Server Configuration Agent monitor and manage the following components in the CCM:

306
Control-M Administrator Guide

 Control-M/Server
 GUI Server (GSR)
 Gateway (GTW)
 Global Condition Server (GCS)
 Batch Impact Manager Server (BIM)
 Forecast Server
 Self Service Server
 Web Server
 Configuration Manager Server (CMS)
 Naming Service
 PostgreSQL database server
 Workload Archiving Server
 Services Configuration Agent
The Services Configuration Agent runs on all installations, such as primary, secondary, and distributed.
The Control-M/EM Configuration Agent verifies that the Services Configuration Agent is always up. On the
Non-Active host, it verifies all other services are stopped.THe Control-M/EM services (Service Health
Monitor, Reporting Facility, Validation Service, Zookeeper, Kafka, and Protocol Translator) run only on the
Active machine and are shutdown if there is a manual failover by the Services Configuration Agent.
If a Control-M/EM or Control-M/Server component goes down, the Configuration Agent attempts to start it
up (if desired state is set to Up), based on defined intervals, as described in Maintenance parameters (on
page 101) and High Availability parameters (on page 145).
If you are using a PostgreSQL database, the Configuration Agent manages the database component and
sends a life check every defined interval (see Maintenance parameters (on page 101) and High Availability
parameters (on page 145)). If there is no response after a defined number of attempts, the Configuration
Agent restarts the database automatically. If you are using an Oracle or MSSQL database, you can view
the database component in the CCM, but the Configuration Agent does not manage the component and
cannot start it up or shut it down.

Control-M/EM and Control-M/Server high availability with

Oracle/MSSQL/External PostgreSQL
After you have installed a secondary Control-M (see High availability installation), the Control-M/EM or
Control-M/Server Configuration Agent on the secondary host monitors the primary Control-M/EM or
Control-M/Server based on defined intervals. If there is no response from the primary, you can fail over to
the secondary in one of the following modes:

307
Control-M Administrator Guide

 Automatic failover (on page 311): The secondary Configuration Agent automatically takes control and
resumes production, when it detects that the primary Control-M/EM or Control-M/Server and its
primary Configuration Agent has stopped unexpectedly.
 Manual failover (on page 312): You can perform a manual failover at any time from the CCM if the
manual failover option is enabled. After the failover is complete, the production runs on the
secondary.
The following procedures describe how to manually fail over to a secondary host, pause Control-M/Server,
fall back to a primary host, and set secondary to Primary:
• Failing over a Control-M/EM or Control-M/Server to secondary (on page 313)
• Pausing Control-M/Server (on page 21)
• Falling back Control-M/EM or Control-M/Server to primary (on page 314)
• Setting a Secondary to Primary (on page 314)
NOTE: If you attempt to manually start up components on the secondary when the primary is active, the
components shut down automatically. This prevents both the primary and secondary from running
components simultaneously.
For a description of configurable Control-M/EM high availability system parameters, see Maintenance
parameters (on page 101). For a description of configurable Control-M/Server high availability system
parameters, see High Availability parameters (on page 145). To receive notifications about
Control-M/Server high availability events, see Control-M/Server general parameters (on page 142). To
receive notifications about Control-M/EM high availability events, see Control-M/EM general parameters
(on page 59).

Control-M/EM high availability architecture

The following diagram shows Control-M/EM in a high availability environment using an Oracle, MSSQL, or
external PostgreSQL database.

308
Control-M Administrator Guide

The following diagram shows a Control-M/EM automatic failover when the the primary components are no
longer available.

309
Control-M Administrator Guide

Control-M/Server high availability architecture

(Oracle/MSSQL/External PostgreSQL)
The following diagram shows Control-M/Server in a high availability environment using an Oracle, MSSQL,
or external PostgreSQL database.
NOTE: The Configuration Agent on the primary and secondary host communicate using port 2368. To
change this settling, see Communication parameters (on page 147).

The following diagram shows a Control-M/Server automatic failover when the the primary components are
no longer available.

310
Control-M Administrator Guide

See Also
Manual failover ............................................................................................................... 312

Automatic failover
An automatic failover occurs when the secondary Configuration Agent detects that the primary
Control-M/EM or Control-M/Server and its Configuration Agent is not alive and the production on the
primary has stopped unexpectedly. This can occur due to a hardware malfunction, machine crash, a
network card stops responding, or if all components are down.
Control-M/EM: To ensure that the primary Control-M/EM is not functioning, the following conditions
must be met before an automatic failover occurs (default: 60 seconds):

311
Control-M Administrator Guide

 There are no life check responses from all Control-M/EM components and the primary Configuration
Agent (see Maintenance parameters (on page 101)).
EXAMPLE: If HA_LIFECHECK_TRIES is set to 3, and each Check Interval for each Control-M/EM
component is set to 20, an automatic failover starts after 60 seconds. The production on the
secondary is ready after all the components are up and this time is determined by the
operating system, number of Control-M/Servers, and number of jobs.
 There are no transactions recorded in the database from all Control-M/EM components and its
primary Configuration Agent.
EXAMPLE: If all components are down and the Configuration Agent is up, an automatic failover does not
occur.
 The Oracle, MSSQL, or external PostgreSQL database is up.
Control-M/Server: To ensure that the primary Control-M/Server is not functioning, the following
conditions must be met before an automatic failover occurs (default: 60 seconds):
 There is no life check response from the primary Configuration Agent (see High Availability
parameters (on page 145)).
EXAMPLE: If HA_TIME_BETWEEN_LIFECHECKS is set to 15 (default) and
HA_LIFE_CHECK_TIMEOUT is set to 5 (default), the primary Configuration Agent is
considered not functioning after 20 seconds.
 There are no transactions recorded in the database from all running Control-M/Server processes and
its primary Configuration Agent.
EXAMPLE: If HA_LIFE_CHECK_TRIES is set to 3 (default), HA_TIME_BETWEEN_LIFECHECKS
is set to 15 (default) and HA_LIFE_CHECK_TIMEOUT is set to 5 (default), processes
are considered not writing to the database after 40 seconds ( (3-1) * (15 +5) )
EXAMPLE: If all Control-M/Server processes are down but the Configuration Agent is up, an
automatic failover does not occur.
 The Oracle, MSSQL, or external PostgreSQL database is up.

Manual failover
You can perform a manual failover at any time from the CCM if the manual failover option is enabled.
The following scenarios describe the required conditions for a manual failover to occur.
Oracle/MSSQL/External PosgreSQL: A manual failover can occur in one of the following scenarios:
 If the the primary Configuration Agent is running:
• The secondary Configuration Agent responds to life check requests from the primary
Configuration Agent.
• The database server is available for the Primary Configuration Agent.
 If the primary Configuration Agent is not running:
• The primary Control-M/Server is not running.
• The database server is available for the Secondary Configuration Agent.

312
Control-M Administrator Guide

Dedicated BMC PostgreSQL: A manual failover can occur in one of the following scenarios:
 If the the primary Configuration Agent is running:
• The secondary Configuration Agent responds to life check requests from the primary
Configuration Agent.
• The primary and secondary Configuration Agent has access to the shared directory.
 If the primary Configuration Agent is not running:
• The primary database server is not running.
• The secondary Configuration Agent has access to the shared directory.
• The secondary database server is available for the Secondary Configuration Agent.

Changing the Failover mode

This procedure describes how to change the failover mode from Automatic to Manual on Control-M/EM
and Control-M/Server. This enables you to determine when to shut down Control-M/EM or
Control-M/Server and perform a failover.
 To define failover mode:
1. Select the primary Control-M/EM or Control-M/Server component.
2. Right-click and select Properties.
The Control-M/EM Properties or Control-M/Server Definitions window appears.
3. From the Failover Mode drop-down list, select Manual.
4. Click Save.
The failover mode is now set to Manual, and a failover will not occur until you perform it manually, as
described in Failing over a Control-M/EM or Control-M/Server to secondary (on page 313).

Failing over a Control-M/EM or Control-M/Server to secondary

This procedure describes how to manually fail over a Control-M/EM or Control-M/Server to a secondary
host.
In manual mode, the secondary CA starts up the CMS.
NOTE: Control-M/EM and/or Control-M/Server must be using a MSSQL or Oracle database.

 To fail over to secondary:

1. From the High Availability tab, select the primary Control-M/EM or Control-M/Server component
and click Failover to Secondary.
A progress window appears listing each step in the failover process.
2. When the failover is complete, click Close.
Control-M/EM or Control-M/Server is now running on the secondary host.
3. If you want to revert to your original configuration, fix the problem on the primary and then fall back
to primary, as described in Falling back Control-M/EM or Control-M/Server to primary (on page 314).

313
Control-M Administrator Guide

Falling back Control-M/EM or Control-M/Server to primary

This procedure describes how to manually fall back a Control-M/EM or Control-M/Server to the primary
host.
NOTE: Control-M/EM and/or Control-M/Server must be using a MSSQL, Oracle, or external PostgreSQL
database.
 To fall back to primary:
1. On the primary host, start up the Configuration Agent.
2. From the High Availability tab, click Fallback to Primary.
A progress window appears listing each step in the fallback process.
3. When the fallback is complete, click Close.
Control-M/EM or Control-M/Server is now running on the primary host.

Setting a Secondary to Primary

This procedure describes how to set a secondary host to act as the primary host when the primary
installation is corrupted.
 To set a secondary to primary:
1. After a successful failover has occurred, from the High Availability tab, select the secondary and
click Set as Primary.
The secondary is now the new primary host.
2. Install a secondary on the original primary computer or on another computer, as described in High
availability installation.
The primary detects the new secondary, and you now have a new high availability configuration. You
can work with this configuration, but if you want to revert to your original configuration (the
secondary is installed on the original primary computer), continue to the next step.
3. Perform a failover from the new primary to the new secondary, as described in Failing over a
Control-M/EM or Control-M/Server to secondary (on page 313).
The secondary is now the active host.
4. From the High Availability tab, select the secondary and click Set as Primary.
You have now reverted to your original high availability configuration.

Control-M/Server high availability with a dedicated BMC

PostgreSQL
The Control-M/Server high availability solution with a dedicated BMC PostgreSQL database supports both
a manual failover of the Control-M server along with PostgreSQL database replication. Control-M/Server is
installed on the same host as the PostgreSQL database on the primary and on the secondary.

314
Control-M Administrator Guide

After the data replication is turned on and initialized successfully, the Control-M/Server database data is
replicated, synchronously to the secondary database server. However, if there are network
communication problems, the replication mode switches to Asynchronous. The data is replicated as well
to a shared drive, which is used if the primary or secondary are temporarily unavailable (see High
availability installation).
The secondary Configuration Agent monitors the primary to verify life check responses from
Control-M/Server and the primary Configuration Agent is working, based on defined intervals. You can
perform a manual failover at any time from the CCM if the manual failover option is enabled, based on the
conditions described in Manual failover (on page 312).
The following procedures describe how to start database replication, manually fail over to secondary, set
secondary as primary, pause Control-M/Server, and manually fall back to primary:
 Starting database replication (on page 317)
 Failing over Control-M/Server and PostgreSQL database server to secondary (on page 317)
 Setting a Secondary to Primary (on page 314)
 Pausing Control-M/Server (on page 21)
 Falling back Control-M/Server and PostgreSQL database server to primary (on page 317)
For a description of configurable Control-M/Server high availability system parameters and to receive
notifications about high availability events, see High Availability parameters (on page 145).

Control-M/Server high availability architecture (Dedicated BMC

PostgreSQL)
The following diagram shows Control-M/Server in a high availability environment using a dedicated BMC
PostgreSQL database.

315
Control-M Administrator Guide

NOTE: The Configuration Agent on the primary and secondary communicate using port 2368. To change
this settling, see Communication parameters (on page 147).

The following diagram shows a Control-M/Server manual failover when the the primary components are
no longer available.

316
Control-M Administrator Guide

Starting database replication

This procedure describes how to start the database replication process when it is not initialized or not
working. You will need to perform this procedure after you install a secondary, perform failover, or
fallback, or after a communication malfunction occurred between the primary and secondary database
servers.
 To start database replication:
1. From the High Availability tab, select the primary Control-M/Server component and click Start
Database Replication.
The Replication process initiates. After the initiation process is complete, the following message
appears in the Properties pane:
Database is replicated
2. Restart Control-M/Server, as described in Starting up a component (on page 41).
The database continues to replicate to the secondary in synchronous mode. If there are network
communication problems, the replication mode switches to Asynchronous. After the network problems
are resolved, click Switch to Sync Replication to continue replicating in synchronous mode.

Failing over Control-M/Server and PostgreSQL database server to

secondary
This procedure describes how to manually fail over the Control-M/Server and PostgreSQL database server
to a secondary host.
 To fail over to secondary:
1. From the High Availability tab, select the primary Control-M/Server component and click Failover
to Secondary.
A progress window appears listing each step in the failover process.
2. When the failover is complete, click Close.
The Control-M/Server and database server is now running on the secondary host.
3. If you want to revert to your original configuration, fix the problem on the primary and then fall back
to primary, as described in Falling back Control-M/Server and PostgreSQL database server to primary
(on page 317).

Falling back Control-M/Server and PostgreSQL database server to

primary
This procedure describes how to manually fall back the Control-M/Server and PostgreSQL database server
to the primary host after the primary is fixed and is up and running.
 To fall back to primary:
1. On the primary host, start up the Configuration Agent.

317
Control-M Administrator Guide

2. Start database replication from the secondary to the primary, as described in Starting database
replication (on page 317).
3. From the High Availability tab, select the primary Control-M/Server component and click Fallback
to Primary.
A progress window appears listing each step in the fallback process.
4. When the fallback is complete, click Close.
The Control-M/Server and database server is now running on the primary host.
5. Resume database replication from the primary to the secondary, as described in Starting database
replication (on page 317).

318
Control-M Administrator Guide

High availability scenarios

The following table describes the possible scenarios in a high availability environment.

Scenario System action User action

PostgreSQL database is down The primary Configuration Agent You can perform a manual
tries to start it up. failover, as described in Failing
over Control-M/Server and
PostgreSQL database server to
secondary (on page 317).

Oracle/MSSQL database is down An automatic failover does not

occur.

Primary crashes (PostgreSQL) You can perform a manual

failover, as described in Failing
over Control-M/Server and
PostgreSQL database server to
secondary (on page 317).

Primary crashes (Oracle/MSSQL) An automatic failover occurs,

based on the conditions
described in Automatic failover
(on page 311).

Shared directory is not available Manual failover is disabled.

(PostgreSQL)

Reconnecting Control-M/Server After a secondary N/A

to Control-M/EM after a Control-M/Server is installed,
failover/fallback of Control-M/EM is provided with
Control-M/Server the secondary host. If there is a
disconnection between
Control-M/EM and
Control-M/Server, a check is
performed to see if
Control-M/Server has failed over
to the secondary (or primary if it
is a fallback).

319
Control-M Administrator Guide

Scenario System action User action

Reconnecting Control-M/EM After the CCM or Control-M GUI N/A

clients connects to the GUI server or
CMS, the secondary host details
are distributed to the clients.If
there is a disconnection, a check
is performed automatically to
see if the GUI Server and CMS
have failed over to the
secondary (or primary if it is a
fallback).

Reconnecting Control-M Web Type the Web client URL of the

clients: secondary host.
 Control-M Self Service
 Control-M

Control-M/EM failover fails to Run the following command on

complete. the primary host:
em emcha -restore primary

320
7
7
Alerts
The following are types of alerts in Control-M:
• Shouts: Shouts are alerts that relate to job processing problems and you can define their
settings in the Shout Destination Manager. For more information, see Shout destination
management (on page 321).
• Exception alerts: Alerts that notify you of system failures in the database, communication
network, and application errors and failures. You can handle these exception alerts as necessary
in the Exception Alerts window. The Exception Alerts window displays information about each
alert, such as the alert ID, severity of the alert, the message that was generated by the alert, and
more. For more information, see Managing exception alerts (on page 324).
Alerts are deleted automatically after they reach the threshold in the database. You can also delete alerts
manually if necessary,(example: low disk space), as described in Removing old alerts (on page 325).

Shout destination management

A shout is a notification of the job's status. There are two types of shouts. Shouts that are sent out before
a job ends, and shouts that are sent out after a job ends. For example, in Control-M, after you create a
job, you can assign a shout to the job to indicate if the job's running time is delayed. When you assign a
shout to a job, you also need to assign a destination to it. In Control-M, after you created the job and
assigned a shout to it, you assign the destination you want the shout to be sent to, such as log.
In the Shout Destination Manager, you can define the destinations you want the shouts to go to. Shout
destinations are grouped in tables to enable you to define specific destinations for the shouts and to send
the shouts to a number of destinations.
Each shout destination table can contain a number of destinations. You can create any number of shout
destination tables, but only one of them can be designated as the active shout destination table at any
given time. If you set the destination table as active, the shouts are sent only to the destinations you
specified in that table. If you change the designation of the active table, you change the delivery of the
shouts to different destinations you defined in the other table.
The following procedures describe how to create edit, delete, and set shout destination tables and shout
destinations.
 Creating a shout destination table (on page 322)
 Editing a shout destination table (on page 322)
 Deleting a shout destination table (on page 322)
 Setting a shout destination table as active (on page 323)
 Creating a shout destination (on page 323)
 Deleting a shout destination (on page 324)
You can also use following utilities to manage shout destinations:

321
Control-M Administrator Guide

 ctmshout: Sends a shout message to a specified user or destination, using the specified severity level
as described in ctmshout.
 ctmsys utility: Defines and maintains shout destination tables, as described in ctmsys.

Creating a shout destination table

This procedure describes how to create a shout destination table, which enables you to add, edit, and
delete shout destinations.

 To create a shout destination table:

1. From the Manage tab, in the Alerts group, click Shout Destination.
The Shout Destination Manager window appears.
2. From the Actions menu, select Add Shout Table.
The Shout Destination New Table window appears.
3. In the New Table Name field, type a name for the shout destination table, and then click OK.
The Shout Destination List Editor window appears where you can create shout destinations, as
described in Creating a shout destination (on page 323).

Editing a shout destination table

This procedure describes how to edit a shout destination table, which enables you to add, update, and
delete shout destinations in the specified shout destination table.

 To edit a shout destination table:

1. From the Manage tab, in the Alerts group, click Shout Destination.
The Shout Destination Manager window appears.
2. From the list of shout destination tables, select the shout destination table to edit.
3. From the Actions menu, select Update Shout Table.
The Shout Destination List Editor window appears.
4. From the Shout Destination List Editor window, do one of the following:
• Creating a shout destination (on page 323)
• Deleting a shout destination (on page 324)
5. Click Close.
The shout destination table is updated.

Deleting a shout destination table

This procedure describes how to delete a shout destination table.

 To delete a shout destination table:

1. From the Manage tab, in the Alerts group, click Shout Destination.

322
Control-M Administrator Guide

The Shout Destination Manager window appears.

2. From the list of shout destination tables, select the shout destination table to delete.
3. From the Actions menu, select Delete Shout Table.
A confirmation message appears.
4. Click Yes.
The shout destination table is deleted.

Setting a shout destination table as active

This procedure describes how to set a shout destination table as active, which enables you to send shouts
to the shout destinations you defined in the specified shout destination table.
 To set a shout destination table as active:
1. From the Manage tab, in the Alerts group, click Shout Destination.
The Shout Destination Manager window appears.
2. From the list of shout destination tables, select the shout destination table to set as the active table.
3. From the Actions menu, select Set Active Shout Table.
A confirmation message appears.
4. Click Yes.
The specified shout destination table is set to active.

Creating a shout destination

This procedure describes how to create a shout destination, which enables you to add a shout destination
to the specified shout destination table.
 To create a shout destination:
1. Do one of the following:
• If you have reached the Shout Destination List Editor window after you created a shout
destination table, continue to step 3.
• From the Manage tab, in the Alerts group, click Shout Destination
The Shout Destination Manager window appears.
2. From the list of shout destination tables, select the shout destination table to edit.
3. From the Actions menu, select Add Shout Destination.
The New Destination properties window appears.
4. In the Logical Name field, type a logical name up to 16 characters, case sensitive.
5. From the Address drop-down list, select Server or Agent.
6. From the Destination drop-down list, select the destination.
7. In the Value field, type the destination.

323
Control-M Administrator Guide

8. Click OK.
The shout destination is created.

Deleting a shout destination

This procedure describes how to delete a shout destination, which enables you to remove shout
destinations from the specified shout destination table.
 To delete a shout destination:
1. From the Manage tab, in the Alerts group, click Shout Destination.
The Shout Destination Manager window appears.
2. From the list of shout destination tables, select the shout destination table to edit.
3. From the Actions menu, select Update Shout Table.
The Shout Destination List Editor window appears.
4. Select the shout destination to delete.
5. From the Actions menu, select Delete Shout Destination.
A confirmation message appears.
6. Click Yes.
The shout destination is deleted.

Managing exception alerts

This procedure describes how to manage alerts, which enables you to view information about each alert,
change the alert status, remove old alerts, add notes, and set additional options to alerts.
 To manage exception alerts:
1. From the Manage tab, in the Alerts group, click Exception Alerts.
The Exception Alerts window appears.
2. From the alerts list, select an alert.
3. From the X-Alert menu you can do the following:
• Select Properties to view properties of the alert such as Alert ID, Severity, Time, Message,
and more. You can also add a note to the alert in the Note field.
• Select Handle to mark an alert as viewed and handled.
• Select Unhandle to mark an alert as unhandled.
4. From the Tools menu, you can do the following:
• Select Remove Old Alerts and define the number of days to delete old alerts in the Remove
X-Alerts older than x days ago field.
• Select Options and do the following:
a. In the Refresh view every x seconds field define the time in seconds to refresh the view.

324
Control-M Administrator Guide

b. From the On new X-Alert do x drop-down list, select one of the options when a new alert
appears.

Removing old alerts

This procedure describes how to remove old alerts manually.

 To remove old alerts:

1. From the Manage tab, in the Alerts group, click Remove Old Alerts.
The Remove Old Alerts window appears.
2. From the Date drop-down list, select the date to delete all alerts posted on or before the specified
date, and then click OK.
The GUI Server must be refreshed for the alerts to be removed.

Sending alerts and xAlerts to an event management

system
This procedure describes how to send alerts and xAlerts to your organization's event management system
via SNMP.
For a detailed list of trap variables, see SNMP trap format (on page 326).

 To send alerts and xAlerts to an event management system:

1. Copy the Control-M/EM MIB file from the following location to your SNMP server.
Control-M EM 9.0.20\Data\ BMC-CONTROLMEM-MIB.txt
2. From the CCM, define the following system parameters, as described in Defining Control-M/EM system
parameters (on page 45):
• SNMPHost: Define the hostname of the SNMP server where the alerts are sent.
• SNMPSendActive: Change the value to 1 to generate SNMP messages for Active Alerts.
• SendSNMP: Change the value to 0 to send alerts to SNMP server only.
• SendAlertNotesSnmp: Change the value to 1 if you want to send the NOTES field to the SNMP
server.
• XAlertsEnableSending: Change the value to 1 to enable xAlert sending.
• XAlertsSnmpHosts: Define the hostname of the SNMP server where the xAlerts are sent.
• XalertsSendSnmp: Change the value to 1 to send xAlerts to SNMP server only.
For more information about Alert parameters, see Control-M/EM general parameters (on page 59).
3. Recycle the Gateway.
4. To test an alert, order a job that sends a notification to the Alerts window.

325
Control-M Administrator Guide

SNMP trap format

The following table describes SNMP variable that Control-M/EM uses to send alerts to an event
management system via SNMP, as described in Sending alerts and xAlerts to an event management
system (on page 325).

# Field Description

1 UPDATE TYPE Single character indicating the

type of event that triggered the
alert:
 I-A new alert was issued.
 U- An existing alert was
updated

2 ALERT ID Numeric value used as a key

(index) to identify the alert.

3 CONTROLM Name of the data center to

which the job belongs.

4 MEMNAME Mem Name of the job.

5 ORDERID Order ID of the job.

6 SEVERITY Severity of the alert:

 V — Very urgent
 U — Urgent
 R — Regular

7 STATUS Values:
 Not noticed
 Noticed
 Handled

8 TIME Time and date that the alert was

issued.
Format: yyyymmddhhmmss

9 USER Name of the user who last

modified the status or text of
the alert

326
Control-M Administrator Guide

# Field Description

10 UPDATE TIME Time and date that the alert was

last modified by the user

11 MESSAGE Full text of the alert

12 OWNER Owner of the job

13 GROUP Group of the job

14 APPLICATION Application of the job

15 JOB NAME Name of the job

16 NODE ID Node or host where the job is

run

17 TYPE Alert type. Valid values:

 R - Regular (Can also be
empty). Default.
 B - BIM

18 CLOSED FROM EM Initial value is empty. If the a

Remedy ticket was closed from
Control-M/EM, the value is Y.

19 TICKET NUMBER Remedy ticket number

20 RUN COUNTER When a job is executed more

than once within a scheduling
day, this counter uniquely
identifies each execution of that
job.
This way you know exactly in
what instance of the job’s
execution the remedy ticket was
opened.

21 NOTES Displays the text that can be

edited and saved in
Control-M/EM Alerts window.
Enable SendAlertNotesSnmp
parameter (set to 1).

327
Control-M Administrator Guide

Sending Alerts and xAlerts to a script

This procedure describes how to send alerts and xAlerts to a script.
 To send alerts and xAlerts to a script:
1. From the CCM, define the following system parameters, as described in Defining Control-M/EM system
parameters (on page 45):
• SendAlarmToScript: Define the full path name of the script that is activated when an alert is
generated.
• SendSNMP: Change the value to 1 to send alerts to a script only.
• SendAlertNotesSnmp: Change the value to 1 if you want to send the NOTES field to a script.
• SNMPSendActive: Change the value to 1 to generate SNMP messages to a script.
• XAlertsEnableSending: Change the value to 1 to enable xAlert sending.
• XAlertsSend2Script: Define the full path name of the script that is activated when an xAlert is
generated.
• XalertsSendSnmp: Change the value to 2 to send xAlerts to a script only.
For more information about Alert parameters, see Control-M/EM general parameters (on page 59).
2. Recycle the Gateway.

Usage alerts
Usage alerts enable you to send alerts when the number of tasks in a Control-M/Enterprise Manager
environment exceed the permitted limit of tasks in the Active Jobs file. You can specify the following:
 The platforms you want to set the task count and alerts for, depending on which platforms you have.
If you have both a Control-M for z/OS and Control-M for Distributed Systems platforms, you can
choose the all platforms option. For more information, see Creating a usage alert (on page 329).
 The number of tasks allowed per day on all Control-M/Enterprise Manager environments, as described
in Creating a usage alert (on page 329).
 The percentage of the permitted tasks that when exceeded an alert is issued, as described in Creating
a usage alert (on page 329).
 The recipients that receive the alert notification if task count is exceeded, as described in Creating a
usage alert (on page 329).
 All Control-M/Enterprise Manager environments that are in use, to manage task counts on, and send
alerts when the task count exceeds the permitted limit. For more information, see Adding a usage
alert environment (on page 329).
If the number of permitted tasks is exceeded, an alert is sent to the recipients you specified.

328
Control-M Administrator Guide

Creating a usage alert

This procedure describes how to create a usage alert, which enables you to set alerts when the number
of tasks in a platform exceeds the permitted limit.
 To create a usage alert:
1. From the Manage tab, in the Alerts group, select Usage Alerts.
The Usage Alerts window appears.
2. Select the Alerts tab.
3. Select the Enable Alerts checkbox.

4. Select the platform you want to set up alerts for, and then click .
If you have both a Control-M for z/OS and a Control-M for Distributed Systems platform, select the
Alerts for all platforms option.
5. In the Task Count field, set the number of permitted tasks.
6. In the Alert when task count exceeds field, set the percentage of the permitted tasks that when
exceeded an alert is issued.
7. In the Alert e-mail recipients field, type the e-mail addresses of the recipients of the alert.
If adding multiple e-mails, type each e-mail separated with ;.
8. Click Save.
The usage alert is created.

Deleting a usage alert

This procedure describes how to delete a usage alert.

 To delete a usage alert:

1. From the Manage tab, in the Alerts group, select Usage Alerts.
The Usage Alerts window appears.
2. Select the Alerts tab.
3. Select the alert you want to delete.

4. Click .
The usage alert is deleted.

Adding a usage alert environment

This procedure describes how to add a usage alert environment, which enables you to manage task
counts on all Control-M/Enterprise Manager environments and send alerts when the task count exceeds
the permitted limit.

329
Control-M Administrator Guide

 To add a usage alert environment:

1. From the Manage tab, in the Alerts group, select Usage Alerts.
The Usage Alerts window appears.
2. Select the Enterprise Manager tab.

3. To add an environment, click .

4. Define the required parameters, as described in Enterprise Manager parameters (on page 330).
5. Click Test Connectivity, to check that the environment is available.
A message appears confirming that the environment is available. If the environment is unavailable,
the test fails, and you will not be able to save your alert settings.
6. Click Save.
The environment is added.

Enterprise Manager parameters

The following table describes the Enterprise Manager parameters.

Parameter Description

Environment Name Defines a logical display name for Control-M/EM.

Database type Defines the database type of the installation. From the dropdown
list select one of the databases.

Host Defines the database host in a Control-M/EM installation. Can be

the current installation or a remote EM.

Port Defines the database server port number for the Control-M/EM
installation.

User Name Defines the user name name of the database.

Password Defines the password of the database.

Database/Inst..  PostgreSQL: Defines the specific installation internal

database name in the database.
 Oracle: Defines the Server ID (SID) of the Oracle Database
Server.
 MSSQL: Defines the Instance name of the database.

330
Control-M Administrator Guide

Deleting a usage alert environment

This procedure describes how to delete a usage alert environment from the Enterprise Manager usage
alerts list.
 To delete an environment:
1. From the Manage tab, in the Alerts group, select Usage Alerts.
The Usage Alerts window appears.
2. Select the Enterprise Manager tab.
3. Select the environment you want to delete.

4. Click .
The environment is deleted.

331
8
8
Host group management
A host is a computer that can run jobs and a host group is a collection of hosts, which enable you to
define and run jobs on any of the computers within the host group.
For example, if you have a job that might require more resources than the host ID where the job runs,
you can define the job to run on host group. If the host ID is not able to handle the job, it is routed to
another host, which has more resources, or the job is set to a Wait status. For more information, see
Host groups (on page 332).
You can implement load balancing with Host restrictions, which enable you to limit the number of jobs
submitted to a specific host according to a defined CPU usage limit and the number of concurrently
running jobs on a host . This helps you manage your resources and prevent them from being overloaded
and indicates when a host resource is not used efficiently. For more information, see Host group
restrictions (on page 334).

Host groups
A host is a computer that can run jobs and a host group is a collection of hosts, which enable you to
define and run jobs on any of the computers within the host group.
For example, if you have a job that might require more resources than the host ID where the job runs,
you can define the job to run on host group. If the host ID is not able to handle the job, it is routed to
another host, which has more resources, or the job is set to a Wait status.
The load on any host computer or host group can be controlled. You can limit the usage of a host and the
specific times when those limitations are applied. A host’s participation in a host group can also be
defined for specific times. This helps you control the hosts available to the jobs in the active environment.
The following procedures describe how to create, edit, delete host groups, and remove hosts from host
groups:
 Creating a host group (on page 332)
 Editing a host group (on page 333)
 Deleting a host group (on page 334)
 Removing a host from the host group (on page 334)

Creating a host group

This procedure describes how to create a host group, which enables you to run a job on a host group
instead of a specific host.
 To create a host group:
1. From the Manage tab, in the Hosts Management group, click Hosts Manager.
The Hosts Manager window appears.

332
Control-M Administrator Guide

2. From the Hosts Group tab, click .

The New Host Group window appears.
3. In the Host Group Name field, type the name of the host group.
4. In the Application Type Filter drop-down list, select the type of jobs that you want to run on the
host group.
Only the hosts that can run the specific job that you selected appear. For example, if you select a
Control-M for SAP job type, then only the hosts that have Control-M for SAP installed appear in the
filter.
If you are creating a host group for regular script or command jobs, select OS.
5. In the Nonassociated Hosts area, select the hosts that you want to be part of the group and then

click .
All of the hosts in the group with the same Application Type Filter, must have the same Application
Plug-in version, including fix pack number. For example, if you select Control-M for Databases, then
make sure that all the hosts in the group have the same version of Control-M for Databases.
6. In the Associated Hosts area, select a host that you want to apply active definitions.
This determines when a job can run on the host based on days, hours, or conditions.

7. Click .
The Host Settings window appears.
8. Do one of the following:
• In the Date & Time Settings area, select the time frame when a job can run on the host.
• In the Conditions area, type the name of the condition and select a condition date when a job
can run on the host.
9. Click OK.
The host setting appears in the Participation Definitions area.
10. Click OK.
The host group appears in the Host Group tab.

Editing a host group

This procedure describes how to edit a host group, which enables you to run a job on a host group
instead of a specific host.
 To edit a host group:
1. From the Manage tab, in the Hosts Management group, click Hosts Manager.
The Hosts Manager window appears.
2. From the Hosts Group tab, select the host group that you want to edit and then click .
The Update Host Group dialog box appears.
3. Edit the required fields, as described in Creating a host group (on page 332).

333
Control-M Administrator Guide

4. Click OK.

Deleting a host group

This procedure describes how to delete a host group.
 To delete a host group:
1. From the Manage tab, in the Hosts Management group, click Hosts Manager.
The Hosts Manager window appears.

2. From the Hosts Group tab, select the host group that you want to delete and then click .
A confirmation message appears.
3. Click Yes.
The host group is deleted.

Removing a host from the host group

This procedure describes how remove a host from a host group, which disables the host from jobs
running on the host group that contained the host.
 To remove a host from the host group:
1. From the Manage tab, in the Hosts Management group, click Hosts Manager.
The Hosts Manager window appears.

2. From the Hosts Group tab, select the host that you want to remove and then click .
A confirmation message appears.
3. Click Yes.
The host is removed from the host group.

Host group restrictions

Host restrictions enable you to limit the number of jobs submitted to a specific host according to a defined
CPU usage limit and the number of concurrently running jobs on a host. This helps you manage your
resources and prevent them from being overloaded and indicates when a host resource is under used.
NOTE: Host restrictions for CPU are only enforced on jobs in the active jobs database if you are using
Control-M/Agent version 7.0.00 and higher.
To sample the CPU on UNIX computers, use the SAR utility. For AIX computers, the Control-M/Agent must
run as root as the SAR utility needs root authorization.

334
Control-M Administrator Guide

Defining host group restrictions

This procedure describes how to define host group restrictions, which enable you to limit the number of
jobs submitted to a specific host according to a defined CPU usage limit and the number of concurrently
running jobs on a host.
 To define host group restrictions:
1. From the Manage tab, in the Hosts Management group, click Hosts Manager.
The Hosts Manager window appears.
2. Click the Hosts Restrictions tab.

3. Click .
The Hosts Restrictions Definitions dialog box appears.
4. Do the following:
a. In the Host(s) field, type the name of the host that you want to apply the restriction(s).
You can also enter the host prefix followed by the wildcard “*”.
b. In the Maximum CPU Utilization% field, select the maximum percentage of CPU usage for the
host.
c. In the Maximum Concurrent Jobs field, select the maximum number of jobs that can be
running on the host concurrently.
5. Click OK.

Editing host group restrictions

This procedure describes how to edit host group restrictions, which enable you to limit the number of jobs
submitted to a specific host according to a defined CPU usage limit and the number of concurrently
running jobs on a host.

 To edit host group restrictions:

1. From the Manage tab, in the Hosts Management group, click Hosts Manager.
The Hosts Manager window appears.
2. Click the Hosts Restrictions tab.
3. Click .
The Hosts Restrictions Definitions dialog box appears.
4. Edit the required parameters, as described in Defining host group restrictions (on page 335).

Deleting host group restrictions

This procedure describes how to define host group restrictions.
 To delete host group restrictions:
1. From the Manage tab, in the Hosts Management group, click Hosts Manager.

335
Control-M Administrator Guide

The Hosts Manager window appears.

2. Click the Hosts Restrictions tab.
3. Type the name of the host group in the Host(s) field.
4. Select the restriction that you want to delete.

5. Click .
A confirmation message appears.
6. Click OK.

336
9
9
Control-M deployment
In Control-M, you can deploy the following components:
 Control-M/Agents:The Control-M/Agent Deployment tool enables you to automatically upgrade
multiple Control-M/Agents from one single point of access, as described in Control-M/Agent
deployment (on page 337).
 Control-M MFT: The Control-M MFT Deployment tool enables you to automatically install and
upgrade Control-M MFT on multiple Control-M/Agents from one single point of access, as described in
Control-M MFT deployment (on page 342).
 Application Pack: The Application Pack Deployment tool enables you to automatically install and
upgrade Application Plug-ins on multiple Control-M/Agents from one single point of access, as
described in Application Pack deployment (on page 344).
 Control-M Client:The Client Distribution tool that enables you to deploy a single instance of
Control-M/EM client components over the Web to every supported Windows computer in your
organization, as described in Client Distribution (on page 350).
Chapter

Control-M/Agent deployment
The Control-M/Agent Deployment tool enables you to automatically upgrade multiple Control-M/Agents
from one single point of access.
From the CCM, you can transfer Control-M/Agent software packages to multiple Control-M/Agents. After
the transfer, you can then upgrade the Control-M/Agents to version 9.0.20 and higher on UNIX and
Windows, and to version 7.0.01 and higher on AS400.
The following procedures describe how to set up the software packages, upgrade, and downgrade
Control-M/Agents:
 Copying Control-M/Agent installation packages (on page 338)
 Upgrading Control-M/Agents (on page 339)
 Rolling back Control-M/Agents (on page 340)
For a description of configurable deployment parameters, see Deployment parameters (on page 144),
Control-M/Agent deployment parameters (on page 190), and Control-M/EM general parameters (on page
59).

337
Control-M Administrator Guide

NOTE:
 If the Control-M/Agent windows service is set to Log on as > This account, the upgrade must be
performed with this user.
 To run a deploy activity in the CCM or in a CLI, you must have full access level in the Configuration
and Operation privileges, as described in Privileges (on page 273).
 To upgrade to Control-M/Agent 9.0.20, Control-M/Agent 8.0.00 or higher must be installed.
 You cannot upgrade more than one Control-M/Agent on the same Windows computer simultaneously.
 BMC recommends to perform the Agent deployment in groups. By default, you can
upgrade/downgrade 5 Control-M/Agents simultaneously. To change this configuration, see the
DEPLOYMENT_THREADS parameter, as described in Deployment parameters (on page 144).
 In Windows, when deploying on Control-M/Agent with a very high load of jobs, deployment may fail.
You must run the upgrade at a later stage, when the Control-M/Agent is not loaded or install with
downtime. If you deploy, upgrade fails with the following message:
-------------------------------Pay
Attention--------------------------------------------
Installation with no downtime cannot be executed at this moment.
1. Check communication between Control-M/Agent and Control-M/Server.
2. Run the ctmagcfg utility. In Advanced parameters, verify that the
Logical Agent Name value matches the Control-M/Agent Name defined in the
Control-M/Server and rerun the installation again.
3. To install with downtime, shut down the Control-M/Agent processes and
rerun the installation again.

Copying Control-M/Agent installation packages

This procedure describes how to copy Control-M/Agent installation packages for each platform and place
them in the Control-M/EM repository. This enables you to upgrade multiple Control-M/Agents from
different platforms and versions to the latest version and fix pack.
 To copy Control-M/Agent installation packages:
1. Download the Control-M/Agent installation packages via EPD
athttps://www.bmc.com/available/epd.html.
You need to download the required package for each platform that you want to upgrade. Do not
rename the installation package.
2. Do one of the following:
• If you want to save the installation packages to the Control-M/EM computer, copy the installation
package to the $EM_HOME/AUTO_DEPLOY directory on the computer where the CMS is
installed.
EXAMPLE: /home/one900a/ctm_em/AUTO_DEPLOY
• If you want to save the installation packages to a specific network location, define the
CentralDeployLocation system parameter, as described in Defining Control-M/EM system
parameters (on page 45).

338
Control-M Administrator Guide

NOTE: Verify that the Control-M/EM user that is defined in the Control-M/EM Configuration Agent
Windows service is set to This account and has access to the relevant network location.
3. Restart the New Activity Upgrade wizard.

Upgrading Control-M/Agents
This procedure describes how to transfer installation packages to existing Control-M/Agents and upgrade
them to the current base version or fix pack on UNIX, Windows, or AS400.
NOTE: (Windows only) An upgrade does not begin until all jobs have ended, unless you selected Force
Upgrade in a Retry (Control-M/Agent 9.0.00 or earlier).
NOTE: You cannot upgrade more than one Control-M/Agent on the same Windows computer
simultaneously.
 To upgrade Control-M/Agents:
1. From the Manage tab, select Deployment.
The Deployment window appears.
2. Click New Activity > Agent> Upgrade.
The Upgrade Control-M Agents Activity window appears.
3. Do the following:
a. In the Activity Name field, accept the default or type a new name for this activity.
b. In the Description field, describe the purpose of this activity (optional).
c. In the E-Mail Notification field, type the email address(es) that you want to receive notifications
about this activity (optional).
To receive email notification, you need to define the email server parameters, as described in
SMTP parameters (on page 174).
4. Select one of the following:
• Send Agent Deploy to Control-M Agent(s): Transfers the installation package to specific
Control-M/Agent computers. After the package is transfered, you can manually start the upgrade
process, at any time, from the Agent Deployment window or upgrade with CLI, as described in
ccmcli.
• Send and Install Agent Deploy to Control-M Agent(s): Transfers the installation package to
specific Control-M/Agent computers and begins the upgrade process automatically.
NOTE:
 The Control-M/Agent installation package is deleted after a successful upgrade. If the upgrade
failed or you performed a transfer only, then the installation package remains on the
Control-M/Agent computer for 30 days. If you want to change this setting, define the
Control-M/Agent system parameter AD_RETAIN_PACKAGES, as described in Defining
Control-M/Agent system parameters (on page 189).
 The Control-M/Agent installation package remains on the Control-M/Server computer for 30 days.
If you want to change this setting, define the Control-M/Server AD_RETAIN_PACKAGES, as
described in Defining Control-M/Server system parameters (on page 141).

339
Control-M Administrator Guide

5. Click Next.
6. From the Upgrade Agents to Version drop-down list, select the version or fix pack that you want to
upgrade to and then select the Control-M/Agent(s) that you want to upgrade.
The list of values depends on the Agent installation packages in your repository. For more
information, see Copying Control-M/Agent installation packages (on page 338).
7. Depending on which method you selected, click Transfer or Upgrade.
The transfer process starts and progress messages appear in the right pane of the deployment
activity. To view and troubleshoot the internal stages of the upgrade, click Log from the Agent
Deployment window. If you selected to transfer the installation package, you can upgrade the
Control-M/Agent(s) any time after the transfer is complete. A job runs on the Control-M/Agent(s) to
verify that it upgraded successfully.

Rolling back Control-M/Agents

This procedure describes how to roll back Control-M/Agents to their original version prior to the upgrade,
if there was a problem with the upgrade. You can only roll back Control-M/Agents that were upgraded
with the Control-M/Agent Deployment tool.
This procedure must be done within a defined period based on the AD_GA_RETAIN_DAYS system
parameter, as described in Control-M/Agent deployment parameters (on page 190).
Before you begin
 Verify that all jobs on the selected Control-M/Agents have ended. If jobs are still running during the
rollback, they might fail.
 To roll back Control-M/Agents:
1. From the Manage tab, select Deployment.
The Deployment window appears.
2. Click New Activity > Agent > Rollback.
The Rollback Control-M Agents Activity window appears.
3. Do the following:
a. In the Activity Name field, accept the default or type a new name for this activity.
b. In the Description field, describe the purpose of this activity (optional).
c. In the E-Mail Notification Address field, type the email address(es) that you want to receive
notifications about this activity (optional).
To receive email notification, you need to define the email server parameters, as described in
SMTP parameters (on page 174).
NOTE: Any configuration changes that you might have made after the upgrade will be lost when you
roll back to the previous version including the updating the primary or secondary Control-M/Server or
communication port.
4. Click Next.
5. From the Rollback Agents from Version drop-down list, select the version or fix pack that you
want to roll back from and then select the Control-M/Agent(s) that you want to roll back.

340
Control-M Administrator Guide

6. Click Rollback.
The rollback process begins immediately and is rolled back to the previous version. To view and
troubleshoot the internal stages of the rollback, click Log from the Agent Deployment window.

Cancelling a deploy activity

This procedure describes how to cancel a transfer, upgrade, or downgrade deployment activity. The
cancel operation does not happen immediately upon execution. The current phase of the activity is
completed, but the next phase is canceled.
EXAMPLE: The downgrade process has two phases: preparation and downgrade. If you click Cancel
during the preparation phase, the preparation completes but the downgrade phase is
canceled. If you click Cancel during the downgrade phase, the downgrade completes.
 To cancel a deploy activity:
1. From the Deployment window, select a transfer, upgrade, or downgrade activity that you want to
cancel.
2. Click Cancel.
The next phase of the activity is canceled.

Deleting a deploy activity

This procedure describes how to delete a completed or failed transfer, upgrade, or downgrade
deployment activity from the Deployment window.
You cannot delete an activity in the middle of processing. Cancel the activity (see Cancelling a deploy
activity (on page 341)), and then delete it.
NOTE: The installation package remains on the Control-M/Agent computer even if the deploy activity is
deleted.
 To delete an activity:
1. From the Deployment window, select a completed or failed transfer, upgrade, or downgrade activity
that you want to delete.
2. Click Delete.
The activity is deleted.

Exporting deployment activities

This procedure describes how to export a transfer, upgrade, or downgrade deployment activity details and
its log to an Excel, HTML, or text file.
 To export deployment activities:
1. From the Manage tab, select Deployment.
The Deployment window appears.
2. Do one of the following:

341
Control-M Administrator Guide

• If you want to export the details of a transfer, upgrade, or downgrade deployment activity, do the
following:
a. Click Export.
b. Browse to the location where you want to save the file, select the file type and click Save.
• If you want to export the log of a deployment activity, do the following:
c. Select the deployment activity and click Log.
d. Click Export.
e. Browse to the location where you want to save the file, select the file type and click Save.

Control-M MFT deployment

The Control-M MFT Deployment tool enables you to automatically install and upgrade Control-M MFT on
multiple Control-M/Agents from one single point of access.
From the CCM, you can transfer Control-M MFT software packages to multiple Control-M/Agents. After the
transfer, you can then install or upgrade Control-M MFT on the Control-M/Agents to version 9.0.20 and
higher on UNIX and Windows.
The following procedures describe how to deploy and roll back Control-M MFT to and from
Control-M/Agents:
 Deploying Control-M MFT (on page 342)
 Rolling back Control-M MFT (on page 344)
The following procedures describe how cancel, delete, and export deployment activities:
 Cancelling a deploy activity (on page 341)
 Deleting a deploy activity (on page 341)
 Exporting deployment activities (on page 341)
For a description of configurable deployment parameters, see Deployment parameters (on page 144),
Control-M/Agent deployment parameters (on page 190), and Control-M/EM general parameters (on page
59).
NOTE:
 If the Control-M/Agent windows service is set to Log on as > This account, the upgrade must be
performed with this user.
 To run a deploy activity in the CCM or in a CLI, you must have full access level in the Configuration
and Operation privileges, as described in Privileges (on page 273).

Deploying Control-M MFT

This procedure describes how to transfer MFT installation packages to existing Control-M/Agents and
install or upgrade Control-M MFT on UNIX or Windows.

342
Control-M Administrator Guide

NOTE: You can only deploy MFT 9.0.20 on Control-M MFT 9.0.18 and higher.
NOTE: You can only deploy MFT 9.0.20 to Control-M/Agent 9.0.18.
NOTE: You cannot upgrade more than one MFT activity on the same Windows computer simultaneously.

 To deploy Control-M MFT:

1. From the Manage tab, select Deployment.
The Deployment window appears.
2. Click New Activity >Managed File Transfer > Install/Upgrade.
The MFT Upgrade/Install window appears.
3. Do the following:
a. In the Activity Name field, type a name for this activity.
b. In the Description field, describe the purpose of this activity (optional).
c. In the E-Mail Notification Address field, type the email address(es) that you want to receive
notifications about this activity (optional).
To receive email notification, you need to define the email server parameters, as described in
SMTP parameters (on page 174).
4. Select one of the following:
• Send MFT to Control-M Agent(s): Transfers the MFT installation package to specific
Control-M/Agent computers. After the package is transfered, you can manually start the upgrade
process, at any time, from the Agent Deployment window or upgrade with CLI, as described in
ccmcli.
• Send and Install MFT to Control-M Agent(s): Transfers the MFT installation package to
specific Control-M/Agent computers and begins the upgrade process automatically.
NOTE:
 The Control-M MFT installation package is deleted after a successful upgrade. If the upgrade
failed, then the installation package remains on the Control-M/Agent computer until the next
successful upgrade.
 The MFT installation package remains on the Control-M/Server computer for 30 days. If you want
to change this setting, define the Control-M/Server AD_RETAIN_PACKAGES, as described in
Defining Control-M/Server system parameters (on page 141).
5. Click Next.
6. Select the Control-M/Agent(s) to deploy Control-M MFT.
NOTE: If you selected a Control-M/Agent on Windows that is set to Logon as User, you need to
define the Run As User for each Control-M/Agent.
7. Depending on which method you selected, click Transfer or Upgrade.
The transfer process starts and progress messages appear in the right pane of the deployment
activity. To view and troubleshoot the internal stages of the upgrade, click Log from the Agent
Deployment window. If you selected to transfer the installation package, you can upgrade or install
Control-M MFT any time after the transfer is complete. A job runs on the Control-M/Agent(s) to verify
that it upgraded successfully.

343
Control-M Administrator Guide

Rolling back Control-M MFT

This procedure describes how to roll back Control-M MFT from multiple Control-M/Agents. You can only
roll back Control-M MFT if it was upgraded with the Deployment tool.
This procedure must be done within a defined period based on the AD_GA_RETAIN_DAYS system
parameter, as described in Control-M/Agent deployment parameters (on page 190).
Before you begin
 Verify that all jobs on the selected Control-M/Agents have ended. If jobs are still running during the
rollback, they might fail.
 To roll back Control-M MFT:
1. From the Manage tab, select Deployment.
The Deployment window appears.
2. Click New Activity > Manage File Transfer > Rollback.
The MFT Rollback window appears.
3. Do the following:
a. In the Activity Name field, type a name for this activity.
b. In the Description field, describe the purpose of this activity (optional).
c. In the E-Mail Notification Address field, type the email address(es) that you want to receive
notifications about this activity (optional).
To receive email notification, you need to define the email server parameters, as described in
SMTP parameters (on page 174).
4. Click Next.
5. Select the Control-M/Agent(s) with Control-M MFT to roll back.
6. Click Rollback.
The rollback process begins immediately and Control-M MFT is removed from the Control-M/Agent. To
view and troubleshoot the internal stages of the rollback, click Log from the Deployment window.

Application Pack deployment

The Application Pack Deployment tool enables you to automatically install and upgrade Application
Plug-ins on multiple Control-M/Agents from one single point of access.
The Application Pack Deployment allows you to upgrade to the new version of Application Pack with no
down time on the Control-M/Agent. Application Pack jobs that are running during the upgrade continue to
process to completion. Jobs that are submitted after the upgrade completes, are processed by the new
version. The previous version installation files are deleted after a predefined set of time. The minimum
requirement to run the deployment with no downtime is Application Pack 9.0.18.200.
This process eliminates the need to designate a maintenance period on every Control-M/Agent and
eliminates the need to coordinate between application owners and Control-M Administrators. In addition,
it reduces the total cost of ownership and makes administrative task transparent to business needs.

344
Control-M Administrator Guide

From the CCM, you can transfer the Application Pack software packages to multiple Control-M/Agents.
After the transfer, you can then install or upgrade the Application Pack on the Control-M/Agents to version
9.0.18 and higher on UNIX and Windows.
The Application Pack includes the following Application Plug-ins:
 Control-M for Backup
 Control-M for Databases
 Control-M Application Integrator
 Control-M for Hadoop (Linux only)
 Control-M for AWS
 Control-M for Azure
 Control-M for Informatica
To deploy the Application Pack to and from Control-M/Agents, see Deploying Application Plug-ins (on
page 345). To roll back to its original version, see Rolling back Application Pack (on page 346).
The following procedures describe how to cancel, delete, and export deployment activities:
 Cancelling a deploy activity (on page 341)
 Deleting a deploy activity (on page 341)
 Exporting deployment activities (on page 341)
For a description of configurable deployment parameters, see Deployment parameters (on page 144),
Control-M/Agent deployment parameters (on page 190), and Control-M/EM general parameters (on page
59).
NOTES:
 If the Control-M/Agent windows service is set to Log on as > This account, the upgrade must be
performed with this user.
 To run a deploy activity in the CCM you must have full access level in the Configuration and Operation
privileges, as described in Privileges (on page 273).
 If you are using the DB2 connector for Control-M for Databases, verify that a license file is installed
properly as described inhttp://www-01.ibm.com/support/docview.wss?uid=swg21413734.
 Control-M for Hadoop must be installed on a Control-M/Agent that is on the Edge node of the Hadoop
cluster.

Deploying Application Plug-ins

This procedure describes how to transfer the Application Pack installation packages to existing
Control-M/Agents and install or upgrade Application Plug-ins on UNIX or Windows.
NOTE: You cannot upgrade more than one Application Plug-in activity on the same Windows computer
simultaneously.
 To deploy Application Plug-ins:
1. From the Manage tab, select Deployment.

345
Control-M Administrator Guide

The Deployment window appears.

2. Click New Activity >Application Pack> Install/Upgrade.
The Application Pack Upgrade/Install window appears.
3. Do the following:
a. In the Activity Name field, type a name for this activity.
b. In the Description field, describe the purpose of this activity (optional).
c. In the E-Mail Notification Address field, type the email address(es) that you want to receive
notifications about this activity (optional).
To receive email notification, you need to define the email server parameters, as described in
SMTP parameters (on page 174).
4. Select one of the following:
• Send Application Pack to Control-M/Agent(s): Transfers the Application Pack installation
package to specific Control-M/Agent computers. After the package is transferred, you can
manually start the upgrade process, at any time, from the Deployment window or upgrade with
CLI, as described in ccmcli.
• Send and Install Application Pack to Control-M/Agent(s): Transfers the Application Pack
installation package to specific Control-M/Agent computers and begins the upgrade process
automatically.
NOTE:
 The Application Pack installation package is deleted after a successful upgrade. If the upgrade
failed, then the installation package remains on the Control-M/Agent computer until the next
successful upgrade.
 The Application Pack installation package remains on the Control-M/Server computer for 30 days.
If you want to change this setting, define the Control-M/Server AD_RETAIN_PACKAGES, as
described in Defining Control-M/Server system parameters (on page 141).
5. Click Next.
6. Select the Control-M/Agent(s) to deploy Application Plug-ins.
NOTE: If you selected a Control-M/Agent on Windows that is set to Logon as User, you need to
define the Run As User for each Control-M/Agent.
7. Depending on which method you selected, click Transfer or Install.
The transfer process starts and progress messages appear in the right pane of the deployment
activity. To view and troubleshoot the internal stages of the upgrade, click Log from the
Deployment window. If you selected to transfer the installation package, you can upgrade or install
the Application Pack any time after the transfer is complete. A job runs on the Control-M/Agent(s) to
verify that it upgraded successfully.

Rolling back Application Pack

This procedure describes how to roll back the Application Pack from multiple Control-M/Agents. You can
only roll back the Application Pack if it was upgraded with the Deployment tool.

346
Control-M Administrator Guide

Before you begin

 Verify that all jobs on the selected Control-M/Agents have ended. If jobs are still running during the
rollback, they might fail.
 To roll back Application Pack:
1. From the Manage tab, select Deployment.
The Deployment window appears.
2. Click New Activity > Application Pack> Rollback.
The Application Pack Rollback window appears.
3. Do the following:
a. In the Activity Name field, type a name for this activity.
b. In the Description field, describe the purpose of this activity (optional).
c. In the E-Mail Notification Address field, type the email address(es) that you want to receive
notifications about this activity (optional).
To receive email notification, you need to define the email server parameters, as described in
SMTP parameters (on page 174).
4. Click Next.
5. Select the Control-M/Agent(s) with the Application Pack to roll back.
6. Click Rollback.
The rollback process begins immediately and the Application Pack rolls back to its original version. To
view and troubleshoot the internal stages of the rollback, click Log from the Deployment window.

Removing old files and processes from Windows

This procedure describes how to remove old files and processes from Windows that are no longer needed
after you upgraded Application from a version lower than 9.0.18. The files from previous versions remain
on the computer to allow you to migrate connection profiles to Application Pack. If you do not need those
files, perform this procedure.
 To remove old files and processes from Windows:
1. Stop old Control-M for Databases processes that are no longer in use, as follows:
a. Navigate to the following directory:
<Control-M Agent_Home_Dir>\Default\CM\DB\exe
b. From a command line, type the following:
ctmdbcontainer.cmd stop
2. Remove the Control-M for Databases entry from the list of installed programs, as follows:
a. Open the Registry Editor.
b. Navigate to the following key:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall

347
Control-M Administrator Guide

c. Back up the Uninstall key.

d. Delete the Control-M for Databases 9.0.20 key under Uninstall key.
3. Remove old Control-M for Databases files that are no longer in use, as follows:
a. Navigate to the following directory:
<Control-M Agent_Home_Dir>\Default\CM
b. Back up and delete the DB directory.
4. Stop old Control-M Application Integrator processes that are no longer in use, as follows:
a. Navigate to the following directory:
<Control-M Agent_Home_Dir>\Default\CM\AI\exe
b. From a command line, type the following:
cm_container.cmd stop
5. Remove the Control-M Application Integrator entry from the list of installed programs, as follows:
a. Open the Registry Editor.
b. Navigate to the following key:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall
c. Back up the Uninstall key.
d. Delete the Control-M Application Integrator 9.0.20 key under Uninstall key.
6. Remove old Control-M Application Integrator files that are no longer in use, as follows:
a. Navigate to the following directory:
<Control-M Agent_Home_Dir>\Default\CM
b. Back up and delete the AI directory.
7. Stop old Control-M for Backup processes that are no longer in use, as follows:
a. Navigate to the following directory:
<Control-M Agent_Home_Dir>\Default\CM\Backup\exe
b. From a command line, type the following:
ctmBackup_container.cmd stop
8. Remove the Control-M for Backup entry from the list of installed programs, as follows:
a. Open the Registry Editor.
b. Navigate to the following key:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall
c. Back up the Uninstall key.
d. Delete the Control-M for Backup 9.0.20 key under Uninstall key.
9. Remove old Control-M for Backup files that are no longer in use, as follows:
a. Navigate to the following directory:

348
Control-M Administrator Guide

<Control-M Agent_Home_Dir>\Default\CM
b. Back up and delete the Backup directory.

Removing old files and processes from UNIX

This procedure describes how to remove old files and processes from UNIX that are no longer needed
after you upgraded Application from a version lower than 9.0.18. The files from previous versions remain
on the computer to allow you to migrate connection profiles to Application Pack. If you do not need those
files, perform this procedure.
 To remove old files and processes from UNIX:
1. Stop old Control-M for Databases processes that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm/DB/exe/
b. From a command line, type the following:
./ctmdbcontainer stop
2. Remove old Control-M for Databases files that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm
b. Back up and delete the DB directory.
3. Stop old Control-M Application Integrator processes that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm/AI/exe/
b. From a command line, type the following:
./cm_container stop
4. Remove old Control-M Application Integrator files that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm
b. Back up and delete the AI directory.
5. Stop old Control-M for Backup processes that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm/BACKUP/exe
b. From a command line, type the following:
./ctmBackup_container stop
6. Remove old Control-M for Backup files that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm

349
Control-M Administrator Guide

b. Back up and delete the BACKUP directory.

7. Stop old Control-M for Hadoop processes that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm/HADOOP/exe
b. From a command line, type the following:
./ctmHadoop_container stop
8. Remove old Control-M for Hadoop files that are no longer in use, as follows:
a. Navigate to the following directory:
$CONTROLM/cm
b. Back up and delete the HADOOP directory.

Setting the Job Output file authorizations

This procedure describes how to configure the Control-M Application Pack Job Output file permissions
(UNIX only).
 To set Job Output file authorizations:
1. Open the following file and add the following line:
<Control-M/Agent_home_dir>/ctm/data/AP.dat
SYSOUT_MODE <required file permission>
EXAMPLE: SYSOUT_MODE 755
2. Restart the Control-M/Agent.
The Job Output file authorizations are updated.

Client Distribution
Client Distribution is a software deployment tool that enables you to deploy a single instance of
Control-M/EM client components over the Web to every supported Windows computer in your
organization. The distribution includes version 9.0.18 or higher and can upgrade Control-M clients from
version 9.0.00.500 and higher.
Control-M client updates are automatically distributed to end users. If a new update is available, users will
receive a message when they log in.
You can require end users to install updates by a specific date. If the end users have not installed the
update by the defined deadline, they cannot log in until they complete the installation.
To distribute Control-M clients, see Distributing Control-M clients (on page 351).
NOTE: If the Control-M client was installed via Client Distribution by a non-Admin user, then updates can
only be installed by the same user.

350
Control-M Administrator Guide

Distributing Control-M clients

This procedure describes how to distribute Control-M clients to multiple end users over the Web.
Before you begin:
 Verify that all the target computers meet the system requirements, as described in Control-M client
system requirements.

 To distribute Control-M clients:

1. From the Manage tab, select Client Distribution.
The Client Distribution window appears.
2. Select the Enable Distribution Mode checkbox.
3. Do one of the following:
• If you want to distribute the Control-M client to end users, send them the following URL:

• If you want to distribute a Control-M client update, from the Distribute version drop-down list,
select the Control-M version that you want to distribute to the end users.
The list of available versions reflects the installations on the Control-M/EM server.
NOTE: If you want to ensure that the end users upgrade the distributed client by a certain date,
select the Prevent login if user has not upgraded by: checkbox and select a date.
4. Click OK.
If you distributed a Control-M client update, the installation is automatically downloaded to your end
users computers. They will receive a notification that an installation update is ready to be installed.
The connection parameters to the Control-M/EM server are automatically populated in the installation
wizard. When the installation is complete, the Control-M client is available to the end users.

Configuring Control-M Web Server access with FQDN

This procedure describes how to configure Control-M Web Server access with a fully qualified domain
name (FQDN). You need to perform this procedure when the host computer, where Control-M Web Server
is installed, can only be accessed via FQDN. This enables you to view the Control-M Online Help, and to
use Application Integrator and Client Distribution.
 To configure Control-M Web Server access with FQDN:
1. Run the following command:
em restore_host_config -interface_name -name <FQDN>
NOTE: If you are working in a high availability environment or with a Distributed environment, run
the command on both the primary and secondary hosts.
2. Navigate to the following directory:
<Control-M/EM_home_dir>/Client_Updates/conf/
3. Open web_server_params.xml and apply the following changes:

351
Control-M Administrator Guide

a. Change <ALLOW_MODIFICATION>true</ALLOW_MODIFICATION> to
<ALLOW_MODIFICATION>false</ALLOW_MODIFICATION>.
b. Change <WEB_SRV_HOST><value></WEB_SRV_HOST> to
<WEB_SRV_HOST><FQDN></WEB_SRV_HOST>.
4. Save the file.
5. Restart the Control-M client and the Control-M Web Server.

Compatibility Mode
Compatibility Mode allows users with previous versions of the Control-M client to connect to the latest
version of Control-M/EM server in addition to the upgraded Control-M clients. However, when
Compatibility Mode is on, new features are disabled in upgraded Control-M clients. This ensures system
integrity during the transition to a higher version. After Compatibility Mode is turned off, the new features
are enabled in the upgraded Control-M clients and older clients are disconnected. Users that have not
upgraded their Control-M clients cannot log in.
The following table lists the features that are disabled in Control-M clients after you have upgraded and
compatibility mode is on.

Source version Target version Disabled features

9.0.00.xxx 9.0.19  Cyclic Folders

 End Folder
 Variable Simulation
 Control-M Web User Views
 Control-M Web Site
Standards
 XML validation
 85 character host name limit

9.0.18.XXX 9.0.19  Control-M Web User Views

 Control-M Web Site
Standards
 XML validation
 85 character host name limit

Turning off Compatibility Mode

This procedure describes how to turn off Compatibility Mode, which enables new features in upgraded
clients.

352
Control-M Administrator Guide

NOTE: After Compatibility Mode is turned off, users that have not upgraded their Control-M clients cannot
log in.
WARNING: After Compatibility Mode is turned off, you cannot turn it back on.
 To turn off Compatibility Mode:
1. From the Manage tab, click Compatibility Mode.
2. Click I have read and understand.
3. Click Turn Off Compatibility Mode.
Control-M/EM server components are restarted automatically.

Control-M client and Control-M/EM server compatibility scenarios

The following table lists the different Control-M client and Control-M/EM server compatibility scenarios
after you upgrade Control-M/EM server from the source (compatibility version) to the new target version.

Control-M/EM server source Control-M/EM server target Client version Result

version version

9.0.18.xxx 9.0.19 9.0.00.500 Fail

Compatibility mode: On Reason: The client
earlier than the serv
compatibility versio

9.0.18.xxx 9.0.19 9.0.18.xxx Success

Compatibility mode: On

9.0.18.xxx 9.0.19 9.0.18.xxx Fail

Compatibility mode: Off Reason: When com
mode is off, the clie
in the same major r
server target versio

9.0.18.xxx 9.0.19 9.0.19 Success

Compatibility mode: On

9.0.00.xxx 9.0.19 9.0.00.xxx Success

Compatibility mode: On

353
10
10
Workload Archiving configuration
Control-M Workload Archiving is a Control-M add-on that enables you to archive job data in a secure and
central repository whenever jobs finish executing. Archived data includes job logs from Control-M/Server
and job output from Control-M/Agents, as well as a small amount of job metadata from Control-M/EM.
When Control-M/Server submits a job to run on an Agent, the Workload Archiving Server archives the job
log and output in a separate PostgresQL or Oracle database for a defined period based on Workload
Archiving Policies.
A Workload Archiving Policy determines what job data to archive based on various criteria, including the
following main criteria:
• Type of data — log, output, or both
• Retention period — maximum number of days, months, or years to store the archived data
• System type — Distributed systems, z/OS, or both
NOTE: The Workload Archiving process receives Control-M/EM authorization data to apply Control-M/EM
user authorization rules. You do not need to define additional authorizations. For more information, see
Control-M/EM Authorizations (on page 263).
NOTE: (Control-M for z/OS only) To collect job output and logs, you must define the security user
ARCUSER with the View LOG and View SYSOUT permissions.

To start/stop the Workload Archiving database, perform backup and restore, and other database
procedures, see arc_database_menu.
The following procedures describe how to start up and configure Workload Archiving settings:
 Starting up the Workload Archiving Server (on page 355)
 Defining Workload Archiving policies (on page 355)
 Configuring Workload Archiving disk space and cleanup settings (on page 357)
 Deleting data from the Workload Archiving server (on page 358)
 Shutting down the Workload Archiving Server (on page 359)
 Configuring the Workload Archiving cyclic log collection (on page 359)
 Configuring retention parameters to prevent loss of archive data (on page 359)
You can also perform several procedures through Workload Archiving command line utilities, as described
in Workload Archiving command line utilities (on page 361).
After you have created a Workload Archiving policy and have configured the required settings, you can
now perform an Archive search, as described in Control-M Workload Archiving.

354
Control-M Administrator Guide

Starting up the Workload Archiving Server

This procedure describes how to start up the Workload Archiving Server from the CCM.
 To start up the Workload Archiving Server:
 Right-click the Workload Archiving Server component and select Desired State > Up.
The Workload Archiving Server is now up.

Defining Workload Archiving policies

This procedure describes how to define Workload Archiving policies, which enables you to determine what
type of data to archive and the retention period in the Workload Archiving database.
 To define Workload Archiving policies:
1. From the Manage tab, click Workload Archiving.
The Archive Configuration window appears.

2. Click .
The Archive Policy Rule Settings dialog box appears.
3. For each field, type or select the required value, as described in Workload Archiving policy rule
parameters (on page 356).
4. Click Save.
The Workload Archiving policy rule is added to the Archive Policy table.

355
Control-M Administrator Guide

Workload Archiving policy rule parameters

The following table describes Workload Archiving policy rule parameters that are used in Defining
Workload Archiving policies (on page 355).

Parameter Description

Name Defines the name of the Workload Archiving policy

Status Determines whether the Workload Archiving policy rule is active or

inactive

Description Describes the purpose or details of the Workload Archiving policy

Retention Period Determines the number of days, months, or years the log/output
is archived

Archive Data Determines whether to archive the job log, output, or both

Control-M Server Determines which Control-M/Servers are used to archive the data.
You can use special characters to include in the Criteria column
or exclude in the Exceptions column, as described in Pattern
matching strings.

Type Determines whether to archive the data from Distributed systems,

z/OS, or both

Job Name Determines which jobs are used to archive the data.
You can use special characters to include in the Criteria column
or exclude in the Exceptions column, as described in Pattern
matching strings.

Job Type Determines which job types are used to archived the data, such as
OS or specific Application Plug-ins

Job Status Determines whether to archive jobs that ended OK, Not OK, or
both

Library (z/OS only) Determines which libraries are used to archive the
data.
You can use special characters to include in the Criteria column
or exclude in the Exceptions column, as described in Pattern
matching strings.

356
Control-M Administrator Guide

Parameter Description

Application Determines which Applications are used to archive the data.

You can use special characters to include in the Criteria column
or exclude in the Exceptions column, as described in Pattern
matching strings.

Sub-application Determines which Sub-applications are used to archive the data.

You can use special characters to include in the Criteria column
or exclude in the Exceptions column, as described in Pattern
matching strings.

Folder Determines which Folders are used to archive the data.

You can use special characters to include in the Criteria column
or exclude in the Exceptions column, as described in Pattern
matching strings.
EXAMPLE: If you want to collect a SMART folder and all its
content, add it here.
If you want to collect a sub folder and all its content
add its full path (including its name).
If a sub-folder with same name <sub_folder_name>
exist in more than one SMART folder, and you want to
collect all of them,add */<sub_folder_name>.

Maximum Output Size Determines the maximum size of job output that is archived in the
Workload Archiving server.

Trim in case output exceeds max Determines whether to archive the output if it exceeds the
output maximum output size or cut off data from the beginning or end of
the file.

Configuring Workload Archiving disk space and cleanup

settings
This procedure describes how to configure Workload Archiving disk space and cleanup settings from the
CCM.
 To configure Workload Archiving disk space and cleanup settings:
1. From the Manage tab, click Workload Archiving.
The Archive Configuration window appears.
2. In the left pane, click Advanced Configuration.

357
Control-M Administrator Guide

The Server Configuration dialog box appears.

3. For each field, type or select the required value, as described in Workload Archiving Server
Configuration parameters (on page 358).
4. Click Save.

Workload Archiving Server Configuration parameters

The following table describes the Workload Archiving Server Configuration parameters that are used in
Configuring Workload Archiving disk space and cleanup settings (on page 357).

Parameter Description

Minimum free disk space Determines the size of free disk space that must remain where
required for Archive Control-M Workload Archiving is installed. If the threshold is
exceeded, the Archiving process stops collecting data until the free
disk space issue is resolved.

Interval to check free disk space Determines intervals in seconds, minutes, or hours when to check
the Workload Archiving Server for free disk space

Data cleanup cycle Determines when to delete data from the Workload Archiving
Server that is older than the retention period defined in the
Workload Archiving policy (see Workload Archiving policy rule
parameters (on page 356))

Cleanup start time Determines when to start the cleanup

Deleting data from the Workload Archiving server

This procedure describes how to delete data (jobs including output and logs) from the Workload Archiving
server. You can delete data that belongs to a specific rule or delete data that matches specific criteria of
the command.
 To delete data from the Workload Archiving server:
 Type one of the following commands:
• Rule Name: arc_cleanup -user<user> -password<password> -rule<ruleName>
• Data Attributes: arc_cleanup -user<user> -password<password>
-job_name<jobName> -job_name_exceptions<jobNameExceptions>
-ctm<CTMServerName> -ctm_exceptions<CTMServerNameExceptions>
-job_state<OK|NOTOK> -app<appName> -app_exceptions<appNameExceptions>
-subapp<subApplication> -subapp_exceptions<subappEexceptions>
-folder<folderName> -folder_exceptions<folderNameExceptions>
-lib<library> -lib_exceptions<libraryExceptions>

358
Control-M Administrator Guide

The search criteria support wildcard characters (* and ?) for both values and exceptions .
NOTE: The parameters -user and -password are mandatory arguments.
EXAMPLE: Delete all archived jobs that contain ‘AA’ except for jobs that start with ‘B’.
arc_cleanup –user <user> -password <password> –job_name "*AA*" –
job_name_exceptions "B*"

Shutting down the Workload Archiving Server

This procedure describes how to shut down the Workload Archiving Server from the CCM.
 To shut down the Workload Archiving Server:
 Right-click the Workload Archiving Server component and select Desired State > Down.
The Workload Archiving Server is now down.

Configuring the Workload Archiving cyclic log collection

This procedure describes how to configure the Workload Archiving cyclic log collection, which enables you
to determine when the logs and outputs of a cyclic job are archived. The ability to change this
configuration reduces the load on resources, such as CPU usage and disk space.
 To configure the Workload Archiving cyclic log collection:
1. From the Control-M/EM server computer, navigate to the following directory:
<Control-M EM_Home_Dir>\archive\config
2. Open the SystemParameters.xml file and search for the cyclic.log.collection.interval.minutes
system parameter.
3. Change the value to the required number of minutes before the output and log of a cyclic job are
archived.
If you enter a value of 0, the output and logs of cyclic jobs are collected after every run.

Configuring retention parameters to prevent loss of

archive data
This procedure describes how to check and adjust retention parameters, to prevent loss of archive data
during periods of time when the Workload Archiving Server is down and cannot collect job data. At such
times, you must ensure that data is retained in Control-M components for a large enough number of days
to cover the time that the Workload Archiving Server was down and the extra time that the Workload
Archiving Server needs for retrieving job data after it is brought back up.
 To configure retention parameters to prevent loss of archive data
1. Update retention parameters for Control-M/Server through the ctmsys utility:
a. Run the ctmsys utility, as described in Running the ctmsys utility.

359
Control-M Administrator Guide

b. From the Main Menu, choose Option 2, System Parameters.

c. Specify n to display the second page of parameters.
d. Update the following parameters with larger values:
o Option 6, Maximum Days Retained by Control-M Log
o Option 7, Maximum Days to Retain Output Files
e. Save your changes and exit the utility.
NOTE: Increasing Control-M Log retention requires additional database space on Control-M/Server.
Increasing job output retention requires additional disk space on each Control-M/Agent.
2. If you require a retention period that is longer than the default of 30 days, update the retention
period for all Control-M/Agents:
Through the CCM, update the value defined in the GENERAL_CLEANUP_INTERVAL system parameter
for each of your agents, as described in Defining Control-M/Agent system parameters (on page 189).
3. Verify that Control-M/Server retention parameters take effect on all Control-M/Agents:
• Ensure that the Control-M/Agents do not use the SYSKEEPDAYS parameter:
o On UNIX, ensure that the CONFIG table in <Agent home>/data/CONFIG.dat does not
contain the SYSKEEPDAYS parameter. If necessary, remove this parameter.
o On Windows, ensure that the Agent Registry folder that contains the CONFIG table does not
contain the SYSKEEPDAYS parameter. If necessary, remove this parameter.
o In the CCM, right-click each Control-M/Agent and select Properties. On the Output tab,
ensure that the Days to retain OUTPUT files is set to Default.
• Verify that Control-M/Server sends the output retention value to all agents at NewDay time:
a. In the Control-M/Server config.dat file, located in <Control-M/Server home
directory>/ctm_server/data/, update or add the following line:
AGENTS_CLEANUP_IN_NEWDAY Y
b. Restart the Control-M/Server.
4. If you need a long retention period, update retention for Control-M/EM. Through the CCM, update the
values of the following Control-M/EM system parameters, as described in Defining Control-M/EM
system parameters (on page 45):
• ArchiveRetentionPeriod, one of the Control-M Workload Archiving parameters (on page 139)
• RunTimeHistoryDays, a general system parameter. This is the number of days that Runinfo
history information is retained before being cleaned from the Control-M/EM database. The default
is 90 days.
NOTE: Increasing the Archive retention through Control-M/EM system parameters will impact the
Control-M/EM database size required to support the new value.
5. Update the following retention parameters in
$EM_HOME/archive/config/SystemParameters.xml on the Workload Archiving Server with the
same values that you used in Step 1:
• override.num.days.log.keep.in.server
• override.num.days.output.keep.in.server
For your changes to take effect, recycle the Workload Archiving Server.

360
Control-M Administrator Guide

Workload Archiving command line utilities

The following table describes the Workload Archiving command line utilities.

Utility Description

arc_start_server Starts up the Workload Archiving server

arc_stop_server Shuts down the Workload Archiving server

arc_server_state Checks the status of the Workload Archiving server

arc_kill_server Terminates Workload Archiving server processes if they won't stop

regularly

arc_sql Starts an SQL prompt in the Workload Archiving database

arc_data_collector Creates a package of OS and Workload Archiving logs and

configuration for review by BMC Support.

arc_recollect_jobs Attempts to recollect the job output or log after the Workload
Archiving server failed to collect exceeding the retry threshold.
NOTE: To avoid using unnecessary resources on the Workload
Archiving server, apply accurate search criteria when you run this
script.

361
11
11
Control-M for MFT configuration
Control-M Managed File Transfer (MFT) is an FTP/SFTP client and server that enables you to watch and
transfer files from a local host to a remote host, a remote host to a local host, or a remote host to
another remote host. Control-M for MFT enables you to perform the following administrative tasks in the
CCM:
 Create, update, delete, test, copy, and export accounts, as described in Connection profile
management (on page 362).
 Create, update, copy, and delete MVS templates, which enable you to define MVS file transfer
parameters, as described in MVS file template management (on page 383).
 Create, update, copy, and delete PGP templates, which enable you to define PGP commands using
your own PGP application to integrate with Control-M for MFT for each transfer, as described in PGP
template management (on page 387).
 Generate SSH keys, which enables the SFTP client to authenticate itself to the SFTP server instead of
using a password, as described in Generating SSH keys (on page 391).
 Authorize an SSH host when the SSH server’s signature changes, which ensures that you connect to
the correct SFTP server to avoid MFT job failures, as described in Authorizing an SSH host (on page
392).
 Configure general MFT and File Watcher parameters, as described in Configuring Control-M for MFT
parameters (on page 393).
 Update connection profile parameters, such as hostname, username, and password globally across all
accounts, as described in Mass connection profile update parameters (on page 397).

Connection profile management

Before you can define a File Transfer job in Control-M, you need to create a connection profile in the
Control-M Configuration Manager, which enables you to connect to the required FTP server.
A connection profile contains the connection parameters for either the source or destination host,or both,
such as hostname, port, communication protocols, username, and password. By adding a connection
profile to the CCM, you enable users to connect to the required server with only the connection profile
name. Users then can run a job without having to provide authentication details every time they connect
to the server.
The following procedures describe how to create, edit, delete, test, copy, and export a connection profile
in the CCM:

362
Control-M Administrator Guide

 Creating a connection profile (on page 363)

 Editing a connection profile (on page 375)
 Deleting a connection profile (on page 375)
 Testing a connection profile (on page 376)
 Copying a connection profile (on page 376)
 Exporting a connection profile (on page 377)

Creating a connection profile

This procedure describes how to create an MFT connection profile in the Control-M Configuration
Manager, which enables you to define a File Transfer job in the Control-M.
NOTE: If you are defining a connection profile for MFT Enterprise B2B on the File Transfer Server (Hub),
you must define it as SFTP.

Before you begin

 If you want to use key authentication to access an SFTP server, you need to generate an SSH key, as
described in Generating SSH keys (on page 391).
 If you are creating an S3 connection profile, you must have list permissions for S3 buckets.

 To create a connection profile:

1. From Control-M Configuration Manager, select the Control-M Managed File Transfer on the host
that you want to manage and right-click Connection Profile Management.
The Managed File Transfer - Connection Profile Management dialog box appears.

2. Click the icon.

The Add Connection Profile dialog box appears.
3. In the Connection Profile Name field, type the name of the connection profile that you want to add
(The connection profile name must begin with a letter and without any blanks or special characters).
4. In the Connection Profile Type area, select one of the following:
• File transfer single endpoint: Transfers files from the host defined in this connection profile to
hosts defined in multiple connection profiles. Select this option if you want to reuse this
connection profile to transfer files to different hosts.
• File transfer dual endpoint: Transfers files between two specific hosts defined in this
connection profile.
• File transfer group: See Creating a file transfer group connection profile (on page 365).
5. In the Control-M Users table, do one of the following:
a. To select users from the list, select the users that you want to allow access to this connection
profile, click Add, and then click Next.
b. To add users or groups manually, , click Add Manually.
The Authorized User or Group dialog box appears.

363
Control-M Administrator Guide

a. In the Add EM user or group field, type the name of the user or group you want to add.
Multiple users and groups must be separated by a | character.
b. In the Type area, select User or Group.
c. Click OK.
NOTE: Wildcard characters (* and?) can be used as part of a defined Control-M/EM user or group.
The Set Host1 details dialog box appears.
6. For each field, type the required value, as described in Control-M for MFT host parameters (on page
366).
7. If you have defined this host as a Local CM, continue to step 8, otherwise, in the Communication
Protocol area, select one of the following options, and then click Next:
a. FTP: File Transfer Protocol. For each field, type the required value, as described in FTP protocol
parameters (on page 368).
b. SFTP (SSH): Secure File Transfer Protocol.For each field, type the required value, as described in
SFTP (SSH) protocol parameters (on page 369).
c. S3: Amazon Simple Storage Service. For each field, type the required value, as described in S3
protocol parameters (on page 369).
d. AS2:Applicability Statement. For each field, type the required value, as described in AS2
parameters (on page 370).
The Set Host2 details dialog box appears. If you are defining one host, continue with step 10.
8. For each field, type the required value as described in Control-M for MFT host parameters (on page
366).
9. Repeat steps to set Host2, and then click Next.
The Set Additional Settings dialog box appears.
10. For each field, type the required value as described in Connection profile additional parameters (on
page 371), and then click Next.
If you want to manually add additional parameters for a single connection profile, in the Manual
Additional Parameters area, add new parameters, as described in Connection profile manual
parameters.
The Add Connection Profile - Summary dialog box appears.
11. Review the connection profile details and click Test (optional) or Finish.
If the test completed successfully, the connection profile is validated and you can now define a MFT
job, as described in Defining a Control-M job. If the test failed, review the error message and test it
again.
NOTE: IN AS2, a test file is sent to the AS2 server.
The connection profile is added to the Control-M for MFT - Connection Profile Management
dialog box.

364
Control-M Administrator Guide

Creating a file transfer group connection profile

This procedure describes how to create a file transfer group, which enables you to transfer a file from one
host to multiple hosts in one transfer.
 To create a file transfer group connection profile:
1. From Control-M Configuration Manager, select the Control-M Managed File Transfer on the host
that you want to manage and right-click Connection Profile Management.
The Managed File Transfer - Connection Profile Management dialog box appears.

2. Click the icon.

The Add Connection Profile dialog box appears.
3. In the Connection Profile Name field, type the name of the connection profile that you want to add
(The connection profile name must begin with a letter and without any blanks or special characters).
4. In the Connection Profile Type area, select File transfer group.
5. In the Control-M Users table, do one of the following:
a. To select users from the list, select the users that you want to allow access to this connection
profile, click Add, and then click Next.
b. To add users or groups manually, , click Add Manually.
The Authorized User or Group dialog box appears.
a. In the Add EM user or group field, type the name of the user or group you want to add.
Multiple users and groups must be separated by a | character.
b. In the Type area, select User or Group
c. Click OK.
NOTE: Wildcard characters (* and?) can be used as part of a defined Control-M/EM user or group.
The Select Hosts dialog box appears.
6. Select the connection profiles that you want to add to this group and click Next.
The Summary dialog box appears.
7. Review the connection profile details and click Test (optional) or Finish.
If the test completed successfully, the connection profile is validated and you can now define a File
Transfer job, as described in Defining a Control-M job. If the test failed, review the error message and
test it again.
The connection profile is added to the Control-M MFT - Connection Profile Management dialog
box.

365
Control-M Administrator Guide

Control-M for MFT host parameters

The following table lists the host parameters.

Field Description

Host Name Defines the name of the host computer

Local CM Defines the host as a local computer (Control-M/Agent

computer).
If you select this option, the Host Name and Port fields are
disabled.

OS Type Determines which platform the host resides. If you are

defining a connection profile on a remote Microsoft Windows
computer, see Configuring connection details for a remote
Windows server (on page 439).
NOTE:
 If you want to connect with SFTP to a USS file system
on Mainframe, you must select UNIX.
 If you want to connect with SFTP to a z/OS file system
on Mainframe (via Co:Z), you must select MVS.

Port Determines the port used to communicate for each host.

Defaults are:
FTP: 21
SFTP: 22

User Name Defines the username of each host.

If it is a local host on Windows, the domain name must be
specified. If it is a remote host on Windows, the domain
name might need to be specified if required by the server.
To execute PGP commands, you need to add this user, if the
Local CM checkbox is selected, to specific policies in the
Local Security Settings window, as described in Adding users
to Local Security policies (on page 441).

Password Defines the password for each user connection profile

Confirm Password Confirms the password for each user connection profile

Home Directory Determines the home directory for each host that appears in
the File Selection dialog box in the Control-M for MFT
properties pane.
Control-M for MFT supports both Name Format 0 and Name

366
Control-M Administrator Guide

Field Description
Format 1. The syntax of the home directory determines
which format is used (OS/400 platforms only).
To retrieve the home directory from the remote server or
local computer, click Get Home Directory (This feature is not
available for Unisys OS2200).

367
Control-M Administrator Guide

FTP protocol parameters

The following table lists the FTP protocol parameters.

Parameter Description

FTP over SSL/TLS (FTPS) Defines the communication protocol as FTP over SSL/TLS

Clear Command Channel Sets the transmission mode in a control connection from an
encrypted mode to clear text mode. You can secure sensitive
information, including your user name and password, by
sending them in an encrypted mode, and then use the CCC
sub-command to change the transmission mode back to
clear text mode to send the port and IP information (FTP
over SSL/TLS).

Clear Data Channel Encrypts the connection process while files are transferred
without encryption. You can select this option if you want
your login information encrypted and your files transferred
without encryption.

SSL Implicit Automatically creates an SSL connection between the MFT

client and the FTP server (Default port 990). In SSL Explicit
mode, the MFT client connects to the FTP server and then
changes the connection to SSL mode (FTP over SSL/TLS).

SSL Security Level Defines the SSL security levels for the host as 2, 3, or 4. For
more details about SSL security levels, see SSL Security
levels (on page 434).

FTP Passive Initiates the data and control connections from the FTP
client to the FTP server, which solves firewall issues.

Substitute IP address Forces passive connections to use the host address.

Extended Passive Mode Determines whether to use the Extended Passive Mode,
(EPSV) where the FTP client uses the same IP address to open a
data channel.
This is mainly used for IPV6 environments..

368
Control-M Administrator Guide

SFTP (SSH) protocol parameters

The following table lists the SFTP (SSH) protocol parameters.

Parameter Description

Compression Compresses the file before the transfer

Key Authentication Uses Key Authentication to access the SFTP server. To

generate SSH keys, see Generating SSH keys (on page 391)

Private Key Name Defines the path and file name of the private key

Key Passphrase Defines the password of the private key file

Confirm Passphrase Confirms the password of the private key file

S3 protocol parameters
The following table describes S3 protocol parameters.

Parameter Description

Storage Type Determines one of the following S3 storage types:

 Amazon S3 Storage: Amazon Simple Storage solution.
 S3 Compatible Storage: A storage solution that allows you
to access and manage the data it stores over an S3 compliant
interface.

REST Endpoint Defines the network address where the S3 Compatible Storage is
located.

Access Key Determines the access key to Amazon S3 storage or S3

Compatible storage.

Secret Access Key Determines the secret access key to Amazon S3 storage or S3
Compatible storage

Region Determines the default region to perform the Amazon S3 requests.

For better performance, select the region where the bucket is
located.

369
Control-M Administrator Guide

AS2 parameters
The following table describes AS2 parameters:

Parameter Description

Partner AS2 ID Defines the logical name of the remote AS2 server.

Destination URL Defines the URL of the AS2 server

Partner Certificate Alias Defines the alias of the partner certificate that is stored in the AS2
keystore

Sign Message Determines whether to digitally sign the AS2 message with one of
the listed algorithms

Encrypt Message Determines whether to encrypt the AS2 message with one of the
listed encryption algorithms

Request Receipt Determines whether to receive a signed or unsigned MDN receipt

of the AS2 message from the AS2 server that it was received and
processed

Compress Message Determines whether to compress the AS2 message when sent

User Name Defines the username of the HTTP request for the AS2 message

Password Defines the password of the HTTP request for the AS2 message

Confirm Password Confirms the password of the HTTP request for the AS2 message

Send Message Timeout Determines the number of seconds to wait for the AS2 server to
reply before a timeout occurs
Default: 300

A-sync Receive Timeout Determines the number of minutes to wait for the AS2 server to
send the receipt before a timeout occurs
Default: 300

370
Control-M Administrator Guide

Connection profile additional parameters

The following table lists the connection profile additional parameters.

Parameter Description

Verify destination file size Verifies the size of the file after a successful transfer.
NOTE:
 If a file transfer has spaces in the file name and it fails
during this verification, you must not select this option,
as some FTP servers do not list file names with spaces.
 This option is only available on Windows and UNIX FTP
servers.
 This option is only relevant for Binary mode transfer.

Verify total bytes sent Determines whether to verify, after a successful transfer, if
the actual number of bytes sent to destination is the same
as the size of the file on the source.
If it is not the same size, the transfer fails.
NOTE:
 This option is only available on Windows and UNIX FTP
servers.
 This option is only relevant for Binary mode transfer.

Verify checksum Verifies that the file transferred correctly by executing MD5
checksum on the FTP server.
This option is available only for FTP Servers that support
either the XMD5 or the SITE CHECKSUM checksum
commands.
For UNIX FTP servers, ensure that the md5sum program is
installed on the FTP server search path, to enable the SITE
CHECKMETHOD MD5 and SITE CHECKSUM commands to
work properly.

Manual Additional Enables you to add parameters for futher connection profile
Parameters configuration, as described in Connection profile manual
additional parameters (on page 372).

371
Control-M Administrator Guide

Connection profile manual additional parameters

The following table describes the Connection profile manual additional parameters.

Parameter Description

ssl.provider.options.sslprotocol Overrides the enabled SSL protocols such as,

SSLv3,TLSv1,TLSv1.1, and TLSv1.2.
NOTE: If you want to work with SSLv3, mark the
jdk.tls.disabledAlgorithms=SSLv3 attribute with #, and
then restart the container.
To edit the file, use the following path: ${path}\BMC
Software\Control-M
Agent\Default\CM\AFT\JRE\lib\security
EXAMPLE:
TLSv1.2
SSLv3,TLSv1

ssl.provider.options.tlsciphersuit Overrides the enabled cipher suites

e

ssl.keystore.keyalias Overrides the keystore alias

ftp.charset Uses a different character set when connecting to a remote FTP

server (if not specified, UTF-8 is the default charset).
EXAMPLE: ISO-8859-1

ftp.timezone.offset Defines the timezone offset of the remote FTP server. Use this if
the FTP server timezone is different than the Control-M/Agent
timezone.
Format: +/-HH:MM.
EXAMPLE: +04:00

sftp.charset Uses a different character set when connecting to a remote

SFTP server (if not specified, UTF-8 is the default charset)
EXAMPLE: ISO-8859-1

sftp.newline Defines CRLF or LF to override the ASCII End of Line control

character abbreviation, when transferring with SFTP protocol
and ASCII mode.
By default, End of Line is based on the Connection Profile OS
type (Windows = CRLF, UNIX = LF).
EXAMPLE: CRLF or LF

372
Control-M Administrator Guide

Parameter Description

sftp.remove.directory.trailing.sla Determines whether the remote SFTP server enforces omitting a

sh trailing slash when running directory operations (such as, mkdir
and rmdir).
Default: Trailing slash
EXAMPLE: true or false

sftp.ignoreIsRemoteDirChecking Enables you to upload files to a specific server.

WhenStoreFile
Default: true

sftp.ciphers Overrides the SFTP ciphers that are used when connecting to
the SFTP server (commas separated values).
EXAMPLE:
aes128-cbc,aes192-cbc,aes256-cbc,aes128-ctr,aes1
92-ctr,aes256-ctr

sftp.kex Overrides the SFTP key exchange algorithms that are used when
connecting to the SFTP server (commas separated values).
EXAMPLE:
ecdh-sha2-nistp256,diffie-hellman-group-exchange-s
ha1,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-h
ellman-group14-sha1,diffie-hellman-group-exchange
-sha256,diffie-hellman-group1-sha1

sftp.mac Overrides the SFTP mac algorithms that are used when
connecting to the SFTP server (commas separated values).
EXAMPLE:
hmac-md5,hmac-sha2-256,hmac-sha1,hmac-sha1-9
6,hmac-md5-96

slowdown.rate.millisecond Determines the number of milliseconds to wait between each

read/write operation during transfer when the remote server is
very slow.
EXAMPLE: 300

ui.max.records.in.list Limits or extends the number of records returned to the File

Transfer browser dialog.
By Default, 10,000 records are returned
EXAMPLE: 20000

373
Control-M Administrator Guide

Parameter Description

ftp.path.with.spaces.improved.di Determines whether the FTP client performs a directory listing

rectory.listing on the whole directory when transferring specific file path that
includes spaces such as, /aaa/bbb/ccc ddd.txt or square
brackets.
This property has no affect if transferring a path without
spaces or transferring directory or pattern. Use this property
only if the Connection Profile is Windows or Linux (not supported
on AIX).
EXAMPLE: true or false

 ftp.performChangeDirectory Determines whether to change the working directory to the

BeforeAction target FTP or SFTP path before writing a file.
 sftp.performChangeDirectory EXAMPLE: true or false
BeforeAction

sftp.flush Determines whether to ask SFTP server to flush any buffer than
was sent (to verify the target file was updated in case of
disconnections).
NOTE: If set to true, performance might be affected.
EXAMPLE: true or false

as2.compressMessageBeforeSign Determines whether to compress AS2 message before signing

the message.
EXAMPLE: true or false

s3.use.virtual.hosted.style Determines whether to use the virtual-hosted style (mybucket1.

s3-eu-west-1.amazonaws.com) for S3 buckets on S3 API calls.
EXAMPLE: true or false

s3.set.api.version Determines which REST API version to use .

Default: 2

s3.set.http.connection.protocol Determines whether to use HTTP instead of HTTPS for S3

connections.
EXAMPLE: true or false

use.proxy Determines whether to connect to the SFTP, FTP, or S3 server

via Web Proxy, if enabled in the Configuration Management
window.
Default: true

374
Control-M Administrator Guide

Parameter Description

s3.proxy.host Determines the hostname or IP of the web proxy server.

NOTE: The Connection Profile web proxy server settings
override the Configuration Management web proxy server
settings (see Control-M for MFT configuration parameters (on
page 394)).

s3.proxy.port Determines the port number of the web proxy server.

NOTE: The Connection Profile web proxy server settings
override the Configuration Management web proxy server
settings (see Control-M for MFT configuration parameters (on
page 394)).

Editing a connection profile

This procedure describes how to edit a connection profile in the Control-M Configuration Manager.

 To edit a connection profile:

1. From the Control-M Configuration Manager, select the Control-M Managed File Transfer on the
host that you want to manage and right-click Connection Profile Management.
The Control-M for MFT - Connection Profile Management dialog box appears.

2. Select a connection profile that you want to edit and click the icon.
The Update <connection profile> Connection Profile dialog box appears.
3. Update the required parameters in the Host1 or Host2 tabs, as described in Creating a connection
profile (on page 363).
4. In the Additional Settings tab, update the required parameters, as described in Connection profile
additional parameters (on page 371).
5. Review the connection profile details and click Test (optional).
If the test completes successfully, the connection profile validates and you can now define a MFT job,
as described in Defining a Control-M job. If the test fails, review the error message and test it again.
6. Click OK.
The connection profile is updated in the Control-M for MFT - Connection Profile Management
dialog box.

Deleting a connection profile

This procedure describes how to delete a connection profile from the CCM.
 To delete a connection profile:
1. From the CCM, select Control-M for MFT, right-click and select Connection Profile Management.

375
Control-M Administrator Guide

The Control-M for MFT - Connection Profile Management dialog box appears.

2. Select the connection profile that you want to delete, and click the icon.
A confirmation message appears.
3. Click Yes.
The connection profile is deleted.

Testing a connection profile

This procedure describes how to test a connection profile in the Control-M Configuration Manager to
validate the connection parameters.
 To test a connection profile:
1. From Control-M Configuration Manager, select Control-M for MFT, right click and select
Connection Profile Management.
The Control-M for MFT - Connection Profile Management dialog box appears.

2. Select the connection profile that you want to test, and click .
If the test completes successfully, the connection profile validates and you can now define a MFT job,
as described in Defining a Control-M job. If the test fails, review the error message(s), fix any
problems as necessary, and test it again.

Copying a connection profile

This procedure describes how to copy a connection profile in the Control-M Configuration Manager, which
enables you to create an additional connection profile using the parameters of an existing connection
profile.

 To copy a connection profile:

1. From the CCM, select Control-M for MFT, right-click and select Connection Profile Management.
The Control-M for MFT - Connection Profile Management dialog box appears.

2. Select the connection profile that you want to copy, and click .
The Copy <connection profile> Connection Profile dialog box appears.
3. In the Connection Profile Name field, enter a name for the new connection profile and click OK.
If you want to change parameters to this connection profile, see Editing a connection profile (on page
375).
4. Click Test (optional).
If the test completes successfully, the connection is validated and you can now define a MFT job, as
described in Defining a Control-M job. If the test fails, review the error message and test it again.
5. Click OK.

376
Control-M Administrator Guide

Exporting a connection profile

This procedure describes how to export a connection profile from one Control-M/Agent to another
Control-M/Agent, where Control-M for MFT is installed.
 To export a connection profile:
1. From the CCM, select Control-M for MFT on the host that you want to manage, right-click and
select Connection Profile Management.
The Control-M for MFT - Connection Profile Management dialog box appears.

2. Select the connection profile that you want to export, and click .
The Connection Profile Management - Export Connection Profile Destination dialog box
appears.
3. From the Control-M/Server name drop-down list, select the Control-M/Server that contains the
Control-M/Agent, where you want to export the connection profile.
4. From the Control-M/CM Host Name drop-down list, select the Control-M/Agent that contains the
target Control-M MFT to export the connection profile.
5. Click OK.
The Export Connection Profile Destination dialog box appears.
6. In the Connection Profile Name field, enter a name for the exported connection profile and click
OK.
If you want to change parameters to this connection profile, see Editing a connection profile (on page
375).
7. Click Test (optional).
If the test completed successfully, the connection profile is validated and you can now define a MFT
job, as described in Defining a Control-M job. If the test failed, review the error message and test it
again.
8. Click OK.

377
12

Silent mode connection profile management

12
Before you can define an MFT job in Control-M, you need to create a connection profile, which enables
you to connect to the required server to transfer files.
A connection profile contains the connection parameters to a specified server(s), such as host name, port,
communication protocols, username, and password. By creating a connection profile, you enable users to
connect to the required server with only the connection profile name. Users then can define or modify a
job without having to provide authentication and connection attribute details every time they connect to a
server.
The following procedures describe how to create, update, delete, and test a connection profile in the
silent mode:
 Creating a connection profile (on page 378)
 Editing a connection profile (on page 382)
 Deleting a connection profile (on page 382)
 Testing a connection profile (on page 383)

Creating a connection profile

This procedure describes how to create a connection profile in silent mode, which enables you to define
an MFT job in Control-M.
NOTE: To run the ctmaftacc utility on Windows, you need to open the command line as an administrator.
 To create a connection profile:
 From a command line, type the required silent mode parameters, as described in Silent mode
parameters (on page 380).
 The operation parameters (add, update, del) must follow the agent parameters on Windows. On
UNIX, the operation parameter must appear first.
 If you are running this utility on UNIX, all instances of backslash "\" must be doubled "\\".
The following example defines a new connection profile called local_SFTP where host1 is the local
computer and host2 is an SFTP server.
EXAMPLE: ctmaftacc -add -account local_SFTP -emuser ftpuser -host1 djgh64 -ostype1 unix -user1
ctmagent -pswd1 ctmpass -home1 /home/ctmagent/ -host2 yotli17 -ostype2 unix -port2
22 -user2 ftpuser -pswdenc2 00510-570-57011900100-2200340110 -home2
/home/ftpuser/ -security2 sftp -compress2 N
The following example defines a new connection profile called FTP_SSL where host1 is a remote
FTP server and host2 is a remote FTP over SSL/TLS server.

378
Control-M Administrator Guide

EXAMPLE: ctmaftacc -agent Default -add -account FTP_SSL -emuser ssluser -host1 lucia65 -ostype1
OS400 -port1 21 -user1 ctmagent -pswd1 ctmpass -home1 /home/ctmagent/ -host2
baegh51 -ostype2 windows -port2 21 -user2 dghdom\\ftpuser -pswdenc2
00510-570-57011900100-2200340110 -home2 c:\\ftpuser\\ -security2 ftp_ssl

379
Control-M Administrator Guide

Silent mode parameters

The following table lists the silent mode parameters.

Parameter Description

agent Defines the name of the Control-M/Agent on which

Control-M MFT is installed (Windows only).

Connection profile Defines the name of the connection profile.

emuser Defines the authorized EM users.

If there is more than one Control-M/EM user, they must be
enclosed in quotes (") and separated by a pipe symbol (|).

host1, host2 Defines the name of the host computer.

ostype1, ostype2 Determines which platform the host resides. If you are
defining a connection profile on a Microsoft Windows
computer, see Configuring connection details for a remote
Windows server (on page 439) (Remote side only)

user1, user2 Defines the username of each host.

If it is a local host on Windows, the domain name must be
specified. If it is a remote host on Windows, the domain
name might need to be specified if required by the server.

pswd1, pswd2 Defines the password for each user connection profile

home1, home2 Determines the home directory for each host. that appears
in the File Selection dialog box in the MFT properties pane.
Control-M MFT supports both Name Format 0 and Name
Format 1. The syntax of the home directory determines
which format is used (OS/400 platforms only).

port1, port2 Determines the port used to communicate for each host.
Defaults are:
 FTP: 21
 SFTP: 22

pswdenc1, pswdenc2 Defines the encrypted password for each user connection
profile
If you are using a plain text password, encrypt the
password, as described in Encrypting a password.

security1, security2 Defines the communication protocol as FTP_SSL or SFTP for

380
Control-M Administrator Guide

Parameter Description
each host.

compress1, compress2 Compresses the file before the transfer for each host.

Destsize Verifies the size of the file after a successful transfer.

If a file transfer has spaces in the file name and it fails
during this verification, you must not select this option, as
some FTP servers do not list file names with spaces.
This option is only available on Windows and UNIX FTP
servers.

Checksum Verifies that the file transferred correctly by executing MD5

checksum on the FTP server.
Notes: This option is available only for FTP Servers that
support either the XMD5 or the SITE CHECKSUM checksum
commands.
For UNIX FTP servers, ensure that the md5sum program is
installed on the FTP server search path, to enable the SITE
CHECKMETHOD MD5 and SITE CHECKSUM commands to
work properly.

Restart Resumes the file transfer from the point that it failed.
If you connect to an FTP server, you must select this option,
as well as the Rerun from point of failure checkbox in
the Properties pane, as described in Defining a Control-M
job. If you are using a different connection type, select the
Rerun from point of failure checkbox in the job
properties pane..

Keyfile1, Keyfile2 Defines the path and file name for key authentication for
each host.

Passphr1, Passphr2 Defines the password of the private key file for each host.

Passphrenc1, Defines the encrypted password of the private key file for
Passphrenc2 each host.
If you are using a plain text password, encrypt the
password, as described in Encrypting a password

Passive1, Passive2 Initiates the data and control connections from the MFT
client to the FTP server, which solves firewall issues. For
more details about FTP Active and Passive modes, see
Configuring an FTP firewall in active and passive mode (on
page 440).

381
Control-M Administrator Guide

Parameter Description

SubIpAdd1, SubIpAdd2 Forces passive connections to use the host address.

CCC1, CCC2 Sets the transmission mode in a control connection from an

encrypted mode to clear text mode. This means that you
can secure sensitive information, including your user name
and password, by sending them in an encrypted mode, and
then use the CCC sub-command to change the transmission
mode back to clear text mode to send the port and IP
information (FTP over SSL/TLS).

CDC1, CDC2 Encrypts the connection process while files are transferred
without encryption. You can select this option if you want
your login information encrypted and your files transferred
without encryption.

IMPLICIT1, IMPLICIT2 Automatically creates an SSL connection between the MFT

client and the FTP server (Default port 990). In SSL Explicit
mode, the MFT client connects to the FTP server and then
changes the connection to SSL mode (FTP over SSL/TLS).

SSL_LEVEL1, SSL_LEVEL2 Defines the SSL security levels for the host as 2, 3, or 4. For
more details about SSL security levels, see FTP over SSL/TLS
configuration (on page 433).

Editing a connection profile

This procedure describes how to update a connection profile in silent mode, which enables you to define
an MFT job in the Control-M.
NOTE: To run the ctmaftacc utility on Winodws, you need to open the command line as an administrator.
 To edit a connection profile:
 From a command line, update the required parameters, as described in Silent mode parameters (on
page 380).
The following example updates a connection profile called local_SFTP, by changing the password for
user1 and the user name password and home directory on host2.
EXAMPLE: ctmaftacc -agent Default -update -account local_SFTP -pswd1 pasnew -user2 slavaft
-pswdenc2 00170-570-64011650100-2218340126 -home2 /home/slavaft/

Deleting a connection profile

This procedure describes how to delete a connection profile in silent mode.

382
Control-M Administrator Guide

NOTE: To run the ctmaftacc utility on Winodws, you need to open the command line as an administrator.
 To delete a connection profile:
 From a command line, type the following command and apply the required values, as described in
Silent mode parameters (on page 380).
ctmaftacc [-agent agent_name] -del -account account_name

Testing a connection profile

This procedure describes how to test a connection profile in silent mode, to confirm that you are able to
connect to the required FTP servers.
NOTE: To run the ctmaftacc utility on Winodws, you need to open the command line as an administrator.
NOTE: When you run a Control-M OS job that tests a connection profile, you need to use the -batch
parameter
 To test a connection profile:
1. Do one of the following:
a. To test a single connection profile, type the following:
ctmaftacc [-agent agent_name] -validate -account account_name
b. To test all connection profiles, type the following:
ctmaftacc [-agent agent_name] -validate -account
2. Apply the required values for each parameter, as described in Silent mode parameters (on page 380).

MVS file template management

The following procedures describe how to add, update, copy, and delete MVS File templates that are used
to determine how to handle MVS file transfers.
 Creating an MVS file template (on page 383)
 Editing an MVS file template (on page 386)
 Copying an MVS file template (on page 386)
 Deleting an MVS file template (on page 387)

Creating an MVS file template

This procedure describes how to create an MVS file template in the Control-M Configuration Manager that
is used to determine how to handle MVS file transfers.
 To create an MVS file template:
1. From the Control-M Configuration Manager, select Control-M Managed File Transfer, right-click
and select MVS File Template management.
The Control-M for MFT MVS File Templates Management window appears.

383
Control-M Administrator Guide

2. Click the icon.

The MVS File Template Details dialog box appears.
3. For each field type the required value, as described in MVS template parameters (on page 385).
4. Click OK.
The MVS file template is added to the Control-M for MFT MVS File Templates Management
window.

384
Control-M Administrator Guide

MVS template parameters

The following table lists the MVS template parameters.

Parameter Description

Template Name Defines the name of the MVS template.

The first character cannot be an integer.

Record Format Determines the value for the record format

Logical Record Length Determines the logical record length values between
0-32760

Block Size Determines the block size values between 0-32760

Translate Table Determines what table is used by the FTP server during
transfer for translation (8 characters maximum)

Transfer Mode Determines the mode used to transfer files:

Block: Transfers the file as a series of data blocks preceded
by one or more header bytes.
Stream: Transfers the file as a stream of bytes.
Transfer mode is valid only for transfer of files from MVS to
MVS.

SMS Management Class Determines which SMS Management Class is assigned to a

new data set

DBCS Encoding Determines which DBCS data sets are used for the transfer

Allocation Units Determines which allocation unit type is used for the transfer

Volume Defines the volume value (6 characters maximum)

Unit Defines unit value (8 characters maximum)

Primary Defines the primary allocation amount between 1-16777215

Secondary Defines the secondary allocation amount between

1-16777215

SMS Data Class Defines the SMS Data Class provided by your organization
for the FTP server.

385
Control-M Administrator Guide

Parameter Description

Transfer to unique file Creates a file with a unique name on the remote system
instead of overwriting an existing file. The FTP server on the
remote system sends the name of the created file back to
the MFT client.
When you select this option, you cannot do any of the
following:
Use a temporary prefix for the destination file
Rename the destination file
Rerun from point of failure

Additional Options Defines MVS FTP Server SITE command sub-parameters and
(Host1, Host2) values (214 characters maximum)

Editing an MVS file template

This procedure describes how to update an MVS file template in the Control-M Configuration Manager that
is used to determine how to handle MVS files after a transfer.
 To edit an MVS file template:
1. From the Control-M Configuration Manager, select Control-M Managed File Transfer, right-click
and select MVS File Template management.
The Control-M for MFT MVS File Templates Management window appears.

2. Select the MVS file template that you want to update and click the icon.
3. Update the required parameters, as described in MVS template parameters (on page 385).
4. Click OK.
The MVS file template is updated.

Copying an MVS file template

This procedure describes how to copy an MVS file template in the Control-M Configuration Manager that is
used to determine how to handle MVS files after a transfer.

 To copy an MVS file template:

1. From the Control-M Configuration Manager, select Control-M Managed File Transfer, right-click
and select MVS File Template management.
The Control-M for MFT MVS File Templates Management window appears.

2. Select the MVS file template that you want to copy and click the icon.
3. Update the required parameters, as described in MVS template parameters (on page 385).

386
Control-M Administrator Guide

4. Click OK.
The MVS file template is copied.

Deleting an MVS file template

This procedure describes how to delete an MVS file template in the Configuration Manager.

 To delete an MVS file template:

1. From the Control-M Configuration Manager, select Control-M Managed File Transfer, right-click
and select MVS File Template management.
The Control-M for MFT MVS File Templates Management window appears.

2. Select the MVS file template that you want to delete and click the icon.
A confirmation message appears.
3. Click OK.
The MVS file template is deleted.

PGP template management

Control-M MFT transfers can integrate with your PGP application, which enables you to encrypt files on a
local computer before a transfer and decrypt files on a local computer after a transfer.
NOTE:
 To enable PGP integration into Control-M for MFT, you must have a PGP application, which supports
batch command line operations, installed on the local computer.
 To execute PGP commands, you need to add the user, that is defined in the connection profile in the
host where the Local CM checkbox is selected, to specific policies in the Local Security Settings
window, as described in Adding users to Local Security policies (on page 441) (Windows only).
The following procedures describe how to create, update, copy, and delete PGP templates, which enable
you to define PGP commands for each transfer.
 Creating a PGP template (on page 387)
 Editing a PGP template (on page 390)
 Copying a PGP template (on page 391)
 Deleting a PGP template (on page 391)

Creating a PGP template

This procedure describes how to create a PGP template in the Control-M Configuration Manager, which
can be used to define PGP commands in the properties pane.

387
Control-M Administrator Guide

NOTE: BMC Software recommends that you use one of the pre-defined GnuPG or PGP templates supplied
by Control-M MFT, which define the command line parameters for these PGP applications. To use one of
the pre-defined templates, see Copying a PGP template (on page 391).
 To create a PGP template:
1. From the Control-M Configuration Manager, select the Control-M Managed File Transfer on the
host that you want to manage, right-click, and select PGP Template Management.
The Control-M for MFT - PGP Templates Management window appears.

2. Click the icon.

The Control-M for MFT-PGP template details dialog box appears.
3. For each field, type the required value, as described in PGP template parameters (on page 389).
4. Click OK.
The PGP template appears in the Control-M for MFT- PGP Templates Management window.

388
Control-M Administrator Guide

PGP template parameters

The following table lists the PGP template parameters.

Parameter Description

Template Name Defines the name of the PGP template (30 characters
maximum length).

PGP Executable Full Path Defines the location and name of the executable file for the
PGP application

Exit Code Defines the code of a successful PGP operation

Passphrase Defines the passphrase that is used to decrypt the file

Confirm Passphrase Confirms the passphrase that is used to decrypt the file

Recipient Determines the name of the recipient that is defined in the

encrypt command

389
Control-M Administrator Guide

Parameter Description

Encryption/Decryption Defines the PGP command line parameters for

Parameters encryption/decryption.
The following variables can be used:
$$PGP_PASSPHRASE$$: Determines the passphrase that
is defined in the Passphrase field. This provides additional
security as you do not have to write the passphrase in the
PGP command.
$$PGP_RECIPIENT$$: Determines the recipient name
that is defined the Recipient field.
$$PGP_INPUT_FILE$$: Determines the name of the file
to encrypt/decrypt
$$PGP_OUTPUT_FILE$$: Determines the name and the
location of the encrypted/decrypted file. You need to use
this variable with the output option of your PGP application.
You must use both $$PGP_INPUT_FILE$$ and
$$PGP_OUTPUT_FILE$$ when defining a PGP template,
otherwise Control-M MFT fails to complete the PGP
operation.
You must define either encrypt or decrypt parameters, or
both.
Encrypt GnuPG example: -e -r $$PGP_RECIPIENT$$ -o
$$PGP_OUTPUT_FILE$$ $$PGP_INPUT_FILE$$
Decrypt GnuPG example: -d --batch --passphrase
$$PGP_PASSPHRASE$$ -o $$PGP_OUTPUT_FILE$$
$$PGP_INPUT_FILE$$

Editing a PGP template

This procedure describes how to edit a PGP template in the Control-M Configuration Manager, which can
be used to define PGP parameters in the properties pane.
NOTE: You cannot edit pre-defined PGP templates (highlighted in red).
 To edit a PGP template:
1. From the Control-M Configuration Manager, select the Control-M Managed File Transfer on the
host that you want to manage, right-click, and select PGP Template Management.
The Control-M for MFT - PGP Templates Management window appears.

2. Select the template that you want update and click the icon.
The Control-M for MFT-PGP Template details dialog box appears.

390
Control-M Administrator Guide

3. For each field, update the required value, as described in PGP template parameters (on page 389).
4. Click OK.
The PGP template is updated.

Copying a PGP template

This procedure describes how to copy a PGP template in the Control-M Configuration Manager.
 To copy a PGP template:
1. From the Control-M Configuration Manager, select the Control-M Managed File Transfer on the
host that you want to manage, right-click, and select PGP Template Management.
The Control-M for MFT - PGP Templates Management window appears.

2. Select the template that you want to copy and click the icon.
The Control-M for MFT-PGP Template details dialog box appears.
3. In the Template Name field, type a name for the new template and click OK.
The PGP template is copied.

Deleting a PGP template

This procedure describes how to delete a PGP template in the Control-M Configuration Manager.
NOTE: You cannot delete pre-defined PGP templates (highlighted in red).

 To delete a PGP template:

1. From the Control-M Configuration Manager, select the Control-M Managed File Transfer on the
host that you want to manage, right-click, and select PGP Template Management.
The Control-M for MFT - PGP Templates Management window appears.

2. Select the PGP template that you want to delete and click the icon.
A confirmation message appears.
3. Click Yes.
The template is deleted.
Chapter

Generating SSH keys

This procedure describes how to generate an SSH private and public keys in the Control-M Configuration
Manager, which enables the SFTP client to authenticate itself to the SFTP server instead of using a
password. After the keys are generated, you need to send the public key to the SFTP server administrator
to activate public key authentication.

391
Control-M Administrator Guide

NOTE: If you upgraded to Control-M for AFT 8.2 or Control-M MFT, your previous SSH keys were
migrated during the installation. The new keys retain their original name and location, but they no longer
have a .ppk extension. If your SSH keys were not migrated, an error message might appear in the
installation log. If that occurs, you need to generate new keys from the CCM.
 To generate SSH keys:
1. From the Control-M Configuration Manager, select the Control-M Managed File Transfer on the
host that you want to manage, right-click, and select Generate SSH key.
The Control-M for MFT- Generate SSH Key dialog box appears.
2. In the Key Name field, type the name for the private and public keys.
3. In the Key Passphrase area, do the following:
a. In the Passphrase field, type the password of the private key file.
b. In the Confirm Passphrase field, re-type the password of the private key file.
4. In the Key generation parameters area, select the required parameters and click Save.
The public and private keys are generated and saved in the Control-M/Agent computer in the
following location:
<Control-M/Agent_Home_Dir>\cm\AFT\data\keys
NOTE: Generated keys defined with larger bits provides more security. However, you might receive a
timeout message if generated on a slower computer. Verify that the keys were generated by checking
the above location.
5. To extend the timeout period, see:
• Extending the timeout period in Control-M/EM (on page 441)
• Extending the timeout period in Control-M/Server (on page 442)
6. To save the public key locally, click Yes.
7. Select the filename and location for the public key, which can be later distributed to the SSH server.
The key is saved on the Control-M/EM client local computer.
8. Add the private key path and file name and passphrase to a connection profile, as described in
Creating a connection profile (on page 363).

Authorizing an SSH host

This procedure describes how to re-authorize an SSH host in the Control-M Configuration Manager, which
ensures that you connect to the correct SFTP server. The host authorization key might change when you
reinstall the SSH server, or if you are working in a cluster environment you need to authorize all nodes in
the cluster before creating a connection profile. If the key changed or you did not authorize all cluster
nodes, the next job fails, and the output reports HOST NOT AUTHORIZED.
Contact your SFTP server administrator to verify if the signature has changed.
 To authorize an SSH host:
1. From the Control-M Configuration Manager, select the Control-M Managed File Transfer on the
host that you want to manage, right-click and select Authorize SSH Host.

392
Control-M Administrator Guide

The Authorize SSH Known Host dialog box appears.

2. From the Host Name drop-down list, select the name of the host that you want to re-authorize.
3. In the Port field, type the port of the host.
4. Click Authorize.
5. If you are working in a cluster environment and need to authorize multiple hosts in the cluster that
have different signatures, do the following:
a. Select Cluster.
b. In the Cluster Name field, type the name of the host that you want to authorize.

c. Click and in the Physical Host Name field, type the cluster logical name.
d. Click Authorize.
6. Click Close.
The SSH host is authorized.

Configuring Control-M for MFT parameters

This procedure describes how to configure Control-M for MFT parameters in the CCM.
 To configure Control-M for MFT parameters:
1. From the CCM, select the Control-M Managed File Transfer on the host that you want to manage,
right-click, and select Configuration Management.
The Control-M for MFT - Configuration Management dialog box appears.
2. In each field, type or select the required value, as described in Control-M for MFT configuration
parameters (on page 394).
3. Click OK.
The Control-M for MFT parameters are configured.

393
Control-M Administrator Guide

Control-M for MFT configuration parameters

The following table lists the Control-M for MFT configuration parameters.

Parameter Description

Number of retries Determines the number of connection attempts between

0-99 after a connection failure to an FTP server (Default: 5).
When the remote FTP server is running on an MVS system,
this parameter has no effect.

Connection timeout Determines the number of seconds the MFT client attempts
to establish a connection to an FTP server before a timeout
(Default: 30)

Time between retries Determines the number of seconds between each

connection attempt to an FTP server (Default: 6)

PGP temporary directory Determines the temporary location where PGP files are
stored (Default:
<Control-M/Agent_Home_Dir>\cm\AFT\pgp_tmp.)
The users that are defined in the connection profile in the
host where the Local CM checkbox is selected, must have
read and write permissions in the PGP temporary directory.

Debug Level Determines the debug level of Control-M MFT.

NOTE: If the debug level of the Control-M/Agent is higher
than Control-M MFT, then the debug level of Control-M MFT
is based on the Control-M/Agent (Default: 0).

SSL Debug trace Determines whether the Control-M for MFT SSL diagnostics
must run.
NOTE: To view SSL trace information in the log, add the
following flag to the Java command in the ctmaftcontainer
script:
-Djavax.net.debug=ssl:[flag]
Example:
-Djavax.net.debug=ssl
-Djavax.net.debug=ssl:record
-Djavax.net.debug=ssl:handshake:data

Use PAM password Authenticates the local host with PAM based authentication
authentication (Solaris, HP-UX, and Linux computers only)

394
Control-M Administrator Guide

Parameter Description

Web Proxy Determines whether to transfer files through a Web Proxy

server
NOTE: Supports FTP, FTPS, SFTP, and S3.

Proxy Host Defines the hostname of the proxy server

Proxy Port Defines the port number of the proxy server

Proxy User Defines the username of the proxy server

Proxy Password Defines the user's password of the proxy server

Interval between file Determines the range in seconds (1-9999) between

searches successive attempts to detect the existence of a file and the
range between attempts to monitor the size of a file after it
is detected (Default: 30)

Number of iterations Determines the numbers of attempts (1-999) to monitor the

while size is static file size when it is static after it has reached its minimum
detected size (Default: 3)

Checks that the file is not Checks if the file is used by another process or application
in use on a local host. If it is, then the watch action fails.
You must have the lsof utility on your computer and it must
exist in the root user path, and the Control-M/Agent must
run as root user. Otherwise this check does not function
properly (UNIX only).

Interval between retries Determines the number of seconds (1-9999) to wait before
Control-M for MFT attempts to perform a post action on the
source or destination file after a successful transfer, as
described in Advanced general parameters (Default: 5).

Number of retries Determines the number of retries (0-999) Control-M for MFT
attempts to perform the post action on the source or
destination file after a successful transfer, as described in
Advanced general parameters (Default: 3).

Editing mass connection profiles

This procedure describes how to edit connection profiles parameters such as hostname, username, and
password, that are used in multiple connection profiles in the Control-M Configuration Manager.

395
Control-M Administrator Guide

 To edit mass connection profiles:

1. From the Control-M Configuration Manager, right-click Control-M Managed File Transfer and
select Mass Connection Profile Update.
The Control-M for MFT - Mass Connection Profiles Update dialog box appears.
2. For each field, type the required value, as described in Mass connection profile update parameters (on
page 397).
3. Click OK.
The Control-M for MFT - Update Connection Profiles Summary window appears.
4. To view the update results, double-click the required row.

396
Control-M Administrator Guide

Mass connection profile update parameters

The following table lists the mass connection profile update parameters.

Parameter Description

Control-M/Server Name Determines the Control-M/Server that contains the

Control-M/Agent, where you want to perform a mass
update.
To perform a mass update across all Control-M/Servers, see
Editing mass connection profiles (on page 395).

Control-M Host Name Determines the Control-M/Agent or ALL Control-M/Agents

that contains the connection profile on the CM, where you
want to perform a mass update.

Host Name Defines the hostname of the parameter that you want to
update.
If you are updating a password or a username for a local CM
host, you must type Local in this field.

User Name Defines the username of the parameter that you want to
update.
NOTE: If you are typing a username with a backslash (\),
type two backslashes such as ADPROD\\cuser.

Update the Determines whether you are updating a hostname,

username, or a password to a connection profile.
NOTE:
 If you are updating a hostname, you cannot update a
local CM host.
 If you are updating a username, and you do not define a
New password and/or a New home directory, the fields
are not updated.

Configuring the File Transfer Server

This procedure describes how to configure the File Transfer Server in the CCM, which enables you to
transfer files directly from one MFT host to another MFT host, without using an FTP server on a third
computer. The File Transfer Server is included on every Control-M/Agent that has Control-M MFT
installed, supports both FTP/S and SFTP, and is embedded in the MFT process.

397
Control-M Administrator Guide

NOTE: Verify that the Control-M/EM server you are connected to has the Control-M MFT Deployment
Package installed.
 To configure the File Transfer Server:
1. From the CCM, select Control-M Managed File Transfer on the host that you want to manage,
right-click and select File Transfer Server.
The File Transfer Server window appears.
2. Configure the following File Transfer server parameters:
• File Transfer Server general parameters (on page 399)
• FTP/FTPS server parameters (on page 400)
• SFTP server parameters (on page 401)
• File Transfer Server Authentication parameters (on page 402)
3. Click Save.
4. Restart the File Transfer Server by running one of the following commands:
• UNIX: cm/AFT/exe/startb2b.sh
• Windows: cm\AFT\exe\startb2b.sh

Connecting to the SFTP Server with Public Key Authentication

This procedure describes how to connect to the SFTP Server with Public Key authentication without
logging in with a user and password for each connection.
NOTE: The File Transfer Server only accepts SSH keys with a non-empty passphrase.
 To connect to the SFTP Server:
1. Generate client public keys or use existing keys from your SFTP client.
If your client is Control-M MFT, see Generating SSH keys (on page 391).
2. Navigate to the following location:
<Agent_Home>\CM\AFT\data\
3. Open the authorized_keys file and add a new line with the following format:
<user> <key format> <key content>
EXAMPLE: cuser ssh-rsa
AAAAB3NzaC1yc2EAAAAB97sd6f7f6dsfe3sdfsdalkjhfsdklafdufdsAJSDJKAJDHGjhgaSDjhgAj
khgA

398
Control-M Administrator Guide

File Transfer Server general parameters

The following table describes File Transfer Server general parameters.

Parameter Description

Host Defines the hostname where the File Transfer Server is installed

Home directory Defines the root path where transfered files are stored.
NOTE: If you want to use a different directory for each logged in
user, you must add \${userName} to the path.
EXAMPLE: C:\temp\${userName}
Bob connects to the File Transfer Server and uploads the file a.txt
to the root directory, the file is saved in
C:\temp\Bob\a.txt.
Default:<Agent_Home>/CM/AFT/ftshome/${userName}

Multiple login allowed Determines whether multiple users can connect to the File
Transfer Server simultaneously.
NOTE: FTP only

Max. logins Determines the number of users that can connect to the File
Transfer Server simultaneously
NOTE: FTP only

Max login failures Determines the maximum number of login attempts that are
allowed before no more logins are allowed for the period of time
defined by the next parameter
NOTE: FTP only

Delay between failed login Determines the number of seconds to wait after a login failure
attempts before the next attempt
NOTE: FTP only

Throttling activated Determines whether to limit number of simultaneous uploads and

downloads.

Max simultaneous uploads Determines the maximum number of simultaneous uploads

Max simultaneous downloads Determines the maximum number of simultaneous downloads

399
Control-M Administrator Guide

FTP/FTPS server parameters

The following table describes FTP/FTPS server parameters.

Parameter Description

Enable server Determines whether the File Transfer Server that supports client
connection via FTP/FTPS is enabled

Port Determines the port number that the File Transfer Server listens
to for FTP/FTPS connections
NOTE:This port is used by clients to connect to the FTP/FTPS
server (Default: 1221).

Authentication Authenticates the FTP user with one of the following methods:
 Windows local user
 LDAP
 PAM (UNIX only)

Secured Determines whether FTPS is enabled

Keystore file path Defines the path to the file that contains the server certificate.
NOTE: The keystore must be in PKCS#12 format. If FIPS is
enabled, the format must be BCFKS.

Keystore file password Defines the password of the file that contains the server certificate

Ciphers Lists the names of ciphers used for FTPS.

If no ciphers are specified, all available ciphers are supported.

Listen for implicit connections Determines whether to automatically turn on security after a
connection is established between the FTPS client and the
Managed File Transfer server.

Passive Port/s: Limits the range of dynamic ports that can be used for passive
connections in FTP. Ports can be defined as single ports, closed or
open ranges. Multiple definitions must be separated by commas.
EXAMPLE:
2300 :Uses 2300 as the passive port
2300-2399:Uses all ports in the range
2300-:Uses all ports larger than 2300
2300, 2305, 2400-: Uses 2300 or 2305 or any port larger than
2400

400
Control-M Administrator Guide

SFTP server parameters

The following table describes SFTP server parameters.

Parameter Description

Enable server Determines whether the File Transfer Server that supports client
connection via SFTP is enabled

Port Determines the port number that the File Transfer Server listens
to for SFTP connections
NOTE:This port is used by clients to connect to the SFTP server
(Default: 1222).

Keystore file path Defines the path to the file that contains the client's certificate

Keystore file password Defines the password for the file that contains the server's
certificate.
NOTE: The keystore must be in PKCS#12 format. If FIPS is
enabled, the format must be BCFKS.

Ciphers Lists the names of ciphers used for SFTP.

Known user file path Defines the path to the file that contains known users by SFTP

Authentication Authenticates the FTP user with one of the following methods:
 Windows local user
 LDAP
 PAM (UNIX only)

Override home directory for Determines which internal users can override their specific home
specific internal users directory to connect to the FTS/Hub with SFTP. The home
directory changes are saved in the fts_config.proerties file in
the following format:
home.directory.expression.<user>=<home_dir>
NOTE: The home directory can be a network path in the UNC
format.

401
Control-M Administrator Guide

File Transfer Server Authentication parameters

The following table describes LDAP Authentication parameters.

Parameter Description

Search user Defines the LDAP Browse user

Password Defines the password of the user defined in the Search user field.
The value of this field can be left blank if the Search user does not
have a defined password.

URL Defines the URL address and (optionally) port of a directory server
ldap(s)://<server>:<port>

Base DN Defines the point from where the server will search for users.
EXAMPLE: ou=sales,dc=company,dc=us,dc=com

Username Attribute Defines the name of the LDAP attribute that determines the
username. The search users perform a lookup for any login user
on this attribute.

DN Attribute Defines the name of the LDAP attribute that determines the user
DN (distinguished name). After the search users perform lookup
for any login user based on the Username Attribute, it verifies
authentication with the user DN (which appears in the user’s DN
attribute).

Timeout Determines the number of milliseconds to wait before a timeout

(Default: 30000)

The following table describes the PAM authentication parameters:

Parameter Description

Service name Defines the PAM service name (default passwd)

NOTE: In non-root mode, you can only authenticate the
Control-M/Agent user. To authenticate other users, you must run
as root.

402
Control-M Administrator Guide

Control-M MFT Enterprise B2B

Control-M MFT Enterprise B2B is an MFT add-on that enables you to securely transfer and receive files to
and from external users outside of your organization. Internal users can transfer files externally with File
Transfer jobs, while external users transfer files to and from your organization via a BMC-provided web
application or third-party FTP client.
To use Control-M MFT Enterprise B2B, you need to define external users and virtual folders. Virtual folders
are the locations where external users transfer and receive files. Each folder has an incoming sub-folder
where files are sent by external users to your organization, and an outgoing sub-folder where files are
sent by internal users to external users. Authorizations are applied at the folder level to determine which
external users can access the folders. Folders can be configured to define a maximum retention period,
and can generate email notifications to associated users when new files are available.
The following diagram shows the Control-M MFT Enterprise B2B architecture.

Control-M MFT Enterprise B2B includes the following main components:

 MFT Enterprise B2B Hub:The Hub is the File Transfer Server that is installed with Control-M MFT
and is used to manage external file transfers. After MFT Enterprise B2B is enabled, the File Transfer
Server configuration is managed in the Hub settings. The Hub allows internal and external users to
log in, whereas the File Transfer Server only allows internal users to log in.
 MFT Enterprise B2B Gateway: A proxy server that is installed in the DMZ and listens for incoming
SFTP, FTPS, and HTTPS connections from external user accounts defined in the MFT B2B Hub. The
MFT Enterprise B2B Gateway communicates with the Hub, but does not store any transfer file data.
NOTE: REST API is also supported on an HTTPS connection. If you want to use REST API to access
the B2B Gateway, you can see the REST API available calls/documentation at the following URL:

403
Control-M Administrator Guide

 MFT Enterprise B2B File Exchange: A web application that enables external users to view the
contents of their folders, and upload and download files.
Files are transfered between the Hub (File Transfer Server) within your organization, and external users
via the Control-M MFT Enterprise B2B Gateway in the DMZ.
To get started with Control-M MFT Enterprise B2B, see Setting up the Control-M MFT Enterprise B2B
environment (on page 404).

Setting up the Control-M MFT Enterprise B2B environment

This procedure describes how to set up the Control-M MFT Enterprise B2B environment.
Before you begin
Ensure that you have installed the following:
 Control-M/EM 9.0.20
 Control-M/Server 9.0.18.200 and higher
 Control-M/Agent 9.0.18.200 or higher
 To set up:
1. Install the Control-M MFT Deployment package on a Control-M/EM server 9.0.20, as described in
Control-M Managed File Transfer installation.
2. Deploy Control-M MFT (on page 345) 9.0.20 to at least one Control-M/Agent.
3. Install Control-M MFT B2B on a Control-M/EM server.
4. Install Control-M MFT B2B Gateway in the DMZ on a Linux computer, as described in Installing the
Control-M MFT Enterprise B2B Gateway on Linux.
5. Enable a B2B Hub (on page 406).
6. Create External users (on page 408) and Virtual Folders (on page 409).
7. Provide external users with their login credentials (username, password,and port) to the MFT
Enterprise B2B File Exchange website or third-party FTP client.
8. Create an SFTP connection profile using the Hub as the host with port 1222, as described in Creating
a connection profile (on page 363).
9. Transfer files between external and internal users, as described in Defining a Control-M job.

Setting up a Control-M MFT B2B AS2 configuration

Applicability Statement 2 (AS2) is a standard used to transfer EDI and other data in real time. The AS2
protocol facilitates the ability to exchange AS2 EDI messages over HTTP/S protocol.
This procedure describes how to set up a Control-M MFT B2B AS2 configuration, which enables you to
transfer and receive files with an AS2 trading partner.

 To set up a Control-M MFT B2B AS2 configuration:

1. Add your AS2 key pair and trading partner’s AS2 certificate to the Control-M MFT keystore by doing
the following:

404
Control-M Administrator Guide

a. From the java keytool, import your key pair and partner’s certificate to the
data/as2/keys/as2_keystore.pfx file.
Keystore default password is: password
b. Record the Alias names used for your key and for your partner’s certificate.
c. Provide your public certificate key to the partner (so they can add it to their keystore).
2. Create an AS2 connection profile, as described in Creating a connection profile (on page 363).
Verify that Partner Certificate Alias defined in AS2 parameters (on page 370) is the same alias
defined in step 1.
3. Test the connectivity to the AS2 server, as described in Testing a connection profile (on page 376).
A test file is sent to the AS2 server. You can configure the filename and content of the test file by
editing the as2.testFileUploadPath parameter value in the data/aft_configurable.properties
file.
4. Define the partner on the Hub by creating an external user, as described in Creating external users
(on page 408) (Do not define AS2 settings yet).
5. Create a virtual folder on the Hub where AS2 messages are stored and associate the partner with it,
as described in Creating Virtual Folders (on page 409).
6. Select the user you created above and add the AS2 settings, as described in Creating external users
(on page 408).
The partner’s AS2 ID and Alias must be similar to the values specified in the Connection Profile.
7. Configure AS2 settings on the Hub, as described in AS2 Settings (on page 422).
Verify that the AS2 Listener is selected and ports are available.
8. Define a File Transfer job that sends files to partner's AS2 server, as described in Defining a Control-M
job.
Verify that the selected connection profile is Local to AS2.

Setting up High Availability for Control-M MFT Enterprise

This procedure describes how to set up High Availability for Control-M MFT Enterprise, which enables you
to add multiple Hubs and Gateways in your environment. This ensures that file transfers between external
and internal users are successful even if one Hub or Gateway is down. In this environment,
communication is bidirectional. The Hub communicates with the Gateway via port 9443 and Gateway
communicates with the Hub via port 7443.

405
Control-M Administrator Guide

NOTE: BMC recommends to set up at least three Hubs and two Gateways.
Before you begin:
 All Hubs must be on version 9.0.20 or higher and installed on the same platform (Windows or Linux)
 All Gateways must have the same authentication password that is defined during installation.
 Verify that firewall ports are opened (GTW > Hub: 1222, 7443; Hub > GTW: 9443, Hub x<->Hub y:
3180-3183)
 All Control-M/Agents must be part of the same Host Group. For more information, see Host group
management (on page 332).
 BMC recommends to move MFT keystore files to a shared location to simplify maintenance.

 To set up High Availability for Control-M MFT Enterprise:

1. Complete all steps described in Setting up the Control-M MFT Enterprise B2B environment (on page
404).
2. Define additional Hubs and Gateways, as described in Adding Hubs and Gateways (on page 407).
3. Create a shared drive for uploaded files and define the path in the Home Directory field in General
Settings (on page 416).
All Hubs must have read/write access to this path.
After your environment is setup, the following data is synced between all Hubs and Gateways.
• MFT Enterprise database entities, such as Users, Folders, Groups, and Rules
• MFT Enterprise configuration parameters, such as Hub settings, and Gateway settings
• MFT Enterprise host data: (data/zoo.cfg file, data/gateways.json file)
• MFT Enterprise profiles and templates, such as Connection Profiles, PGP templates, and MVS
templates
4. Set up a load balancer and distribute the load between the Gateways for all incoming requests via
HTTPS (9443), SFTP (1224), FTP (1223) and AS2 (10083/7).
5. Define the load balancer's public domain name/IP in the Domain Name, as described in Gateway
Settings (on page 428).
EXAMPLE: If the load balancer can be accessed on https://file.company.com:9443, define
files.company.com)
The load balancer must be configured to work with session stickiness (all requests on the same
session must be routed to the same Gateway).

Enabling an MFT Enterprise B2B Hub

This procedure describes how to enable an MFT Enterprise B2B Hub, which allows file transfers to and
from the Control-M MFT Enterprise B2B Gateway. The MFT Enterprise B2B Hub uses the File Transfer
Server to transfer files.
After the Hub is enabled, all File Transfer Server configuration is managed from the Hub Settings (on
page 415).

406
Control-M Administrator Guide

NOTE: You can enable one MFT Enterprise B2B Hub per Control-M/EM server.
 To enable an MFT Enterprise B2B Hub:
1. From the Manage tab, click MFT B2B.
If the button is disabled, you need to install Control-M MFT B2B, as described in Control-M MFT
Enterprise B2B installation.
The MFT B2B window appears.
2. Click Add Hub.
3. Do the following:
a. From the Select B2B hub environment drop-down list, select the host where Control-M MFT is
installed.
NOTE: You can only select a Control-M MFT 9.0.18 or higher that is installed on a
Control-M/Agent 9.0.18 or higher.
b. In the Gateway Authentication Password field, type the same password you used when you
installed the Control-M MFT Enterprise B2B Gateway.
c. In the Domain Name field, type the domain name of the MFT Enterprise B2B File Exchange
website where external users can transfer using HTTP.
EXAMPLE:or 172.99.98.77:<HTTP_Port>
d. In the Company Name field, type the name of your company.
This name appears in the MFT Enterprise B2B File Exchange website and the email notification
signature.
e. In the Company Support Email field, type the email address that is used to send and receive
email notifications to and from external users.
4. Click Create.
The MFT Enterprise B2B Hub is enabled.

Adding Hubs and Gateways

This procedure describes how to add additional Hubs and Gateways to your Control-M MFT Enterprise
environment. This ensures that file transfers between external and internal users are successful even if
one Hub or Gateway is down.
NOTE: BMC recommends to set up at least three Hubs and two Gateways.

 To add Hubs and Gateways:

1. From the Environment tab, do one or more of the following:
• To add a Hub, do the following:

a. From the MFT B2B Hubs pane, click .

b. From the Add Agent drop-down list, select one of the available Control-M/Agents to be a Hub
and click Save.
NOTE:

407
Control-M Administrator Guide

o All Control-M/Agents must be on the same platform (Windows or Linux) and part of the same
host group.
o After a new Hub host is added to the environment, all its Connection Profiles, PGP and MVS
templates will be overwritten with the existing host data. BMC recommends to add a new
MFT host to the environment.
• To add a Gateway:

c. From the MFT B2B Gateways pane, click .

d. Type the hostname and the port where the Gateway is installed and click Add.
2. Repeat these steps to add additional Hubs and Gateways.

Creating external users

This procedure describes how to create MFT Enterprise B2B external users, which enables them to
transfer and receive files via the File Exchange website or a third party FTP client.
Before you begin
 Enable an MFT Enterprise B2B Hub, as described in Enabling an MFT Enterprise B2B Hub (on page
406)

 To create external users:

1. From the Manage tab, click MFT B2B.
The MFT B2B window appears.

2. From the Users tab, click .

3. Do the following:
a. In the User Name field, type the name of the new external user.
b. In the Password field, create a password for the external user.
c. In the Email field, type the email address of this user.
d. In the Phone Number field, type the phone number of the user.
e. In the Company Name field, type the name of the organization that this user belongs to.
f. In the Description field, provide a description of this user.
g. In the SSH Setting area, in the SSH Public Key field, type the ssh-rsa key format.
h. In the AS2 Setting area, do the following:
a. In the AS2 ID field, type the logical name of the trading partner.
b. In the Partners Certificate Alias field, type the alias of the partner certificate that is stored
in the AS2 keystore
c. In the AS2 Destination Folder, select the authorized virtual folder where the uploaded file
must be saved.
If the virtual folder doesn't exist, the AS2 messages is stored in
/cm/AFT/as2/server/inbox.

408
Control-M Administrator Guide

Creating Groups
This procedure describes how to create a group of external users, which are then applied to Virtual
Folders. This allows you to give permissions to multiple users to Folders without listing every individual
user.You can also create a group that consists of LDAP groups.
Before you begin
 Enable an MFT Enterprise B2B Hub, as described in Enabling an MFT Enterprise B2B Hub (on page
406)
 o create a group:
1. From the Manage tab, click MFT B2B.
The MFT B2B window appears.

2. From the Groups tab, click .

3. Do the following:
a. In the Group Name field, type the name for the group.
b. In the External Users field, type the names of the external users that you want to be part of this
group.
c. In the LDAP Groups field, type the names of the LDAP groups that you to be included in this
group (comma separated values).
To enable this option, you must enable LDAP external users authentication, as described in
Authentication Settings (on page 417) and define LDAP Settings for External Users (on page 425).

Creating Virtual Folders

This procedure describes how to create MFT Enterprise B2B Virtual Folders. These folders are used to
transfer incoming and outgoing files between external and internal users. Authorizations are applied at
the folder level that determine which external and internal users can access the folders. Folders can be
configured to define a maximum retention period, and can generate email notifications to associated
users when new files are available.
Before you begin
 Enable an MFT Enterprise B2B Hub, as described in Enabling an MFT Enterprise B2B Hub (on page
406).
 To create Virtual Folders:
1. From the Manage tab, click MFT B2B.
The MFT B2B window appears.

2. From the Virtual Folders tab, click .

3. Do the following:
a. In the Virtual Folder Name field, type the name of the folder.
By default the following sub-folders are automatically created within this folder in the Hub
environment:

409
Control-M Administrator Guide

o Incoming:Files sent by external users to your organization.

o Outgoing:Files sent by internal users to external users.
b. In the Size Limit field, type the maximum number of GB allowed before file uploading is blocked
for external and internal users.
NOTE: If the value is set to 0, files uploading is unlimited.
c. In the Retention Time field, type the maximum number of hours to keep the file, before it is
automatically deleted.
NOTE: If the value is set to 0, retention is unlimited.
NOTE: If a file was uploaded with the SFTP -p option, which preserves file attributes, the file
might be deleted. In this case, do not use the -p option or extend the retention, as required.
d. If you want to delete the file after an internal user has downloaded it from an incoming
sub-folder, select the Delete file after downloaded from incoming folder option (SFTP only).
e. If you want to enable external users to delete files from the outgoing folder of a virtual folder,
select Enable external users to delete files from outgoing.
f. In the Authorized External Users field, type the names of the external users that you want to
have access to this folder.
To notify users that a file is ready for download from the Outgoing sub-folder, select the Send
email notification to allowed users when a new file arrives checkbox.
g. In the Authorized Internal Users field, type the names of internal users that you want to have
access to this folder.
For all internal users, type *.
h. In the Allowed File Pattern field, type the file pattern that you want to allow external users to
upload to this folder.
NOTE: By default, all files are allowed to a folder.
EXAMPLE: *.txt,Receipt*.pdf
i. In the Blocked File Pattern field, type the file pattern that you want to exclude external users
from uploading to this folder.
4. Click Save.
The folder is created.

Creating an MFT Enterprise post processing rule

This procedure describes how to create an MFT Enterprise post processing rule. After an external user
uploads a file, the Hub receives it and processes the file based on defined rules such as moving the file to
another location and sending alert email messages.
EXAMPLES: Run anti-virus for each arriving file and delete it if the scan fails. Order a job that transfers
an arriving file from the Hub to a specific server. Copy all files that appear in
Folder1/incoming to backup directory on the network.

 To create an MFT Enterprise post processing rule:

1. From the Manage tab, click MFT B2B.

410
Control-M Administrator Guide

The MFT B2B window appears.

2. Select the Rules tab, and then click .

3. Do the following:
a. In the Name field, type the name of the rule.
b. In the Description field, describe the purpose the rule.
c. From the Priority drop-down list, select the priority level for this rule.
If you select a higher priority level, this rule will be processed before other matching rules.
1-Highest, 10-Lowest.
4. Click the Conditions tab, select one or more of the following conditions for this rule and then click
Add.
• If file name matches a pattern
• If file matches a certain size
• If file sent by specific user/company
• If arrives in specific virtual folder
NOTE: To create a rule that executes for every incoming file, leave the conditions section empty.
5. Apply the condition criteria, as described in Control-M MFT Enterprise rule conditions (on page 412).
6. Click the Actions tab, select one or more of the following actions for this rule and then click Add.
• Notify by email
• Move/Copy received file
• Order Control-M folder/job
• Raise Control-M condition
• Run command/script
NOTE: To ensure that jobs that are ordered close to New Day time are executed, set Max Wait to at
least 1 for Order Control-M folder/job.
7. Apply the action criteria, as described in Control-M MFT Enterprise rule actions (on page 412).
8. Click Save.

411
Control-M Administrator Guide

Control-M MFT Enterprise rule conditions

The following table describes the Control-M MFT Enterprise conditions that you can apply for each rule.

Parameter Description

If file name matches a pattern Determines whether the file matches a specific filename, a regular
expression, or if it is case sensitive
EXAMPLE: AAA.txt,B*.pdf,C???.csv

If file matches a certain size Determines the minimum and maximum file size in bytes, KB, MB,
or GB

If file sent by specific Determines which users or companies sent the file
user/company

If file arrives in specific virtual Determines which virtual folders external users can upload files to.
folder

Control-M MFT Enterprise rule actions

The following table describes the Control-M MFT Enterprise actions that you can apply for each rule.

412
Control-M Administrator Guide

NOTE: You can also use variables for each parameter, as described in Action rule variables (on page
414).

Parameter Description

Notify by email Defines the email address, subject, and message of the
notification. It also determines whether to abort, delete the file, or
continue to the next action if the action fails.

Move/Copy received file Determines whether to move or copy the file the file to a relative
or absolute path and whether to rename the destination file. It
also determines whether to abort, delete the file, or continue to
the next action if the action fails.

Order Control-M folder/job Determines which folder and jobs to order with order options and
variables. It also determines whether to abort, delete the file, or
continue to the next action if the action fails.

Raise Control-M condition Determines the Control-M condition name and condition date to
raise. It also determines whether to abort, delete the file, or
continue to the next action if the action fails.

Run command script Defines the executable command or script to run with successful
return codes..It also determines whether to abort, delete the file,
or continue to the next action if the action fails.
NOTE: Do not change the file name (by renaming or moving) if
one of the other matching rules is expected to use this file.

413
Control-M Administrator Guide

Action rule variables

The following table describes the variables that you can use as values for actions in a rule.

Variable Description

$$FILE_PATH$$ Defines the path of the file.

EXAMPLE: \b2bhome\Folder1\incoming\aaa.txt

$$FILE_ABS_PATH$$ Defines the absolute path of the file.

EXAMPLE:
C:\Agent\cm\AFT\ftshome\b2bhome\Folder1\incoming
\aaa.txt

$$FILE_DIR$$ Defines the parent directory of the file.

EXAMPLE: \b2bhome\Folder1\incoming

$$FILE_ABS_DIR$$ Defines the absolute parent directory path of the file.

EXAMPLE:
C:\Agent\cm\AFT\ftshome\b2bhome\Folder1\incoming

$$FILE_NAME$$ Defines the name of the file.

EXAMPLE:aaa.txt

$$FILE_NAME_NO_EXT$$ Defines the name of the file without an extension

$$FILE_EXT$$ Determines the file extension (including the "." character).

$$FILE_EXT_NO_DOT$$ Determines the file extension (without the "." character).

$$FILE_DATE$$ Defines the date of the file in YYYYMMDD format.

EXAMPLE:20180325

$$FILE_TIME$$ Defines the time of the file in HHmmSS format.

EXAMPLE:170459

$$FILE_SIZE$$ Determines the size of the file in bytes

$$USER$$ Determines which users are allowed

$$COMPANY$$ Determines which companies are allowed

$$VIRTUAL_FOLDER$$ Defines the virtual folder name

414
Control-M Administrator Guide

Hub Settings
The Hub settings are pre-configured and are based on the settings you have defined in the File Transfer
Server.
The following lists the Hub settings options:
 General Settings (on page 416)
 Authentication Settings (on page 417)
 HTTP Settings (on page 418)
 SFTP Settings (on page 419)
 FTP/S Settings (on page 420)
 LDAP Settings for Internal Users (on page 424)
 Notification Settings (on page 427)

415
Control-M Administrator Guide

General Settings
The following table describes the Hub general setting parameters.

Parameter Description

Hub Name Defines the logical name of the Hub.

Home Directory Defines the root path where transfered files are stored.
NOTE: If you want to use a different directory for each logged in
internal user, you must add \${userName} to the path.
EXAMPLE: C:\temp\${userName}
Bob connects to the File Transfer Server and uploads the file a.txt
to the root directory, the file is saved in
C:\temp\Bob\a.txt.
Default:<Agent_Home>/CM/AFT/ftshome/${userName}

B2B Subfolder Defines the name of the folder under the home directory that
contains all the Virtual Folders.
NOTE: For internal users, this folder is hidden. Internal user can
only access the B2B virtual folders by typing the B2B sub-folder
under the home dir.
EXAMPLE: /b2bhome/

Configuration Port Determines the port number used to access the Hub for
configuration changes.
Default: 28080

Send Audit Logs Determines whether to generate records to the database.

Log Level Determines one of the following log levels for the Hub:
 ERROR
 WARN
 INFO
 DEBUG
 TRACE

Enable external users to delete Determines whether to allow external users to delete files from
files from the outgoing virtual the outgoing virtual folder
folder

416
Control-M Administrator Guide

Authentication Settings
The following table describes the Hub authentication parameters.

Parameter Description

Gateway Authentication Determines the authentication password between the MFT

Password Enterprise B2B Gateway and the Hub. This is the same password
set during the MFT Enterprise B2B Gateway installation.
NOTE: If you change the password, you must the also define the
new password in proxyConfig.properties file on the host where
the Gateway is installed and restart the Gateway.

Internal users authentication Determines one of the following authentication methods for
method (SFTP/FTP) internal users for both SFTP and FTP:
 Windows Local Users (Windows only)
 PAM (UNIX only)
 LDAP
NOTE: (PAM) You can only authenticate the Control-M/Agent user
in non-root mode. To authenticate other users, you must run as
root.

External users authentication Determines one of the following authentication methods for
method external users:
 Authenticate LDAP users
 Authenticate Control-M MFTE users
 Both: The user is authenticated first in the MFT Enterprise
users list. If the authentication fails, another attempt occurs in
the LDAP list.

417
Control-M Administrator Guide

HTTP Settings
The following table describes HTTP Settings for the MFT Enterprise B2B File Exchange web application.

Parameter Description Location

HTTP Port Determines the HTTP or HTTPS port number for the MFT  Hub Settings
Enterprise B2B File Exchange.
 Gateways
NOTE: Settings
 If you change this parameter in Gateway Settings, you must
change it in the proxyConfig.properties file in the
Gateway and restart the Gateway.
 If you set the port below 1024, which is a privileged port
(well-known ports), the MFT Gateway must be executed as
root user.

Enable SSL Determines whether to enable HTTPS.  Hub Settings

NOTE: If you change this parameter, you must change it in the  Gateways
Hub and Gateway settings and in the hub.ssl parameter in the Settings
proxyConfig.properties file in the Gateway and restart the
Gateway.

Keystore File Determines the path for the HTTPS keystore file.  Hub Settings
Path
NOTE: The keystore must be in PKCS12 format. If FIPS is  Gateways
enabled, the format must be BCFKS. Settings

Keystore File Determines the password that is used by the Hub to access the  Hub Settings
Password HTTPS keystore.
 Gateways
Default: password (Hub), abcd1234 (Gateway) Settings
NOTE: If you change this password, the keystore password is
not changed. For more information, see Changing the MFT
keystore password (on page 437).

Session Timeout Determines the number of seconds to wait before a timeout. Hub Settings

418
Control-M Administrator Guide

SFTP Settings
The following table describes the SFTP settings between the Hub and the MFT Enterprise B2B Gateway.

Parameter Description Location

SFTP Port Determines the port number that the embedded Hub/Gateway  Hub Settings
listens to for SFTP connections.
 Gateways
NOTE: Settings
 This port is used by clients to connect to the SFTP server
 If you set the port below 1024, which is a privileged port
(well-known ports), the MFT Gateway must be executed as
root user.
Default: 1222 (Hub), 1224 (Gateway).

Keystore File Defines the path to the file that contains the client's certificate.  Hub Settings
Path
NOTE: The keystore must be in PKCS12 format. If FIPS is  Gateways
enabled, the format must be BCFKS. Settings

Keystore File Defines the password for the file that contains the server's  Hub Settings
Password certificate.
 Gateways
Default: abcd1234 Settings
NOTE: If you change this password, the keystore password is
not changed. For more information, see Changing the MFT
keystore password (on page 437).

Allowed Ciphers Determines the cipher security settings used for SFTP.  Hub Settings
 Gateways
Settings

Authorized Keys Defines the path to the file that contains authorized users by Hub Settings
File Path SFTP.
NOTE: The authorized users file must include all internal users’
public keys. Each user should be included in the following
format:
<username> <ssh public key (ssh-rsa format)>

419
Control-M Administrator Guide

FTP/S Settings
The following table describes FTP/S settings between the Hub and the MFT B2B Gateway.

Parameter Description Location

Listen for FTP/S Determine whether the Hub/Gateway that supports client Hub Settings
connection connection with the FTP/FTPS protocol is enabled.
NOTE: When internal users connect with FTP/S, they
cannot access the B2B sub-folder. To access the B2B
sub-folder from inside the organization, use SFTP
protocol.

FTP Port Determines the port number that the embedded  Hub Settings
Hub/Gateway listens to for FTP/FTPS connections.
 Gateways Settings
NOTE:
 This port is used by clients to connect to the
FTP/FTPS server.
 If you set the port below 1024, which is a privileged
port (well-known ports), the MFT Gateway must be
executed as root user.
Default: 1221 (Hub), 1223 (Gateway).

Allow multiple open Determines whether multiple users can connect to the  Hub Settings
sessions Hub/Gateway simultaneously.
 Gateways Settings

Maximum Concurrent Determines the number of users that can connect to the  Hub Settings
Open Sessions Hub/Gateway simultaneously.
 Gateways Settings

Maximum Login Determines the maximum number of login attempts  Hub Settings
Failures before a timeout.
 Gateways Settings

Delay Between Login Determines the number of seconds to wait after a login  Hub Settings
Failures failure before the next attempt.
 Gateways Settings

Secured FTP Enabled Determines whether FTPS is enabled.  Hub Settings

NOTE: If you change this parameter, you must change it  Gateways Settings
in the Hub and Gateway settings and in the hub.ssl
parameter in the proxyConfig.properties file in the
Gateway and restart the Gateway

420
Control-M Administrator Guide

Parameter Description Location

Keystore File Path Defines the path to the file that contains the server  Hub Settings
certificate.
 Gateways Settings
NOTE: The keystore must be in PKCS12 format. If FIPS
is enabled, the format must be BCFKS.

Keystore File Defines the password of the file that contains the server  Hub Settings
Password certificate.
 Gateways Settings
Default: password (Hub), abcd1234 (Gateway)
NOTE: If you change this password, the keystore
password is not changed. For more information, see
Changing the MFT keystore password (on page 437).

Allowed Ciphers Determines the cipher security settings used for FTPS.  Hub Settings
 Gateways Settings

Listen for Implicit Determines whether to automatically turn on security after  Hub Settings
Connection a connection is established between the FTPS client and
the Managed File Transfer server.  Gateways Settings

Passive Ports Limits the range of dynamic ports that can be used for  Hub Settings
passive connections in FTP. Ports can be defined as single
ports, closed or open ranges. Multiple definitions must be  Gateways Settings
separated by commas.
EXAMPLE:
2300 :Uses 2300 as the passive port
2300-2399:Uses all ports in the range
2300-:Uses all ports larger than 2300
2300,2305,2400-: Uses 2300 or 2305 or any port larger
than 2400

421
Control-M Administrator Guide

AS2 Settings
The following table describes the Hub AS2 settings.

Parameter Description

Listen for AS2 settings Determines whether the Hub/Gateway that supports client
connection with the AS2 protocol is enabled

AS2 Port Determines the port on the Hub where AS2 listens for messages

MDN Port Determines the port on the Hub to listen for MDN receipts

AS2 ID Defines the logical name of your AS2 server

AS2 Email Defines the email address of the AS2 server

AS2 Keystore File Path Defines the location where AS2 keystore that contains your
certificate and all partner certificates is located

AS2 Keystore File Password Defines the AS2 keystore password.

NOTE: If you change this password, the keystore password is not
changed. For more information, see Changing the MFT keystore
password (on page 437).

AS2 Keystore Key Alias Defines the alias of your AS2 Server in the keystore

Set file name from Content Determines whether to name the file as the Content Disposition
Disposition Header Header only if it exists

Set file name from the HTTP Determines whether to name the file according to the filename
header 'filename' parameter parameter value in the HTTP header

422
Control-M Administrator Guide

Parameter Description

Default AS2 File Name Pattern Determines whether to name the file with the defined default
value:
Default:
AS2_${AS2_FROM}_${UUID}.${MIME_TYPE_EXTENSION}
Valid variables:
 ${AS2_FROM}
 ${AS2_TO}
 ${UUID}
 ${MIME_TYPE_EXTENSION}
 ${MSG_ID}
NOTE: To avoid overwriting files, use the unique ${UUID} or
${MSG_ID} variables.

423
Control-M Administrator Guide

LDAP Settings for Internal Users

The following table describes the LDAP or PAM settings for the Hub. These parameters are for internal
users only.

Table Header Table Header

LDAP Search User Defines the LDAP Browse user.

LDAP Search Password Defines the password of the user defined in the LDAP Search User
field. The value of this field can be left blank if the Search user
does not have a defined password.

LDAP Server URL Defines URL address and port of a directory server, the DN of an
entry within that server, or the criteria for performing a search
within that server.
ldap(s)://<server>:<port>

Base DN Defines the starting domain name for the user search in the
directory tree structure.
EXAMPLE:sales.company.us.com,dc=sales,
dc=company,dc=us,dc=com.
This field must have a value if the LDAP Search User field is left
blank. Otherwise the default value is the domain where the search
user is located.

Home Directory Defines the LDAP Home Directory.

Timeout Determines the number of milliseconds to wait before a timeout.

The following table describes the PAM authentication parameters:

Parameter Description

Service name Defines the PAM service name (default passwd)

NOTE: In non-root mode, you can only authenticate the
Control-M/Agent user. To authenticate other users, you must run
as root.

424
Control-M Administrator Guide

LDAP Settings for External Users

The following table describes the LDAP settings for external users.

Table Header Table Header

LDAP Search User Defines the LDAP Browse user that is used to connect to LDAP
and search for users.

LDAP Search Password Defines the password of the user defined in the LDAP Search User
field. The value of this field can be left blank if the Search user
does not have a defined password.

LDAP Server URL Defines URL address and port of a directory server, the DN of an
entry within that server, or the criteria for performing a search
within that server.
ldap(s)://<server>:<port>

Base DN Defines the starting domain name for the user search in the
directory tree structure.
EXAMPLE:sales.company.us.com,dc=sales,
dc=company,dc=us,dc=com.
This field must have a value if the LDAP Search User field is left
blank. Otherwise the default value is the domain where the search
user is located.
You can use multiple Base DNs separated by a semicolon.

Group Search Base DN Defines the starting domain name for the group search in the
directory tree structure.
EXAMPLE:sales.company.us.com,dc=sales,
dc=company,dc=us,dc=com.

Username Attribute Defines the LDAP vendor column attribute for the LDAP username

DN Attribute Defines the LDAP vendor column attribute for the distinguished
name

First Name Attribute Defines the LDAP vendor column attribute for the first name of the
LDAP user

Las Name Attribute Defines the LDAP vendor column attribute for the last name of the
LDAP user

Company Name Attribute Defines the LDAP vendor column attribute for the company name

Email Attribute Defines the LDAP vendor column attribute for the email

425
Control-M Administrator Guide

Table Header Table Header

Group Name Attribute Defines the LDAP vendor column attribute for the LDAP group
name

Member Attribute Defines the LDAP vendor column attribute for the member

Description Attribute Defines the LDAP vendor column attribute for the description

SSH Public Key Attribute Defines the LDAP vendor column attribute for the SSH Public key

AS2 ID Attribute Defines the LDAP vendor column attribute for the AS2 ID

AS2 Certificate Alias Attribute Defines the LDAP vendor column attribute for the AS2 Certificate
Alias

AS2 Target Folder Defines the LDAP vendor column attribute for the AS2 Target

Timeout Determines the number of milliseconds to wait before a timeout.

426
Control-M Administrator Guide

Notification Settings
The following table describes notification settings that enables MFT Enterprise B2B to send email
notifications to external users that files have arrived. Notifications are sent when a file is uploaded with
SFTP to the Hub as an internal user. The SMTP settings must be valid.

Parameter Description

SMTP Host Defines the hostname that sends the email notifications.

SMTP Port Defines the SMTP port number.

SMTP Username Defines the username that is used to send the notifications.

SMTP Password Defines the SMTP password.

SMTP Security Method Determines one of the following SMTP security methods:
 SMTP without TLS
 SMTP with STARTTLS
 SMTPS (SMTP over TLS)

Sender Address Defines the email address that is used to send the email
notification.

Sender Name Defines the name of the sender that appears on the notification
mail signature.
NOTE: If this field is left empty, then the Company Name defined
in Site Settings (on page 428) is used.

427
Control-M Administrator Guide

Gateway Settings
The following table describes the MFT Enterprise B2B Gateway settings.

Parameter Description

Domain Name Defines the MFT Enterprise B2B File Exchange website domain
name that is accessed by external users.
http(s)://<domain_name>:<HTTP_port>

Log Level Determines one of the following log levels for the Gateway:
 ERROR
 WARN
 INFO
 DEBUG
 TRACE

HTTP Settings See HTTP Settings (on page 418).

SFTP Settings See SFTP Settings (on page 419).

FTP/S Settings See FTP/S Settings (on page 420).

AS2 Settings See AS2 Settings (on page 422)

Site Settings
The following table describes the File Exchange settings for each external web application.

Parameter Description

Company Name Defines your company name that appears in the MFT Enterprise
B2B File Exchange web application and email notification
signature.

Company Support Email Defines your company's email address that is available for external
users from the File Exchange web application and as the sender
address for email notifications.
NOTE: This field can be overwritten by the Sender Name field in
Notification Settings (on page 427).

428
Control-M Administrator Guide

Changing the Control-M MFT B2B Gateway password

This procedure describes how to change the Control-M MFT B2B password.
 To change the password:
1. Log into the computer where the Control-M MFT B2B Gateway is installed.
2. Navigate to the following directory:
mft_proxy/data/proxyConfig.properties
3. Change the value of the gateway.password parameter to the new password.
4. Restart the Control-M MFT B2B Gateway, by running the following commands:
a. shut-mft-proxy.sh
b. start-mft-proxy.sh

429
13

Configuration procedures
13
The following procedures describe how to configure Control-M MFT additional functionality:
 FTP over SSL/TLS configuration (on page 433)
 Configuring connection details for a remote Windows server (on page 439)
 Configuring LDAP with SSL (on page 439)
 Configuring an FTP firewall in active and passive mode (on page 440)
 Configuring an SFTP firewall (on page 441)
 Adding users to Local Security policies (on page 441)
 Extending the timeout period in Control-M/EM (on page 441)
 Extending the timeout period in Control-M/Server (on page 442)
 Configuring Control-M in the aft_configurable.properties file (on page 447)

430
Control-M Administrator Guide

Control-M MFT Security

The following table lists the available options you can use to secure and encrypt connections in Control-M
MFT.

Option Description

PGP encryption For push or pull actions (where the File Transfer job initiates a
connection to a remote server directly and uploads or downloads a
file), you can use PGP templates in File Transfer jobs to encrypt a
file before uploading to remote server, or decrypt it after
downloading to a local host. For more information, see PGP
template management (on page 387).
NOTE: BMC does not provide the PGP utiltiy. You must install it
separately.
For incoming files from external partners (where they initiate the
connection to the Control-M MFT Enterprise Gateway and upload
an encrypted file to the Hub), you can either use processing rules
or File Watcher jobs to decrypt. For more information, see
Creating an MFT Enterprise post processing rule (on page 410).
EXAMPLE: Define a rule with the condition files from specific
partner that has a pgp extension and run a script that
decrypts them so they are decrypted in the Hub's file
system.
Or, define a file watcher job that watches the specific folder,
downloads the file locally, and decrypts it. This can be
followed by another job that sends the decrypted file
to an application that can process it.

431
Control-M Administrator Guide

Option Description

SFTP (SSH)  Uses libraries that depend on JCE

 File Transfer jobs support both password and key
authentication
 FTS/Hub accepts clients with both password and key
authentication
 Generates a key pair (openssh libs, minimum key length is
1024)
 The private/public keys are stored in a local file system, with
rw permission only for the Control-M /Agent account.
 The public key must be stored in a remote SSH server’s
authorized_keys file.
 FTS/Hub also has authorized_keys file where the Admin can
add other user keys (ssh-rsa format) for remote users to
connect.
 Fingerprints of remote servers (hostkeys) are stored in a local
file (known_hosts) to allow verifying remote host after
connecting.
 By default, the first connection is accepted, and block future
connection if the host key has changed. This behavior can be
changed.
 Cipher:
blowfish-cbc,3des-cbc,aes128-cbc,aes192-cbc,aes256-cbc,aes
128-ctr,aes192-ctr,aes256-ctr,3des-ctr,arcfour,arcfour12
8,arcfour256
 Key exchange:
diffie-hellman-group-exchange-sha1,diffie-hellman-group1-sha
1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-
sha256,ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nis
tp521
 MAC: hmac-md5, hmac-sha1, hmac-md5-96, hmac-sha1-96
 Host key type:
ssh-dss,ssh-rsa,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecd
sa-sha2-nistp521

432
Control-M Administrator Guide

Option Description

SSL/TLS  File Transfer jobs and FTS support FTP connection over SSL
(FTPS)
 Hub supports HTTPS
 SSL/TLS is supported in Encryption only, Server Authentication
only, and Both Server and Client authentication.
 Supports TLS1.2
 FTP Client supports both Explicit/Implicit SSL, CCC/CDC.
 Several keystore files for storing remote servers’ CA x.509
certificates and a few keystores for the server to store its
and clients certificates and keys (for different protocols: FTPS,
HTTPS, AS2)
 Supports PKCS12 and BCFKS keystore formats.
 For FTPS, we support more than 70 different ciphers by
default. On FIPS mode, some ciphers are disabled.

Secured data in configurations  MFT secure data is stored encrypted with AES256 (local key
that can be rotated)
 Secure data is also transferred encrypted with AES256
 External user passwords are stored hashed (cannot be
decrypted)
 Control-M components can communicate over SSL

FTP over SSL/TLS configuration

To configure your support for FTP over SSL/TLS, you must do the following if you want to define jobs
with Control-M MFT via an FTP over SSL/TLS server.
 SSL Security levels (on page 434): Describes how to define your security level
 Certification (on page 434): Describes how to configure Control-M MFT for server and client
authentication
 Changing the MFT keystore password (on page 437): Describes how to change the key database
password from the default password that is configured with Control-M MFT to a more secure
password

433
Control-M Administrator Guide

SSL Security levels

There are three SSL security levels, as follows:

Security Level Authentication Client certificate Security

2 No Authentication Not sent Low

3 Server Authentication Not sent Moderate

4 Server and client Authentication Sent High

You can define the security level per host in a connection profile utility, as described in FTP protocol
parameters (on page 368).

Certification
An SSL certificate is a small data file that digitally binds a cryptographic key to to an organization's details
and is used to authenticate a connection between a client and server.
The following procedures describe how to configure Control-M MFT for server and client configuration
 Configuring Control-M MFT for server authentication (on page 434)
 Configuring Control-M MFT for client authentication (on page 435)
 Configuring Control-M MFT for an alternative CA (on page 436)
If you want to authenticate the identity of the server and the server to authenticate the client, you must
complete both procedures.
Control-M MFT uses a Java Keytool as key and certificate management utility. It allows you to manage
your own public/private key pairs and certificates. Java Keytool stores the keys and certificates in a
keystore and protects the private keys and keystore with the same password.
The Java Keytool utility path is <Agent home directory>/cm/AFT/JRE/bin/keytool. Each certificate in a
Java keystore is associated with a unique alias.
NOTE: All paths described in the following procedures are written for UNIX users. Users of Microsoft
Windows must ensure that when following these commands, all occurrences of a foreslash ("/") are
changed to a backslash ("\").
NOTE:You must not use the sslcmd utility provided with Control-M/Agent. The utility and kdb format are
no longer supported by Control-M MFT.

Configuring Control-M MFT for server authentication

This procedure describes how to configure Control-M MFT for server authentication. To implement server
authentication, you must import the CA belonging to each of the FTP over SSL/TLS servers to which
Control-M MFT keystore.
 To configure Control-M MFT for server authentication:
1. Set the host security level to Level 3.

434
Control-M Administrator Guide

2. Copy the FTP over SSL/TLS server CA file to a temporary location on the computer on which
Control-M MFT is installed.
3. Navigate to the following location:
<Control-M/Agent home directory>/cm/AFT/JRE_LINK/bin/
4. Import the certificate for the CA as follows:
• FIPS ON: ./keytool -J-Djava.security.properties==<java_security_file_path>
-J--module-path="<ctm_agent>/ctm/cm/AFT/exe/providers"
-J-Dorg.bouncycastle.fips.approved_only=true -importcert -alias <server_alias> -file
<server_certificate_file> -keystore <keystore_file> -storepass <password> -storetype BCFKS
• FIPS OFF: ./keytool
-J-Djava.security.properties==<ctm_agent>/ctm/cm/AFT/data/java.security.mft
-J--module-path="<ctm_agent>/ctm/cm/AFT/exe/providers" -importcert -alias <server_alias>
-file <server_certificate_file> -keystore <keystore_file> -storepass <password>
Where <java_security_file_path> is as follows::
o Windows, Solaris and AIX: <ctm_agent>/ctm/cm/AFT/data/java.security.mft
o Linux: <ctm_agent>/ctm/cm/AFT/data/java.security.mft.bcf
NOTE: Ensure that the certificate is valid before you import it as a trusted certificate. View it with the
keytool -printcert command or the keytool -importcert command without the -noprompt option, and
verify that the displayed certificate fingerprints match the expected ones.

Configuring Control-M MFT for client authentication

This procedure describes how to configure Control-M MFT for client authentication that allows the server
to authenticate Control-M MFT. You can either use the Control-M MFT Certificate of Authentication (CA),
or you can use one supplied by an outside vendor, as described in Configuring Control-M MFT for an
alternative CA (on page 436).
 To configure Control-M MFT for client authentication:
1. Set the host security level to Level 4.
2. Configure Control-M MFT for server authentication, as described in Configuring Control-M MFT for
server authentication (on page 434).
3. Do one of the following:
• To use the Control-M MFT CA, use your server’s Import utility to import clientCA.crt file from
the following location:
<Control-M/Agent home directory>/cm/AFT/data/SSL/cert
• To use an alternative CA, you must configure Control-M MFT so that this CA is recognized by the
application, as described in Configuring Control-M MFT for an alternative CA (on page 436).
NOTE: All paths described in the following procedures are written for UNIX users. Users of Microsoft
Windows must ensure that when following these commands, all occurrences of a foreslash ("/") are
changed to a backslash ("\").

435
Control-M Administrator Guide

Configuring Control-M MFT for an alternative CA

This procedure describes how to configure Control-M MFT for client authentication using an alternative
CA.
Before you begin
 Create your own Java Keystore file.
 Generate a CSR and submit the request to the CA.
 Import the received certificate from the CA into the keystore.
 Export the CA certificate that authenticates the public key to a file.
NOTE: Use the same password to protect the keystore and its private keys.

 To configure Control-M MFT for an alternative CA:

1. Copy your keystore file to the following location:
<Control-M/Agent home directory>/cm/AFT/data/SSL/cert
2. Update the keystore filename, location, and type, in the following location, as described in Java
Keystore configuration (on page 437):
<Control-M/Agent home directory>/cm/AFT/data/ftpssl_config.properties
3. Update the password, as follows:
<Control-M/Agent_Home_Dir>/CM/AFT/exe/keystoreutil –changepassword –storepass
<your keystore password> –new_storepass <your keystore password> -keystoretype
AFT_SSL –keystore <full path to your keystore file>
The keystore file password is maintained, and the Control-M MFT SSL configuration file
ftpssl_config.properties is updated with the encrypted password.
4. Import the CA to your FTP server.

436
Control-M Administrator Guide

Java Keystore configuration

The following table describes Java Keystore configuration properties. A keystore is a database of
cryptographic keys, X.509 certificate chains, and trusted certificates. By default, Control-M MFT is installed
with a defined keystore file located in <Control-M/Agent home
directory>/cm/AFT/data/SSL/cert/aftkeystore.pfx.

Parameter Description

ssl.securitydir Defines the path to the security directory where Java keystore file
is located

ssl.keystore.filename Defines the keystore file name

ssl.keystore.type Determines the type of the keystore file (PKCS12 or JKS)

ssl.keystore.keyalias (Optional) Defines a unique alias in for the keystore.

Use this option if you set security level to Level 4 and you have
more than one private key entry in the keystore.
NOTE: If there is only one private key entry, there is no need to
set this property.

ssl.keystore.password Defines the encrypted password for the keystore. Use the same
password for keystore and private keys.
NOTE: The aftkeystore.pfx file is provided with the default
password: password. To ensure data security, change this
password immediately, as described in Changing the MFT keystore
password (on page 437). If you created a new keystore file in
Configuring Control-M MFT for an alternative CA (on page
436),use its password for future commands. If you already
changed it, use the new password.

Changing the MFT keystore password

This procedure describes how to change the keystore password and update the Control-M MFT SSL
configuration file with the new encrypted password.
NOTE: If this is the first time, you are changing the keystore password, the default password is
password.
 To change the keystore password:
1. Navigate to the following location:
<Control-M/Agent_Home_Dir>\CM\AFT\
2. Type the following command:
keystoreutil –changepassword –help

437
Control-M Administrator Guide

For keystoretype parameter choose: AFT_SSL

The keystore and Control-M MFT SSL configuration files are updated with the new password.

Creating your own keystore

This procedure describes how to create your own keystore for Control-M MFT and Control-M MFT B2B
Gateway.
 To create your own keystore:
1. Run the keytool for Control-M MFT and Control-M MFT B2B Gateway in the following locations:
• MFT: <Agent Home>/cm/AFT/JRE_LINK/bin
• MFT B2B Gateway: <Gateway Home>/mft-proxy/JRE/bin
2. Do one of the following:
• Generate a new keystore in PKCS#12 format by doing the following:
a. Run the following:
keytool -genkeypair -v -alias <my_alias> -keystore <keystorePath> -storetype
PKCS12 -keypass <keystore_password> -storepass <keystore_password> -keyalg
RSA -keysize 2048
b. Create a certificate signing request from a CA and then import the certificate reply from a CA
to the keystore.
• Generate a new keystore in PKCS#12 format and bring your own key-pair into the keystore by
doing the following:
c. Empty the keystore from public/private key-pair entry, as follows:
keytool -delete -alias <my_alias> -keystore <keystorePath> -storetype PKCS12
-storepass <keystore_password>
d. Ensure that the keystore is empty by running the following:
keytool -v -list --keystore <keystorePath> -storetype PKCS12 -storepass
<keystore_password>
e. Import the public/private key-pair stored in <file_location>.p12 (pfx) file into the keystore by
running the folllowing:
keytool -v -importkeystore -srckeystore <whateverthefileis.p12> -srcstoretype
PKCS12 - srcstorepass <whateverthefileis_password> -destkeystore
<keystorePath> -deststoretype PKCS12 -deststorepass <keystore_password>
• Convert an existing keystore in JKS/PKCS12 format to the PKCS#12 format.
EXAMPLE: keytool -v -importkeystore -srckeystore <srckeystorePath> -srcstoretype PKCS12
- srcstorepass <srcKeystorePassword> -destkeystore <destkeystorePath> -deststoretype
PKCS12 -deststorepass <destKeystorePassword>
For more specific information, see Keytool Documentation
https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html.

438
Control-M Administrator Guide

Configuring connection details for a remote Windows server

This procedure describes how to configure connection details for a remote Windows server, which enables
you to avoid any problems caused by this issue when defining a Control-M MFT connection profile.
There is no standard way in which Windows-based FTP/SFTP servers display the file system.
 To configure connection details for a remote Windows server:
1. From your local FTP/SFTP client, connect to the remote Windows FTP/SFTP server as follows:
a. FTP: enter ftp <host>
b. SFTP: enter sftp <username>@<host>
The FTP/SFTP server might require that you define the domain. Both the username and host must be
the same values you use when defining the connection profile.
NOTE: The SFTP Client Application name might vary, depending on the application or the platform on
which you are working.
2. Type your password.
3. From the command line, type pwd.
The user home directory is displayed.
The syntax of the path of the home directory indicates the operating system on which it is running.
4. Select the appropriate host OS Type in Connection Profile Management utility according to the
following:
a. If the path uses ‘/’, define the host as UNIX.
b. If the path uses ‘\’, define the host as Windows.
If you select UNIX as the OS Type, you should not transfer files in ASCII mode.
5. In the Connection Profile utility, ensure that home directory path name is defined using the same
syntax as that shown in the pwd command (see step 3).

Configuring LDAP with SSL

This procedure describes how to configure LDAP with SSL/TLS, which takes the LDAP certificate (signed
by CA) and adds it to the JRE trusted CA (cacerts) keystore.
 To configure LDAP with SSL:
1. Import the CA certificate that signed the LDAP directory’s certificate, by running the following:
<MFT JRE>/keytool -importcert -keystore <MFT JRE>/lib/security/cacerts -file
<certificate> -alias <unique name>
EXAMPLE: /home/ctmagent/ctm/cm/AFT/JRE_LINK/bin/keytool -v -importcert -keystore /home/
ctmagent/ctm/cm/AFT/JRE_LINK/lib/security/cacerts -file /p/qadata/LDAP/tlvldap.cer
-alias myldap
2. At the password prompt, type changeit.
3. Modify the LDAP Server URL parameter to use LDAPS, as described in LDAP Settings for Internal
Users (on page 424) (default SSL port is 636).

439
Control-M Administrator Guide

EXAMPLE: ldaps://tlv-ldp-srv.bmc.com:636
4. Restart the Hub.

Configuring an FTP firewall in active and passive mode

Control-M MFT supports both the Active Data Transfer Process, and the Passive Data Transfer Process,
enabling it to work behind a firewall and connect to remote FTP servers. The FTP mode is defined in the
Connection Profile utility, when you define the connection definition.
This procedure describes how to configure an FTP firewall in active and passive mode.

 To configure an FTP firewall in active and passive mode:

1. Open the following communication channels in the FTP server firewall:
• FTP server's port 21 from anywhere (Client Connects the Server)
• FTP server's port 21 to ports greater than 1023 (Server responds to client's control port)
• FTP server's port 20 to ports greater than 1023 (Server initiates data connection to client's data
port)
• FTP server's port 20 from ports greater than 1023 (Client sends ACKs to server's data port)
Active mode can be problematic for FTP clients behind a firewall because the FTP client does not
initiate the connection to the data port of the server; rather the server connects to the client port as
defined in the PORT command. Usually an outside system initiating a connection to the client is
blocked by the client firewall.
The FTP Passive Data Transfer mode was developed to resolve this issue. In Passive mode, the
following sequence of events occurs:
1. The client initiates both connections to the server, by first connecting to Server command port 21.
2. The client then issues the PASV command, (which requests that the Server open a random
unprivileged port for the data port, and sends the PORT command to the client).
3. The client then connects to the data Server port as specified in the PORT command.
2. Open the following communication channels in the FTP server firewall, to support Passive mode FTP:
• FTP server's port 21 from anywhere (Client connects the server)
• FTP server's port 21 to ports greater than 1023 (Server responds to client's control port)
• FTP server's ports greater than 1023 from anywhere (Client initiates data connection to random
port specified by server)
• FTP server's ports greater than 1023 to remote ports greater than 1023 (Server sends ACKs (and
data) to client's data port)
Problems can occur if an FTP server is behind a firewall, when FTP clients try to use passive mode to
connect to a temporary random port number on the FTP server machine. The most common of these
is that the firewall blocks the connection from the client to the server.

440
Control-M Administrator Guide

When a restrictive firewall (one that denies a connection except for a few well known ports) exists on
both the server and client sides, you should configure the firewall on the server side.Many FTP
servers allow the administrator to specify a range of ports for the FTP server to use. The
administrator can then limit the port range for the FTP server, and the firewall can then be configured
to allow connection for the specified FTP server port range.

Configuring an SFTP firewall

This procedure describes howe to configure an SFTP firewall.
 To configure an SFTP firewall:
 If the SSH server resides behind a firewall, open the SSH port for traffic.
The client usually connects to SSH server port 22.

Adding users to Local Security policies

This procedure describes how to add users, that are defined in the connection profile in the host where
the Local CM checkbox is selected to Administrators, which enable you to execute PGP commands
(Windows only).
 To add users to Administrators group:
1. From the Computer Management window, select Local Users and Groups -> Groups
->Administrators.
The Administrators Properties window appears.
2. Click Add to define the user name defined in the connection profile, and then click OK.
3. Click OK.

Extending the timeout period in Control-M/EM

This procedure describes how to extend the timeout period in Control-M/EM. and Control-M/Server, which
prevents timeouts from occurring when you are generating an SSH key in the Control-M Configuration
Manager.
 To extend the timeout period in Control-M/EM:
1. Log into the Control-M Configuration Manager, as described in the Control-M Administrator Guide.
2. From the Tools menu, select System Parameters > Control-M/EM System Parameters.
The Control-M/EM - System Parameters window appears.
3. Double-click the RemoteCmdTimeout parameter.
4. In the Value field, change the value to 3600.
5. Click Save, and then click Close.

441
Control-M Administrator Guide

Extending the timeout period in Control-M/Server

This procedures how to extend the timeout period in Control-M/Server, which prevents timeouts from
occurring when you are generating an SSH key in the Control-M Configuration Manager.
 To extend the timeout period in Control-M/Server:
1. Access the CTM_Server\data directory and open the config.dat file.
2. Check the file for the following parameter:
CTM_CONFIG_AGENT_TUNNEL_TIMEOUT <value>
3. Do one of the following:
a. If the parameter exists, change the value to 3600 or higher
b. If the parameter does not exist, add it to the file.
4. Restart the Control-M/Server Configuration Agent.

Setting the Output file permissions

This procedure describes how to configure the Control-M for MFT Output file permissions (UNIX only).
 To set the Output file permissions:
 Open the <Control-M/Agent_home_dir>/ctm/data/FILE_TRANS.dat file and add the
following line:
SYSOUT_MODE <required file permission>
EXAMPLE: SYSOUT_MODE 755
NOTE: If the SYSOUT_MODE is not configured in the FILE_TRANS.dat, but rather the Agent
CONFIG.dat, AFT uses the value configured in Agent CONFIG.dat.

Activating the Control-M for MFT debug level

This procedure describes how to activate the Control-M for MFT debug level, which enables you generate
Control-M for MFT debug information.
 To activate the Control-M for MFT debug level:
1. Raise the Control-M/Agent debug level to 4, as described in the Control-M Administrator Guide.
The debug files are created in the following location.
<Control-M/Agent_home_dir>/proclog
2. When you have all the required debug information, decrease the debug level to 0, as described in the
Control-M Administrator Guide.

442
Control-M Administrator Guide

Changing the blowfish key

This procedure describes how to change the blowfish key used to encrypt passwords in MFT accounts.
The password can be encrypted with a non default key for the Control-M/Agent version 7.0.00 fix pack 1
or later and Control-M for AFT version 7.0.00 or later.
 To change the blowfish key:
 Run the Control-M/Agent agkeystore utility that updates the key for Control- M/Agent, Control-M for
AFT, and all Application Plug-ins.
For more information about agkeystore, see the Control-M Utility Guide.

Enabling FIPS on Control-M MFT

This procedure describes how to enable FIPS on Control-M MFT.

Before you begin

 Back up all data before making any changes.

 To enable FIPS:
1. Create the environment variable MFT_FIPS set to ON on all Hub and Gateway hosts.
2. Create and configure FIPS compliant keystores, as described in Creating FIPS compliant keystores (on
page 445) on all Hub and Gateway hosts.
3. ModifyMFT client SSL configuration by opening the <Agent>/cm/AFT/ftpssl_config.properties
file and modify the relevant properties.
EXAMPLE: # The path to the security directory where keystore file resided
ssl.securitydir=${cm.home}/data/SSL/cert/fips
# The keystore file name
ssl.keystore.filename=aftkeystore.bcfks
# The keystore type
ssl.keystore.type=BCFKS
4. Modify the MFT Server SSL/SSH configuration by opening the
<Agent>/cm/AFT/data/fts_config.properties file and modify the relevant properties.
• ftp.secure.keystore=${cm.home}/data/SSL/cert/fips/ftskeystore.bcfks
• ftp.secure.keystore.type=BCFKS

443
Control-M Administrator Guide

• ftp.secure.ciphers=SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CB
C_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TLS_DHE_
RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_
256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_3DES_EDE_C
BC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_256_CBC_
SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC
_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_S
HA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_
ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECD
HE_RSA_WITH_AES_256_CBC_SHA
• ssh.host.keystore=${cm.home}/data/Keys/fips/keystore.bcfks
• ssh.host.keystore.type=BCFKS
• ssh.ciphers=AES128CBC,AES256CBC,AES192CBC,AES128CTR,AES192CTR,AES256CTR,TripleDESC
BC
NOTE: The FTP secure ciphers list does not include specific SHA functions security bits. If you want
to enforce a specific cipher suite, add it as a suffix, such as
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256.
5. Modify the Gateway configuration on the MFT Hub by opening the
<Agent>/cm/AFT/data/proxyConfig.properties file and modify the relevant properties.
• param.ftp.secure.keystore=${cm.home}/data/SSL/cert/fips/ftskeystore.bcfks
• param.ftp.secure.keystore.type=BCFKS
• param.ftp.secure.ciphers=SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_
EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TL
S_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WIT
H_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_3DES
_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_25
6_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_1
28_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_
CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS
_ECDHE_RSA_WITH_AES_256_CBC_SHA
• param.ssh.host.keystore=${cm.home}/data/Keys/fips/keystore.bcfks
• param.ssh.host.keystore.type=BCFKS
• param.ssh.ciphers=AES128CBC,AES256CBC,AES192CBC,AES128CTR,AES192CTR,AES256CTR,T
ripleDESCBC
• param.http.key.store.path=data/fips/ssl_keystore.bcfks
• param.http.key.store.type=BCFKS
NOTE: The FTP secure ciphers list does not include specific SHA functions security bits. If you want
to enforce a specific cipher suite, add it as a suffix, such as
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256.

444
Control-M Administrator Guide

Enabling FIPS on the Control-M MFT B2B Gateway

This procedure describes how to enable FIPS on the Control-M MFT B2B Gateway:
Before you begin
 Back up all data before making any changes.
 To enable FIPS:
1. Update the java.security file by renaming java.security.bcf to java.security in the following location:
<Gateway Home>/mft-proxy/JRE/lib/security/
2. Configure SunJSSE for FIPS mode, as follows:
a. Open the java.security file and add BCFIPS to the end of the following line:
security.provider.2=com.sun.net.ssl.internal.ssl.Provider BCFIPS
The list of providers must be in the following order:
o security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
C:DEFRND[SHA256];ENABLE{ALL};
o security.provider.2=com.sun.net.ssl.internal.ssl.Provider BCFIPS
o security.provider.3=sun.security.provider.Sun
o security.provider.4=sun.security.rsa.SunRsaSign
3. Configure the BouncyCastle provider to FIPS Approved mode by doing the following:
a. Navigate to the folllowing file:
/mft-proxy/exe/gateway.sh
b. Search for ./JRE/bin/java.
c. Add the following after the java command:
-Dorg.bouncycastle.fips.approved_only=true
4. Create and configure FIPS compliant keystores, as described in Creating FIPS compliant keystores (on
page 445).

Creating FIPS compliant keystores

This procedure describes how to create FIPS compliant keystores for Control-M MFT and Control-M MFT
B2B Gateway.
If using the JSSE in FIPS mode, the key-stores containing either the private server credentials, or the
private client credentials, must be readable using the BCFIPS provider. The only key-store type the
BCFIPS provider has available that is FIPS compliant is the BCFKS. When using the JSSE in FIPS mode,
the key-stores for private key credentials need to be BCFKS.The PKCS12 key store is not available in FIPS
mode of operation due to the algorithms required for PBE key generation in the PKCS12 standard.
NOTE: <java_security_file_path> must be one of the following:

445
Control-M Administrator Guide

 Windows, Solaris and AIX: <ctm_agent>/ctm/cm/AFT/data/java.security.mft

 Linux: <ctm_agent>/ctm/cm/AFT/data/java.security.mft.bcf
 To create FIPS compliant keystores:
1. Run the keytool for Control-M MFT and Control-M MFT B2B Gateway in the following locations:
• MFT: <Agent Home>/cm/AFT/JRE_LINK/bin
• MFT B2B Gateway: <Gateway Home>/mft-proxy/JRE/bin
2. Do one of the following:
• Generate a new keystore in BCFKS format by doing the following:
a. Run the following:
keytool -J-Djava.security.properties==<java_security_file_path> -J--module-path
="<ctm_agent>/ctm/cm/AFT/exe/providers" -J-Dorg.bouncycastle.fips.approved
_only=true -genkeypair -v -alias <my_alias> -keystore <keystorePath> -storetype
BCFKS -keypass <keystore_password> -storepass <keystore_password> -keyalg
RSA -keysize 2048
b. Create a certificate signing request from a CA and then import the certificate reply from a CA
to the keystore.
• Generate a new keystore in BCFKS format and bring your own key-pair into the keystore by doing
the following:
c. Empty the keystore from public/private key-pair entry, as follows:
keytool -J-Djava.security.properties==<java_security_file_path> -J--module-path
="<ctm_agent>/ctm/cm/AFT/exe/providers" -delete -alias <my_alias> -keystore
<keystorePath> -storetype BCFKS -storepass <keystore_password>
d. Ensure that the keystore is empty by running the following:
keytool -J-Djava.security.properties==<java_security_file_path> -J--module-path
="<ctm_agent>/ctm/cm/AFT/exe/providers" -v -list --keystore <keystorePath>
-storetype BCFKS -storepass <keystore_password>
e. Import the public/private key-pair stored in <file_location>.p12 (pfx) file into the keystore by
running the folllowing:
keytool -J-Djava.security.properties==<java_security_file_path>
-J--module-path="<ctm_agent>/ctm/cm/AFT/exe/providers" -v -importkeystore
-srckeystore <whateverthefileis.p12> -srcstoretype PKCS12 - srcstorepass
<whateverthefileis_password> -destkeystore <keystorePath> -deststoretype
BCFKS -deststorepass <keystore_password>
• Convert an existing keystore in JKS/PKCS12 format to the BCFKS format.
EXAMPLE: keytool -v -importkeystore -srckeystore <srckeystorePath> -srcstoretype PKCS12
- srcstorepass <srcKeystorePassword> -destkeystore <destkeystorePath> -deststoretype
BCFKS -deststorepass <destKeystorePassword>
For more specific information, see Keytool Documentation
https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html.

446
Control-M Administrator Guide

Control-M MFT keystores

The following table lists the Control-M MFT keystores and their locations.

Keystore Location Non-FIPS keystore FIPS keystore

FTS Keystore for fingerprints data\keystore\ keystore.pfx keystore.bckfs

MFT client keystore data\SSL\cert\ aftkeystore.pfx aftkeystore.bcfks

FTS keystore (SSL) data\SSL\cert\ ftskeystore.pfx ftskeystore.bcfks

Configuring Control-M in the aft_configurable.properties file

This procedure describes how to configure Control-M in the aft_configurable.properties file.

 To configure Control-M:
1. Navigate to one of the following directories:
• UNIX: ~/ctm/cm/AFT/data
• Windows: Control-M Agent\Default\CM\AFT\data
2. Open the aft_configurable.properties file.
3. Edit the parameters as required, as described in aft_configurable.properties file parameters (on page
447).

aft_configurable.properties file parameters

The following table describes some of the aft_configurable.properties file parameters:

447
Control-M Administrator Guide

NOTE: You can access the aft_configurable.properties file in ~/ctm/cm/AFT/data (UNIX) or

Control-M Agent\Default\CM\AFT\data (Windows).

Parameter Description

com.bmc.aft.configurable.ftp.disabl (UNIX Only) Enables a password for a specified user for the
eUnixPass local host in the Connection Profile. Values:
 true: Disables the password for the specified user
 false: Enables the password for the specified user
Default: false
NOTE: After setting the parameter, you can use any dummy
password for local accounts and bypass password maintenance
for local accounts for UNIX machines. The Agent must run in
Root mode.

com.bmc.aft.configurable.ftp.failOn The job fails when Control-M for AFT or Control-M MFT fails to
DestCloseDataChannel close the data channel after the transfer completes. Values:
 true: Enables the job to fail when the data channel fails to
close after the transfer completes
 false: The job does not fail when the data channel fails to
close after the transfer completes
Default: false

com.bmc.aft.configurable.disableFil Enables you to set authorizations to perform actions such as

eSystemRequests mkdir, rename, and delete from the AFT remote browser
dialog.
Values:
 true: Disables authorizations
 false: Enable authorizations
Default: false

com.bmc.aft.configurable.disablePre (Control-M MFT only) Enables you to avoid printing pre/post

PostCommandOutput commands in the job output. Values:
 true: Avoids printing pre/post commands in the output
 false: Prints pre-/post commands in the output
Default: false

448
Control-M Administrator Guide

Parameter Description

com.bmc.aft.configurable.ffdc.enabl (Control-M MFT only) Enables FFDC (First Failure Data Capture)
e mechanism for AFT
Values:
 true: Enables FFDC mechanism
 false: Disables FFDC mechanism
Default: true

com.bmc.aft.configurable.ccm.static (Control-M MFT only) Sets the interval time when the file
.check.interval watcher checks if the file is static. This parameter is also used
when the Transfer all matching files checkbox is checked in
the Control-M client.
Default: 2 (seconds)
Values: 1-999

com.bmc.aft.configurable.maxConc Determines the maximum number of concurrent running jobs.

urrentJobs
Default: 300
NOTE: If you want to raise the default value, be aware that it
might consume more resources and module performance.

com.bmc.aft.configurable.ccm.pgp. Determines whether to automatically add or remove extensions

handle.extension to a file that is encrypted/decrypted using PGP template.
Default: false
NOTE: The extension is added when files are copied to a
directory. If a specific target file name is specified, the
destination file name does not change.

com.bmc.aft.configurable.ccm.pgp.f Determines which extension is added or removed to or from

ile.extension files that are encrypted/decrypted when
com.bmc.aft.configurable.ccm.pgp.handle.extension is
set to true.
Default: .pgp

com.bmc.cm.aft.client.filecopy.mine Determines the minimum number of milliseconds for File

ventlimit Transfer updates sent to Control-M/EM.
Default: 2000
By default, an event is sent on every progress value change,
but not more than one In Progress event is sent per file every
2 seconds.

449
Control-M Administrator Guide

Parameter Description

com.bmc.cm.aft.client.filecopy.max Determines the maximum number of milliseconds for File

eventlimit Transfer updates sent to Control-M/EM.
Default: 20000
By default, an event is sent on every progress value change,
but since large files progress may take time to change, an
event is sent every 20 seconds even if progress wasn’t
changed. For example, from 42% to 43%.

com.bmc.aft.configurable.ftp.buffer Determines the buffer size for every chunk sent during a file
Size transfer.
Default: 32768

com.bmc.aft.configurable.createEve Determines whether a failed file transfer record must be added

ntOnFileWatcherFailedWhenTransfe to the MFT Search view and dashboard in case of File Watcher
rExist failure. For example, if a file was not found.
Default: false

com.bmc.aft.configurable.printTrans Determines whether to print transfer definition details to the

ferDefinitions job output. This can be valuable if you use variables in job
definitions and want to see the resolved values (watch pattern
includes an Auto-Edit variable).
Default: false

com.bmc.aft.configurable.renameD Renames the <prefix><filename> to the target file name in a

estOnPrefix rename post action. If false, the prefix is removed and then
<file> is renamed to the target file name.
Default: true

com.bmc.aft.configurable.actions.ov Determines whether to overwrite an existing target name in a

erwriteIfExists rename post action. When set to false, the rename operation
fails with a message that the file already exists.
Default: true

com.bmc.aft.configurable.actions.m Determines whether to move a file under the target directory

oveToDirectoryIfExists (even if trailing slash wasn’t specified), When set to false, it
treats the target name as a file (when trailing slash is not
specified).
Default: false

450
Control-M Administrator Guide

Parameter Description

com.bmc.aft.configurable.file.filterR Determines whether to support filtering by regular expression.

egex When set to true, the source file name is treated as a regular
expression.
Default: false
NOTE:
 Wildcards (“*” and “?”) are still supported (use them
instead of “.*” and “.”)
 Wildcards must be specified in a file pattern for the feature
to work (e.g.: [Ff][Ii][Ll][Ee]*.txt)

com.bmc.aft.configurable.performR Determines whether to perform a rename on source or

enameActionWhenOptFieldIsMissing destination file even when the option is Left as is. but there is
AndNewNameFieldExist a new file name specified in the job definition. These jobs can
be created by users using an old Control-M/EM Desktop version
(7.0.00 or before).
Default: false

com.bmc.aft.configurable.sftp.prepe Determines where to prepend preceding slash to source or

ndPrecedingSlashToPathWhenMissi destination path when it is missing (SFTP Connection Profiles
ng only).
Default: false

com.bmc.aft.configurable.linux.impe Determines whether to do full impersonation on Linux when

rsonation.enabled the Control-M/Agent is running as root. When value is false
(default), the container, which runs as root, still checks file
permissions for every transfer and sets the owner according to
the Connection Profile user. The transfer itself is done as root.
Default: false

com.bmc.aft.configurable.performPr Determines whether to execute the pre-command when

eCommandAfterFileWatcherActionS defining File Watcher job with Pre-Command, after the file
ucceeded watcher operation (if watch operation succeeded).
Default: false

com.bmc.aft.configurable.ftp.os220 Determine whether to change the working directory to the

0.retrieveFromSourceDir source directory before opening the file to read from (on
OS2200).
Default: true

com.bmc.aft.configurable.ignoreFile Determines whether to ignore files containing a control

sControlCharacter character in the name.
Default: false

451
Control-M Administrator Guide

Parameter Description

com.bmc.aft.configurable.security.ft Determines whether to ignore checking algorithm constraints.

p.checkAlgorithmConstraints When set to true, Control-M MFT doesn't fail connections for
deprecated signature algorithm used for certificates. (MD2
algorithm, or a server that uses key size with length lower than
1024).
Default: false

com.bmc.aft.configurable.publish.do Determines whether to store File Transfer updates in Control-M

NotStoreEvents MFT database (Updates don't appear in Dashboard or Search
view).
NOTE: If set to true, new file transfer records do not appear in
the MFT Dashboard and search results.
Default: false

com.bmc.aft.configurable.publish.do Determines whether to publish File Transfer updates to

NotPublishEvents Control-M/EM (Updates don't appear in Dashboard or Search
view).
NOTE: If set to true, new file transfer records do not appear in
the MFT Dashboard and search results.
Default: false

com.bmc.aft.configurable.sftp.allow. Determines whether to ignore failing authentications while

authentication.failure.on.host.autho authorizing an SSH host, and proceed with storing the host key
rization in the known_hosts file.
Default: false

com.bmc.aft.configurable.sftp.NewL Defines this server to hold files with <CR><LF> at the end of
ine.CRLF.Servers= line.

com.bmc.aft.configurable.sftp.NewL Defines this server to hold files with <LF> at the end of line.
ine.LF.Servers=

com.bmc.aft.configurable.local.trans Determines whether the file is in use before a transfer. Files

fer.files.in.use that are in use are skipped.
Default: false

com.bmc.aft.configurable.verify.file. Determines whether to verify if the file size has changed since
size.has.not.changed.before.transfe the file(s) were marked for transfer.
r
Default: false

452
Control-M Administrator Guide

Parameter Description

com.bmc.aft.configurable.file.strea Determines the number of retries to perform when file streams

m.operations.number.of.retries fails to open or close.
Default: 0

com.bmc.aft.configurable.file.strea Determines the number of seconds to wait before each retry.

m.operations.time.between.retries.i
Default: 0
n.seconds

com.bmc.aft.configurable.destName Determines whether the destination file uses the symbolic link
UseSymbolicLinkName name.
Default: true

com.bmc.aft.configurable.ftp.remot Determines whether to enable server verification of an FTP

eVerificationControlVsDataEnabled server that is defined with a virtual IP.
Default: true

453
14
14
Control-M diagnostics
Control-M diagnostics enables you to gather diagnostic information to identify and fix a problem that
occurs in one or more of the Control-M components. For each Control-M component, you can define the
debug levels and generate diagnostics data.
There are several diagnostic mechanisms you can use to gather diagnostic information, such as:
 Debug levels (on page 454)
 Communication Traces: creates either a log or trace file that contains detailed data communication
between Control-M/Server and Control-M/Agent. For more information, see Defining the
Control-M/Agent debug level (on page 455).
 Exception alerts: alerts you to system failures and enables you to handle them as necessary. For more
information, see Managing exception alerts (on page 324).
The following procedures describe how to define debug levels and generate diagnostic data for each
Control-M component:
 Defining the Control-M/EM debug level (on page 455)
 Defining the Control-M/Server debug level (on page 455)
 Defining the Control-M/Agent debug level (on page 455)
 Generating diagnostic data (on page 458)
NOTE: You can also generate diagnostic data by running the Health Check Utility. For more
information, see Health Check utility in Utilities.

Debug levels
Debug levels determine which information you want to view in the logs. Debug levels range according to
each Control-M component. For example, if you set a debug level to 4, you are able to view all levels of
information. The higher the level set, the more details are displayed in the logs. However, the higher the
level set, the more system resources are required. This can result in an environment functioning slower
than usual.
The following procedures describe how to define the debug levels for Control-M/EM, Control-M/Server,
and Control-M/Agent:
 Defining the Control-M/EM debug level (on page 455)
 Defining the Control-M/Server debug level (on page 455)
 Defining the Control-M/Agent debug level (on page 455)
 Defining the Workload Archiving debug level (on page 456)
 Setting the debug level by scenario (on page 456)

454
Control-M Administrator Guide

Defining the Control-M/EM debug level

This procedure describes how to define the Control-M/EM debug levels, which enables you to adjust
debug levels to view in the log.
 To define the Control-M/EM debug level:
1. From the CCM component list, select the Control-M/EM component.
2. Click Control Shell.
The Control Shell window appears.
3. In the Specify a control shell command line field, type one of the following commands:
• DIAGON: Starts the DIAG functionality
• DIAGOFF: Stops the DIAG functionality
• DIAGL: Sets the debug level. For more information, see Debug levels (on page 454).
4. In the Result section, set the following usage for DIAGL:
• Context: Defines which context to set the debug level on. The context suggestions are listed in
the Result section.
• Level: Sets the debug level.
The debug levels for the Control-M/EM component are set.

Defining the Control-M/Server debug level

This procedure describes how to define the Control-M/Server debug level, which enables you to adjust
debug levels to view in the log.
 To define the Control-M/Server debug level:
1. From CCM components' list, select the Control-M/Server component.
2. Right-click on the component and select Control-M/Server Debug.
The Control-M/Server Debug window appears.
3. From the Debug Level drop-down list, select the debug level for each process.
Valid values range from 0 to 5, where 0 indicates no diagnostic activity, and 5 indicates the highest
level of diagnostic functionality.
4. Click OK.
The debug levels for the Control-M/Server are set.

Defining the Control-M/Agent debug level

This procedure describes how to define the Control-M/Agent debug level, which enables you to adjust
debug levels to view in the log.
 To define the Control-M/Agent debug level:
1. From the CCM component list, select the Control-M/Agent component.

455
Control-M Administrator Guide

2. Right-click on the component and select Agent Debug.

The Control-M/Agent Debug window appears.
3. From the Control-M/Server drop-down list, select the required Control-M/Server.
4. From the Control-M/Agent drop-down list, select the required Control-M/Agent.
5. From the Diagnostic Level drop-down list, select the debug level.
Valid values range from 0 to 4, where 0 indicates no diagnostic activity, and 4 indicates the highest
level of diagnostic functionality.
6. From the Communication Trace drop-down list, select the debug level.
Valid values range from 0 to 1, where 0 indicates no communication trace, and 1 activates the
communication trace.
7. Click OK.
The debug levels for Control-M/Agent are set.

Defining the Workload Archiving debug level

This procedure describes how to define the Workload Archiving debug level.

 To define the Workload Archiving debug level:

1. Type the following command:
arc_dbg_lvl
2. Type the following:
-level <x>
Where x is the a number 1(low)-5(high).

Setting the debug level by scenario

This procedure describes how to set debug levels by a particular scenario. It enables you to collect
diagnostic data particular to that problem by processing the relevant Control-M components where the
problem resides and communicate that information to BMC customer support.
 To set a debug level by scenario:
1. From the CCM, select Tools>Debug>Set Debug Level By Scenario.
The Debug Scenario Wizard appears.
2. From the Scenario drop-down list, select that scenario that represents the problem you have.
3. Select the Control-M component/s where the problem resides (The list is populated dynamically
according to the scenario you have selected in the previous step) and then click Next and then click
OK.
A confirmation message appears. The debug level process starts.
4. Recreate the problem on the remote host where the problem occurred, after the debug level
processing is completed successfully.

456
Control-M Administrator Guide

5. In the wizard, select the Scenario recreated checkbox to confirm that you have recreated the
problem on the machine where the problem occurred.
6. Select the Reset Debug Level checkbox.
If you select this checkbox, all debug levels are reset to 0. If you choose not to reset debug levels to
0, you can reset the debug levels manually to the levels you want. For more information, see Debug
levels (on page 454).
7. Click Next and then click OK.
8. Select one or both of the following:
• Collect usage measurements reports
• Collect product logs and configuration
9. In the Last days field, define the number of days in the past to include data in the report.
10. From the Save Method drop-down list, select one of the following and then click Next:
• Common location: Enables you to save the collected output files of all relevant components to
either a default location at the component directory or a shared network location. Take note that
if you select this option, all relevant Control-M components must have one platform, either
Windows or UNIX.
• Custom location:Enables you to save the collected files and save them per component to either
a default location at the component directory or a shared network location.
NOTE: If you are working with more than one platform, the files are automatically saved to the
default location at the component directory. Copy the files to a shared network location, and
specify the shared network location path.
The diagnostic data is being collected.
11. Collect the generated files from the output directories provided in the dialog box, and upload them to
the BMC FTP site ftp://ftp.bmc.com/incoming/ ftp://ftp.bmc.com/incoming/ and then click Finish.

Defining Web Server log levels

This procedure describes how to define Web Server log levels for Control-M Web, Client Deploy, and Data
Collection (internal component collecting data for logging and support) without restarting the Web Server.
 To define the Web Server log levels:
 Do one of the following:
• To define Web Server log levels from the CCM, do the following:
a. From the Control-M Web service component, right-click and select Control Shell.
The Control Shell dialog box appears.
b. Type the following control shell command line:
diagl -l=<log_level>
o Error: (Default) Writes to the log file on the disk only when there is an issue with data
consistency, network connectivity, or expected received data structure.

457
Control-M Administrator Guide

o Warning: Writes to the log file all Error level messages and some uncommon behavior that
might indicate problems.
o Info: Writes both error and warning messages and messages that might explain a complete
flow or an alert of requests to a server and their type.
o Debug: Includes Error, Warning,and Info messages and important information that might
occur during every procedure.
NOTE: Info and Debug are used only during problem analysis, as they both consume high
disk space resources.
• To define Web Server log levels from the services-cli utility, type the following command:
services-cli -s controlm-web -i "all" -c diagl -level <log_level>
The following message appears:
Root log level is changed successfully to <log_level>

Generating diagnostic data

This procedure describe how to generate diagnostic data for Control-M/EM, Control-M/ Agent, and
Control-M/Server, such as usage measurement reports and product logs and configuration. This enables
you to identify and troubleshoot problems or areas of inefficiency in the Control-M production
environment and communicate that information to BMC customer support.
 To generate diagnostic data:
1. From the CCM component list, select a component.
2. Right-click on the component and select Diagnostics Data.
The Diagnostics Data Collection window appears.
3. Select one or both of the following:
• Collect usage measurements reports
• Collect product logs and configuration
4. In the Last days field, define the number of days in the past to include data in the report.
5. Click Advanced.
6. In the Save to section, select one of the following:
• Save to Default location at the component directory
• Save to a shared network location
7. In the Command Line Parameters field, type of the commands as described in Running Health Check
utility from the command line.
8. Click OK.
The Action Result dialog box appears.
9. Monitor the status of the request until the diagnostic data collection completes.
If the diagnostic data collection returns with the following error, see Troubleshooting diagnostic data
collection failure (on page 459).

458
Control-M Administrator Guide

Data collection failed. ERROR: No available disk space, <SIZE_IN_MB> needed, exiting...

Troubleshooting diagnostic data collection failure

This procedure describes how to troubleshoot diagnostics data collection failure due to no available disk
space.
 To troubleshoot diagnostic data collection failure:
1. From the Diagnostic Data Collection window, click Advanced.
2. In the Command Line Parameters field, add the following string:
-max_size=<NEW_SIZE_IN_MB>
The value of <NEW_SIZE_IN_MB> is calculated as follows:
• Check the available space under ctm_em location.
• Define a new value that is less than the available disk space divided by 3.
3. Click OK.
The data is regenerated.

Sending commands to Control-M/EM server components

This procedure describes how to send a direct command to one of the EM servers components from the
CCM, which is mostly used for diagnostic or configuration purposes.
 To send commands to Control-M/EM server components:
1. From the CCM component list, select the Control-M/EM component.
2. Right-click on the component and select Control Shell.
The Control Shell window appears.
NOTE: If you are sending a shell command to a Control-M for z/OS, the information that appears and
the commands that you specify apply to the Global monitor.
3. Do one of the following:
• In the Specify a control shell command line field, type the command.
• To display the list of valid commands and requests for the selected component, click Usage and
select one of the commands that appear in the Result section.
4. Click Apply.

Monitoring the Control-M/EM Configuration Agents Log

This procedure describes how to monitor the Control-M/EM Configuration Agents log. The log lists the
events and monitoring actions that the Configuration Agent performs on all Control-M/EM components,
such as starting up and shutting down components and checking database connections.

459
Control-M Administrator Guide

 To monitor the Control-M/EM Configuration Agent:

 From the Diagnostics tab, click EM Configuration Agents Log.
The EM Configuration Agents Log appears.

Usage Reporting Tool

The Control-M Usage Reporting Tool measures peak usage across all of your Control-M environments for
license auditing and compliance purposes. The Usage Reporting Tool provides a wizard-based interface to
assist you with generating usage reports showing your aggregated peak usage over the last year. The
tool displays task usage, installed optional components such as the BMC Batch Impact Manager and
Control-M Self Service add-ons, Control-M for Advanced File Transfer application plug-in, and Endpoint
data.
If you want to connect the Usage Tool to Oracle RAC, see 000075660
https://bmcsites.force.com/casemgmt/sc_KnowledgeArticle?sfdcid=000075660.
The Usage Tool counts tasks, which are based on the total number of jobs present in the Control–M
Active Jobs databases within any 24-hour period, but does not apply to users whose license is based on
other units of measurement, such as MIPS, CPU, or tiers. Tasks in the Control-M Active Jobs database
refer to all Control-M tasks that are monitored by Control-M across all of your Distributed Systems or
Mainframe environments, which includes development, staging, QA, pre-production, test, and production
environments.
Tasks are counted according to the following rules:
 Regardless of whether they execute or not.
 A single task that executes more than one script is counted as one task.
 A task that runs more than once during the day (with the same Order ID) is counted as one task,
which includes cyclic and tasks that are re-run.
 Tasks that have time zone settings may remain in the Active Jobs databases for up to three
consecutive days, but are only counted once as a single task.
 Jobs that are ordered to run on a future date are counted every day the job resides in the Active Jobs
database.
 SMART folders and sub-folders, which contain scheduling definitions, and are listed as tasks in the
Active Jobs database, are not counted as tasks.

Generating a usage report

This procedure describes how to generate a usage report, which measures peak usage across all
Control-M environments.

460
Control-M Administrator Guide

 To generate a usage report:

1. From the Start menu, select All Programs > BMC Control-M 9.0.20> Usage Utility (Run as
Administrator).
The Control-M Usage Reporting Tool appears.
2. Review the Reporting Tool Wizard information and click Next.
3. From the dropdown list, select the Control-M type, add the Control-M/EM environments as necessary,
and click Next.
NOTE: To check the database name, from the CCM, in the Components Tree pane, under the
Control-M/EM component, right-click Database and then click Properties.
The Control-M Usage Reporting Tool reviews the connection status.
4. Click Next.
The full set of reports appears.
NOTE: The Reports are automatically saved in <Control-M/EM home>\default\usagetool\reports.
Each time you run the tool, a new sub-folder is created, and the new set of reports is placed in the
Reports folder.
5. If you want to send the report by email click Send Report.
NOTE: By default, the Report is sent by email, emworkloadautomation@bmc.com. If you want to
change the email go to <Control-M/EM home>\default\usagetool\data, open the config.ini file, and
change the UsageAlertEmail parameter.
6. If you want to save the report to a different location, click Save Report.
7. To close the Reporting Tool, click Finish.

Configuring persistent source level debugging diagnostics

This procedure describes how to configure the source level debugging diagnostics in the initialization file
per component.
 To configure source level debugging diagnostics:
1. Navigate to the following location:
<Control-M/EM_home>/ini/<component_name> DiagLvls.ini.
2. Configure the parameters as required, as described in Persistent diagnostic record file parameters (on
page 462).
3. Save the file.

461
Control-M Administrator Guide

Persistent diagnostic record file parameters

The following table describes Persistent diagnostic record file parameters in the .ini file.

Parameter Description

IsCyclic Indicates whether the file is cyclic. Optional.

Valid values:
 0 (non-cyclic)
 1 (cyclic)
Default: 0

NumOfFiles Determines the maximum number of cyclic files to create.

Mandatory only if IsCyclic = 1.

NumOfMessages Determines the maximum messages in each cyclical file.

Mandatory only if IsCyclic = 1.

*default Determines the debug level of the DIAG debug trace for the
component.
Valid values: 0 (minimum messages) -7 (all messages).
Default: 0.

<filename> debug_level Defines the debug level with the syntax: filename debug_level
NOTE: The filename is supplied by BMC Software Customer
Support.
EXAMPLE: gas_srv 5

MinimumDbgLvl Determines the message levels for messages sent to the log file
and the memory buffer.
Valid values:0 (no messages) - 7 (all messages)
Default: 0
EXAMPLE: MinimumDbgLvl 4 7 will set level 4 for the log file and
7 for the memory buffer.

MemBufferSize Determines the buffer size in kilobytes.

Valid values: 20 - 1000
The ctl utility can change the buffer size for the GUI Server during
run time.

462
Control-M Administrator Guide

Parameter Description

IsBufer Determines whether the memory buffer is used or disabled.

Valid values:
 0: Memory buffer is disabled
 1: Memory buffer is used
Default: 0

IsPIDUsed Determines if the DIAG file name contains a Process ID (PID).

Valid values:
 0: PID is not included in the file name
 1: PID is included in the file name
Default: 0

PrintLevelMaps Determines whether the list of DIAG levels for the process or
component must be printed.
Valid values:
 0: Printed
 1: Not printed
Default: 0

FlushBufferSize Determines the number of bytes the buffer holds before DIAG
messages are automatically written to file.
Default: 0: Causes each DIAG message to be flushed
immediately.

DiagStacksOn Determines whether the on and off toggle switch that controls
whether an application stack trace is accumulated.
Valid values:
 0: (off)
 1: (on)

"Context” @<context_name> <debug level>

EXAMPLE: @20 2
NOTE: Do not modify.

IgnoreMinimum Default: 0

463
Control-M Administrator Guide

Parameter Description

ApplyCleanup Enables the clean up of old log files.

Default: 0

RetainDays Determines the number of days a log file must exist before
automatic deletion according to the last modified date.
Default: 3

Enable Enables diagnostic functionality (on/off).

NOTE: Equivalent to the dynamic settings DIAGON and DIAGOFF.
Default: 1

464
Control-M Administrator Guide

Troubleshooting scenarios
The following table describes Control-M/EM troubleshooting scenarios and corrective actions when there
are communication problems between Control-M/EM and Control-M/Server.

Scenario Description Action/Control Shell

Control-M Configuration Agent  Ensure that the

Not Available configuration specifications
of the host name and
Configuration Agent port
number are identical in both
the specific Control-M
iteration, and in the
Control-M/EM server.
 Check that the Configuration
Agent is up and running.
 Run netstat -na to check the
status of the Configuration
Agent port.

The Gateway is running but is Communication status is down  TRACE_LINK_CTM

not synchronized with in the CCM.
Control-M/Server  TRACE_CTM

Gateway is stuck downloading There are constant downloading,  TRACE_LINK_CTM

download failed error messages
that repeat cyclically.

Gateway bounces The Gateway status changes Type -dbg 3 in the Additional
from Up to Down and back Parameters field in the
again, frequently Gateway component.
NOTE: Due to the apparent
instability of the Gateway, you
cannot use the Control Shell
functionality.

465
Control-M Administrator Guide

Scenario Description Action/Control Shell

User actions take an unusually This causes a timeout to occur.  TRACE_LINK_CTM

long time Such actions can include issues
as not seeing updates after a  TRACE_CLIENT
certain action has been
performed, or an upload (or
download) not succeeding or
taking longer than usual.

The GUI Server does not come  Possibility 1: The  Possibility 1: Start the
up. Control-M/EM Configuration Configuration Agent.
Agent fails to respond.
 Possibility 2: If the
 Possibility 2: The database is down, bring it
Database is not responding. up.
 Possibility 3: The  Possibility 3: Change the
Control-M/EM Configuration Desired State to Ignore and
Agent is available but has then to Up.
exceeded its retry limit for
this component.
 Possibility 4: Change the
Desired State of the Web
 Possibility 4: The Web Server to Up and use a web
Server is unavailable or not browser to try to connect to
responding URL defined in the Web
Server URLs in the CCM.

User cannot log in  Possibility 1: The Web  Possibility 1: Change the

Server is unavailable or not Desired State of the Web
responding. Server to Up and use a web
browser to try to connect to
 Possibility 2: The GUI
URL defined in the Web
Server is down.
Server URLs in the CCM.
 Possibility 3: The database
 Possibility 2: Start up the
server is down.
GUI server.
 Possibility 3: Check the
GUI Server log for the most
recent instance of the
wording vendorMessage,
and for any messages
displayed immediately after
an equals symbol (=).
Contact your Database
Administrator with this
information.

466
Control-M Administrator Guide

Scenario Description Action/Control Shell

Global Condition Server issues Use this file to determine  Check the GCS_LOG file
whether this is a single or
multiple condition issue, as  GCS_DIAG.
described in GCS condition
issues (on page 467).

GCS condition issues

The following table describes issues that can happen with conditions that can cause GCS problems.

Scenario Description

Toggling conditions If the word TOGGLED is displayed in the GCS_LOG file in relation
to the global condition is question, it means that the issue has
arisen as a result of toggling behavior, which in turn might
indicate that there is a problem.
Contact BMC Customer Support with this information.

Incorrectly defined conditions  Check to see if the condition was received from the source,
but not sent to the target.
 Check to see if the expected condition is absent completely
from the file.

Heavy condition distribution If there is an unusual flow of messages in the GCS_LOG file; for
activity example, a non-systematic flow with large numbers of timestamps
that are very close together in chronology, or a large number of
messages with the word REJECTED included, or evidence that the
same conditions were sent over and over again.
This might indicate that specific conditions are affected, or that all
conditions are affected.

Communication problems If conditions do not appear (as either Received or Sent) in the
between the Global Conditions GCS_LOG file (no lines for the conditions are showing up in the
Server and the Gateway file), or lines of conditions repeat themselves without a successful
report, or no line contains the word CONFIRMED.

Problematic conditions clean-up This typically happens near the time when the New Day is
policy scheduled to start, and is indicated by a sequence of large
numbers of conditions (possibly with old dates assigned to them).

467
15
15
Database operation and maintenance
A Control-M/Server database contains the job processing definitions (organized by tables). In addition to
the Definitions file, the Control-M/Server database also maintains Active Jobs, a Resources table and a
Conditions table.
A Control-M/EM database enables you to control your entire batch production enterprise. The Definition
file of the Control-M/EM database contains a copy of all job processing definitions from all of your
Control-M/Server databases. This database also includes the Active Jobs Database.
You can back up and restore your data from a Control-M/EM or Control-M/Server database, as described
in Database backup and restore (on page 471).
You can perform periodic maintenance procedures on a Control-M/EM and Control-M/Server database, as
described in Database maintenance and cleanup (on page 478).
To maintain Control-M/EM databases:
 Use the interactive Database Maintenance menu, which you access from the Root menu.
 Run the util utility from the command line .
 To maintain Control-M/Server databases, use the Database Maintenance menu that you access from
the Control-M Main Menu.

Accessing the Control-M/EM database maintenance menu

This procedure describes how to access the Control-M/EM database menu, which enables you export,
import, and perform other database procedures.
 To access the Control-M/EM database maintenance menu:
1. Log in to the Control-M/EM host computer.
2. Type root_menu command.
3. When prompted, enter the Control-M/EM Database Owner (DBO) user name and password.
The Control-M/EM Root Menu appears.
4. From Control-M/EM Root Menu, type the number for Database Maintenance. (on page 469)
The Database Maintenance Menu appears.

468
Control-M Administrator Guide

Control-M/EM Database Maintenance menu options

The following table describes the options in the Database Maintenance Menu for Control-M/EM.

Menu option Description

Export Database Extracts the contents of the Control-M/EM database to a compressed

flat file or tape.

Import Database Restores the Control-M/EM database from a file or tape created using
the Export Database option.
Stop all Control-M/EM components before performing this operation.

Custom Displays the Export/Import Default Parameters menu that

Export/Import enables you to customize the parameters used for the Export
Database and Import Database options.
Stop all Control-M/EM components before performing this operation.

Extend Enlarges the data portion of the Control-M/EM database. Depending on

Database Size the type of database server installed, this option runs the
db_extend_oracle utility. When the utility runs, you may be prompted
for the following data:
 Password for the sa or SYSTEM user.
 Oracle: Name of the existing device you want to extend.
 Size in MB of the additional space to allocate.
 Full path for the device.
 Size (in MB) to which you want to extend the device.

Erase Old Nets Erases an old network.

Erase Audit Data Erases audit records that were stored in the database.

Erase Exception Erases exception alerts that were stored in the Control-M/EM database.
Alerts

DBUMonitor
The DBUMonitor is a monitoring tool that is part of the Watchdog functionality that monitors the
Control-M/Server dedicated PostgreSQL database. It identifies database issues and suggests a correct
solution when the problem occurs.
The DBUMonitor can find the following error types:

469
Control-M Administrator Guide

 Database corruptions
 Application SQL Errors (Control-M/EM, Control-M/Server, Workload Archiving)
 Database backups are not performed regularly
When errors are found in the logs, an xAlert is sent. To change the default DBUMonitor configuration, see
Configuring the DBUMonitor (on page 470).

Configuring the DBUMonitor

This procedure describes how to configure the DBUMonitor After installation, the DBUMonitor is active by
default. This procedure describes how to change the default parameters.
 To configure the DBUMonitor:
1. Navigate to one of the following directories:
• UNIX: <ctm_server_home>/data/DBUMonitor.dat
• Windows: <ctm_server_home>\data\DBUMonitor.dat
2. Change the parameter values as required, as described in DBUMonitor parameters (on page 470).
3. Save the file.

DBUMonitor parameters
The following table describes DBUMonitor parameters.

Parameter Description

ACTIVE Determines whether the DBUMonitor is enabled

MONITOR_BACKUP Determines whether to monitor the PostgreSQL database backups

MONITOR_BACKUP_WORKING_ Determines whether to monitor the PostgreSQL database backups

HOURS_ONLY during working hours only

MONITOR_PG Determines whether to monitor the PostgreSQL database log files

MONITOR_PG_WORKING_HOUR Determines whether to monitor the PostgreSQL database log files

S_ONLY during working hours only

TRACE Determines whether to include the Trace log in the xAlert

WORKING_HOURS Determines which hours are defined as working hours

KEEP_FILES_DAYS Determines how many day to keep log and temp files before they
are automatically removed.

470
Control-M Administrator Guide

Database backup and restore

You can back up and restore your data from a Control-M/EM or Control-M/Server database with the
following backup and restore options:
 Hot backup: Tracks changes to the database while Control-M/Server is active. After a crash (or other
event), you can restore the database to the previous state before the crash. Hot backups are
performed in archive mode, which requires extra disk space for control files. You must specify an
existing directory when implementing hot backups (Dedicated PostgresSQL only).
 Cold backup: Copies the contents of the database to a file when Control-M/Server is shut down. The
database can be restored up to the date/time of the last backup. You can use cold backups to restore
the database to the state it was in when the backup was performed. To perform a cold backup,
archive mode must be disabled. You can run the ctm_backup_bcp utility even when the database is in
archive mode. Shut down Control-M/Server before performing a cold backup (Existing Oracle and
dedicated PostgresSQL only).
 Archive mode: Control-M/Server backs up the logs before overwriting them with new information. If
the database subsequently crashes, you can use the archived logs to restore the database up until the
most recent SQL transaction. If you enable archive mode, you should plan to keep it enabled for long
term use. If you enable and disabled it frequently, the archived log files do not provide useful
information for database restoration. You can only use Archive Mode option when Control-M is
running with the database server supplied with the Control-M installation. The Control-M/Server
automatically shuts down during this procedure. If archive mode is enabled, database transactions
might perform slowly, and archive files require more disk space (Dedicated PostgresSQL only).
 Restore and rebuild: Restores data from a correct database structure. If the Control-M/Server
database structure (schema) becomes corrupt, you must rebuild the database. After the rebuild, you
must restore the data. When a cold restore is performed, the restore file must be exported from the
database with the same encoding as the destination database. If you rebuild the database with UTF8
encoding, you must manually configure the environment settings, to enable the Control-M/Server
components to support this encoding.
NOTE: Before rebuilding the database running the Build DB option through ctm_menu, when using an
existing PostgreSQL database, first kill all transactions and then run Build DB. To find out which
transactions are still open, you can refer to the Transactions Report that is generated by running the List
All Active Transactions option using ctm_menu.

Control-M/Server database backup and restore

The following procedures describe how to back up and restore a Control-M/Server database:
 Enabling archiving of a Control-M/Server database (Oracle and PostgreSQL only) (on page 472)
 Backing up a Control-M/Server MSSQL database (on page 472)
 Restoring a Control-M/Server MSSQL database from a backup (on page 474)
 Rebuilding a Control-M/Server database (on page 476)

471
Control-M Administrator Guide

Enabling archiving of a Control-M/Server database (Oracle and PostgreSQL

only)
This procedure describes how to archive database log files when they become full.
NOTE: If a database crash occurs, you can use the archived files to restore the database up until the
most recent SQL transaction. Hot backups require that archive mode be enabled, but the backup
procedure automatically sets archive mode if it was not previously set. For more information about hot
backups, see Database backup and restore (on page 471).
 To enable archiving of a Control-M/Server database:
1. Display the Control-M Main Menu by typing the ctm_menu command.
2. In the Control-M Main menu, enter the number for the Database Menu option.
The Database Utilities Menu appears.
3. In the Database Utilities Menu, enter the number for the Management option.
The Management Menu appears.
4. In the Management Menu, enter the number for Set Database Archive Mode option.
5. At the prompt for the mode, type ON.
6. At the prompt for the destination directory, enter the name of the destination for archived log files.
7. When you are done, enter q to quit.

Backing up a Control-M/Server MSSQL database

This procedure describes how to back up a Control-M/Serer MSSQL database onto a backup device. BMC
recommends that you back up your Control-M/Server databases onto backup devices daily. You can
complete this procedure while the database is running.
NOTE: Performing this procedure has the same effect as running the ctmdbbck utility.
 To back up a Control-M/Server MSSQL database:
1. Display the Control-M Main Menu by typing the ctm_menu command.
2. In the Control-M Main Menu, enter the number for the Database Maintenance option.
3. In the Database Maintenance menu, enter the number for the List Backup Devices option, and
write down the name of the device that you want to use.
When backing up an MSSQL database, the full path is a path on the database server computer.
4. Return to the Database Maintenance menu, and enter the number of the Backup Database
option.
5. Enter the name of the backup device you wrote down in step 3.
The backup device must be either a valid device defined in the SQL database, or the full path name of
a file to be created by the backup procedure.
6. Respond to the subsequent prompts that are displayed.
7. When you are done, enter q to quit.

472
Control-M Administrator Guide

The Control-M/Server database is backed up onto a backup device.

Backing up a Control-M/Server Oracle or PostgreSQL database

This procedure describes how to back up a Control-M/Serer Oracle or PostgreSQL database onto a backup
device. BMC recommends that you back up your Control-M/Server databases onto backup devices daily.
You can complete this procedure while the database is running.
NOTE: Performing this procedure has the same effect as running the ctmdbbck utility.
 To back up a Control-M/Server Oracle or PostgreSQL database:
1. Display the Control-M Main Menu by typing ctm_menu command.
2. In the Control-M Main menu, enter the number for the Maintenance option.
3. In the Maintenance menu, enter the number for the Backup Database option.
Oracle: The following prompt appears:
Enter a destination directory name [<ctm_home_dir>]:
PostgreSQL: The following prompt appears:
Enter a destination file name [<ctm_home_dir>]:
4. Press Enter to accept the default directory, or enter the name of a different directory where you want
the backup to be saved.
The backup procedure assigns its own file name.
• If Archive mode is not active at your site, a cold backup is automatically performed.
• If Archive mode is active, the following prompt is displayed:
Enter your choice for backup mode (Hot or Cold) [H/C]:
5. Select either H for hot backup or C for cold backup, and press Enter.
The following prompt appears:
Specify archiving process destination directory:
6. Enter the directory path and filename in which the archive process will store its control files.
The backup procedure begins. Informational messages report the progress of the backup.
7. When you are done, enter q to quit.
8. If you selected a cold backup in when the backup is complete, start Control-M/Server.

473
Control-M Administrator Guide

Backup device parameters

The following table describes backup device parameters:

Variable Description

<dev_logical_name> Logical name of the device

{disk|tape} Type of device. This device can be either a disk file or a tape drive.
Backups to disk files are faster and do not require operator
intervention.
 If you specify disk, you must specify the file full path name.
 If you specify tape, you must specify the device name.

<file_full_path_name| Full path name (for disk) or a device name (for tape)
device_name>

Restoring a Control-M/Server MSSQL database from a backup

This procedure describes how to restore the Control-M/Server MSSQL database from a database failure or
data corruption.
NOTE: Performing this procedure has the same effect as running the ctmdbrst utility.
 To restore an MSSQL database from a backup device:
1. Display the Control-M Main Menu (ctm_menu).
2. In the Control-M Main menu, enter the number for the Database Maintenance option.
3. In the Database Maintenance menu, enter the number for the Restore Database option.
4. Follow the displayed prompts.
The backup device must be a valid device defined in the database, or the full path name of a backup
file to be used as input for the ctmdbrst utility.
If you do not know the name of the backup device, display the list of backup devices by entering the
number of the List Backup Devices option in the Database Maintenance menu, and then note
the name of the device.
5. Type q to quit.

 To recover from a hot restore failure (for PostgreSQL):

1. Stop any PostgreSQL processes currently running on the computer.
2. Go to the pgsql parent directory. On UNIX for example, this directory is the user ctm_em directory.
3. Check if pgsql_old_<current_date> exists. If so, this means that the restore process renamed the
old (now corrupted) directory.
4. Rename it to pgsql.

474
Control-M Administrator Guide

5. Start the PostgreSQL server.

Restoring a Control-M/Server Oracle or PostgreSQL database from a backup

This procedure describes how to restore the Control-M/Server Oracle or PostgreSQL database are down
as the result of a crash. If this is not the case, the restore procedure fails.
NOTE: Performing this procedure has the same effect as running the ctmdbrst utility.
Before you begin
If you want to perform a restore from a Cold backup and Archive mode is active, deactivate Archive mode
(using option 1 of the Database Maintenance menu) before performing the steps described below.
 To restore a Control-M/Server Oracle or PostgreSQL database from a backup:
1. Shut down Control-M/Server, and verify there are no other users or processes connected to the SQL
Server.
2. Display the Control-M Main Menu by typing ctm_menu command.
3. In the Control-M Main menu, enter the number for the Maintenance option.
4. In the Maintenance menu, enter the number for the Restore Database option.
The following prompt appears:
Enter a destination directory name [<ctm_home_dir>]:
5. Press Enter to accept the default directory, or type the name of the directory in which the backup
was saved.
6. When you are done, enter q to quit.
Control-M performs the restore as follows:
• If Archive mode is not active, a restore is automatically performed using information from the
most recent Cold backup.
• If Archive mode is active, a restore is automatically performed using information from the most
recent Hot backup.
(For PostgreSQL only) - If a hot restore process failed, it is possible to revert back to the file system
as it existed before the restore process began. For details, see the following instructions.
NOTE: The hot restore process uses the ctm_em/pgsql/data/pg_xlog directory to recover the
database up until the point of failure. If this directory was damaged during the failure, the database
can only be recovered up until the last database log switch.

Reverting back to a PostgreSQL database

This procedure describes how to revert back if a hot restore fails for a PostgreSQL database.
NOTE: Performing this procedure has the same effect as running the ctmdbrst utility.

 To revert back to a PostgreSQL database:

1. Stop any PostgreSQL processes currently running on the computer.
2. Go to the pgsql parent directory. On UNIX for example, this directory is the user ctm_em directory.

475
Control-M Administrator Guide

3. Check if pgsql_old_<current_date> exists.

NOTE: If it exists, the restore process renamed the old (now corrupted) directory.
4. Rename it to pgsql.
5. Start the PostgreSQL server.

Rebuilding a Control-M/Server database

This procedure describes how to rebuild a Control-M/Server database if the database structure (schema)
is corrupt. After you rebuild the database, you need to restore the data.

Before you begin

Before rebuilding the database, verify that the following requirements are met:
 Back up the database data (see Backing up a Control-M/Server MSSQL database (on page 472))
 Shut down Control-M/Server and Control-M/Server Configuration Agent
 The SQL database is running
 No Control-M/Server utilities are connected to the SQL Server

 To rebuild a Control-M/Server database:

1. Display the Control-M Main Menu by typing the ctm_menu command.
2. In the Control-M Main menu enter the number for the Database Menu option.
The Database Utilities Menu appears.
3. In the Database Utilities Menu, enter the number for Management.
Management Menu appears.
4. In the Management Menu, enter the number for the Build Database option.
5. Follow the prompts online, and specify or change the parameters as required.
Default values are provided for most of the parameters. Modify them as required.
NOTE: When rebuilding the database, working in an existing mode, the full path names of the log
and data devices must be different from the original path names.
6. In the Main Menu, enter the number of the Database Maintenance option.
7. In the Database Maintenance, enter the number of the Cold Database Restore option to load
the data into the new database.
8. Follow the displayed prompts.
The backup device must be a valid device defined in the database, or the full path name of a backup
file to be used as input for the ctmdbrst utility.
If you do not know the name of the backup device, display the list of backup devices by entering the
number of the List Backup Devices option in the Database Maintenance menu, and then note
the name of the device.
9. When you are done, enter q to quit.

476
Control-M Administrator Guide

Control-M/EM database backup and restore

The following procedures describe how to back up and restore a Control-M/EM database:
 Backing up Control-M/EM data (on page 477)
 Restoring Control-M/EM data (on page 477)
 Backing up audit records (on page 478)
 Restoring audit records (on page 478)
You can use the ctmsec batch utility to export and import Control-M Security Definition tables. The file
that is generated by the ctmsec command is an executable file containing API functions that redefines all
the security entries when the script runs. The generated file can be modified and imported to any
Control-M installation.

Backing up Control-M/EM data

This procedure describes how to back up Control-M/EM data by exporting the data to a file in a defined
location.
 To back up Control-M/EM data:
1. Display the Control-M/EM Root Menu (root_menu).
2. In the Control-M/EM Root Menu, enter the number for the Database Maintenance option.
3. In the Database Maintenance menu, enter the number for the Export Database option.
4. Specify the name of the file to which the database should be exported.
The database is exported to a file you specify. The file is called export_file_name.Z.
5. Enter q to exit the Database Maintenance menu and the Root menu.

Restoring Control-M/EM data

This procedure describes how to restore Control-M/EM data.

 To restore Control-M/EM data:

1. Display the Control-M/EM Root Menu (root_menu).
2. In the Control-M/EM Root Menu, enter the number for the Database Maintenance option.
3. In the Database Maintenance menu, enter the number for the Import Database option.
You are prompted for location of the export_file_name file that was created during the procedure.
Enter the path and name for the export_file_name file. Do not include the .Z extension.When the
procedure is complete, the Database Maintenance menu is displayed.
4. Enter q to exit the Database Maintenance menu and the Root menu.
If you quit the Root menu or its submenus while performing the database restore, you must perform
Rebuilding the database schema following import interruption.

477
Control-M Administrator Guide

Backing up audit records

This procedure describes how to back up audit records.

 To back up audit records:

 Invoke the util utility with -export and -type audit, using the following syntax:
util -U DBO_name -P DBO_password -export -type audit

Restoring audit records

This procedure describes how to restore Control-M/EM audit records. The command described in this
procedure deletes old audit records.
 To restore audit records:
1. To save old audit records, invoke the util utility with -export and -type audit.
2. Invoke the util utility with -import, -replace, and -type audit, using the following syntax:
util -U DBO_name -P DBO_password -import -replace -type audit

Database maintenance and cleanup

Older and unneeded data is normally cleaned (deleted) from the database automatically according to
system parameters that determine (for example) how long to retain records, how many records to retain,
and how often to perform cleanup.
Manual database housekeeping and cleanup is intended for special situations where you might want to
clean out more data than is cleaned out by the automatic clean up. For example, if disk space is low, you
might want to remove a larger than normal portion of a particular type of data.
If you find that you are performing manual cleanups frequently, especially the same type of cleanup each
time, consider adjusting the system parameters so that automatic cleanup matches the required cleanup
pattern.

Control-M/EM database maintenance and cleanup

The database server writes a message to an error log file when the server starts or shuts down, and when
a database error occurs. This file is not automatically truncated. If not manually truncated, the file utilizes
a large amount of disk space. The file created is called an error log for MSSQL, and an alert log for Oracle.
[UNIX only].
Whether responsibility of maintaining the error log file goes to the Control-M administrator or the
database administrator depends on whether your site is using the dedicated database server provided
with the installation, or an existing database server. If you use an existing database server, it is the
responsibility of the database administrator to truncate this file on a regular basis.
Some log files are automatically cleaned (deleted) periodically, depending on system parameter
definitions. Other log files have limits so that older log messages are deleted as newer ones are written in.
The administrator must check the log files to ensure that they are not filling up or too large. If necessary,
the administrator must manually delete them. The MaxOldDays system parameter tells how long to retain
the Gateway log files before the gateway deletes them.

478
Control-M Administrator Guide

NOTE: If you are using a PosgreSQL, the database process logs are stored in the pgsql/data/pg_log
directory. This folder is not automatically managed nor cleaned by the database or by Control-M
processes. To avoid consuming disk space, BMC recommends to delete log files older than ten days.
The following procedures describe how to perform periodic Control-M/EM database maintenance and
cleanup:
 Checking Database space (on page 37)
 Extending the Oracle database (on page 38)
 Extending the MSSQL database (on page 38)
 Removing old archived viewpoints (on page 479)

Removing old archived viewpoints

This procedure describes how to remove old archived viewpoints, which are recordings of job changes
(data, conditions, and resources) that occur in the Active Jobs file on any given day.
For more information, see Loading an archived Viewpoint.
 To remove old archived viewpoints:
1. Display the Control-M/EM Root Menu (root_menu).
2. In the Control-M/EM Root Menu, enter the number for the Database Maintenance option.
3. In the Database Maintenance menu, enter the number for the Erase Old Nets option.
4. Enter q to exit the Database Maintenance menu and the Root menu.
(Windows only) Gateway automatically removes old archived networks.

Deleting audit records from the root_menu

This procedure describes how to delete audit records of the Audit_activities table in the database from the
root_menu.
 To delete audit records interactively from the root_menu (UNIX only):
1. Display the Control-M/EM Root Menu (root_menu).
2. In the Control-M/EM Root Menu, enter the number for the Database Maintenance option.
3. In the Database Maintenance menu, enter the number for the Erase Audit Data option.
4. Enter q to exit the Database Maintenance menu and the Root menu.

 To delete audit records using a script (UNIX or Windows):

1. Log on to the Control-M/EM host computer as a Control-M/EM administrator.
2. Enter the following command. If you do not specify -U and -P, you will be prompted to enter the DBO
user name and password.
erase_audit_data [-date yyyymmdd] [-U EM_DBO_name] [-P EM_DBO_password]
Records written before the specified date are deleted.

479
Control-M Administrator Guide

Deleting audit records with a script

This procedure describes how to delete audit records of the Audit_activities table in the database with a
script.

 To delete audit records using a script (UNIX or Windows):

1. Log on to the Control-M/EM host computer as a Control-M/EM administrator.
2. Enter the following command. If you do not specify -U and -P, you will be prompted to enter the DBO
user name and password.
erase_audit_data [-date yyyymmdd] [-U EM_DBO_name] [-P EM_DBO_password]
Records written before the specified date are deleted.

Control-M/Server database maintenance and cleanup

The database server writes a message to an error log file when the server is started or shut down, and
when a database error occurs. This file is not automatically truncated. If not manually truncated, the file
will utilize a large amount of disk space. The file created is called an error log for MSSQL, and an alert log
for Oracle. [UNIX only]
The responsibility of maintaining the error log file goes to the Control-M administrator or the database
administrator depending on whether your site is using the database server provided with the installation,
or a current database server when your site:
 Uses a BMC-supplied PostgreSQL database server, it is the responsibility of the Control-M
administrator to truncate this file on a regular basis
 Uses a current database server, it is the responsibility of the database administrator to truncate this
file on a regular basis
Control-M/Server writes process log trace files to the proclog directory.
Each time Control-M/Server starts:
 The new logs are saved to one of the following locations:
• UNIX: $CONTROLM_SERVER/proclog
• Windows: <ctm_installation>\proclog
 The proclog file from the previous session is saved to one of the following locations:
• UNIX: $CONTROLM_SERVER/proclog.sav
• Windows: <ctm_installation>\proclog.sav
The higher the trace level, the larger the log files. If Control-M/Server entities operate for a long time
using a trace level greater than zero, these log files utilize a large amount of disk space.
NOTE: If you are using a PosgreSQL, the database process logs are stored in the pgsql/data/pg_log
directory. This folder is not automatically managed nor cleaned by the database or by Control-M
processes. To avoid consuming disk space, BMC recommends to delete log files older than ten days.
The following procedures describe how to perform periodic Control-M/Server database cleanup
procedures:

480
Control-M Administrator Guide

 Extending the Oracle database (on page 38)

 Extending the MSSQL database (on page 38)
 Cleaning up the Control-M/Server proclog directory (on page 481)

Cleaning up the Control-M/Server proclog directory

This procedure describes how to clean up the Control-M/Server proclog directory. The Control-M/Server
administrator should delete these log files when they are no longer needed.
 To clean up the Control-M/Server proclog directory:
1. Display the Control-M Main Menu by typing the ctm_menu command.
2. In the Control-M Main menu, type the number corresponding to the Troubleshooting option.
3. In the Troubleshooting menu, enter the number corresponding to the Erase Proclog Files option.
This option erases the contents of the current process log file either for all active Control-M/Server
processes or for any specific active process.
4. Specify the 2-character code for a specific process, or ALL for all current process log files.

proclog utility parameters

Log retention is determined by the parameters in the following table.

Parameter Description

OS_DIAG_LIMIT_LOG_ Number of generations of diagnostic log information to keep for a process or a

VERSIONS thread.
Valid values:
 -1 (no limit to the number of files)
 1–2^31
Default: -1 (In the shipped config.dat, the default value is overridden by 10.)
Refresh Type: Recycle

OS_DIAG_LIMIT_LOG_ Maximum size (MB) of diagnostic log files for a process or a thread.
FILE_SIZE
Valid values:
 -1 (no filesize limit)
 1–2^31
Default: -1 (In the shipped config.dat, the default value is overridden by 10.)
Refresh Type: Recycle

481
Control-M Administrator Guide

Database parameters
Database configuration parameters are specified during installation, before the Control-M/Server database
is created. You can subsequently change these parameters and rebuild the Control-M/Server database by
using the Database Menu menu for PostgreSQL, MSSQL, and Oracle.
UNIX: System paths or raw partitions for the data and log files must be unique (MSSQL and PostgreSQL).
The following lists configuration parameters for the following databases:
 Oracle parameters (on page 483)
 MSSQL parameters (on page 485)
 PostgreSQL parameters (on page 487)

482
Control-M Administrator Guide

Oracle parameters
The following table lists the Control-M/Server database parameters for the Oracle environment.

Parameter Description

Control-M Database Defines the name of the Oracle SQL server (1 to 8 characters, alphabetic plus "_")
Instance name
Default: ctrlm

Control-M INDEX Defines the full path name to the Control-M INDEX tablespace file
tablespace file location
Default: /<controlm_home_dir>/oracle/oradata/ctrlm/indx01.dbf

Control-M INDEX Defines the size of the Control-M INDEX tablespace file
tablespace size
Default: 50 MB

Control-M Listener port Defines the TCP/IP port for communication between Control-M and Oracle SQL
number Server. The port must be dedicated to this purpose. Choose a number in the range
1024 to 65534 inclusive.
Default: 1521
Refresh Type: Recycle

Control-M RBS Defines the full path name to the Control-M RBS tablespace file
(Rollback Segment)
Default: /<controlm_home_dir>/oracle/oradata/
tablespace file location
ctrlm/rbs01.dbf

Control-M RBS Defines the size of the Control-M RBS tablespace file
tablespace size
Default: 50 MB

Control-M SYSTEM Defines the full path name to the Control-M SYSTEM tablespace file
tablespace file location
Default: /<controlm_home_dir>/oracle/oradata/
ctrlm system01.dbf

Control-M SYSTEM Defines the size of the Control-M SYSTEM tablespace file
tablespace size
Default: 50 MB

Control-M TEMP Defines the full path name to the Control-M TEMP tablespace file
tablespace file location
Default: /<controlm_home_dir>/oracle/oradata/ctrlm/temp01.dbf

Control-M TEMP Defines the size of the Control-M TEMP tablespace file
tablespace size
Default: 100 MB

Name of the first Defines the full path name of the first database log file
database log file
Default: /<controlm_home_dir>/oracle/oradata/ctrlm/log01.dbf

483
Control-M Administrator Guide

Parameter Description

Name of the second Defines the full path name of the second database log file
database log file
Default: /<controlm_home_dir>/oracle/oradata/ctrlm/log02.dbf

Name of the Defines the full path name of Control-M/Server database data file
Tablespace data file
Default: /<controlm_home_dir>/oracle/oradata/ctrlmdata.dbf

Oracle CDROM name Defines the name of CDROM device containing the Oracle installation CDROM.

Oracle home directory Defines the directory where Oracle binary files are stored
Default: /<controlm_home_dir>/oracle

Oracle Server Host Defines the host computer name of an existing Oracle server
name

Oracle SYSTEM user Defines the password of the Oracle SYSTEM user
password

Size of Control-M Defines the size of each database log file. There are two files of equal size.
database log files
Default: 20 MB

Tablespace size Defines the total size of the Control-M/Server database

Default: 250 MB

Tablespace User Defines the name of Control-M/Server database user

Default: controlm

User Password Defines the password for the Control-M/Server database user (6 to 30 characters,
alphanumeric). The characters you enter do not echo for security reasons.
Control-M processes and utilities uses the password to access the Control-M/Server
database.
Default: password

484
Control-M Administrator Guide

MSSQL parameters
The following table lists Control-M/Server database parameters for the MSSQL environment.

Parameter Description

Server Host Name Defines the host name of the machine where the SQL Server resides. If you
install the dedicated SQL Server, the value is the current machine. For a silent
installation the value of this parameter is blank, and the installation procedure
uses the name of the current machine.

Query Port Number Defines two TCP/IP ports for communication between Control-M/Server and
the SQL Server. The port numbers must be different from each other. If these
-and-
port numbers are already used by an existing application, choose other values,
Backup Port Number each in the range 1024 to 65534 inclusive.
Default: 7102 and 7103
Refresh Type: Recycle

System Administrator (SA) Defines the password (6 to 30 alphanumeric characters) for the database
Password administrator (user sa). The characters you enter, do not echo for security
reasons. Control-M/Server utilities uses the password to access restricted
sections of the Control-M/Server database.
Default: password

Control-M/Server Database Defines the name for the Control-M/Server database, which must be unique.
Name
If you use unique values for owner name, database name, and device
assignments, a new database is built on the server. By using an existing
owner name, database name, and device assignment, you delete and recreate
the database elements.
Every computer type uses a different character set for the server.
Default: ctrlm

Control-M/Server Database Defines the database name of the Control-M/Server database owner. The
Owner installation script creates this user in the database. Control-M/Server uses the
name when accessing its database.
Default: ctrlm

Control-M/Server Database Defines the password of the Control-M/Server database owner (6 to 30

Owner (DBO) Password alphanumeric characters). The characters you enter, do not echo for security
reasons. The first character must be a letter (A – Z). Control-M/Server uses
the password for processes and utilities to access the Control-M/Server
database.
Default: password

485
Control-M Administrator Guide

Parameter Description

Data Device Logical Name Defines the name of the device where the Control-M/Server database is
located.
Default: ctrlm_ux

Data Device Path Defines the full path name of the Control-M/Server database.
Default: c:\<sql_dir>\data\ctrlm_ux

Data Device Size Defines the amount of space (MB) allocated for the data portion of the
Control-M/Server database.
Default: 75 (MB)

Log Device Logical Name Defines the name of the device where the Control-M/Server database is
located.
Default: ctrlm_log

Log Device Location Defines the full path name where the Control-M/Server database log is
located.
Default: c:\<sql_dir>\data\ctrlm_log

Log Device Size Defines the amount of space (MB) to allocate for the Control-M/Server
database log.
Default: 25 (MB)

486
Control-M Administrator Guide

PostgreSQL parameters
The following table lists the Control-M/Server database parameters for the PostgreSQL environment.

Parameter Description

Host Interface Name Defines the host name of the machine where the PostgreSQL Server resides.
If you install the dedicated PostgreSQL Server, the value is the current
machine. For a silent installation, the value of this parameter is blank, and the
installation procedure uses the name of the current machine.

Port Number Defines the TCP/IP port for communication between Control-M/Server and the
PostgreSQL Server. If this port number is already used by an existing
application, choose another value, in the range 1024 to 65534 inclusive.
Default: 5432
Refresh Type: Recycle

Database Administrator Defines the password for the database administrator (user postgres). The
(postgres) Password characters you enter do not echo for security reasons. Control-M/Server
utilities uses the password to access restricted sections of the
Control-M/Server database.
NOTE: The single apostrophe symbol (" ‘ ") is not permitted for PostgreSQL.

Control-M/Server Database Defines the name of the Control-M/Server database. This name must be
Name unique, and contain up to 30 alphanumeric lowercase characters (including
the underscore character).

Control-M/Server Database Defines the database name for the Control-M/Server database owner. The
Owner installation script creates this user in the database. Control-M/Server uses this
when accessing its database.
If you use unique values for owner name, database name, and device
assignments, a new database is built on the server. By using an existing
owner name, database name, and device assignment, you delete and recreate
the database elements.
Every computer type uses a different character set for the server.

Control-M/Server Database Defines the password for the Control-M/Server database owner. This name
Owner (DBO) Password must be unique, and must contain up to 30 alphanumeric lowercase
characters (including the underscore character). The characters you enter do
not echo for security reasons. Control-M/Server processes and utilities use the
password to access the Control-M/Server database.
NOTE: The single apostrophe symbol (" ‘ ") is not permitted for PostgreSQL.

487
Control-M Administrator Guide

Parameter Description

Database Scalability Defines the amount of resources in the operating system of the computer on
which the PostgreSQL server is employed.
Valid values:
 Small
 Medium
 Large

Database Server Home Defines the full path name of the location where the PostgreSQL database
Directory (Windows only) server resides: <Control-M/Server path>/pgsql.
NOTE: Only for PostgreSQL database server on Windows.

Database Location (UNIX Defines the full path name of the location in which the Control-M/Server
only) database should be installed: $PGHOME
You must create this location prior to installing the Control-M/Server database.
NOTE: Only for PostgreSQL database server on UNIX.

Configuring Control-M/EM Always On

This procedure describes how to configure Control-M/EM with MSSQL Always On data replication.
NOTE: The DBUbuild and Cold restore utilities are not supported in Always On mode.

 To configure Control-M/EM Always On:

1. Install Control-M/EM on a new computer, as described in Installing Control-M/EM on Windows.
2. Migrate Control-M/EM data from the older version to the new Control-M/EM version, as described in
Control-M/EM Migration.
3. Shut down Control-M/EM.
4. Send a request to the site DBA to load the standalone database into the Availability Group.
The database is now accessed by the global listener.
5. Send a request to the site DBA to grant VIEW SERVER STATE permissions the new login.
6. Verify that the site DBA sends you the Always On listener name and port number.
7. Run the restore_host_config utility, as described in Reconfiguring the database server connection
data.
Control-M/EM is now working in Always On mode.
8. Verify Always On connectivity, by running the following command:
always_on_config list pass=<Control-M/EM password>

488
Control-M Administrator Guide

Configuring Control-M/Server with MSSQL Always On

This procedure describes how to configure Control-M/Server with MSSQL Always On data replication.
NOTE: The DBUbuild and Cold restore utilities are not supported in Always On mode.

 To configure Control-M/Server Always On:

1. Install Control-M/Server on a new computer, as described in Installing Control-M/Server on Windows.
2. Migrate Control-M/Server data from the older version to the new Control-M/Server version, as
described in Control-M/Server Upgrade.
3. Shut down Control-M/Server.
4. Send a request to the site DBA to load the standalone database into the Availability Group.
The database is now accessed by the global listener.
5. Send a request to the site DBA to grant VIEW SERVER STATE permissions the new login.
6. Verify that the site DBA sends you the Always On listener name and port number.
7. Run the following commands:
• always_on_config set mode=Y
• always_on_config set server=<listenername{,port}>
The password for the database login remains the same.
8. Start up Control-M/Server.
Control-M/Server is now working in Always On mode.
9. Verify Always On connectivity, by running the following command:
always_on_config list pass=<Control-M/Server password>

489
16
16
User Exits
A user exit is a user-defined procedure that can be used to modify certain information before it is
processed. At certain points in processing, a flat text file is produced describing information that is passed
to the next step in a procedure. This text file can be modified by a user-defined exit script before it is
passed on for processing.
Control-M/Server user exits can be used to enforce site standards (for example, file naming conventions
or valid date formats), and to apply security definitions to limit certain user’s actions. Exits can also be
used to trigger other actions prior or subsequent to execution of a Control-M job.
EXAMPLE: A flat text file is produced containing parameters to be processed by Control-M. The name of
the text file is passed as a parameter to the user exit script. The user exit script runs, and is
often used to modify the contents of the text file. However, it can also be used to perform
any other action (for example, to copy information from the text file to another location).
Control-M then continues processing using the modified text file.
User exits are implemented only if they have been enabled by setting the appropriate configuration
parameters.
To implement user exits, see Implementing User Exits in Control-M/Server (on page 490).
To view available user exits, see Control-M general user exits (on page 491).

Implementing User Exits in Control-M/Server

This procedure describes how to implement user exits in Control-M/Server.

 To implement User Exits in Control-M/Server:

1. Implement one of the user exits, as described in Control-M general user exits (on page 491).
2. Set appropriate values to exit configuration parameters in the config.dat file, which is located in the
following directory:
• UNIX: <controlmOwner>/ctm_server/data/config.dat
• Windows: <productDirectory>\ctm_server\data\config.dat
3. Do the following:
a. Enable Control-M exits: Ensure that the value of the CTM_PRM_ENABLE_UE parameter is set to
Y (default).
b. Enable specific user exits: Set the value of the relevant CTM_PRM_ENABLE_UEnnn
configuration parameters to Y (nnn is the numeric part of the user exit name, valid values
101-106).
c. In the CTM_PRM_TIMEOUT_UEnnn configuration parameter, set the maximum time to wait
for the associated user exit script to run before it is terminated (where nnn is the numeric part of
the user exit name, valid values 101-106).
UNIX: Time is measured in units of seconds.

490
Control-M Administrator Guide

Windows: Time is measured in units of milliseconds.

4. In the user exit directory, define the scripts for the implemented user exits and assign the scripts
default file names in the format:
• UNIX: ctm_exitnnn.sh (nnn is the numeric part of the user exit name, valid values 101-106).
• Windows: ctm_exitnnn.bat (nnn is the numeric part of the user exit name, valid values
101-106).
The location of the directory is:
• UNIX: controlmOwner/ctm_server/ue_exit
• Windows: <productDirectory>\ctm_server\ue_exit

Control-M general user exits

The following table describes the available user exits.

User Exit Description

Job Order Exit (CTMUE101) (on Executes for each Control-M job before it is ordered
page 491)

Job Submission Exit (CTMUE102) Executes for each Control-M job before it is submitted for
(on page 493) execution

Before New Day Procedure Exit Executes before the New Day procedure runs
(CTMUE103) (on page 495)

After New Day Procedure Exit Executes after the New Day procedure runs
(CTMUE104) (on page 496)

Before User Daily Exit Executes before each run of a Control-M User Daily job (except
(CTMUE105) (on page 496) SYSTEM)

After User Daily Exit Executes after each run of a Control-M User Daily job (except
(CTMUE106) (on page 496) SYSTEM)

Job Order Exit (CTMUE101)

This exit is executed for each Control-M job before it is ordered. The flat text file passed to the exit is a
job record from the Scheduling definition folder. User exit CTMUE101 can be used to alter the job
information in this file after it is fetched from the database and before it is passed to the procedure that
determines if the job will be ordered for the current day.

491
Control-M Administrator Guide

NOTE: This user exit does not support sub-folders in Control-M/Server.

The following is a sample text file in the format that is passed to the CTMUE101 exit:
JOBNAME daily_job
JOBNO 30
DESCRIPT
APPLIC STRESS
APPLGROUP STRESS
SCHEDTAB STRESS
AUTHOR ctm600
OWNER ctm600
PRIORITY 0
CRITICAL N
CYCLIC N
RETRO N
AUTOARCH N
TASKCLASS
CYCLICINT 0
TASKTYPE C
DATEMEM
NODEGRP
computer
NODEID
DOCLIB
DOCMEM
MEMLIB
MEMNAME
OVERLIB
CMDLINE ./stress_cmd_spl.ctm600
MAXRERUN 0
MAXDAYS 0
MAXRUNS 0
FROMTIME
UNTIL
MAXWAIT 0
DAYSTR ALL

492
Control-M Administrator Guide

WDAYSTR
MONTHSTR YYYYYYYYYYYY
AJFSONSTR NNNNNNNNNNNNN
CONF N
UNKNOWNTIM 0
DAYSCAL
WEEKCAL
CONFCAL
CAL_ANDOR O
SHIFT
ADJUST_COND
STARTENDCYCIND S
CREATIONUSERID ctm600
CREATIONDATETIME 20001113070229
CHANGEUSERID
CHANGEDATETIME
RELATIONSHIP
GROUPID 0
TABROWNO 1
EXAMPLE: The following exit script changes the Days parameter (DAYSTR) for jobs that were scheduled
on the first day of the month, so that these jobs are ordered on the second day of the month.
#!/bin/ksh
cp $1 /tmp/ue101.$$
sed -e 's/DAYSTR 1/DAYSTR 2/' /tmp/ue101.$$ > $1

Job Submission Exit (CTMUE102)

This exit is executed for each Control-M job before it is submitted for execution. The flat text file passed
to the exit contains a job record from the Active Jobs table. User exit CTMUE102 can be used to alter job
information in this record before it is passed to the Control-M/Agent for job submission.
The following is a sample text file in the format that is passed to the CTMUE102 exit:
JOBNO 0
ORDERNO 19450
PRIORITY 1039
CRITICAL N
TASKTYPE C

493
Control-M Administrator Guide

CYCLIC N
CONFIRM_R N
CONFIRMED N
RETRO N
AUTOARCH N
TASKCLASS
HOLDFLAG N
STATUS N
STATE E
CYCLICINT 0
APPLGROUP dw_S_A_AAS
NODEGRP
NODEID fire
MEMLIB /mdw/oper/tgt/scripts/shells
MEMNAME dw##r#####
OVERLIB /mdw/oper/tgt/scripts/shells/overlib_all
CMDLINE sleep 30
ODATE 19960229
PROCID
RERUN_NO 0
OSCOMPSTAT 0
OSCOMPMSG
NEXTTIME
PREVDATE
NEXTDATE
STARTRUN
ENDRUN
MAXRERUN 0
FROMTIME
UNTIL
JOBNAME dwlnr21AAS
SCHEDTAB CREATED
OWNER ctm600
MAXWAIT 7
APPLIC DW_ln

494
Control-M Administrator Guide

RUNCOUNT 1
DAILYNAME ctm600
AJFSONSTR YYNNYNNNNNNNN
DESCRIPT Datawarehouse ln snapshot sort and form
DOCMEM dwlnr1
DOCLIB /mdw/cntlm/doc
MAXDAYS 0
MAXRUNS 0
UNKNOWNTIM 0
STARTENDCYCIND S
TRIGGER_TAG
GROUP_ORD 0
AUTHOR
EXAMPLE: The following exit script checks if the job has a Owner of root and changes the Owner for
these jobs to nobody.
#!/bin/ksh
cp $1 /tmp/ue102.$$
sed -e 's/OWNER root/OWNER nobody/' /tmp/ue102.$$ > $1

Before New Day Procedure Exit (CTMUE103)

This exit is executed before the New Day procedure is run. The New Day Procedure performs automatic
functions at the beginning of each new Control-M working day. This procedure is used as a master
scheduler for all Control-M activities.
The flat text file that is passed to the exit contains the name of the Daily (SYSTEM), time, and original
scheduling date (Order Date) of the procedure.
The following is a sample text file in the format that is passed to the CTMUE103 exit:
DAILY_NAME SYSTEM
TIME 1300
ODATE 20001121
EXAMPLE: The following exit script runs a procedure that performs various actions before the New Day
procedure is run.
#!/bin/ksh
/opt/controlm/scripts/run_pre_New_Day_proc

495
Control-M Administrator Guide

After New Day Procedure Exit (CTMUE104)

This exit is executed after each run of the Control-M New Day procedure. The flat text file that is passed
to the exit contains the name of the Daily (SYSTEM), time, and original scheduling date (Order Date) of
the procedure.
The following is a sample text file in the format that is passed to the CTMUE104 exit:
DAILY_NAME SYSTEM
TIME 1319
ODATE 20001121
EXAMPLE: The following exit script runs a procedure that performs various actions after completion of
the New Day procedure.
#!/bin/ksh
/opt/controlm/scripts/run_post_New_Day_proc

Before User Daily Exit (CTMUE105)

This exit is executed before each Control-M User Daily job (except SYSTEM) is run. User Daily jobs can be
used to order new jobs.
The flat text file that is passed to the exit contains the name of the User Daily, time, and original
scheduling date (Order Date) of the User Daily job.
The following is a sample text file in the format that is passed to the CTMUE105 exit:
DAILY_NAME my_daily
TIME 1321
ODATE 20001121

After User Daily Exit (CTMUE106)

This exit is executed after each Control-M User Daily job (except SYSTEM) is run. User Daily jobs can be
used to order new jobs.
The flat text file that is passed to the exit contains the name of the User Daily, time, and original
scheduling date (Order Date) of the User Daily job.
The following is a sample text file in the format that is passed to the CTMUE106 exit:
DAILY_NAME my_daily
TIME 1322
ODATE 20001121
If the User Daily job fails, the User Exit 106 (UE106) will not be executed.

496
17
17
Scripts
The following topics describe how to write scripts on a Control-M/Agent computer on UNIX and Windows
for a Control-M/Server job:
 Shell Scripts on UNIX (on page 497)
 Scripts on Windows (on page 502)

Shell Scripts on UNIX

When writing a shell script on an Agent computer, which is run as a Control-M/Sever job, you need to do
the following:
 Specify the shell type, as described in Shell types (on page 497).
 Factor the runtime environment, as described in Runtime environment (on page 499).
 Use On Statement/Code parameter to interpret script lines, as described in On Statement/Code
parameter (on page 500).
BMC recommends that you run each script manually to validate the script syntax before running the
script.

Shell types
The following table describes the shell path, which you need to specify on the first line of the script to
enable Control-M to recognize the script shell type.
#! <shell path>

Shell type Shell path Default Switch Other switches

Bourne /bin/sh -x -v/n

bash /bin/bash -x -v/n

Korn /bin/ksh -x -v/n

Restricted Korn /bin/rksh -x -v/n

csh /bin/csh

tcsh /bin/tcsh

NOTE: The command line of command type jobs must be in Bourne shell syntax only.
For information about the switches, see Shell switch parameters (on page 498).

497
Control-M Administrator Guide

Shell switch parameters

The following table describes the Shell switch parameters, which affect Control-M/Agent processing:

Parameter Description

-x Enables Control-M/Agent to submit the script as is. The script runs

under the specified shell and prints commands and related
arguments as they are executed.
NOTE: 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 s later used during an On statement
post-processing phase of the jobs output to distinguish between
the different commands and their output.

-v Enables Control-M/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 should be executed as is and no

commands will be included in the job’s output. As a result no
On-statement processing is possible.

For more information about the different flags, see Shell script type switch examples (on page 498).
NOTE: Arguments specified after the shell name are ignored by Control-M/Agent with the following
exception: -x is supported when running a script under the Bourne shell and bash or Korn shell and
restricted Korn shell. If -x is specified as an argument after the shell name, it overrides any option set in
the CTM_PRM_SH_FLAGS or CTM_PRM_KSH_FLAGS parameters.

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 $?

498
Control-M Administrator Guide

 If the -x flag was set when running the sample script, the job produces the following output:
DBNAME=app
+ export DBNAME
+ dbrefresh -U dbadmin -P stx111
DB refreshed
+ 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

Activating REXX-Language scripts

This procedure describes how to activate REXX-Language scripts, which are supported on AIX and Solaris.

Before you begin

Ensure the REXX product is installed on the agent computer.

 To activate a REXX script:

 Specify the full path under which REXX is installed in the first line of the REXX script.
EXAMPLE: #!/usr/;oca;/bin/rxx

Runtime environment
Control-M runs a job script under the environment specified for the job owner (the name specified in the
Run As parameter). The environment affects these factors in the execution of the script:

499
Control-M Administrator Guide

 Establishing the user log on process: As jobs are submitted for execution, Control-M/Agent logs
in as the user and executes the job (the shell script) using the following command:
su- <owner> -c <script name>
During the log in process, the user environment is set according to the shell type specified in
/etc/passwd.
 Establishing the shell script startup process: The startup process for running the script depends
upon the type of shell under which the script runs.
• When a csh or tcsh script is run, the .cshrc file of the job owner is executed as part of the startup
process for the script.
• For all other shell types, the .profile file of the job owner is executed as part of the startup
process for the script.
NOTE: The .login file is not executed as part of the start up process.
• When Control-M executes job scripts, there is no terminal associated with the job. Therefore, do
not use commands in a script that query terminal characteristics or take input from a terminal.
• The shell script startup process sets the environment variables that are available when the script
is run. Use the #! statement to indicate the shell under which the script is intended to run.
 Indicating the Working directory: The working directory when the script runs is initially set to
the home directory of the job owner (the home directory for each user is set by the UNIX
administrator in /etc/passwd).
When writing scripts that access files, specify the file name in the script with a full path or with a path
relative to the home directory of the job owner.

On Statement/Code parameter
The following items describe how the On Statement/Code job processing parameter interprets script lines.
 Type of Script Statement: Depending on the shell used, Control-M/Agent does not process the
following types of script statements for comparison with the text specified in the Stmt sub parameter
of the On Statement/Code parameter:
• For a Bourne shell, text in if, for, while and case statements.
• For a csh shell, text in if statements

500
Control-M Administrator Guide

EXAMPLE: No part of the following script line should be used in the Stmt sub parameter of the On
Statement/Code parameter:
if [ ‘baseline’ - eq 0 ]; then
 Continuation Lines: Control-M/Agent does not process continuation lines for comparison with text
specified in the Stmt sub parameter of the On Statement/Code parameter. In the Stmt
subparameter do not specify text that is on a script continuation line.
 Length of Script Statement: Control-M/Agent only processes the first 132 characters of a script
statement for comparison with the text specified in the Stmt subparameter of the On Statement/Code
parameter.
 HERE Documents: The term HERE document refers to lines of text in a script that are passed to a
command as input, but are not passed to the shell. Control-M/Agent does not support the On
Statement/Code job processing parameter for HERE documents.
EXAMPLE: In the following script, line 1 and line 2 of a HERE document are passed to the specified
cat command:
cat > /tmp/junk << EOF_EOF
line 1
line 2
EOF_EOF
echo "DONE"
For more information about the On Statement/Codes, see On/Do Actions in Control-M Parameters.

Using different exit codes for Control-M/Server

This procedure describes how to enable Control-M/Server to distinguish between different exit codes.

 To use different exit codes for Control-M/Server:

 In the On Statement/Code job processing parameter, type the following expression in the Code sub
parameter:
COMPSTAT=<value>
<value> is the exit code of the script.
EXAMPLE: Assume that a script exits with an exit code of 5. This condition can be detected by defining
the following On Statement/Code parameters:
Stmt: *
Code: COMPSTAT=5

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 Control-M/Server job using the –v
flag it is parsed into a temporary script. For more information about Shell types, see Shell types (on
page 497).

501
Control-M Administrator Guide

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 Control-M/Server 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 the ctmunixcfg utility, as described in ctmunixcfg.
Setting the flag causes Control-M/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.
EXAMPLE:
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 Control-M/Server 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

Scripts on Windows
In Windows, Control-M/Agent can run any type of job scripts (such as vbs, perl, DOS bat or cmd, Rexx,
etc). To correctly implement scripts for Windows, you need to consider the following:

502
Control-M Administrator Guide

 Comply with script rules: As part of the post processing of a job, you must do the following to
scripts analyzed by Control-M/Server:
• Begin the script with the echo on command, which ensures that job script statements are written
to the output file.
• End each prompt with the > or ] character. These characters and embedded spaces should not
be used inside the prompt text string.
 Use On Statement/Code parameters: Control-M/Agent can use the On Statement/Code job
processing parameters to perform post-processing analysis of the output of jobs that are submitted
by using these scripts. The following items describe how the On Statement/Code job processing
parameter interprets script lines:
• On Statement/Code output: Text in an output file that follows a > prompt or ] prompt is
treated by Control-M/Server as part of the job script. All other text is treated as part of the
operating system response. When specifying an On Statement/Code statement (format 1) in a job
processing definition, place text that follows either of these prompts in the Stmt parameter. Place
other text in the Code parameter.
• Continuation Lines: Control-M/Server does not process continuation lines for comparison with
text in a Stmt sub parameter. Therefore, do not specify script continuation line text in the Stmt
sub parameter.
• Length of script statement: Control-M/Server compares the first 512 characters of a script
statement with the text in sub parameter Stmt. Therefore, in subparameter Stmt, do not specify
text that comes after the first 512 characters of a script statement. The maximum length of the
On Code parameter is 255 characters.
For more information about the On Statement/Code parameters, see On/Do Actions.
 Enable Control-M/Server to distinguish between exit codes: Both DOS .bat scripts and REXX
.cmd scripts can return an exit code to Control-M/Server upon completion. The _exit utility described
is used by .bat scripts. For more information about enabling Control-M/Server to distinguish between
exit codes, see Using different exit codes for Control-M/Server (on page 501).
 Use script utilities: The_exit and _sleep utilities can be accessed from within job scripts. For more
information, see Control-M/Agent utilities.
 Translate DOS files and REXX scripts to UNC, as described in Translating DOS files and REXX
scripts to UNC (on page 503).

Translating DOS files and REXX scripts to UNC

This procedure describes how to translate DOS batch files (.bat) and REXX-language (.cmd) scripts that
contain mapped path names into scripts, which use Universal Naming Convention (UNC) equivalents, to
reference remote disk resources using the CTMBAT2UNC utility. These translated scripts enable
Control-M/Agent to execute multiple scripts simultaneously. The owners of the jobs do not have to be
logged on to provide the drive mappings for the scripts.
 To translate DOS files and REXX scripts to UNC:
 Type the following command:
ctmbat2unc.exe <batch_file_to_translate> <output_file_name>
batch_file_to_translate>: Original .bat or .cmd script

503
Control-M Administrator Guide

<output_file_name>: New script after translation

For an example, see Example translating DOS files using the CTMBAT2UNC utility (on page 504).

Example translating DOS files using the CTMBAT2UNC utility

Two job owners, A and B, are executing ScriptA.bat and ScriptB.bat, respectively. Owner A has drive M
mapped to \\nt-A\share. Owner B has drive M mapped to \\nt-B\share.
The following table describes these scripts before and after executing the CTMBAT2UNC utility.

Owner Original script Translated script

A @echo off @echo off

dir M:\jobs REM Following line was
changed by CTMBAT2UNC
dir \\nt-A\share\jobs

B @echo off @echo off

dir M:\jobs REM Following line was
changed by CTMBAT2UNC
dir \\nt-B\share\jobs

As shown above, every line changed by the CTMBAT2UNC utility is marked by a REM comment inserted
before the translated line.
BMC recommends that you review the translated script after invoking the ctmbat2unc utility.

504
18
18
BSM configuration procedures
The following procedures describe how do basic configurations for BMC Batch Impact Manager and
Control-M/Forecast:
 BMC Service Impact Manager configuration (on page 505)
 Purging obsolete periodic statistics entries (on page 507)

BMC Service Impact Manager configuration

You can configure the BMC ProactiveNet (TrueSight) to enable you to work with Control-M BMC Batch
Impact Manager classes. BMC ProactiveNet (TrueSight) solution versions 8.x through 9.x are supported.
The following procedures enable you to configure BMC SIM:
 Configuring BMC ProactiveNet on Microsoft Windows (on page 505)
 Configuring BMC ProactiveNet server on UNIX (on page 506)

Configuring BMC ProactiveNet on Microsoft Windows

This procedure describes how to install and configure the BMC Batch Impact Manager class on BMC
ProactiveNet Server on Windows.
 To configure BMC ProactiveNet on Microsoft Windows:
1. Create a temporary directory.
2. From the BMC Batch Impact Manager installation home, copy the contents of one of the
%EM_HOME%/bim/proactivenet/classes subdirectory to the temporary directory.
3. Navigate to the temporary directory, created in step 1, which contains the files copied from the
installation CD.
4. Open the Microsoft Windows Services utility and ensure that the mcell_cellID service is running.
5. Open a Command Prompt window and run the following command:
load.cmd > load.log
6. To check that the mcell service is running, refresh the display periodically by pressing F5.
7. If the mcell service stops, restart it.
8. Close the Command Prompt window.
9. Ensure that you keep the load.log file that is generated by load.cmd, in case services do not get
transferred to BMC ProactiveNet.

505
Control-M Administrator Guide

load.cmd file parameters

The following table describes the load.cmd file parameters.

Parameter Details

MASTERCELL_HOME Defines the name of the folder where BMC Service Impact
Manager is installed.

CELLID Defines the ID for the BMC Service Impact Manager instance
you are installing.

PERL Defines the full path containing the perl.exe file, which is
installed during the BMC Service Impact Manager installation.

Configuring BMC ProactiveNet server on UNIX

This procedure describes how to install and configure BMC ProactiveNet server on UNIX to include the
BMC Batch Impact Manager class.
 To configure ProactiveNet server on UNIX:
1. Create a temporary directory in the BMC ProactiveNet Server side.
2. From the BMC Batch Impact Manager installation, copy the contents of one of the
$HOME/ctm_em/etc/bim/proactivenet/classes subdirectories to the temporary directory,
as follows:
a. Copy the ctm_bim_classes.baroc file to the BMC SIM classes directory, called
%MCELL_HOME%/etc/%CELLID%/kb/classes.
b. Add ctm_bim_classes to the end of the .load file, located in
%MCELL_HOME%/etc/%CELLID%/kb/classes/.load
c. Copy the ctm_autocloseOK.mrl and ctm_NewClosesOld.mrl files to the SIM rules
directory, called %MCELL_HOME/etc/%CELLID/kb/rules.
d. Add ctm_autocloseOK and ctm_NewClosesOld to the end of the .load file, located at
%MCELL_HOME%/etc/%CELLID%/kb/rules/.load as follows:
o ctm_autocloseOK
o ctm_NewClosesOld
The BMC SIM engine compiles all files listed in this file.
3. Run the following command to compile the database:
%MCELL_HOME/server/bin/mccomp" -v
%MCELL_HOME/server/etc/%CELLID/kb/manifest.kb
4. Run the following commands to reload the database:
%MCELL_HOME/bin/mcontrol -n %CELLID% reload data

506
Control-M Administrator Guide

%MCELL_HOME/bin/mcontrol -n %CELLID% reload kb

%MCELL_HOME/bin/mcontrol -n %CELLID% reload collect

Purging obsolete periodic statistics entries

Each time a job completes its execution, its periodic statistics entry in the Control-M/EM database is
updated.
Periodic statistics entries that are not updated for a specified duration of time are considered obsolete and
are removed from the database. The user specifies the duration of the time by setting the
RunInfoStatsPurgeDays parameter (Type: cms) to the required number of days.
The Control-M Configuration Manager server automatically purges the database of obsolete statistics
records at specific intervals. The user determines the interval between purges by setting the
RunInfoStatsPurgeInterval parameter (type: cms) to the required number of minutes.

507
19

Remedy configuration
You can configure the connection to the Remedy server and test the connection with the new parameters
by using the following interactive utilities:
• emremedy_configure (Control-M/EM): The utility is located in ctm_em/bin (UNIX) and <EM
home>\bin (Windows)
• ctm_remedy_configure (Control-M/Server): The utility is located in <CTM server
home>/scripts (UNIX) and <CTM server home>\Exe (Windows)
These utilities enable you to set the Remedy server hostname, port, username, and password.
NOTE: When the Remedy server is configured to use a port mapper, the Remedy port must be set to 0
(default), otherwise the port is the Remedy server port.
The following sections describe how to configure the Remedy connection parameters, to change Remedy
incident information and create an incident form from the indirect process.
 Configuring Remedy connection parameters (on page i)
 Remedy incident information configuration (on page i)
 Creating an incident form (on page iii)

Configuring Remedy connection parameters

This procedure describes how to configure Remedy connection parameters.
 To configure Remedy connection parameters:
1. From a command line, type one of the following:
• emremedy_configure (Control-M/EM)
• ctm_remedy_configure (Control-M/Server)
2. Select the appropriate menu items and type the required information.
3. Type s.
Your configuration settings are saved.

Remedy incident information configuration

You can configure the Remedy incident information by accessing the configuration file,
RemedyConfig.XML, which is located as follows:
 emremedy_configure (Control-M/EM): ctm_em/etc/cli/data/REMEDY (UNIX) or <EM
home>\data\REMEDY (Windows)
 ctm_remedy_configure (Control-M/Server): <CTM server home>/data/REMEDY (UNIX) or <CTM
server home>\data\REMEDY (Windows)
The configuration file consists of three sections:
 Connection settings: Enables you to configure the Remedy server connection through either
emremedy_configure or ctm_remedy_configure. For more information, see: Remedy configuration (on
page i).
 Configuration settings: Enables you to configure settings for Remedy server version 6
 Configuration settings: Enables you to configure settings for Remedy server version 7
Each Remedy server version contains action configurations for opening and closing incidents, which
contain the schema or form name as shown in the following table.

Server Action Form

Remedy 7,8,9 Open HPD: IncidentInterface_Create

Close HPD: IncidentInterface

NOTE: Configuration info for Remedy 7 also applies to Remedy 8 and Remedy 9.
An incident form is created either directly (the default process for Remedy 6) or indirectly (the default
process for Remedy 7) by the Remedy server. When the indirect process is used to create an incident
form, the Remedy sever initially creates an intermediate form that contains an ID number that identifies
the real (target) form. The intermediate form must be resolved to obtain the real form ID. To create an
incident form, see: Creating an incident form (on page iii).
When Remedy incidents are created, default values are used for each of the Remedy incident fields.
Each Remedy incident field consists of the following attributes:
 Name - field description
 ID - Remedy field identification number
 Data Type - either a string field (indicated by the number 4) or a selection field (indicated by the
number 6)
 Value - default value used
The Remedy field ID values for additional Remedy fields must be obtained from the Remedy
administrator.
The configuration file contains the following built-in Remedy fields that are automatically populated by
BMC Batch Impact Manager and Control-M/Server.
 Summary
 Note
 Urgency
Creating an incident form
This procedure describes how to create an incident form from the indirect process by the Remedy server.
 To create an incident form:
 Do one of the following:
• For the ResolveRealFormID, specify Yes.
• For the RealFormFieldID, specify a field ID number that will contain the real form ID.
NOTE: The built-in fields are used to resolve the field ID in the Remedy form. When BMC Batch
Manager or Control-M/Server creates an incident, the built-in fields are automatically resolved,
overwriting any values that may have been manually specified. For more information about Remedy
fields and parameters, see the Remedy documentation.