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 parameter.

   Parameter	Definition
   Port*	The TCP port for receipt of FTP requests. FTP standard is port 21.
   Local bind address	The 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	The base directory for this FTP Server. When user mailbox paths are relative, they are below this directory.
   Allow Anonymous	If set to true, then anonymous login is permitted. Anonymous users inherit the default read and write security.
   Use Safestore	The 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
   Authentication Realm	Enter the name of the configured Authentication Realm provider. If left blank, then the user and their authentication credentials must be maintained in the FTP Server user repository.
   Repository Type	This determines how the user repository is stored. The repository can be stored either as an XML file or as a JDBC database.
   Security File [URL] *	The 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 Provider	The name of the iWay JDBC provider.
   JDBC Driver	The JDBC driver to use for accessing repository. This is required if repository type is JDBC.
   JDBC User Name	The 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 set to true, then users without specific security can read.
   Default Can WRITE	If set to true, then 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 set to true, clients can execute processes using the SITE EXEC command.
   Stream Encoding if ASCII	Determines the type of encoding to be used for ASCII transfers carried in a stream document. This value must use valid ASCII encoding.
   Stream Encoding if EBCDIC	Determines the type of encoding to be used for EBCDIC transfers carried in a stream document. This value must use valid EBCDIC encoding.
   Security
   Session Timeout *	If a value greater than 0 is set, then that value is the maximum number of seconds between commands before the session automatically times out.
   Security Provider	Enter the iWay keystore or SSL context security provider name. If this component is secure and no value is entered, then the default security provider is used.
   Security Protocol	The minimal security protocol supported for FTPS.
   Use 128-bit Encryption	This enforces the use of 128-bit encryption for all TLS channels.
   Require Secure Auth	The login must be through 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	The data transfers must be through a secured channel. You must 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	This 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	The number of documents that can be processed in parallel.
   Maximum threads	The number of parallel threads that can grow automatically on demand.
   Execution Time Limit	The time limit (in seconds) for a document to execute before it is terminated.
   Default Java File Encoding	The 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, the error documents are processed by any configured preemitters.
   Listener is Transaction Manager	If set to true, the 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.

   Note: The FTPServer listener supports streaming. Streaming is used for large documents or documents for which the application needs to split the input into sections under the same transaction. For more information on streaming and configuring streaming preparsers, see the iWay Service Manager Component and Functional Language Reference Guide.

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.

Client GET (and MGET) requests the return of information to the client by the server. A GET client for a file can be handled differently, depending on the current settings for the action. The default setting is configured for the listener but it can be overridden for any specific user in the security file.

1. Use File System

   This is a standard FTP retrieval. Data is returned from the named file in the file system.

   For example:

   ftp> get test.xml
   200 PORT command successful.
   150 ASCII data connection for test.xml (172.30.246.86,4071) (42 bytes).
   226 ASCII transfer complete (42 bytes).
   ftp: 42 bytes received in 0.00Seconds 42000.00Kbytes/sec.

   Test.xml was retrieved from the FTPServer and sent to the FTP client.

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. The result of the execution is returned to the client.

   For example, create a process flow that contains a MQEmit service object. Add the process flow to the FTPServer channel.

   ftp> get test.xml
   200 PORT command successful.
   150 ASCII data connection for /test.xml (172.30.246.86,4150) (0 bytes).
   226 ASCII transfer complete
   ftp: 1144 bytes received in 0.05Seconds 24.34Kbytes/sec.

   The following document is constructed and passed to the process flow.

   <ftpd user="user" type="get">
   <command>retr</command>
   <parm>/test.xml</parm>
   </ftpd>

   The process flow emits the above document to a MQ queue. The status document (shown below) is returned to the FTP client as test.xml.

   <?xml version="1.0" encoding="ISO-8859-1" ?>
   <emitstatus status="0">
   <protocol>MQ</protocol>
   <parms>
   <parm name="attribs">true</parm><parm name="ccsid"/>
   <parm name="channel">SYSTEM.DEF.SVRCONN</parm>
   <parm name="cipherspec">None</parm><parm name="correlid"/>
   <parm name="correlidtag"/><parm name="expiry"/>
   <parm name="format"/><parm name="host"/>
   <parm name="localtrans">true</parm>
   <parm name="manager">qm7</parm>
   <parm name="neverUseMaster">true</parm>
   <parm name="nopreemit">true</parm>
   <parm name="persist">queue</parm>
   <parm name="port">1414</parm>
   <parm name="priority"/>
   <parm name="queue">out</parm>
   <parm name="reportq"/>
   <parm name="reqcoa">false</parm>
   <parm name="reqcod">false</parm>
   <parm name="return">status</parm>
   <parm name="type">datagram</parm>
   <parm name="userregs">false</parm>
   <parm name="version">default</parm>
   <parm name="wanteos">false</parm>
   </parms>
   <timestamp>2010-11-29T21:25:51.800Z</timestamp>
   <status>0</status>
   <channel>ftpserver</channel>
   <nodename>com.ibi.agents.XDMQEmitAgent</nodename>
   <msgid>base64(AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)</msgid>
   <native>0</native>
   <correlid>base64(QU1RIHFtNyAgICAgICAgIBIu7UwgPXwF)</correlid>
   </emitstatus>

