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

OS/2 Help File | 1998-08-11 | 47KB | 1,294 lines

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

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

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/html/software

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

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 750 Belgian francs to the following bank account

           Marion Gevers
           Account number 210-0384103-35
           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.

At present, the only languages available are English and Russian.  (The Russian
version is ftpserver.inf.866.)  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 Russian translation belongs to 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 most 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
      multiple home directories, if desired.

     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 Setup program
     Manual configuration


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

 GENERAL CONCEPTS

Each user of the server has a login name (username), a password, and one or
more home directories.  Users may access their home directories, including any
subdirectories, but they cannot get at, or even see, any other directories in
the machine's file system.  Optionally, you can also block access to specified
subdirectories of their home directory.

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 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 Setup utility, as explained below.

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

   1. By using the Setup program that is supplied with FtpServer. This is the
      recommended method, for compatibility with future releases of FtpServer,
      and also because this method ensures that you produce syntactically
      correct permission files.  The procedure is described in the section
      Using the Setup 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 four 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.

 Remark  It is possible for a user to be given read, write, and/or delete
         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.

 Multiple home directories

 When a user has just one home directory, that directory appears to the user to
 be the root directory.  (The user does not see the true name of the
 directory.)  There is no way for users to see any directories other than the
 home directory and its subdirectories.

 When a user has more than one home directory, each home directory has a
 "volume name" chosen by the system manager.  One use for multiple home
 directories is to give a user access to files on more than one disk drive. In
 that case, you might choose to use the drive letter as the volume name; but
 that's not compulsory, you can choose the volume names arbitrarily.

 When the user logs in, each volume appears to be a subdirectory of the user's
 root directory.  Thus, the normal "change directory" commands can be used to
 step through the different volumes.

 Remark: the volume name is irrelevant in the case of a single home directory,
 because in that case the user never gets to see the volume name.


ΓòÉΓòÉΓòÉ 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 Setup program to
automate the editing.

If the user information is already in the server's INI file (e.g. because you
used the Setup 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 at the end
of this page.)

The first two 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.

 After that, you specify one or more volumes.  The volume information is in the
 form

     <volume name> = <home directory> <directory descriptor>

 The home directory must be given as a full path name, starting with a drive
 name and ending with the '/' character.

 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

 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 home directory, the default permissions are: visible, read, no write,
 no delete.)

 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>

 where the <directory descriptor> follows exactly the same rules as the
 <directory descriptor> for the home directory.  That is, it can also contain
 things like comma-separated lists of subdirectory information.

 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

 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
      "C:/users/pub/" V+R+  % home directory
        ( upload W+,       % allow write access to upload directory
          private V-R- )   % deny all access to private directory

 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.

 For example, suppose that a permission file contains two home directory
 specifications:

      C:/PUB/
      D:/XYZ/UVW/

 This looks OK, but in fact it confuses the parser.  When the parser sees the
 "D" on the second line, it thinks you're trying to enable delete permission
 for the home directory on the preceding line.  Having consumed the "D", it
 then decides that the drive name for the second directory is ":".

 The way to solve this problem is to put a semicolon at the end of the first
 line (or the beginning of the second line), to separate the two
 specifications.


ΓòÉΓòÉΓòÉ 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 Setup utility ΓòÉΓòÉΓòÉ

 The program SETUP.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 F5 function key 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
     Modifying user permissions


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

Setting the server parameters

When you run SETUP.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.

 User logging level
           The server creates a log file called FTPUSERS.LOG.  (If you delete
           the file, it will be re-created.  It would be a good idea to delete
           it, or move it to an archive, every month or so, so that it does not
           grow too large.)  The user logging level controls how much detail
           gets written to this file.

              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

 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.

 Transaction logging
           You can choose to send a detailed log 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 Setup program,
 or type F5 to get to the security screen.


ΓòÉΓòÉΓòÉ 8.2. Security settings ΓòÉΓòÉΓòÉ

Security settings

To modify the security settings, run SETUP.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 allow/deny lists, as described below.  When you've finished setting
the values on this page, type F5 to get to the user permission editor.

Restricting access to certain IP addresses

