| iMatix home page
| Xitami home page
| << | < | > | >>
Xitami Xitami
Version 2.5b4

The FTP Service

Overview

Xitami supports the FTP (file transfer) protocol. The FTP service was designed to be simple and easy to administer, while providing the security and speed necessary for a web site. You can administer the FTP service from the WBA screens, in the same way as you administer the rest of Xitami.

The current implementation of FTP does not support virtual hosts, so the FTP configuration applies to all virtual hosts defined for a web site.

The FTP service recognises these commands, and handles those not marked by '*':

 USER    PASV    STOU*   MAIL*   ALLO*   CWD     PWD     XMKD
 PASS    TYPE    SYST    MSND*   REST    CDUP    RMD     XRMD
 ACCT*   STRU    XSYS*   MSOM*   RNFR    XCWD    SITE*   XPWD
 REIN    MODE    PASV    MSAM*   RNTO    LIST    STAT*   XCUP*
 QUIT    RETR    APPE    MRSQ*   ABOR    MKD     HELP    XEXC*
 PORT    STOR    MLFL*   MRCP*   DELE    NLST    NOOP    SIZE

FTP Configuration Options

The configuration of the FTP service is handled by specific sections in the standard configuration file.  

The [FTP] Section

This section controls the FTP service.

enabled
Specifies whether the FTP service is enabled or not. If you change this option you must stop and restart the server for it to take effect. (The WBA control panel 'Restart' action will not start the FTP service.)
Default: 1 (enabled).
root
Specifies the root directory for FTP logins, unless a specific directory is defined for the current user.
Default: ftproot (below main Xitami directory).
port
Specifies the FTP connection port. The port is shifted by the portbase specified for the main HTTP service. For instance if you specify a port 21, and a portbase of 8000, your server will accept FTP connections on port 8021 and HTTP connections on port 8080.
Default: 21 (the standard FTP port).
timeout
Specifies the time in seconds after which inactive control connections are closed. An FTP session requires one control connection, plus one data connection during file transfers. You should tune this timeout to suit the requirements of your system. For instance, under an OS like Windows 95, sockets are a limited resource, so a shorter timeout is a good idea. For sites with a small user group, you can use high timeouts, which users generally prefer.
Default: 300 (5 minutes)
limit
Specifies the maximum number of users that may login at once. On systems that can handle lots of open sockets (e.g. Unix, OS/2, WinNT, Win98), you may want to increase this. Xitami does not impose any fixed limit. If you set this value to 0, it means 'no limit'.
Default: 25 users.
user-file
Specifies the name of the user definition file. The syntax for this is described below.
Default: ftpusers.aut.
directory-file
Specifies the name of the directory definition file. The syntax for this is described below.
Default: ftpdirs.aut.
dirsort
Specifies the sort order for directory listings. You can sort by file name, extension, size, or modification date/time using any combination of the letters 'n', 'x', 's', and 't'. For instance, dirsort=xnt will sort by extension, then name, then time. To sort in reverse order, use capital letters. For instance to show the most recent files first, use dirsort=T.
Default: n (sort by name).
message-script
Specifies the GSL script that is used to format FTP messages. If you use this option, Xitami ignores the welcome, signoff, and login-text options. You can edit the script to customise welcome and error messages. Look at the default script for a full description of the attributes you can use.
Default: templates/ftpmesg.gsl.
welcome
Specifies a text to be shown when a user connects to the FTP server. This can be literal text, or the name of a file, preceded by '@'. The file can contain up to 2000 characters. Any lines that start with '#' are ignored as comments. If you modify this file, it is safest to make a copy (call it welcome.txt or something) and change this option to refer to the changed file. This avoids unpleasant surprises when you reinstall the next latest greatest version of Xitami.
Default: @ftphello.txt (an example file).
signoff
Specifies a text to be shown when a user ends the FTP session. This can be literal text, or the name of a file, preceded by '@'. The file can contain up to 2000 characters. Any lines that start with '#' are ignored as comments. If you modify this file, it is safest to make a copy (call it goodbye.txt or something) and change this option to refer to the changed file. This avoids unpleasant surprises when you reinstall the next latest greatest version of Xitami.
Default: @ftpadios.txt (an example file).
login-text
Specifies a text to be shown when a user logs-in to the FTP server. This can be literal text, or the name of a file, preceded by '@'. The file can contain up to 2000 characters. Any lines that start with '#' are ignored as comments. If you modify this file, it is safest to make a copy (call it login.txt or something) and change this option to refer to the changed file. Xitami will search for this file first in the user's login directory, then in the main Xitami directory.
Default: @ftplogin.txt (an example file).
user-at-host
This flag controls whether Xitami allows virtual hosts using the syntax 'username@hostname'. This syntax is supported by some FTP clients, and allows you to use multiple FTP virtual hosts on a single IP address.
Default: 1 (enabled).
email-check
If 1, the FTP server will check that the e-mail address supplied for anonymous logins is a valid address. The nature of the check is not documented (it may just look for an '@' in the address).
Default: 0 (do not check addresses).
http-aliases
Specifies whether the HTTP [Alias] section should be used by the FTP service. This can be useful in configurations where you want to share the same data between services, but it can be a security risk if you want to use FTP aliases to access directories outside the HTTP space.
Default: 0 (disabled).
soft-quota
Specifies the default soft quota for FTP users who are subject to a quota. You can also specify quota values for individual users. This value is specified in megabytes, as a decimal number (using a decimal point, not comma, even in Europe). When a user exceeds their soft quota, they start getting warning messages.
2.5
hard-quota
Specifies the default hard quota for FTP users who are subject to a quota. You can also specify quota values for individual users. This value is specified in megabytes, as a decimal number. When a user exceeds their hard quota, they cannot upload new files.
2.5
webmask
Specifies the set of clients that can connect to the FTP server. The section on webmasks provides more details.
password-case
If 1, FTP passwords are case-sensitive. If 0, passwords are always converted to lower-case before validation. If you set this to 0, be sure to use only lower-case passwords in the password file.
Default: 1 (case-sensitive)
data-port
Specifies the port at which data connections will be made. Xitami scans for free ports, so this is simply the start of a range of ports. The port is shifted by whatever value was used for the server portbase.
Default: 200.
force-ip
Indicates whether passive connections must be forced to the IP address specified in the 'ipaddress' option.
Default: 0 (do not force).
ipaddress
The IP address used for passive connections. If '*', accepts passive connections on all local available IP addresses.
Default: '*'.  

