SFTP Connector

The SFTP Connector implements a secure file transport channel so that your Mule application can exchange files with external resources. SFTP uses the SSH security protocol to transfer messages. You can implement the SFTP endpoint as an inbound endpoint with a one-way exchange pattern, or as an outbound endpoint configured for either a one-way or request-response exchange pattern. Mule uses the JCraft library for SFTP SSH.

Notes:

Mule 3.8 and newer accepts SSH known_hosts files. For more information, see the SFTP Transport Reference.
Mule 3.7 and newer supports SFTP retries.

Compatibility

Following the release of Mule 3.8.5, the SFTP Connector can connect via a proxy. The SFTP Connector supports connections through a proxy from Mule Runtime 3.8.5 and higher. For older versions of the product, a patch may be requested to achieve this configuration.

The following properties can be set in the Environment to support a proxy configuration:

mule.sftp.proxy.host
mule.sftp.proxy.port
mule.sftp.proxy.protocol (can be: HTTP, SOCKS4 or SOCKS5)
mule.sftp.proxy.username (if required)
mule.sftp.proxy.password (if required)

To Install this Connector

In Anypoint Studio, click the Exchange icon in the Studio taskbar.
Click Login in Anypoint Exchange.
Search for the connector and click Install.
Follow the prompts to install the connector.

When Studio has an update, a message displays in the lower right corner, which you can click to install the update.

Configuration

SFTP endpoint configuration consists of two stages:

Decide where you want to place the SFTP endpoint within your Mule flow, then drag it from the Palette to the appropriate place in the sequence of processors that make up your Mule flow.
1. If you place the SFTP endpoint at the beginning of the flow, it acts as an inbound endpoint (a message source), triggering the flow whenever it receives a message. (You can also use the Composite Source scope to wrap the SFTP endpoint along with other, similar endpoints (such as File or UDP) so that your flow can receive files through multiple transport channels).
2. If you place the SFTP processor in the middle or at the end of the flow, it serves as an outbound endpoint, passing information out of the flow to external resources.

SFTP Inbound Endpoints can only be set to a one-way exchange pattern. SFTP Outbound Endpoints can be set to either a one-way or request-response exchange pattern. . Configure the SFTP endpoint by providing values for the fields on the various tabs on the properties editor, which you open by clicking the SFTP icon on the Message Flow canvas.

General Tab

Field Description

Field	Description
Display Name	Defaults to the generic endpoint name, which in this case is SFTP. Change the display name, which must be alpha-numeric, to reflect the endpoint’s specific role, for example, `File Retrieval Endpoint.`
Exchange Pattern	If set to one-way, an SFTP inbound or outbound endpoint sends the incoming message to the next processor in the flow. If an SFTP outbound endpoint is set to request-response (the SFTP inbound endpoint cannot be set to request-response), that outbound endpoint waits for a response before sending the message. One-way is the default for both the inbound and outbound SFTP endpoints.
Connector Configuration	Use the dropdown list to select a previously configured connector configuration for this endpoint. If you have not created a connector configuration for this type of endpoint, you can do so from this window by clicking the green plus sign (+). Click the Edit icon to modify a previously created global element.
Output Pattern	(Applies to outbound SFTP endpoint only.) Specify a pattern for naming files that get sent from the File endpoint to the connected file system. If this is not set, the File endpoint uses the same file-naming pattern used for incoming files. Example: `#[header:inbound:originalFilename]`
Host	Identify the outgoing (local) SFTP server, then supply user credentials for connecting to this server. Defaults to localhost. Enter the Fully Qualified Domain Name (FQDN) or IP address of the server on your host machine that connects to the external SFTP server.
Port	The port that connects to the local (host) server. (Normally, 22)
Path	Specify a path that facilitates connection to the local server so that you don’t have to provide a username and password.
User	The username for authentication on the host server.
Password	The password for authentication on the host server.

Display Name

Defaults to the generic endpoint name, which in this case is SFTP. Change the display name, which must be alpha-numeric, to reflect the endpoint’s specific role, for example, File Retrieval Endpoint.

Exchange Pattern

If set to one-way, an SFTP inbound or outbound endpoint sends the incoming message to the next processor in the flow. If an SFTP outbound endpoint is set to request-response (the SFTP inbound endpoint cannot be set to request-response), that outbound endpoint waits for a response before sending the message. One-way is the default for both the inbound and outbound SFTP endpoints.

Connector Configuration

Use the dropdown list to select a previously configured connector configuration for this endpoint. If you have not created a connector configuration for this type of endpoint, you can do so from this window by clicking the green plus sign (+). Click the Edit icon EditIcon to modify a previously created global element.

