Skip to end of metadata
  • Created by Former user, last modified by Former user on Dec 22, 2010
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

OECN RPC based on USP is considered obsolete. The SSDT recommends that ITC sites use OECN VXS for OECN RPC services. This document is retained for historical purposes for sites still maintaining a USP installation.

Introduction

Important: OECN RPC based on USP is considered obsolete. The SSDT recommends that ITC sites use OECN VXS for OECN RPC services. This document is retained for historical purposes for sites still maintaining a USP installation.

OECN State Software contains an RPC (Remote Procedure Call) service. The RPC service allows remote client software (e.g. web applications) to make remote calls to standard OECN software routines via an XML interface. The primary purpose of the RPC service is to expose standard OECN software functions and business logic for use in web based or graphical user interfaces.

The OECN RPC service allows remote software to invoke OECN software routines in a standard OECN user’s security context and enforces the same authentication and security constraints as an interactive user.

This document describes the software requirements and installation process for installing the OECN RPC service and related routines on an OpenVMS server running state software. The service is required for certain state software features.

OECN RPC Basic Operation Overview

The OECN RPC service uses USP (see below) to allow remote clients to establish a network connection to the OECN software server to perform various functions. When a remote client makes a network connection to request services, the following occurs:

  1. A detached VMS process is created to service the connection
  2. The remote client must provide an OpenVMS username and password.The service authenticates the user using standard OpenVMS authentication policies.
  3. If authentication is successful, the service process “impersonates” the user by acquiring the OpenVMS security profile of the authenticated user (i.e. default privileges and security identifiers). At this point, the VMS process has the same security rights as the authenticated user.
  4. The network client provides a code indicating the district data to be used.The OECN RPC service uses the district code and SETUPENV to define logical definitions to associate the server process with the desired district data. For EMIS, the client may also select an EMIS database.
  5. At this point, the remote client may call predefined OECN software functions that are available to the OECN RPC service. (For example, USAS functions for posting a requisition).The remote client may make as many calls as necessary while the connection is active.The VMS process remains on the system until the user disconnects.
  6. When the remote client has finished using the OECN RPC service, it disconnects from the service and the VMS process is deleted.Alternatively, the service may disconnect automatically after the configured inactivity timeout.

Please note the following:

  • For each remote client (user) a dedicated VMS process will exist on the system while the remote user is connected to the service.
  • The process created on behalf of the user does not execute the system-wide LOGIN.COM, the user’s LOGIN.COM nor is it associated with the user’s normal group logical name table.
  • Only the default privileges from the user’s SYSUAF record are enabled. The service will not enable any authorized privileges. Therefore, when the service process accesses data files, the default login security profile will be used.
  • A log file for each connection is created in USP$LOGS named OECN_RPC_n.LOG.This log file will contain any severe error messages emitted from the COBOL routines.

Software Requirements

The following software and minimum versions are required to successfully install and run the OECN RPC service:

  • OECN State Software
  • OpenVMS/Alpha Version 7.3-2
  • One of:
    • USP (Universal Service Provider) Version 6.1
    • OECN VXS v2.2-0

OECN VXS

The remainder of this document discusses USP as the transport layer for the OECN RPC service. If you prefer an alternative to USP, you should skip this document and use OECN VXS.

Universal Service Provider (USP)

USP is a middleware software product written by STABILIT and licensed by HP. HP provides an “As Is” (no cost) license for USP on OpenVMS/Alpha.USP provides the network connection, communication and process management for various forms of RPCs between network clients and servers.The OECN RPC service is layered on USP and therefore USP must be installed to support the OECN RPC service

Support for USP

The “As Is” license from HP does not provide any software support for the USP. As of July 2008, the SSDT no longer maintains a support contract with STABILIT. The SSDT will be attempt to provide support for USP to the OECN DA Sites using it with state software. However, sites having problems with USP will be encourage to switch to OECN VXS when possible for OECN RPC.

Acquiring the USP Software Installation Kit

