next_group up previous contents
Up: CFHT Director/Agent Model Revision Previous: 4. The Director   Contents


5. Appendix

5.1 Terminology

Constantly running process that talks to some hardware or provides some other ``service'' for client programs (which come and go in the Pegasus model). There are usually always servers running for telescope control, CCD control, filter wheels, etc.
Our name for the clients. A custom handler exists for each Pegasus server. All communication with the server, and also filling in of fits cards is done using the handlers.
The (custom) communications scheme used by Pegasus handlers to send commands and get responses back from servers.
Really the same thing as a server. Just made up ``agent'' to have a way to distinguish from Pegasus servers. The difference is, there is no device specific ``handler'' per se.
``Parent'' of the agent program. Takes care of accepting command requests on behalf of the agent from various sources and forwards them on. Displays colorized response messages in ``Pegasus feedback window.''
Plays role of handler for the Agent, but is general to all agents (it only knows how to send a command and get back PASS/FAIL.)
Pipes, Named Pipes, and Sockets
A Pipe feeds the output of one program into the input of another. A Named Pipe is an empty file in the filesystem that is opened for reading by one process and written to by other process(es) to establish a pipe between programs that are started up independently. Sockets are required to establish pipe connections between different machines on the network.
Remote shell protocol allows a process on one machine to start up something on another and gives it input and output pipes to communicate with the remote process.
A terminal emulator window (like XTerm) that supports VT100 escape sequences and ANSI color escape sequences.

5.2 Environment and Director

DIRECTOR (this is version `2')
  DO NOT SET this externally!  Director sets it to an appropriate value
  so agents know what version of director they are running under.

  If unset, director will set this to the current hostname.  If it is set
  but it doesn't agree with the current hostname, director will issue a warning
  and keep the value you have set. The symbolic link file ~/.director/sessionhost
  overrides this.

  If unset, director sets this to SESSIONHOST:0.0.

  After a userid for a director session has been determined (either that
  passed with `-k' or getuid() if no `-k') director overrides these two
  variables to agree with information from the passwd table. The original
  settings of these variables have no effect on director or its agents.

  User's current path is sent to agent as-is.

  Ignored (set to 0 to force ncurses to determine window size on its own.)

  Defaults to /cfht/conf.

  Log messages from agents running within director are also written here
  using cfhtlog() calls.  The message type is determined from the first
  few characters in a line printed by the agent.  For example, a string
  starting with `error:' is written as CFHT_ERROR, etc.  See also `-hs'.
  Defaults to /tmp/pipes/

  If this file (fifo) does not exist, or if no other process is currently
  reading from it, it is opened.  Messages written to this node by other
  programs are echoed in the director feedback area.

  Passed on to the agent.  If not found, defaults to ~/.,template

When the agent runs on another host, these are the ONLY variables it
should expect to have defined.

5.3 String Parsing Rules

String parsing rules: ('^'->beginning of a line)

^status:     displays green,  logs as CFHT_STATUS
^logonly:    displays brown,  logs as CFHT_LOGONLY
^debug:      displays brown,  logs as CFHT_DEBUG
^warning:    displays yellow, logs as CFHT_WARN
^error:      displays red,    logs as CFHT_ERROR
Any line on stderr is at least a CFHT_WARN, so C agents can use perror().
All other lines are not logged, but display in various areas of the screen:
^statusbar:  creates status bar (if needed); displays text in reverse video
^titlebar:   displays text in window title (if TERM=xterm or rxvt only)
^infoN:      (where N is 1..9) displays on info panel if infosize >= N
^instant:    displays text in user prompt area until command completes
^*           displays with highlighted background (including the *)
^ok>         command completed ok *handled internally by cli_getline()
^failed>     last command failed  *handled internally by cli_getline()
\a(bell)     rings the terminal bell immediately (and eats the character)
...          all other lines scroll in white in the feedback area
             long lines are word-wrapped to fit the current window size

 ~ or ~user  basic shell-style tilde-substitution is done by director
