Control-M/EM System Settings Configuration

The following API commands enable you to configure Control-M/EM system parameters and system settings:

config em:param::set (deprecated)

The config em:param::set command enables you to set the value of a Control-M/EM system parameter. Supports only a select group of system parameters. The user can set this value only if they have permissions to that specific environment.

Deprecated as of version 9.0.21.300. Use config systemsettings::set instead.

CLI Syntax

Copy 
ctm config em:param::set <paramName> <value>

The following table describes the config em:param::set command parameters.

Parameter

Description

paramName

The system parameter defined in the Control-M/EM, one of the following supported system parameters:

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
paramName=api_key
value=true
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/em/param/$paramName"

config systemsettings::get

The config systemsettings::get command enables you to get details of general system settings.

The output is returned in JSON format. You can use this output as a template when you use the config systemsettings::set command to set new values for general system settings.

For more information about the available settings and their JSON syntax, see System Settings File and General System Settings.

CLI Syntax

Copy 
ctm config systemsettings::get [-s "server=<serverName>"]

The optional -s swtich can be used to filter by name of server.

REST API Syntax

cURL:

Copy 
server=myServer
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/systemsettings"?server=$serverName

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config systemsettings::set

The config systemsettings::set command enables you too modify general system settings based on definitions that you provide through a JSON file.

You can optionally use this API command to integrate your SAML2 identity provider (IdP) with Control-M to support Single Sign On (SSO) authentication.

For full details about the available system settings and their JSON syntax, as returned by the config systemsettings::get command, see System Settings File and General System Settings.

CLI Syntax

Copy 
ctm config systemsettings::set <systemsetting> [saml2metadatafile] [server]

The following table describes the config systemsettings::set command parameters.

Parameter

Description

systemsetting

Full path and name of a .json payload file that contains details of system settings, as described in System Settings File.

saml2metadatafile

Full path and name of a SAML2 Metadata file, an .xml payload file that contains SAML2 IdP metadata.

To provide the SAML2 IdP metadata through an .xml payload file, ensure that you have set the MetadataUrl property in the .json payload file to metadata.

For information about the steps involved in integrating your SAML2 IdP with Control-M to support Single Sign On (SSO) authentication, see System Settings File.

server

Name of Control-M/Server

REST API Syntax

cURL:

Copy 
serverName=myServer
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -F '[email protected]' "$endpoint/config/systemsettings?server=$serverName

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config systemsettings:identityprovidermetadata::get

The config systemsettings:identityprovidermetadata::get command enables you to get metadata from the SAML2 IdP that you integrated with Control-M. The output is SAML2 metadata in XML format.

For information about the steps involved in integrating your SAML2 IdP with Control-M to support Single Sign On (SSO) authentication (prior to running this API command), see Steps for Enabling a SAML2 IdP.

CLI Syntax

Copy 
ctm config systemsetting:identityprovidermetadata::get

REST API Syntax

cURL:

Copy 
server=myServer
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/systemsettings/identityprovidermetadata"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

System Settings File

The following code sample shows the system settings that you can include within payload JSON files that are involved in the configuration of system settings. Details about each of these system settings are provided below.

Copy 
{
 "saml2IdentityProvider": {
    "metadataUrl": "https://dba-life:8443",
    "enabled": false,
    "serviceProviderInformation": {
      "entityID": "Control-M_appId",
      "ssoUrls": [
        "https://dba-life:8443"
      ]
    },
    "forceAuthentication": true
  },
  "ldapSettings": {
    "ldapEnabled": true,
    "defaultDomain": "prod",
    "domains": [
        {
            "domainName": "prod",
            "directorySearchUser": "[email protected]",
            "directorySearchPassword": "*****",
            "communicationProtocol": "TCP",
            "directoryServerType": "Active Directory",
            "serverHostNameAndPort": [
              {
                "physicalHostname": "prod.bmc.com",
                "port": "1234"
              }
            ],
            "directorySearchBase": ["prod.bmc.com"]
        }
    ]
  },
  "enforceSiteStandards": {
    "value": "true"
  },
  "strictnesslevel": {
    "value": "non-strict"
  },
  "cmsCommMode": {
    "value": "tcp"
  },
  "userAuditAnnotation": {
    "value": "false"
  },
  "additionalParameters": [
    {
      "name": "MaxUserTimeoutSec",
      "value": "10800"
    }
  ]
}

SAML2 Identity Provider Settings

The first element in the JSON list of system settings, Saml2IdentityProvider, focuses on settings for integration of a SAML2 identity provider (IdP) with Control-M.

The following table describes the Saml2IdentityProvider property parameters.

Property

Description

metadataUrl

