Control-M Managed File Transfer (MFT) Configuration

The config server agent mft service enables you to manage the setup of your integration with Control-M Managed File Transfer (MFT) and enable file transfers to, from, and between remote hosts.

You can use API commands to configure the following areas and entities in Control-M MFT:

• SSH Settings

• PGP Templates

• z/OS Templates

• MFT Configuration

• File Transfer Server (FTS) Settings

SSH Settings

The following API commands are available for the configuration of SSH Settings in Control-M MFT:

• config server:agent:mft:ssh:key::generate: Generate SSH keys.

• config server:agent:mft:ssh:host::authorize: Authorize an SSH host.

• config server:agent:mft:ssh:cluster::authorize: Authorize an SSH cluster.

config server:agent:mft:ssh:key::generate

The config server:agent:mft:ssh:key::generate command enables you to generate an SSH key pair (private and public keys) in the MFT client and returns the public key. This 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.

CLI Syntax

ctm config server:agent:mft:ssh:key::generate <server> <agent> <keyName> <keyPassphrase> [keySize]

The following table describes the config server:agent:mft:ssh:key::generate command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
curl -H "x-api-key: $token" -X POST
"$endpoint/config/server/$server/agent/$agent/mft/ssh/key?keyName=MyKey1&keyPassphrase=123456"

config server:agent:mft:ssh:host::authorize

The config server:agent:mft:ssh:host::authorize command enables you to authorize an SSH host by adding or updating its fingerprint in the local known_hosts file.

CLI Syntax

ctm config server:agent:mft:ssh:host::authorize <server> <agent> <hostname> [port]

The following table describes the config server:agent:mft:ssh:host::authorize command parameters.

REST API Syntax

server=myInstance
agent=myAgent
hostname=myGreatHost
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/ssh/host/$hostname?port=7999"

config server:agent:mft:ssh:cluster::authorize

The config server:agent:mft:ssh:cluster::authorize command enables you to authorize an SSH cluster by adding or updating fingerprints for its nodes in the local known_hosts file.

CLI Syntax

ctm config server:agent:mft:ssh:cluster::authorize <server> <agent> <clusterName> -f nodePortDefinitions.json

The following table describes the config server:agent:mft:ssh:cluster::authorize command parameters.

{
   "hostList" : [  
   {
      "physicalHostname": "host1", "port": "22"
   },  
   {   
      "physicalHostname": "host2", "port": "1222"
   }]
}

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

REST API Syntax

server=myInstance
agent=myAgent
clusterName=myGreatCluster
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/ssh/cluster/$clusterName"
--data "nodePortDefinitions.json"

PGP Templates

The following API commands are available for the configuration of PGP templates in Control-M MFT:

• config server:agent:mft:pgptemplate::add: Add a PGP template.

• config server:agent:mft:pgptemplate::update: Update a PGP template.

• config server:agent:mft:pgptemplate::delete: Delete a PGP template.

• config server:agent:mft:pgptemplates::get: Retrieve details of PGP templates.

config server:agent:mft:pgptemplate::add

The config server:agent:mft:pgptemplate::add command enables you to create a new PGP template, which enables you to define PGP commands for file transfers. PGP commands enable you to use PGP applications to encrypt files on a local computer before a transfer and decrypt files on a local computer after a transfer.

CLI Syntax

ctm config server:agent:mft:pgptemplate::add <server> <agent> <templateName> -f pgptemplateData.json

The following table describes the config server:agent:mft:pgptemplate::add command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
templateName=pgpTemplate1
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"
--data "pgptemplateData.json"

config server:agent:mft:pgptemplate::update

The config server:agent:mft:pgptemplate::update command enables you to update an existing PGP template based on template definitions that you provide through a .json file. PGP templates enables you to define PGP commands for encyrption and dycription of files involved in file transfers.

CLI Syntax

ctm config server:agent:mft:pgptemplate::update <server> <agent> <templateName> -f pgptemplateData.json

The following table describes the config server:agent:mft:pgptemplate::update command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
templateName=pgpTemplate1
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"
--data "pgptemplateData.json"

config server:agent:mft:pgptemplate::delete

The config server:agent:mft:pgptemplate::delete command enables you to delete an existing PGP template in Control-M MFT.

CLI Syntax

ctm config server:agent:mft:pgptemplate::delete <server> <agent> <templateName>

The following table describes the config server:agent:mft:pgptemplate::delete command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
templateName=pgpTemplate1
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"

config server:agent:mft:pgptemplates::get

The config server:agent:mft:pgptemplates::get command enables you to get the details of defined PGP templates in Control-M MFT.

The output is returned in JSON format. You can use this output as the starting point for creating your own PGP Template Data files when creating new PGP templates or editing existing PGP templates. For more information about the syntax of definitions, see PGP Template Data File.

CLI Syntax

ctm config server:agent:mft:pgptemplates::get <server> <agent> [-s "name=<pattern>"]

The following table describes the config server:agent:mft:pgptemplates::get command parameters.

In addition, the optional -s runs a search and filters the output based on template name. For multiple values, use wildcards (* or ?) or commas.

REST API Syntax

curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/pgptemplates"
                     
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/pgptemplates?name=a*"

PGP Template Data File

The following code sample demonstrates PGP template definitions in a JSON file:

{ 
  "name": "template1",
  "executableFullPath": "/home/dbauser/bin",
  "exitCode": 0,
  "passphrase": "passphrase/KEEP_EXISTING",
  "recipient": "moshe",
  "encryptionAttributes": "-e $$PGP_INPUT_FILE$$ ...",
  "decryptionAttributes": "-d $$PGP_INPUT_FILE$$ ..."
} 

The following table describes PGP Template Data File properties for each template.

-e -r $$PGP_RECIPIENT$$ -o $$PGP_OUTPUT_FILE$$ $$PGP_INPUT_FILE$$

-d --batch --passphrase $$PGP_PASSPHRASE$$ -o $$PGP_OUTPUT_FILE$$ $$PGP_INPUT_FILE$$

z/OS Templates

The following API commands are available for the configuration of z/OS templates in Control-M MFT:

• config server:agent:mft:zostemplate::add: Add a z/OS template.

• config server:agent:mft:zostemplate::update: Update a z/OS template.

• config server:agent:mft:zostemplate::delete: Delete a z/OS template.

• config server:agent:mft:zostemplates::get: Retrieve details of z/OS templates.

config server:agent:mft:zostemplate::add

The config server:agent:mft:zostemplate::add command enables you to create a new z/OS template for z/OS file transfers.

CLI Syntax

ctm config server:agent:mft:zostemplate::add <server> <agent> <templateName> -f zosTemplateData.json

The following table describes the config server:agent:mft:zostemplate::add command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
templateName=zosTemplate1
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"
--data "zosTemplateData.json"

config server:agent:mft:zostemplate::update

The config server:agent:mft:zostemplate::update command enables you to update an existing z/OS template based on template definitions that you provide through a .json file. z/OS templates are used for z/OS file transfers.

CLI Syntax

ctm config server:agent:mft:zostemplate::update <server> <agent> <templateName> -f zosTemplateData.json

The following table describes the config server:agent:mft:zostemplate::update command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
templateName=zosTemplate1
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"
--data "zosTemplateData.json"

config server:agent:mft:zostemplate::delete

The config server:agent:mft:zostemplate::delete command enables you to delete an existing z/OS template in Control-M MFT.

CLI Syntax

ctm config server:agent:mft:zostemplate::delete <server> <agent> <templateName>

The following table describes the config server:agent:mft:zostemplate::delete command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
templateName=zosTemplate1
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"

config server:agent:mft:zostemplates::get

The config server:agent:mft:zostemplates::get command enables you to get the details of defined z/OS templates in Control-M MFT.

The output is returned in JSON format. You can use this output as the starting point for creating your own z/OS Template Data files when creating new z/OS templates or editing existing z/OS templates. For more information about the syntax of definitions, see z/OS Template Data File.

CLI Syntax

ctm config server:agent:mft:zostemplates::get <server> <agent> [-s "name=<pattern>"]

The following table describes the config server:agent:mft:zostemplates::get command parameters.

In addition, the optional -s runs a search and filters the output based on template name. For multiple values, use wildcards (* or ?) or commas.

REST API Syntax

curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/zostemplates"
                     
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/zostemplates?name=a*"

z/OS Template Data File

The following code sample demonstrates z/OS template definitions in a JSON file:

{ 
  "name": "ZOS_template1",
  "recordFormat": "Fixed",
  "logicalRecordLength": 1000,
  "blockSize": 1200,
  "translationTable": "BELGIAN",
  "transferMode": "Block",
  "smsManagmentClass": "A",
  "allocationUnits" : "TRACKS",
  "volume" : "asdsa",
  "unit" : "aaa",
  "primaryAllocation" : 123,
  "secondaryAllocation" : 444,
  "smsDataClass" : "asdsa",
  "dbcsEncoding" : "Hangeul",
  "transferToUniqueFile" : true,
  "additionalOptionsHost1" : "",
  "additionalOptionsHost2" : ""
} 

The following tables describes the z/OS Template Data file properties for each template:

MFT Configuration

The following API commands are available for the management of MFT configuration:

• config server:agent:mft:configuration::get: Retrieve details of MFT configuration.

• config server:agent:mft:configuration::update: Update MFT configuration.

config server:agent:mft:configuration::get

The config server:agent:mft:configuration::get command enables you to get the details of the MFT configuration.

The output is returned in JSON format. You can use this output as the starting point for updating MFT configuration. For more information about the various details returned in the output JSON, see MFT Configuration Data File.

CLI Syntax

ctm config server:agent:mft:configuration::get <server> <agent>

The following table describes the config server:agent:mft:configuration::get command parameters.

REST API Syntax

curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/configuration"

config server:agent:mft:configuration::update

The config server:agent:mft:configuration::update command enables you to update the MFT configuration properties based on configuration that you provide through a .json file.

CLI Syntax

ctm config server:agent:mft:configuration::update <server> <agent> -f mftConfigurationData.json

The following table describes the config server:agent:mft:configuration::update command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/configuration"
--data "mftConfigurationData.json"

