FTP Server Adapter (V5.2.2 - 5.2.5)

The FTP Server adapter receives and processes requests from external trading partners that are submitted using FTP. This adapter is used with a perimeter server.

The following table provides an overview of the FTP Server adapter:

System name FTP Server Adapter
Graphical Process Modeler (GPM) category None
Description This adapter receives and processes requests from external trading partners that are submitted using the FTP protocol. This adapter is used with a perimeter server.
Business usage Use this adapter to put files into, or get files from, a mailbox.
Usage example A trading partner uses an FTP client to retrieve a business document from a mailbox. The FTP Server adapter receives and processes the trading partner request.
Preconfigured? A configuration of the FTP Server adapter is installed, but disabled by default. You can enable the preconfigured FTP Server adapter or create a new configuration.
Requires third party files? No
Platform availability All supported platforms
Related services None
Application requirements To log in to the FTP server, you must have permission to your virtual root (either explicitly assigned or defaulted). To access a mailbox, you must have permission to that mailbox and all mailboxes between it and your virtual root. If a user exceeds the maximum number of failed login attempts, the FTP Server adapter locks the user out. The lock must be reset before the user can access the server again.
Initiates business processes? The FTP Server adapter does not directly initiate business processes. However, mailbox activities can trigger routing rules.
Invocation Not used in business processes
Business process context considerations None
Returned status values None
Restrictions Restrictions:
  • FTP Server is tightly integrated with the application’s mailbox system. An FTP client can only access the mailbox that is assigned to its user account.
  • FTP Server does not support all functions specified in RFC 0959 (Standard FTP Server). Basic functions are supported to integrate with the mailbox system, such as list message and sub-mailbox, send and extract message to/from mailbox.
  • FTP Server is not integrated with business process invocation when processing a request from a client.
  • The home directory for FTP is a virtual root mailbox. Mailboxes include both extractable and nonextractable messages. When accessing a mailbox using the FTP Server adapter, only extractable messages are displayed. To change this default behavior, edit the ftpserver.properties file and set listUnextractables=true (default is false).
  • The timeout value for a control channel connection is controlled by a parameter in the ftpserver.properties file. The default timeout value is 600 seconds. The minimum value is 60 seconds. If the control channel is idle longer than the timeout value, the session is terminated, unless the data channel is open (whether or not data is being transferred).
  • To access the FTP Server adapter and have full mailbox operations (listing, retrieving, and placing messages), you must have permission to the virtual root (either explicitly assigned or default). To operate fully on mailboxes in the hierarchy directory, you must have permissions on all mailboxes between the target mailbox and the virtual root.
  • Restricted operation can be granted to users with a parameter named MailboxLoginWithoutVirtualRootPermission. With this permission, you can log in and list files in a mailbox, but cannot retrieve or place files. This restricted permission only applies to the virtual root mailbox and does not impact operation on submailboxes.
Persistence level None. This adapter does not have a pre-set persistence level.
Testing considerations At application startup, attempt to access the FTP server using a supported FTP client with the configured IP address and port. Debug information can be found in the FTP logs. Select Logging Level from the following:
  • Error – Errors only
  • Communication Trace – Errors, requests from clients, and responses from the Server adapter, including ACL violations
  • All - for debugging, all activities

Implementing the FTP Server Adapter

To implement the FTP Server adapter, complete the following tasks:
  1. Create an FTP Server adapter configuration (or enable the installed configuration and edit parameters as needed).
  2. Configure the FTP Server adapter.

Configuring the FTP Server Adapter

To configure the FTP Server adapter, you must specify settings for the following fields:

Field Description
Name Unique and meaningful name for the adapter configuration. Required.
Description Meaningful description for the adapter configuration. Required.
Select a Group Not applicable for this adapter. Do not change default value.
FTP Server Listen Port Port number that the FTP Server should bind to and listen on for connection requests. The default value depends on your system platform and on configuration. Required.
Active Data Port Range Range of ports the server can allocate for the transfer of data to or from the FTP client in active mode. Optional. Example values are:
  • 1024-2048
  • 2222
  • 3000-4000
