HGFTP Manager's Guide

HGFTP Manager's Guide


March, 2004

This manual describes the installation and configuration of the HGFTP server software.

Revision/Update Information: This is a revised manual. Revision bars indicate changes made since the last version of this software.

Operating System and Version: OpenVMS VAX V5.0 or later

OpenVMS Alpha V1.5 or later

Software Version: HGFTP V3.1-2


04 March 2004

Permission is granted to copy and redistribute this document for no commercial gain.

The information in this document is subject to change without notice and should not be construed as a commitment by Hunter Goatley. The authors assume no responsibility for any errors that may appear in this document.

DISCLAIMER: The software described in this document is provided "as is." No guarantee is made by the authors as to the suitability, reliability, security, usefulness, or performance of this software.

The following are trademarks of Digital Equipment Corporation:
AXP VAX DEC OpenVMS
VMS UCX VAXcluster VMScluster

MultiNet is a registered trademark of Process Software, LLC.

TCPware is a trademark of Process Software, LLC.

Copyright ©2004 Hunter Goatley. All Rights Reserved.

Contents


Preface

FTP (File Transfer Protocol) is a TCP/IP subsystem that allows users to transfer files between a local system and remote systems.

HGFTP began life as the FTP client and server that were distributed with CMU-Tek TCP/IP, a mostly-free TCP/IP implementation written by Tektronix and Carnegie-Mellon University and supported by CMU. When the code was made freely available, support was picked up primarily by Henry Miller and John Clement.

HGFTP is based on John and Henry's CMU FTP V3.1. HGFTP works with the NETLIB TCP/IP Interface Library, which means that the HGFTP will run under any TCP/IP software supported by NETLIB. The following TCP/IP products are currently supported by NETLIB: Process Software's MultiNet and TCPware, Digital's DEC TCP/IP Services for OpenVMS, Wollongong's WIN/TCP and Pathway, and CMU-IP.

The NETLIB port was done by Darrell Burkhead, who based some of the changes on a much earlier UCX port (known as CRUX) done by Matt Madison. The OpenVMS Alpha port was done by Hunter Goatley.

NETLIB must be installed before you can use the HGFTP. NETLIB is written by Matt Madison and is a MadGoat Software product.

HGFTP is currently maintained by Hunter Goatley, PMDF Technical Manager for Process Software, LLC (goathunter@goatley.com).

Intended Audience

This manual is intended for any OpenVMS system manager wanting to use the HGFTP server. The reader should be familiar with VMSINSTAL and FTP principles.

Document Structure

This guide consists of four chapters.
Chapter 1 Provides a description of the HGFTP server.
Chapter 2 Provides descriptions of the HGFTP server logicals.
Chapter 3 Provides a description for setting up anonymous FTP accounts.
Chapter 4 Provides descriptions of the HGFTP server logicals for anonymous FTP.

Authors

Copyright © 1986, 1992, Carnegie Mellon University.
Copyright © 1994, 2001, Hunter Goatley. All rights reserved.

The CMU client and server were originally written by:

The MadGoat version was written by:

Since 1995, HGFTP has been maintained by:


Chapter 1
The HGFTP Server

FTP is a TCP/IP subsystem that implements the File Transfer Protocol for transferring files between a local system and one or more remote systems on an internet. The FTP client, invoked by the DCL command FTP, establishes a network link to an FTP server on the remote system. When the connection is established, you must log in to an account on that remote system. Once logged in, files can be transferred to and from the remote system, depending on the type of access allowed.

The HGFTP server provides all the features normally found in an FTP server, as well as support for anonymous FTP and STRU VMS. It was written primarily to allow sites running DEC TCP/IP Services for OpenVMS (formerly UCX) to provide true anonymous FTP access to their systems, though it can be used with virtually all of the TCP/IP packages for OpenVMS.

1.1 HGFTP Server Operation

The HGFTP server consists of two programs, FTP_LISTENER.EXE and FTP_SERVER.EXE. The FTP_LISTENER is executed as a detached process that listens for incoming FTP connection requests on port 21, the standard incoming FTP TCP/IP port number. Once a connection has been established and the remote client sends the username to log in as, the listener waits for and verifies the password. If the password is invalid, the connection is rejected. Otherwise, the listener creates a new process running FTP_SERVER.EXE and turns control of the FTP session over to the new process.

The FTP server processes all FTP commands issued by the remote client. The server does not exit until the remote client closes the port or logs out. If the remote client logs out, the server process returns control of the session to the FTP listener, which waits for a new login username.

1.2 Configuring the HGFTP Server

The HGFTP server is controlled by the use of various system logicals. All of the logicals begin with the prefix ``HG_FTP_''. The logicals are shown in tables Table 1-1 and Table 1-2. Each logical is described in detail in the sections following the tables.

The file HG_ROOT:[COM]FTP_LOGICALS.TEMPLATE should be renamed as FTP_LOGICALS.COM and edited to customize the various HGFTP logicals.

The logicals shown in Table 1-1 must be defined as executive-mode logicals in the system logical name table (LNM$SYSTEM_TABLE). For example:


$ DEFINE/SYSTEM/EXEC HG_FTP_TIMEOUT 600

Copyright © 1986, 1992, Carnegie Mellon University.
Copyright © 1994, 2001, Hunter Goatley. All rights reserved.

The HGFTP Listener and Server use the following logicals:

