Linux/IRAF Site Manager's Guide

2.2. Configuring the Device and Environment Tables

Teaching IRAF about the devices, network nodes, external programs, and other special resources available at a site is largely a matter of editing a standard set of device descriptor and environment setup files, all of which are simple text files. The versions of these files provided with the distribution are simply those in use on the NOAO system from which the tapes were made, at the time the tapes were generated. Hence while these files may be useful as examples of properly configured descriptor files, the defaults, and many specific device entries, will in many cases be meaningless for a different site. This is harmless but it may be confusing to the user if, for example, the default printer doesn't exist at your site.

The device and environment files also contain much material which any site will need, however, so care must be taken when editing the files. Important changes may be made to the global portions of these files as part of any IRAF release. To facilitate future updates, it is wise where possible to isolate any local changes or additions so that they may be copied into the new (distributed) version of the file in a future update.

2.2.1. Environment definitions

Since IRAF is a machine and operating system independent, distributed system it has its own environment facility apart from that of the host system. Host system environment variables may be accessed as if they are part of the IRAF environment (which is sometimes useful but which can also be dangerous), but if the same variable is defined in the IRAF environment it is the IRAF variable which will be used. The IRAF environment definitions, as defined at CL startup time, are defined in a number of files in the unix/hlib directory. Chief among these is the zzsetenv.def file. Additional user modifiable definitions may be given in the template login.cl file (see §2.2.2).

The zzsetenv.def file contains a number of environment definitions. Many of these define IRAF logical directories and should be left alone. Only those definitions in the header area of the file should need to be edited to customize the file for a site. It is the default editor, default device, etc. definitions in this file which are most likely to require modification for a site.

If the name of a default device is modified, the named device must also have an entry in the termcap file (terminals and printers) or the graphcap file (graphics terminals and image displays) in iraf/dev. There must also be an editor.ed file in dev for the default editor; edt, emacs, and vi are examples of currently supported editors.

Sample values of those variables most likely to require modification for a site are shown below.

set editor      = "vi"
set printer     = "lp"
set stdplot     = "lp"
set stdimage    = "imt512"

For example, you may wish to change the default editor to ``emacs'', the default printer to ``lw5'', or the default image display to ``imt800''. Note that the values of terminal and stdgraph, which also appear in the zzsetenv.def file, have little meaning except for debugging processes run standalone, as the values of the environment variables are reset automatically by stty at login time. The issues of interfacing new graphics and image display devices are discussed further in §5.

2.2.2. The template LOGIN.CL

The template login.cl file hlib$login.cl, is the file used by mkiraf to produce the user login.cl file. The user login.cl file, after having possibly been edited by the user, is read by the CL every time a new CL is started, with the CL processing all environment and task definitions, package loads, etc., in the login file. Hence this file plays an important role in establishing the IRAF environment seen by the user.

Examples of things one might want to change in the template login.cl are the commented out environment definitions, the commented out CL parameter assignments, the foreign task definitions making up the default user package, and the list of packages to be loaded at startup time. For example, if there are host tasks or local packages which should be part of the default IRAF operating environment at your site, the template login.cl is the place to make the necessary changes.

2.2.3. The TAPECAP file

Beginning with V2.10 IRAF magtape devices are described by the tapecap file, dev$tapecap. This replaces the ``devices'' file used in earlier versions of IRAF. The tapecap file describes each local magtape device and controls all i/o to the device, as well as device allocation.

The tapecap file included in the distributed system includes some generic device entries such as ``mtdat0'' (HP DAT unit 0), ``mtexb0'' (Exabyte 8mm drive, unit 0), and so on which you may be able to use as-is to access your local magtape devices. Most likely you will want to add some device aliases, and you may need to prepare custom device entries for local devices. There must be an entry in the tapecap file for a magtape device in order to be able to access the device from within IRAF.

Instructions for adding devices to the tapecap file are given in the document IRAF Version 2.10 Revisions Summary, in the discussion of the new magtape system.

2.2.4. The DEVICES.HLP file

All physical devices that the user might need to access by name should be documented in the file dev$devices.hlp. Typing

cl> help devices

or just

cl> devices

in the CL will format and output the contents of this file. It is the IRAF name of the device, as given in files such as termcap, graphcap, and tapecap, which should appear in this help file.

2.2.5. The TERMCAP file