The [FTPLog] Section

This section controls the FTP access log.

enabled
Specifies whether FTP accesses are logged or not. FTP accesses are logged in a format similar to that used for HTTP accesses.
Default: 1 (accesses are logged).
filename
Specifies the filename for access logging. This may be the same as the main HTTP access log file.
Default: access.log.
cycle
Specifies the cycle mode for the log file.
Can be one of:
  • startup, or 0 - cycle log when the server is starts;
  • hourly, or 1 - cycle log each hour;
  • daily, or 2 - cycle log each day;
  • weekly, or 3 - cycle log each week;
  • monthly, or 4 - cycle log each month, or
  • manual, or 5 - manual cycling only.
Default: daily.
local
Specifies whether to include local addresses or not.
Default: 1 (include local addresses).
 

The [FTP-Alias] Section

This section lets you define multiple FTP file roots. Each alias alias specifies a name and a path. For example:

[FTP-Alias]
volume-c=C:

The alias name itself may not contain '/'. It is not case sensitive. FTP aliases are only shown to 'root' users, i.e. those with an empty root value, or those who have the 'aliases=1' option defined (see below). Like HTTP aliases, the FTP alias is always the first component of a filename (e.g. /volume-c/somefile). Aliases are shown only if the user has no GET access, and if the specified user's root directory actually exists.  

The [FTPErrLog] Section

This section controls the FTP error log.

enabled
Specifies whether FTP errors are logged or not. FTP errors are logged in a format similar to that used for HTTP errors.
Default: 1 (errors are logged).
filename
Specifies the filename for error logging. This may be the same as the main HTTP error log file.
Default: error.log.
cycle
Specifies the cycle mode for the log file.
Can be one of:
  • startup, or 0 - cycle log when the server is starts;
  • hourly, or 1 - cycle log each hour;
  • daily, or 2 - cycle log each day;
  • weekly, or 3 - cycle log each week;
  • monthly, or 4 - cycle log each month, or
  • manual, or 5 - manual cycling only.
Default: daily.
local
Specifies whether to include local addresses or not.
Default: 1 (include local addresses).
 

FTP User File Syntax

The FTP user file defines all users that may log-in to the FTP server. This is a typical user file:

[Admin]
    Access=*
    Password=-
    Root=""
    Aliases=1           #   Will have access to aliases
[Anonymous]
    Access=G
    Password=*
    Root=pub
[Guest]
    Access=G
    Root=c:\public\guest
[Upload]
    Access=P
    Password=upload
    Root=/tempfiles/upload
    Use-quotas=1
    Soft-quota=10
    Hard-quota=12

The user name is specified like this: [Admin]. User names are not case-sensitive. The password may be any text. The password may be one of these special values:

The access rights are any combination of:

The 'root' option defines where the user can work. If this is not specified, the user can work anywhere below the FTP root directory. You can also specify a full path, for instance:

root=/home/users/guest

The 'aliases' option defines whether or not a user has access to the FTP aliases. By default this is true for all 'root' users, i.e. those with an empty root value. You can override this default by specifying an explicit value for the aliases option.