Note: You can enter double ranges separated by commas, as shown in this example: 10500-10599,10700-10799
If left blank, the server selects available system ports.
Passive Data Port Range Range of ports the server can allocate for the transfer of data to or from the FTP client in passive mode. Optional. Example values are:
  • 1024-2048
  • 2222
  • 3000-4000
Note: You can enter double ranges separated by commas, as shown in this example: 10500-10599,10700-10799
If left blank, the server will choose available system ports.
Perimeter Server Select a perimeter server from the list. Default is node1 and local. Required.
Note: You should use a specific external interface for communications with trading partners. Using a wildcard address can cause problems with FTP sessions. If another process binds the port used for the data channel on an interface, it may receive connections intended for the data channel. Using a specific TCP/IP address or DNS name prevents this from occurring.
Transfer Buffer Size (bytes) Specifies the size in bytes of the buffer used when transferring a file. Required. Valid values are 0 to 999,999,999. Default is 32000.
Minimum Number of Threads Tuning parameter indicating the range of threads available for handling events to improve performance. Must be less than or equal to the Maximum Number of Threads value. Default is 3. Required.
Note: Do not change the default value unless instructed otherwise by Sterling Commerce support.
Maximum Number of Threads Tuning parameter indicating the range of threads available for handling events to improve performance. Must be greater than or equal to the Minimum Number of Threads value. Default is 6. Required.
Note: Do not change the default value unless instructed otherwise by Sterling Commerce support.
NAT Address Specifies the NAT IP address the FTP server should send to the user FTP client in passive connection mode. Optional. Overrides the global NAT address specified in the ftpserver.properties file.
Maximum Logins Maximum number of logins the adapter may have active at any time. If no value is specified, logins are unlimited. Optional. Valid value is any integer to 9999999999.
Maximum Logins per user Maximum number of logins each user may have active on this adapter at any point of time. If no value is specified, logins are unlimited. Optional. Valid value is any integer to 9999999999.
Document Storage Indicates whether the body of the request document must be stored on the file system or in the database. Valid values are:
  • System Default – If your system administrator has changed the default value, this ensures the correct location is used.
  • Database – Body of the request document will be stored in the database.
  • File System (default) – This is the default value, but it can be changed. Contact your system administrator to see if the default has been changed.
Required.
Note: For more information about document storage types, see Managing Services and Adapters.
Should the adapter be restricted to a certain group of users? Select Yes or No to indicate whether to restrict access to the FTP server. Required. Default is No. If Yes, select Users and or Groups from the lists on subsequent pages.
Should the restricted users be assigned a specific range of ports? Select Yes or No to indicate whether to assign a specific port, range, or range of ports to users. Required. Default is No. If Yes, specify User Active Ports, User Passive Ports, Group Active Ports, and or Group Passive Ports on subsequent pages. You can specify any or all of these fields.
Should users start in the directory that matches their user name upon login? Places the user, upon logging in, into a directory (mailbox) that corresponds to their user ID. Valid values are:
  • Yes – Upon login, the user is automatically placed in a directory that matches their user ID. If such a directory is not available, the user is placed in the virtual root directory. This option allows Connect:Enterprise UNIX customers to run production scripts that require each user to be placed into directories that correspond to their user ID. Caution: Do not select Yes if any user IDs differ only by case (example: jsmith and JSmith).
  • No – User is placed in the virtual root directory.
Users Select a list of users who are granted permission to access the server.
Groups Select a list of groups who are granted permission to access the server.
User Active Ports Any port number or a range of port numbers to be used as ACTIVE port. Valid values are valid, available port numbers or a range of port numbers. Ranges are separated by hyphens. Multiple entries must be separated by commas. Spaces do not affect the meaning.Optional. Examples of valid values are:
  • 3000
  • 4000-5000, 6000