There must be entries in this file for all local terminal and printer devices you wish to access from IRAF (there is currently no ``printcap'' file in IRAF). The entry for a printer contains one special device-specific entry, called DD. This consists of three fields: the device name, e.g. ``node!device'', the template for the temporary spoolfile, and the UNIX command to be used to dispose of the file to the printer. On most UNIX systems it is not necessary to make use of the node name and IRAF networking to access a remote device since UNIX lpr already provides this capability, however it might still be useful if the desired device does not have a local lpr entry for some reason.

If you have a local terminal which has no entry in the IRAF termcap file, you probably already have an entry in the UNIX termcap file. Simply copy it into the IRAF file; both systems use the same termcap database format and terminal device capabilities. However, if the terminal in question is a graphics terminal with a device entry in the graphcap file, you should add a `:gd' capability to the termcap entry. If the graphcap entry has a different name from the termcap entry, make it `:gd=gname'.

2.2.6. The GRAPHCAP file

There must be entries in the graphcap file for all graphics terminals, batch plotters, and image displays accessed by IRAF programs. New graphics terminals will need a new entry. The IRAF file gio$doc/gio.hlp contains documentation describing how to prepare graphcap device entries. A printed copy of this document is available from the iraf/docs directory in the IRAF network archive. However, once IRAF is up you may find it easier to generate your own copy using help, as follows:

cl> help gio$doc/gio.hlp fi+ | lprint

which will print the document on the default IRAF printer device (use the ``device='' hidden parameter to specify a different device). Alternatively, to view the file on the terminal,

cl> phelp gio$doc/gio.hlp fi+

The help pages for the IRAF tasks showcap and stty should also be reviewed as these utilities are useful for generating new graphcap entries. The i/o logging feature of stty is useful for determining exactly what characters your graphcap device entry is generating. The gdevices task is useful for printing summary information about the available graphics devices.

Help preparing new graphcap device entries is available if needed. We ask that new graphcap entries be sent back to us so that we may include them in the master graphcap file for all to benefit.

2.2.7. Configuring IRAF networking

The dev directory contains several files (hosts, irafhosts, and uhosts) used by the IRAF network interface. IRAF networking is used to access remote image displays, printers, magtape devices, files, images, etc. via the network. Nodes do not necessarily have to have the same architecture, or even run the same operating system, so long as they can run IRAF.

To enable IRAF networking for a Linux/IRAF system, all that is necessary is to edit the ``hosts'' file. Make an entry for each logical node, in the format

nodename [ aliases ] ":" irafks.e-pathname

following the examples given in the hosts file supplied with the distribution (which is the NOAO/Tucson hosts file). Note that there may be multiple logical entries for a single physical node.

The ``uhosts'' file is not used by UNIX/IRAF systems hence does not need to be modified (it used by VMS/IRAF). The ``irafhosts'' file is the template file used to create user .irafhosts files. It does not have to be modified, although you can do so if you wish to change the default parameter values given in the file.

To enable IRAF networking on a particular IRAF host, the Linux hostname must appear as a primary name or alias somewhere in the IRAF hosts table. During process startup, the IRAF VOS looks for the system name for the current host and automatically disables networking if this name is not found. Hence IRAF networking is automatically disabled when the distributed system is first installed - unless you are unlucky enough to have installed the system on a host with the same name as one of the nodes in the NOAO host table. Note that it may be best to simply delete the NOAO host table entries since any duplicate with a local host entry will will cause the IRAF ``cd'' command to fail and may have other consequences.

Once IRAF networking is configured, the following command may be typed in the CL to verify that all is well:

cl> netstatus

This will print the host table and state the name of the local host. Read the output carefully to see if any problems are reported.

For IRAF networking to be of any use, it is necessary that IRAF be installed on at least two systems. In that case either system can serve as the server for an IRAF client (IRAF program) running on the other node. It is not necessary to have a separate copy of IRAF on each node, i.e., a single copy of IRAF may be NFS mounted on all nodes (you will need to run the IRAF install script on each client node). If it is not possible to install IRAF on a node for some reason (either directly or using NFS) it is possible to manage by installing only enough of IRAF to run the IRAF kernel server. Contact IRAF site support if you need to configure things in this manner.

