FTP Server Adapter

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
  • 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 non-extractable 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)
  • Transfer resumption (for mailboxes) is disabled by default. To enable transfer resumption and listing documents that are in the staging area, set the value for listStagedDocuments property to true in the customer_overrides.properties file. The input to the customer_overrides.properties file must be ftpserver.listStagedDocuments=true It is set to true by default. Also, to control the amount of data that is uploaded between the checkpoints, specify a required value for the checkpointInterval property in the customer_overrides.properties file. The input to the customer_overrides.properties file must be ftpserver.checkpointInterval=100M. Checkpoints save the incomplete file for later resumption. Actual checkpoint is at the end of the buffer write that exceeds the interval. The checkpoint occurs only if the server adapter is configured for resumption, and if the upload is to a Global Mailbox . If you set the property to 0, automatic checkpoint is disabled. Default value for the property is 100M (megabytes). You can also specify the value in kilobytes (100K) or gigabytes (100G).
    Important: You must set the values in the customer_overrides.properties file that is located in the adapter container where the Global Mailbox system enabled adapters are running. For example, if the adapters are in the adapter container, node1AC1, you must set the values in the customer_overrides.properties file, which is located in the same adapter container.

    To support transfer resumption, the FTP Server adapter keeps partial documents in a temporary document staging area. This allows FTP clients to resume a transfer (within a specified time frame). If the transfer does not resume within the specified amount of time, the Partial Document Clean Up Service removes documents from the staging area and the transfer is no longer available for resumption.

    A common behavior among FTP clients before resuming a transfer is to request a list of the directory contents. In response to list requests, the default behavior is for the FTP Server adapter to return a listing that includes:
    • Complete documents in the target mailbox.

    • Partial documents in the staging area. Partial documents are assigned to a particular user. The system only displays partial documents to the user to whom they are assigned.

    If two documents with the same name exist in both the mailbox and the document staging area, only the partial document in the staging area is displayed in response to a list request.

    The home directory for FTP is a virtual root mailbox in the application or a path and directory specified on a physical file system on the server. The mailbox can include both extractable and nonextractable messages. When the FTP Server adapter accesses the home directory, only extractable messages are displayed.

    The FTP Server adapter does not return nonextractable files as part of a directory listing. Once a message becomes nonextractable, it effectively disappears from the FTP view of the mailbox.
Persistence level None. This adapter does not have a pre-set persistence level.
Testing considerations At application start up, 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. You can deploy the FTP adapter in the ASI or AC node.

    If you want to stop the ASI node while still receiving files, you can run the FTP adapter in an adapter container. If you upload a message when the JVM is down, message events are queued for processing and are processed when the JVM is up and running.

    If you run a Global Mailbox enabled adapter in the Adapter Container, you must also run a Global Mailbox Client Adapter in the adapter container.

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.
Environment Nodes where the FTP Server Adapter is deployed. The values are - nodes in the cluster, adapter containers, All ASI nodes, All ASI nodes plus all Adapter Container Nodes, and All Adapter Container Nodes. To scale the FTP server adapters as and when new nodes are added to the cluster, the options All ASI nodes, All ASI nodes plus all Adapter Container Nodes, and All Adapter Container Nodes are introduced.
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
Fast path: You can enter double ranges separated by commas, as shown in this example: 10500-10599,10700-10799
If 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
Fast path: You can enter double ranges separated by commas, as shown in this example: 10500-10599,10700-10799
If blank, the server will choose available system ports.
Perimeter Server Select a perimeter server from the list. Default is node1 and local. Required.
Restriction: 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.
Restriction: Do not change the default value unless instructed otherwise by IBM 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.
Restriction: Do not change the default value unless instructed otherwise by IBM support.
Resumption Timeout (hours)
Specify the time within which an incomplete transfer can be resumed. If the transfer is not resumed within the specified time, the incomplete files are removed from the staging area (by the Partial Document Clean Up service) and are no longer available for resumption.
Important: The resumption time applies to incomplete messages in traditional mailboxes only. The value of this parameter is ignored for incomplete messages in a Global Mailbox
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.
Payload Repository Whether files or messages are stored in the local 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 sub-folders, see Configuring a File System Virtual Root.
Enable Global Mailboxes The FTP Server adapter directs messages to a traditional or Global Mailbox, based on the realm of the virtual root of the user that is logged in and this setting. The options are the following values:
  • No - Select No to disable Global Mailbox. When you disable Global Mailbox, the FTP server adapter always uses traditional mailbox.
  • Yes - Select Yes to enable Global Mailbox. When you enable Global Mailbox, the FTP server adapter first looks for the Global Mailbox virtual root of the user. If a Global Mailbox virtual root is found, the FTP server adapter uses the Global Mailbox for that user. Otherwise, the FTP server adapter uses the traditional mailbox.
Document Storage Displayed only if Mailbox is selected for Payload Repository. 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. 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 log in, 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 number or 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: It is recommended to use SSL rather than plain FTP.
Restriction: 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 user name. 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 user name. 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 user name. 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.
Restriction: For a Global Mailbox, only Limited and Full (resume of file transfers not supported) options are supported.

FTP Server Functions That Are Supported

Table 1. FTP Server Functions That Are 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 – Log out
  • 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 That Are Not Supported

Table 2. FTP Server functions that are 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

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/ftpserver1 then the file system virtual root can be any folder/directory under the /install_dir/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.