Table 1-1 General HGFTP Logicals
Logical Description
HG _FTP _220 _REPLY Specifies a message to be displayed as part of the " 220 " response greeting clients when they connect to the HGFTP Listener.
HG _FTP _221 _REPLY Specifies a message to be displayed as part of the " 221 " response generated when a client disconnects from the HGFTP Listener.
HG _FTP _ACCEPT _IP _LIST Specifies the IP addresses of systems allowed to connect to the local system via FTP.
HG_FTP_ACT_LOG+ Enables server activity logging.
HG_FTP_ACTIVITY Specified name of activity logs.
HG_FTP_ALLOW_PRIV_PORT Allow clients to specify privileged ports in PORT commands.
HG_FTP_ANON_LOG_DIR Specifies the device and directory in which anonymous FTP log files are stored.
HG_FTP_DIRS+ If defined, limits all FTP access to the specified directories.
HG_FTP_DO_UNIX_LS+ If defined, causes server directory displays to emulate the UNIX "ls" format if the specified directory name is given in a UNIX-style format. If defined as "ALWAYS", the server will always generate UNIX-emulation directory listings.
HG_FTP_HELP Points to the HGFTP client help library.
HG _FTP _HIDE _VMS _SYST Causes the system identification string returned by the server in response to the SYST command to hide the fact that this is a VMS system. Sometimes needed for proper UNIX-mode emulation.
HG_FTP_INIT+ Points to an FTP client initialization file.
HG_FTP_LISTENER_TIMEOUT Number of seconds that the HGFTP listener will leave an idle connection active.
HG_FTP_LOCAL_HOSTNAME+ Specifies the system name that should be displayed in the 220 greeting from the HGFTP listener.
HG_FTP_LOG+ Specifies the level of logging for FTP connections.
HG _FTP _MAXIMUM _SERVERS Specifies the maximum number of FTP connections supported by the server at any one time.
HG_FTP_QUOTE_PATHNAME+ Specifies whether replies to MKD and PWD server commands should place double quotes around the pathname.
HG_FTP_REJECT_user Disallows FTP access for user ``user'' and contains rejection message text.
HG _FTP _REJECT _IP _LIST Specifies the IP addresses of systems that are not allowed to connect to the local system via FTP.
HG_FTP_RESTRICT+ Specifies the directory access restrictions for FTP access.
HG_FTP_TILDE_ANONDIR Enables use of ``~username'' in directory specifications for anonymous users. Also specifies the name of the users' anonymous subdirectories.
HG_FTP_TIMEOUT+ Number of seconds that the HGFTP server will leave an idle connection active.
HG_FTP_USER_PROMPT+ Causes the client to automatically prompt for a username when a connection is made to a remote system.
HG_FTP_WELCOME+ Welcome message for general FTP access.
HG _FTP _WINDOW _SIZE Specifies the default window size used by HGFTP. The default value is 17520 bytes.


+May be overridden for individual users by defining the logical in the user's LOGIN.COM.

The logicals shown in Table 1-2 control anonymous FTP access to your system. Anonymous FTP is described in Chapter 3.

The anonymous FTP logicals must be defined as executive-mode logicals in the special HGFTP logical name table, HG_FTP_NAME_TABLE. This logical name table is automatically created by the HGFTP startup procedures. To define a logical in this table, use a command like the following:


$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$       HG_FTP_ANON_LOAD_LIMIT 1.0

Table 1-2 Anonymous HGFTP Logicals
Logical Description
HG_FTP_user_WELCOME The welcome message for anonymous user ``user''.
HG_FTP_user_DIRS Specifies the directories to which the anonymous user ``user'' has access.
HG_FTP_ANON_LOAD_LIMIT Enables checks to disallow access during ``prime times.''
HG_FTP_ANON_PRIME_START+ Starting time for ``prime time.''
HG_FTP_ANON_PRIME_END+ Ending time for ``prime time.''
HG_FTP_ANON_PRIME_DAYS+ ``Prime time'' during which anonymous ftp is restricted.


+Valid only when HG_FTP_ANON_LOAD_LIMIT is defined.


Chapter 2
The HGFTP General Logicals

This chapter describes the general logicals that control the HGFTP listener and server.

The logicals described must be defined as executive-mode logicals in the system logical name table (LNM$SYSTEM_TABLE). For example:


$ DEFINE/SYSTEM/EXEC HG_FTP_TIMEOUT 600

These logicals should be defined in the HGFTP startup procedure, HG_ROOT:[COM]FTP_STARTUP.COM.

2.1 HG_FTP_220_REPLY

The HG_FTP_220_REPLY logical specifies text that is to be sent back to the remote client upon a successful connection, but before a login. For example:


$ DEFINE/SYSTEM/EXEC HG_FTP_220_REPLY -
_$     "FTP.WKU.EDU -- Quality VMS Freeware and more"

If the logical's value begins with "@", the rest of the string is used as a file name whose contents are read and sent back to the remote client. For example, the following definition would cause the contents of FTP_220_REPLY.TXT to be read and sent back to the remote user:


$ DEFINE/SYSTEM/EXEC HG_FTP_220_REPLY -
_$     "@SYS$MANAGER:FTP_220_REPLY.TXT"

2.2 HG_FTP_221_REPLY

The HG_FTP_221_REPLY logical specifies text that is to be sent back to the remote client when the client disconnects from the server. For example:


$ DEFINE/SYSTEM/EXEC HG_FTP_221_REPLY -
_$     "Thanks for visiting FTP.WKU.EDU!"

If the logical's value begins with "@", the rest of the string is used as a file name whose contents are read and sent back to the remote client. For example, the following definition would cause the contents of FTP_221_REPLY.TXT to be read and sent back to the remote user:


$ DEFINE/SYSTEM/EXEC HG_FTP_221_REPLY -
_$     "@SYS$MANAGER:FTP_221_REPLY.TXT"

2.3 HG_FTP_ACCEPT_IP_LIST

