Zeus Admin Server

Network registry tools

Aim

To provide information on using the command line tools to edit configuration entries directly allowing them to bypass the web interface of the administration server. This allows the reader to configure options for which there is no web interface, or to automate configuration changes through shell scripts.

Introduction

All Zeus configuration information is stored in a central registry that is built into the admin server. The interface to the registry is via a TCP/IP connection allowing remote applications to share centralised configuration settings. With each configuration setting, the registry also holds access control information to implement a secure delegable configuration system.

Each Zeus application retrieves its configuration settings from this registry, and the administration server provides a web based interface for easy configuration of the frequently used settings.

To support this model, the configuration data held by the registry is not editable directly, but held in a private format. Instead command line tools are provided which can perform any modification on the configuration data, access control permitting.

Terminology

The registry consists of a hierarchical set of key/value pairs. Each key may be a setting, or a branch with key/values pairs beneath it. The diagram below shows a portion of the configuration hierarchy. All persistent configuration information is contained within a parent branch called conf. A full setting name is written in a textual form by placing a '!' between each branch, e.g. conf!web!servers!myserver!port.

The regedit program

The regedit program (in the $ZEUSHOME/bin directory) allows the user to visualise and modify the registry hierarchy interactively.

Upon running regedit, a screen similar to that shown below will be seen:

Use the cursor keys to navigate the registry hierarchy. A + indicates a branch which is closed. Pressing the cursor right key will expand the branch and display its entries. The + will also have changed into a - indicating the branch is open. Pressing the cursor left key on an open branch will close it. The cursor up and down keys can be used to select a particular entry in a branch. Switching between fields in dialogue boxes may be achieved with the TAB key.

Commands

The commands available are displayed across the bottom of the screen. These commands are:
.
Key press Function
A Adds an entry under the current branch
B Adds a branch under the current branch
E Edits the current setting
D Deletes the current setting or branch
L Login to the registry as a valid user
R Renames the current setting or branch
S Alters the users which may modify this setting or settings below and including this branch
Q Quits the regedit program

The registry allows read access to all users, but any operation which involves modifying the registry configuration requires logging into register with a valid user and password. Generally this is the admin password which you use for using the admin-server web interface. To login to the registry, press the 'l' key, and a dialogue will allow you to enter a user and password. When you are logged into the registry, your user is shown in the top left of the screen.

Most of the operations of the regedit program are simple enough to require no explanation. However the add operation will be discussed in more detail here.

Choosing to add a setting under the current branch brings up a dialogue as show below. Each setting in the registry has an associated type. When adding a setting, you should ensure that you create it with the correct type.

The regcmd program

The regcmd tool (in the $ZEUSHOME/bin directory) allows you to directly issue commands to the registry. The core commands are:

add <key> <type> <value> Adds a new setting to the registry
set <key> <value> Sets an existing value
branch <name> Adds a new branch
get <key> Retrieves the value of an existing setting
delete <key or branch> Deletes a specified key or branch from the registry
copy <source> <dest> Copies a registry branch or key
list <branch> List a branch
listval <branch> List a the keys under a branch along with their values
setcrypt <key> <crypted-value> Set a crypted registry setting

The regcmd program reads commands from a file (or stdin if a '-' is used in place of a file). A simple example would be:

echo 'get conf!paths!zeushome' | regcmd - This will retrieve the setting conf!paths!zeushome from the registry and print it to stdout. Note that single forward quotes are used as '!' is a special character in many shells.

The regcmd program also has -user and -pass arguments to authenticate yourself to the registry. Instead of using -pass, you can alternatively use -passfile <filename> to provide the password from a file instead of supplying it on the commandline.

The regdump program

The regdump program reads the registry file off disk, and displays all the settings. The output is in regcmd format, so that it can be piped back into regcmd. You cannot run regdump on a registry file that is currently being used by a running admin server.

Example Usage

The following command will list all the configured webservers setup in the standard registry database file. regdump $ZEUSHOME/etc/reg.data | grep 'branch conf!web!servers![^!]*$' \ | cut -d'!' -f4`

Notes

As mentioned previously, make sure all '!' characters appear inside forward single quotes as many shells will expand them otherwise. However, environment variables will not be expanded inside single quotes, so you may need to use: echo 'add conf!web!servers!'$NAME'!docroot text '$DOCROOT

Further Information

The upgrade.sh and adduser.sh scripts in the web/bin directory are good examples of using the tools. Similarly the fpinst.sh script for setting up Frontpage. Other good examples are the post_install scripts found in packages/webbin/post_install and packages/adminbin/post_install

Contributing Scripts

If you write scripts that you feel other people might find useful, please email the to us, and we will make them available for other customers on our website.