The USP software kit may be downloaded using INSTALL_PACKAGE from OECN_DOWNLOAD. The following files are available in OECN_DOWNLOAD:

  • CPQ-AXPVMS-USP-V0601-nn-1.PCSI_EXE
  • CPQ-USP-V0601-22-INSTALL.PDF
  • CPQ-USP-V0601-22-ADMIN.PDF

The PCSI_EXE file is a compressed PCSI kit that may be decompressed and installed in the same fashion as other OpenVMS PCSI kits. The PDF files are the USP Installation Guide and USP Administrators Guide, respectively.

Alternatively, the USP Software can be obtained directly from STABILIT’s web site: http://vms.stabilit.ch/

You do not need to download or install the Java or other components for USP.

It is strongly recommended that you download and print the “USP Installation Guide”. You may also wish to have the “USP Administrators Guide” available.The other documentation on the web site is only of interest if you intend to do your own development with USP.

Installing the USP Software

See the “USP Installation Guide” for detailed instructions on installing and configuring the USP software. The USP installation is a standard PCSI layered product installation. It is not necessary to reboot after this installation.

We recommend the following when installing and configuring USP for use with the OECN RPC service:

  • By default, USP will be installed under SYS$COMMON. We recommend you accept the default location.
  • If warned, “CSWS (Apache Webserver) is not started yet”, answer, “YES” to continue the installation. The OECN RPC service does not require USP integration with CSWS Apache.
  • If prompted, “Do you want to use broadcast services?” answer “NO”.
  • Do not install the USP Java Client as documented in the installation guide. The USP Java client classes will be provided by the web applications using the OECN RPC service.

Post-Installation

Follow the “Post Installation Tasks” as documented in the USP Installation Guide. In particular, execute the USP$STARTUP.COM and USP$SHUTDOWN.COM in SYSTARTUP_VMS.COM and SYSHUTDWN.COM, respectively. Rename the template startup file, as recommended in the install guide to allow automatic startup.

If you have CSWS (Apache) running, the USP installation will modify your HTTPD.CONF file to enable USP and CSWS integration. This is not needed by the OECN RPC service. It does no harm to leave the integration enabled, but you may comment out the include directive for MOD_USP.CONF from your HTTPD.CONF.

Configuring the OECN RPC Service

After USP is installed and is running, you must execute OECNRPC_CONFIG.COM in OECN$ to configure the OECN RPC service.OECNRPC_CONFIG provides the basic configuration of the USP service and ensures the system is properly configured to support the OECN RPC service.

OECNRPC_CONFIG.COM attempts to verify that USP has been properly installed and configured. You must install and configure USP prior to using this procedure.

Start the configuration process with:

$ @OECN$:OECNRPC_CONFIG

See the following sections for more information about the operation of the configuration utility.

OECNRPC Username

The OECN RPC service runs under a special username called OECNRPC. This username has specific quota and privilege requirements.The first time you execute OECN$:OECNRPC_CONFIG.COM, the procedure will verify if the OECNRPC user exists on the system.If OECNRPC user does not exist, it will offer to create it for you.

When creating the OECNRPC user OECNRPC_CONFIG will ask you for the following:

  • _UIC group _for the OECNRPC user:You should enter the octal group number.The first available member number in the group will be determined automatically.The default is group 376, which is commonly used for network service processes on OpenVMS.
  • Login device/directory for the OECNRPC user: This directory may be used for log and other temporary files.The default is SYS$SYSDEVICE:[OECNRPC].

Logicals

Several logicals affect the behavior of the OECN RPC service.

OECN$RPC_DEBUG_username

Enables RPC debug mode for the specified user. Causes additional debug messages to be logged to the session log file (USP$LOGS:OECNRPC*.LOG) and causes request and response XML files to be written to user's SYS$LOGIN. Must be defined system-wide or as a process logical in an OECN RPC prologue file.

For example:

$ DEFINE OECN$RPC_DEBUG_SMITH "YES"

Enables debugging mode for the VMS user "SMITH".

OECN$ACME_PROCESS_TYPE

The OECN RPC service uses the ACME system services to authenticate and impersonate users. This logical determines the type of VMS process (NETWORK or REMOTE) to use for authentication. The choice of process type determines which SYSUAF and VMS security policies apply to the process.

