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

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

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

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

keyName

A name for the private and public keys.

keyPassphrase

A password for the private key file.

keySize

(Optional) A maximum size for the key, in bits.

Default: 2,048 bits.

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 
server=myInstance
agent=myAgent
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST
"$endpoint/config/server/$server/agent/$agent/mft/ssh/key?keyName=MyKey1&keyPassphrase=123456"

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

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

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

hostName

Name of the SSH host.

port

(Optional) Port number of the SSH host.

Default: 22

REST API Syntax

cURL:

Copy 
server=myInstance
agent=myAgent
hostname=myGreatHost
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/server/$server/agent/$agent/mft/ssh/host/$hostname?port=7999"

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

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

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

clusterName

Name of the SSH cluster.

nodePortDefinitions

Full pathname of a .json payload file that contains node and port definitions for the SSH hosts in the cluster.

Here is an example of the contents of such a Definitions file:

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

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 
server=myInstance
agent=myAgent
clusterName=myGreatCluster
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/server/$server/agent/$agent/mft/ssh/cluster/$clusterName"
--data "nodePortDefinitions.json"

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

PGP Templates

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

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

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

templateName

Name of the PGP template.

pgptemplateData

Full path and name of a .json payload file that contains definitions of the PGP template, as described in PGP Template Data File.

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 
server=myInstance
agent=myAgent
templateName=pgpTemplate1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"
--data "pgptemplateData.json"

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

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.

Besides applying all settings that are explicitly defined in the PGP Template Data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:

  1. Obtain ALL current settings of the template by running the config server:agent:mft:pgptemplates::get command.

  2. Use the current definitions of the relevant template (from the output of the previous step) to create your PGP Template Data file, a .json file.

  3. In the PGP Template Data file, change the specific settings that you want to update, and keep all other content in the file.

    For full details about all template definitions, see PGP Template Data File.

  4. Proceed with running the Update command.

CLI Syntax

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

templateName

Name of the PGP template.

pgptemplateData

Full path and name of a .json payload file that contains definitions of the PGP template, as described in PGP Template Data File.

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 
server=myInstance
agent=myAgent
templateName=pgpTemplate1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"
--data "pgptemplateData.json"

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

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

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

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

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

templateName

Name of the PGP template.

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 
server=myInstance
agent=myAgent
templateName=pgpTemplate1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"

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

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

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

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

-s "name=a*"

REST API Syntax

cURL, one without a filter and one with a filter:

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

curl -H "$AuthHeader" "$endpoint/config/server/$server/agent/$agent/mft/pgptemplates"
                     
curl -H "$AuthHeader" "$endpoint/config/server/$server/agent/$agent/mft/pgptemplates?name=a*"

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

PGP Template Data File

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

