12. The Observing ``Sessions''

12.1 History

At CFHT, we refer to the user account for an instrument and all of the software installed within it as the ``session''. Sessions which conform to the original (1980s!) design, which includes automatic clean-up, re-build, and release mechanisms are known as ``Pegasus sessions.'' Practically every session has enough manual edits and tweaks that the only way to restore the setup is from a simple archival backup. All current (2016) sessions build on Pegasus software but have completely abandoned the auto-build design. These are known as ``NEO'' (New Environment for Observing) sessions.

12.2 Template Session

Just as the username `` pegasus'' was a non-instrument-specific demo/testing session, the username `` neo'' (with home directory /h/neo) serves as a template for what we might want future sessions to look like. At the moment, it is unlikely that existing instrument sessions would work, though, if one just forced all the generic components of /h/neo into a specific session. Unfortunately the instrument-specific needs are not as well separated as they should be. The ``NEO'' account has been abandoned for so long, it would be unwise to look at as a good example of how things are set up.

The following subsections describe the generic NEO account, and also how to convert a Pegasus account to use as much of the NEO things (XFCE, Director, Detcom) as possible.

12.3 Components of a NEO session

This is a description of all of the files and programs that make up a CFHT observing ``session'' such as megacam, cfhtir, and instruments using DetCom as the source for FITS files. It is written from the point of view of setting up a new account from scratch.

12.3.1 Home directory and login (NIS)

The first step to create a data acquisition account (or any other user account, in fact) is to add an entry to the master NIS password database, currently on the machine ``niu'' in Waimea. This step is usually performed by the system administrator. Skip to step 2 if an account has already been created.

A typical observing account entry in /var/yp/src/passwd would look like this:

neo:xxxxxxxxxxxxx:1234:1000:New Environment for Observing:/h/neo:/usr/bin/bash

Notes:

• For the second field, copy the encrypted password string from another active observing account.

• For the third field, be sure to pick a new, UNUSED number and place the entry in order, SORTED by user ids.

• For the last field, use /usr/bin/bash. ``Bash'' is the only shell which has a consistently configured version across all platforms at CFHT.

The home directory should be located on a reliable RAID disk at the summit, and the entry in the autofs maps is maintained in the file /var/yp/src/autofs/LINUXautomount/auto.h also on nui.

neo         alakai:/local/h/neo

would be the entry matching the passwd example above.

Finally, add the new user account to netgroups ``doubt'' and ``observer'' and push the changes out to all machines using the normal procedures.

12.3.2 Dot Files

Once an empty home directory exists, some dot-files must be set up to configure the account as an observing session. In addition to the files shown here, other dot-files may appear as a result of logging in and using various programs, but those listed here are believed to be the only ones necessary for a functioning session.

.fvwm-errors-HOSTNAME

This file will be created. All output from the rest of the setup scripts ends up here. HOSTNAME is usually the session host, except for very early messages from the login process, when it might be the name of the display host instead. Hint: ``ls -latr'' will list the most recently touched file(s) at the end of its output.

.fvwm-options

This is a shell script (or any other type of executable) which can echo bash-syntax commands on its stdout. This provides a mechanism to set option variables or override defaults in the FVWM startup sequence. The following is an example of a complete .fvwm-options for a session that should run on noeau (regardless of where the user logs in)

#!/bin/sh

#
# Set sessionhost here.
#
echo export SSO_HOST=megacam-session
echo export SSO_WMNAME=xfce
#echo export SSO_WMNAME=fvwm2

Another (currently unused) use for the .fvwm-options script is to display a pre-login user interface. This could be used to get something like a user preference for default shell in terminal windows. Add this to the end of a session's .fvwm-options file use the Tcl/Tk script "sso" to gather preferences from the user:

if [ "$HOSTNAME" = "$SSO_HOST" ]; then
  #
  # If we are already on the real sessionhost, display
  # the GUI that lets the user choose a few extra options
  # related to the session before the window manager starts:
  #
  exec /usr/wm/common/sso
fi

IMPORTANT: Be sure to run "chmod +x" on the script to make it executable.

.fvwm-initfunction

