koeboot and koehalt - Starting and Stopping the System

Name

koeboot, koehalt -- Utilities for booting and halting the KOE

Synopsis

koeboot [-f filename] [-x] [-q] [-h] [kssname ...]

koehalt [-f filename] [-x] [-q] [-h] [-w] [-z] [-a] [kssname ...]

The koeboot utility starts up a KOE, including the Worldroot, Knowbot Service Stations (KSS), and tools such as the Visualizer. The description of what gets started is contained in configuration files which can be customized for a specific site or user.

The koehalt utility shuts down a KOE, and like the koeboot utility, finds the list of components to shut down by looking at the configuration files.

Command Line Options

The koeboot utility supports the following options. For each option, a short and a long form is supported. Long options start with two dashes.

-f filename
--filename filename: Read the specified configuration file after reading all the system default configuration files. See the Files section belowfor a description of the load order. Multiple -f options can be specified on the command line.
-x
--exclude: Change the semantics of command line specified kernel lists, so that all configuration file specified kernels except those listed on the command line will be started or shut down.
-q
--quiet: Do not print status information as parts of the KOE are started up or shut down.
-h
--help: Print a usage message and exit.
kssname ...: The optional list KSSs to start up or shut down. The semantics of this list are dependent on the presence of the -x flag, and are described in detail below.

The koehalt utility supports the same options as koeboot, as well as the following:

-w
--worldroot: Shut down the Worldroot server. Ordinarily, koehalt does not shut down the Worldroot.
-z
--visualizer: Shut down the Visualizer. Ordinarily, koehalt does not shut down the Visualizer.
-a
--all: Shut down both the Worldroot and the Visualizer.

Files

These utilities are driven by a set of configuration files, which can be customized on a per-site and per-user basis. By default, all configuration files reside in the configuration directory, normally $KOSROOT/config. The configuration files are, in the order in which they are loaded:

boot -- the standard, default configuration file.
boot.cluster -- a site specific configuration file.
boot.<USER> -- a user specific configuration file, where <USER> is the value of the $LOGNAME environment variable, or if that is not defined, the $USER environment variable.
If -f options were specified on the command line, then the associated files are loaded.

Configuration files that are loaded later in the order can override or augment values defined in earlier files.

In configuration files, lines beginning with a # character are comments, and the rest of the line is ignored. Note that # is a comment character if and only if it is the first non-whitespace character on the line.

Each configuration file is made up of sections, which are delimited by tags of the format: [SECTION] where the word inside the square brackets has some predefined meaning. Inside the sections, lines are of the format:

option: value

where continuations and such are in the style of RFC 822 headers. Section names are case sensitive, but option names are case insensitive. Values are taken literally, and quotes are not needed for multi-word values. However, if the value is meant to be the empty string, then "" must be used.

The values can contain format strings (of the Python variety) which refer to other values in the same section, or values in a special [DEFAULT] section, defined at the top of the boot configuration file. For example:

something: %(dir)s/whatever

would resolve the string %(dir)s to the value of the dir option. All option expansions are performed as late as possible, and only on demand. The following substitutions are predefined:

%(kosroot)s -- the base directory of the KOE software (i.e. $KOSROOT).
%(kosname)s -- the name of the current KSS being started.
%(hostname)s -- the short name of the host machine.

There are currently four predefined sections, with several optional sections also allowed.

The [DEFAULT] Section

This section defines the default values of all options, which are inherited by all the other sections. The following options are defined, along with their default values:

enable

A boolean value (i.e. either 0 or 1) which describes whether this application should be started up by koeboot. Default value is 1. (Setting this to 0 is an easy way to disable a configuration entry temporarily.)

args

A string containing the command line arguments for the program. The default value is

    -n %(kosname)s -q

which is relevant for starting KSS kernels in quiet mode, with the given kernel name.

exec-file

The path to the program. The default value is

    %(kosroot)s/kernel/kernel.py

which is the path to the KSS kernel program.

ns-path

The path within the namespace to check for the program's existence. The default value is

    kos/%(kosname)s/receiver

which is path to a KSS kernel's Receiver object.

ping-for-life

A boolean value. If true, ns-path existence in the namespace is not enough to guarantee object liveness. When this value is 1, the object is also pinged to verify liveness. The default value is 0.

wait-for

A boolean value. If true, after the program is started, koeboot waits for the ns-path to appear in the namespace before continuing to start up subsequent programs. If the name it is waiting for fails to show up before a timeout occurs, koeboot aborts. The default value is 1.

x-display

The value of the $DISPLAY environment variable for the program's execution. If the value is the empty string, $DISPLAY is inherited from the parent environment.

The [Worldroot] Section

This section defines how to start the Worldroot server. The default configuration file contains the appropriate information.

The [Visualizer] Section

This section defines how to start the Visualizer (if at all). The default configuration contains the appropriate information but disables the visualizer. It can be enabled by a [Visualizer] section containing

enable:1

in the user specific configuration file.

The [KERNELS] Section

This section specifies the list of KSS kernels to start or shut down, by name. This section is arranged differently than the other sections, since it is used to simply define the list of KSSs to start or shut down. There are two ways this list is defined:

The - option (a single hyphen). If the value for the - option is non-empty, it is a list of kernel names.
An option matching the name of the current host computer. To match these options, fully qualified domain name matches are preferred over non-qualified host names. If a matching option in the [KERNELS] section is found, then the value is a list of kernel names to start or stop. This list is appended to the list found under the - option.

For example, suppose the boot configuration file contains the following section:

[KERNELS]
-:        %(hostname)s
gather:   searcher imagerepo

On a host named gather, koeboot would start up three kernels, named gather, imagerepo and searcher. On all other hosts, only one kernel would be started, and it would have the host's name. The same rules are used by koehalt, except that it only shuts down kernels if it believes they are up and running.

Kernel specific sections

Each KSS kernel can have its own section, specified by putting the kernel name in square brackets. Within this section, you can override any option, with values specific to that kernel. You do not have to have a kernel specific setion for every KSS named in the [KERNELS] section.

KSS Lists

The list of KSSs to start or stop is determined based on the configuration files and the command line options given to the scripts.

If no KSS names are given on the command line, then only those kernels found in the configuration files are started or stopped. If any KSS names are given on the command line, then only those kernels are started or stopped, and the KSS names in the configuration files are ignored. If the -x option is given then all kernels specified in the configuration files are started or stopped except those named on the command line.