SFTP/FTP/FTPS Client

The SFTP/FTP/FTPS Client executor moves or removes a file on an SFTP/FTP/FTPS server each time it receives an event. You cannot perform multiple tasks in the same executor. To perform more than one task, use additional executors. For information about supported versions, see Supported Systems and Versions in the Data Collector documentation.

Use the SFTP/FTP/FTPS Client executor as part of an event stream. You can use the executor in any logical way, such as moving a file after receiving a file-processed event from the SFTP/FTP/FTPS Client origin or a file-closure event from the SFTP/FTP/FTPS Client destination.

When you configure the SFTP/FTP/FTPS Client executor, you specify the protocol to use and the URL of the server to connect to. You can also use a connection to configure the executor.

You specify the task to perform. When deleting a file, you specify the file path of the file to delete. When moving a file, you specify both the file path and the target directory.

When needed, you can connect to the server through an HTTP or SOCKS proxy.

If the server requires authentication, configure the credentials for the protocol you are using. For the SFTP protocol, the executor can require that the server be listed in a known hosts file. For the FTPS protocol, the executor can authenticate with the server using a client certificate and can authenticate the certificate from the FTPS server.

For a solution that describes how an executor can move output files after they are written, see Managing Output Files.

Credentials

The SFTP/FTP/FTPS Client executor can use several methods to authenticate with the remote server. From the Credentials tab, configure the authentication required by the remote server.

Authentication options differ for each protocol:

For all protocols, select an authentication method to log in to the remote server. Choose the method based on the protocol and remote server requirements:
- None - The stage does not authenticate with the server.
- Password - The stage authenticates with the server using a user name and password. You must specify the user name and password.
- Private key - The stage authenticates using a private key. Use only with the SFTP protocol. You must specify the private key, either in a local file or in plain text.
For the SFTP protocol, the stage can require that the server be listed in a known hosts file. You must specify the path to the known hosts file that contains the host keys for the approved SFTP servers.
For the FTPS protocol, the stage can use certificates to authenticate with the server. You must specify the keystore file and password. You can also configure the stage to authenticate the server by specifying a truststore provider. For more information about keystores and truststores, see Keystore and Truststore Configuration.

Configuring an SFTP/FTP/FTPS Client Executor

Configure an SFTP/FTP/FTPS Client executor to move or delete a file on an SFTP, FTP, or FTPS server upon receiving an event.

In the Properties panel, on the General tab, configure the following properties:


General Property	Description
Name	Stage name.
Description	Optional description.
Required Fields	Fields that must include data for the record to be passed into the stage. Tip: You might include fields that the stage uses. Records that do not include all required fields are processed based on the error handling configured for the pipeline.
Preconditions	Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions. Records that do not meet all preconditions are processed based on the error handling configured for the stage.
On Record Error	Error record handling for the stage: Discard - Discards the record. Send to Error - Sends the record to the pipeline for error handling. Stop Pipeline - Stops the pipeline.

On the SFTP/FTP/FTPS tab, configure the following properties:


SFTP/FTP/FTPS Property	Description
Connection	Connection that defines the information required to connect to an external system. To connect to an external system, you can select a connection that contains the details, or you can directly enter the details in the pipeline. When you select a connection, Control Hub hides other properties so that you cannot directly enter connection details in the pipeline.
Resource URL	URL to access the remote server. Use the appropriate format: SFTP protocol: `sftp://<host name>:<port number>/<path>` FTP protocol: `ftp://<host name>:<port number>/<path>` FTPS protocol: `ftps://<host name>:<port number>/<path>` You can omit the port number from the URL if the server uses the standard port number: 22 for SFTP, or 21 for FTP or FTPS. You can optionally include the user name to log in to the SFTP, FTP, or FTPS server in the URL. For example, for the FTP protocol, you can use the following format: `ftp://<user name>:<password>@<host name>/<path>`. You can enter an email address as a user name. Note: If you enter a user name in the resource URL and configure password or private key authentication on the Credentials tab, the value entered in the URL takes precedence.
Protocol	Protocol to use to connect to the server: SFTP FTP FTPS
Enable Proxy	Enables using a proxy to connect to the remote server.
Proxy Type	Type of proxy to use: HTTP or SOCKS.
Proxy URL	URL of the proxy.
Path Relative to User Home Directory	Interprets the path entered in the resource URL as relative to the home directory of the user that logs in to the remote server. You specify the user name in the URL or when you configure password or private key authentication on the Credentials tab.
FTPS Mode	Encryption negotiation mode to use for the FTPS protocol: Implicit - Uses encryption immediately. Explicit - Uses plain FTP to connect to the server and then negotiates encryption with the server.
FTPS Data Channel Protection Level	Protection level to use for the FTPS data channel: Clear - Encrypts only communication with the server, not data sent to the server. Private - Encrypts both communication with the server and data sent to the server.
Socket Timeout	Maximum number of seconds to allow between TCP packets. 0 indicates no limit.
Connection Timeout	Maximum number of seconds to allow to initiate a connection to the SFTP, FTP, or FTPS server. 0 indicates no limit.
Data Timeout	Maximum number of seconds allowed to modify a file. 0 indicates no limit.
Maximum Connection Inactivity Time	Maximum seconds of inactivity to allow before recreating connections to the SFTP, FTP, or FTPS server. 0 indicates no limit.