Linux/IRAF currently supports only TCP/IP based networking. Networking between any heterogeneous collection of systems is possible provided they support TCP/IP based networking (virtually all UNIX-based systems do). The situation with networking between UNIX and VMS systems is more complex. V2.9 and earlier versions of VMS/IRAF support client-side only TCP/IP using the third party Wollongong software. For V2.10 we plan to drop support for the Wollongong software and switch to the more fully-featured Multinet instead (another third party product). Contact the IRAF project for further information on networking between UNIX and VMS systems.

Once IRAF networking is enabled, objects resident on the server node may be accessed from within IRAF merely by specifying the node name in the object name, with a ``node!'' prefix. For example, if foo is a network node,

cl> page foo!hlib$motd
cl> allocate foo!mta
cl> devstatus foo!mta

In a network of ``trusted hosts'' the network connection will be made automatically, without a password prompt. A password prompt will be generated if the user does not have permission to access the remote node with UNIX commands such as rsh. Each user has a .irafhosts file in their UNIX login directory which can be used to exercise more control over how the system connect to remote hosts. See the discussion of IRAF networking in the IRAF Version 2.10 Revisions Summary, or in the V2.10 system notes file, for a more in-depth discussion of how IRAF networking works.

To keep track of where files are in a distributed file system, IRAF uses network pathnames. A network pathname is a name such as ``foo!/tmp3/images/m51.pix'', i.e., a host or IRAF filename with the node name prepended. The network pathname allows an IRAF process running on any node to access an object regardless of where it is located on the network.

Inefficiencies can result when image pixel files are stored on disks which are cross-mounted using NFS. The typical problem arises when imdir (the pixel file storage directory) is set to a path such as ``/data/iraf/user/'', where /data is a NFS mounted directory. Since NFS is transparent to applications like IRAF, IRAF thinks that /data is a local disk and the network pathame for a pixel file will be something like ``foo!/data/iraf'' where ``foo'' is the hostname of the machine on which the file is written. If the image is then accessed from a different network node the image data will be accessed via an IRAF networking connection to node ``foo'', followed by an NFS connection to the node on which the disk is physically mounted, causing the data to traverse the network twice, slowing access and unnecessarily loading the network.

A simple way to avoid this sort of problem is to include the server name in the imdir, e.g.,

cl> set imdir = "server!/data/iraf/user/"

This also has the advantage of avoiding NFS for pixel file access - NFS is fine for small files but can load the server excessively when used to access bulk image data.

Alternatively, one can set imdir to a value such as ``HDR$pixels/'', or disable IRAF networking for disk file access. In both cases NFS will be used for image file access.

2.2.8. Configuring the IRAF account

The IRAF account, i.e., what one gets when one logs into Linux as ``iraf'', is the account used by the IRAF site manager to work on the IRAF system. Anyone who uses this account is in effect a site manager, since they have permission to modify, delete, or rebuild any part of IRAF. For these and other reasons (e.g., concurrency problems) it is recommended that all routine use of IRAF be performed from other accounts (user accounts).

If the system has been installed according to the instructions given in the installation guide the login directory for the IRAF account will be iraf/local. This directory contains both a .login file defining the environment for the IRAF account, and a number of other ``dot'' files used to setup a sample XFree86 screen of the type that an IRAF user will want, i.e., with the IRAF graphics and image display windows.

Most site managers will probably want to customize these files according to their personal preferences. In doing this please use caution to avoid losing environment definitions, etc., which are essential to the correct operation of IRAF, including IRAF software development.

The default login.cl file supplied in the IRAF login directory uses machine independent pathnames and should work as-is (no need to do a mkiraf - in fact mkiraf has safeguards against inadvertent use within the IRAF directories and may not work in iraf/local). It may be necessary to edit the .login file to modify the way the environment variable IRAFARCH is defined. This variable, required for software development but optional for merely using IRAF, must be set to the name of the desired machine architecture, e.g., ssun for Sun Solaris, linux for PC Linux, etc. If it is set to the name of an architecture for which there are no binaries, e.g., generic, the CL may not run, so be careful. The alias setarch, defined in the iraf account .login, is convenient for setting the desired architecture for IRAF execution and software development.

2.2.9. Configuring user accounts for IRAF

User accounts should be loosely modeled after the IRAF account. All that is required for a user to run IRAF is that they run mkiraf in their desired IRAF login directory before starting up the CL. Defining IRAFARCH in the user environment is not required unless the user will be doing any IRAF based software development (including IMFORT).