The HG_FTP_ACCEPT_IP_LIST logical specifies the IP addresses of nodes and/or networks that are allowed FTP access to the local machine. By default, access is not restricted by IP address. You can control access by defining either of the logicals HG_FTP_ACCEPT_IP_LIST or HG_FTP_REJECT_IP_LIST.

Multiple addresses can be specified using multiple equivalence strings. All addresses not matching an address in the ACCEPT list will be refused connection to the FTP server. (See Section 2.19 to reject only certain addresses.)

Subnets may be specified by using the following format:


xxx.xxx.xxx.xxx/yy 

where ``yy'' is the number of significant bits in the network mask. For example, a value of "/29" means there are 29 significant bits in the subnet mask, which is a mask of 255.255.255.248 (or, in hexadecimal, FF.FF.FF.80).

Note

If this logical is defined, it must be defined /EXECUTIVE_MODE, and it must be defined in the HG_FTP_NAME_TABLE logical name table. This can be done automatically by adding the commands to the HG_ROOT:[COM]FTP_LOGICALS.COM file (see the FTP_LOGICALS.TEMPLATE file for other examples).

For example:


$ create/name_table/attr=super/exec-
_$      /parent=LNM$SYSTEM_DIRECTORY/nolog-
_$      /prot=(s:rwed,o:rwed,w:r) HG_FTP_NAME_TABLE
$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$    HG_FTP_ACCEPT_IP_LIST "10.1.2.3","224.32.32.34",-
_$    "66.170.199.220/29"

In this example, only connections from IP addresses 10.1.2.3, 224.32.32.34, and the subnet 66.170.199.220 would be allowed to connect. The "/29" specifies that there are 29 significant bits in the address (meaning a subnet mask of 255.255.255.248), which means .220--.228 would be allowed to connect.

Clients refused a connection will receive the following message:


421 Access denied, IP address rejected

The following rules are applied with the access logicals:

  1. If neither logical is defined, access is not restricted.
  2. If only the ACCEPT logical is defined, all connections are rejected unless the IP address is included in the equivalence for the logical.
  3. If only the REJECT logical is defined, all connections are accepted unless the IP address is included in the equivalence for the logical.
  4. If both logicals are defined, only specified ACCEPT addresses are accepted. If an address is accepted because it matches a specified network, the listener will check to make sure the particular IP address is not rejected explicitly.

2.4 HG_FTP_ACT_LOG

If defined, the logical HG_FTP_ACT_LOG causes the HGFTP server process to record information in the HGFTP activity logs. This information includes each command that is processed by the server, as well as connect and disconnect requests from the listener process.

To enable server activity logging, use a command like the following:


$ DEFINE/SYSTEM/EXEC HG_FTP_ACT_LOG TRUE

By default, the activity log file is created in HG_ROOT:[LOGS] as HG_FTP_ACTIVITY.LOG. You can specify a different name by defining the HG_FTP_ACTIVITY logical.

2.5 HG_FTP_ACTIVITY

The logical HG_FTP_ACTIVITY can be defined to specify an alternate file specification for the FTP activity logs. By default, the logs are created in HG_ROOT:[LOGS] as HG_FTP_ACTIVITY.LOG.


$ DEFINE/SYSTEM/EXEC HG_FTP_ACTIVITY LOCAL$LOGS:FTP.LOG

2.6 HG_FTP_ALLOW_PRIV_PORT

By default, the HGFTP server does not accept port numbers lower than 1024 on the PORT command received from clients. Allowing ports below 1024 is a potential security risk, as it could allow attackers to gain illegal access to RSH/RLOGIN ports.

There are some old FTP clients that only generate PORT commands with ports below 1024. You can force the HGFTP server to accept those ports by defining the logical HG_FTP_ALLOW_PRIV_PORT:


$ DEFINE/SYSTEM/EXEC HG_FTP_ALLOW_PRIV_PORT TRUE

2.7 HG_FTP_ANON_LOG_DIR

The logical HG_FTP_ANON_LOG_DIR points to the directory where the log files for ANONYMOUS logins are stored. If this logical is not defined, the logs are created in the login directory for the ANONYMOUS account. See Chapter 3 for information on creating anonymous FTP accounts.

The default file name is ANON_FTP_LOG.LOG. The logical ANON_FTP_LOG can be defined to specify a different file name.

2.8 HG_FTP_DIRS

The logical HG_FTP_DIRS is used to restrict FTP access to specified directories. If defined at the system level, the restrictions apply to all FTP access for all users. This logical can be overridden by individual users when added to a user's LOGIN.COM.

When this logical is defined, the access restrictions apply to the FTP session regardless of each account's VMS privileges.

HG_FTP_DIRS should be defined as a search list that specifies all the directories to which access is allowed. For example, the following command would restrict access to the [DIR] directory tree on DISK1:, all directories on DISK2:, and [PUBLIC] on DISK3:.


$ DEFINE/SYSTEM/EXEC HG_FTP_DIRS -
_$    DISK1:[DIR...],DISK2:[ANON...],DISK3:[PUBLIC]

Note

Defining HG_FTP_DIRS at the system level will restrict access for all users, unless the users override the logical definition. A user can override the directory restrictions by equating the logical to a space character:


$ define hg_ftp_dirs " "

2.9 HG_FTP_DO_UNIX_LS

By default, the HGFTP server generates directory listings in a VMS-style format. Unfortunately, many Web browsers assume the world is UNIX, and some of them have problems accessing VMS FTP sites. To ease the headaches caused by this, HGFTP can be told to generate UNIX-style directory listings in response to the LIST command from clients.

If the logical HG_FTP_DO_UNIX_LS is defined, the HGFTP server will generate UNIX-style directory listings if a UNIX-style path is specified on a CWD or LIST command. The logical should be defined with a command like this:


$ DEFINE/SYSTEM/EXEC HG_FTP_DO_UNIX_LS TRUE

You can also force the server to always generate UNIX-style listings by equating the logical to the string "ALWAYS":


$ DEFINE/SYSTEM/EXEC HG_FTP_DO_UNIX_LS ALWAYS

This logical can be defined by individual users.

2.10 HG_FTP_HELP

The logical HG_FTP_HELP points to the VMS on-line help library for the HGFTP client. Normally, the library is stored as HG_FTP_HELP.HLB in HG_ROOT:[HELP]. You can define this logical if you move the library file to another location.

2.11 HG_FTP_HIDE_VMS_SYST

The HG_FTP_HIDE_VMS_SYST logical may be used to camouflage the fact that the server is running on VMS by changing the string returned by the server in response to a SYST command from a client. This logical was added to better provide UNIX emulation that works well with various PC web browsers.

Netscape is actually smart enough to recognize that it's talking to a VMS system by checking the output generated in response to the SYST command. Unfortunately, when UNIX emulation was in effect, this caused Netscape to misinterpret the directory listing and display only the returned file names. Now, when the logical HG_FTP_HIDE_VMS_SYST is defined and UNIX emulation is in effect, the SYST response includes spaces to disguise the fact that it's a VMS system running HGFTP. This causes Netscape to interpret the file names and display file information for each file listed.


$ DEFINE/SYSTEM/EXEC HG_FTP_HIDE_VMS_SYST TRUE

2.12 HG_FTP_INIT

The HG_FTP_INIT logical points to an FTP client initialization procedure. When defined system-wide, the initialization file can be used to perform such operations as turning on the bell for the client.

This logical can be defined by individual users.

2.13 HG_FTP_LISTENER_TIMEOUT

The HG_FTP_LISTENER_TIMEOUT logical specifies the number of seconds that the HGFTP listener process will wait for a remote FTP client to log in. If the listener is idle longer than the specified number of seconds, the connection is automatically closed by the listener.

By default, the listener will keep a connection open for 5 minutes (300 seconds). The following command sets the listener timeout to 1 minute (60 seconds):


$ DEFINE/SYSTEM/EXEC HG_FTP_LISTENER_TIMEOUT 60

2.14 HG_FTP_LOCAL_HOSTNAME

The HG_FTP_LOCAL_HOSTNAME logical specifies the system name that should be displayed in the initial greeting from the HGFTP listener when a connection is established. By default, the system name as defined by your TCP/IP software is used. You can use this logical to override that name and display a different system name. For example, on KID.GOATLEY.COM, the banner normally looks like this:


220 kid.goatley.com HGFTP server V3.0-1 ready. 

To have it display "ftp.goatley.com" instead, you can use this command:


$ DEFINE/SYSTEM/EXEC HG_FTP_LOCAL_HOSTNAME "ftp.goatley.com"

which would result in this banner:


220 ftp.goatley.com HGFTP server V3.0-1 ready. 

2.15 HG_FTP_LOG

The HG_FTP_LOG logical controls the amount of information written to the file FTP_SERVER.LOG in each user's login directory. A log file is always created; by default, it only contains the connection information. By defining HG_FTP_LOG system-wide, you can enable additional logging for all users. Users can override this logical definition in their LOGIN.COM files.

The HG_FTP_LOG equivalence value is a number representing a bitmask. Each bit represents a particular kind of information. The value should be the sum of the following:
Value Meaning
0 Do not log anything.
1 Log the results of commands.
2 Log the commands entered and the time each was executed.
4 Include all data transferred in the log file. You generally do not want this option.

For example, the following creates a log file that contains a log of all commands and their results:


$ $ DEFINE/SYSTEM/EXEC HG_FTP_LOG 3

2.16 HG_FTP_MAXIMUM_SERVERS

The HG_FTP_MAXIMUM_SERVERS logical specifies the maximum number of FTP connections allowed at any one time. If this logical is not defined, or is defined as "0", a default value of 20 servers is used.


$ DEFINE/SYSTEM/EXEC HG_FTP_MAXIMUM_SERVERS 3

If the maximum number of servers allowed is 3, and 3 sessions are currently active, any additional connection attempts will be greeted with a 421 response, and the HGFTP Listener will drop the connection:


421 Access denied, server limited exceeded; try again later.

2.17 HG_FTP_QUOTE_PATHNAME

The logical HG_FTP_QUOTE_PATHNAME is used to control the output of type-257 server replies, which are returned by PWD and MKD server commands. For example:


>PWD 
<257 "SYS$SYSROOT:[SYSHLP]" is current directory. 

By default, pathnames will be quoted. However, if HG_FTP_QUOTE_PATHNAME is defined as either "F" or "N", the quotes will be omitted from the reply. This option has been provided for compatibility with some FTP clients that do not recognize quoted pathnames.

2.18 HG_FTP_REJECT_user

The logical HG_FTP_REJECT_user is used to reject FTP connections for username ``user.'' When defined, that username cannot be used for FTP access, even when a valid password is supplied. The rejection message is only seen after a successful login.

The value of the logical is used as the rejection message that is sent back to the remote FTP client. For example, the following definition would reject connections for username MCCAMMON:


$ DEFINE/SYSTEM/EXEC HG_FTP_REJECT_MCCAMMON "Sorry, dude!"

The remote user would see the following when trying to log in as MCCAMMON:


FTP:alpha> user mccammon
Attempting to login to user mccammon
<331 Username ``mccammon'' Okay, need password.
Password:
<530-Sorry, dude!
<530-Not logged in.
<530 Login attempt rejected.
Not logged In.
FTP:alpha>