Output Pattern

(Applies to outbound SFTP endpoint only.) Specify a pattern for naming files that get sent from the File endpoint to the connected file system. If this is not set, the File endpoint uses the same file-naming pattern used for incoming files.

Example:

#[header:inbound:originalFilename]

Host

Identify the outgoing (local) SFTP server, then supply user credentials for connecting to this server. Defaults to localhost. Enter the Fully Qualified Domain Name (FQDN) or IP address of the server on your host machine that connects to the external SFTP server.

Port

The port that connects to the local (host) server. (Normally, 22)

Path

Specify a path that facilitates connection to the local server so that you don’t have to provide a username and password.

User

The username for authentication on the host server.

Password

The password for authentication on the host server.

General Tab - Global Element Properties Screens

After you click the Connector Configuration’s green plus sign (+) or the edit symbol EditIcon , the Global Elements Properties screens appear with tabs for General, Advanced, Properties, Reconnection, File, and Notes. You can specify optional server property information or notes as needed. The rest of the screens are described in this section.

Global Element Properties - General Tab

Field Description

Field	Description
Name	Configuration name
Output Pattern	(Applies to outbound SFTP endpoint only.) Specify a pattern for naming files that get sent from the File endpoint to the connected file system. If not set, the File endpoint uses the same file-naming pattern used for incoming files. Example: `#[header:inbound:originalFilename]`
Identity File	File location for the PKI private key file.
Passphrase	Passphrase for the identity file (if needed).
Show password	Set to make the characters in the Passphrase field visible.

Name

Configuration name

Output Pattern

(Applies to outbound SFTP endpoint only.) Specify a pattern for naming files that get sent from the File endpoint to the connected file system. If not set, the File endpoint uses the same file-naming pattern used for incoming files.

Example:

#[header:inbound:originalFilename]

Identity File

File location for the PKI private key file.

Passphrase

Passphrase for the identity file (if needed).

Show password

Set to make the characters in the Passphrase field visible.

Global Element Properties - Advanced Tab

Field	Description
Dispatched Pool Factory	Configures Bean properties.
Dynamic Notifications	Indicate if you want dynamic email notifications.
Validate Connections	Validate connections. Enabled by default.
Connection Pool Size	Creates a connection pool size for one or more active connections. Specify a negative number for no limit of pool size, or set to zero (0) to indicate not to use a connection pool.
Polling Frequency	Frequency in milliseconds to check the read directory. The read directory is specified by the endpoint of the listening component.
File Age	Minimum age in milliseconds for Mule to wait before consuming a file. This allows a file write to complete before processing. Note: The Mule server and the SFTP server must have synchronized time for file age to work correctly.
Size Check Wait Time	Wait time in milliseconds between size checks to determine if a file is ready to be processed. This allows a file write to complete before processing. You can disable this feature by setting to a negative number or omitting a value. When enabled, Mule performs two size checks waiting the specified time between calls. If both checks return the same value, the file is ready to process.

Field

Description

Dispatched Pool Factory

Configures Bean properties.

Dynamic Notifications

Indicate if you want dynamic email notifications.

Validate Connections

Validate connections. Enabled by default.

Connection Pool Size

Creates a connection pool size for one or more active connections. Specify a negative number for no limit of pool size, or set to zero (0) to indicate not to use a connection pool.

Polling Frequency

Frequency in milliseconds to check the read directory. The read directory is specified by the endpoint of the listening component.

File Age

Minimum age in milliseconds for Mule to wait before consuming a file. This allows a file write to complete before processing.

Note: The Mule server and the SFTP server must have synchronized time for file age to work correctly.

Size Check Wait Time

Wait time in milliseconds between size checks to determine if a file is ready to be processed. This allows a file write to complete before processing. You can disable this feature by setting to a negative number or omitting a value. When enabled, Mule performs two size checks waiting the specified time between calls. If both checks return the same value, the file is ready to process.

Global Element Properties - Reconnection Tab

Field	Description
Do not use a Reconnection strategy	Disables a strategy in the event of an SFTP connection failure.
Standard Reconnection	Enables a reconnection strategy where Mule retries the connection the number of reconnection attempts and waits the number of milliseconds between attempts.
Frequency (ms)	The number of milliseconds that Mule should wait between attempting to re-establish an SFTP connection after a failure.
Reconnection Attempts	The number of attempts Mule should make to re-establish an SFTP connection after a connection failure.
Reconnect Forever	Click if you want Mule to continually attempt to reconnect an SFTP connection after it fails. Mule continues to wait Frequency milliseconds between attempts to reconnect.
Custom Reconnection	Lets you specify a file containing custom properties for how you want to define a connection policy. The file contains a class definition for the RetryPolicyTemplate interface.
Class	Path to a file containing a class definition for the RetryPolicyTemplate interface.
Properties	Properties to set for the RetryPolicyTemplate interface.

