[OPUS]

Frequently Asked Questions

OPUS Installation

OPUS Installation

What are the system requirements for the OPUS software?

OPUS currently runs on the following operating systems: 
	- Solaris 2.7
	- OpenVMS / VAX 7.1
	- OpenVMS / AXP 7.1
	- Tru64 Unix 5.0A
	- Redhat Linux 6.1
However, the VMS versions are not currently available for broad distribution. We could add VMS to the distribution in the future if there is a demand for it. Plans are also underway to port OPUS to the Windows NT platform.

The processes that form your pipeline will determine how fast a CPU and how much memory are required. The disk space requirements of OPUS vary depending on the type of installation desired and the size of your pipeline processes and datasets. In general, your system should be capable of running the pipeline processes outside of the OPUS environment to a satisfactory performance level; this will ensure satisfactory performance within the OPUS environment.

Additional requirements: A CD-ROM drive is required to install software from the OPUS CD-ROM; X Windows is required to run the Motif managers; Unix versions of OPUS rely on the C shell interpreter.

How much disk space is required to install the OPUS system?

The "opus_install" script requires you to have ~35 KB free for a CD installation ("Option 1") or, for a disk installation ("Option 2"), 38 MB with the GIF files; 13 MB without. Additional space is required to run the sample pipeline.

Can I run OPUS on a network of computers?

Yes.

In fact, OPUS specifically was designed to allow for distributed processing across several networked computers. The primary requirement is that all computers that are part of the OPUS pipeline be able to see the OPUS blackboard and executables. This implies that there must be common disk space shared among all of the networked computers (an NFS mounted volume, for example). In addition, Unix systems must be reachable with the rsh facility (i.e., the rsh service must be activated in your inet daemon configuration file, and the appropriate rhosts files must be present).

Does OPUS require special privileges to run?

No.

A user does need to have an account on each machine that is to run OPUS processes, however, and the accounts must allow rsh access. You can test whether or not your accounts are configured to allow rsh access by attempting to execute a remote command with rsh. For example, suppose you have accounts on two machines, foo and bar, that will run OPUS processes. To test whether you have rsh access you might try the following command from foo: 

   rsh username@bar ls
where "username" is your login name on bar. You might have to use a full domain name specification (e.g., bar.yourdomain.edu) if bar is not on your local network.

If successful, you should get a directory listing of your login directory on bar. If you received a "Permission denied" error message, then most likely you do not have a .rhosts file on bar. Refer other problems to your system administrator.

How do I obtain the OPUS system?

You can install the OPUS system from the distribution CD-ROM. To obtain a CD-ROM, or to report any problems with your CD-ROM, send e-mail to opushelp@stsci.edu.

Do I have to put the OPUS distribution in a specially named directory?

The OPUS installation procedure allows you to choose where to install the OPUS distribution directory tree. The location of this directory is not important although it must be available to all systems that will use OPUS. The default location is /usr/local, and if you choose to install OPUS there, you will need the appropriate write access.

Can I run OPUS straight out of the box?

Yes, you can run OPUS from the CD-ROM. You will still need to create an OPUS directory tree on your disk, but only those files that must be installed from CD-ROM in order to run OPUS will be copied over. This option reduces the total installation size necessary for running OPUS, but requires that the CD-ROM be accessible during a run. In addition to creating a directory structure and installing a limited number of files, you will need to configure at least one account for the OPUS environment.

How do I install the OPUS distribution?

The installation takes only a few minutes.

First, the OPUS CD-ROM must be mounted on the system on which you wish to install the software. Once the CD-ROM is available, you can access the README file in the install directory on the top-level of the CD. The README file contains late-breaking information relevant to OPUS installation. Be sure to read the contents of this file before proceeding.

The installation script "opus_install" in the install directory will guide you through the rest of the installation. It presents you with two installation options (CD or disk) and an option to configure your account to use OPUS. Only the first two options are relevant at this point. 


   --------------------------------------------
   - Welcome to the OPUS Installation Script! -
   --------------------------------------------

   Please choose from the following items:

      [1] Setup OPUS to run from CD-ROM

      [2] Setup OPUS to run from a local disk

      [3] Configure a user account to use OPUS for the first time

      [4] Upgrade existing version of OPUS to v2.2

      [5] Upgrade an existing v1.4 user account to v2.2

      [6] Exit


      Selection:
You must decide whether to install OPUS to run from the CD-ROM (in addition to a minimal set of disk files) or exclusively from your disk. The latter option requires more disk space to install, but it allows you to use OPUS without accessing the CD-ROM at run-time.

Execute the "opus_install" script by entering: 

   [cd_path]/install/opus_install
where "[cd_path]" is the path to where your CD-ROM is mounted, and follow the on-screen instructions.

What do I do if the installation fails?

The installation script provides descriptive error messages whenever possible during installation. In most cases, installation problems can be corrected by interpreting the error message. For example, if the error message indicates that the installation failed trying to create the OPUS directory tree because of write permissions, either a new install location must be chosen for the software or the target directory permissions must be changed to allow creation of a directory there by the installer.

Should installation fail at some point, it is possible that only a partial installation was done or that one or more of the OPUS files was left incomplete. A list of all files that the installer copies to your system for each installation option is provided in files named 

   install_tree_cd.txt
   install_tree_disk.txt
in the install directory of the OPUS CD-ROM. Refer to these files to verify that a complete installation was done if you encounter problems during installation.

How do I uninstall the OPUS distribution?

The OPUS distribution is contained under the directory "opus" created at the location specified by the user at installation. To delete the distribution, simply delete the contents of this directory and all of its subdirectories. For example, if you installed OPUS in /usr/local, you would delete the OPUS distribution by issuing the command 
   /bin/rm -rf /usr/local/opus
This will remove the OPUS distribution from your disk, but it will not remove modifications to individual users' .cshrc files or remove their OPUS_HOME_DIR directories. Individual OPUS_HOME_DIR directories can be removed by each OPUS user in the same manner as the OPUS distribution using rm. Users can remove OPUS modifications to their .cshrc files by deleting lines containing "041367OPUS" with a text editor.

How do I configure my accounts to run OPUS?

Each account that will run OPUS processes must have access to the OPUS executables. On Unix systems, this is accomplished by adding the path to the OPUS executables to your default path. OPUS uses the C shell, so the path must be modified in the .cshrc file in your home directory. The install script, "opus_install", has an option to configure individual accounts to use OPUS. Note that the OPUS distribution must be installed before selecting this option. This option will modify your .cshrc file by adding a "set path" statement similar to the following: 
   # (041367OPUS:1) *******************************************************
   # (041367OPUS:2) THE FOLLOWING LINES WERE ADDED BY THE OPUS_INSTALL.
   # (041367OPUS:3) SCRIPT. DO NOT MODIFY ANYTHING BETWEEN THE *'S
   # (041367OPUS:4)
   # (041367OPUS:5) OTREE /home/mydir/opus/
   set path = ( /cdrom/bin/sparc_solaris /cdrom/com/ $path )
   source /home/mydir/opus_test/definitions//opus_login.csh     # (041367OPUS:7)
   # (041367OPUS:8) *******************************************************
It now will also add a line to source your opus_login.csh file. Be certain to source your .cshrc file before you begin OPUS.

Unix systems also use the rsh service to initiate processes on all nodes. To use this service, you must create a .rhosts file in the login directory of each account on each node that will run OPUS pipeline processes. This file should contain entries for every node. Refer to the rhosts man page for a detailed description of this file. In general, each .rhosts file should contain two entries, separated by white space, per line. The first entry specifies a host name, the second entry a login name. Each line grants rsh access to your account from the host named in the first entry by the user named in the second entry, bypassing the normal password authentication procedure.

For example, to allow access to your account smith on foo by user smith on bar, the following line should be added to the .rhosts file on foo: 

   bar smith
Be sure you understand the potential security implications before creating this file.

NOTE: Names of nodes that are to be used for OPUS pipeline processing may not be longer than 6 characters. This limitation is driven by the amount of space allotted for the process name in the "NODE" field of the process status file.

What is the OPUS directory structure?

The OPUS directory structure consists of two directory trees (possibly merged). There is the OPUS distribution directory, named opus, that was created at installation time. It contains directories that hold the OPUS executables, script files, help files , etc., and any of the processes that you add to the OPUS pipeline. Each OPUS installation need have only one OPUS directory tree, but all OPUS users must have read access to this directory.