If the reject message begins with "@", the rest of the string is used as a file name whose contents are read and sent back to the remote client. For example, the following definition would cause the contents of REJECT.TXT to be read and sent back to the remote user:


$ DEFINE/SYSTEM/EXEC HG_FTP_REJECT_MCCAMMON -
_$         "@SYS$MANAGER:REJECT.TXT"

Note

If you use the "@" form, be sure the rejected user has access to the text file.

2.19 HG_FTP_REJECT_IP_LIST

The HG_FTP_REJECT_IP_LIST logical specifies the IP addresses of nodes and/or networks that are not allowed FTP access to the local machine. By default, access is not restricted by IP address. You can control access by defining either of the logicals HG_FTP_ACCEPT_IP_LIST or HG_FTP_REJECT_IP_LIST.

Multiple addresses can be specified using multiple equivalence strings. All addresses matching an address in the REJECT list will be refused connection to the FTP server. (See Section 2.3 to allow only certain addresses to connect.)

Subnets may be specified by using the following format:


xxx.xxx.xxx.xxx/yy 

where ``yy'' is the number of significant bits in the network mask. For example, a value of "/29" means there are 29 significant bits in the subnet mask, which is a mask of 255.255.255.248 (or, in hexadecimal, FF.FF.FF.80).

Note

If this logical is defined, it must be defined /EXECUTIVE_MODE, and it must be defined in the HG_FTP_NAME_TABLE logical name table. This can be done automatically by adding the commands to the HG_ROOT:[COM]FTP_LOGICALS.COM file (see the FTP_LOGICALS.TEMPLATE file for other examples).

For example:


$ create/name_table/attr=super/exec-
_$      /parent=LNM$SYSTEM_DIRECTORY/nolog-
_$      /prot=(s:rwed,o:rwed,w:r) HG_FTP_NAME_TABLE
$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$    HG_FTP_REJECT_IP_LIST "10.1.2.3","224.32.32.34",-
_$    "66.170.199.220/29"

In this example, connections from IP addresses 10.1.2.3, 224.32.32.34, and the subnet 66.170.199.220 would not be allowed to connect. The "/29" specifies that there are 29 significant bits in the address (meaning a subnet mask of 255.255.255.248), which means .220--.228 would be not be allowed to connect.

Clients refused a connection will receive the following message:


421 Access denied, IP address rejected

The following rules are applied with the access logicals:

  1. If neither logical is defined, access is not restricted.
  2. If only the ACCEPT logical is defined, all connections are rejected unless the IP address is included in the equivalence for the logical.
  3. If only the REJECT logical is defined, all connections are accepted unless the IP address is included in the equivalence for the logical.
  4. If both logicals are defined, only specified ACCEPT addresses are accepted. If an address is accepted because it matches a specified network, the listener will check to make sure the particular IP address is not rejected explicitly.

2.20 HG_FTP_RESTRICT

The HG_FTP_RESTRICT logical can be used to limit the functions allowed by the server. Its equivalence value is the sum of the following desired values:
Value Meaning
1 No read (RETR)
2 No write (STOR, STOU, APPE, MKD)
4 No control (SITE)
8 No delete (DELE, RMD)
16 No list (LIST, NLST, STAT param)
32 No change working directory (CWD)

The default value is 0, which means that the server is not restricted. By defining the logical system-wide, you can provide a different default value for all users. Users can override the system-wide value by defining the logical in their LOGIN.COM files. The following command would restrict access to only reading and listing files:


$ DEFINE/SYSTEM/EXEC HG_FTP_RESTRICT 14

2.21 HG_FTP_TILDE_ANONDIR

The HG_FTP_TILDE_ANONDIR logical can be used to allow users on the local system to offer files for anonymous FTP access. Anonymous users can use the special syntax ``~username'' to access the files ``username'' has made available via anonymous FTP. The files are stored in a subdirectory under the local user's login directory, allowing sites to provide anonymous FTP files on a user-by-user basis much like Web servers provide user-based HTML pages.

If HG_FTP_TILDE_ANONDIR is defined, its equivalence value is used as the name of an ``anonymous FTP'' subdirectory under each user's login directory. For example, assume the following command has been executed:


$ DEFINE/SYSTEM/EXEC HG_FTP_TILDE_ANONDIR AFTP

If the login directory for user BOB is USER:[BOB], the directory tree USER:[BOB.AFTP...] would be accessible to anonymous FTP users, if the directory exists. The remote anonymous user would simply issue a command like ``cd ~bob'' to change the default directory to USER:[BOB.AFTP].

Note

When defining this logical, you should make sure that your users are aware of the significance of subdirectories with that name to ensure that files are not accidentally made available via anonymous FTP.

All files in user anonymous FTP directories must have WORLD:READ access to be accessible by anonymous users. The following example shows how such a directory might be created:


$ set def sys$login:
$ create/dir [.aftp]
$ set file/prot=w:re aftp.dir
$ copy xyz.txt [.aftp]*.*;/prot=w:re

See Section 3.2 for more information about anonymous FTP directories.

If the HG_FTP_TILDE_ANONDIR logical is not defined, an anonymous user receives a ``Bad directory'' response to a command like ``CD ~joeuser''.

2.22 HG_FTP_TIMEOUT

The HG_FTP_TIMEOUT logical specifies the number of seconds that the HGFTP server process will wait for a command from the remote FTP client. If the server is idle longer than the specified number of seconds, the connection is automatically closed by the server.

By default, the server will keep an idle connection open for 5 minutes (300 seconds). The following command sets the server timeout to 10 minutes (600 seconds):


$ DEFINE/SYSTEM/EXEC HG_FTP_TIMEOUT 600