Points to the location of SAML2 metadata that you obtained from your identity provider.

You can choose from the following options:

  • A URL that points to the metadata.

  • The constant value metadata enables you to provide metadata as an XML payload file through the config systemsettings::set API command.

enabled

Whether the SAML2 IdP is enabled in your environment, either true or false.

After you enable the SAML2 IdP, certain user authorization management actions are no longer relevant and cannot be performed. These include adding, updating, or deleting a user, as well as getting user details.

serviceProviderInformation

Attributes generated by Control-M for enabling integration with a SAML2 IdP.

entityID

An ID that dictates the entity or audience for SAML2 assertions for the internal IdP in Control-M.

You obtain this property value by running the config systemsettings::get API command.

ssoUrls

A list of URLs for single sign-on, where SAML2 assertions are sent by the internal IdP in Control-M.

This property is read-only. You obtain the value of this property by running the config systemsettings::get API command, but you cannot modify its value using the config systemsettings::set API command.

forceAuthentication

Whether to force re-authentication of users even if the user has a SSO session at the IdP, either true or false.

The default is true.

Steps for Enabling a SAML2 IdP

A typical end-to-end process for enabling a SAML2 IdP consists of the following steps:

  1. Obtain values for the two properties that pertain to the internal IdP in Control-M — ssoUrls and entityID — by running the config systemsettings::get API command.

  2. Obtain SAML2 metadata from your SAML2 IdP, either as a URL or as an XML file.

  3. Use the output from Step 1 as a template for creation of a System Settings .json file.

    In the same file, set the metadataUrl property to the relevant value (from step 2) and the enabled property to true.

  4. Run the config systemsettings::set API command and provide the System Settings .json file (that you prepared in step 3) as a payload file for this API command.

    If you set the metadataUrl property in the .json file to metadata, you must also provide a SAML2 Metadata file in XML format.

After completing this setup, if at any point you want to review the SAML2 metadata from your SAML2 IdP, you can run the config systemsettings:identityprovidermetadata::get API command.

LDAP System Settings

Through the JSON file, you can define the LDAP settings used for authentication of users. The following table summarizes and describes the available LDAP system settings properties.

LDAP system settings that you define in the JSON file reflect the final settings (NOT just the changes that you want to apply). If current LDAP settings exist, they are replaced by the LDAP settings in the JSON file when you run the config systemsettings::set API command. For example, if an existing domain or LDAP server is defined and you do not include it in your JSON, the domain or LDAP server is deleted when you run the config systemsettings::set API command.

Property

Description

ldapEnabled

Whether LDAP authentication is enabled, either true or false.

Default: false

If a SAML2 identity provider is enabled, it takes precedence over LDAP user authentication. In such a case, ldapEnabled=true is ignored.

defaultDomain

Name of the default domain.

domains

Details of all the domains that host LDAP servers that authenticate users.

domainName

Name of the domain.

directorySearchUser

Name of the user that runs the search action for users that log on.

For example, [email protected] or cn=admin,dc=company,dc=us,dc=com.

If this property is not defined, then you must specify a value for the directorySearchBase property.

directorySearchPassword

Password of the user that runs the search action (previous property).

If this user does not have a defined password, set this property to an empty value.

communicationProtocol

The transmission protocol that LDAP uses to connect to Control-M, either TCP or SSL.

Default: TCP

directoryServerType

Type of configuration used for authentication by the LDAP server.

Valid values for this property are as specified in the DirectoryServiceType.cfg  configuration file located in the ctm_em/etc directory. For more information, see DirectoryServiceType.cfg Parameters.

serverHostNameAndPort

A list of LDAP server hosts.

Each LDAP server host is defined by the following properties:

  • physicalHostname — Host name of the computer where the LDAP directory server is located.

  • port — Port number for the LDAP directory server. If not specified, the default is 389 for TCP communication or 636 for SSL communication.

directorySearchBase

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 property must have a specified value if the directorySearchUser property is not defined. Otherwise, the default value is the domain where the search user is located.

General System Settings

A variety of general system settings are included in the JSON list.

The following table describes the available parameters:

Property

Description

enforceSiteStandards

Whether to enforce validation of folders based on Site Standards.

Valid Values: true | false

Default: false

strictnesslevel

The level of strictness for folder validation.

Valid Values:

  • non-strict

  • strict

Default: non-strict

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

userAuditAnnotation

Determines whether 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.

Valid Values:

  • 0: Annotations are not required.

  • 1: Annotations are required.

Default: 0

additionalParameters

Lists many additional Control-M/EM system parameters in an array structure. Each system parameter is identified by its API parameter name, along with the parameter value.

For more information about these additional parameters, see Configuring Control-M/EM System Parameters.