OS/2 Shareware BBS: 35 Internet/35-Internet.zip/ftpsr085.zip/ftpserver.INF

OS/2 Help File | 2000-07-04 | 68KB | 2,105 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ

FtpServer is an ftp daemon for OS/2.  It is distributed as optional shareware.
This documentation is for version 0.85.

Disclaimer of Warranty

      This Product is provided "as-is", without warranty of any kind, either
      expressed or implied, including, but not limited to, the implied
      warranties of merchantability and fitness for a particular purpose.  The
      entire risk as to the quality and performance of the Product is with you.
      Should the Product prove defective, the full cost of repair, servicing,
      or correction lies with you.

 The author of FtpServer is Peter Moylan, [e-mail].

 The latest version of FtpServer is normally kept at
 ftp://eepjm.newcastle.edu.au/software
 Information about other software on this site may be found at
 http://eepjm.newcastle.edu.au/os2/software.html.

 I keep a mailing list of people who receive e-mail notification of new
 versions of my software.  If you want to be put on this list, let me know by
 e-mail to [e-mail]. The mailing list is not used for any
 other purposes, and the addresses will not be passed on to anyone else.


ΓòÉΓòÉΓòÉ 2. Registration ΓòÉΓòÉΓòÉ

 Registration

This software is "optional shareware".  What this means is that you decide
whether you want to register as a paid owner of the software. The software is
not crippled in any way, and I will continue to provide support and free
releases of new versions to all users, whether or not they are registered, for
at least the short-term future.

If you decide that this software is worth supporting, you have the following
payment options.

Payment through BMT Micro

This is likely to be the most convenient method for most people, because BMT
Micro has a number of different payment methods, including credit cards.  It
also has agents in several countries.  For full details, see the BMTMicro
folder included in the FtpServer distribution. (This includes a program that
simplifies registration by e-mail, if you want to do it that way.)  The price
is $20 (US dollars).

From Europe

