SFTP Client

Deprecated Component

This communication point has been deprecated and replaced by the (S)FTP Client communication point.

It is strongly recommended you replace any SFTP Client communication points in your RLCs with (S)FTP Client communication points. For assistance in adapting your RLCs to use (S)FTP Client communication points, contact Rhapsody Support.

The SFTP Client communication point is used to connect to a server running a secure FTP (SFTP) service to look for files from an input directory and to send messages to an output directory. Refer to Published Properties for a list of properties associated with this communication point.

Typically, an SFTP service uses an underlying SSH layer to provide public-private key based authentication features. There is a wide range of key formats produced by different SSH emulations. Rhapsody supports OpenSSH; that is, Rhapsody only uses public-private key pairs generated in accordance with the OpenSSH standards.

The SFTP Client communication point supports Triple DES encryption algorithm. Public key authentication is supported for OpenSSH on Unix where the default algorithm is Triple DES, but not on Cygwin in Windows where the default algorithm is AES-128.

Supported Operational Modes: All.

Input Mode Properties

Ensure that the input location for multiple distinct communication point instances do not resolve to the same filename in order to prevent race conditions with multiple communication points trying to read the same file.

Property	Description
Server	Hostname/IP Address of SFTP Server to which to connect.
Port	SFTP communications port on the remote server.
Username	The username to log in with. This is to be provided when the administrator of the remote SFTP server provides a username for the purposes of logging in. Alternatively, the administrator can be asked to create a user with this identity (combination of username, password, and public key file) on the remote server. This may be provided as a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation).
Password	The password for the user. This may be provided as a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation). As message properties are visible in the Management Console to users with the appropriate access rights, it is highly recommended that you encrypt passwords provided in this message using the Encrypt Password function in Rhapsody IDE. Alternatively, you can use Configuration Templates, which do not require providing the password in a message property. If the passwords are retrieved from a Rhapsody variable using JavaScript, then the retrieval functions can leave them in this format. Refer to Encrypted Rhapsody Variables for details.
Passphrase	An optional passphrase used in case of public key based authentication. This is to be provided if the OpenSSH key pair has been created with a passphrase.
Read Timeout	Specifies the length of time Rhapsody will wait for a response from the SFTP server when requesting connections. Units: milliseconds.
Connection Mode	Options: `Disconnect if idle`, `Maintain a constant connection`. Default: `Maintain a constant connection` Allows the communication point to hold on to the SFTP connections made to the SFTP server if this is set to `Maintain a constant connection`. This is not advised if the communication point is expected to stay idle for extensive periods of time without any SFTP activity.
Authentication Mode	Options: `Public Key Authentication`, `Password Authentication`. Default: `Public Key Authentication` SFTP servers allow user authentication using a password or using SSH2 protocol specified Public-Private Key Files or both. The simplest form of user authentication is Password Authentication, where the user is required to set up a password as part of the Communication Point Configuration. The alternative mode requires some setup on the part of the administrators of both the local machine (machine on which Rhapsody IDE is installed) and the remote SFTP server machine. These two modes deal with OpenSSH based public-private keys. In the Public Key Authentication mode: An OpenSSH based public-private key pair is generated on the Rhapsody installation machine (or any other machine that can generate an OpenSSH public-private key pair). The OpenSSH private key belonging to the client is provided as the Private Key File configuration property. Once selected it is attached to the communication point for future use in its current form. The OpenSSH private key in the specified file is expected to be encrypted using Triple-DES, and the passphrase for that encryption provided in the Passphrase configuration property. During public key authentication, the client's public key is sent to the server, with proof that the client holds the associated private key. The server validates this in order to authenticate the client
Private Key File	Required when authentication mode is set to `Public Key Authentication`. The complete file path (absolute location) of the private key file to be used for public key authentication. If the file is not found in the specified location, the communication point cannot be configured.
Known Hosts	The complete file path of the `known_hosts` file on the Rhapsody Engine machine. The file maintains the list of the public keys that is loaded by the client to validate the server. When configured, Rhapsody uses the entries in this file to authenticate the remote server to log on to. The SSH login protocol allows validation of the remote server that Rhapsody will be logging on to.
Input Directory	The directory to check for input files. If this property is empty the default will be used, which is dependent on the SFTP server being used.
Pattern	The pattern to use to select input files from the Input Directory. This is an optional property. The default value is an asterisk (); that is, all files from Input Directory* are to be processed.
Refresh Rate	Specifies the frequency (in ms) that the input directory is checked for new files. The default value is `60,000ms` (1 minute).
Before Receive	Specifies a set of commands to execute on the remote server just before the file transfer begins. A failure to execute any of the commands set up will result in the file transfer process from being aborted and the communication point will shut down in an error state. This assumes that a batch file's executable has to exist in the user's home directory or any other directory that the SFTP server is allowed to access for command execution. Some SFTP server implementations can access operating system related commands directly, such as `echo`, `run.sh`. Refer to Send and Receive Commands for details.
After Receive	Specifies a set of commands to execute on the remote server just after file transfer begins. A failure to execute any of the commands will result in the communication point shutting down. Refer to Send and Receive Commands for details.

