Guide to configuring OLC clients

Starting in Athena release 8.1, it is no longer necessary to compile clients for various OLxx services separately. The OLC binaries in the Athena release can be made to act as any of their OLxx counterparts through use of configuration files.

The following sections are intended as a guide through the process of setting up the clients for any OLxx service. If you have questions about any of this, please let me know, and I'll attempt to make it clearer.

1. Client configuration files

Every OLxx client should have a configuration file describing its setup. (If, for some reason, the file cannot be found, the client binary will attempt to provide at least some functionality to the user, but this will not work as well or as reliably as a properly configured client.) If you're doing this on Athena, you may wish to start the process of configuring your client by looking at /usr/athena/lib/olc/olc.cfg and /usr/athena/lib/olc/olcr.cfg, which are the configuration files for olc and olcr, respectively. Later sections contain information on testing your configuration file and putting it into production.

1.1 Configuration file format

The client configuration file contains lines of the form 
	configuration_keyword
or 
	configuration_keyword   "string argument"
Blank lines are ignored. Any line starting with # will is a comment and will be ignored. (Note that the comment must start the line and may not appear following a configuration keyword on the same line.)

Unless otherwise noted, any particular configuration keyword should appear at most once in the configuration file. Here is a list of all keywords:

service "NAME"

Specifies the name of the OLxx service. NAME should be the capitalized name of the service.
Example: 
	service           "OWL"

This keyword is required for normal operation of the client.

fallback_server "server.host.name"

Specifies the hostname of the server. This value is used only if the Hesiod lookup fails.
Example: 
	fallback_server   "matisse.mit.edu"

This keyword is avaliable if the client uses Hesiod (always true on Athena). In that case, it is needed for normal operation of the client if the network experiences problems.

server "server.host.name"

(This keyword does not apply to Athena.) Specifies the hostname of the server.
Example: 
	server            "matisse.impressionists.org"

This keyword is avaliable if the client does not use Hesiod (never true on Athena). In that case, it is needed for normal operation of the client.

prompt "text> "

Specifies the default prompt, which may be overridden via the -prompt command-line flag.
Example: 
	prompt            "owl : "

If this keyword isn't specified, the prompt defaults to the name of the configuration file used, followed by a greater-than sign and a single space (e.g. "owl> ").

answer_client

If present, indicates that this client is used by the consultant-type people to answer questions and that consulting commands should be enabled. If not present, a question-asking-only client is assumed.

no_hours

If present, indicates that this service does not have set hours of operation, so the hours command is disabled.

consultant_title "title"

Specifies the "generic" title for one of the people answering questions. This is used primarily for messages to the user. (For example, if the title is set to "lazy no-good documenter", the user might see a message saying "You are not connected to a lazy no-good documenter.") Note that for messages referring to a particular person (eg. "You are connected to consultant joe"), the titles can be set on a person-by-person basis in a file on the OLxx server.
Example: 
	consultant_title  "Pontifex Maximus"

This keyword is required for normal operation of the client.

help_dir "/path/to/help"

Specifies the path to the directory containing help files. (See the discussion of OLC client help.)
Example: 
	help_dir          "/usr/athena/lib/olc/olc_help"

This keyword is required for help to work.

help_ext ".ext"

Specifies the filename extension for the help files. (See the discussion of OLC client help.)
Example: 
	help_ext          ".help"

If no extension is specified, ".help" is used.

help_name "help_file"

Specifies the help file displayed when help is used with no arguments. (See the discussion of OLC client help.)
Example: 
	help_name         "olc"

If no name is specified, the name of the configuration file is used, which may not be what you want.

stock_browser "/path/to/browser"

Specifies the path to the executable which can be used to access the stock answers tree.
Example: 
	stock_browser     "/mit/library/browser"

This keyword is required if the service has any stock answers.

stock_dir "/path/to/stock/answers"

Specifies the path to the root directory of the stock answer tree.
Example: 
	stock_dir         "/mit/library/stock_answers"

This keyword is required if the service has any stock answers.

