The information here is for those setting up environments that use Director. The actual commands available inside Director are mostly those provided by the Agents, and so are application specific. For those, the command ``help'', typed at the Director prompt, usually gives a list of available commands from Agents and scripts.
For information on invoking Director, typing ``director -h'' from the unix shell lists most of the information in the sections below.
In an observing session where Director has been automatically started from login scripts, as part of the window session, it will appear in an rxvt terminal window in the lower right corner of the screen.
To bring up a similar window of an observing session in another session, I've created a script called /usr/local/bin/clone which will invoke the most appropriate version of director for you (possibly in a color terminal, if you have DISPLAY set correctly). So, for example, if you want to view the feedback from the ``aobir'' session, or send a message to the users of that session, type:
clone aobir
Here is the help screen, which you can get on-line on a CFHT machine by just typing clone by itself.
usage: clone <session>
Where <session> is the name of a Pegasus session, e.g., aobir
From another Xsession or X-Terminal:
- Make sure your DISPLAY variable is set first.
- A new X window will pop up on DISPLAY with a director clone
From home, or from a telnet session not on an X-display:
- If DISPLAY is _not_ set, clone will start in the current window.
- Be sure that TERM is set correctly. When logged in using
MS Windows telnet, for example, a setting of TERM=vt100 should
work as long as the window is big enough to not have scroll bars.
Unless you deliberately enter the Pegasus account password in your
director clone window, it will not be possible for you to send
any commands to the session except for the 'say' command, which
just broadcasts a message to all other director windows.
To use Director to run or test your own Agent programs,
make sure your PATH is set up so you get the right version. You
should typically have HOME/bin and /usr/local/bin
before /cfht/bin in your PATH variable if you are CFHT.
Locally, I make sure that /usr/local/bin/director exists,
which will always be a link to the most recent stable version
If you need to select a specific version that you know works with your setup,
then you should do as the Pegasus accounts do and create a symbolic link in
HOME/bin pointing to the appropriate version. For example, the
current stable version is 3.31, so you'd run the command:
ln -fs /cfht/bin/director3-3.31 HOME/bin/director
just once to set up selection of this version. After that, you
can start up Director in one of the following ways:
usage: director [director options] [ -- [rhost:]agent [agent options] ]
or director [director options] -- [{9600,N81,see_manual...}]serialdevice
or director (no startup and no args, just tails log pipe)
or director -k <user> (attach to another user's session without su'ing)
realprogram options are passed without change to the actual cli program
director options are:
-i <n> displays <n> info lines at bottom of screen (default is 0)
-j enables jumpscroll mode for slow terminals
-v turns on verbose mode which shows logonly and debug
-d turns on debug messages (also requires -v to see on screen)
-m used by sessions to ensure they get a master, not a clone
-c sends a CR character after each command instead of a newline
-C turn off the titlebar clock for slow connections
-t <type> override terminal auto-sensing and TERM var (e.g., -t vt100)
-p <str> sets the prompt string to expect after each command completes
-h displays this help information
-hf displays summary of director-related files and resources
-hs displays string parsing rules used on output from realprogram
-he displays summary of how the environment affects director
(hint: -he can be combined with -k<user> for testing) (*) See appendix
All options above can also be controlled by director builtin commands.
Type `builtin' at the director command prompt for more help on these.
When opening a serial port, it is possible to specify optional parameters enclosed in braces , immediately before the name of the serial devices. There must be no spaces anywhere in this string. Multiple options can be separated by commas. Currently, the following option names are recognized. They are case sensitive:
| 300 1200 2400 9600 19200 38400 | Choose one of these to select a baud rate when the port is opened. Some systems may support other baud rates in addition to the ones listed here. |
| N81 N72 O71 E71 | Choose one of these to set parity, data bits, and stop bits. Default is N81. |
| LOCAL/-LOCAL | Use this if you have/don't have modem control lines (DCD, etc.) connected. If you don't give either, the default setting of the port is kept. |
| SOFTFLOW/HARDFLOW | Select between software/hardware flow control. Default is both OFF. When SOFTFLOW is selected (same as XON,XOFF) the stop/start characters are set to control-S/control-Q. It is currently not possible to select any other stop/start characters in director. When HARDFLOW is selected, it is assumed that CTS and RTS lines are hardwired. Note: If you need to distinguish between output flow control and input flow control, use combinations of settings below instead. |
| XON/CTS_OFLOW (or use XANY instead of XON) | Select between software/hardware output flow control. Default is both OFF (So there is no need to give -XON or -CTS_OFLOW). On systems that have it, XANY also allows any character received to restart output (instead of just control-Q). Turning on XANY implies XON. Note: CTSXON and RTSCTS are synonyms for CTS_OFLOW. |
| XOFF/RTS_IFLOW | Select between software/hardware input flow control. Default is both OFF. Note: RTSXOFF is a synonym for RTS_IFLOW. |
For example, to connect to a typical 9600 baud RS232 device that has hardware flow control but is not a modem, the invocation might look something like this:
director -- '{9600,N81,-LOCAL,HARDFLOW}/dev/tty02'
For serial devices that are really terminal server ``rtelnet'' processes you may not need any extra options at all since the settings in the terminal server itself are the ones that matter. You may, however, need a -p option to specify what the prompt looks like, and the -c option if the program expects a CR instead of a LF as the newline character. For example, to connect to a Prolog system:
director -c -p '->' -- /dev/termsrv4/tty16
For devices which have no prompt at all, specifying an empty string for the prompt, as in:
director -p '' -- /dev/termsrv4/tty16
will cause director to assume that the device is ready for new commands after all output has been flushed and a certain timeout has elapsed. The -T option (also an option to the builtin, ``agent start'' in Director 3.x) can be used to tune the timeouts in this case.
Depending on the type of terminal you use to run Director, you should get most of the features illustrated in figure 4.
~/.,session.np (see also: director -he) Opened for reading session feedback messages from other sources. ~/.director/bin/ When Director receives a command, this subdirectory is searched first. A non-executable file with a matching name is sourced like a batch file. An executable (or link to executable, or link to clicmd) is executed with the same arguments given on the command line. ~/.director/sessionhost If this file exists as a symlink, Director will first attempt to `remsh' to the machine name given by the contents of the link. ~/.director/startup This file is automatically sourced at startup (non-clones only). Providing an agent on the command line (after --) suppresses this. ~/.director/history Command history is saved here between sessions. The `~' is always replaced by the home directory of the original user starting Director. ~/.director/command.np Non-clones create (and remove at exit) this FIFO and read from it. Clones (and other external programs) must only write commands to it. If `-k' is present, clones use the `~' for that account. `~' expansion at the command prompt also follows the `-k' user after in that case.
When you type `help' in the Director window, you'll see something like this. The exact commands available will depend on the agent and its current mode of operation.
*---[ Command Set ]-------------------------------------------------------* cd : Change working directories list : List files in DIR rename : Rename a file count : Counts args in argv comment : Sets the comment header sync : Re-read par file exit : Exit the program help : Displays help for directest builtin : Displays help for director builtin options !... : Passes ... to a unix shell (e.g. `!ls -l *.fits') *-------------------------------------------------------------------------*
Here are some help screens about features that are handled by Director or the rxvt terminal window. These commands are reserved words and the agents themselves must never implement them.
*---[ Builtin Director Commands ]-----------------------------------------* termhelp : display help screen for operating this terminal window debug on|off : toggles debug output (also requires verbose for displaying) verbose on|off: toggles displaying of verbose messages clock on|off : controls display of titlebar clock infosize N : displays N lines of the info panel (N=0..9) cancel (or ^G): cancels queued but not yet executing commands abort (or ^C): sends SIGINT to the agent stop (or ^Z): sends SIGTSTP to the agent quit (or ^|): sends SIGQUIT to the agent sigsend [NAME]: sends SIG[NAME] to the agent ready : silently returns pass or fail (for clicmd) say <message> : use to send messages to other users with director clones agent ... : starts, restarts, or stops an agent running in director autorestart on|off: tells director whether or not to restart agents that die source <file> : reads batch commands from <file> *-------------------------------------------------------------------------*
Want more lines or bigger fonts in the text window? Here's how...
*---[ Terminal Window Tips ]----------------------------------------------* o Resizing window will cause feedback area to fill available space o Shift-numpad-plus and Shift-numpad-minus change font size (rxvt only) o Shift-page-up and Shift-page-down scroll back the window (rxvt only) o Up-arrow and Down-arrow allow editing/repeating previous commands o Other cursor keys (home, end, left, right) do their thing o Most commonly used emacs bindings work also (but not ^Y!) o Command/file completion (usually bound to esc/tab) NOT implemented o Pressing Control-L will clear and redraw the entire window *-------------------------------------------------------------------------*
With Director 2.x, the agent command was mostly used in just one way, with restart as the argument. At the Director window prompt:
> agent restart Restarting primary agent ... Agent ready. > _
This was mostly intended for debugging, recovering from crashes, or switching to a new version of an Agent without restarting Director. With Director 3.x, agent restart still works, but there are many other options. First, agent restart now takes an (optional) extra parameter telling it which Agent should be restarted. If none is given, the default Agent is restart. The default Agent is the determined by the following rules:
This is mainly to provide backward compatibility with Director 2.x, where the ``agent restart'' command was never ambiguous since there was only one agent. With Director 3.x, it is best to give the handle of the agent to be restarted.
The command ``agent start [options] ...'' is the recommended way to add an Agent to a Director session. The command can be placed in .director/startup so that director, typed by itself from a unix prompt, will begin a Director session without any other required parameters or aliases. The syntax is as follows:
> agent start [options] [hostname:]agentname
If the optional hostname: is omitted, the agent is started on the same host as Director. After this command completes, commands can be issued to this agent by using its ``handle'' (which, by default, is the agentname, with any version numbers removed.)
> agentname.somecommand someagrs ...
The same string could be passed to clicmd, described below.
The handle can be omitted if this Agent is the only one running, or if -D is given in the [options] to agent start. The handle name can also be omitted if a script by the name of somecommand is placed in HOME/.director/bin/ (create the directory if it does not exist). Write the script so it simply calls
exec agentname.somecommand "$@"
In the future, we may create a mechanism for agents to register their command set with Director so it is this necessary, but for now, this gives the same appearance to the user.
agent start supports several other options:
> agent stop handlename
Use this to cause an agent to exit and be removed from the list in Director. If this agent needs be started again, a complete ``agent start ...'' command must be issued. Use ``agent restart'' instead for starting a new version of the Agent.
This command will print a table of all Agents in this session, along with the unix process IDs, handles, and current status.
This is another useful debugging command. It displays the internal queue of commands waiting to be processed. When scripts call other commands, this nesting is shown as a tree structure by clidump.
As of version 3.x, Director itself no longer needs setuid-root privileges. This was required to allow Director to open rcmd() connections when an agent needs to run on a different host from the one running director. This is now handled with a separate utility, runon. There are also a set of three utilities which are useful for scripting, called clicmd and related programs clicap and clidup.
Runon is based on rsh source code. It would be possible to have director use rsh ( remsh on some systems) but not all features with signal handling and exit status may work correctly. Instead, it is recommended that you install runon if Agents will need to run on various hosts. This utility needs setuid-root privileges.
A man page for runon is available on the Web. Director automatically invokes runon with the correct options when an agent is preceded with ``hostname:''.
Agents are a type of server. The clicmd utility can be thought of as a very simple, non-specific client, because it allows any script to invoke commands as if they were separate executables. The PASS/FAIL return of the invoked command becomes the exit status of clicmd. It is typically used like this:
clicmd command [arguments ...]
This is equivalent to typing ``command [arguments ...]'' in the Director window at the prompt. To make it even easier to access agent commands from a shell, clicmd can also be used transparently, by creating symlinks for each command which should appear as a unix shell command. By this simple mechanism, commands to a persistent server (the agent) can appear as unix shell commands (without having to add the clicmd prefix). To configure this, follow these steps:
If runon is also available on all hosts involved, the clicmd utility will even work when it is run from another host. It is most efficient, however, to run all sequencing and script on the same host as Director. Running Agents on different hosts does impose an efficiency penalty however.
This utility is the same as clicmd (see above), except that it captures the output of the command and sends it to the terminal where clicap was invoked, rather than sending feedback to the Director window. This can be confusing (users watching the Director window or clone windows will have no idea that a command was executed). Without a status server, clicap has been used as a temporary way of retrieving status from an agent. To do this, first create a command in the agent which prints a status value (and does nothing else.) The command with no arguments can be made to do this, or a separate command can be created. The following example demonstrates how this can be used to capture a value into a shell script environment variable.
#!/bin/sh OLD_FILTER=`clicap filter` # # The dialog with the Agent for the above command looks like this: # > filter # R # > _ # # OLD_FILTER now contains "R" # echo The old filter was \`$OLD_FILTER\'. Moving it to \`V\'. exec clicmd filter V
Note the use of exec as the last statement in the shell script. It is appropriate to exec clicmd if the clicmd is the final step in the script, and the return code of the script should indicate the success or failure of this command. For clicmd (or anything else that can fail) appearing in the middle of a script, always check for failure so that scripts exit if something goes wrong.
clicmd filter V || exit 1
This command is identical to clicap, except that output goes to both stdout of clicap and the director window. If a script uses clidup and this script is called from the Director window, output will be seen twice! The clidup command is only useful in some rare cases.
Most of the functions in libcli are for building Agents themselves. There is also a function in libcli which can be used to pass a command from another C program to an agent. This has the same effect as system("clicmd ..."); but is more efficient. It is used as follows:
. . .
#include "cli/cli.h"
int
main(int argc, const char* argv[])
{
/* NOTE: Do _not_ call cli_init() unless this program is also an Agent. */
. . .
if (cli_cmd("filter V") != PASS)
exit(EXIT_FAILURE);
. . .
exit(SUCCESS);
}