On the Credentials tab, configure the following properties:


Credentials Property	Description
Authentication	Authentication method to use to log in to the remote server: None - Does not authenticate with remote server. Password - Authenticates with the remote server using a user name and password. Private key - Authenticates with an SFTP server using a private key. Default is None.
Username	User name to log in to the remote server. Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation. Available when using password or private key authentication.
Password	Password to log in to the remote server. Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation. Available when using password authentication.
Private Key Provider	Source that provides the private key: File - Reads the private key from a local file. Plain-Text - Reads the private key from a plain-text field. Available when using private key authentication.
Private Key File	Full path to the local private key file used to log in to the remote server. Available when using private key authentication with a file private key provider.
Private Key	Private key used to log in to the remote server. Available when using private key authentication and providing a plain text private key.
Private Key Passphrase	Passphrase used to open the private key. Available when using private key authentication and providing a plain text private key.
Use Client Certificate for FTPS	Authenticates with the FTPS server using a client certificate. Select this option when the FTPS server requires mutual authentication. You must provide a keystore file that contains the client certificate. Available when using FTPS.
Use Remote Keystore	Enables loading the contents of the keystore from a remote credential store or from values entered in the stage properties. Available when using a client certificate for FTPS.
Private Key	Private key used in the remote keystore. Enter a credential function that returns the key or enter the contents of the key. For more information, see credential functions. Available when using a client certificate for FTPS.
Certificate Chain	Each PEM certificate used in the remote keystore. Enter a credential function that returns the certificate or enter the contents of the certificate. Using simple or bulk edit mode, click the Add icon to add additional certificates. Available when using a client certificate for FTPS.
FTPS Client Certificate Keystore File	Full path to the keystore file that contains the client certificate. Available when using a client certificate for FTPS.
FTPS Client Certificate Keystore Type	Type of keystore file that contains the client certificate. Available when using a client certificate for FTPS.
FTPS Client Certificate Keystore Password	Password to the keystore file that contains the client certificate. A password is optional, but recommended. Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation. Available when using a client certificate for FTPS.
FTPS Truststore Provider	Method that the destination uses to authenticate the certificate from the FTPS server: Allow All - Allows any certificate, skipping authentication. File - Authenticates certificate with a specified truststore file. Remote Truststore - Authenticates certificate with a truststore file built from specified certificates. For more information, see Remote Keystore and Truststore. JVM Default - Authenticates certificate with the JVM default truststore. Available when using FTPS.
Trusted Certificates	Each PEM certificate used in the remote truststore. Enter a credential function that returns the certificate or enter the contents of the certificate. For more information, see credential functions. Using simple or bulk edit mode, click the Add icon to add additional certificates. Available when using a remote truststore as the FTPS truststore provider.
FTPS Truststore File	Full path to the truststore file that contains the server certificate. Available when using a file as the FTPS truststore provider.
FTPS Truststore Type	Type of truststore: Java Keystore file (JKS) PKCS-12 (p12 file) Available when using a file as the FTPS truststore provider.
FTPS Truststore Password	Password to the truststore file. A password is optional, but recommended. Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation. Available when using a file as the FTPS truststore provider.
Strict Host Checking	Requires that the SFTP server is listed in the known hosts file. When enabled, the destination connects to the server only if the server is listed in the known hosts file. Requires the known hosts file to include an RSA key. Available when using SFTP.
Known Hosts File	Full path to the local known hosts file. Required if strict host checking is selected. Available when using strict host checking.

On the Task tab. configure the following properties:


Task Property	Description
File Name Expression	Expression that specifies the location of the file to act upon. The default, `${record:value('/filepath')}`, performs a task on the file specified in the `filepath` field of the event record.
Task	Task to perform: Delete File - Removes the file from the server. Move File - Moves the file to the specified location.
Target Directory	Directory to move the file to. Enter a directory relative to the SFTP/FTP/FTPS root directory of the user specified on the Credentials tab. Available only when moving files.
File Exists Action	Action to take when a file of the same name already exists in the specified target directory: Overwrite - Overwrites the existing file. Send to Error - Handles the records in the file based on the configured stage error handling. Available only when moving files.