stock_attach "command"

Specifies a command to execute in preparation for browsing the stock answers. This is usually used to attach (mount) the filesystem containing the stock answers, but can be used to run any command. More than one command can be specified by using the keyword more than once, in which case they will be executed in the order in which they are listed in the configuration file.
Example: 
	stock_attach      "/bin/athena/attach library"

This keyword can be omitted if the stock answers are always available.

stock_magic "/path/to/MAGIC"

Specifies a file to check to determine if the filesystem containing is available. If this file is not accessible, the commands specified by stock_attach (if any) are executed; if the file still isn't accessible, the stock answers are assumed to be unavailable.
Example: 
	stock_magic       "/mit/library/MAGIC"

This keyword is required if the service has any stock answers. (Even if your stock answers are available without running any special commands via stock_attach.)

1.2 Support for the help command

The OLC client configuration currently contains provides means for configuring the data displayed with the help command. However, at the time of writing, all OLxx services (olc, olta and owl) used the help files for olc. This means that help for olta actually refers to "olc", but presumably the user can figure out what is going on.

If you want to set up your own set of help pages, you can configure their location and filenames using the help_dir, help_name and help_ext configuration keywords. (You could do as little as replacing all occurrences of "olc" with the name of your OLxx service; Emacs search-and-replace should get the capitalization right.)

If you want to avoid customizing the help pages, you can use the help pages from the system packs by setting 

	help_dir          "/usr/athena/lib/olc/olc_help"
	help_ext          ".help"
as well as 
	help_name         "olc"
for your user client and 
	help_name         "olcr"
for the consulting client. Note that, in this case, you need to specify "olc" and "olcr" in place of the actual names of your clients, because help files named after your service won't be available on the system packs.

1.3 Support for stock answers

