OS/2 Shareware BBS: 35 Internet

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / ftpser076.zip / ftpserver.INF (.txt) < prev next >

Wrap

OS/2 Help File | 1999-09-23 | 54KB | 1,533 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ FtpServer is an ftp daemon for OS/2. It is distributed as optional shareware. This documentation is for version 0.76. 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, peter@ee.newcastle.edu.au. 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.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 peter@ee.newcastle.edu.au. 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 750 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 peter@ee.newcastle.edu.au 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 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 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 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 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 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 data. 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. 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 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 later in this page.) The first three 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). After that, 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 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.) 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 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 ""="" 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 Setup utility ΓòÉΓòÉΓòÉ 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 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 ΓòÉΓòÉΓòÉ 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 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 Setup program will allow you to change the allow/refuse flag on this final entry, but it will not allow you to delete it. ΓòÉΓòÉΓòÉ 8.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. ΓòÉΓòÉΓòÉ 8.4. Modifying user permissions ΓòÉΓòÉΓòÉ Modifying user permissions To modify the user permissions, run SETUP.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 Setup 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. ΓòÉΓòÉΓòÉ 8.5. Editing a user's permissions ΓòÉΓòÉΓòÉ Editing a user's permissions You get to this point by running the Setup 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 five 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.) 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 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 user permission data to the new format. The Setup 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 Setup 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 "VRWD". The meanings of these user permission codes are explained in the General concepts section. To the right of the VRWD 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 Setup. 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, Setup 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. ΓòÉΓòÉΓòÉ 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 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. %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 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 ΓòÉΓòÉΓòÉ 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. 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 ΓòÉΓòÉΓòÉ 13. Development notes ΓòÉΓòÉΓòÉ Development tools Why Modula-2? Known bugs Unresolved issues Reporting errors Year 2000 compliance ΓòÉΓòÉΓòÉ 13.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. ΓòÉΓòÉΓòÉ 13.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. ΓòÉΓòÉΓòÉ 13.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 ΓòÉΓòÉΓòÉ 13.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. ΓòÉΓòÉΓòÉ 13.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. ΓòÉΓòÉΓòÉ 13.6. Reporting errors ΓòÉΓòÉΓòÉ If you find any error that's not mentioned in this document, please report it to peter@ee.newcastle.edu.au. 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.