This manual provides installation and setup instructions for the HGFTP client and server.
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
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:
MultiNet is a registered trademark of Process Software, LLC.
TCPware is a trademark of Process Software, LLC.
This guide describes how to install the HGFTP.
This manual is intended for use by the system manager or any individual responsible for installing and maintaining the HGFTP client and server.
This guide consists of three chapters and three appendices.
|Chapter 1||Contains pre-installation information.|
|Chapter 2||Describes the HGFTP installation procedure.|
|Chapter 3||Contains post-installation information.|
|Appendix A||Contains a listing of a sample installation.|
|Appendix B||Describes the contents of the HGFTP distribution kit.|
|Appendix C||Contains a list of the files created by an installation.|
You can find additional information in the following documents:
This chapter describes the steps that should be taken prior to
installing the HGFTP client and server.
1.1 Prerequisite Software
HGFTP requires OpenVMS VAX (VAX VMS) V5.0 or later or OpenVMS Alpha V1.5 or later to run.
The HGFTP software requires the NETLIB package, available from
MadGoat Software (and included with HGFTP). A NETLIB-supported
TCP/IP package is also required (refer to the NETLIB release notes for
1.2 Accessing the Online Release Notes
The HGFTP provides online release notes, which you can display
or print by using VMSINSTAL with the OPTIONS N parameter. After the
installation, you can read the release notes by printing the file
SYS$HELP:HGFTPvvn.RELEASE_NOTES, where "vvn" denotes the
version number of the software. For example, for version V3.1-2
of HGFTP, the file name would be HGFTP031.
1.3 Installation Procedure Requirements
Before installing HGFTP, ensure that the following privileges, resources, and requirements are met:
HGFTP uses VMSINSTAL for installation. If you do not know how to
use VMSINSTAL, you should first read the chapter on installing software
in the VMS System Manager's Manual. For the installation, you
should be logged into the SYSTEM account or another suitably privileged
2.1 Invoking VMSINSTAL
Invoke VMSINSTAL to install HGFTP.
$ @SYS$UPDATE:VMSINSTAL HGFTP031 ddcu:
Substitute the appropriate device name for ddcu.
VAX/VMS Software Product Installation Procedure V5.5-2 It is dd-Mmm-yyyy at hh:mm. Enter a question mark (?) at any time for help.
If there are any users logged into the system, you will see the message:
%VMSINSTAL-W-ACTIVE, The following processes are still active: ...process names...
You can install HGFTP while users are logged in, though no user should be running the HGFTP client from a previous version.
* Do you want to continue anyway [NO]?
If you wish to continue, answer YES.
* Are you satisfied with the backup of your system disk [YES]?
If you feel comfortable with your system disk backup, answer YES.
Otherwise, answer NO, perform the backup, then restart the installation
2.2 Installation Options
The next question is
* Do you want to purge files replaced by this installation [YES]?
If this is the first time you have installed HGFTP, answering NO
to this question can save some time when the HGFTP files are
moved into their directories.
2.3 Mixed VMSclusters (VAX and Alpha systems)
Mixed VMSclusters that consist of both VAX and Alpha systems are fully supported by HGFTP. The HG_ROOT directory tree can be shared by both systems if it resides on a common disk. When the VAX and Alpha systems share a common HG_ROOT directory, the client and server may be run on both types of systems.
When the HGFTP installation determines that the node is part of a cluster, it will ask whether or not the cluster contains both VAX and Alpha systems. Additional questions relating to mixed-VMScluster support will be asked if the cluster is mixed.
HGFTP must be installed twice on a mixed-VMScluster: once on a VAX system and once on an Alpha system. This is necessary because the HGFTP executables are linked during the installation. Installing HGFTP on a VAX produces the VAX executable images and installing it on an Alpha produces the Alpha images.
If the VAX and Alpha systems will be sharing a HG_ROOT directory, it is only necessary to install the full HGFTP kit on one of the systems (VAX or Alpha). For the second installation on the other type of machine, you can elect to install only the executables for that machine. The installation will prompt for the type of installation to be performed. Choosing to install only the executables on the second installation eliminates the need to copy files that have already been installed.
The HG_ROOT: directory tree contains two directories for executables:
HG_ROOT:[EXE] for VAX executables and HG_ROOT:[ALPHA_EXE] for Alpha
executables. The logical HG_EXE:, which is used in all examples below,
will automatically be defined appropriately on each system in the
2.4 Disk and Directory Selection
HGFTP is installed in its own rooted directory to avoid mixing HGFTP files with normal VMS files. The only file copied to a VMS directory is the file containing the HGFTP release notes, which is copied to SYS$HELP:.
HGFTP can reside on any disk. The installation prompts you for the name of the disk and top-level directory for the utilities. The default is SYS$SYSDEVICE:[HG].
* Enter the top-level directory for HGFTP [DUA0:[HG]]:
Once a directory has been specified (or [RETURN] is pressed to select the default), the directory is created and a message like the following is displayed:
%VMSINSTAL-I-SYSDIR, This product creates system disk directory DUA0:[HG].
The HGFTP installation provides a number of options for installing individual components. The following list describes the options.
The first question asked gives you the opportunity to install only the sources for HGFTP:
* Do you want to install ONLY the sources for HGFTP [NO]?
Answering YES will cause the installation to skip the rest of the questions and begin copying the documentation and source files. There will be no more questions asked.
If you answer NO the question above, you will be prompted for whether or not you wish to install the sources at all:
* Do you want to install the sources for HGFTP [YES]?
Answering YES to the question will install the appropriate source files
for the HGFTP software. The source files will be copied to
2.5.2 Installing the Client and Server
The installation will next ask you about installing the documentation for HGFTP. Documentation is supplied in Bookreader, PostScript, and ASCII text file formats. The installation will prompt you with this question:
* Do you want to install the documentation for HGFTP [YES]?
If you answer YES to the question, the documentation will be copied to
2.5.3 Client DCL Command and On-line Help
The installation next gives you the opportunity to have the FTP command added to the system-wide DCLTABLES. Answering YES to the following question will create a ``real'' DCL command that is automatically available to all users on the system:
* Do you want to add the FTP command to DCLTABLES [YES]?
Answering YES will cause your vendor's FTP command definition to be replaced by the HGFTP command definition.
You will then be asked whether or not you want to install the on-line help for the FTP client in a help library. If you answer YES, you will also be asked which library should contain the help.
* Do you want to add the HGFTP help to a library [YES]?
The installation will present a number of choices for the library to receive the on-line help. In addition to offering the system-wide help library as an option, the installation procedure will look for any HLP$LIBRARY commands defined in the system directory and will offer those too:
This installation updates the help library so that the DCL command "$ HELP FTP" will provide information about the HGFTP client. There are several help libraries into which the help file can be placed. Some of them are: SYS$SYSROOT:[SYSHLP]HELPLIB.HLB WKU$ROOT:[HELP]WKU_HELP.HLB * To which library should HGFTP client help be added [SYS$SYSROOT:[SYSHLP]HELPLIB.HLB]:
The HGFTP distribution includes the version of NETLIB that was current at the time the distribution was assembled. The HGFTP installation checks to see if NETLIB is already installed on your system. If it does not, it is automatically installed and you will have to answer questions identifying which TCP/IP implementations are installed on your system or cluster.
If NETLIB is already installed on the system, you are given the chance to update it with the version distributed with HGFTP. If that version is newer than the version already installed, you should upgrade NETLIB.
A version of the NETLIB library for TCP/IP support is already installed on this system. * Do you want to install the NETLIB V1.6 library [YES]?
After the configuration questions, the selected components are installed. Files are copied from each save set of the installation kit and the appropriate images are linked, then all installed files are copied to their destination directories. Informational messages about the individual components are displayed as needed.
This chapter contains important information about the HGFTP
configuration and startup options. Most of the configuration options
apply only if you intend to use the HGFTP server.
3.1 Starting HGFTP
Once the installation is complete, you can start the HGFTP
client and server by executing the command procedure FTP_STARTUP.COM,
located in HG_ROOT:[COM]. This procedure will define the HG_ROOT and
HG_EXE logicals in the system logical name table and install the FTP
client and server images with the necessary privileges.
Before starting HGFTP, you should create
HG_ROOT:[COM]FTP_LOGICALS.COM from the FTP_LOGICALS.TEMPLATE file,
customizing the logicals as needed for your site.
Before starting HGFTP, you should create HG_ROOT:[COM]FTP_LOGICALS.COM from the FTP_LOGICALS.TEMPLATE file, customizing the logicals as needed for your site.
To start the HGFTP software automatically at system startup, you should add a line like the following to the system startup procedure (SYSTARTUP_V5.COM or SYSTARTUP_VMS.COM in SYS$MANAGER):
You should, of course, specify the actual device and top-level directory that you specified during the installation.
If you only want to use the HGFTP client and not the server, you can specify ``CLIENT_ONLY'' as a parameter to the startup procedure:
$ @dua0:[hg.com]ftp_startup.com client_only
If you did not elect to install the FTP command system-wide in DCLTABLES, then you should add a command like the following to your system login procedure (SYS$SYLOGIN or SYS$MANAGER:SYLOGIN.COM):
$ ftp :== $hg_exe:ftp.exe
The HG_EXE: logical is defined by FTP_STARTUP.COM to point to the
appropriate architecture-specific image directory.
3.2 Disabling Vendor FTP Support
If your TCP/IP vendor provides FTP support as part of its package, you
should disable that support before starting the HGFTP server.
The methods for disabling support for several vendors' products are
3.2.1 Disabling CMUIP FTP
For CMU-OpenVMS/IP (aka CMU-Tek TCP/IP and CMUIP and other names), edit
the INTERNET.CONFIG file, comment out the line that begins with
``WKS:21'', and then restart TCP/IP.
3.2.2 Disabling MultiNet FTP
For MultiNet, use the Server Configuration Utility to disable MultiNet's FTP service:
$ MULTINET CONFIGURE/SERVER MultiNet Server Configuration Utility 2.2(25) [Reading in symbols from SERVER image MULTINET:SERVER.EXE] [Reading in configuration from MULTINET:SERVICES.MASTER_SERVER] SERVER-CONFIG>DISABLE FTP SERVER-CONFIG>RESTART SERVER-CONFIG>EXIT $
For DEC TCP/IP Services for OpenVMS (aka UCX), use the UCX utility to disable the FTP service:
$ UCX UCX> DISABLE SERVICE FTP UCX>
You must also modify the file UCX$INET_SET_INTERFACES.COM and comment
out the line that enables the FTP service.
3.2.4 Disabling TCPware
For TCPware, use the TCPware configuration utility to disable TCPware's FTP server, if you installed TCPware-FTP. For TCPware V3.0 or higher, type:
$ @TCPWARE:CNFNET FULL FTP
For versions of TCPware prior to V3.0, type:
$ @TCPWARE_ROOT:CNFNET FULL FTP
Enter the number of listening Server-FTP processes :
enter 0. When asked whether to restart FTP, answer YES.
3.2.5 Disabling WIN/TCP and PathWay
For WIN/TCP and PathWay, follow these steps:
#service-name FTP [...]
$ netstat -a
To prevent the PathWay FTP server from restarting on the next system
boot, comment out the FTP_INIT line in the PathWay startup file,
3.3 Using the Bookreader Documentation
To include the HGFTP Bookreader documents in the Bookreader search list, you should perform one or both of the following actions, depending on your Bookreader setup.
For more information, consult the Bookreader documentation.
3.4 Registering Your Installation
HGFTP is freely distributable software, and no license is required to use it. Registration of your installation is at your discretion and is used by the author only to determine the size of the HGFTP user base and the future directions for the package.
To register, simply send a note to Hunter Goatley with the following information:
You can send it electronically to firstname.lastname@example.org.
This appendix includes a sample HGFTP installation. In this example, NETLIB is also installed.
$ @SYS$UPDATE:VMSINSTAL HGFTP031 DUB0:[HUNTER] VAX/VMS Software Product Installation Procedure V5.4-2 It is 6-AUG-1996 at 06:49. Enter a question mark (?) at any time for help. %VMSINSTAL-W-NOTSYSTEM, You are not logged in to the SYSTEM account. %VMSINSTAL-W-ACTIVE, The following processes are still active: Polter Goat Goat Busters * Do you want to continue anyway [NO]? yes * Are you satisfied with the backup of your system disk [YES]? [RETURN] The following products will be processed: HGFTP V3.1-2 Beginning installation of HGFTP V3.1-2 at 06:50 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. HGFTP V3.1-2 Installation Copyright © 2002, Hunter Goatley. All rights reserved. Redistribution for no commercial gain is permitted. * Do you want to purge files replaced by this installation [YES]? [RETURN] Configuring Base HGFTP Directories and Logicals ----------------------------------------------------- HG software is installed in its own rooted directory to avoid mixing HG files with normal VMS files. The directory can reside on any disk. THERE ARE NO FILES COPIED TO SYS$SYSTEM, SYS$LIBRARY, etc. (The only file copied to a VMS directory is the Release Notes file, which is copied to SYS$HELP.) * Enter the top-level directory for the HG root directory [SYS$SYSDEVICE:[HG]]: [RETURN] %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.EXE]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.ALPHA_EXE]. Selecting HGFTP Components -------------------------------- The HGFTP client and server are normally installed by linking the object files packed with the kit. The installation will also give you a chance to add the FTP DCL command and on-line help to your system. The HGFTP sources are also provided. You can either install the products and the sources, or you can install the sources only and rebuild them by hand. If you only want to install the sources and want to skip the product installations, enter YES to the following prompt. * Do you want to install ONLY the sources for HGFTP [NO]? [RETURN] The answer to the following question will determine whether the source files for the HGFTP client and server are installed. * Do you want to install the sources for HGFTP [YES]? no Documentation for HGFTP comes in Bookreader, PostScript, and ASCII text file formats. If you elect to install the documentation, the files will be placed in HG_ROOT:[DOC]. * Do you want to install the documentation for HGFTP [YES]? [RETURN] The HGFTP client DCL command, FTP, can be added to the system-wide DCLTABLES, making the command available to all users, or it can be defined as a foreign command. * Do you want to add the FTP command to DCLTABLES [YES]? [RETURN] * Do you want to add the HGFTP client help to a library [YES]? [RETURN] This installation updates the help library so that the DCL command "$ HELP FTP" will provide information about the HGFTP client. There are several help libraries into which the help file can be placed. Some of them are: SYS$SYSROOT:[SYSHLP]HELPLIB.HLB * To which library should HGFTP client help be added [SYS$SYSROOT:[SYSHLP]HELPLIB.HLB]: [RETURN] A version of the NETLIB library for TCP/IP support is already installed on this system. HGFTP requires NETLIB V2.0 or higher. * Do you want to install the NETLIB V2.2 library [YES]? [RETURN] %VMSINSTAL-I-RESTORE, Restoring product save set B ... Now installing NETLIB library for TCP/IP support. %HGFTP-I-NETLRNOT, Release notes for NETLIB V2.2 have been copied to SYS$HELP. %VMSINSTAL-I-RESTORE, Restoring product save set C ... TCP/IP Support Selection Select the NETLIB TCP/IP support you wish to install from the menu below. An asterisk appears next to the packages that have already been selected. You can remove a package from the list by selecting it again. You may enter more than one selection by separating your choices with commas. 1. [ ] CMU TCP/IP 2. [ ] Digital TCP/IP Services 3. [*] Process Software MultiNet 4. [ ] Process Software TCPware 5. [ ] Attachmate PathWay 6. Exit * Your choice : [RETURN] You have selected the following TCP/IP support: Process Software MultiNet * Is this correct [YES]? [RETURN] Choosing the NETLIB Directory The NETLIB libraries can be placed in any directory, as long as that directory is accessible to all users who plan to use or develop NETLIB-based applications. * Where should the NETLIB libraries be placed [SYS$COMMON:[SYSLIB]]: HG_ROOT:[EXE] %VMSINSTAL-I-SYSDIR, This product creates system disk directory HG_ROOT:[EXE]. %CREATE-I-EXISTS, HG_ROOT:[EXE] already exists %NETLIB-I-LINKING, Linking image NETLIB_SHRXFR... %NETLIB-I-LINKING, Linking image NETLIB_MULTINET_SHR... No further questions will be asked. The HGFTP installation will now continue for 2 to 15 minutes, depending on your type of media and the system configuration. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.COM]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.DATA]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.LOGS]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.DOC]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.HELP]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.SOURCES]. %VMSINSTAL-I-SYSDIR, This product creates system disk directory WKUMV1$DUB0:[HG.SOURCES.FTP]. %VMSINSTAL-I-RESTORE, Restoring product save set E ... %HGFTP-I-LINKING, Linking image FTP.... %HGFTP-I-LINKING, Linking image FTP_LISTENER.... %HGFTP-I-LINKING, Linking image FTP_SERVER.... %HGFTP-I-INSTDOC, Installing documentation.... %VMSINSTAL-I-RESTORE, Restoring product save set F ... To install the HGFTP images and define the HG_ROOT logical, execute the following command. To automate this procedure at system startup, you should also add the following line to the system startup command procedure (SYSTARTUP_V5.COM or SYSTARTUP_VMS.COM in SYS$MANAGER:). $ @WKUMV1$DUB0:[HG.COM]FTP_STARTUP.COM If you do not want to run the HGFTP server, then use this command instead: $ @WKUMV1$DUB0:[HG.COM]FTP_STARTUP.COM CLIENT_ONLY %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of HGFTP V3.1-2 completed at 07:01 VMSINSTAL procedure done at 07:01 $
The HGFTP is provided in a VMSINSTALlable distribution kit consisting of five save sets. Each save set is briefly described in Table B-1.
|HGFTP031.A||The KITINSTAL command procedure and the HGFTP release notes.|
|HGFTP031.B||NETLIB common files.|
|HGFTP031.C||NETLIB VAX files.|
|HGFTP031.D||NETLIB Alpha files.|
|HGFTP031.E||Object libraries, command procedures, help files.|
|HGFTP031.F||Documentation files, in PostScript, Bookreader, and plain ASCII formats.|
|HGFTP031.G||HGFTP source files.|
The files in Table C-1 are created during the installation of the HGFTP software.
|Files in HG_ROOT:[COM]|
|ANONYMOUS_LOGIN.TEMPLATE||LOGIN.COM template for anonymous FTP accounts.|
|FTP.CLD||CLD file for FTP client|
|FTP_GET_ANONYMOUS_PASSWORD.COM||Command procedure to fetch the password supplied for anonymous logins.|
|FTP_LOGICALS.TEMPLATE||Template for HGFTP logical definitions.|
|FTP_SERVER.COM||Command procedure that drives the HGFTP server processes.|
|FTP_STARTUP.COM||Command procedure invoked to start HGFTP.|
|FTP_START_LISTENER.COM||Command procedure that drives the HGFTP listener process.|
|Files in HG_ROOT:[DOC]|
|FTP_INSTALL_GUIDE.DECW$BOOK||HGFTP Installation Guide (Bookreader)|
|FTP _INSTALL _GUIDE.PDF||HGFTP Installation Guide (Adobe PDF)|
|FTP_INSTALL_GUIDE.PS||HGFTP Installation Guide (PostScript)|
|FTP_INSTALL_GUIDE.TXT||HGFTP Installation Guide (ASCII)|
|FTP_MGMT_GUIDE.DECW$BOOK||HGFTP Manager's Guide (Bookreader)|
|FTP _MGMT _GUIDE.PDF||HGFTP Manager's Guide (Adobe PDF)|
|FTP_MGMT_GUIDE.PS||HGFTP Manager's Guide (PostScript)|
|FTP_MGMT_GUIDE.TXT||HGFTP Manager's Guide (ASCII)|
|FTP_USERS_GUIDE.DECW$BOOK||HGFTP User's Guide (Bookreader)|
|FTP _USERS _GUIDE.PDF||HGFTP User's Guide (Adobe PDF)|
|FTP_USERS_GUIDE.PS||HGFTP User's Guide (PostScript)|
|FTP_USERS_GUIDE.TXT||HGFTP User's Guide (ASCII)|
|LIBRARY.DECW$BOOKSHELF||Bookshelf file for Bookreader documents|
|Files in HG_ROOT:[EXE] and [ALPHA_EXE]|
|FTP.EXE||Executable image for FTP client|
|FTP_LISTENER.EXE||Executable image for FTP listener|
|FTP_SERVER.EXE||Executable image for FTP server|
|Files in HG_ROOT:[HELP]|
|HG_FTP_HELP.HLB||Help library for HGFTP client.|
|FTP_COMMAND.HLP||Help file for the FTP DCL command.|
|Files in HG_ROOT:[SOURCES.FTP] +|
|Various||BLISS source files for the HGFTP client, server, and listener.|
|Files in SYS$COMMON:[SYSHLP]|
|HGFTP031.RELEASE_NOTES||Release notes for HGFTP|