The directory structure on the CD-ROM contains the following directories. When you run the installation script to install onto your local disk, these directories will be created: 

   bin/			! executables and scripts
   bin/axp_unix/	! ...for the Tru64 Unix platform
   bin/linux/		! ...for the Linux platform
   bin/sparc_solaris/	! ...for the sparc_solaris platform
   com/			! command procedures or scripts (fxlogin.csh)
   dat/			! sundry data files
   db/			! database files
   definitions/		! OPUS resource files
   definitions/unix/	! OPUS resource files; unix specific
   gif/			! Input data for the sample pipeline
   hlp/			! Help files for the applications
   html/		! HTML directory including opusfaq.html
   install/		! Installation scripts and tar files
   lib/			! OAPI library
   lib/axp_unix/	! ...for the Tru64 platform
   lib/sparc_solaris/   ! ...for the sparc_solaris platform
   lib/linux/   	! ...for the Linux platform
   uid/			! Motif user interface definition files.
In addition each user will have his or her own set of directories for local operations. Except for the definitions directory which can contain files that override the delivered definitions, you should consider the contents of these directories as temporary: they can and should be emptied prior to using the OPUS sample pipeline: 
   ~/opus_test/home/	    	!contains process log and status files 
   ~/opus_test/home/lock/	!contains lock files dynamically created during PSF updates 
   ~/opus_test/definitions/     !overrides the delivered definitions
   ~/opus_test/g2f/input/       !copy the data you want to test here
   ~/opus_test/g2f/obs/	        !contains the path-specific observation status files
   ~/opus_test/g2f/obs/lock/	!contains lock files dynamically created during OSF updates
   ~/opus_test/g2f/fits/	!contains the output of the sample pipeline
   ~/opus_test/quick/input/     !A second path simulating quick-look data
   ~/opus_test/quick/obs/
   ~/opus_test/quick/obs/lock/
   ~/opus_test/quick/fits/
   ~/opus_test/repro/input/     !A third path simulating reprocessing.
   ~/opus_test/repro/obs/
   ~/opus_test/repro/obs/lock/
   ~/opus_test/repro/fits/

What environment variables are required?

The user-adjustable environment variables that OPUS needs are defined in opus_login.csh which is located in your OPUS_HOME_DIR. The version of this file created at installation will serve as a template for your pipeline and is fully functional for use with the sample pipeline. It defines a minimum set of environment variables necessary to use OPUS with the sample pipeline.

For the sample pipeline discussed below, the opus_login.csh file looks something like this: 


#!/bin/csh -X
#
#-----------------------------------------------------------------------------
#
#       OPUS login
#
# This file is a template of opus_login.csh.  Any of these variables can
# be stretched through your own area.  Also you can add any additional
# variables to this file for your own application.
#
# Your customized version of this file should be placed in the directory
# you define below as opus_definitions_dir.
#
# **************************************************************************
# **************************************************************************
# *********                                                         ********
# *********  Look for the angle brackets <...> below to find where  ********
# *********  to insert parameters for your run-time environment.    ********
# *********                                                         ********
# **************************************************************************
# **************************************************************************
#
#            PR
#   DATE   NUMBER   User   Description
# -------- ------   ------ ----------------------------------------------
# 04/22/97 33431    WMiller Initial code
# 12/29/98 38080    WMiller Configure XUSERFILESEARCHPATH dynamically
# 04/20/00 41456    WMiller Configure LD_LIBRARY_PATH dynamically
#
#-----------------------------------------------------------------------------
#
#=================== BEGINNING OF USER-DEFINED VARIABLES =====================
#-----------------------------------------------------------------------------
# Define variables for YOUR shell environment.  Examples of every user-
# defined variable precede the actual definitions.  Do NOT copy these
# verbatim.  Use disks and directory trees in YOUR OWN ENVIRONMENT.  Replace
# all angle brackets <...> and their contents with the appropriate values.
#
# setenv SOGS_DISK <"/home/smith/opus/ /usr/local/opus/">
setenv SOGS_DISK "/info/devcl/pipe/heller/sample//opus/"
#
# setenv OPUS_DEFINITIONS_DIR 
setenv OPUS_DEFINITIONS_DIR "/home/heller//opus_test//definitions/ SOGS_DISK:/de
finitions/unix/ SOGS_DISK:/definitions/"
#
# location for PSTAT files and process log files
# setenv OPUS_HOME_DIR 
setenv OPUS_HOME_DIR /home/heller//opus_test/home//
#
#====================== END OF USER-DEFINED VARIABLES =========================
#
# location for default X-resource files (pmg and omg)
if ( $?XUSERFILESEARCHPATH ) then
   setenv XUSERFILESEARCHPATH ${XUSERFILESEARCHPATH}:$HOME/%N.dat