Individual users can override this timeout by redefining it in their LOGIN.COM files. If you do not want them to be able to override the value you've defined, you can define it as a process logical in FTP_SERVER.COM in HG_ROOT:[COM].

2.23 HG_FTP_USER_PROMPT

The HG_FTP_USER_PROMPT logical determines whether or not the HGFTP client automatically prompts for the remote username when a connection is made to a remote system. By default, the client does not prompt; the user must issue the USER or LOGIN commands to begin the login.

Many FTP clients, including UNIX and UCX clients, will automatically prompt for the remote username. If your users are accustomed to this behavior, issuing the following command will enable that feature:


$ DEFINE/SYSTEM/EXEC HG_FTP_USER_PROMPT -
_$     TRUE

The HGFTP client will not prompt for a username if the value of HG_FTP_USER_PROMPT starts with ``N'' or ``F.'' Users can define the logical themselves to override a system-wide definition of HG_FTP_USER_PROMPT.

2.24 HG_FTP_WELCOME

The HG_FTP_WELCOME logical specifies the welcome text that is to be sent back to the remote client upon a successful login. For example:


$ DEFINE/SYSTEM/EXEC HG_FTP_WELCOME -
_$     "Welcome to node YYZ"

If the welcome message begins with "@", the rest of the string is used as a file name whose contents are read and sent back to the remote client. For example, the following definition would cause the contents of FTP_WELCOME.TXT to be read and sent back to the remote user:


$ DEFINE/SYSTEM/EXEC HG_FTP_WELCOME -
_$     "@SYS$MANAGER:FTP_WELCOME.TXT"

This form lets you send back to the user information such as access policies, e-mail address for archive maintainers, etc.

You can also specify a welcome message to be displayed when a remote client enters a directory. The message text should be stored in a file called .MESSAGE located in the target directory. See Section 3.2 for more information.


Chapter 3
Setting Up Anonymous FTP

This chapter describes the steps necessary to set up anonymous FTP on a system using the HGFTP server. Anonymous FTP provides anonymous (guest) access to certain files on your system. Anonymous FTP logins are controlled using the logicals described in Chapter 4.

The basic steps for setting up anonymous FTP are:

3.1 Creating an ANONYMOUS Account

Anonymous FTP logins are normally accomplished using a login username ANONYMOUS. The ANONYMOUS account must be created using the VMS account creation utility, AUTHORIZE.

You can also use any other account as an anonymous FTP account by granting each account the HG_FTP_ANON identifier.

3.1.1 The ANONYMOUS Username

The ANONYMOUS account should have the following characteristics:

The following example shows a typical ANONYMOUS account creation. Figure 3-1 shows the UAF entry for a typical ANONYMOUS account.


$ set default sys$system:
$ run authorize
UAF> add anonymous/uic=[13,1]/password=junk-
_UAF> /flag=(nodisuser,dismail)/owner="Anonymous FTP"-
_UAF> /network/nointeractive/noremote/nobatch-
_UAF> /device=SYS$SYSDEVICE:/directory=[ANONYMOUS]-
_UAF> /privilege=(noall,netmbx)/defpriv=(noall,netmbx)
User record successfully added
Identifier ANONYMOUS value: [000013,000001] added to rights data base
UAF> exit
$ create/directory/owner=anonymous sys$sysdevice:[anonymous]
$ 

Figure 3-1 ANONYMOUS Account Attributes



Username: ANONYMOUS                        Owner:  Anonymous FTP 
Account:                                   UIC:    [13,1] ([ANONYMOUS]) 
CLI:      DCL                              Tables: DCLTABLES 
Default:  SYS$SYSDEVICE:[ANONYMOUS] 
LGICMD:   LOGIN 
Flags:  DisMail 
Primary days:   Mon Tue Wed Thu Fri 
Secondary days:                     Sat Sun 
Primary   000000000011111111112222  Secondary 000000000011111111112222 
Day Hours 012345678901234567890123  Day Hours 012345678901234567890123 
Network:  ##### Full access ######            ##### Full access ###### 
Batch:    -----  No access  ------            -----  No access  ------ 
Local:    -----  No access  ------            -----  No access  ------ 
Dialup:   -----  No access  ------            -----  No access  ------ 
Remote:   -----  No access  ------            -----  No access  ------ 
Expiration:            (none)    Pwdminimum:  6   Login Fails:     0 
Pwdlifetime:         90 00:00    Pwdchange:      (pre-expired) 
Last Login:            (none) (interactive),            (none) (non-interactive) 
Maxjobs:         0  Fillm:       100  Bytlm:         8192 
Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0 
Maxdetach:       0  BIOlm:        18  JTquota:       1024 
Prclm:           2  DIOlm:        18  WSdef:          150 
Prio:            4  ASTlm:        24  WSquo:          256 
Queprio:         0  TQElm:        10  WSextent:       512 
CPU:        (none)  Enqlm:       100  Pgflquo:      10240 
Authorized Privileges: 
  NETMBX 
Default Privileges: 
  NETMBX 

3.1.2 Additional Anonymous FTP Accounts

You can create additional anonymous FTP accounts by granting the HG_FTP_ANON identifier to one or more usernames. When an account holds this identifier and is used as an FTP login username, the same rules that apply to the ANONYMOUS account are enforced for those logins. You might create additional anonymous accounts to provide for controlled uploading of files, or to allow remote users to access files you don't want to be visible under the ANONYMOUS account.

The AUTHORIZE utility is used to grant the HG_FTP_ANON identifier. Before you can grant the identifier to an account, you must create it. The identifier only needs to be created once:


$ set default sys$system:
$ run authorize
UAF> add/ident hg_ftp_anon
Identifier HG_FTP_ANON value: %X80010010 added to rights data base
UAF> 