Note that put-only directories should be treated as special cases, and used only as a user's root directory. You cannot 'chdir' to a put-only directory.

You can enable/disable quotas per user. We defined a 'soft quota' and a 'hard quota'. Above the soft quota, the user gets warning messages. Above the hard limit, uploads are refused, and warnings are sent to the web server console. The quota is calculated quite simply: it is the limit for all files in the user's login directory and subdirectories. You can therefore share a quota between users, or allocate a quota to individual users. The site administrator can decide whether log files are part of the quota or not, by putting them into the user's space, or into separate (non-quota) directories. For quotas to work, keep a user limited to the login subtree. I.e. do not allow writeable aliases. Quotas are managed by the three configuration keys: use-quota, soft-quota, and hard-quota.

The 'pipe' option lets you specify a throttle pipe for this account. You can define a default pipe for the entire FTP server. To specify that an account uses no pipe (runs at full speed) while a default pipe is defined for the server, specify the pipe name "-".

FTP Directory File Syntax

The FTP directory file defines access rights per user for specific directories. Each section is a directory name; either an absolute directory (e.g. [/pub]) or a child of the ftproot directory (specified without a leading slash: [pub]). To define rights for an alias directory, you must use the child's root directory plus the alias directory. For instance if you define an aliase like 'info' which maps to a CD-ROM drive, protection for a user 'guest' who's initial root directory is 'guest' looks like this:

[guest/info]

For instance, if the guest user has access to aliases, but you want to disable access to the 'info' alias, you could use an entry like this:

[guest/info]
guest=-

A directory entry covers all child directories, unless a more specific directory is defined for that user. Directory names are not case significant.

Each entry specifies access rights for a user; the user must have been defined in the FTP users file. The same access right codes are used.

An Example FTP Configuration

This material for this section was provided by Paul C. Fretz, <pcfretz@mha.shalom.k12.pa.us>.

Install Xitami in its own directory. Have your web pages in a separate directory such as c:\webpages

Setup 'defaults.cfg' to include:

[Server]
    Webpages=c:\webpages
[Ftp]
    Root=c:\webpages
    welcome="Welcome"                   #   text or @filename
    login-text="Login"                  #   text or @filename
    user-file=ftpulist.aut              #   Users authorization file
[Security]
    password-case=1                     #   Case-sensitive passwords
    filename=password.aut               #   Authorization file

Setup 'ftpulist.aut' to include:

[Anonymous]
    Access=G
    Password=*
    Root=AnonFTP
[WEBRoot]
    Access=G
    Password=123456
    Root=""
[U101]
   Access=GPDMR
   Password=123101
   Root=User/U101
[U102]
   Access=GPDMR
   Password=123102
   Root=User/U102

There are several things to keep in mind:

  1. The directory structure for the above is as follows:
    c:\webpages
           |-AnonFTP
           |-User
              |-U101
              |-U102
              |-...
    
  2. For FTP access to c:\webpages\User\U101 the userid is U101 and the password is 123101.
  3. The WEBRoot entry gives FTP 'get' access to your whole website.

Setup 'password.aut' as follows if you want to password protect the same subdirectories for browsing:

[/admin]
    Admin=-             #   By default, admin access is disabled
    Webmask=local       #   <== when 'local', remote access is not allowed
[User/U101]
   U101=123101
[User/U102]
   U102=123102
  1. 'Admin=-' disables web-based administration. Change this if you wish.
  2. When you try to access with your browser anything located in c:\webpages\User\U101 (by using http://yourdomain/User/U101/) the browser will ask for user name and password. The username is U101 and the password is 123101. The first line [User/U101] refers to the subdirectory. The second line U101=123101 is the user name and password and does not have to be anything like the first line.
  3. A scheme like this allows users to have their own private subdirectory on the web server. They can access just theirs by FTP using Netscape or a program like WS-FTP. These pages are then available for anyone to browse or if you protect them as shown above in 'password.aut', they are private.
  4. Note that the default Xitami configuration requires that CGIs start with the string '/cgi-bin'. The above configuration does not allow users to upload and run arbitrary CGIs, something that usually presents a security risk.

| << | < | > | >>
| Welcome To Xitami | Table Of Contents | Installing Xitami | Administration | Configuration | Using The Common Gateway Interface (CGI) | Server-Side Includes (SSI) | Using Filters | Server-Side XML Processing | Server-Side GSL Scripting | Image Maps | Virtual Hosts | The FTP Service | The Dynamic DNS Feature | Throttle Pipes | A Beginner's Guide | Writing Web Server Extension (WSX) Agents | Extending Xitami with External Peer Processes | FAQ | Getting Support | Credits | Release History | License Agreement
iMatix
Copyright © 1996-99 iMatix Corporation