else
   setenv XUSERFILESEARCHPATH $HOME/%N.dat
endif
#
# location for shared libraries
if ( $?LD_LIBRARY_PATH ) then
   setenv LD_LIBRARY_PATH /info/devcl/pipe/heller/sample//opus/lib/axp_unix/:$LD
_LIBRARY_PATH
else
   setenv LD_LIBRARY_PATH /info/devcl/pipe/heller/sample//opus/lib/axp_unix/
endif
#
set fxlogin = `osfile_stretch_file SOGS_DISK:/com/fxlogin.csh`
source $fxlogin

How do I determine whether OPUS works on my system?

Try the sample pipeline provided with the OPUS distribution to ensure OPUS is working on your system.

Can I run the sample pipeline on a network of mixed Unix types?

Yes. Since OPUS and the sample pipeline support Solaris, Tru64 Unix, and Linux, you can setup a pipeline that contains nodes running any combination of the above operating systems. You will have to do some extra configuration, however, beyond the basic installation procedure. The fundamental requirement for a mixed Unix pipeline is that all nodes see the same data and control directories; the OPUS executables for each version of Unix are installed automatically when you install OPUS to disk. For the sample pipeline, all of the data and control components are stored under the opus_test directory. With this in mind, you should select option 3 ("Configure user account to use OPUS") for only one of the host types, but choose a location to create this directory tree that is visible to all nodes in your planned pipeline.

Option 3 also modifies your .cshrc script in order to add the OPUS executable directories to your default path. Since this path is operating system dependent, you will need to modify the entries that "opus_install" makes to add support for all versions of Unix you plan to use. In particular, you will need to add one "set path" command per Unix type, and wrap each of these commands in if-else statements so that the correct "set path" command is executed for each operating system. All of this assumes that your login or home directory is the same for each Unix type; if they are not, then you need only copy the additions "opus_install Option 3" makes to your .cshrc on the host you ran it on to the .cshrc files in your other login directories with appropriate changes to the "set path" command bin directory (see below).

Each line that "opus_install" adds to your .cshrc file is indexed by the string "041367OPUS" so that you can easily identify the section of this file pertaining to OPUS. Within the block of statements labeled by this key, you will see the "set path" command mentioned above. For example, if you ran "Option 3" of "opus_install" from a Solaris workstation, the "set path" command line might look like: 

   set path = ( /home/jsmith/opus/bin/sparc_solaris/ /home/jsmith/opus/com/ $path )     # (041367OPUS:6)

The exact directory specification will vary depending on where you installed OPUS, but the important feature at present is the directory "sparc_solaris" under "bin". That is the location of the Solaris OPUS executables. For Linux systems, the directory is "bin/linux" and for Tru64 Unix, it is "bin/axp_unix".

You need to isolate this "set path" command so that it is executed only under Solaris, and add other "set path" commands, pointing to the correct bin directory, that are executed only under those operating systems. To accomplish this, duplicate the existing line exactly as many times as necessary for the other operating systems, but replace the directory under "bin" with the other operating system labels (again, "sparc_solaris" for Solaris, "linux" for Linux, and "axp_unix" for Tru64 Unix). If you were planning to run under all three supported Unix types, your changes would look like: 

   set path = ( /home/jsmith/opus/bin/sparc_solaris/ /home/jsmith/opus/com/ $path )     # (041367OPUS:6)
   set path = ( /home/jsmith/opus/bin/axp_unix/ /home/jsmith/opus/com/ $path ) # (041367OPUS:6)
   set path = ( /home/jsmith/opus/bin/linux/ /home/jsmith/opus/com/ $path ) # (041367OPUS:6)

Do not modify the label "(041367OPUS:6)", and be careful with the parentheses in the "set path" command: there must be spaces on both sides of them.

