FTP Server Adapter (V5.2.0 - 5.2.1)

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 get or put files from: Mailbox in this system Physical file system No additional permissions are required.
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 is 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 that may be between it and your virtual root.
Initiates business processes?	The FTP Server adapter: Can initiate business processes if the Payload Repository is a File System. You can configure the adapter to invoke a specific business process each time a message or file is placed in the home directory. Does not initiate business processes if the Payload Repository is a mailbox. 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 systems'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). It supports basic functions to integrate with the system 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 in the system. 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.
Restrictions (continued)	When the FTP Server adapter is used with File System, the following restrictions apply: The FTP Server is tightly integrated with the system's file system. An FTP client can only access the directory that is assigned to its user account. The FTP Server supports almost all functions specified in RFC 0959 (Standard FTP Server). 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). The home directory for FTP user is a combination of Base Directory and File System Virtual Root specified for the user. Only the directories and files that are within this directory are accessible to the user. When a particular user connects to different instances of FTP server adapter on the same instance, the user would see same files. This may not be true for FTP servers configured with File System. When the same user connects to different instances of FTP server on the same instance, the user would either see same files or different, depending on how the FTP server is configured.
Persistence level	None. This adapter does not have a pre-set persistence level.
Testing considerations	At 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:

Create an FTP Server adapter configuration (or enable the configuration installed with the application and edit parameters as needed).
Configure the FTP Server adapter.

Configuring the FTP Server Adapter

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

UI Field	Description
Name	Unique and meaningful name for the adapter configuration. Required.
Description	Meaningful description for the adapter configuration, for reference purposes. Required.
Select a Group	Not applicable for this adapter. Leave at default.
FTP Server Listen Port	The port number that the FTP Server should bind to and listen on for connection requests. The default value depends on the system platform and on your application configuration. Required.
Active Data Port Range	A range of ports that the server can allocate for the transfer of data to or from the FTP client in active mode. Optional. If left blank, the server will choose available system ports. Example values are: 1024-2048 2222 3000-4000 10500-10599,10700-10799
Passive Data Port Range	A range of ports that the server can allocate for the transfer of data to or from the FTP client in passive mode. Optional. If left blank, the server will choose available system ports. Example values are: 1024-2048 2222 3000-4000 10500-10599,10700-10799
Perimeter Server	Select a Perimeter server from the list. Default is node1 & 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 some other process has bound 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	A tuning parameter that indicates 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: Retain the default value unless instructed otherwise by IBM® support.
Maximum Number of Threads	A tuning parameter that indicates 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: Retain the default value unless instructed otherwise by IBM support.
Resumption Timeout (hours)	Timeout value for the incomplete document before it is purged. Required. Valid value is any number between 1 and 9,999,999.
NAT Address	Specifies the NAT IP address that the FTP server should send to the user FTP client in the 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 point of 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.
Payload Repository	Whether files or messages will be stored in a mailbox or a physical file system on the server. Required. Valid values are: Mailbox (default) - If you want to restrict user access to specific mailboxes, see the Mailbox Features, Creating Virtual Roots documentation. File System - If you want to restrict user access to specific file system folders and subfolders, see the Configuring an File System Virtual Root.
Document Storage	Displayed only if Mailbox is selected for Payload Repository. Indicates whether the body of the requested document must be stored on the file system or if it should be in the database. Required. Valid values are: System Default – If your system administrator has changed the installed default of File System, this ensures that 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 when the application is installed, but it can be changed. Contact your system administrator to see if the default has been changed. Note: For more information about document storage types, see Managing Services and Adapters.
Add Policy Type	If you want to apply an existing policy to this instance, select the plus sign.
Select policy type	Select one of the adapter policy types: Bandwidth Limiting Policy Lockout Policy Data Limit Policy Command Limiting Policy
Select Policy	Select from the list. Policy must have already been created.
Select Business Process Base Directory	Parameter is only configurable if File System is selected for Payload Repository. Choose the business process from the list to be invoked each time an inbound file is received. Optional.
Base Directory	Parameter is only configurable if File System is selected for Payload Repository. Path to the directory on the physical file system which this server adapter has access to. The file system virtual root defined for any user should be relative to this directory. The home directory for any user will be a combination of this directory and the file system virtual root. Required. The operating system level user who is running the JVM must have access to this directory.
Should the adapter be restricted to a certain group of users?	Select Yes or No to indicate whether to restrict specific users and groups to access 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 ranges of ports to the 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?	Valid values are: Yes – Upon login, the user is automatically placed in a directory that matches his or her user ID. If such a directory is not available, the user is placed in the virtual root directory. This option allows Sterling Connect:Enterprise® UNIX customers to run production scripts that require each user to be placed into directories that correspond to user ID. Caution: Do not select Yes if there is any chance that users of your application might have user IDs that differ only by case (example: jsmith and JSmith). No – The 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, range, or ranges of port numbers to be used as ACTIVE port. Optional. 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. Examples of valid values are: 3000 4000-5000, 6000
`User` Passive Ports	Any port number, range, or ranges of port numbers to be used as PASSIVE port. Optional. 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. Examples of valid values are: 3000 4000-5000, 6000
`Group` Active Ports	Any port number, range, or ranges of port numbers to be used as ACTIVE port. Optional. 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. Examples of valid values are: 3000 4000-5000, 6000
`Group` Passive Ports	Any port number, range, or ranges of port numbers to be used as PASSIVE port. Optional. 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. 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. Optional. Valid values are: Yes (Default) No
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 specified, 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.

Applying Policies to the FTP Adapter

You can apply adapter polices to the FTP Adapter. You can define Lockout, Bandwidth Limiting, Command Limiting, and Data Limit policies from the Admin Console UI (Deployment > Adapter Utilities > Policies). For more information, see Adapter Policies.

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:

Navigate to the Administration Menu > Deployment > Adapter Utilities > FS Virtual Root.
Next to Create a new Virtual Root, click Go!
Select the User ID from the list and click Next.
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.
Click Finish.

Editing a File System Virtual Root

To edit a File System Virtual Root:

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

Deleting a File System Virtual Root

To delete a File System Virtual Root:

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