The two large boxes on this screen page are the "allow" and "deny" lists of IP
addresses.  These are for putting restrictions on which remote hosts are
allowed to log into the server. (If you don't need this feature, just leave the
two lists empty.) The server interprets the lists as follows.

     If a client address matches one of the entries in the "allow" list, then
      the client is allowed to proceed, and the "deny" list is ignored.

     Otherwise, the client is allowed to connect only if its IP address does
      not match any of the entries in the "deny" list.

 Each list entry consists of two 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, put an entry in the "deny" list with address
 123.45.67.0 and mask 255.255.255.128.  The "allow" list can be left empty in
 this case.

 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 by
 putting an entry in the "allow" list with address 123.45.66.0 and mask
 255.255.254.0.  To lock out everyone else, put an entry in the "deny" list
 with mask 0.0.0.0.

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

     put an entry in the "allow" list with address 123.45.67.89 and mask
      255.255.255.255
     put an entry in the "deny" list with address 123.45.67.0 and mask
      255.255.255.0


ΓòÉΓòÉΓòÉ 8.3. Modifying user permissions ΓòÉΓòÉΓòÉ

Modifying user permissions

To modify the user permissions, run SETUP.EXE, and then type the F5 function
key twice to get the 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 F5 function key to get back to the main Setup screen.

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.

Editing the permissions of an existing user

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


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

Editing a user's permissions

You get to this point by running the Setup program, typing 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 four fields near the top of the screen.

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

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

 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.

 Next, you have to go to the list of home directories, in the bottom half of
 the screen.  (For a new user, this list will initially be empty.)  Use the
 down-arrow key to get to the list, and then type either A (to add a home
 directory) or E (to modify an existing entry in the list of home directories).

 This gives you a new screen, where the top two lines are

  Virtual drive name
           This is the name that the user will see as the "directory name" for
           this home directory.

  Home directory
           This should be a full path name, starting with a physical drive name
           and finishing with the '/' character.  For example, it could be
           "C:/users/pub/" (without the quotation marks).  In this field, the
           software considers the characters '/' and '\' to be equivalent.

 After editing these two fields, use the "cursor down" key to go to the
 "directories" box on the screen.  There will be a short pause while the
 program builds a list of all subdirectories.  (If you have many
 subdirectories, it will be a long pause.)

 You are then presented with a list of subdirectories of this home directory.
 To the left of each directory name, you will see a code consisting of one or
 more of the letters "VRWD".  The meanings of these user permission codes are
 explained in the General concepts section.

 You might also see a "+" in front of some directory names.  This indicates
 that this directory is collapsed, i.e. it has subdirectories which are not at
 present displayed on the screen.

 At this point, 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 directory 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.

 When you've finished editing the permissions, type X to return to the previous
 screen.  Alternatively, you can get to the previous screen with the "cursor
 up" key.

 Now you're back in the list of home directories.  At this point you have the
 choice of adding more home directories, or leaving this list with the "Esc" or
 "cursor up" keys.

 When you've finished setting up all users, type the F5 key to get back to the
 main page of the Setup program.


ΓòÉΓòÉΓòÉ 9. 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.


ΓòÉΓòÉΓòÉ 9.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.


ΓòÉΓòÉΓòÉ 9.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.


ΓòÉΓòÉΓòÉ 9.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.


ΓòÉΓòÉΓòÉ 9.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 WELCOME2.MSG in the same directory as ftpd.exe.
WELCOME.MSG, if present, is displayed to the user when the initial connection
is made.  WELCOME2.MSG, if present, is displayed to the user after the username
and password have been accepted.  To avoid confusion, you should probably
choose to have only one of these two options.

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.

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


ΓòÉΓòÉΓòÉ 9.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 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.


ΓòÉΓòÉΓòÉ 10. 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.

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 Monitor program, type the X key.

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


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

Setting up the Monitor parameters

When running MONITOR.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 Monitor main screen.


ΓòÉΓòÉΓòÉ 11. 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 *


ΓòÉΓòÉΓòÉ 12. Development notes ΓòÉΓòÉΓòÉ

     Development tools

     Why Modula-2?

     Known bugs

     Unresolved issues

     Reporting errors

     Year 2000 compliance


ΓòÉΓòÉΓòÉ 12.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.


ΓòÉΓòÉΓòÉ 12.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
used to be found at ftp://ee.newcastle.edu.au/.  This server is temporarily
unavailable at present, so I'll try to find a new home for the document.

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.


ΓòÉΓòÉΓòÉ 12.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


ΓòÉΓòÉΓòÉ 12.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.


ΓòÉΓòÉΓòÉ 12.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.


ΓòÉΓòÉΓòÉ 12.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.