                                              SETUP Manager's Guide                    February, 1990    4           This manual describes SETUP, a utility for:           centralizing application setup operations on VMS           systems.          >           Revision/Update Information:  This manual supersedes?                                         the SETUP User's Guide.   9           Operating System and Version: VMS V5.0 or later   2           Software Version:             SETUP V2.1    (           Engineering Computing Services*           Rensselaer Polytechnic Institute           Troy, New York                               "           ________________________           27 February 1990  =           Permission is granted to copy and redistribute this @           document provide the copies are made for no commercial           advantage.  ?           The information in this document is subject to change 9           without notice and should not be construed as a 9           commitment by Rensselaer Polytechnic Institute. =           Rensselaer assumes 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@           author or the author's employer as to the suitability,>           reliability, security, usefulness, or performance of           this software.             __________@           Copyright 1988, 1990 Rensselaer Polytechnic Institute                       All Rights Reserved.           Printed in U.S.A.     @           This document was prepared using VAX DOCUMENT, Version
           1.2                A           _______________________________________________________              Preface     >           If you run many third-party applications on your VMS;           system, you probably have had to contend with the =           problems of getting these applications "set up" for ;           users: defining the right logical names, symbols, >           commands, etc. When many applications are available,=           placing all of their definitions in the system-wide ;           login command procedure can drastically slow down @           login time, and forcing users to place the appropriate<           commands in their own LOGIN.COM files can make for;           headaches when the commands required to set up an            application change.   ;           SETUP assists you with this task by providing one <           command through which all application setup can be<           executed. You define the application names and the;           command or commands to be executed to perform the ?           setup. You can change the actual commands at any time <           without the users having to modify their LOGIN.COM           files.  ;           SETUP also allows you to restrict access to setup =           information and commands in two ways: by VAXcluster @           node name, and through the use of access control lists           (ACL's).  L           __________________________________________________________________             Intended Audience   5           This manual is intended for system managers :           responsible for installing and setting up SETUP.            A                                                                 v                     Preface     L           __________________________________________________________________             Document Structure  8           This document consists of two parts. The first:           describes the installation and use of SETUP. The=           second describes the SETUP command and the SETUPDEF            APPLICATION command.                                                                               vi               A           _______________________________________________________   "           New and Changed Features    <           SETUP V2.1 includes the following new features and           changes.  ?           1  The APPLICATION command in SETUPDEF now includes a ?              /NODE qualifier to allow access restrictions based               on node names.   0           2  Messages were improved in SETUPDEF.                                                          A                                                               vii                A           _______________________________________________________     "           Part I  Management Guide  @           This part describes the installation and use of SETUP.                 A           _______________________________________________________       1      Installing SETUP      L           __________________________________________________________________  $    1.1    Installing the SETUP Files  >           The SETUP binary distribution includes the following           files:  /           SETUP.EXE             The SETUP image   ;           SETUPDEF.EXE          Program to create the SETUP 1                                 application table   @           SETUP_CLD.CLD         Command Language Definition file)                                 for SETUP   9           SETUP.RNH             DSR source for SETUP help +                                 information   ;           For a typical installation, you would perform the            following steps:  B                $COPY SETUP.EXE SYS$COMMON:[SYSEXE]/PROTECTION=W:RE?                $SET COMMAND/TABLE=SYS$COMMON:[SYSLIB]DCLTABLES- A                _$  /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES SETUP_CLD                  $RUNOFF SETUP.RNH;                $LIBRARY/REPLACE/HELP SYS$HELP:HELPLIB SETUP   <           You should then use the INSTALL utility to replace@           SYS$LIBRARY:DCLTABLES the system, and if the system is?           part of a VAXcluster, the other nodes in the cluster. >           If you plan on using the security features of SETUP,4           you should also use the following command:  ;                $INSTALL CREATE SYS$SYSTEM:SETUP/PRIV=SYSPRV   <           You should also include this command in you system$           startup command procedure.  A                                                               1-1                     Installing SETUP    L           __________________________________________________________________  (    1.2    Creating the Application Table  ?           The SETUPDEF program is used to build the application 9           table used by SETUP. By default, SETUPDEF takes 7           its input from the file SETUP_CMDS.DAT in the 8           current directory, and writes the table to the:           file RPI$ROOT:[SETUP]SETUP_SECTION.DAT. However,6           by defining the logical names SETUP_CMDS and:           SETUP_SECTION, you can redirect the input and/or            output of the program.  <           For a typical installation, it is best to create a<           directory for storing SETUPDEF, any SETUP_CMDS.DAT<           files, and the SETUP_SECTION.DAT file. Unless this:           directory is called RPI$ROOT:[SETUP], you should@           define the following system-wide logical name to point(           to the application table file:  G                $DEFINE/SYSTEM/EXEC SETUP_SECTION dev:[dir]SETUP_SECTION   =           This command should also be included in your system ;           startup command procedure, and should be executed >           on all nodes in your cluster if you run a VAXcluster           system.   %           ___________________________       1.2.1  Defining Applications   @           To ease the definition of SETUP applications, create a?           SETUP_CMDS.DAT file to store the APPLICATION commands @           used by SETUPDEF. The APPLICATION command is described&           in Part II of this document.  >           It is important to assign meaningful but brief names8           to your applications. If you maintain multiple;           versions of some applications simultaneously, you >           may want to include some kind of version information9           in the name. For example, when a new version of 9           an application comes in, you could define it as @           application NEW_name. When it has been tested, you can@           then make the new version available as just name while>           moving the older version to OLD_name. This way, when  
           1-2          A                                                  Installing SETUP       =           users just include SETUP name in their LOGIN files, >           they get the most current version considered stable.  %           ___________________________   "    1.2.2  Ordering the Definitions  <           The SETUPDEF program stores the definitions in the=           application table in the order that they are given, ?           without any form of sorting. You may wish to sort the >           definitions in your SETUP_CMDS.DAT file so that they=           are either in alphabetic order for better listings, ?           or in most-used-first order for faster access (though =           access should be fast enough unless the application '           table is inordinately large).   %           ___________________________       1.2.3  Running SETUPDEF  >           Once you have entered your APPLICATION commands into9           the SETUP_CMDS.DAT file, just type RUN SETUPDEF 7           to create the new application table. SETUPDEF :           will display an informational message about each9           application it places in the table. If SETUP is =           installed with SYSPRV, no further action is needed; >           otherwise, you should be sure that the SETUP_SECTION'           file is protected WORLD:READ.   L           __________________________________________________________________  "    1.3    Using Access Restrctions  :           SETUP provides two forms of access restrictions::           node-based restrictions and access control lists6           (ACL's). Both can be used to tailor a single?           application table for use by several groups of users.   =           Node-based restrictions are useful when you have an <           application that is licensed only on certain nodes=           in your VAXcluster, or for any other reason you may <           have for restricting its use to certain nodes. The:           application shows up in SETUP/LIST on all nodes,=           but an attempt to use SETUP on an unauthorized node @           returns the message "application not available on this  A                                                               1-3                     Installing SETUP      >           node". Users can type SETUP/LIST/FULL to display the=           list of nodes on which the application may be used.   <           ACL's are useful when you have a centrally managed;           application that should be used only by a certain <           group of users. You can key the ACL's by UIC or on>           an identifier. READ (which allows SETUP/LIST access);           and/or EXECUTE (which allows the execution of the             setup) can be granted.  =           If ACL's are used to protect the setup information, =           you should also be sure that the application table, 8           the setup command procedures, and applications9           themselves are adequately protected. Generally, >           users will need only EXECUTE access to setup command:           procedures and the directories in which they are>           stored. No WORLD access to the SETUP_SECTION file is@           required if SETUP is installed with SYSPRV or READALL.  L           __________________________________________________________________  *    1.4    Building Robust Setup Procedures  @           Most applications will need to have command procedures<           executed for their setups. You should be sure that4           these command procedures are coded so that  @           o  they define what they need without interfering with<              other symbols, logical names, etc. the user may              need;  :           o  they cannot be tripped up by unusual symbols,7              logicals, etc., the user may have defined;   @           o  they can be executed multiple times without any ill              effects.   >           Some third-party application vendors don't bother to@           code the setup command procedures they provide so that@           they abide by these rules, so it is prudent to examine>           any provided procedures carefully and modify them as           needed.   
           1-4          A                                                  Installing SETUP       <           The following is an example of the kind of command<           procedure that follows the robustness rules listed           above.  N           $ V = 'F$VERIFY (0)                ! prevent SET VERIFY interference           $! Setup for ACSL            $!J           $ SET := SET                       ! prevent symbol interference           $ IF := IFX           $ DEFINE := DEFINE/NOLOG           ! use /NOLOG to eliminate "superseded" msgs           $ EXIT := EXIT           $!           $ SET NOON3           $ DEFINE ACSL_SYS ECS_SYS6:[ACSL.ACSL8.S] /           $ DEFINE ACSLLIB ACSL_SYS:ACSLL8R.OLB /           $ DEFINE ACSLSHR ACSL_SYS:ACSLL8R.EXE /           $ DEFINE ACSLHLP ACSL_SYS:ACSLH8R.HLB /           $ DEFINE ACSLSPR ACSL_SYS:ACSLSPR.OLB /           $ DEFINE ACSLKEY ACSL_SYS:ACSLKEY.DAT ,           $ DEFINE ACSLOPT ACSL_SYS:ACSL.OPT%           $ SET COMMAND ACSL_SYS:ACSL            $!E           $! The following DCL code adds the ACSL help library to the F           $! process-local list of help libraries.  It first checks toD           $! see if the library name is already present, and if not,@           $! adds it to the search list logical name definition.           $!(           $ HLP_NAME := ACSL_SYS:ACSLH8R8           $ HLP = F$TRNLNM ("HLP$LIBRARY","LNM$PROCESS");           $ IF HLP .EQS. HLP_NAME THEN EXIT 1+0*F$VERIFY(V)            $ I = 0 .           $ IF HLP .NES. "" THEN GOTO HLP_LOOP(           $ DEFINE HLP$LIBRARY 'HLP_NAME            $ EXIT 1+0*F$VERIFY(V)           $HLP_LOOP:           $ I = I + 1 !           $ IF I .GT. 9 THEN EXIT =           $ HLP = F$TRNLNM ("HLP$LIBRARY_''I'","LNM$PROCESS") ;           $ IF HLP .EQS. HLP_NAME THEN EXIT 1+0*F$VERIFY(V) .           $ IF HLP .NES. "" THEN GOTO HLP_LOOP  A                                                               1-5                     Installing SETUP      ,           $ DEFINE HLP$LIBRARY_'I' 'HLP_NAME            $ EXIT 1+0*F$VERIFY(V)  L           __________________________________________________________________       1.5    Sample SETUP_CMDS File  9           The following is a sample SETUP_CMDS file which 3           contains several application definitions.              ! 8           ! ABAQUS: can be used only by authorized users           ! >           APPLICATION ABAQUS/SETUP="@RPI$ROOT:[SETUP]ABAQUS7"-"               /DESC="ABAQUS V4.7"-<               /ACCESS=((IDENTIFIER=ABAQUS_USER,ACCESS=R+E),-4                     (IDENTIFIER=[SYS,*],ACCESS=R+E))  :           APPLICATION ACSL/SETUP="@RPI$ROOT:[SETUP]ACSL9"-O               /DESCRIPTION="Advanced Continuous Simulation Language Version 9B"   ?           APPLICATION DISSPLA/SETUP="@RPI$ROOT:[SETUP]DISSPLA"- E               /DESCRIPTION="CA-DISSPLA graphics package Version 10.5"              ! 1           ! MACSYMA: only available on the 6320's            ! ?           APPLICATION MACSYMA/SETUP="@RPI$ROOT:[SETUP]MACSYMA"- ,               /DESCRIPTION="MACSYMA 412.61"-!               /NODE=(ECS01,ECS02)   C           APPLICATION MOVIE.BYU/SETUP="@RPI$ROOT:[SETUP]MOVIE-BYU"- +               /DESCRIPTION="MOVIE.BYU V6.2"   G           APPLICATION NEW_DISSPLA/SETUP="@RPI$ROOT:[SETUP]NEW_DISSPLA"- C               /DESCRIPTION="CA-DISSPLA graphics package Version 11"   M           APPLCIATION TELL-A-GRAF/SETUP="@RPI$ROOT:[SETUP]TELL-A-GRAF"/DESC=- 6               "CA-Tell-a-Graf graphics generator V6.0"  H           APPLICATION TEX/SETUP="@RPI$ROOT:[SETUP]TEX"/DESC="TEX V2.991"  
           1-6          A                                                  Installing SETUP                  ! A           ! Applications with the UNSP: prefix are "unsupported".            ! @           APPLICATION UNSP:EMACS/SETUP="@RPI$ROOT:[SETUP]EMACS"-;               /DESC="GNU Emacs version 18.52 (UNSUPPORTED)"                                                                         A                                                               1-7n m  o          A           _______________________________________________________     '           Part II  Command Descriptionsa V  i    A                                              Command Descriptions A                                                             SETUPe    A           _______________________________________________________              SETUP       $           Application setup command.  A           _______________________________________________________i             FORMAT             SETUP  appl-name  A           _______________________________________________________o)           Command Qualifiers     Defaultsg             /FULLu           /INITIAL           /LISTa  A           _______________________________________________________              PARAMETERS           appl-namer8           The name of the application to be set up. When<           the /LIST qualifier is used, this can be a pattern(           including wildcard characters.  A           _______________________________________________________t             DESCRIPTION   :           The SETUP command is used to provide the logical8           names, symbols, commands, etc. needed to use a=           particular application. Typically, each application ?           needs to be set up for each terminal session or batch <           job, so it may be a good idea to include the SETUP@           command for the applications you use in your LOGIN.COM           file._  A                                                             CMD-3n n  h               Command Descriptions           SETUP     >           Some applications may also require a one-time setup,@           which might create files or directories needed for use?           of the application, etc. Any applications requiring a @           one-time setup will be listed as such when you use the           SETUP/LIST command.   A           _______________________________________________________              QUALIFIERS           /FULLt=           Used only with the /LIST qualifier, /FULL specifies =           that a more informative listing of each application ?           should be displayed, including a one-line descriptioni<           of the application (if available) and any per-node$           availability restrictions.             /INITIAL<           Specifies that the one-time setup commands for the8           application should be executed, instead of the;           per-login setup commands. If there is no one-time 8           setup for the application, an error message is           displayed.             /LIST 9           Lists the available applications, including the 8           application name and types of setups available&           (per-login and/or one-time).                                       CMD-4_ _  _    A                                              Command DescriptionsdA                                                       APPLICATION     A           _______________________________________________________              APPLICATION       @           In the SETUPDEF utility, defines an application setup.  A           ________________________________________________________             FORMAT              APPLICATION  appl-name  A           _______________________________________________________e)           Command Qualifiers     Defaults              /ACCESS=aclt           /DESCRIPTION=descP           /INITIAL=onetime-cmd           /NODE=node-list            /SETUP=perlogin-cmd   A           ________________________________________________________             PARAMETERS           appl-name =           Name of the application to be defined. The name mayc<           consist of any characters, but should probably not=           include spaces or tabs, asterisks ("*"), or percent            signs ("%").  A           _______________________________________________________              QUALIFIERS           /ACCESS=aclP;           Specifies an access control list to govern access :           to the application setup information. The access?           control list should contain identifer ACE's which may_=           grant EXECUTE and/or READ access. EXECUTE access isG>           required for a user to execute the application setup@           command; READ access is required for a user to see the1           application definition with SETUP/LIST.i  A                                                             CMD-5_ _  _               Command Descriptions           APPLICATION     <           If you do not use the /ACCESS qualifier, access is?           assumed to be granted to all users for any operation. @           If you do use the /ACCESS qualifier, access is assumed;           to be denied to all users not covered by the ACL.   ;           Using /ACCESS to protect setup information is not 9           effective unless the SETUP_SECTION file is also >           protected (with no WORLD access), which will require8           that SETUP be installed with SYSPRV or READALL>           privilege. You should also protect the setup command:           procedures themselves (giving WORLD only EXECUTE<           access) as well as the directory or directories in2           which they are stored (also W:E access).             /DESCRIPTION=desc <           Attaches a brief description of the application to>           the definition for display with SETUP/LIST/FULL. The;           description should be enclosed in quotation markst?           and should probably included the complete name of thee&           application and the version.             /INITIAL=onetime-cmd4           Defines the one-time setup command for the=           application. Any command, including "@" for commandU:           procedure execution, is allowed. If omitted, the;           application is assumed to have no one-time setup.              /NODE=node-list :           Specifies that the application is only available<           on VAXcluster nodes matching one of the node names:           specified in node-list. The specified node names;           may include wildcard characters; if more than onet8           is specified, the list should be surrounded by:           parentheses and separated by commas. Attempts to>           use SETUP for the application on a non-matching node=           results in an informational message indicating thatN+           the application is not available.i  @           If omitted, the application is assumed to be available           on all nodes.              CMD-6g .       A                                              Command Descriptions A                                                       APPLICATION,               /SETUP=perlogin-cmdl5           Defines the per-login setup command for the]=           application. Any command, including "@" for commandl:           procedure execution, is allowed. If omitted, the<           application is assumed to have no per-login setup.                                                                        A                                                             CMD-7 