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.
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>Note: 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. |
Note: The ‘-’ character revokes the specific permission. For example, -d revokes the delete permission for that directory, -r revokes the read permission.
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.
User configuration information can be stored in any relational database that is accessible through JDBC. To configure the user database:
- Create the database using any tool that can execute a DDL script. DDL scripts for MySQL, HSQLDB, and MSSQL are supplied and can be provided for other RDBMS as requested.
- From the iSM command line, run the MigrateFTPUsers tool.
-
Type MigrateFTPUsers along with
the command line arguments that are listed and described in the
following table:
Command
Description
userfile
Path to the XML user configuration file you wish to migrate.
op: operation
Specify one of the following operations:
- delete. Removes users, groups, and templates in the user file from the user database.
- upsert. Inserts or update users, groups, and templates found in file.
driver
Name of JDBC driver class.
url
JDBC connection URL for the user database.
u
User ID that is used to connect to the user database. Must have insert/update/delete permission for user database tables.
pwd
Password that is used to connect to the user database.
-
Alternatively, you can use the p switch to point to a
standard Java properties file that sets properties driver, url,
user, and password to be used in the connection to the database.
For example:
Enter command:>tool MigrateFTPUsers -userfile c:/working/ftptest/userfile.xml -driver com.mysql.jdbc.Driver -url jdbc:mysql:///iwftp -u root -pwd harrison -op upsert
or:
Enter command:>tool MigrateFTPUsers -p c:/working/mp.txt -userfile c:/working/ftptest/userfile.xml -op upsert
The mp.txt file that is referred to in this example can have the following structure and format:
driver=com.mysql.jdbc.Driver url= jdbc:mysql:///itm_db user=steve password=secret
-
Perform the following steps to configure the FTPServer
listener to use the user database for security information:
- Set the Repository Type property to JDBC.
- Set the Security File property to the JDBC connection URL for the user database.
- Set driver, user, and password properties appropriately.
User information can be stored in a small relational database consisting of four tables:
- iwftp_owners
- iwftp_permissions
- iwftp_user_hosts
- iwftp_templates
The iwftp_owners table defines users and groups that can access the server. The fields are listed and described in the following table:
|
Field |
Type |
Description |
|---|---|---|
|
iw_ownername |
varchar(45) |
The identifier for the user or group. |
|
iw_ownertype |
char(1) |
Specify G for group or U for user. |
|
iw_password |
varchar(45) |
Password for the user or group. |
|
iw_isanon |
integer |
Specify 1 if this user definition should be used for anonymous logins, or 0 otherwise. |
|
iw_fullname |
varchar(45) |
The long identifier for the user. |
|
iw_partner |
varchar(45) |
The reference to a partner agreement defined in iWay Trading Manager. |
|
iw_groupname |
varchar(45) |
For users, the group to which they belong. FK to iw_ownername. |
|
iw_comment |
varchar(45) |
The documentation for the owner. |
|
iw_home |
varchar(45) |
The home directory is the root of the virtual file system for the owner. |
|
iw_initialposition |
varchar(45) |
The directory where the owner should be positioned at login. |
|
iw_getaction |
integer |
The action of the server on RETR command (0 is system default, 1 is exec, 2 is signal, and 3 is file). |
|
iw_putaction |
integer |
The action of the server on STOR command. Uses the same constants as iw_getaction. |
|
iw_canread |
integer |
Default read permission for this owner (0 for no, 1 for yes, and 2 for not set). |
|
iw_canwrite |
integer |
Default write permission for this owner. Uses the same constants as iw_canread. |
|
iw_candelete |
integer |
Default delete permission for this owner. Uses the same constants as iw_canread. |
|
iw_canoverwrite |
integer |
Default overwrite permission for this owner. Uses the same constants as iw_canread. |
|
iw_canvisit |
integer |
Default visit permission for this owner. Uses the same constants as iw_canread. |
|
iw_canmod |
integer |
Default directory modify permission for this owner. Uses the same constants as iw_canread. |
The iwftp_permissions table defines resources to which an owner has access and the specific constraints on that access. The fields are listed and described in the following table:
|
Field |
Type |
Description |
|---|---|---|
|
iw_owner |
varchar(45) |
User or group to which this permission entry applies. FK for iwftp_owners.iw_ownername. |
|
iw_ownertype |
char(1) |
Specify G for group or U for user. FK for iwftp_owners.iw_ownertype. |
|
iw_resource |
varchar(45) |
Name of the directory for which access should be defined. Enter with an absolute path using the virtual file system of the owner. |
|
iw_canread |
integer |
Default read permission for this owner (0 for no, 1 for yes, and 2 for not set). |
|
iw_canwrite |
integer |
Default write permission for this owner. Uses the same constants as iw_canread. |
|
iw_candelete |
integer |
Default delete permission for this owner. Uses the same constants as iw_canread. |
|
iw_canoverwrite |
integer |
Default overwrite permission for this owner. Uses the same constants as iw_canread. |
|
iw_canvisit |
integer |
Default visit permission for this owner. Uses the same constants as iw_canread. |
|
iw_canmod |
integer |
Default directory modify permission for this owner. Uses the same constants as iw_canread. |
The iwftp_user_hosts table defines host names or IP addresses from which a specific user can connect to the server. The fields are listed and described in the following table:
|
Field |
Type |
Description |
|---|---|---|
|
iw_username |
varchar(45) |
User or group for which this host entry applies. FK for iwftp_owners.iw_ownername. |
|
iw_hostname |
varchar(45) |
Host name or IP address from which this user can connect to the server. |
The iwftp_templates table defines patterns that can be used as shorthand when configuring users or groups. The fields are listed and described in the following table:
|
Field |
Type |
Description |
|---|---|---|
|
iw_templatename |
varchar(45) |
The identifier for this template. |
|
iw_templatepattern |
varchar(45) |
The substitution string for this template. |
To configure for anonymous access:
- Set the Allow Anonymous property for the listener to true.
-
Define a user with the permissions you wish to grant
anonymous users.
It is customary to name this user anonymous. However, you may use any name you wish.
-
Set the anonxx attribute for this user to true, as shown
in the following example:
<user anonxx="true" home="/common" use="v-r-w-d">anonymous</user>
When the anonymous user logs in, he is prompted for a password. Any string containing the @ character is accepted.
If the path specified in the <home> element is absolute (for example, a physical location on a disk, such as d:/a/b), then the server root parameter on the listener 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 (configured on the listener). 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.