builtin      (where `builtin' is a director builtin command) runs immediately
other        (where `other' is any other command) put in queue for agent
@cmd         runs cmd as above but does not echo the command itself to window
-cmd         runs cmd as above but does not abort a script if this command fails
{PID}cmd     runs cmd as above; when it returns director signals PID with:
               SIGUSR1 if command returned PASS (prompt was ^ok>)
               SIGUSR2 if command returned FAIL (prompt was ^failed>)
               *handled internally by cli_cmd() or the shell utility `clicmd'

5.4 Licensing

Director is free software. It is distributed under the terms of the GNU General Public License version 2. If you modify it, please make sure this is clearly advertised when the program starts up.

5.5 Requirements, Downloading, Building, and Installing Director

5.5.1 Requirements under Linux

Most Linux systems already contain the necessary prerequisites for building and installing Director.

5.5.2 Requirements under other unix platforms

Director has been tested on HP-UX 9 and 10, SunOS 4.1, Solaris 2.x and Solaris 7, but only after installing a bunch of GNU software to make these systems look more like a Linux system. Most importantly, GNU make, the GNU C compiler, and the ncurses library (defaults on Linux, but not many other unix platforms) are required to build Director. If any of these are installed in a place other than /usr/local, be sure to edit Make.Common so Director's Makefile system can find them.

You'll want to install these items in the order given below. All GNU packages are available from The versions indicated are the versions that we are using. Most likely later versions (and possibly some older versions) will work as well.

GNU make
Install GNU make first. Some of the Makefiles may give errors versions of GNU make older than about 3.74, so upgrade to 3.79.1 or later if you receive errors related to a ';' in the wrong place. Make sure GNU make is in your path before other make's like /bin/make.
GNU fileutils
This is only needed for the BSD compatible install program. If you already have a BSD compatible install program, edit Make.Common (in the CFHT stuff) to make sure it can find it.
GNU C Compiler
All of the software below has been tested to work correctly when compiled with gcc-2.7.2. Director and DetCom also compile correctly with gcc-3.0, and some versions of GCC in between.
Some of these patches may be needed to get ncurses to work correctly with rxvt. In our setup, I simply replaced the entry for rxvt with vt100 plus emca+color. I commented out the old rxvt entry in ncurses-4.1/misc/terminfo.src and replaced it with:

rxvt|xterm-color|reduced xterm terminal (X Window System),
        use=vt100, use=ecma+color,
After that you have to do a ``make install'' in the misc subdirectory to install the new terminfo. One way to be sure things will work correctly would be to use our version of rxvt and our version of ncurses, as they are known to work together. The tar files can be downloaded from the page. Then you won't have to worry about patching anything at all.
rxvt-2.19 or a modern xterm
Once you have installed Director, you may want to experiment a bit to get the best color support, because it makes the screen a lot more read-able. Here are some things to try:

If one of these terminal types turns on color support for you, you could also make that the default by putting it in the COLORTERM environment variable.

5.5.3 Requirements under Windows NT

I have also managed to compile rxvt, ncurses, and Director under Windows NT using the cygwin32 GCC from Cynus Solutions (now RedHat). With some tweaking, Director should run properly under Windows NT (and possibly Windows 95). Without named pipes, however, its functionality will be somewhat limited on that platform.

5.5.4 Downloading

director-and-detcom-3.31.tgz [0.60MB]
contains full source to both Director and DetCom (if you don't need DetCom, comment ``detcom'' and ``fh'' out of the top level Makefile.) Source for supporting libraries and Makefiles for GNU make and GCC are also included.

rxvt-2.19-cfht.tgz [0.35 MB]
is a patched version of the rxvt color text terminal. (Our patches include gracefully dealing with a full colormap.) Current releases or X11R6 have an xterm which supports ANSI color, so you may not need this program.

A mirror of the man pages for rxvt are available on this site, and are also included with the tar file, along with a ``vga.pcf'' font. Again, all of this may already exist on other Linux installations, and under modern Solaris, HPUX, and others, xterm will probably work fine. If it comes up without color, try ``director -t xterm-color ...''.

ncurses-4.1-cfht.tgz [1.35 MB]
If there is already a pre-existing ``ncurses'' library installed on your system, use that one instead. Linux distributions should have this already. If there is no ncurses installed, you might try the latest version (ncurses-5.2) rather than this patched one.

Links to some documentation on ncurses and its libraries are included in the tar file, and at on this site.

5.5.5 Building and Installing

  1. Choose the directory tree where you want to install everything. This directory will be referred to as PREFIX from now on. Some examples are:


    WARNING: At the moment, /usr/local/cfht/ and /local/cfht/ in particular do NOT work as PREFIX, unless you create a symbolic link in root (/cfht) pointing to this directory.

  2. Create directory PREFIX ( /opt/cfht in this example) and untar director-and-detcom-X.YY.tgz there. This will create PREFIX/src with directories for projects cli, fh, and detcom. Example:

      cd /opt/cfht ; gzip -dc ~/director-and-detcom-3.31.tgz | tar xvf -

    When you are finished, you should something similar to this:

      /opt/cfht/src/Make.Common      (Shared Makefile stuff)
      /opt/cfht/src/ThisIsTopLevel   (Marker used by Make.Common)
      /opt/cfht/src/cli ->           (Symlink to the current version)
      /opt/cfht/src/cli-3.31/...     (Complete source tree and libraries)
      /opt/cfht/src/fh ->            (FITS Header library used by DetCom)
      /opt/cfht/src/detcom ->        (Symlink to the current version)
      /opt/cfht/src/detcom-3.31/...  (DetCom source code.)

    Note: after building and installing, files will appear in:

      /opt/cfht/obs/PROJECT/...      (Unstripped programs and object files)
      /opt/cfht/lib/libNAME.a        (Archive libraries)
      /opt/cfht/include/NAME/*.h     (Include files for libNAME.a)
      /opt/cfht/bin/...              (Stripped program executables)

    Assuming PREFIX=/opt/cfht, so choose PREFIX accordingly. PREFIX=/usr/local will cause things to go into /usr/local/bin/, so you typically won't have to adjust your path or make symlinks. It's a matter of taste really.

  3. If necessary, edit Make.Common and make sure that the PATH in this file includes the proper version of GNU make before any other make's you might have on your system. (One alternative would be to install GNU make as ``gmake'' and run ``gmake'' instead of just ``make''.)

  4. To verify the installation locations before doing anything, change to the src/ directory and type ``make''. The ``make'' command will then give further instructions on how to proceed. DetCom may not build on some platforms. To avoid building DetCom, change to the src/cli directory and run ``make world'' there (which builds and installs everything from there down, skipping src/fh and src/detcom.

  5. During the make process, you will be prompted for the root password once. This is used to make the ``setuidinst'' program setuid root. It, in turn, is run when you install ``runon'' (or any other program that it has been authorized to operate on) to make ``runon'' setuid root so you don't have to remember to do it manually. If you consider this a security risk, you'll have to manually make ``runon'' setuid root to be able to run Agents on remote hosts.

If the programs compile successfully, but there were warnings, read them carefully to be sure that they are not going to cause problems later on. Warnings about SIG_IGN or SIG_DFL not being proper prototypes and warnings about format arguments to printf's can be ignored. If the warnings are due to other missing prototypes on your system, you should check the man page for a prototype and add it to ``missing_protos.h''. This file does not appear in the dependencies for any targets, so you'll have to do a ``make clean world'' to rebuild everything after editing this file. (The alternative is to add ``-Werror'' to the gcc options to prevent anything from building unless it is completely warning-free.)

Just a tip when looking around in the directories: If you find a file called `` Index'' it will typically tell you what the files and subdirectories in the current directory are for.

next_group up previous contents
Up: CFHT Director/Agent Model Revision Previous: 4. The Director   Contents
Sidik Isani