3. Deny Access to This Service

   The user may not execute a retrieval.

   For example:

   ftp> get test.xml
   200 PORT command successful.
   553 'test.xml': cannot read.
   Test.xml was not retrieved.

4. Use File System Then Execute a Message

   The retrieval operates as a standard FTP retrieval. Data is returned from the named file in the file system. Then, a standardized XML ftpd request document is constructed containing the request. This document is passed to the system for execution. The result of the execution is sent to the configured emitter.

   For example, create a process flow that contains a MQEmit service object. Add the process flow to the FTPServer channel.

   ftp> get test.xml
   200 PORT command successful.
   150 ASCII data connection for /test.xml (172.30.246.86,4150) (0 bytes).
   226 ASCII transfer complete
   ftp: 1144 bytes received in 0.05Seconds 24.34Kbytes/sec.

   Test.xml was retrieved from the FTPServer and returned to the FTP client. In addition, the following document is constructed:

   <ftpd user="user" type="get">
   <command>retr</command>
   <parm>/test.xml</parm>
   </ftpd>

   The document is passed to the process flow. The process flow emits the above document to a MQ queue. The following status document is returned from the process flow and sent to any configured emitters:

   <?xml version="1.0" encoding="ISO-8859-1" ?>
   <emitstatus status="0">
   <protocol>MQ</protocol>
   <parms>
   <parm name="attribs">true</parm><parm name="ccsid"/>
   <parm name="channel">SYSTEM.DEF.SVRCONN</parm>
   <parm name="cipherspec">None</parm><parm name="correlid"/>
   <parm name="correlidtag"/><parm name="expiry"/>
   <parm name="format"/><parm name="host"/>
   <parm name="localtrans">true</parm>
   <parm name="manager">qm7</parm>
   <parm name="neverUseMaster">true</parm>
   <parm name="nopreemit">true</parm>
   <parm name="persist">queue</parm>
   <parm name="port">1414</parm>
   <parm name="priority"/>
   <parm name="queue">out</parm>
   <parm name="reportq"/>
   <parm name="reqcoa">false</parm>
   <parm name="reqcod">false</parm>
   <parm name="return">status</parm>
   <parm name="type">datagram</parm>
   <parm name="userregs">false</parm>
   <parm name="version">default</parm>
   <parm name="wanteos">false</parm>
   </parms>
   <timestamp>2010-11-29T21:25:51.800Z</timestamp>
   <status>0</status>
   <channel>ftpserver</channel>
   <nodename>com.ibi.agents.XDMQEmitAgent</nodename>
   <msgid>base64(AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)</msgid>
   <native>0</native>
   <correlid>base64(QU1RIHFtNyAgICAgICAgIBIu7UwgPXwF)</correlid>
   </emitstatus>

Client PUT (including append) cause the transfer of information from the client to the server. A client PUT request can be handled differently, 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.

1. Use File System

   The request operates as a standard FTP store command. Data is stored from the named file in the file system.

   For example:

   ftp> put test.xml
   200 PORT command successful.
   150 ASCII data connection for /test.xml (172.30.246.86,4242).
   226 ASCII /test.xml transfer complete (42 bytes)
   ftp: 42 bytes sent in 0.00Seconds 42000.00Kbytes/sec.

   Test.xml was sent to the FTPServer and saved in the server root directory.

2. Execute as a Message

   The data is passed, as a document, into the system for execution. A standardized XML document is constructed containing the data. This document is passed to the system for execution.

   For example, create a process flow that contains a MQEmit service object. Add the process flow to the FTPServer channel.

   ftp> put test.xml
   200 PORT command successful.
   150 ASCII data connection for test.xml (172.30.246.86,4288).
   226 'STOR EXEC entered for test.xml': was successful.
   ftp: 42 bytes sent in 0.00Seconds 42000.00Kbytes/sec.

   Test.xml was sent to the FTPServer. It is then passed to the configured process flow which emits the document to an MQ queue.

   A 451 error code is returned to the FTP client when an error occurs in the process flow. For example:

   ftp> put test.xml
   200 PORT command successful.
   150 ASCII data connection for test.xml (172.30.246.86,1060).
   451 'STOR EXEC entered for test.xml': had an execution error!
   ftp: 1144 bytes sent in 0.00Seconds 1144000.00Kbytes/sec.

   An example of this type of error is when an MQEmit service object attempts to send a document to a queue that does not exist.