NETWORK will apply the SYSUAF /NETWORK access restrictions and will ignore expired passwords.

REMOTE will apply SYSUAF /REMOTE access restrictions and will prevent login with expired passwords.

This logical must be defined as a system-wide logical or in an OECN RPC Prologue procedure. For example, to treat OECN RPC processes as REMOTE:

$ DEFINE/SYSTEM OECN$ACME_PROCESS_TYPE "REMOTE"

The default is "NETWORK" for compatibility with previous releases.

This features has been available since the March 2007 release.

USP Configuration

OECNRPC_CONFIG automatically modifies the USP configuration to support the OECN RPC service. The first time that OECNRPC_CONFIG is executed it will check to see if the OECN_RPC service is defined in USP. If not, it will offer to create it for you.

When creating the OECN_RPC service in USP, the procedure will ask you for the following parameters:

  • _Maximum number of concurrent connections: Indicate the maximum number of concurrent connections you wish to support. Enter “?” for additional information.
  • _Inactivity timeout in minutes: _Indicate the desired timeout for inactive connections.Enter “?” for additional information.

The protection on USP$LOGS directory will be modified to permit “world write” access to the log directory. This is necessary to permit the OECNRPC user and non-privileged state software users to create log files in this directory.

Additional Features of OECNRPC_CONFIG.COM

After the initial configuration, the OECNRPC_CONFIG procedure may be used to re-configure or manage the OECNRPC service. This provides a simplified management interface to the USP administrative functions.

When run after the initial configuration, the procedure offers the options described below:

Reset OECNRPC user account quotas and properties

Periodically, the SSDT may change the quota requirements for the OECNRPC user. This option resets the quotas to the SSDT recommended quotas and ensures that the username is active and configured properly.

Re-configure OECNRPC USP service parameters

Reconfigures the OECN_RPC service in the USP configuration to ensure it matches the SSDT defaults for the service. Also allows the ITC to change the timeout and maximum servers

START the OECNRPC service

Starts the OECNRPC service in USP. Use this option if the service had been previously stopped.

STOP the OECNRPC service

Stops the OECNRPC service after all current connections have terminated.

ABORT the OECNRPC

Abort the OECNRPC service.Current connections to the service are aborted immediately.

DISABLE the OECNRPC service

Disable the OECNRPC service to prevent subsequent connections. Clients will not be able to establish a connection while the service is disabled.

ENABLE the OECNRPC service

Enable the service after it was disabled.

SHOW the OECNRPC service

Show the current status of the service including the number of current and active connections. If the service is not running or there have not been any connections since USP startup, the service may display as “no such service”. This is normal.It means that the service has not been activated.

LIST the current configuration

Show detailed configuration and version information about the USP configuration. The SSDT may request that you perform this option and send the output if you are having difficulty with the service.

REMOVE the OECNRPC service

Completely removes the OECNRPC service from the USP configuration. Use this option only if you intend to remove OECNRPC from the system, or need to re-create the service from scratch.

SETUPENV Requirements

A significant feature of the OECN RPC service is that it provides a server process environment that is very similar to an interactive user. This security profile and logical environment allows OECN software routines to function in an environment that is nearly identical to an interactive user.

However, because the OECN RPC service initially logs into the OECNRPC user as a detached process and then impersonates a state software user, it does not execute the user’s LOGIN.COM and the process is not associated with the user’s normal group logical name table.

Therefore, the OECN RPC service requires an alternative method of associating a user service login with the appropriate data directory. In other words, logicals such as OECN$DTA and OECN$EMIS$DTA must be defined using a method other than LOGIN.COM or group name tables.

The OECN RPC service uses the SETUPENV API for the following:

  • Determine which district, or districts, the user may be allowed to access
  • Set the logicals as defined in SETUPENV as requested by the remote user

Therefore, each DA Site must establish a minimal OECN$SETUP.INI file in OECN$CUSTOM that contains enough information to establish the logical environment required by the software routines being used. An entry (section) in OECN$SETUP.INI must exist for each district which will be using an application using the OECN RPC service.

Districts acting as their own DAS for EMIS purposes must establish an OECN$SETUP.INI file. This is the case, even if there will only be a single district entry in the file.