Next, you need to wrap each of these statements in if-else clauses so that only one of them is executed per operating system. To do this, make the following changes: 

   setenv HOSTTYPE = `uname -s`
   if ( $HOSTTYPE == SunOS ) then
      set path = ( /home/jsmith/opus/bin/sparc_solaris/ /home/jsmith/opus/com/ $path )  # (041367OPUS:6)
   else if ( $HOSTTYPE == OSF1 ) then
      set path = ( /home/jsmith/opus/bin/axp_unix/ /home/jsmith/opus/com/ $path )  # (041367OPUS:6)
   else if ( $HOSTTYPE == Linux ) then
      set path = ( /home/jsmith/opus/bin/linux/ /home/jsmith/opus/com/ $path )  # (041367OPUS:6)
   endif

Note that the HOSTTYPE corresponding to sparc_solaris is "SunOS", the HOSTTYPE corresponding to Tru64 Unix is "OSF1", and the HOSTTYPE corresponding to Linux is "Linux". Again, make sure there are spaces surrounding each of the parentheses.

HOSTTYPE is pre-definded in the tcsh, but it has different values from `uname -s`. The tcsh-defined HOSTTYPE corresponding to sparc_solaris is "sun4", the tcsh-defined HOSTTYPE corresponding to Tru64 Unix is "alpha", and the tcsh-defined HOSTTYPE corresponding to Linux is "i386-linux". Again, make sure there are spaces surrounding each of the parentheses.

How do I upgrade my version of the OPUS distribution to V2.2?

You must first download the upgrade distribution from the OPUS web site. If you are a licensed user of OPUS, you can obtain permission to access the upgrade page on the OPUS web site by sending e-mail to opushelp@stsci.edu. Once you have an account, proceed to the OPUS web page at

http://www.stsci.edu/opus

and select the link to the upgrade area. You will be prompted to enter your account name and password. Follow the instructions on that page to download the compressed tar file containing the upgrade. If your browser is not automatically set up to do so, uncompress and extract the tar file in a temporary directory large enough to hold approximately 45 kilobytes.

For example, if the compressed tar file were saved in /home/opus/temp, you would perform the following actions: 

% cd /home/opus/temp
% ls
opus_upgradeV2_2.tar.Z

% uncompress opus_upgradeV2_2.tar.Z
opus_upgradeV2_2.tar.Z:  -- replaced with opus_upgradeV2_2.tar

% tar xf opus_upgradeV2_2.tar
% ls
README.TXT        html/      install/   opus_upgradeV2_2.tar

%

Extracting opus_upgradeV2_2.tar creates the following files/directories in place: 

README.TXT -- this text file
html/      -- directory containing a copy of the latest OPUS FAQ
install/   -- directory containing the files necessary for the upgrade

Next, the contents of the install directory should be copied to your opus/install directory. For example, if you previously installed OPUS in /usr/local, you would need to perform the following actions: 

% cd install
% cp * /usr/local/opus/install

There is no need to copy the OPUS FAQ to your OPUS directory- the upgrade process will automatically install a new FAQ for you.

Now, run opus_install in opus/install and select option 4 to continue with the upgrade process.

Once the upgrade is complete, you can delete the files and directories extracted from the opus_upgradeV2_2.tar file, and the tar file itself. You might want to keep this README.TXT file for future reference.

What, exactly, does the upgrade process do?

Upgrading your previously installed version of the OPUS distribution replaces the executables, OPUS FAQ, and sample pipeline configuration files under the opus directory with the 2.2 versions. The old versions are overwritten, so you should back these files up if you wish to keep them- in fact, it is recommended that you perform a complete backup of the opus directory prior to upgrading to 2.2.

If you have placed any new files or directories in the opus directory, they will be preserved provided that there is no naming conflict with a version 2.2 file or directory. Again, it would be wise to make a backup of these files before proceeding with the upgrade.

User pipeline files (including those in the opus_test sample pipeline, if installed) and modifications to user .cshrc, omg.dat and pmg.dat files are not modified by the upgrade option 4 of opus_install. Instead, prior to using the upgraded version of OPUS, each user must run opus_install and select option 5 ("Upgrade an existing v1.4 user account to v2.2") to convert their pipelines to version 2.2.

The following items are upgraded in user pipelines by this option:

Top of Install FAQ

Top of OPUS FAQ