The following configuration properties determine how the communication point connects to servers and authenticates connections:

Server

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTP, FTPS, SFTP.

Server is the name or IP address of the server to connect to.

Port

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTP, FTPS, SFTP.

Port is the port on the remote machine to connect to. To use the default port for the selected protocol, set this property to 0 (zero).

Read Timeout

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTP, FTPS, SFTP.

Read Timeout specifies the length of time in milliseconds that Rhapsody waits for a response from the FTP server.

For SFTP, it is also treated as an idle timeout. The internal connection to the SFTP server is closed if there is no activity for the specified period. However, the internal connection is automatically re-established as soon as it is needed again.

When running in Input-only mode, the Read Timeout and Refresh Rate cannot be configured to be within five seconds of each other. If this is the case, then the Read Timeout is automatically adjusted so that it is five seconds longer than the Refresh Rate. If the properties have the same value, a race condition is introduced whereby the connection times out just as the refresh rate indicates that polling for messages is required. This would result in spurious connection failures on the communication point - the failures would be re-tried but would incorrectly indicate that an error had occurred.

Connection Mode

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTP, FTPS.

Connection Mode specifies whether to use active or passive mode for data connections.

Property Option Description

ACTIVE†

 the remote server opens a data connection back to the communication point in order to transfer files.

PASSIVE

 the communication point establishes the data connection to the remote server.

† Default option.

Transfer Mode

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTPS, SFTP.

Transfer Mode indicates what data format to transfer the file.

Property Option Description

Binary†

 Transfer the file as binary data.
ASCII Transfer the file as ASCII data. ASCII transfer changes the line endings of text files to match the OS of the remote server. This makes it unsuitable for any binary file types.
EBCDIC Transfer the file as EBCDIC data. Internally this uses a binary connection to process most commands, but explicitly switches to EBCDIC to send or receive files, and back to binary once the send or receive is finished.

† Default option.

  • EBCDIC should only be enabled when connecting to a server that requires EBCDIC support.
  • EBCDIC cannot be used with SFTP.

Server Validation Mode

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTPS, SFTP.

The Server Validation Mode is used to determine how the (S)FTP Client communication point finds the SSL certificates or SSH public keys for server validation. Server validation is the process where the (S)FTP Client communication point verifies that it is talking to the FTPS / SFTP server that it thinks that it is talking to. This validation process either as part of the connection process (for FTPS implicit mode and SFTP) or shortly afterward (for FTPS explicit mode), but in all cases it is done prior to logging in. For FTPS, server validation is done using SSL certificates; for SFTP, it is done using SSH public keys.

Property Option Description
Use Preconfigured Keys (Recommended)† The SSL certificates and SSH public keys used to validate the remote server must be explicitly configured on the (S)FTP Client communication point. For the static configuration mode or when using configuration templates, the communication point will fail to configure if the appropriate certificates or keys are not provided. For dynamic configuration using message properties, the outgoing message will be sent to the error queue if the certificates or keys are not provided.
Allow Dynamic Key Lookups

The SSL certificates and SSH public keys can be looked up dynamically in the Rhapsody certificate and key store by the (S)FTP Client communication point as it performs the connection to the FTPS or SFTP server. These certificates and keys do not need to be explicitly configured on the (S)FTP Client communication point, however, they do need to already be present in the Rhapsody certificate and key store with the correct alias. For SSL certificates, this alias is in the format of hostname:port (for example, sample-ftps-server:990). For SSH public keys, this alias is in the format of hostname:port:algorithm (for example, sample-sftp-server:22:ssh-rsa or sample-sftp-server:22:ssh-dss).

If a dynamic lookup is performed, then the connection will succeed if the dynamic lookup finds exactly the same SSL certificate or SSH public key that has been presented by the FTPS or SFTP server. The connection will fail to be established if either no SSL certificate or SSH public key is found with the required alias, or if the wrong SSL certificate or SSH public key. In addition, dynamic lookups for SSL certificates will fail if the SSL certificate has expired or fails hostname validation (although hostname validation can be disabled with a separate option).

It is possible to enable the dynamic key lookups option and also statically configure SSL certificates or SSH public keys. If this is done then the statically configured certificates and keys are checked first, before any dynamic lookups are performed.
Auto-Add Keys For New Servers