Output Mode Properties

Ensure that the output location for multiple distinct communication point instances do not resolve to the same filename in order to prevent potential overwrites occurring as a result of trying to write to the same file.

Property	Description
Server	Hostname/IP Address of SFTP Server to which to connect.
Port	SFTP communications port on the remote server.
Username	The username to log in with. This is to be provided when the administrator of the remote SFTP server provides a username for the purposes of logging in. Alternatively, the administrator can be asked to create a user with this identity (combination of username, password, and public key file) on the remote server. This may be provided as a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation)
Password	The password for the user. This may be provided as a literal, a Rhapsody variable (using the `$(variableName)` notation), or a Rhapsody message property (using the `$propertyName` notation). As message properties are visible in the Management Console to users with the appropriate access right, it is recommended that passwords provided in message properties are kept in their obfuscated form. If those passwords are retrieved via Rhapsody variables using JavaScript, then the retrieval functions can leave them in this format - refer to Encrypted Rhapsody Variables for details. If those passwords are provided as literals elsewhere in the configuration, then the Encrypt Password function in the Rhapsody IDE can be used.
Passphrase	An optional passphrase used in the case of public key based authentication. This is to be provided if the OpenSSH key pair has been created with a passphrase.
Read Timeout	Specifies the length of time Rhapsody will wait for a response from the SFTP server when requesting connections. Units: milliseconds.
Connection Mode	Options: `Disconnect if idle`, `Maintain a constant connection`. Default: `Maintain a constant connection` Allows the communication point to hold on to the SFTP connections made to the SFTP server if this is set to `Maintain a constant connection`. This is not advised if the communication point is expected to stay idle for extended periods of time without any SFTP activity.
Authentication Mode	Options: `Public Key Authentication`, `Password Authentication`. Default: `Public Key Authentication` SFTP servers allow user authentication using a password or by using the SSH2 protocol specified in the Public-Private Key Files or both. The simplest form of user authentication is Password Authentication, where the user is required to set up a password as part of the Communication Point Configuration. The alternative mode requires some setup on the part of the administrators of both the local machine (machine on which Rhapsody IDE is installed) and the remote SFTP server machine. These two modes deal with OpenSSH based public-private keys. In the Public Key Authentication mode: An OpenSSH based public-private key pair is generated on the Rhapsody installation machine (or any other machine that can generate an OpenSSH public-private key pair). The OpenSSH private key belonging to the client is provided as the Private Key File configuration property. Once selected it is attached to the communication point for future use in its current form. The OpenSSH private key in the specified file is expected to be encrypted using Triple-DES, and the passphrase for that encryption provided in the Passphrase configuration property. During public key authentication, the client's public key is sent to the server, with proof that the client holds the associated private key. The server validates this in order to authenticate the client
Private Key File	Required when authentication mode is set to `Public Key Authentication`. The complete file path (absolute location) of the private key file to be used for public key authentication. If the file is not found in the specified location, the communication point cannot be configured.
Known Hosts	The complete file path of the known_hosts file on the Rhapsody Engine machine. The file maintains the list of the public keys that is loaded by the client to validate the server. When configured, Rhapsody uses the entries in this file to authenticate the remote server to log on to. The SSH login protocol allows validation of the remote server that Rhapsody will be logging on to.
Output Directory	Directory on the remote server to place output messages.
Base Filename	Base filename to use for output messages. Refer to File Naming Options for details on specifying a published property or Rhapsody variable for this property.
Suffix	Optional suffix to append to the end of the filename. Refer to File Naming Options for details on specifying a published property or Rhapsody variable for this property.
Append Date	Options: `True`, `False`. Default: `False` Appends the current date/time to the filename. Note that the default is `True`; this compares with default `False` for the Directory communication point. This difference is because it is harder to test for unique names over FTP and hence is more important to generate a unique filename.
Check Name	Options: `True`, `False`. Default: `False` If `False`, existing files with the same name as the generated file will be overwritten. If `True` and a duplicate filename is encountered, a counter will be added to the newly generated filename. For example, if `uploaded.txt` already exists then `uploaded(1).txt` will be created for the new message. Setting Check Name to `True` will significantly slow the performance of the SFTP Client communication point.
Use temp file	Options: `True`, `False`. Default: `False` Allows Rhapsody to use a temporary file (file with a `.tmp` extension) to transfer the output message to. The temporary file will be renamed to the specified output file name once the entire transfer is complete.
Append to existing file	Options: `True`, `False`. Default: `False`. This will allow the SFTP transfer process to append messages to a file that may already exist on the remote server. This property cannot be set to `True` when Use Temp File or Check Name are set to `True`.
Before Send	Specifies a set of commands to execute on the local server just before file transfer begins. A failure to execute any of the commands will result in the communication point shutting down. Refer to Send and Receive Commands for details.
After Send	Specifies a set of commands to execute on the local server just after file transfer begins. A failure to execute any of the commands will result in the communication point shutting down. Refer to Send and Receive Commands for details.