This works best for people living in the European Union.  (Warning: check first
whether your bank is going to charge you transfer fees. They shouldn't, but
I've heard of exceptions.)  You have two options:

     Transfer ΓòÆ20, or the equivalent in Belgian francs, to the following bank
      account

           Marion Gevers
           Account number 220-0586389-60
           GВnВrale de Banque (Belgium)
           Mention: FtpServer

      and send an e-mail to [e-mail] to confirm that you've
      done it.

     Send a Eurocheque for 750 Belgian francs to

           Peter Moylan
           91 Harriet Street
           Waratah, NSW 2298
           Australia

 Payment directly to me in Australia

 This is a more attractive option for people in Australia.  From other
 countries, it's not a good idea because of the bank charges on international
 transfers.  (Please don't send non-Australian currency to an Australian bank,
 because then I get hit with exorbitant bank fees.) You can do it in either of
 two ways.

     Send a cheque, or equivalent, for $25 (Australian dollars) to

           Peter Moylan
           91 Harriet Street
           Waratah, NSW 2298
           Australia

     Transfer the amount of $25 (Australian dollars) to the following bank
      account.

           Marion Gevers
           Account number (06 2831) 00626468
           Commonwealth Bank
           University of Newcastle, Australia


ΓòÉΓòÉΓòÉ 3. Documentation in other languages ΓòÉΓòÉΓòÉ

Documentation in other languages

To simplify the distribution, the FtpServer zip file normally contains only
English-language documentation.  To get documentation in another language, go
to ftp://eepjm.newcastle.edu.au/inf and look for a file called
ftpserver.inf.xxx, where xxx indicates the language. If you want to volunteer
to do another translation, you will find the original document source
(FtpServer.IPF) in source.zip, which is included as part of the FtpServer
distribution.

The copyright on the translations belongs to the people who did the
translations.

The versions that are now available are

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéItaliano/Italian   Γöéftpserver.inf.it   ΓöéAndrea Brancatelli     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
│PycckuЧ/Russian    │ftpserver.inf.866  │Konstantin Boyandin    │
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 4. Server features ΓòÉΓòÉΓòÉ

 FtpServer is an ftp server program that implements most of the ftp standard,
RFC 959.  It supports re-get and passive mode transfers.  The system manager
can control which directories are visible to users, and the kind of access
(read, write, delete) allowed in each directory.

For further details, see

     What's special about FtpServer
     Limitations and missing features
     Quirks
     Troublesome clients
     Nonstandard features


ΓòÉΓòÉΓòÉ 4.1. What's special about FtpServer? ΓòÉΓòÉΓòÉ

     Supports essentially all of what's in the FTP standard, including re-get
      and passive mode.

     Fast and compact.

     Compatible with all FTP clients that I've been able to test.

     Separate read, write, and delete permission for each directory the user
      can see.  You can also make directories invisible. Users can be given
      access to multiple drives or network drives, if desired.

     The directories seen by a user can include symbolic links.

     You can restrict the IP addresses from which clients can log in, and you
      can restrict the number of simultaneous logins from the same address.

     Can be run from inetd.

     Can be run detached.


ΓòÉΓòÉΓòÉ 4.2. Limitations and missing features ΓòÉΓòÉΓòÉ

LIMITATIONS AND MISSING FEATURES

These are things I might fix up when I have the time, though some have higher
priority than others.

     Transfer types: only Ascii, Image, and "Local 8" are supported. Support
      for Fortran carriage control and EBCDIC will probably never be added.

     Page-structured files will probably never be supported. (As far as I
      know, only PDP-10 systems support this feature.)

     The only supported transmission mode is stream mode.  I might or might
      not add support for block mode and compressed mode at a later stage.  For
      the moment, there doesn't seem to be any demand for these extras - I
      haven't come across any ftp client that uses them.

 The only command from RFC 959 that is not implemented is STAT.


ΓòÉΓòÉΓòÉ 4.3. Quirks ΓòÉΓòÉΓòÉ

QUIRKS

These might be seen as errors, but there's no need to fix them because they
don't have a harmful effect.

     Can CD to a directory that doesn't exist, if that directory is shown as
      visible in the user's permission file.  Not a real problem, because the
      user sees an empty listing and can't do any operations in that directory.


ΓòÉΓòÉΓòÉ 4.4. Troublesome clients ΓòÉΓòÉΓòÉ

TROUBLESOME CLIENTS

Different ftp clients work differently, and some of them don't bother to adhere
to the standards, so there will probably always be some client
incompatibilities.  The ones I know about so far are:

   1. One of the MS-Windows ftp clients (for the moment I've forgotten which
      one) gives unreasonable time delays when listing a short directory,
      although long listings are quite fast.  The tests I've been able to do
      suggest that this problem occurs only when the client and server machines
      are physically close to each other.  Once the network delays rise to more
      typical values, the problem goes away.

   2. I've been told of a problem when using ws-ftp, involving a "can't change
      directory" symptom when fetching the entire contents of a directory; but
      I've been unable to reproduce the problem and I'm still not quite sure of
      the precise nature of the problem.

   3. Apparently some proxy servers can't handle multiline responses to FTP
      commands. If you hit this problem, you might be able to solve it by
      deleting the file WELCOME.MSG.


ΓòÉΓòÉΓòÉ 4.5. Non-standard features ΓòÉΓòÉΓòÉ

NON-STANDARD FEATURES

The program violates RFC959 in the following ways:

   1. Extra commands SIZE and MDTM are implemented.

   2. The SYST command returns a reply of UNIX rather than OS/2. I had to do
      this because the "correct" reply causes WebExplorer to misinterpret the
      directory listings, and I'm told that at least one Microsoft ftp client
      will refuse to connect to a server that identifies itself as OS/2.

   3. The obsolete and non-official commands XMKD, XRMD, XPWD, XCUP, and XCWD
      are implemented.  (These became obsolete more than 10 years ago, and most
      ftp clients don't use them; but apparently one of the clients for Windows
      NT hasn't yet been updated to the current standard.)


ΓòÉΓòÉΓòÉ 5. Installation ΓòÉΓòÉΓòÉ

Installation

See also De-installation

You should have received this package in the form of a zip file. To install it,
simply unzip the file into a directory of your choice. (Presumably you've
already done this.)  The server is now ready to run.

The server itself is the program called ftpd.exe.  You can run it either by
double-clicking on the desktop icon, or by entering the command "ftpd" in a
command-line session.  (In the latter case, make sure you're in the right
directory, otherwise you'll end up running the ftpd that was supplied with
OS/2.)  Most people will want to put a program object or shadow for ftpd into
the startup folder, so that the server will run each time the system is booted;
but that's up to you.

Even though the server will work "out of the box", you still need to define the
user permissions so that clients can connect to the server. You can do this
either before running the server, or while it's running.  See Setting up the
User Permissions.

The file source.zip is optional.  If you're not interested in the source code,
you can delete it.

For some other options, see

     Command line parameters
     Running from inetd
     Running FtpServer detached
     Welcome messages


ΓòÉΓòÉΓòÉ 6. De-installation ΓòÉΓòÉΓòÉ

De-installation

FtpServer does not tamper with CONFIG.SYS or with other system files. If you
decide that you don't want to keep FtpServer, simply delete the directory into
which you installed it.


ΓòÉΓòÉΓòÉ 7. Setting up the User Permissions ΓòÉΓòÉΓòÉ

 User Permissions

     General concepts
     Setting up users with the PMSetup program
     Setting up users with the VIOSetup program
     Manual configuration


ΓòÉΓòÉΓòÉ 7.1. User permissions: General concepts ΓòÉΓòÉΓòÉ

 GENERAL CONCEPTS

Each user of the server has a login name (username), a password, and a tree of
accessible directories.  Typically this tree consists of one home directory and
all of its subdirectories, but more complex arrangements are possible.  The
system manager may, by the use of symbolic links, allow the tree to cross
multiple drives or even multiple nodes on the local area network.  The system
manager may also allow access to a directory but block access to specified
subdirectories of that directory.  In all cases, a user is restricted to using
the directories that the system manager has specified for that user.  Users
cannot get at, or even see, any other directories in the machine's file system.
Furthermore, users are not told the true physical paths of those directories
that they are allowed to see.

Note:  In this context, "user" refers to a username rather than to a person.
For example, you might have a number of different people all accessing the
server via the username "anonymous". As far as the server is concerned, they
are not separate users, but rather separate instances of the user called
"anonymous".

The server looks up the user information in an INI file called FTPD.INI, which
should be in the same directory as ftpd.exe. This INI file is created and
maintained by the PMSetup or VIOSetup utility, as explained below.

There are two ways to create and edit the user permissions.

   1. By using the VIOSetup or PMSetup program that is supplied with FtpServer.
      (VIOSetup and PMSetup do the same job, except that one of them is a
      text-mode program and the other isn't.) This is the recommended method,
      for compatibility with future releases of FtpServer, and also because
      this method ensures that you produce syntactically correct permission
      data.  The procedure is described in the sections Using the PMSetup
      utility and Using the VIOSetup utility.

   2. Manually, using any text editor.  The details can be found in the section
      Manual configuration.  Manual configuration is supported for the benefit
      of existing FtpServer users who have become used to doing it this way;
      but it is not the recommended method, because it's too easy to make
      mistakes.

 User categories

 Each user is classified as one of the following.

   G       Guest user, who has to provide an e-mail address as a password.

   U       Normal user, who has to supply a password

   N       User who does not need a password.

   M       Manager: same as U, except that a manager gets some extra
           privileges.

 Normally you would create one "manager" account for yourself, and use the G or
 U categories for all other users.  The N category is for those rare cases
 where you don't need to control access with a password.

 Directory permissions

 Each directory that is accessible to the user is described by some combination
 of the following five permission attributes.

   V       Directory visible.  This should be set in most cases.  When it's not
           set, the client can't do a "change directory" to this directory, and
           it won't appear in directory listings.

   R       Read permission.  If this is set then the client can download files
           from this directory.

   W       Write permission.  If this is set then the client can upload files
           to this directory.

   D       Delete permission.  If this is set then the client can delete files
           from this directory.  Note: to overwrite an existing file, both W
           and D permissions are needed.

   N       Rename permission.  If this is set then the client can rename files
           in this directory.  Note: if the rename results in moving a file to
           a different directory, then the N permission flag is no longer
           relevant.  In that case, the user needs a D permission for the
           source directory and a W permission for the destination directory.

 Remark  It is possible for a user to be given read, write, delete, and/or
         rename privileges to an invisible directory.  In such cases the users
         can perform the permitted operations only if they know the correct
         file name, including the directory name, because they won't see the
         directory name in a directory listing.

 It's also possible for an invisible directory to have visible subdirectories.
 Users can get to those directories only if they know the path name, including
 the name of the invisible directory.

 Symbolic links

 A symbolic link is a pointer to some other part of the machine's file system.
 You - the system manager - can insert symbolic links in any directory. From
 the user's point of view, a symbolic link looks like just another
 subdirectory.

 A symbolic link has a name (which is what the user sees) and a physical path
 (which is known only to the system manager).  The physical path must be either
 a null string, or a full path name including the drive letter.

 A symbolic link normally points to a directory, but it is also possible to
 create a symbolic link to a file that is not a directory.

 Note that the user cannot see any difference between a symbolic link and an
 ordinary file or subdirectory name.  All that the user sees is a single
 directory tree that starts with a root node called "/".

 Pseudo-directories

 It is possible to specify a symbolic link whose physical path is unspecified.
 (That is, it is an empty string.)  This creates a pseudo-directory: something
 that ftp clients will see as a directory, but which does not correspond to any
 physical directory.  A pseudo-directory cannot hold any real files, but it can
 contain symbolic links.

 The main use for a pseudo-directory is for the case where you want to give a
 user access to several unrelated directories, possibly on different drives.
 To do this, you make the user's top-level directory a pseudo-directory, and
 then put links in that directory to the directories that the user is allowed
 to see.


ΓòÉΓòÉΓòÉ 7.2. Manual configuration ΓòÉΓòÉΓòÉ

 Manual configuration of users

This section describes how to edit a permission file.  It can be skipped by
most people, because in most cases it's better to use the PMSetup or VIOSetup
program to automate the editing.

If the user information is already in the server's INI file (e.g. because you
used the PMSetup utility to add this user), then the first thing you need to do
is to use the StorePRM utility to create a PRM file for this user. (Of course
this step is not needed if you have an existing PRM file for the user.)  After
editing the PRM file, which you can do with any text editor, you can use the
LoadPRM utility to load the information back into the INI file.

A PRM file is free-format, i.e. the exact formatting is not important; but, for
the sake of readability, I suggest that you use indentation etc. to make its
structure clearer.

The file can include comments.  A comment is anything from the '%' sign to the
end of the current line.  Note, however, that comments will be stripped out
when the LoadPRM program loads the data into the server's INI file.

File names containing spaces or special characters should be delimited by
either double quote marks ("...") or single quote marks ('...').  For "normal"
file names the quotation marks are optional.  (But see the warning later in
this page.)

The first five things in a permission file are:

   1. The user category code (G, U, N, M), as described in the General concepts
      section.

   2. The password.  For a guest user, put "@" as the password. For an 'N'
      user, just supply a dummy entry here.

   3. The user limit (a numeric value).

   4. This user's speed limit (a numeric value).

   5. The user's real name.

 Next, you may have some notes - up to 2048 characters - starting with the
 character pair '(*' and finishing with '*)'.  If the strings (* and *) occur
 inside the notes, they must occur as properly nested matched pairs.

 Finally you specify the directory information, in the format

     <directory name> <directory descriptor>

 where <directory name> specifies the user's root directory.  There are two
 possible ways to specify a <directory name>:

     <namestring>
     <namestring> = <namestring>

 where a <namestring> is any string of characters, optionally enclosed in
 quotation marks.  The first alternative - the one without the '=' sign - would
 not normally be used in specifying the root directory, but it is the normal
 form for specifying a subdirectory (see below). The second alternative
 specifies a symbolic link.  In that case the <namestring> before the '=' sign
 is the directory name as seen by the ftp client, and the <namestring> after
 the '=' sign is a full path name, starting with a drive letter.

 At the root level, the directory name is not seen by the user in any case, and
 the full path name is very often a null string, in order to specify a
 pseudo-directory.  Thus, a very common form of specification for the
 root-level directory is simply

     ""=""

 A <directory descriptor> gives the permissions for this home directory and all
 of its subdirectories.  It has the form

     <code> <subdirectory info>

 Both of these are optional.  The <code> can be any combination of

   V+      Directory visible
   V-      Directory invisible
   R+      Allow reads (i.e. downloads) of files in this directory
   R-      Deny read
   W+      Allow write
   W-      Deny write
   D+      Allow delete
   D-      Deny delete
   N+      Allow rename
   N-      Deny rename

 The permission codes are always to be interpreted relative to the parent
 directory's permission code.  That is, a directory has the same permissions as
 its parent, unless explicitly changed by adding and/or deleting permissions.

 (For the root directory, the default permissions are: visible, read, no write,
 no delete, no rename.)

 The <subdirectory info> is defined recursively.  It has the form

     (  <item> ,  <item> ,  ...  , <item> )

 i.e. it is a comma-separated list of items, surrounded by parentheses.  Each
 <item> has the form

     <directory name>  <directory descriptor>

 That is, it follows exactly the same rules as described above for the root
 directory.  The recursive nature of the rules means, of course, that the
 <directory descriptor> for any subdirectory may contain specifications of
 further subdirectories, down to any desired level.

 If this sounds complicated, take a look at the supplied *.PRM files, and
 you'll soon pick up the pattern.

 Note:  You don't have to list all of the subdirectories - only the ones whose
 permissions are different from the permissions of the parent directory.

 Example 1

 Suppose you want the user "anonymous" to have read access to the directory
 C:\users\pub; read and write access to C:\users\pub\upload; no access at all
 to C:\users\pub\private; and read access to all other subdirectories of
 C:\users\pub.  Then the permission file ANONYMOUS.PRM should have the
 following contents.

      G                         % user category = guest
      @                         % password = e-mail address
      10                        % user limit
      2000                      % speed limit
      ""                        % no real name recorded
      (*This is a guest account*)   % notes to store in INI file
      pub="C:/users/pub/" V+R+  % user's root directory
        ( upload W+,            % allow write access to upload directory
          private V-R- )        % deny all access to private directory

 Example 2

 Suppose you want the user "user1" to have read and write access to drive A:;
 read-only access to directory C:\users\pub and all of its subdirectories; read
 and write access to D:\abc and all of its subdirectories; and read and delete
 access to E:\Apps. To make the example more interesting, let us suppose that
 we want to make the directory on E: look like a subdirectory of D:\abc\def.
 You can do this by creating a permission file USER1.PRM with the following
 contents.

      U                         % normal user
      secret                    % password
      2                         % user limit
      6000                      % speed limit
      "Bart MacHomer"           % real name
      (*Created April 1999*)    % notes to store in INI file
      ""="" W+                  % root directory is a pseudo-directory
         ("A"="A:",
          "pub"="C:/users/pub" W-,
          "dir1"="D:/abc"
            (def
              ("apps"="E:/Apps" W-D+)
            )
         )

 Remark: FtpServer considers the forward slash (/) and backslash (\) to be
 equivalent in filename strings.

 Warning about potential syntax errors

 The software that parses a permission file tries to be as non-rigid as
 possible; for example, it does not insist that the characters in passwords,
 directory names, etc. be alphanumeric characters.  This flexibility comes at a
 price: you can write permission files that seem to be correct, but which are
 syntactically ambiguous.

 To avoid problems, it is a good idea always to enclose directory and file
 names in quotation marks.

 Converting from older formats

 The rules for specifying directories, as described on this page, were
 introduced in version 0.71 of FtpServer.  For version 0.70 and earlier, the
 rules were slightly different.  Both the old and new formats will be supported
 in versions 0.71 up to 0.80, but after that the old format will no longer be
 accepted.  Thus, you should convert all your old PRM files to the new format.

 The conversion can be done with the LoadPRM utility, which can read PRM files
 in either the old or new format but will store the data (in FTPD.INI) in the
 new format.  A quick way to convert all your PRM files into the new format is
 to execute the two commands

          loadprm *
          storeprm *

 Note that this will strip all comments out of the files.  If you want to keep
 the comments, you will have to do some manual editing.


ΓòÉΓòÉΓòÉ 7.3. Manager privileges ΓòÉΓòÉΓòÉ

Manager privileges

A manager account is the same as a normal user account, except that a manager
has a few extra privileges.

     Managers can see system and hidden files in directory listings; other
      users cannot.

     Managers are allowed to use the SITE MNGR commands.


ΓòÉΓòÉΓòÉ 8. The PMSetup utility ΓòÉΓòÉΓòÉ

The PMSetup utility

When you run PMSetup, you get a notebook that controls all of the configuration
details of FtpServer.  The parameter settings are stored in a file FTPD.INI.
The server reads its INI file as it starts up, so any changes you make will not
take effect until the next time you start the server.

Exception: the user permissions are not read until a user attempts to log in.
You may therefore alter the user permissions while the server is running, and
the alterations will affect the next user to log in.

The opening screen of PMSetup gives you a choice between local and remote
configuration.  (The remote case is described in a later section.) If you want
to bypass this choice, you can use the command

         pmsetup -G

and this will skip the opening dialogue and continue as if you had pressed the
"GO" button.  In this case, the local/remote option remains as it was the last
time you ran PMSetup.

The setup details are divided into four groups.

     Basic
     Options
     Security
     Users


ΓòÉΓòÉΓòÉ 8.1. The basic server settings ΓòÉΓòÉΓòÉ

The basic server settings

The first part of the "Basic" page controls the following parameters.

 Port number
           This is the tcp port on which FtpServer listens for new connections.
           Unless you are doing something nonstandard (for example, running two
           ftp servers on the same machine) this should always be 21.

 Maximum number of users
           This specifies how many clients will be allowed to use the server
           simultaneously. I usually set this to 10.  Higher values will, of
           course, increase the potential load on your processor.

           Note: this is a global maximum.  You may also set this to a very
           high value, and then control the number of users on a per-username
           basis.

 Maximum number of guest users
           This typically should be slightly less than the number specified for
           the maximum number of users, to reserve one or more login slots for
           the system manager and other non-guest users.

 Free space threshold (MB)
           This specifies the amount of free space that must be available on a
           drive for uploads to be enabled.  If the free space, in megabytes,
           falls below this level then uploads will be disabled.

 Timeout (seconds)
           The time that a client session may remain idle before the user is
           evicted. You will find that many ftp clients, especially web
           browsers, don't log out properly, so their sessions have to be
           killed with the timeout mechanism.

 Transfer logging

 You can ask the server to produce a user log (FTPUSERS.LOG) and/or a log in
 common log format (COMMON.LOG). (If you delete these files, they will be
 re-created.  It would be a good idea to delete them periodically, or move them
 to an archive, so that they do not grow too large.)  The user log produces a
 list of files that have been uploaded or downloaded.  The common log contains
 similar information, but in a format used by many http servers.  This allows
 you to use log analysis tools that have been designed for web servers.

 You can select how much detail gets written to these two logs.

 No transfer logging
           This effectively disables the transfer logging.

 Log successful transfers
           The log includes entries for all uploads and downloads that
           completed successfully, but the operations that failed are not
           logged.

 Log all file transfers
           With this option, you get log entries even for transfers that were
           aborted before they completed.

 Log all clients
           This creates user log entries for all users, even those who didn't
           transfer any files.

 Transaction logging

 The transaction log is a much more detailed log.  You can choose to send it to
 the screen, or to a disk file, or both. The disk file is called FTPTRANS.LOG,
 and it is updated approximately once every 15 minutes if this feature is
 enabled.

 Warning: Transaction logging can create very large log files.  I suggest that
 you don't enable transaction logging to a file unless you're trying to track
 down a problem. Logging to the screen, on the other hand, will give you some
 idea of how busy the server is.


ΓòÉΓòÉΓòÉ 8.2. Options ΓòÉΓòÉΓòÉ

Options

In the present version, the only option on this page is a choice between
binding to all local interfaces, or binding to a specific IP address.  If you
choose the "specific address", you should enter an IP address in the standard
format (four decimal numbers, separated by dots).

For most applications, the best choice is "all interfaces".  With this choice
the server listen for ftp requests on all your network interfaces, even if your
machine has multiple IP addresses.

The "specific address" option is for the case where you have two or more IP
addresses, but you want the server to respond to only one of them.  In this
case you could, if you wished, run several independent ftp servers on the same
machine, each responding to a different address.

(Another way to run several ftp servers is to make each one listen on a
different port.  That's a less attractive option, however, because most ftp
clients expect to find the server on the standard port 21.)

If you do run multiple copies of ftpd.exe, put each of them in a different
directory.  This is because ftpd.exe expects to find its INI file in the same
directory as the executable, and for multiple copies you would want to have a
different INI file for each one.


ΓòÉΓòÉΓòÉ 8.3. Security settings ΓòÉΓòÉΓòÉ

Security settings

The first item on the "Security" page is a field called "Max connections from
same address".  This specifies the maximum number of users that can be
connected simultaneously from the same IP address.  It is primarily a
protection against users who hog the server by logging in more than once.  I
usually set it to 2 or 3.  If you do not want this protection, set the number
to a very large value.

Restricting access to certain IP addresses

The large box on this page defines a filter for IP addresses.  This is for
putting restrictions on which remote hosts are allowed to log into the server.
(If you don't need this feature, just use a single "Allow all" entry.)  When a
client tries to connect, the server searches this list, starting at the
beginning, for the first entry that matches the client's IP address.  There
will always be a match, because the last entry is always an "everything else"
entry. The allow/refuse flag on the matching entry is used to decide whether
the client should be allowed to connect.  If the flag value is "refuse", the
connection attempt is rejected.

Each list entry has an allow/refuse flag and two numeric components, an address
and a mask.  Each of these is expressed in "dotted quad" notation: a four-byte
value where each byte has its value written out in decimal. (This is a standard
convention for writing IP addresses.) A client address matches an entry if

    (client IP address) AND mask = (IP address in the list)

where AND means the bit-by-bit Boolean "logical AND" operation.

Note, in particular, the two extreme cases:

     If the mask is 255.255.255.255, then we are specifying an exact match
      between the client IP address and the address in the list.

     If the mask were 0.0.0.0, then any IP address would match this entry. The
      last entry in the list is implicitly of this form, to specify an
      "everything else" condition.

 Example 1. If you want to lock out all machines with IP address in the range
 123.45.67.0 to 123.45.67.127, your list would look like this.

      Refuse  123.45.67.0  255.255.255.128
      Allow   all others

 Example 2. Suppose you want to give access only to your local network, which
 has addresses in the range 123.45.66.0 to 123.45.67.255.  You can do this as
 follows.

      Allow   123.45.66.0  255.255.254.0
      Refuse  all others

 Example 3. To allow access to 123.45.67.89, but to lock out everyone else in
 123.45.67.*, you can use the rules

      Allow   123.45.67.89  255.255.255.255
      Refuse  123.45.67.0   255.255.255.0
      Allow   all others

 Notice that the list always finishes with an "all others" entry.  The PMSetup
 program will allow you to change the allow/refuse flag on this final entry,
 but it will not allow you to delete it.


ΓòÉΓòÉΓòÉ 8.4. Adding and removing users ΓòÉΓòÉΓòÉ

Adding and removing users

The "Users" page controls who is allowed to log in to the server.

Deleting a user

Select the entry you want to delete, then click on the "Delete" button.

Adding a new user

Click on the "Add" button, and then proceed as for Editing a user's
permissions.

Cloning an existing user

First select the user whose details you want to duplicate, then click on the
"Clone" button, and then proceed as for Editing a user's permissions. This is
the same as adding a new user, except that the new user's attributes are copied
from those for an existing user.

Editing the permissions of an existing user

Select the user name, click on the "Edit" button, and then follow the
instructions in the section Editing a user's permissions. Alternatively, just
double-click on the user name.


ΓòÉΓòÉΓòÉ 8.5. Editing a user's permissions ΓòÉΓòÉΓòÉ

Editing a user's permissions

You get to this point by running the PMSetup program and choosing any of the
options (except "Delete") on the "Users" notebook page.

The first item in the resulting dialogue is a client category - NoPassword,
Guest, User, or Manager.  The categories are explained in the General concepts
section.

Below this you have several entry fields.

   Speed limit
           An approximate upper bound on the file transfer speed for this user,
           in case you want to restrict how much of the processor power this
           user can get.  If you don't want such a control, just make this a
           large number.

   User limit
           The maximum number of simultaneous sessions with this user name. (If
           you don't want such a control, just make this number larger than the
           global user limit.)

   Real name
           This field is purely for your own records.  It is not used by
           FtpServer.

   Username
           The name that the user will use when logging in.

   Password
           This user's password.  Note that this entry field is disabled if the
           user category is "NoPassword" or "Guest".

   Notes
           Use this for any purpose you wish.

 Warning: If you change the user name, the permissions for the previous user
 name will be deleted.  You should also avoid using a user name that is the
 same as for some other user.

 The small window near the bottom of this dialogue gives a summary - but not a
 complete description - of the top level of this user's directory tree.  To see
 the complete details, and to modify those details, click on the "Edit
 directories" button or double-click on the summary window.

 Instructions for modifying the user's tree are on the next page of this
 document.

 Note that none of your changes will be stored until you have confirmed them
 with the "OK" button.  To leave this dialogue without making any changes, use
 the "Cancel" button.

 Converting from older formats

 Some details of the format of user information in FTPD.INI were changed in
 version 0.71 of FtpServer.  Both the old and new formats are supported in
 versions 0.71 up to 0.80, but support for the old format is gradually being
 withdrawn.  Thus, you should convert all your user permission data to the new
 format.

 The PMSetup program will automatically perform the conversion each time you
 edit a user.  If you have a small number of users defined, then the way to do
 the conversion is to run PMSetup and edit each user (without necessarily
 making any changes).

 If you have a large number of users, it is easier to use the LoadPRM program
 to do the conversion.  This can be done with the following sequence of
 commands.

          storeprm *
          loadprm *
          del *.prm

 (The final deletion can be omitted if you prefer to keep a copy of the PRM
 files.  If ever your INI file is damaged or destroyed, you can use the LoadPRM
 utility to re-load user data from PRM files.)


ΓòÉΓòÉΓòÉ 8.6. Editing a directory tree ΓòÉΓòÉΓòÉ

Editing a directory tree

You get to this point while editing a user's permissions. The picture that is
shown on the screen is a representation of the directory tree for this user.
Initially it will show enough subtrees to reveal all symbolic links, and all
entries for which the user's permissions are different from the parent node's
permissions.  (For a new user, there will be nothing except an empty root
node.)  In the course of editing this tree you can expand or collapse nodes to
control how much detail is shown on the screen.

The top of the screen shows both a physical path and a virtual path for the
current entry.  The physical path is the true location of the file or directory
on your disk.  The virtual path is the path as the client sees it.

Each entry describes one directory or file.  At the left of each line, you will
see a code consisting of one or more of the letters "VRWDN". The meanings of
these user permission codes are explained in the General concepts section.

To the right of the VRWDN code, some entries have one or more of the following
codes.

   +       This directory is collapsed, i.e. its subdirectories (if any) are
           not at present displayed on the screen.

   *       This entry is a symbolic link or pseudo-directory.

   #       This entry describes a file rather than a directory.

   ?       There is no file or directory on the disk that matches this entry.
           This might mean that you have made an error in the name;
           alternatively, it might mean that you are specifying a directory or
           file that you haven't yet created.

 To edit the tree, you have the following options.

     You can navigate through the list of directories with mouse clicks, with
      the cursor up/down keys, and also with the Home, End, PageUp, and
      PageDown keys.

     To change a permission, type one of the characters V, R, W, D, or N, or
      click on the buttons with these labels. This toggles the state of the
      corresponding permission code for the currently selected directory.

     The "-" key or button collapses a directory by removing its
      subdirectories from the screen listing. (The subdirectories are still
      there, and are still affected by things like the "Propagate" option.
      They simply aren't shown on the screen.) To get the subdirectories back,
      type the "+" key or button.

     The "Add child" button adds a new child node under the current node.

     The "Edit" button allows you to edit the details for the current entry.
      (Instructions for doing this are given later in this page.)  You can also
      edit by double-clicking on the entry. This option is disabled if the
      current entry describes a file or directory that is physically present on
      the disk.

     The "Delete" button deletes the current node and all of its subtrees.
      This option is disabled if the current entry describes a file or
      directory that is physically present on the disk.

     The "Inherit" button gives the selected entry a copy of the current
      permissions of its parent.

     The "Propagate" button copies the permissions of the currently selected
      directory to all of its subdirectories. Use this if you want to change an
      entire subtree in one operation.

 When you've finished editing the permissions, click on the "Done" button to go
 back to the previous dialogue.  If you've made a mistake, you still have the
 option of using the "Cancel" button on that previous dialogue.

 Modifying the details for one entry

 The "Edit" and "Add child" options will bring up a screen window that
 describes one tree node. The radio buttons at the top let you specify one of
 three kinds of node.

   subdirectory or file
           This refers to a subdirectory or file that is contained within the
           parent directory.  The "Name" field gives the name of the
           subdirectory or file. Note that you cannot choose this option for
           the top-level directory, because the top-level directory has no
           parent.

   link
           This creates a symbolic link.  In the "Name" field, put a name of
           your own choice; this will be the name of the directory as seen by
           the client.  In the "Path" field, put the full physical path
           (including drive letter) for this directory or file.

   pseudo-directory
           This is a special case of a link, where there is no physical path. A
           pseudo-directory should contain only links and other
           pseudo-directories.

 Setting permissions for individual files

 The access permissions used by FtpServer are normally given to directories,
 and the permissions for a directory apply to all non-directory files in that
 directory.  However, PMSetup will let you define an entry for a non-directory
 file, and give it access permissions.  (It would be tedious to do this for
 every file, but this feature can be used for special cases.)  This gives you a
 method for making the permissions for a file different from the permissions of
 the directory that it is in.

 If you create a link or pseudo-directory with the same name as a real file or
 subdirectory, your link will take precedence over the real name. In effect,
 the real file or subdirectory will become invisible as far as the user is
 concerned.


ΓòÉΓòÉΓòÉ 9. Remote configuration ΓòÉΓòÉΓòÉ

PMSetup also offers the option of remote setup.  That is, you can run PMSetup
on one computer and use it to configure a copy of FtpServer that is installed
on a different computer.  To do this, you have to have the freeware utility
INIServe running on the same computer as FtpServer.  You can find INIServe at
http://eepjm.newcastle.edu.au/os2.

If you select the "Remote" radio button after starting PMSetup, a "Setup"
pushbutton is enabled.  Clicking on this gives you four fields to fill in:

   Hostname
           The name (or IP address) of the machine on which FtpServer is
           running.

   INIServe port
           The TCP port that INIServe has been configured to listen on.  The
           default value is 8000.

   INIServe password
           The password needed to log in to your copy of INIServe.

   FtpServer directory
           The full path name of the directory, on the remote machine, where
           FtpServer is installed.

 When you close the Setup window, you can click on the "GO" button to connect
 to the remote machine.  If this gives a "failed to connect" or similar error
 message, it probably means that you don't have INIServe running on the remote
 machine, or that you've done something like specifying an incorrect port
 number.

 Once the connection is made, the operation is the same as for the case of
 local configuration.


ΓòÉΓòÉΓòÉ 10. The VIOSetup utility ΓòÉΓòÉΓòÉ

The VIOSetup utility

The program VIOSETUP.EXE has three functions:

     To set the parameters that the server will use when it starts up.
     To place controls on which IP addresses may access the server.
     To create and edit user permissions.

 Use the F4 and F5 function keys on the keyboard to toggle among these
 functions.

 The parameter settings are stored in a file FTPD.INI.  The server reads its
 INI file as it starts up, so any changes you make will not take effect until
 the next time you start the server.

 Exception: the user permissions are not read until a user attempts to log in.
 You may therefore alter the user permissions while the server is running, and
 the alterations will affect the next user to log in.

 Now read

     Setting the server parameters
     Security settings
     More setup options
     Modifying user permissions


ΓòÉΓòÉΓòÉ 10.1. Setting the server parameters ΓòÉΓòÉΓòÉ

Setting the server parameters

When you run VIOSETUP.EXE, you get a screen showing the following items.

 Server port
           Unless you are doing something nonstandard (for example, running two
           ftp servers on the same machine) this should always be 21.

 Maximum number of users
           This specifies how many clients will be allowed to use the server
           simultaneously. I usually set this to 10.  Higher values will, of
           course, increase the load on your processor.

           Note: this is a global maximum.  You may also set this to a high
           value, and then control the number of users on a per-username basis.

 Maximum number of guest users
           This typically should be slightly less than the number specified for
           the maximum number of users, to reserve one or more login slots for
           the system manager and other non-guest users.

 Free space threshold (MB)
           This specifies the amount of free space that must be available on a
           drive for uploads to be enabled.  If the free space, in megabytes,
           falls below this level then uploads will be disabled.

 Timeout (seconds)
           The time that a client session may remain idle before the user is
           evicted. You will find that many ftp clients, especially web
           browsers, don't log out properly, so their sessions have to be
           killed with the timeout mechanism.

 Transfer log format
           In addition to the detailed transaction log, you can ask the server
           to produce a user log (FTPUSERS.LOG) and/or a log in common log
           format (COMMON.LOG). (If you delete these files, they will be
           re-created.  It would be a good idea to delete them periodically, or
           move them to an archive, so that they do not grow too large.)  The
           user log produces a list of files that have been uploaded or
           downloaded.  The common log contains similar information, but in a
           format used by many http servers.  This allows you to use log
           analysis tools that have been designed for web servers.

 Transfer logging level
           The logging level controls how much detail gets written to the user
           log.

              0           No logging

              1           Log successful file transfers

              2           Log successful and unsuccessful file transfers

              3           Log all users, even those who didn't transfer any
                          files

 Transaction logging
           The transaction log is a much more detailed log.  You can choose to
           send it to the screen, or to a disk file, or both. The disk file is
           called FTPTRANS.LOG, and it is updated approximately once every 15
           minutes if this feature is enabled.

           Warning: Transaction logging can create very large log files.  I
           suggest that you don't enable this feature unless you're trying to
           track down a problem.

 To modify any of these parameters, use the up/down arrow keys to get to the
 desired item, then type in the new value.  (The backspace, Insert, Delete,
 Home, and End keys will also work during editing.)  The new value is accepted
 when you type the Enter key, or when you use the function keys to go to
 another field.

 When you've finished editing, use the Esc key to exit from the VIOSetup
 program, or type F5 to get to the security screen.


ΓòÉΓòÉΓòÉ 10.2. Security settings ΓòÉΓòÉΓòÉ

Security settings

To modify the security settings, run VIOSETUP.EXE, and then type the F5
function key on the keyboard to get to the "Security" screen page.

At the top of this page there is a field called the "Same IP limit".  This
specifies the maximum number of users that can be connected simultaneously from
the same IP address.  It is primarily a protection against users who hog the
server by logging in more than once.

Set this value to whatever you want, finishing with the "Enter" or "cursor
down" key to confirm the new value.  The "cursor down" key will take you to the
IP address controls, as described below.  When you've finished setting the
values on this page, type F5 to get to more setup options.

Restricting access to certain IP addresses

The large box on this screen page defines a filter for IP addresses.  This is
for putting restrictions on which remote hosts are allowed to log into the
server. (If you don't need this feature, just use a single "Allow all" entry.)
When a client tries to connect, the server searches this list, starting at the
beginning, for the first entry that matches the client's IP address.  There
will always be a match, because the last entry is always an "everything else"
entry. The allow/refuse flag on the matching entry is used to decide whether
the client should be allowed to connect.  If the flag value is "refuse", the
connection attempt is rejected.

Each list entry has an allow/refuse flag and two numeric components, an address
and a mask.  Each of these is expressed in "dotted quad" notation: a four-byte
value where each byte has its value written out in decimal. (This is a standard
convention for writing IP addresses.) A client address matches an entry if

    (client IP address) AND mask = (IP address in the list)

where AND means the bit-by-bit Boolean "logical AND" operation.

Note, in particular, the two extreme cases:

     If the mask is 255.255.255.255, then we are specifying an exact match
      between the client IP address and the address in the list.

     If the mask is 0.0.0.0, then any IP address will match this entry. You
      can use this to specify an "everything else" condition.

 Example 1. If you want to lock out all machines with IP address in the range
 123.45.67.0 to 123.45.67.127, your list would look like this.

      Refuse  123.45.67.0  255.255.255.128
      Allow   all others

 Example 2. Suppose you want to give access only to your local network, which
 has addresses in the range 123.45.66.0 to 123.45.67.255.  You can do this as
 follows.

      Allow   123.45.66.0  255.255.254.0
      Refuse  all others

 Example 3. To allow access to 123.45.67.89, but to lock out everyone else in
 123.45.67.*, you can use the rules

      Allow   123.45.67.89  255.255.255.255
      Refuse  123.45.67.0   255.255.255.0
      Allow   all others

 Notice that the list always finishes with an "all others" entry.  The VIOSetup
 program will allow you to change the allow/refuse flag on this final entry,
 but it will not allow you to delete it.


ΓòÉΓòÉΓòÉ 10.3. More setup options ΓòÉΓòÉΓòÉ

More setup options

In the present version, the only option on this page is a choice between
binding to all interfaces, or binding to a specific IP address.  Use the cursor
left/right keys to highlight the option you want.  If you highlight "specific
address", you will be given the opportunity to edit the address. After editing
it, use the Enter key or a cursor up/down key to confirm that you've finished
editing.  When you've finished setting the values on this page, type F5 to get
to the user permission editor.

For most applications, the best choice is "all interfaces".  With this choice
the server listen for ftp requests on all your network interfaces, even if your
machine has multiple IP addresses.

The "specific address" option is for the case where you have two or more IP
addresses, but you want the server to respond to only one of them.  In this
case you could, if you wished, run several independent ftp servers on the same
machine, each responding to a different address.

(Another way to run several ftp servers is to make each one listen on a
different port.  That's a less attractive option, however, because most ftp
clients expect to find the server on the standard port 21.)

If you do run multiple copies of ftpd.exe, put each of them in a different
directory.  This is because ftpd.exe expects to find its INI file in the same
directory as the executable, and for multiple copies you would want to have a
different INI file for each one.


ΓòÉΓòÉΓòÉ 10.4. Modifying user permissions ΓòÉΓòÉΓòÉ

Modifying user permissions

To modify the user permissions, run VIOSETUP.EXE, and then type the F4 function
key - or type F5 twice - to get to the "Users" screen page.  This will give you
a list of all existing users.  The first time you run the program, the list
will probably be empty.

From this screen, you can add, delete, or modify users.  When you've finished,
use the F4 or F5 function key to get to the other setup screens, or type X to
exit from the VIOSetup program.

Deleting a user

Use the up/down arrow keys to get to the user you want to delete, and type the
Del (delete) key.

Adding a new user

Type A, and then proceed as for Editing a user's permissions.

Cloning an existing user

Type C, and then proceed as for Editing a user's permissions. This is the same
as adding a new user, except that the new user's attributes are copied from
those for the user that was selected when the C command was typed.

Editing the permissions of an existing user

Type E, and then follow the instructions in the section Editing a user's
permissions.


ΓòÉΓòÉΓòÉ 10.5. Editing a user's permissions ΓòÉΓòÉΓòÉ

Editing a user's permissions

You get to this point by running the VIOSetup program, typing F4 or F5 to get
to the user editor, and then using one of the "A" (add user) or "E" (edit user)
options.

By now you should have six fields near the top of the screen.

   User name
           The name that the user will use when logging in.

   Real name
           This field is not used by FtpServer; it is purely for your own
           records.

   Category
           One of User, Guest, NoPassword, or Manager.

   Password
           This user's password.

   User limit
           The maximum number of simultaneous sessions with this user name. (If
           you don't want such a control, just make this number larger than the
           global user limit.)

   Speed limit
           An approximate upper bound on the file transfer speed for this user,
           in case you want to restrict how much of the processor power this
           user can get.  If you don't want such a control, just make this a
           large number.

 Use the up/down arrow keys to get to the field you want to edit, and then
 modify it as necessary.  For the "Category" field, use the left/right arrow
 keys to select a category.

 Warning: If you change the user name, the permissions for the previous user
 name will be deleted.  You should also avoid using a user name that is the
 same as for some other user.

 The bottom half of this screen gives a summary - but not a complete
 description - of the top level of this user's directory tree.  To see the
 complete details, and to modify those details, use the "cursor down" key to
 move to this part of the screen.

 Instructions for modifying the user's tree are on the next page of this
 document.

 Converting from older formats

 Some details of the format of user information in FTPD.INI were changed in
 version 0.71 of FtpServer.  Both the old and new formats are supported in
 versions 0.71 up to 0.80, but in later versions the old format will probably
 no longer be accepted.  Thus, you should convert all your user permission data
 to the new format.

 The VIOSetup program will automatically perform the conversion each time you
 edit a user.  If you have a small number of users defined, then the way to do
 the conversion is to run VIOSetup and edit each user (without necessarily
 making any changes).

 If you have a large number of users, it is easier to use the LoadPRM program
 to do the conversion.  This can be done with the following sequence of
 commands.

          storeprm *
          loadprm *
          del *.prm

 (The final deletion can be omitted if you prefer to keep a copy of the PRM
 files.  If ever your INI file is damaged or destroyed, you can use the LoadPRM
 utility to re-load user data from PRM files.)


ΓòÉΓòÉΓòÉ 10.6. Editing a directory tree ΓòÉΓòÉΓòÉ

Editing a directory tree

You get to this point while editing a user's permissions. The picture that is
shown on the screen is a representation of the directory tree for this user.
Initially it will show enough subtrees to reveal all symbolic links, and all
entries for which the user's permissions are different from the parent node's
permissions.  (For a new user, there will be nothing except an empty root
node.)  In the course of editing this tree you can expand or collapse nodes to
control how much detail is shown on the screen.

The top of the screen shows both a physical path and a virtual path for the
current entry.  The physical path is the true location of the file or directory
on your disk.  The virtual path is the path as the client sees it.

Each entry describes one directory or file.  At the left of each line, you will
see a code consisting of one or more of the letters "VRWDN". The meanings of
these user permission codes are explained in the General concepts section.

To the right of the VRWDN code, some entries have one or more of the following
codes.

   +       This directory is collapsed, i.e. its subdirectories (if any) are
           not at present displayed on the screen.

   *       This entry is a symbolic link.

   #       This entry describes a file rather than a directory.

   ?       There is no file or directory on the disk that matches this entry.
           This might mean that you have made an error in the name;
           alternatively, it might mean that you are specifying a directory or
           file that you haven't yet created.

 To edit the tree, you have the following options.

     You can navigate through the list of directories with the cursor up/down
      keys, and also with the Home, End, PageUp, and PageDown keys.

     To change a permission, type one of the characters V, R, W, or D. This
      toggles the state of the corresponding permission code for the currently
      selected directory.

     Typing the "I" key gives the selected entry a copy of the current
      permissions of its parent.

     The "P" key copies the permissions of the currently selected directory to
      all of its subdirectories. Use this if you want to change an entire
      subtree in one operation.

     The "-" key collapses a directory by removing its subdirectories from the
      screen listing. (But these subdirectories will still be affected by the
      "P" option.) To get the subdirectories back, type the "+" key.

     The "A" key adds a new child node under the current node.

     The "Del" key deletes the current node and all of its subtrees. This
      option is disabled if the current entry describes a file or directory
      that is physically present on the disk.

     The "E" key allows you to edit the details for the current entry.
      (Instructions for doing this are given later in this page.) This option
      is disabled if the current entry describes a file or directory that is
      physically present on the disk.

 When you've finished editing the permissions, type B to go back to the
 previous screen, or X to exit completely from VIOSetup.

 Modifying the details for one entry

 The "E" or "A" command will bring up a screen window with three details that
 you can modify.  Use the cursor up/down keys to go from one field to another.

   1. The Name field gives the subdirectory or file name.

   2. The Link field should have value "no" for an ordinary subdirectory or
      file, and "yes" for a symbolic link.  Use the cursor left/right keys to
      change the value of this field.

   3. The Path is the physical path (including drive letter) for this directory
      or file.  You can modify this only if the Link field is set to "yes".  If
      you leave the Path blank, you are defining a pseudo-directory.

 When you have finished editing these details, type the Esc key to return to
 the tree.

 Setting permissions for individual files

 The access permissions used by FtpServer are normally given to directories,
 and the permissions for a directory apply to all non-directory files in that
 directory.  However, VIOSetup will let you define an entry for a non-directory
 file, and give it access permissions.  (It would be tedious to do this for
 every file, but this feature can be used for special cases.)  This gives you a
 method for making the permissions for a file different from the permissions of
 the directory that it is in.


ΓòÉΓòÉΓòÉ 11. Running the server ΓòÉΓòÉΓòÉ

Running the server

The server executable is called FTPD.EXE.  You can run this the way you run any
other OS/2 program: from the command-line, by clicking on an icon, from the
Startup folder, etc.  If you're running several server applications, then the
most obvious choice is to put a command to start the server in the command file
\TCPIP\BIN\TCPSTART.CMD.

Normally the server takes its configurable parameters from the INI file created
by the setup program.  You may, however, override these parameters by
specifying command-line parameters.

You also have the options of running the server from inetd or running the
server as a detached program.

Once the server is running, two keyboard commands are available.

   G       Gradual shutdown.  No new users are accepted.  The program will
           terminate when the existing users have logged off (or timed out), or
           when a Q comand is issued.

   Q       Quick shutdown.  The program closes down even if there are logged-in
           users.


ΓòÉΓòÉΓòÉ 11.1. Command line parameters ΓòÉΓòÉΓòÉ

Command line parameters

Normally you don't need any parameters when invoking FTPD.EXE, because the
server takes its parameters from the INI file.  (And the contents of the INI
file are controlled by the setup program.)  You may, however, override the
parameters in the INI file by giving command-line parameters.

There are several optional parameters. These all have the form of a letter
followed by a (decimal) number, and they can be given in any order.

   D       Detailed transaction logging (default 0).

                0         No logging
                1         Logging to the disk file FTPTRANS.LOG
                2         Logging to the screen
                3         Logging to both the screen and the disk file

   F       Free space threshold (megabytes).  Users can't upload to a drive
           that has less than this amount of free space available. The default
           is 10.

   G       Maximum number of guest users.  If you make this smaller than the
           value for M (see below), you effectively reserve some slots for
           non-guest users.  The default is M-1.

   L       User logging option (default 1).

                0         No logging
                1         Logging of successful file transfers
                2         Logging of successful and unsuccessful file transfers
                3         Logging of all users

           The log is a text file called FTPUSERS.LOG.  You can edit it or
           delete it without doing any harm.

   M       Maximum number of simultaneous users.  To limit the number to 12,
           for example, use the command
                  ftpd m12
           The default is 10.

   P       The server's port number.  To make the server listen on port 5003,
           for example, you start the program with the command
                  ftpd p5003
           The default port number is 21.

   T       Timeout limit, i.e. the time before an inactive user is forcibly
           removed.  The value is in seconds, and the default is 900.


ΓòÉΓòÉΓòÉ 11.2. Running from inetd ΓòÉΓòÉΓòÉ

Running the server from inetd

Inetd, which is part of the Warp 4 distribution, is a "listener" program that
can intercept incoming connection attempts, and start up a server when needed.

The advantage is that FtpServer doesn't actually get loaded into main memory
until a client wants to connect.  Thus, it might be a good option if you expect
clients to connect only occasionally.

The disadvantage is that a separate copy of the server is started for each
logged-in user.  This makes inetd a bad choice if you expect lots of
connections.

If you want to run FtpServer from inetd, the way to do it is as follows:

   1. Ensure that inetd will be run the next time you boot. The usual way of
      doing this is to include the line
            start /min inetd
      in your TCPSTART.CMD, and to invoke TCPSTART.CMD from your startup
      folder.  TCPSTART.CMD may be found in the directory \tcpip\bin.

   2. Edit the file \mptn\etc\inetd.lst so that it contains the line
         ftp tcp start /C /min d:\Apps2\FtpServer\ftpd.exe
      (adjusting the path so that it refers to the directory where you've
      installed FtpServer).

 Note:  In earlier releases the inetd users had to use a file called ftpd.cmd.
 That command file is now obsolete.

 You may also include parameters on the inetd.lst line that invokes ftpd.exe,
 subject to the following conditions:

   1. The M parameter is useless, because in this mode of operation the program
      is handling exactly one user.

   2. The P parameter, if present, will be ignored.  When running from inetd,
      you don't get a choice of ports.

 In principle you can now start inetd.  In practice I've found that inetd
 doesn't release ports reliably, so if you already have inetd running you'll
 probably have to re-boot.

 Remark: I'm starting to suspect that inetd adds more overhead than it saves,
 so I've reverted to not using it on my own machine.


ΓòÉΓòÉΓòÉ 11.3. Running FtpServer detached ΓòÉΓòÉΓòÉ

Running the server as a detached program

If you want to run the server detached, the appropriate command is
    DETACH FTPD
(with parameters, if desired).  Note that a detached program does not have any
way of doing screen output or keyboard input, so you can't get any screen
messages in this case.  Nor can you use the keyboard G and Q commands.

Although you can't shut down the server from the keyboard in this case, you can
still shut it down by using the SITE MNGR commands.


ΓòÉΓòÉΓòÉ 11.4. Welcome messages ΓòÉΓòÉΓòÉ

Welcome messages

If you want to give a message to users when they log in, put a plain text file
called WELCOME.MSG or WELCOME0.MSG in the same directory as ftpd.exe.

     WELCOME0.MSG, if present, is displayed to the user when the initial
      connection is made.
     WELCOME.MSG, if present, is displayed to the user after the username and
      password have been accepted.

 You can use both of these options together, if you wish, but it would probably
 be less confusing to the users if you had only one message.

 You can also put a text file called DIR.MSG in any user directory. Users will
 get this message the first time they go to that directory.

 There is a limited form of macro expansion available in these message files.
 The following macros may be included.

   %i"filename" Includes the contents of the given file in the message. Nesting
           is permitted; that is, the included file may also contain a %i
           macro.  In the case of WELCOME.MSG or WELCOME0.MSG the filename may
           be given as an absolute pathname, but if relative then it is
           relative to the directory in which ftpd.exe is running.  (Note that
           you should never give non-trusted users access to this directory.)
           In the case of DIR.MSG, the filename is interpreted in the way the
           client sees the file system - i.e. if relative then it is relative
           to the client's current directory - and the client must have
           permission to read this file.

   %m      Expands to a character string giving the maximum allowed number of
           users with the current username.

   %M      Expands to a character string giving the global maximum allowed
           number of users.

   %t      Expands to a string giving the local time.

   %T      For now, this is the same as %t.

   %u      Expands to a string giving a user number within this user's group.

   %U      Expands to a string giving this user's global user number.

   %%      The '%' character.


ΓòÉΓòÉΓòÉ 11.5. The SITE commands ΓòÉΓòÉΓòÉ

The SITE commands

The SITE PERM command

The command SITE PERM returns a three-character string showing whether you have
read, write, and/or delete permission for the current directory. (This command
was added while I was testing a new feature.  It might be withdrawn in future
versions, because it's not particularly useful for most users.)

The SITE MNGR commands

Commands in this group may be used only from a manager account. Currently the
following options are available.

 SITE MNGR EXEC
           Runs another program.  See below for further details.

 SITE MNGR EXIT
           Shuts down the server.  (Don't do this unless you really mean it!)

 SITE MNGR GXIT
           Shuts down the server after the current users have logged out - i.e.
           the same action as for the keyboard G command.

 SITE MNGR KILL nnn
           Forcibly logs out user number nnn. The number must match the one
           returned by the SITE MNGR LIST command.

 SITE MNGR LIST
           Returns a list of currently logged-in users. The main purpose of
           this command is to support the Monitor utility.

 The SITE MNGR EXEC command starts a new program in a separate session. (If
 FtpServer is running detached, then the new program must also run detached.)
 For example, you could zip up the user log with the command

        site mngr exec zip.exe today.zip ftpusers.log

 If you want to run a batch file then you need to start a suitable command
 shell.  For OS/2 command files and Rexx programs, the appropriate shell is
 cmd.exe, as in the following example.

        site mngr exec cmd.exe /c test.cmd parameter1 parameter2


ΓòÉΓòÉΓòÉ 12. The Monitor utility ΓòÉΓòÉΓòÉ

The Monitor utility

The program MONITOR.EXE allows the system manager to see who is currently
logged in, and to kill sessions where necessary.  This program can be run
either on the same machine as the server, or remotely.

There is one optional parameter, which is the name of this program's INI file.
Normally you don't have to specify this, because the name MONITOR.INI is
assumed by default.  This option exists for the case where you want to run
multiple copies of the monitor to monitor different servers, or to use a
different font or screen size/position.

When you start the program, it attempts to connect to the server.  If it fails
to establish a connection, this might mean that the server is not running.
Alternatively, it might mean that you are attempting to connect to the wrong
machine, or to the right machine with the wrong manager account. In the latter
case, see the setup instructions below.

Once the program has made a connection to the server, it displays one line per
client session. This shows the time the session started, the IP address of the
client, and the username. Once you select one item of this display, you will
also see the last command issued, and in some cases a display of how many bytes
have been transferred in the current operation.

Clicking on the "kill user" button will terminate that client session and
forcibly log out the user.

The "kill server" button allows you to shut down the server.  (Don't do this
unless you really mean it.)  You will be asked to confirm the shutdown by
selecting either "gradual shutdown" or "quick shutdown".  The difference is
that the "gradual shutdown" doesn't terminate the server until all existing
clients have logged out.

Setting up the Monitor parameters

Clicking on the setup button gives you a dialogue with the following items.

  Hostname
           This specifies the machine on which the server is running, for
           example mymachine.here.net.  If the machine has a fixed IP address,
           you can avoid a nameserver lookup by specifying a numeric address,
           for example 123.45.67.89

  Port
           This should normally be 21, but you might have set up the server to
           accept connections from a non-standard port.

  Username
           This must be the username for a manager account.

  Password
           The password for the manager account.

  Update interval
           The time (in seconds) between queries to the server to get the user
           details.  The smaller this value, the more load you're putting on
           the server.  A value between 5 and 10 seconds is usually a good
           compromise.

 When you've finished filling in these details, close this window (or type the
 Enter key) to return to the Monitor main display.


ΓòÉΓòÉΓòÉ 13. The TMonitor utility ΓòÉΓòÉΓòÉ

The TMonitor utility

TMONITOR.EXE is an older version of the monitor program.  It is included in
this distribution for those who prefer to have a text-mode application.

When you start the program, it attempts to connect to the server.  If it fails
to establish a connection, this might mean that the server is not running.
Alternatively, it might mean that you are attempting to connect to the wrong
machine, or to the right machine with the wrong manager account. In the latter
case, see the instructions for Setting up the Monitor parameters.

To kill a client session, use the cursor up/down keys to get to the desired
session, and then type the K key.

To shut down the server, type Ctrl/K.  (Hold down the Ctrl key while typing K.)
You will be asked to confirm the shutdown by typing either G (for a gradual
shutdown) or Q (for a quick shutdown).

To close the TMonitor program, type the X key.

Hint:  If you want to use less screen space, issue the command
     MODE CO80,10
before running TMonitor.exe.


ΓòÉΓòÉΓòÉ 13.1. Setting up the Monitor parameters ΓòÉΓòÉΓòÉ

Setting up the Monitor parameters

When running TMONITOR.EXE, typing S on the keyboard takes you to the setup
screen. There you will see four fields that have to be filled in.

  Server hostname
           This specifies the machine on which the server is running, for
           example mymachine.here.net.  If the machine has a fixed IP address,
           you can avoid a nameserver lookup by specifying a numeric address,
           for example 123.45.67.89

  Server port
           This should normally be 21, but you might have set up the server to
           accept connections from a non-standard port.

  User name
           This must be the username for a manager account.

  Password
           The password for the manager account.

 When you've finished filling in these details, press the Esc key to return to
 the TMonitor main screen.


ΓòÉΓòÉΓòÉ 14. The LoadPRM and StorePRM utilities ΓòÉΓòÉΓòÉ

The LoadPRM utility

This utility is needed if you want to manually edit user permission files. It
copies information from a PRM file into the server's FTPD.INI.  For example,
the command

       loadprm example

takes the information in the file EXAMPLE.PRM and creates or updates an entry
in the INI file for a user called "example".

Wildcards are permitted. To load the information from all the PRM files in the
current directory, use the command

       loadprm *

You do not have to restart the server. The updated user information will take
effect the next time a user logs in.

The StorePRM utility

This utility creates a PRM file by copying the user information from FTPD.INI.
You would use it if the INI file already contains user data that you want to
edit manually. For example, the command

       storeprm example

takes the information in the INI file for the user called "example", and uses
it to create a file EXAMPLE.PRM. (If EXAMPLE.PRM already exists, the original
copy is renamed EXAMPLE.BAK.)

Wildcards are permitted. To create PRM files for all the existing users, use
the command

       storeprm *


ΓòÉΓòÉΓòÉ 15. The LogAnalysis utility ΓòÉΓòÉΓòÉ

The LogAnalysis utility

LogAnalysis.exe is a utility to produce a summary from the FtpServer user log.
You run it with the command

        LogAnalysis logfilename

where "logfilename" is the name of the user log file.  If no parameter is
supplied, it assumes that the log file name is FTPUSERS.LOG.

The results are written to standard output.  You can redirect this to a file,
for example

        LogAnalysis AUGUST.LOG >August.summary


ΓòÉΓòÉΓòÉ 16. Development notes ΓòÉΓòÉΓòÉ

     Development tools

     Why Modula-2?

     Known bugs

     Unresolved issues

     Reporting errors

     Year 2000 compliance


ΓòÉΓòÉΓòÉ 16.1. Development tools ΓòÉΓòÉΓòÉ

Development tools

Some people have asked about the compiler I'm using.  (I guess a lot of people
didn't realise that there were Modula-2 compilers for OS/2.)  It's XDS
Modula-2, OS/2 native mode version.  You can find out about this, and other
Modula-2 compilers for OS/2, at the web page
   http://www.ee.newcastle.edu.au/users/staff/peter/os2/os2m2.html
(I'm getting a little behind on keeping my web pages up to date, but the
information is still basically correct, only the version numbers have changed.)

The XDS home page is at
   http://www.xds.ru/
This is well worth visiting, because the XDS development team often has "try
before you buy" versions of their compilers available for download.

FtpServer uses some of the modules from the PMOS/2 library. If you want to know
more about PMOS/2, you'll also find that on my web pages.  Source code is
available.  My web pages are at
http://www.ee.newcastle.edu.au/users/staff/peter/Moylan.html.

This documentation was prepared with IBM's IPFC help compiler.


ΓòÉΓòÉΓòÉ 16.2. Why Modula-2? ΓòÉΓòÉΓòÉ

Why Modula-2?

I'm often asked why I chose to code FtpServer in Modula-2.  Everyone else seems
to be using C or C++, so why don't I?

The short answer is that I don't think much of the "everyone else uses it"
argument.  If popularity was more important to me than technical merit, I
wouldn't be using OS/2.

The long answer is contained in a document called "The Case Against C", which
can be found at
http://murray.newcastle.edu.au/users/ftp/pub/reports/CaseAgainstC.ps.Z. This is
a compressed Postscript file.  If you can't handle compressed Postscript, a
text-only version (CaseAgainstC.txt) can be found in the same directory.

And the medium-length answer is on this page.

To begin with, run-time efficiency is not as big an issue as most people seem
to think it is.  With modern compiler technology, the main programming
languages (apart from things like BASIC and its derivatives) give about the
same run-time efficiency.  C and C++ lose out a little because their low-level
constructs make it hard for the compiler to do a good job at optimisation; the
figures I've seen tend to suggest that a program written in Modula-2 runs a
little faster than the same program written in C or C++. However, the
difference is typically less than 5%, and hardly worth worrying about.

So the big issue is development efficiency.  For a job like this we can rule
out languages like BASIC and REXX because they're a little too crude; and we
can rule out languages like Fortran because of their poor support for "systems
programming" tasks.  We can also rule out a host of lesser-known languages
because of the unavailability of OS/2 compilers.  That leaves us with Pascal,
Ada, Oberon, Modula-2, C, and C++.

I don't use Pascal because Modula-2 is basically an upgraded Pascal, and I
might as well use the improved version.

I haven't looked into the availability of Ada compilers for OS/2; but in any
case I don't like Ada because of its complexity.  The bigger a language is, the
more things there are to go wrong.

Oberon is a more subjective matter.  Some people will tell you that Oberon is
the successor to Modula-2, and is a superior programming language.  My personal
opinion is that Oberon has deleted some of the features that make Modula-2 a
good language.  I agree, however, that this issue is not entirely clear-cut.

That brings us to C and C++.  I've done a lot of C and C++ programming over the
years, and it's left me with the feeling that those languages are major
barriers to programming efficiency.  It takes me roughly twice the time to get
a C or C++ program working as it does to get a comparable Modula-2 program
working.  (On some projects I've kept logs to verify this.)  The coding time is
roughly the same, but there's a major difference in debugging time.  Everyone I
know writes buggy software in C and C++, and then they take forever trying to
track down the bugs.  Some developers give up, and sell the software with the
bugs still included.

There are two main reasons why C software is so bug-prone.

   1. Lack of type safety.  C is designed in such a way that the compiler can't
      do much error checking, so the compiler gives no warnings for things
      that, in a type-safe language, would be reported as errors at compile
      time.  You don't see the errors until execution time, and then you're
      left wondering what caused the error.

   2. Poor support for modular programming.  You can break up a C program into
      modules, but they're not truly independent of one another.  A slight
      change in one module can have catastrophic effects on other modules.
      Once a project grows moderately large, you lose control of your own code.

 C++ is a little better in these two respects, but C++ has problems of its own.
 The language designers tried to graft high-level features onto a low-level
 language, and the result is a mass of inconsistency.  A C++ reference manual
 is typically several times as thick as manuals for other programming
 languages, because every rule has a maze of exceptions and special cases.

 In addition, I've noticed that a lot of C++ programmers seem to have adopted
 the philosophy of "let's try this, and hope that it works".  The notion that
 you shouldn't write code that you don't understand seems to have become
 unfashionable.  Maybe that's the fault of the language (and its libraries),
 maybe not.  In any case, it's not the way I prefer to work.

 Ultimately, the reason I use Modula-2 is that it lets me get applications
 working quickly, it gives me control of large projects, and it doesn't force
 me to spend huge amounts of time on debugging.  I'm too old to enjoy the
 thrill of tracking down obscure bugs.  I like to get something working, and
 then be free to move on to other projects.

 Of course, it's difficult to guarantee that any piece of software is bug-free,
 no matter what development tools you use.  But I can have the next-best thing,
 which is an acceptably small error rate.


ΓòÉΓòÉΓòÉ 16.3. Known bugs ΓòÉΓòÉΓòÉ

KNOWN BUGS IN SERVER

     Server shutdown does not work correctly when using version 4.02k of the
      TCP/IP stack, although it does work with earlier versions.  Other
      information I've received seems to indicate that *ALL* server
      applications misbehave with version 4.02k, so it looks as if the fault
      lies in the TCP/IP implementation. I have fixed the problem for version
      4.02o, but the fix might not work with 4.02k - my impression is that
      versions between k and o are seriously buggy.

     Uploads not accepted if your free disk space is greater than about 4000
      gigabytes.  There doesn't seem to be any urgent need to fix this just
      yet, but at the rate disk sizes are growing ...

 See also Unresolved issues


ΓòÉΓòÉΓòÉ 16.4. Unresolved issues ΓòÉΓòÉΓòÉ

Unresolved issues

These are problems that various people have reported, but which I haven't been
able to duplicate. I'd be interested in hearing from anyone who can confirm
either that the problem really exists, or that it's now fixed.

     Reported: the server can be crashed by a client running JavaScript. This
      problem is still a mystery to me, I haven't been able to track down
      what's going on.


ΓòÉΓòÉΓòÉ 16.5. Year 2000 compliance ΓòÉΓòÉΓòÉ

Year 2000 compliance

According to my tests, FtpServer should continue running correctly until 31
December 2079.  (It might also continue working after that; but the OS/2 system
clock will not allow me to set the date to 2080 or later.)  This assumes that
you are using HPFS disks.

Systems using the FAT file system will stop working in 2038. This has nothing
to do with FtpServer; it's a fundamental limitation of FAT.


ΓòÉΓòÉΓòÉ 16.6. Reporting errors ΓòÉΓòÉΓòÉ

If you find any error that's not mentioned in this document, please report it
to [e-mail].  The following information would be useful in
tracking down the cause of the error:

     The version number of the version you are using.

     The file errinfo.$$$, if it exists.

     Some information about what the server was doing at the time the problem
      occurred; for example, the last few lines of the transaction log.