The SSL certificates and SSH public keys can be looked up dynamically in the Rhapsody certificate and key store as with the previous option. In addition, if no entry is found with the required alias, the (S)FTP Client communication point will automatically add the SSL certificate or SSH public key presented by the FTPS or SFTP server. This allows the (S)FTP Client communication point to automatically trust an FTPS or SFTP server that it has never seen previously. If the (S)FTP Client communication points adds a new SSL certificate or SSH public key in this manner, it will alias them using the naming convention described above so that subsequent lookups will find the same SSL certificate or SSH public key.

SSL certificates and SSH public keys will not be automatically added to the Rhapsody certificate and key store if there is already a different certificate or key present using the required alias, and will reject the connection if that occurs. In addition, SSL certificates will not be added to the Rhapsody certificate and key store if the SSL certificate has expired or if the hostname validation check fails (although hostname validation can be disabled with a separate option).

It is possible to enable the auto-add certificates and keys option and also statically configure SSL certificates or SSH public keys. If this is done then the statically configured certificates and keys are checked first, before any dynamic lookups or automatic adding of certificates or keys is performed.

Warning - Potentially Insecure

Enabling this option is potentially dangerous as it means that no server validation is performed when the connection is established for the first time and so is subject to a man-in-the-middle attack. Consequently, it should never be enabled on an untrusted network or when performing an FTPS or SFTP connection over the internet. It is always preferable to explicitly configure the SSL certificates and SSH public keys used for server validation to ensure that the connection is secure.

To prevent this option from being accidentally enabled, it is not available until the following line is added to the rhapsody.properties file:

# Indicates whether the (S)FTP Client communication point is allowed to add SSL certificates and SSH public keys to the
# Rhapsody certificate manager when it sees an FTPS/SFTP server for the first time. Once enabled here the option
# becomes available on each instance of the (S)FTP Client communication point. The available settings are: enabled
# or disabled.
FileTransferModule.allowAutoAddingCertificatesAndKeys=enabled

† Default option.

SSL Server Certificates

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTPS.

SSL Server Certificates selects the certificates used to authenticate the FTPS server. It is required if FTPS mode is enabled.

The Server Certificates are selected from the certificates configured in the Rhapsody IDE Certificate and Key Manager.

Hostname Validation

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTPS.

Hostname Validation determines whether the SSL certificates presented by the FTPS server should be validated to ensure they are for the correct server.

Property Option Description

Enabled†

 SSL certificates presented by the server should be validated to ensure they are for the correct server.
Disabled SSL certificates presented by the FTPS server do not need to be validated to ensure they are for the correct server.

† Default option

Cipher Suites

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTPS, SFTP.

Cipher Suites configures the level of security used for the SSL or SSH connection to an FTPS or SFTP server, respectively.

Property Option Description

Very Strong

 For FTPS, refer to SSL Cipher Suites.
For SFTP, refer to SSH Cipher Suites.
FIPS For FTPS, refer to SSL Cipher Suites.
For SFTP, refer to SSH Cipher Suites.
Strong† For FTPS, refer to SSL Cipher Suites.
For SFTP, refer to SSH Cipher Suites.
Weak For FTPS, refer to SSL Cipher Suites.
For SFTP, refer to SSH Cipher Suites.

† Default option.

SSL Client Private Key

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTPS.

The SSL private key is used for client authentication when connecting to an FTPS server. The SSL private key is selected from the keys configured in the Rhapsody IDE Certificate and Key Manager.

SFTP Server Public Key

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: SFTP.

SFTP Server Public Key holds a list of the SSH public keys used to authenticate the SFTP server. It is required when using SFTP so that the communication point can be certain that it is connecting to the correct server. Many SSH/SFTP servers actually have two public keys configured: one for RSA, and one for DSA. It is recommended that both these public keys are configured in the communication point so the connection can be validated regardless of which key the server ultimately chooses to present.

If the SSH public key presented by the SFTP server does not match any of the keys in this list, then the connection is not established.

The SSH Public Keys are selected from the keys configured in Rhapsody IDE's Certificate and Key Manager.

SFTP Client Authentication Mode

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: SFTP.

SFTP Client Authentication Mode configures what type of SSH client authentication is performed when connecting to an SFTP server.

Property Option Description
Password Authentication† Password authentication is selected.
Public Key Authentication Public key authentication is selected. An SSH private key must be configured for the connection.
Password and Public Key Authentication Both password and public key authentication are selected. An SSH private key must be configured for the connection.