Copy 
{ 
  "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.

Property

Description

name

Name of the PGP template, up to 30 characters long.

executableFullPath

Name and location of the executable file for the PGP application.

exitCode

Code of a successful PGP operation.

passphrase

The passphrase that is used to decrypt the file.

recipient

Name of the recipient that is defined in the encrypt command.

encryptionAttributes

PGP command line parameters for encryption.

Within the command line, include the following variables:

  • $$PGP_RECIPIENT$$: Recipient name that is defined the Recipient field. (Optional).

  • $$PGP_INPUT_FILE$$: Name of the file to encrypt.

  • $$PGP_OUTPUT_FILE$$: Name and location of the encrypted file.

    Use the output option of your PGP application together with this variable.

The following command line is an example of a GnuPG encryption command:

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

decryptionAttributes

PGP command line parameters for decryption

Within the command line, you include the following variables:

  • $$PGP_PASSPHRASE$$: The passphrase that is defined in the Passphrase field.

    This optional variable provides additional security, as you do not have to write the passphrase in the PGP command.

  • $$PGP_INPUT_FILE$$: Name of the file to encrypt (required).

  • $$PGP_OUTPUT_FILE$$: Name and location of the encrypted file (required).

    Use the output option of your PGP application together with this variable.

The following command line is an example of a GnuPG decryption command:

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

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

CLI Syntax

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

templateName

Name of the z/OS template.

zosTemplateData

Full path and name of a .json payload file that contains definitions of the z/OS template, as described in z/OS Template Data File.

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 
server=myInstance
agent=myAgent
templateName=zosTemplate1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"
--data "zosTemplateData.json"

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

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.

Besides applying all settings that are explicitly defined in the z/OS Template Data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:

  1. Obtain ALL current settings of the template by running the config server:agent:mft:zostemplates::get command.

  2. Use the current definitions of the relevant template (from the output of the previous step) to create your z/OS Template Data file, a .json file.

  3. In the z/OS Template Data file, change the specific settings that you want to update, and keep all other content in the file.

    For full details about all template definitions, see z/OS Template Data File.

  4. Proceed with running the Update command.

CLI Syntax

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

templateName

Name of the z/OS template.

zosTemplateData

Full path and name of a .json payload file that contains definitions of the z/OS template, as described in z/OS Template Data File.

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 
server=myInstance
agent=myAgent
templateName=zosTemplate1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"
--data "zosTemplateData.json"

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

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

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

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

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

templateName

Name of the z/OS template.

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 
server=myInstance
agent=myAgent
templateName=zosTemplate1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"

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

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

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

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

-s "name=a*"

REST API Syntax

cURL, one without a filter and one with a filter:

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

curl -H "$AuthHeader" "$endpoint/config/server/$server/agent/$agent/mft/zostemplates"
                     
curl -H "$AuthHeader" "$endpoint/config/server/$server/agent/$agent/mft/zostemplates?name=a*"

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

z/OS Template Data File

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

Copy 
{ 
  "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:

Property

Description

name

Name of the z/OS template.

The first character cannot be an integer.

recordFormat

Value for the record format.

logicalRecordLength

Logical record length, values between 0–32,760.

blockSize

Block size values between 0–32,760.

translationTable

The name of the table used by the FTP server during transfer for translation, up to 8 characters.

transferMode

Mode of file transfer:

  • 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 z/OS to z/OS.

smsManagmentClass

The SMS Management Class assigned to a new data set.

allocationUnits

Type of allocation unit used for the transfer.

volume

Volume value, up to 6 characters.

unit

Unit value, up to 8 characters.

primaryAllocation

Primary allocation amount, between 1–16,777,215.

secondaryAllocation

Secondary allocation amount, between 1–16,777,215.

smsDataClass

The SMS Data Class provided by your organization for the FTP server.

dbcsEncoding

The double-byte character set (DBCS) to use for the transfer.

transferToUniqueFile

Whether to create a file with a unique name on the remote system instead of overwriting an existing file.

Values: true | false

additionalOptionsHost1

Two optional properties for additional FTP Server SITE command sub-parameters and values.

Allowed values for these properties are up to 214 characters.

additionalOptionsHost2

MFT Configuration

The following API commands are available for the management of 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

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

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

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

REST API Syntax

cURL:

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

curl -H "$AuthHeader" "$endpoint/config/server/$server/agent/$agent/mft/configuration"

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

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.

In your MFT Configuration Data file, you can choose to include only those properties that you want to update. Any MFT settings that are not included in your MFT Configuration Data file are not updated and remain untouched.

For full details about all MFT configurtion settings, as returned by the config server:agent:mft:configuration::get command, see MFT Configuration Data File.

CLI Syntax

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

mftConfigurationData

Full path and name of a .json payload file that contains MFT configuration details, as described in MFT Configuration Data File.

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 
server=myInstance
agent=myAgent
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/configuration"
--data "mftConfigurationData.json"

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

MFT Configuration Data File

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

Copy 
{ 
  "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.

Property

Description

connectionTimeoutInSeconds

The number of seconds to allow for establishing a connection with an FTP server before timing out.

Default: 30

connectionRetries

The number of times to try to connect after failing to connect with an FTP server.

If the remote FTP server runs on a z/OS system, this parameter has no effect.

Valid values: 0–99

Default: 5

connectionTimeBetweenRetriesInSeconds

The number of seconds between attempts to connect to an FTP server.

Default: 6

debugLevel

Debug level of Control-M MFT.

Valid values range from 0 to 4, where 0 indicates no diagnostic activity, and 4 indicates the highest level of diagnostic functionality.

Default: 0

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.

pgpTempDir

A temporary location where PGP files are stored.

Users defined in the relevant connection profile must have read and write permissions for this temporary directory.

Default: <Control-M/Agent_Home_Dir>\cm\AFT\pgp_tmp

sslDebugTrace

Whether to run SSL diagnostics in Control-M MFT.

Values are either true or false. The default is false.

pamAuthentication

Whether to authenticate the local host with PAM-based authentication (Solaris, HP-UX, and Linux computers only).

Values are either true or false. The default is false.

proxyIsInUse

Whether to transfer files through a Web Proxy server (available for FTP, FTPS, SFTP, and S3)

Values are either true or false. The default is false.

proxyHost

Host name of the proxy server.

proxyPort

Port number of the proxy server.

proxyUser

User name for the connection to the proxy server.

proxyPassword

Password for the proxy server user.

fileWatcherSearchInterval

The number of seconds between successive attempts to detect the existence of a file and between attempts to monitor the size of a detected file.

Valid Values: 1–9,999

Default: 30

fileWatcherStaticIterations

Numbers of attempts to monitor the file size when it is static after it has reached its minimum detected size.

Valid Values: 1–999

Default: 3

fileWatcherCheckFileIsInUse

Whether to check that the file is not being used by another process or application on a local host.

Valid Values: true | false

Default: false.

fileActionsRetriesIntervalInSeconds

Number of seconds to wait before attempting to perform a post action on the source or destination file after a successful transfer.

Valid Values: 1–9,999

Default: 5

fileActionsRetriesNum

Number of times to retry a post action on the source or destination file after a successful transfer.

Valid Values: 1–999

Default: 3

File Transfer Server (FTS) Settings

The following API commands are available for the management of 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

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

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

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

REST API Syntax

cURL:

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

curl -H "$AuthHeader" "$endpoint/config/server/$server/agent/$agent/mft/fts/settings"

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

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.

In your FTS Settings Data file, you can choose to include only those properties that you want to update. Any FTS settings that are not included in your FTS Settings Data file are not updated and remain untouched.

For full details about all FTS settings, as returned by the config server:agent:mft:fts:settings::get command, see FTS Settings Data File.

CLI Syntax

Copy 
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.

Parameter

Description

server

Name of the instance.

agent

Name of host or alias of the Agent.

ftsSettingsData

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

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 
server=myInstance
agent=myAgent
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/fts/settings"
--data "ftsSettingsData.json"

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

FTS Settings Data File

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

Copy 
{
   "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

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

Property

Description

homeDirectory

Root path where transferred files are stored.

If you want to use a different directory for each logged in user, you must add \${userName} to the path.

multipleLoginAllowed

Whether multiple users can connect to the File Transfer Server simultaneously via FTP.

maxOpenSessions

The number of users that can connect to the File Transfer Server simultaneously via FTP.

maxLoginFailures

The maximum number of login attempts that are allowed via FTP before no more logins are allowed for the period of time defined by the delayAfterLoginFailure property.

delayAfterLoginFailure

The number of seconds to wait after a login failure via FTP before the next attempt.

throttlingActivated

Whether to limit number of simultaneous uploads and downloads.

maxSimultaniousUploads

Maximum number of simultaneous uploads.

maxSimultaniousDownloads

Maximum number of simultaneous downloads.
FTP Settings

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

Property

Description

serverEnabled

Whether the File Transfer Server that supports client connection via FTP/FTPS is enabled.

port

Number of the port to which the File Transfer Server listens for FTP/FTPS connections.

Default: 1221

authenticationMethod

Method of authentication of FTP users, one of the following:

  • PAM (on UNIX).

  • LOCAL (Windows local user).

  • LDAP

secured

Whether FTPS is enabled.

keystoreFilePath

Path to the file that contains the server certificate .

The keystore must be in PKCS#12 format. If FIPS is enabled, the format must be BCFKS.

keystoreFilePassword

Password of the file that contains the server certificate.

ciphers

A comma-separated list of names of ciphers that are used for FTPS.

If no ciphers are specified, all available ciphers are supported.

listenForImplicitConnection

Whether to automatically turn on security after a connection is established between the FTPS client and the Managed File Transfer server.

passivePorts

A list of dynamic ports to which to limit passive connections in FTP.

The list of ports can include single ports, as well as closed or open ranges (indicated with a dash). Multiple definitions are separated by commas.
SFTP Settings

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

Property

Description

serverEnabled

Whether the File Transfer Server that supports client connection via SFTP is enabled.

port

Number of the port to which the File Transfer Server listens for SFTP connections.

Default: 1,222

authenticationMethod

Method of authentication of SFTP users, one of the following:

  • PAM (on UNIX).

  • LOCAL (Windows local user).

  • LDAP

keystoreFilePath

Path to the file that contains the server certificate.

The keystore must be in PKCS#12 format. If FIPS is enabled, the format must be BCFKS.

keystoreFilePassword

Password of the file that contains the server certificate.

ciphers

A comma-separated list of names of ciphers that are used for SFTP.

knownUsersFilePath

The path to the file that contains known users by SFTP.

overriddenUsersHomeDirectories

A list of internal users that can override their specific home directory to connect to the FTS/Hub with SFTP.

Under this property, specify pairs of userName and homeDirectory properties.

Note that the home directory can be a network path in the UNC format.
Authentication Details

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

Property

Description

LDAP authentication details (under "ldapAuthenticationDetails")

searchUserName

Name of the LDAP Browse user.

searchUserPassword

Password of the LDAP Browse user.

serverUrl

The URL address and (optionally) port of a directory server, in the following format:

ldap(s)://<server>:<port>

baseDn

The point from where the server will search for users.

ou=sales,dc=company,dc=us,dc=com

usernameAttributeName

The name of the LDAP attribute that determines the username.

dnAttributeName

The name of the LDAP attribute that determines the user DN (Distinguished Name).

connectionTimeout

The number of milliseconds to wait before a timeout.

Default: 30,000

PAM authentication details (under "pamAuthenticationDetails")

serviceName

The name of the PAM service.