x

To configure the FTP Server listener:

1. From the iWay Service Manager web console, click Registry and then Listeners.

   The Listeners pane opens.

2. Click Add.

   The Listener Type pane opens.

   

3. Select the FTPServer listener from the drop-down list, then click Next.

   The configuration parameters pane for the FTPServer listener opens.

   

4. Provide the appropriate property values for the FTPServer listener, as defined in the following table. An asterisk indicates a required property.

   Parameter	Definition
   Port*	TCP port for receipt of FTP requests. FTP standard is port 21.
   Local bind address	Local bind address for multi-homed hosts. Usually leave empty.
   FTP Server Log	A log of server commands received, and the results of each command.
   Server Root	Base directory for this FTP Server. When user mailbox paths are relative, they are below this directory.
   Allow Anonymous	If set, anonymous login is permitted. Anonymous users inherit the default read and write security.
   Use Safestore	Safestore preserves store requests while the incoming document is passing through execution. It is not meaningful for direct writes of messages to the file system. Using safestore can reduce system performance.
   Users
   Repository Type	How is the user repository stored? The repository can be stored either as an XML file or as a JDBC database.
   Security File [URL] *	Security file location. The security file describes users permitted to exchange messages with this server. It also describes their mailbox and security characteristics. This is a JDBC or a file URL depending upon the repository type.
   JDBC Driver	JDBC driver to use for accessing repository. Required if repository type is JDBC.
   JDBC User Name	Password for accessing the JDBC repository. Required if repository type is JDBC.
   JDBC Password	Select one of the following values from the drop-down list: column field row
   Default Permissions
   Default Can READ	If true, users without specific security can read.
   Default Can WRITE	If true, users without specific security can write.
   Action on GET	How should the server treat file retrieve type requests from the client.
   Action on PUT	How should the server treat file store type requests from the client.
   SITE EXEC	If true, clients can execute processes via the SITE EXEC command.
   Security
   Session Timeout *	If greater than 0, maximum seconds between commands before automatic session timeout.
   Security Protocol	Minimal security protocol supported for FTPS.
   Use 128-bit Encryption	Enforces the use of 128-bit encryption for all TLS channels.
   Require Secure Auth	Login must be via a secure authorization channel. You will need to configure the Keystore under HTTPS section of the system properties if client authentication is required. Note, if keystore is configured in system properties make sure it has the CA certificate or the client certificate of the server you are connecting to. If keystore is not configured in system properties default truststore located under /lib/security/cacerts will be used.
   Require Secure Transfer	Data transfers must be via a secured channel. You will need to configure the Keystore under HTTPS section of the system properties if client authentication is required. Note, if keystore is configured in system properties make sure it has the CA certificate or the client certificate of the server you are connecting to. If keystore is not configured in system properties default truststore located under /lib/security/cacerts will be used.
   Other
   Whitespace Normalization	Specifies how the parser treats whitespaces in element content. Choose preserve (default) to disable all normalization as prescribed by the XML specification. Choose condense to remove extra whitespaces in pretty printed documents and for compatibility with earlier versions.
   Accepts non-XML (flat) only	If set to true, the listener expects only flat (non-XML) files and the preparsers do not run.
   Optimize Favoring	Select one of the following values from the drop-down list: performance memory Note: Selecting memory is recommended if you are expecting large input documents.
   Multithreading	Number of documents that can be processed in parallel.
   Maximum threads	Number of parallel threads can grow automatically on demand.
   Execution Time Limit	Time limit (in seconds) for a document to execute before it is terminated.
   Default Java File Encoding	Default encoding if the incoming message is not self-declaring, for example, XML.
   Agent Precedence	Changes order by which engine selects agents. Normally Document overrides listener. This is used to manage iWay documents.
   Always reply to listener default	If set to true, the default reply definition is used in addition to the defined replies.
   Error Documents treated normally	If set to true, error documents are processed by any configured preemitters.
   Listener is Transaction Manager	If set to true, agents run within a local transaction managed by the listener.
   Record in Activity Log(s)	If set to true, the activity on this channel will be recorded in the activity logs, else the activity will not be recorded.

5. Click Next.

   The Name and Description pane opens.

6. Provide a name and optionally, a description for the FTPServer listener, and click Finish.

   The newly created FTPServer listener is added to the list in the Listeners pane.

x

When the home/mailbox information is not empty, it is either absolute or relative to the server root listener configuration parameter. If the home is absolute (for example, a physical location on a disk such as d:/a/b), then the server root is ignored and the user home is at and below the physical location specified. If the location is not absolute, then the home is below the server root. In all cases, the user is restricted to the final home location. iWay recommends that only administrators receive physical home locations that permit access to data other than message data.

x

By providing a user name and a password in the listener configuration window, you are creating a default user that has attributes set by the configuration defaults. This is a simple means of deploying FTP when all users have the same attributes. iWay does not recommend this approach for B2B installations, and suggests that the user and password fields be left empty.

x

Client GET (and MGET) requests the return of information to the client by the server. A GET of a client for a file can be handled in one of two ways, depending upon the current setting for this action. The default setting is configured for the listener but it can be overridden for any specific user. Anonymous users always inherit the listener settings.

1. Use File System. The retrieval operates as a standard FTP retrieval. Data is returned from the named file in the file system.
2. Execute as a Message. A standardized XML ftpd request document is constructed containing the request. This document is passed to the system for execution, and the result of the execution is returned to the client. The document header carries the attribute type='get'.
3. Deny Access to This Service. The user may not execute a retrieval.