† Default option.

It must be configured when using SFTP.

SFTP Client Private Key

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: SFTP.

SFTP Client Private Key selects the single SSH private key used for client authentication when one of the public key authentication modes is selected. It must be configured when public key authentication is enabled; it is not available otherwise. During client authentication, the client transmits the SSH public key associated with this private key to the SFTP server, along with proof that it is the holder of the private key. The SFTP server can then match the SSH public key against its configuration in order to authenticate the client. The private key itself is never transmitted to the server.

The SSH Private Key is selected from the keys configured in the Rhapsody IDE's Certificate and Key Manager.

SFTP Compression

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: SFTP.

The SSH protocol is capable of negotiating a compression algorithm to use when a connection is established. SFTP Compression determines which compression algorithms the (S)FTP Client advertises its support for.

Property Option Description
Allow no compression No compression enabled.
Allow zlib compression SSH compression algorithm zlib enabled.
Allow zlib delayed compression SSH compression algorithm zlib@ssh.com enabled. Unlike zlib, the compression does not start until after authentication has completed.

All enabled by default. This means that selecting none of these options has the same effect as selecting all of these options.

Any of the enabled compression algorithms can be selected during the establishment of the SSH session. For example, if both no compression and zlib compression are enabled, it is acceptable for the server to select no compression. Thus, if you want to force compression, then you must disable the Allow no compression option.

SFTP Advanced Configuration Flags

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: SFTP.

SFTP Advanced Configuration Flags provides some controls to allow the (S)FTP Client Communication Point to successfully operate with some known bugs in various SFTP servers:

Property Option Description
Disable chmod after creating a directory By default, the communication point issues a chmod command immediately after creating a remote directory in order to ensure that the correct permissions are set on the directory, particularly so that the communication point can subsequently issue a change directory command to move into that directory. This is not required for all SFTP servers, and in some cases it results in an error being raised by the server when the chmod command is sent. Enabling this option will prevent the automatic chmod command being sent after creating a new directory. This problem manifests itself as an error in the communication point while it is creating a directory.
Disable chmod after uploading a file The communication point issues a chmod command after uploading a file in order to ensure that the file has the correct permissions. Some SFTP servers do not expect this chmod command and instead report an error that the file does not exist. If this error is encountered then this option can be enabled to prevent the chmod command being sent after an upload.
Disable wait for channel close By default, when closing a channel, the communication point waits for an acknowledgment from the SFTP server after sending the close request. This can cause a connection error to occur on some SFTP servers which do not send the expected acknowledgment. If this problem is encountered, this option can be enabled to prevent the communication point waiting for this acknowledgment when closing a channel.

None enabled by default.

Server Line Endings

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: SFTP.
  • Transfer Mode: ASCII.

When using the ASCII transfer mode with an SFTP server, the communication point must be able to determine what line endings are expected by the remote server in order to perform the line endings translation.

Property Option Description
Auto Detect† By default, the communication point attempts to auto-detect the line endings in use by examining the reported server information when the connection is established (specifically it looks at the line endings on the server information string).
Windows (CR+LF) Explicit set Windows line endings.
Unix (LF) Explicit set UNIX line endings.
Mac (CR) Explicit set Mac OS line endings.

† Default option.

This option is not required for FTP or FTPS, because in this case the ASCII transfer mode is native and handled by the server itself.

Username

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTP, FTPS, SFTP.

Username sets the username/id of the user for authenticating with the FTP server.

Password

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTP, FTPS, SFTP.

Password sets the password of the user for authenticating with the FTP server. The user account must have write access.

Connection Establishment Mode

Applies to...
  • Operational Mode: Input, Output, Out->In.
  • Connection Type: FTP, FTPS, SFTP.

Connection Establishment Mode determines whether to maintain a constant connection to the FTP server or to disconnect the connection immediately after it becomes idle. If the communication point is configured in dynamic mode, this value can be set using the message property ConnectionEstablishmentMode to one of the following values: disconnectIfIdle or maintainConnection.

Property Option Description
Maintain constant connection† Maintain constant connection to the FTP server after connection becomes idle.
Disconnect if idle Disconnect the connection immediately after it becomes idle. This would occur after Sending, Receiving and Throttling.