Once the identifier has been created, you can grant it to an account using the GRANT/IDENTIFIER command:


UAF> grant/identifier hg_ftp_anon uploads
Identifier HG_FTP_ANON granted to UPLOADS
UAF> 

For each anonymous account, you must define the HG_FTP_user_DIRS logical name and create a LOGIN.COM for it, as described in Section 3.3 and in Section 3.4. For example, for the account UPLOADS used above, the logical HG_FTP_UPLOADS_DIRS would have to be defined to specify the directories accessible by username UPLOADS.

3.2 Creating ANONYMOUS Directories

ANONYMOUS access to directories is controlled by the logical HG_FTP_ANONYMOUS_DIRS. The anonymous FTP directories should have the following characteristics:

You can associate a message to be displayed with a directory by creating a file called .MESSAGE in that directory. When a remote client requests a directory change, the server looks for a .MESSAGE file in the target directory. If a .MESSAGE file is found, the message text is displayed as part of the reply for the CWD or CDUP server command as shown below.


FTP:host> cd uploads
250-
250-All files uploaded should be .ZIP files.
250-Uploads without descriptions will be deleted.
250-
250 Current Directory DUB0:[ARCHIVES.UPLOADS], completed.
FTP:host> 

.MESSAGE files can be useful for displaying policy or content information about a particular directory. The message text will not be displayed if the server process does not have read access to the .MESSAGE file.

3.3 Defining the Anonymous FTP Logicals

The file HG_ROOT:[COM]FTP_LOGICALS.TEMPLATE should be renamed as FTP_LOGICALS.COM and edited to customize the various HGFTP logicals. The logicals controlling anonymous FTP access are described in Chapter 4.

Logicals defined there can be overridden by redefining them in the LOGIN.COM for the anonymous account.

3.4 Anonymous LOGIN.COM Files

You can create a LOGIN.COM for each anonymous account to further customize the anonymous FTP environment. For example, you can change the default directory for the account, reject logins based on the password given, or allow anonymous write access for certain accounts.

The file HG_ROOT:[COM]ANONYMOUS_LOGIN.TEMPLATE is provided to as a template for a LOGIN.COM procedure for an anonymous FTP account. It is shown in Figure 3-2.

Optionally, a single LOGIN.COM could be created for all anonymous accounts and the LGICMD UAF parameter could be set to point to the common file.

Figure 3-2 ANONYMOUS LOGIN.COM Example



$ sav = 'f$verify(0)'   !Turn off verify 
$! 
$!  Copyright © 2001, Hunter Goatley.  All rights reserved. 
$! 
$! ANONYMOUS_LOGIN.TEMPLATE 
$! 
$! This file should be edited as appropriate and copied as LOGIN.COM 
$! for each anonymous FTP account. 
$! 
$ username = f$edit(f$getjpi("","USERNAME"),"TRIM") 
$!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 
$! 
$! The code below copies the host name and IP address into the symbols 
$! HOST_NAME and HOST_IP.  If a host name cannot be determined, the 
$! IP address will be used for both. 
$! 
$ @hg_root:[com]ftp_get_connection_info.com !Get the host info 
$! 
$! The IP address is checked to determine if this is a "local" 
$! connection; non-local connections are rejected. 
$! 
$! This section could be expanded to allow different file accesses 
$! based on the remote host name or address, etc. 
$! 
$!$ if f$extract(0,6,host_ip).eqs."161.6." - 
$! then define hg_ftp_reject_'username' "Goodbye" 
$! 
$! Now, you also get the local IP number throught which the request 
$! is made, as well as the hostname for it if available.  The code 
$! below will mangle them a little, so they become usable in conjunction 
$! with some logical name standards. 
$! 
$ loop1: 
$  p = f$locate (".", local_name) 
$  if p .eq. f$length (local_name) then p = f$locate ("-", local_name) 
$  if p .lt. f$length (local_name) 
$  then 
$      local_name == f$extract (0, p, local_name) + "_" + - 
       f$extract (p+1, 1000, local_name) 
$      goto loop1 
$  endif 
$ loop2: 
$  p = f$locate (".", local_ip) 
$  if p .eq. f$length (local_ip) then p = f$locate ("-", local_ip) 
$  if p .lt. f$length (local_ip) 
$  then 
$      local_ip == f$extract (0, p, local_ip) + "_" + - 
     f$extract (p+1, 1000, local_ip) 
$      goto loop2 
$  endif 
$! 
$! The code below copies the anonymous password into the symbol 
$! ANONYMOUS_PASSWORD.  The password is then compared to a string 
$! that is used to reject a login using that password. 
$! 
$! This section could be expanded to allow different file accesses 
$! based on the entered password, etc. 
$! 
$!$ @hg_root:[com]ftp_get_anonymous_password.com !Get the password 
$!$ if anonymous_password .eqs. "BURKHDR@alpha.wku.edu" - 
$! then define hg_ftp_reject_'username' "Goodbye" 
$! 
$!++ 
$! 
$! HG_ANONYMOUS_FTP_DIRS probably doesn't include the ANONYMOUS 
$! account's login directory, since this is where the log files are 
$! kept, by default.  Therefore, if HG_FTP_ANONYMOUS_DIRS is 
$! defined, use the first entry as the default directory.  Note, since 
$! entries can take the form dev:[dir...], we may need to trim ...] off 
$! of the end of the dir spec. 
$! 
$! We first check for HG_FTP_ANONYMOUS_host-name_DIRS 
$! and HG_FTP_ANONYMOUS_ip-number_DIRS 
$! 
$ defdir = f$trnlnm("HG_FTP_''USERNAME'_''local_name'_DIRS","HG_FTP_NAME_TABLE") 
$ if defdir .eqs. "" then - 
     defdir = f$trnlnm("HG_FTP_''USERNAME'_''local_ip'_DIRS","HG_FTP_NAME_TABLE") 