User Passive Ports Any port number or a range of port numbers to be used as PASSIVE port. Valid values are valid, available port numbers or a range of port numbers. Ranges are separated by hyphens. Multiple entries must be separated by commas. Spaces do not affect the meaning. Optional. Examples of valid values are:
  • 3000
  • 4000-5000, 6000
Group Active Ports Any port number or a range of port numbers to be used as ACTIVE port. Valid values are valid, available port numbers or a range of port numbers. Ranges are separated by hyphens. Multiple entries must be separated by commas. Spaces do not affect the meaning. Optional. Examples of valid values are:
  • 3000
  • 4000-5000, 6000
Group Passive Ports Any port numberor a range of port numbers to be used as PASSIVE port. Valid values are valid, available port numbers or range of port numbers. Ranges are separated by hyphens. Multiple entries must be separated by commas. Spaces do not affect the meaning. Optional. Examples of valid values are:
  • 3000
  • 4000-5000, 6000
Extractable Count The number of times the message can be extracted. Cannot be specified in conjunction with Extractable or Extractable For. Valid value is any integer. Optional.
Extractable For Indicates the length of time (in days, hours and minutes) the message can be extracted. Cannot be specified in conjunction with Extractable or Extractable Count. Optional.
Note: If you opt to specify a value for Extractable For, ensure that you do not leave any of the fields (Days, Hours, or Minutes) blank. Enter 0 in the fields for which you do not want to provide any value. That is, if you want the message to be extractable for one minute, enter 1 in the Minutes field and enter 0 in the Days and Hours fields. If left blank, the value is taken as 1.
Extractable Whether the message can be extracted. Cannot be specified in conjunction with Extractable Count or Extractable For. Valid values are Yes and No. Default is Yes. Optional.
SSL Whether Secure Sockets Layer (SSL) is active. Required. Valid values are:
  • None – If SSL is requested by a client it will be rejected (default)
  • Optional – SSL is used if requested by a client
  • Must – Clients that do not request SSL are not allowed to authenticate
Note: If Optional or Must is selected, the asset protection key must enable SSL for the appropriate protocol.
Key Certificate Passphrase Password that protects the server key certificate. Used to encrypt and decrypt messages. Required if SSL option is Must or Optional.
Cipher Strength Strength of the algorithms used to encrypt data. Required if SSL option is Must or Optional. Valid values are:
  • ALL
  • WEAK – Often required for international e-commerce, because government regulations prohibit STRONG encryption from being exported
  • STRONG – Default
Key Certificate (System Store) Private key and certificate for server authentication. Used to encrypt and decrypt messages. Required if SSL option is Must or Optional.
CA Certificates Certificate used to validate the certificate of an FTP client. This is the public key. If no CA certificate is chosen, no client certification is performed. Optional.
Clear Command Channel Indicates that communication across the command channel is not encrypted after authentication is completed. Optional.
Support for concurrent duplicate named file transfers Allows sending duplicate-named files to the same Mailbox using the same username. It also allows partners to receive multiple duplicate files with the same name, concurrently. Valid values are:
  • Limited (resume of file transfers) – The file transfer can be resumed if transfer fails from the point of failure. You cannot transfer files with the same name concurrently using the same Mailbox and the same username. Default.
  • Full, concatenate duplicate-named files on a GET (resume of file transfers not supported) – Supports sending files with the same name concurrently using the same Mailbox and the same username. The files with the same name are concatenated on a GET operation. Listing shows a single concatenated file. You cannot resume broken file transfers.
  • Full (resume of file transfers not supported) – Supports sending files with the same name concurrently using the same Mailbox. The files with the same name are not concatenated on both GET or PUT operations. Listing shows multiple files at the client side. You cannot resume broken file transfers.

FTP Server Functions Supported

The following table lists the FTP functions that are supported with the FTP Server adapter:

Category Commands Supported
Access Control commands
  • CDUP – Change to Parent Directory
  • CWD – Change Working Directory
  • PASS – Password
  • QUIT – Logout
  • REIN – Reinitialize
  • USER – User Name