x

Client PUT (including append) cause the transfer of information from the client to the server. A client request for a file can be handled in one of three ways, depending upon the current setting for this action. The default setting is configured for the listener but it can be overridden for any specific user. Anonymous users always inherit the listener settings.

1. Use File System. The request operates as a standard FTP store command. Data is stored from the named file in the file system.
2. Execute as a Message. The retrieved data is passed as a document into the system for execution. A standardized XML document is constructed containing the request. This document is passed to the system for execution, and the result of the execution is returned to the client. Optionally, the document can be safe stored before it is passed into the system for execution.
3. Deny Access to This Service. The user may not store a file.

x

The security file is loaded when the listener is initialized. This XML file describes the allowed users and their attributes. A schema is provided for this file. The XML holds one <user> element per authorized user. Attributes of the <user> element describe the user. Each user can be a member of one group, which applies the group's access criteria that can then be modified on an individual basis. The format for the <access> element allows the specification of the use attribute. The name of the directory to which the access applies is entered as the value of the <access> element.

The special <access> element name $partner is replaced for a specific logged in user with the name of the partner to which this user belongs.

A very basic example of a security file is:

<ftp>
<users>
<user password="SREG(local_userpwd)"home="SREG(iwayhome)/config/SREG(iwayconfig/mailbox" partner="ibi" group="iway">sr12231
<access use="rwd">soumya_raghavan</access>
</user>
</users>
<!-- v=Visit/View
     r=Retrieve
     w=Write
     d=Delete
     m=Directory create, rename, delete?
     u=Unique filename required, no overwrite 
-->
</ftp>

In this example, the FTP server is on the iWay server. The user on the localhost has read, write, and delete permissions on the localhost FTP server. To test this, open an FTP connection with the localhost and perform an FTP out to the local FTP server. The FTP Server listener will begin to process the message that is sent via FTP.

The following is another example of a security file:

<ftp>

<users>

<user password='pw1'
home=' mailbox' partner='abccorp' group=ediref>joe

<access use='rw'>joe</access>

<host>sheila</host>

<host>256.224.150.234</host>

</user>

<user password='pw2'
home='c:/' put='exec' exec='true' >admin</user>

</users>

<groups>

<group use=rw>ediref>

<access use='rw>'$partner</access>

<access use='r-w'>common</access>

</group>

</groups>

</ftp>

Note: The admin user has a physical home directory. For this user, the server location configuration property does not apply.

In this example, user joe belongs to the group ediref. This gives joe read access to the common directory, and read/write access to the partner directory abccorp, as well as his unique user directory joein. This user can manipulate the joein directory and its subdirectories, but can only read from the common directory. User joe is also restricted to log in from either of two authorized client systems. One is specified by host name and the other one by an IP address.

User joe takes system defaults, while user admin PUT messages are passed through the execution flow. User admin is also explicitly permitted to send SITE EXEC commands.

Any user can have controlled access. Permissions apply at the identified subdirectory below the document root of a user, and to all directories below that directory. If a permission is not specified, it is taken from the specification of a parent. Permissions are specified by the use attribute of the <access> child of the user. Possible access types are read ('r'), and write ('w'). Read permission permits the client to list directories and access files. Write permission permits file storage and the ability to manipulate directories. Either type can be preceded by a minus sign (-), which removes the permission. A plus sign (+) is implied if the minus is omitted. To add both read and write permissions, specify use='rw'. To accept the read permission of the parent and turn off write permission, specify use='-w'. The order of the characters is not significant.

If the partner keyword is included, the special register tpi.fromparty is set to its value. This register can be used to complete TPA() and TPP() functions. For details on these functions, see iWay Trading Manager User's Guide. For details on special registers, see Special Registers. For details on the home attribute, see User Home Locations.

x

SITE is a server-specific command that can be called by clients to execute some site-specific function. The FTPServer supports SITE for the following purposes. The SITE verb itself may or may not be inserted by the specific client in use. The means by which such site-specific commands are requested differs for individual clients. The following table lists available SITE commands.

Command	Description
SITE MIME filename	Returns the MIME-type of the named file.
SITE EXEC command [parameters...]	The password for the user. Can be a function reference such as LDAP()

A client needs specific permission to use the SITE EXEC command. Overall permission is set via the listener configuration, and can be overridden for a specific user via the user for or TPA.

x

Each command executed by the server can be logged. The log takes the format:

2006-01-29T16:20:12Z 1
USER joe : 331 Password required for joe (667c768105d92c18).

2006-01-29T16:20:14Z 1
PASS ---- : 230 User joe logged in.

2006-01-29T16:20:16Z 1
PORT 127,0,0,1,15,10 : 200 PORT command successful.

2006-01-29T16:20:16Z 1
LIST : 226 ASCII transfer complete.

where each line represents one command, in the format:

• Time
• Session Handler Number
• Command
• Parameter
• Result (up to 40 characters)
• Comment (optional)

x

The server exposes several special registers, which are listed and described in the following table.

Special Register	Description
ftpd user	Logged-in user identifier. If the user logged as a partner:user, this is only the user component. If this is a safe-stored message, the user is the username of the client user that passed the message.
tpi.fromparty	The partner name.
source	The hostname of the client connection.
ip	The IP address of the client connection.
ftpd file	The filename associated with the command.
ftpd command	The FTP name of the command being executed, in lower case.
ftpd mode	The current file transfer mode (ASCII or binary).
pdm	Possible duplicate. This message may duplicate an earlier message. This is always set to '1' while safe-stored messages are being processed.