$ if defdir .eqs. "" then - 
     defdir = f$trnlnm("HG_FTP_''USERNAME'_DIRS","HG_FTP_NAME_TABLE") 
$ if defdir .nes. "" .and. defdir .nes. " " 
$ then 
$   length = f$length(defdir) 
$   delimit = f$extract(length-1,1,defdir) 
$   if f$extract(length-4,3,defdir) .eqs. "..." 
$   then sublen = length-4    !Strip off ...] 
$   else sublen = length-1    !Strip off ] 
$   endif 
$   defdir = f$extract(0,sublen,defdir)+"."+delimit 
$   define/trans=conc anonymous 'defdir' 
$   set default anonymous:[000000] 
$ endif 
$! 
$!  Don't allow any access except RETR (GET) and LIST (DIR)! 
$! 
$ define hg_ftp_restrict 14 !RETR and LIST access only! 
$! 
$ exit 1 .or. f$verify(sav)  !Restore verify state 


Chapter 4
The HGFTP Anonymous Logicals

This chapter describes the logicals that control anonymous FTP access using the HGFTP listener and server.

The logicals described must be defined as executive-mode logicals in the logical name table HG_FTP_NAME_TABLE. For example:


$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE logical value

These logicals should be defined in the HGFTP logical name procedure, HG_ROOT:[COM]FTP_LOGICALS.COM.

4.1 HG_FTP_user_WELCOME

You can define a specific welcome message for each anonymous FTP account by defining logicals of the form HG_FTP_user_WELCOME, where ``user'' is the username. For example, to define a special message for an ANONYMOUS account, you could define:


$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$     HG_FTP_ANONYMOUS_WELCOME -
_$     "Welcome to anonymous access on node YYZ"

If the welcome message begins with "@", the rest of the string is used as a file name whose contents are read and sent back to the remote client. For example, the following definition would cause the contents of ANON_FTP_WELCOME.TXT to be read and sent back to the remote user:


$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$     HG_FTP_ANONYMOUS_WELCOME -
_$     "@SYS$MANAGER:ANON_FTP_WELCOME.TXT"

This form lets you send back to the user information such as access policies, e-mail address for archive maintainers, etc.

4.2 HG_FTP_user_DIRS

You can restrict directory access on a user-basis by defining search list logicals of the form HG_FTP_user_DIRS, where ``user'' is the username whose access is to be restricted. For example, to restrict access for an ANONYMOUS account, you could define:


$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$    HG_FTP_ANONYMOUS_DIRS -
_$    DISK:[ANONYMOUS...],DISK2:[PUBLIC]

Such restrictions apply regardless of each account's VMS privileges.

Note

You should define a logical for each ANONYMOUS account to ensure that only the publicly-available files are accessible.

4.3 Limiting Anonymous FTP Access to Off-hours

The HGFTP server can restrict anonymous FTP access to hours other than ``prime-time'' hours if the load average software (LAVDRIVER) is installed. LAVDRIVER gathers load average statistics on an OpenVMS system. The driver is automatically included with TGV's MultiNet, but is also freely available from various sources, including ftp.spc.edu. If the driver is loaded, the device LAV0: will exist:


$ SHOW DEVICE LAV0:
Device                  Device           Error
 Name                   Status           Count
LAV0:                   Online               0
$ 

The logicals described in the following sections are used to control the load checking code.

4.3.1 HG_FTP_ANON_LOAD_LIMIT

The logical HG_FTP_ANON_LOAD_LIMIT logical specifies the load limit for anonymous logins. This limit is a floating-point value between 0.0 and 1.0. If it is defined and the current time is between the prime-time start and end times, then the current load averages are read from the LAV0: device. The current load is computed using the following formula:
load = M15 * (P15 / 4.0))

where M15 is the average load over the last 15 minutes and P15 is the average priority over the last 15 minutes. Thus, the average load is normalized against typical interactive priority to guard against low-priority batch jobs preventing anonymous login access.

If the load is greater than or equal to the HG_FTP_LOAD_LIMIT value, the anonymous login is denied with a reason of ``system too busy,'' If the threshold is not exceeded, the anonymous login is accepted, but the user is warned to minimize access during prime-time hours (with the start and end times displayed along with the time zone information).

If the current time does not fall within prime-time hours, no load checking is performed.

The following command establishes a load limit of 0.5 for anonymous logins:


$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$    HG_FTP_ANON_LOAD_LIMIT "0.5"

4.3.2 HG_FTP_ANON_PRIME_DAYS

The logical HG_FTP_ANON_PRIME_DAYS specifies the days for which ``prime-time'' hours are to apply. The logical value is a comma-separated list of numbers, where 1 is Monday, 2 is Tuesday, etc. If the logical is not defined, then ``prime time'' is assumed to be in effect Monday through Friday.

The following command establishes Monday, Wednesday, and Friday as prime-time days:


$ DEFINE/EXEC/TABLE=HG_FTP_NAME_TABLE -
_$    HG_FTP_ANON_PRIME_DAYS "1,3,5"

The value cannot contain spaces, and it must be surrounded by quotes.

4.3.3 HG_FTP_ANON_PRIME_START

The logical HG_FTP_ANON_PRIME_START specifies the starting time for ``prime-time'' hours. The default value is ``09:00:00''.

4.3.4 HG_FTP_ANON_PRIME_END

The logical HG_FTP_ANON_PRIME_END specifies the ending time for ``prime-time'' hours. The default value is ``17:00:00''.

Contents