Like .fvwm-options, this should also be an executable (usually another shell script) and it is used to launch the session manager tool bar (PSM), director feedback window, and any initial sessionstart processes. The same script can be used by all sessions, since ``sessionstart'' itself figures out what needs to be started for this specific session, and ``.director/startup.USERNAME'' determines which agent programs need to be started. See also the descriptions of those two files, below.

This script runs once on each screen.

#!/bin/sh
#
# .fvwm-initfunction - Start session user interfaces.
#
# Director is started on StatusDisplay in a color rxvt terminal window.
#
if [ "$DISPLAY" = "$StatusDisplay" ]; then
  rxvt -pixmap none +sb -geometry 80x37-62-1 -e director &
fi
#
# All screens should wait for Director on StatusDisplay to be ready,
# so that logging facilities are completely ready.
#
echo "Waiting for director to be ready for log input"
if ( clicmd @running 60 ); then
  echo "Director is ready"
else
  echo "Director still not ready after 60 seconds!"
  # Abort the session somehow?
fi
#
# The main GUI (PSM and/or an exposure form) are started on MainDisplay.
#
if [ "$DISPLAY" = "$MainDisplay" ]; then
  sessionstart &
  psm -X
fi

.fvwm-exitfunction

This is executed whenever anyone logs out of an FVWM session. It must run sessionquit (and sessionquit, like sessionstart, must decide what this specific session needs based on .,config). It also must decide whether or not to ``shutdown'' director. If the instrument is still on, director is left running so that it can be cloned, even if no X-Sessions are logged in. This also allows the alert notification mechanism (which delivers e-mail if a critical condition occurs with the instrument) to continue to operate even when the session is not ``logged in.'' Only megacam uses this at the moment. All other sessions want to shutdown on logout.

More general information on how .fvwm* files are handled in the CFHT environment are given in /usr/wm/common/fvwmstart.ps.

The only thing the window manager startup scripts do, for getting the command line part of the session going, is to start `` director'' without any options. If one wants to have just the command line part of a session, it is usually possible to `` su - username'' and then just run `` director'' as the session.

It is also possible to run the entire graphical session inside a window (vncviewer) using the script `` session-test'', run from your personal account.

.director/startup.USERNAME

However director is invoked, as long as the -p and -S options were not used, director will run any and all commands it finds in .director/startup.USERNAME when it starts as a master. (If you start more director processes by logging in, if the session allows it, or by su'ing and typing director, you will get a clone window, and the startup script is NOT re-run.)

For now, the contents of the .director/startup.USERNAME file specify

• A detector host.
• The version of detcom to be used for this session.
• The location of DSP code lod files to be used by detcom.

Typical syntax looks like this:

@-infosize 9
agent start -R -D -H deticli dethost1:/cfht/bin/detcom-3.47 ~/dsp/ltb.lod ~/dsp/lub.lod

The '@' and '-' characters do the same thing they do in a Makefile. (Don't echo the command itself, and don't stop executing if the command happens to fail.)

The "infosize 9" maximizes the number of debug/user info lines shown below the prompt area. 9 is probably only needed for engineering, so reduce it if you'd rather not confuse the user with DSP code version status, etc. Generally, since we're doing service observing, some of the low level info is good or at least harmless.

The -R and -D options tell director to (R)estart detcom automatically if it exits (or crashes) and that it is the (D)efault agent to receive any user commands that are not prefixed by a handle.

.,deti.par - Needs to be a link to .,detcom.par until all refs to deti.par (possibly just ccd?) are fixed.

.director/sessionhost

This is a ``bogus'' symbolic link. The contents are the hostname where a clone should go to find director's shared memory. In the way we use it at CFHT, the sessionhost link is removed by the main director process when it exits, so that SSO_HOST in .fvwm-options is the single place to change the session host. If .director/sessionhost exists without the presence of .director/sessionhost.tmp, it indicates that the link is not going to be cleaned up automatically by director when it exits. This is not the intended use at CFHT, so if you find `` sessionhost'' hanging around by itself, remove it manually, or director will be confused if you ever change the account's sessionhost.

12.3.3 GUI Form(s)

There are none. Data Aqcuisition is pretty much fully command-driven in Queue Mode now.