INSTALL JUMP ============ Installation instructions for JUMP V5.0 2005-02-19 (19-Feb-2005) Preparation ----------- It is *strongly* recommended you thoroughly read the following files before installing JUMP: - JUMP.HLP = HELP file - JUMP_ACCESS.DAT = example Access List file - CHANGES.TXT = change history of each version of JUMP Requirements ------------ JUMP supports OpenVMS on VAX, Alpha and IA64. It requires versions of OpenVMS which support the following features: - Pseudo-terminals - Callable Mail - LIB$TABLE_PARSE JUMP does NOT require PERSONA system services. JUMP is written almost entirely in HP Pascal and comes with pre-compiled object modules for all Pascal sources for all architectures (VAX, Alpha and IA64). Compilation of Pascal sources is not required to build JUMP. If re-compilation is desired for some reason, HP Pascal is required. NOTE: The definition of privilege sets has been adopted for ease of coding. The source for the information is SYS$LIBRARY:STARLET.PAS. The definition will need reviewing with each release of OpenVMS! *** CAUTION: JUMP has dependencies on the underlying architecture *** *** (VAX, Alpha or IA64) and the version of OpenVMS. Any *** *** changes to either of these REQUIRES JUMP to be re-linked. *** Caveats ------- *** CAUTION: JUMP executes some things in KERNEL or EXECUTIVE mode!!!! *** *** DISCLAIMER: This software is provided "AS IS". It does NOT come *** *** with any representations or warranties, implicit or otherwise, as *** *** to its merchantability or fitness for any particular purpose. *** *** The user assumes ALL risks and responsibilities associated with *** *** installing and running this software. *** Installation ------------ 1. If you have not read the files specified in Preparation above, it is *strongly* recommended that you do so. 2. Ensure all requirements as specified in Requirements above are met. Ensure you have read the Caveats above! 3. Unpack the JUMP distribution file into a single directory and SET DEFAULT to that directory. 4. The Message source file for JUMP (JUMP_MSG.MSG) contains a Facility ID for JUMP. The default value for this is 111. If a different Facility ID is required, edit this file appropriately. 5. If re-compiling Pascal sources and the Pascal compiler version is V5.2 or earlier, edit the JUMP build procedure (BUILD_JUMP.COM) to modify the default value of the DCL symbol "perform" to be 0. 6. Re-link JUMP (NO Traceback): $ @BUILD_JUMP JUMP may also be built with the following options specified in P1: "C" = Compile Pascal sources in addition to normal build actions "L" = Link NO Traceback - this is the default build action "T" = Link *with* Traceback; all other build actions as normal For example, to re-compile the Pascal sources and re-link: $ @BUILD_JUMP C NOTE: The build procedure will always re-compile Macro (.MAR), Message (.MSG) and Command Line Definition (.CLD) source files. You may wish to purge any multiple copies of object and executable files after building JUMP. 7. Copy the JUMP executable (JUMP.EXE) to a suitable location: $ COPY /LOG JUMP.EXE device:[directory]JUMP.EXE 8. JUMP *requires* one or other of the following actions. Both may be done, if desired. a. If you intend to use the JUMP_ACCESS rights ID, create the identifier - the value is not relevant: $ AUTHORIZE ADD /IDENTIFIER JUMP_ACCESS and/or b. Define the JUMP_DOUBLE_CHECK logical name to be "FALSE": $ DEFINE /SYSTEM /EXECUTIVE JUMP_DOUBLE_CHECK FALSE If the JUMP_ACCESS rights ID is *not* created, JUMP_DOUBLE_CHECK *must* be defined. It is recommended that you use the JUMP_ACCESS rights ID and allow the JUMP_DOUBLE_CHECK logical name to take its default value of "TRUE". 9. If required, grant the JUMP_ACCESS rights ID to authorised users: $ AUTHORIZE GRANT /IDENTIFIER JUMP_ACCESS username 10. Create the mandatory audit trail file (JUMP_AUDIT.DAT): $ CREATE device:[directory]JUMP_AUDIT.DAT ^Z The default name for the audit trail file is "SYS_MANAGER:JUMP_AUDIT.DAT". If a different file specification is required, define the logical name JUMP_AUDIT_TRAIL appropriately: $ DEFINE /SYSTEM /EXECUTIVE JUMP_AUDIT_TRAIL file-specification If you wish, you may simply redefine SYS_MANAGER as a logical name pointing to an appropriate directory. For example: $ DEFINE /SYSTEM /EXECUTIVE SYS_MANAGER directory-specification NOTE: Ensure all logical names in the logical name translation tree for specifications are defined in EXECUTIVE mode. 11. If required, create and edit the optional Access List file (JUMP_ACCESS.DAT) - see example file for details of syntax. This file can be copied to a suitable location and edited if desired. The default name for the Access List file is "SYS_MANAGER:JUMP_ACCESS.DAT". If a different file specification is required, define the logical name JUMP_ACCESS_LIST appropriately: $ DEFINE /SYSTEM /EXECUTIVE JUMP_ACCESS_LIST file-specification If you wish, you may simply redefine SYS_MANAGER as a logical name pointing to an appropriate directory. For example: $ DEFINE /SYSTEM /EXECUTIVE SYS_MANAGER directory-specification NOTE: Ensure all logical names in the logical name translation tree for specifications are defined in EXECUTIVE mode. 12. If required, create a secure directory for placing session log files when executing EXACT jumps in secure mode. $ CREATE /DIRECTORY /LOG /OWNER=username directory-specification The default name for the secure directory is "SYS_MANAGER:". If a different directory specification is required, define the logical name JUMP_SECURE_DIR appropriately: $ DEFINE /SYSTEM /EXECUTIVE JUMP_SECURE_DIR directory-specification If you wish, you may simply redefine SYS_MANAGER as a logical name pointing to an appropriate directory. For example: $ DEFINE /SYSTEM /EXECUTIVE SYS_MANAGER directory-specification NOTE: Ensure all logical names in the logical name translation tree for specifications are defined in EXECUTIVE mode. 13. By default, the logical name JUMP_USER_DIR is defined to be "SYS$LOGIN:". However, users may define this logical name in user or supervisor mode to specify a user-specific directory for placing session log files when executing EXACT jumps NOT in secure mode. If you wish to override any user definitions, *explicitly* define the logical name. For example: $ DEFINE /SYSTEM /EXECUTIVE JUMP_USER_DIR directory-specification The default name for the user directory is "SYS$LOGIN:". It is *highly* recommended that you specify either "SYS$LOGIN:", or "SYS$DISK:[]" to force the files into the user's login directory or current directory respectively at the time of invoking JUMP. NOTE: Ensure all logical names in the logical name translation tree for specifications are defined in EXECUTIVE mode. Both SYS$LOGIN and SYS$DISK are defined in EXECUTIVE mode by the system. 14. JUMP requires the following privileges: CMEXEC, CMKRNL, DETACH (aka IMPERSONATE), SYSNAM, SYSPRV If access is required by suitably UNprivileged users, install JUMP with the those privileges. For example: $ INSTALL ADD device:[directory]JUMP /OPEN /HEADER /SHARED - /PRIVILEGE=(CMEXEC,CMKRNL,DETACH,SYSNAM,SYSPRV) 15. Define any other required logical names in the SYSTEM logical name table in EXECUTIVE mode (see help documentation for details). 16. Set appropriate secure access rights on all JUMP files and directories. The following file protections are recommended: To make JUMP generally available to all (authorised) users: JUMP.EXE (S:RWED,O:RWED,G,W:E) Set protections appropriately if more restricted access to the executable image is required. Use Access Control Lists (ACLs) if desired. Other files should be (S:RWED,O:RWED,G,W). These include: JUMP_ACCESS_LIST JUMP_AUDIT_TRAIL JUMP distribution files It is recommended that the owner of all JUMP files be SYSTEM. 17. Define a foreign command to allow JUMP to be invoked: $ JUMP :== $device:[directory]JUMP If desired, this can be defined in the SYS$SYLOGIN procedure. 18. If desired, make the JUMP help available to JUMP users. As JUMP is a powerful, privileged program, it is suggested that the help be made available such that only authorised users can access it. 19. Boing! Troubleshooting --------------- File access problems: JUMP uses a number of files, most of which need to be secure. From time-to-time, messages such as "File not found" or "Cannot access file" may be generated for particular files. Pascal may generate FILNOTFOU or ERRDUROPE errors. There are a number of possible causes. 1. Check that a file which should exist is where it is expected to be and has the correct name. (Remember that some JUMP files are mandatory; some are optional.) 2. If a file is being created (e.g., a session log), check that the appropriate directory exists. 3. Verify that the associated logical name has been defined correctly: - correct equivalence name - defined in SYSTEM logical name table - defined in EXECUTIVE mode - all logical names in iterative translations also defined in EXECUTIVE mode 4. Check that the security attributes on the file and/or directory (protections and ACLs) allow appropriate access. (Remember that JUMP requires SYSPRV and so specific individual user access is unlikely to be required.) 5. In the case of the logical name JUMP_USER_DIR, refer to step 13 in the installation instructions above, and the JUMP help file on this topic. Cannot JUMP to a valid username: 1. If using the JUMP_ACCESS rights ID, check that the username has JUMP_ACCESS granted to it in the UAF. If not using the JUMP_ACCESS rights ID, check that JUMP_DOUBLE_CHECK is defined. See installation instructions 8 and 9 above. 2. For non-Systems Programmers, check that appropriate access is granted in the Access List file. 3. Check for a username and an identifier that have the same name. $ AUTHORIZE SHOW username $ AUTHORIZE SHOW /IDENTIFIER username If an identifier exists that is the same as the username, but it is not the username's UIC identifier, JUMP will assume the username is intended, not the identifier. This affects how access lists are interpreted. See the JUMP Help file (under "Access_List") for more information.