MFT Configuration Data File

The following code sample demonstrates MFT configuration data in a JSON file:

{ 
  "connectionTimeoutInSeconds": 30,
  "connectionRetries": 5,
  "connectionTimeBetweenRetriesInSeconds": 6,
  "debugLevel": 1,
  "pgpTempDir": "C:\\temp",
  "sslDebugTrace": false,
  "pamAuthentication": false,
  "proxyIsInUse" : false,
  "proxyHost" : "host1234",
  "proxyPort" : 1456,
  "proxyUser" : "user1",
  "proxyPassword" : "passphrase/KEEP_EXISTING",
  "fileWatcherSearchInterval" : 30,
  "fileWatcherStaticIterations" : 3,
  "fileWatcherCheckFileIsInUse" : false,
  "fileActionsRetriesIntervalInSeconds" : 5,
  "fileActionsRetriesNum" : 3
}

The following table describes the MFT Configuration Data file properties.

File Transfer Server (FTS) Settings

The following API commands are available for the management of FTS settings:

• config server:agent:mft:fts:settings::get: Retrieve details of FTS settings.

• config server:agent:mft:fts:settings::update: Update FTS settings.

config server:agent:mft:fts:settings::get

The config server:agent:mft:fts:settings::get command enables you to get the details of the File Transfer Server (FTS) settings. FTS settings contain configuration data of FTP/SFTP servers, FTS general settings, and authentication details.

The output is returned in JSON format. For more information about the various details returned in the output JSON, see FTS Settings Data File.

CLI Syntax

ctm config server:agent:mft:fts:settings::get <server> <agent>

The following table describes the config server:agent:mft:fts:settings::get command parameters.

REST API Syntax

curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/fts/settings"

config server:agent:mft:fts:settings::update

The config server:agent:mft:fts:settings::update command enables you to update the FTS settings based on configuration that you provide through a .json file.

CLI Syntax

ctm config server:agent:mft:fts:settings::update <server> <agent> -f ftsSettingsData.json

The following table describes the config server:agent:mft:fts:settings::update command parameters.

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

REST API Syntax

server=myInstance
agent=myAgent
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/fts/settings"
--data "ftsSettingsData.json"

FTS Settings Data File

The following code sample demonstrates FTS settings in a JSON file:

{
   "generalSettings": {
      "homeDirectory": "${CM}/ftshome/${userName}",
      "multipleLoginAllowed": true,
      "maxOpenSessions": 10,
      "maxLoginFailures": 3,
      "delayAfterLoginFailure": 300,
      "throttlingActivated": false,
      "maxSimultaniousUploads": 10,
      "maxSimultaniousDownloads": 10
   },
   "ftpSettings": {
      "serverEnabled": true,
      "port": 1221,
      "authenticationMethod": "PAM",
      "secured": true,
      "keystoreFilePath": "${CM}/data/SSL/cert/ftskeystore.pfx",
      "keystoreFilePassword": "567uiturteerwtrewtrerwere",
      "ciphers": "",
      "listenForImplicitConnection": false,
      "passivePorts": ""
   },
   "sftpSettings": {
      "serverEnabled": true,
      "port": 1222,
      "authenticationMethod": "PAM",
      "keystoreFilePath": "${CM}/AFT/data/Keys/keystore.pfx",
      "keystoreFilePassword": "tyutuyt7987987979879=",
      "ciphers": "AES128CBC,AES256CBC,ARCFOUR128,ARCFOUR256,TripleDESCBC",
      "knownUsersFilePath": "${CM}/AFT/data/authorized_keys",
      "overriddenUsersHomeDirectories": [
         {
            "userName": "user1",
            "homeDirectory": "${cm.home}/ftshome/home1"
         },
         {
            "userName": "user2",
            "homeDirectory": "${cm.home}/ftshome/home2"
         },
         {
            "userName": "user3",
            "homeDirectory": "${cm.home}/ftshome/home3"
         }
      ]
   },
   "authenticationDetails": {
      "ldapAuthenticationDetails": {
         "searchUserName": "CN=user1 name,ou=sales,dc=company,dc=us,dc=com",
         "searchUserPassword": "UYTUYTUytuyt9879879=",
         "serverUrl": "ldap://vw-tlv-ctm-qa98.bmc.com",
         "baseDn": "ou=sales,dc=company,dc=us,dc=com",
         "usernameAttributeName": "sAMAccountName",
         "dnAttributeName": "distinguishedName",
         "connectionTimeout": 30000
   },
      "pamAuthenticationDetails": {
         "serviceName": "passwd"
      }
   }
}

FTS Settings Data File Properties

The FTS Settings Data file contains the following properties:

• General Settings.

• FTP Settings.

• SFTP Settings.

• Authentication Details.

General Settings

The following table describes the general settings properties in the FTS Settings Data file.

FTP Settings

The following table describes the FTP settings properties in the FTS Settings Data file.

SFTP Settings

The following table describes the SFTP settings properties in the FTS Settings Data file.

Authentication Details

The following table describes the FTP Authentication details properties in the FTS Settings Data file.