Transfer Parameter Commands
  • MODE – Transfer Mode (Streamed)
  • PASV – Passive Mode
  • PORT – Data Port
  • TYPE – Representation Type (ASCII, Binary, EBCDIC, and Local byte)
Service Commands
  • ABOR – Abort
  • ALLO – Allocate
  • APPE – Append
  • DELE – Delete
  • HELP – Help
  • LIST – List
  • MDTM – Last modified time of a given file on a remote host
  • MKD – Make Directory
  • NLST – Name List
  • NOOP – No Operation
  • PWD – Print Working Directory
  • REST – Restart
  • RETR – Retrieve
  • RMD – Remove Directory
  • RNFR – Rename From
  • RNTO – Rename To
  • SITE – Site Parameter (CPWD, HELP, PSWD, and WHO ZONE)
  • STAT – Status
  • STOR – Store
  • STOU – Store Unique
  • SYST – System
  • XMKD – Make Directory (Legacy format)
  • XPWD – Print Working Directory (Legacy format)
  • XRMD – Remove Directory (Legacy format)
Security Commands
  • AUTH – Authentication/Security Mechanism
  • CCC – Clear Command Channel
  • EPRT – Specifies an address and port to which the server should connect
  • EPSV – Enter extended passive mode
  • PBSZ – Protect Buffer Size
  • PROT – Data Channel Protection Level
  • SIZE – Return the size of a file

FTP Server Functions Not Supported

The following table lists the FTP functions that are not supported with the FTP Server adapter:

Category Commands Not Supported
Access Control commands
  • ACCT – Account
  • SMNT – Structure Mount
Transfer Parameter Commands
  • MODE – Transfer Mode (Block and Compressed)
  • STRU – File Structure (Record and Page)

Activity Types for the FTP Server Adapter

This adapter reports the following activities to the Services Controller for activity monitoring:
  • PUT – Adds a file to a mailbox
  • MPUT - Adds multiple files to a mailbox
  • GET – Retrieves a file from a mailbox
  • MGET - Retrieves multiple files from a mailbox
  • Session – Records all activity after connection

File System Virtual Root

When you configure an FTP adapter and the Payload Repository is defined as File System, and if you want to restrict user access to specific file system folders and subfolders, then you need to configure the file system virtual root. The file system virtual root is relative to the adapter Base Directory. The virtual root defines the point of access for each user who has permission to use the adapter. The file system virtual root is relative to the Base Directory.

Configuring a File System Virtual Root

Before you begin, you need to know:
  • User ID that need permission to the adapter virtual root
  • Path to the Base Directory
  • Create a folder under the base directory which will be the virtual root

To create a new File System Virtual Root:

  1. Navigate to the Administration Menu > Deployment > Adapter Utilities > FS Virtual Root.
  2. Next to Create a new Virtual Root, click Go!
  3. Select the User ID from the list and click Next.
  4. Enter the path to the virtual root.

    For example, if the base directory is /install_dir/install/ftpserver1 then the file system virtual root can be any folder/directory under the /install_dir/install/ftpserver1 directory.

  5. Click Finish.

Editing a File System Virtual Root

To edit a File System Virtual Root:

  1. Navigate to the Administration Menu > Deployment > Adapter Utilities > FS Virtual Root.
  2. Use either Search or List to locate the User ID for which the virtual root needs to be edited.
  3. Click edit next to the User ID. The User ID is displayed.
  4. Click Next.
  5. Update the Virtual Root and click Next.
  6. Click Finish.

Deleting a File System Virtual Root

To delete a File System Virtual Root:

  1. Navigate to the Administration Menu > Deployment > Adapter Utilities > FS Virtual Root.
  2. Use either Search or List to locate the Virtual Root.
  3. Click delete next to the User ID which virtual root needs to be deleted.
  4. Click OK.
  5. Review the virtual root information.
  6. Click Delete.