3. Deny Access to This Service

   This user may not store a file.

   For example:

   ftp> put test.xml
   200 PORT command successful.
   553 'test.xml': cannot write. (DENY)

   Test.xml was not sent to the FTPServer.

4. Use File System Then Execute a Message

   The retrieval operates as a standard FTP store command. Data is stored from the named file in the file system. Then, a standardized XML ftpd request document is constructed containing the request. This document is passed to the system for execution. The result of the execution is sent to the configured emitter.

   For example, create a process flow that contains a MQEmit service object. Add the process flow to the FTPServer channel.

   Test.xml was sent to the FTPServer and saved in the server root directory. In addition, the following document is constructed:

   <ftpd user="user" type="signal">
   <command>STOR</command>
   <parm>/test.xml</parm>
   <status>226 ASCII /test.xml transfer complete (42 bytes)</status>
   <path>c:\ftpserver\test.xml</path>
   <vpath>/test.xml</vpath>
   <transfersize>42</transfersize>
   </ftpd>

   The document is passed to the process flow. The process flow emits the above document to a MQ queue. The status document (shown below) is returned from the process flow and sent to the emitter (if one is configured).

   <?xml version="1.0" encoding="ISO-8859-1" ?>
   <emitstatus status="0">
   <protocol>MQ</protocol>
   <parms>
   <parm name="attribs">true</parm><parm name="ccsid"/>
   <parm name="channel">SYSTEM.DEF.SVRCONN</parm>
   <parm name="cipherspec">None</parm><parm name="correlid"/>
   <parm name="correlidtag"/><parm name="expiry"/>
   <parm name="format"/><parm name="host"/>
   <parm name="localtrans">true</parm>
   <parm name="manager">qm7</parm>
   <parm name="neverUseMaster">true</parm>
   <parm name="nopreemit">true</parm>
   <parm name="persist">queue</parm>
   <parm name="port">1414</parm>
   <parm name="priority"/>
   <parm name="queue">out</parm>
   <parm name="reportq"/>
   <parm name="reqcoa">false</parm>
   <parm name="reqcod">false</parm>
   <parm name="return">status</parm>
   <parm name="type">datagram</parm>
   <parm name="userregs">false</parm>
   <parm name="version">default</parm>
   <parm name="wanteos">false</parm>
   </parms>
   <timestamp>2010-11-29T21:25:51.800Z</timestamp>
   <status>0</status>
   <channel>ftpserver</channel>
   <nodename>com.ibi.agents.XDMQEmitAgent</nodename>
   <msgid>base64(AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)</msgid>
   <native>0</native>
   <correlid>base64(QU1RIHFtNyAgICAgICAgIBIu7UwgPXwF)</correlid>
   </emitstatus>

The security file (in XML format) is loaded when the listener is initialized. This XML file describes the users that are allowed and their attributes. The XML file contains one <user> element for each authorized user, and attributes of the <user> element are used to describe the user. Each user can be a member of one group, which applies the access group 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 for the <access> element.

Any user can have controlled access. Permissions are applied to the specified subdirectory, which is below the document root of a user, and to all remaining directories below this subdirectory. 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 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.

The following diagram illustrates a sample FTP directory structure that is referred to in the XML security file example that is provided in this section.

The following is a sample XML file that represents the content of a security file:

<ftp>
	<users>
		<!-- u1 user has same permissions as g1 group, 
                 but set at user level 
            -->
		<user password="pw" init="/steve" use="rw">u1			
			<access use="rw-du">/steve/in</access>
			<access use="r-w-d">/steve/out</access>
			<access use="v-r-w">/common</access>
			<access use="r">/common/in</access>
			<access use="-r-w-v">/*</access>			
		</user>
		
		<!-- user john is exactly like u1 (except that he starts in /john directory) 
                 but permissions from group 
              -->
		<user password="pw" group="g1">john</user>
		
		<!-- user steve is exactly like john, with two exceptions (overriding group defaults) 
            -->
		<user password="pw" group="g1">steve
			<access use="rwd">/steve/in</access>
			<access use="rw">/common/in</access>
		</user>
		
		<!-- user u2 is like group g2, with specified home directory below docroot.  
                 Note that when home is used, 
		     init and permission paths are from the user (or group) home, NOT from docroot,
		     while home is from docroot. 
            -->
		<user password="pw" init="/steve1" home="/subroot" use="v-r-w-d">u2
			<access use="rw-du">/steve1/in</access>
			<access use="r-w-d">/steve1/out</access>
			<access use="v-r-w">/common1</access>
			<access use="r">/common1/in</access>
			<access use="-v-r-w">/*</access>	
		</user>	
		
		<!-- john1 has g2 permissions 
            -->
		<user password="pw" group="g2">john1</user>
		
		<!-- steve1 has g2 permissions with override.  keep in mind that g2 
                 specifies non-docroot home, so paths
		     are from home, not docroot. 
            -->
		<user password="pw" group="g2">steve1
			<access use="rwd">/steve1/in</access>
			<access use="rw">/common1/in</access>
		</user>
		
		<!-- u3 is similiar to u2, except starts in /subroot, no init pos. -->
		<user password="pw" home="/subroot" use="vw-d-ru">u3
			<access use="rwduv">/u3</access>
			<access use="-r-w-v">/*</access>	
		</user>		
		
		<user password="pw" group="g3">u4</user>
		
	</users>
	
	<groups>
		<!-- g1 group has same permissions as u1, 
                 generalized with $user pattern 
            -->
		<group init="/$user" use="v-r-w-d">g1
			<access use="rw-d">/$user/in</access>
			<access use="r-w-d">/$user/out</access>
			<access use="v-r-w">/common</access>
			<access use="r">/common/in</access>
			<access use="-r-w-v">/*</access>				
		</group>
		
		<!-- g2 group much like g1, but home dir is /subroot 
                 and all paths are beneath it 
            -->
		<group init="/$user" home="/subroot" use="v-r-w-d">g2
			<access use="rw-d">/$user/in</access>
			<access use="r-w-d">/$user/out</access>
			<access use="v-r-w">/common1</access>
			<access use="r">/common1/in</access>
			<access use="-v-r-w">/*</access>			
		</group>
		
		<!-- log into (virtual) root w/write, but not read permission. change to use subdirectory with full priv. except overwrite, but venture nowhere else -->
		<group home="/subroot" use="vw-d-ru">g3
			<access use="rwduv">/$user</access>
			<access use="-r-w-v">/*</access>				
		</group>	
	</groups>
</ftp>

This sample XML security file describes several different types of users, illustrating some common usage patterns.

For the users u1, steve, and john in the sample security file:

• All have virtual file systems that begin in the docroot of the FTP server.
• All have initial positions other than the root of their virtual files systems. That is, after logging in, each of these users is positioned in the directory specified by their init attribute.
• All can change to and list the contents of, but cannot read or write files in the docroot and /common directories.
• All have some level of permission to access files in the /common/in directory.
• All have some level of permission in their init directories and below.
• None have any other access.

Users u1 and john differ only in that permissions of u1 are assigned to him directly, while john inherits them from the g1 group. User steve differs from john because he has access permissions for the /common/in and /steve/in directories that override the group g1 defaults.

For the users u2, steve1, and john1 in the sample security file:

• All have virtual file systems that begin below the FTP server's docroot, in /subroot. This means that they have no access whatsoever outside of /subroot. When logged in, /subroot appears to them as /.
• In other respects, these users have access permissions like u1, steve, and john. Users steve and john inherit access permissions from group g2.

For the users u3 and u4 in the sample security file:

• Like u2, steve1, and john1, these users have virtual file systems that begin in /subroot. However, since no initial position is specified, after login, these users are positioned in /subroot, which appears to them as /.
• These users can write files to /, but cannot read, overwrite, or delete.
• Each of these users has a private directory below /subroot, where they can read, write, and delete, but cannot overwrite existing files.
• Neither user has access to any other subdirectory of /subroot.
• User u4 differs from u3 in that their access permissions are inherited from group g3, while u3 has permissions assigned directly.

The following table lists and describes the permission flags that are used in the sample security file:

Flag	Description
v	Signifies "visit and view" access. Without the v flag set on a directory, a user cannot change to that directory or list its contents. The v flag is set by default and must be revoked explicitly.
r	Signifies that a user can retrieve files from the specified directory.
w	Signifies that a user can store files in the specified directory.
d	When "d" is set on a directory, a user can delete files from that directory.
u	When a directory has the "u" flag set, a user cannot overwrite a file in that directory.
m	Signifies that the user can modify directories, by creating new directories and renaming existing ones. The -m flag is set by default and must be granted explicitly.

Access Tree Notes:

• Permissions of a user for the root of their virtual file system are specified by the use attribute on the user element or on the group to which the user belongs. Do not add an access element for the virtual root (/).
• Permissions of directory are inherited by its subdirectories unless they are explicitly overridden. For example, if the use attribute flags for /steve are "v-r-w-d" and use for /steve/in is set as "r", then the permissions of the user in /steve/in are "vr-w-d".
• When assigning directory permissions to a user, use paths corresponding to the virtual file system of the user. For example, if the home of the user is /subroot and you want to set permissions for /subroot/common1, the path to use is /common1.

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.

Each command executed by the server can be logged. This log takes the following 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.

Each line in the log represents one command, using the following format:

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

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