HGFTP Installation Guide

HGFTP Installation Guide


March, 2004

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


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

This guide describes how to install the HGFTP.

Intended Audience

This manual is intended for use by the system manager or any individual responsible for installing and maintaining the HGFTP client and server.

Document Structure

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.

Related Documents

You can find additional information in the following documents:


Chapter 1
Preparing to Install HGFTP

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

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:


Chapter 2
Installing HGFTP

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

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

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.

Note

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

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

2.5 Component Selection

The HGFTP installation provides a number of options for installing individual components. The following list describes the options.

2.5.1 Installing the Sources Only

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 HG_ROOT:[SOURCES.FTP].

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 HG_ROOT:[DOC].

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]?

Note

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]: 

2.5.4 Installing NETLIB

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]?

2.6 The Installation Completes

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.


Chapter 3
Post-Installation Information

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.

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


$ @dua0:[hg.com]ftp_startup.com 

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 discussed below.

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
$

3.2.3 Disabling DEC TCP/IP (UCX)

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

When asked:


Enter the number of listening Server-FTP processes [1]:

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:

To prevent the PathWay FTP server from restarting on the next system boot, comment out the FTP_INIT line in the PathWay startup file, TWG$TCP:[NETDIST.MISC]STARTINET.COM.

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 goathunter@goatley.com.


Appendix A
Sample HGFTP Installation

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 [6]: [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 
 
 
$ 


Appendix B
Contents of Distribution Kit

The HGFTP is provided in a VMSINSTALlable distribution kit consisting of five save sets. Each save set is briefly described in Table B-1.

Table B-1 HGFTP installation kit save sets
Save Set Contents
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.


Appendix C
Files Created During Installation

The files in Table C-1 are created during the installation of the HGFTP software.

Table C-1 HGFTP files created during installation
File name Description
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


+Only if sources were installed

Contents