Field

Description

Do not use a Reconnection strategy

Disables a strategy in the event of an SFTP connection failure.

Standard Reconnection

Enables a reconnection strategy where Mule retries the connection the number of reconnection attempts and waits the number of milliseconds between attempts.

Frequency (ms)

The number of milliseconds that Mule should wait between attempting to re-establish an SFTP connection after a failure.

Reconnection Attempts

The number of attempts Mule should make to re-establish an SFTP connection after a connection failure.

Reconnect Forever

Click if you want Mule to continually attempt to reconnect an SFTP connection after it fails. Mule continues to wait Frequency milliseconds between attempts to reconnect.

Custom Reconnection

Lets you specify a file containing custom properties for how you want to define a connection policy. The file contains a class definition for the RetryPolicyTemplate interface.

Class

Path to a file containing a class definition for the RetryPolicyTemplate interface.

Properties

Properties to set for the RetryPolicyTemplate interface.

Global Element Properties - File Tab

Field Description

Field	Description
Archive Directory	(Applies to inbound SFTP endpoint only.) The directory on the Mule server where the file is archived. Create this folder before starting Mule for application deployment. The user that Mule runs under must have permissions to read and write to the folder.
Archive Temporary Receiving Directory	(Applies to inbound SFTP endpoint only.) Specify a directory in which the archive file is temporarily held before being forwarded to the archive directory. This temporary directory must be configured if archiving is implemented.
Archive Temporary Sending Directory	(Applies to inbound SFTP endpoint only.) Specify a directory in which the archived file is stored before it is sent to the outbound SFTP endpoint. This should be a sub-directory of the archive directory and must be specified if archiving is implemented.
Duplicate Handling	(Applies to outbound SFTP endpoint only.) Defines the behavior in case of duplicates.
Temp Directory Inbound	The directory in the inbound SFTP endpoint folder where incoming files are received. Ensure that the `mule` user is configured to create a temp folder. This folder is used to restart a failing file transfer.
Temp Directory Outbound	The directory in the outbound SFTP endpoint folder where outgoing files are staged before sending. Ensure that the `mule` user is configured to create a temp folder.
Keep File On Error	Click to assign a unique time-and-date-based namestamp to the file when it is moved to one of the temporary directories.
Auto Delete	(Applies to inbound SFTP endpoint only.) . Click this box to delete the file after it has been read.
Use Temp File Timestamp Suffix	This field gives the files in the temp directory a guaranteed unique name using the local time when the file was moved to the temp directory.
File Parser	Set either `file-custom-filename-parser` or `file:expression-filename-parser`.

Archive Directory

(Applies to inbound SFTP endpoint only.) The directory on the Mule server where the file is archived. Create this folder before starting Mule for application deployment. The user that Mule runs under must have permissions to read and write to the folder.

Archive Temporary Receiving Directory

(Applies to inbound SFTP endpoint only.) Specify a directory in which the archive file is temporarily held before being forwarded to the archive directory. This temporary directory must be configured if archiving is implemented.

Archive Temporary Sending Directory

(Applies to inbound SFTP endpoint only.) Specify a directory in which the archived file is stored before it is sent to the outbound SFTP endpoint. This should be a sub-directory of the archive directory and must be specified if archiving is implemented.

Duplicate Handling

(Applies to outbound SFTP endpoint only.) Defines the behavior in case of duplicates.

Temp Directory Inbound

The directory in the inbound SFTP endpoint folder where incoming files are received. Ensure that the mule user is configured to create a temp folder. This folder is used to restart a failing file transfer.

Temp Directory Outbound

The directory in the outbound SFTP endpoint folder where outgoing files are staged before sending. Ensure that the mule user is configured to create a temp folder.

Keep File On Error

Click to assign a unique time-and-date-based namestamp to the file when it is moved to one of the temporary directories.

Auto Delete

(Applies to inbound SFTP endpoint only.) . Click this box to delete the file after it has been read.

Use Temp File Timestamp Suffix

This field gives the files in the temp directory a guaranteed unique name using the local time when the file was moved to the temp directory.

File Parser

Set either file-custom-filename-parser or file:expression-filename-parser.