Minimum SETUPENV parameters for OECN RPC

The table below shows the minimal SETUPENV parameters that are required by the OECN RPC service for each district. Entries without these minimal settings will not be accessible by OECN RPC based applications.For ITC's already using SETUPENV for district entries, the existing entries should be adequate provided they meet the described minimums.

·Table 1 Minimal SETUPENV parameters

Parameter

Value

Notes

SECTION

district code

Entity code for the district

DESCRIPTION

District name

Description of the district as it will be seen by the remote user

TYPE

DISTRICT

OECN RPC will only allow access to “DISTRICT” type entries

LOGICAL
Or:GROUP_TABLE
Or:TABLE

[Varies by package]

At a minimum, each district entry must provide a definition for logicals required by the package(s) being used by the district. For USAS and USPS, OECN$DTA must be defined. The definition may be provided as a hard-coded location using LOGICAL or as a reference to a logical name table, as appropriate for the DAS configuration. For EMIS, the entry might provide a definition for EMIS_ROOT or other similar logical that is used in conjunction with EMIS_SELECT.

IDENTIFIER

UIC or identifiers

One or more IDENTIFIER parameters must be specified to allow access to the appropriate users. OECNRPC will not permit a remote client to see entries to which they have not been explicitly granted access.

EMIS Configuration

OECN RPC will also use SETUPENV to establish the EMIS logical context for multiple databases. This is done using the same OECN$EMIS_DBS file used by EMIS_SELECT. Therefore, sites using OECN RPC must establish the standard OECN$EMIS_DBS file to define the available databases.

Example OECN$SETUP.INI file

Below is an example of a minimal OECN$SETUP.INI file suitable for OECN RPC. The example has been simplified to just the parameters required by OECN RPC. However, DA Sites are free to use other features of SETUPENV to set logicals depending on their configuration and other uses of SETUPENV. See the OECN System Managers Manual for more information regarding SETUPENV and the OECN$SETUP.INI file.

! Define entry for District A
!
SECTION=DISTA
TYPE=DISTRICT
DESCRIPTION="District A"
LOGICAL=OECN$DTA,DKA100:[DISTA.DATA]
IDENTIFIER=”[DISTA,*]”      ! UIC group of District A users
! Define entry for District B
!
SECTION=DISTB
TYPE=DISTRICT
DESCRIPTION="District B"
LOGICAL=OECN$DTA, DKA100:[DISTB.DATA]
IDENTIFIER=DISTB_BUSINESSOFFICE  ! Identifier of District B Business Office users
IDENTIFIER=DISTB_SECRETARIES     ! Identifier of District B Secretaries posting REQs

Purpose of IDENTIFIER parameter

The OECN RPC handles some aspects of OECN$SETUP.INI differently than the DCL SETUPENV utility. In particular, for entries that do not have an IDENTIFIER parameter, the default is different for OECN RPC and the SETUPENV utility. This may have an impact on ITC's that are using SETUPENV but have not put IDENTIFIER parameters on their entries. ITC's who have been using SETUPENV only for ITC staff may find that they do not have the appropriate IDENTIFIER settings.

For SETUPENV used interactively, the default IDENTIFIER parameters is:

IDENTIFIER=”[*,*]”

This allows all users to see the entry. For OECN RPC the default IDENTIFIER is:

IDENTIFIER=OECN_SYSMAN

This restricts the entry to only OECN DAS personnel by default. This difference in behavior is intended as a security constraint to make it more difficult for remote network clients from discovering district databases inappropriately. It also reduces confusion on the remote client by preventing a user from attempting to select a district they do not have access to.

It is important to understand that the IDENTIFIER parameters for each entry do not grant the user access to the RMS data files for the district. OECN RPC and SETUPENV do not override standard OpenVMS ACL/UIC based security on the data files.The user’s UAF privileges, rights, and ACL/UIC protections on the data files determine whether the user can access the data. The IDENTIFIER parameter merely determines which users are allowed to see the district entry as an option when they use the OECN RPC service, but does not necessarily imply they will be able to access the data files.

  • No labels