A client may also be configured to provide the answers command (also known as stock), which enables the user to browse a tree of "stock" answers to commonly asked questions. Of course, you will need to generate a stock answer tree, which goes beyond the scope of this document (and to the best of my knowledge isn't really documented anywhere). The root of the stock answer tree should be specified by the stock_dir keyword.

The stock_magic keyword must be used to specify the location of a file which will be available when the stock answers are. This should be a file in the same locker as the stock answer tree, or (if the files live on local disk) a file on the same disk partition. On Athena, this file is traditionally named /mit/lockername/MAGIC. If the tree lives in a locker, you should also use the stock_attach keyword to specify the command(s) to attach the locker.

In addition, you will need a configured OLxx browser, the path to which should be specified using stock_browser.

2. Running the client

2.1 Testing the client configuration

When you finish modifying your configuration file, you will probably want to see how well it works. Start making sure that the name of the configuration file is olxyz.cfg, where olxyz is whatever name you have chosen for the client. From the directory where the configuration file lives, run: 
	olc -config . -name olxyz
The -config flag specifies a directory (or a colon-separated list of directories) that will be searched for the configuration file. On Athena, this defaults to 
	/usr/athena/lib/olc:/mit/olta/config:/mit/library/config
The -name flag specifies the name of the configuration file to be found, with the .cfg extension removed. By default, this is the same as the name by which the client was invoked.

The client invoked in this way should work just as you would expect it to work when it actually gets installed. The only difference is that it may not find the OLC browser, or may use the old one, until you actually deal with the installation of the browser.

2.2 Installing the client as a script

For the release into the field, the OLxx clients can be set up in one of two basic ways. Using a script as the main client executable adds a negligible amount of work and provides a large amount of flexibility. You simply install the configuration file somewhere accessible and create an executable script that invokes olc with the appropriate arguments.

There are several Athena-specific issues to be considered at this point. If your client only needs to run on supported Athena platforms with release 8.1 or later, the script may be reducible to a single line, but otherwise, you should probably consider the following:

The simplest way to check if /usr/athena/bin/olc on an Athena machine has configuration support is to check for existence of the configuration files, for example /usr/athena/lib/olc/olc.cfg.

Finally, you can use symlinks to make the same script be used for the user and consulting clients, making maintenance a little simpler in the long run. The final result might look something like this: 

#!/bin/sh
# invocation script for olxyz and olxyzr

program=`basename $0`

if [ -f "/usr/athena/lib/olc/olc.cfg" ]; then
    # olc.cfg found, assuming /usr/athena/bin/olc is configurable.
    exec /usr/athena/bin/olc -config /mit/olxyz/config -name "$program" ${1+"$@"}
else
    BINARY="`/usr/athena/bin/athdir /mit/olxyz libexec`/$program"
    if [ -f "${BINARY}" ]; then
        # no configuration, but we have a non-configuration binary.
        exec ${BINARY} ${1+"$@"}
    else
        # oops, no binary found.
        echo "$program binary for this platform not found." >&2
        exit 1
    fi
fi

2.3 Installing the client as a symlink

If you are installing your OLxx client onto local disk, or into one of the lockers/mountpoints where the client looks for its configuration, you can simply install the configuration file and create a symbolic link to the client binary with the same name as your configuration file (minus the .cfg extension). Since the invocation name of the binary is the default value for the -name parameter, the binary will correctly find the configuration file and everything will work fine.

This is not recommended on Athena, due to the complications listed in the previous section.

3. Browser configuration files

Like the clients, OLxx stock-answer browsers are configured using configuration files. On Athena, the configuration file for olc_browser is in /usr/athena/lib/olc/olc_browser.cfg, which shouldn't come as a surprise if you've read chapter 1.

The general format of the configuration file is the same as for the client configuration, but the configuration commands are different (and fewer):

root_dir "/path/to/stock/answers"

Specifies the path to the root directory of the stock answer tree. If the browser is invoked from an OLxx client, the value from stock_dir in the client configuration will be used, but we need this in case the browser is invoked stand-alone.
Example: 
	root_dir         "/mit/library/stock_answers"

This keyword is required for normal operation of the browser.

header "Header Line For Browser"

Specifies the header displayed at the top of the browser screens.
Example: 
	header           "On-Line Librarian Browser"

Use of this keyword is optional, but encouraged.

prompt "text> "

Specifies the prompt for the browser.
Example: 
	prompt            "owl_browser> "

If this keyword isn't specified, the prompt defaults to "browser> ".

4. Running the browser

4.1 Testing the browser configuration

When you finish modifying your configuration file, you will probably want to see how well it works. Start making sure that the name of the configuration file is olxyz_browser.cfg, where olxyz_browser is whatever name you have chosen for the client. From the directory where the configuration file lives, run: 
	olc_browser -C . -N olxyz_browser -r /mit/olxyz/stock_answers
The -C and -N flags behave like -config and -name in the browser: the former specifies a directory (or a colon-separated list of directories) that will be searched for the configuration file, and the latter, the name of the configuration file. On Athena, the directories searched default to 
	/usr/athena/lib/olc:/mit/olta/config:/mit/library/config

4.2 Installing the browser

The issues regarding installation of the browser are similar to those involved in installing the client. It can be installed either as a script or a symlink, etc.

Here is an Athena-centric example of a wrapper script. The only differences from the example above is that -config and -name were replaced by their counterparts, -C and -N. 

#!/bin/sh
# invocation script for olxyz_browser

program=`basename $0`

if [ -f "/usr/athena/lib/olc/olc.cfg" ]; then
    # olc.cfg found, assuming /usr/athena/bin/olc is configurable.
    exec /usr/athena/bin/olc -C /mit/olxyz/config -N "$program" ${1+"$@"}
else
    BINARY="`/usr/athena/bin/athdir /mit/olxyz libexec`/$program"
    if [ -f "${BINARY}" ]; then
        # no configuration, but we have a non-configuration binary.
        exec ${BINARY} ${1+"$@"}
    else
        # oops, no binary found.
        echo "$program binary for this platform not found." >&2
        exit 1
    fi
fi
valid HTML Errors on these pages (and bugs in OLC) should be reported to <olcdev@mit.edu>.