Advanced Tab

Field	Description
Address	Enter the address for this endpoint, such as, http://localhost:22/file.
Response Timeout	Specify how long the endpoint must wait for a response (in ms).
Encoding	Choose from a drop-down list the character set used for message data. (i.e., UTF-8).
Disable Transport Transformer	Check this box if you do not want to use the endpoint default response transport.
MIME Type	Select from the dropdown list one of the formats this endpoint supports.
Connector Endpoint	Use the drop-down list to select a previously configured global endpoint template, if any exist. If you have not created a global element for this type of endpoint, you do so by clicking Add and completing the fields on the pane that appears. Click Edit to modify a previously created global element.
Polling Frequency	(Applies to inbound SFTP endpoint only.) Specify how often to check for incoming messages. Default value is 1000 ms.
File Age	(Applies to inbound SFTP endpoint only.) Sets a minimum period a file must wait before it is processed. This helps ensure that long files are received in their entirety before processing starts. However, Mule and the SFTP server must be on synchronized time for this feature to work properly.
Size Check Wait Time	(Applies to inbound SFTP endpoint only.) The period to wait (in ms) between size-checks that determine if a file is ready to be processed.
Identity File and Passphrase Information	Information for PKI authentication.
Enable default events tracking	Enable default business event tracking for this endpoint.

Field

Description

Address

Enter the address for this endpoint, such as, http://localhost:22/file.

Response Timeout

Specify how long the endpoint must wait for a response (in ms).

Encoding

Choose from a drop-down list the character set used for message data. (i.e., UTF-8).

Disable Transport Transformer

Check this box if you do not want to use the endpoint default response transport.

MIME Type

Select from the dropdown list one of the formats this endpoint supports.

Connector Endpoint

Use the drop-down list to select a previously configured global endpoint template, if any exist. If you have not created a global element for this type of endpoint, you do so by clicking Add and completing the fields on the pane that appears. Click Edit to modify a previously created global element.

Polling Frequency

(Applies to inbound SFTP endpoint only.) Specify how often to check for incoming messages. Default value is 1000 ms.

File Age

(Applies to inbound SFTP endpoint only.) Sets a minimum period a file must wait before it is processed. This helps ensure that long files are received in their entirety before processing starts. However, Mule and the SFTP server must be on synchronized time for this feature to work properly.

Size Check Wait Time

(Applies to inbound SFTP endpoint only.) The period to wait (in ms) between size-checks that determine if a file is ready to be processed.

Identity File and Passphrase Information

Information for PKI authentication.

Enable default events tracking

Enable default business event tracking for this endpoint.

Transformers Tab

Field	Description
Request Transformer References	Enter a list of synchronous transformers that will be applied to the request before it is sent to the transport.
Response Transformer References	Enter a list of synchronous transformers that will be applied to the response before it is returned from the transport.

Field

Description

Request Transformer References

Enter a list of synchronous transformers that will be applied to the request before it is sent to the transport.

Response Transformer References

Enter a list of synchronous transformers that will be applied to the response before it is returned from the transport.

File Tab

Field	Description
Duplicate Handling	(Applies to outbound SFTP endpoint only.) Defines the behavior in case of duplicates.
Temp Directory	The directory in the inbound SFTP endpoint folder where incoming files are received, or, in the case of an outbound SFTP endpoint, where outgoing files are staged before sending.
Keep File On Error	(Applies to outbound SFTP endpoint only.) If true, the file on the inbound endpoint will not be deleted if an error occurs while writing to the outbound endpoint.
Auto Delete	(Applies to inbound SFTP endpoint only.) Check this box to delete the file after it has been read.

Field

Description

Duplicate Handling

(Applies to outbound SFTP endpoint only.) Defines the behavior in case of duplicates.

Temp Directory

The directory in the inbound SFTP endpoint folder where incoming files are received, or, in the case of an outbound SFTP endpoint, where outgoing files are staged before sending.

Keep File On Error

(Applies to outbound SFTP endpoint only.) If true, the file on the inbound endpoint will not be deleted if an error occurs while writing to the outbound endpoint.

Auto Delete

(Applies to inbound SFTP endpoint only.) Check this box to delete the file after it has been read.

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

SFTP Connector

Compatibility

To Install this Connector

Configuration

General Tab

General Tab - Global Element Properties Screens

Global Element Properties - General Tab

Global Element Properties - Advanced Tab

Global Element Properties - Reconnection Tab

Global Element Properties - File Tab

Advanced Tab

Transformers Tab

File Tab

See Also