Bidirectional, In->Out and Out->In Mode

The configuration properties for the Directory communication point in Bidirectional, In->Out and Out->In modes is a combination of the properties described above.

Refer to Out->In and In->Out Properties for general details on a communication point's In->Out and Out->In modes.

Send and Receive Commands

In order for these commands to work with the remote server, the following criteria must be met:

The mode is set to Out->In and Connection Mode property is set to Maintain a constant connection.
The command must return some text, otherwise the communication point will assume the command failed and stop in error.

Command	Result
`CD <path>`	Change remote directory to <path>.
`CHGRP <group> <path>`	Change group of file at <path> to user <group>.
`CGMOD <mode> <path>`	Change permissions of file <path> to <mode>.
`GET <remote path> [<local path>]`	Retrieve the <remote-path> and store it on the local machine. If the local path name is not specified, it is given the same name it has on the remote machine.
`LCD <path>`	Change local directory to <path>.
`LPWD`	Print local working directory.
`LS [<path>]`	Display a remote directory listing of either <path> or the current directory if <path> is not specified.
`MKDIR <path>`	Create remote directory specified by <path>.
`PUT <local path> [<remote path>]`	Upload <local-path> and store it on the remote machine. If the <remote path> name is not specified, it is given the same name it has on the local machine.
`PWD`	Print the remote working directory.
`RENAME <old path> <new path>`	Rename remote file from <old path> to <new path>.
`RM <path>`	Delete remote file specified by <path>.
`RMDIR <path>`	Remove remote directory specified by <path>.
`SYMLINK <old path> <new path>`	Create a symbolic link from <old path> to <new path>.
`VERSION`	Display the sftp protocol version.
`! <command>`	Execute <command> in remote shell via SSH. Will use the same credentials for SSH as for SFTP The `! <command>` is executed on the remote machine, unlike most SFTP client implementations which execute the command on the local machine.

Published Properties

Published properties of an INPUT communication point on a route are added to all drop-down lists where message properties can be selected on that route. For the SFTP Client communication point, these are:

Full Filename - the full filename of the file associated with the received message.
Base Filename - the base filename (everything before the last '.' in the full filename) of the file associated with the received message. If there is no '.', it is equal to the full filename.
Suffix - the suffix (everything from the last '.' in the full filename, including the '.') of the file associated with the received message. If there is no '.', it is empty.