Skip to end of metadata
Go to start of metadata

Contents

Introduction

System RUSS servers are managed using the ruservice tool. ruservice  can pull configurations from local and network sources. This simplifies management for large numbers of hosts.

Sources

The ruservice.sources file specifies the sources of configuration files. The default ruservice.sources file at /etc/russ/ruservice.sources is:

local:dir:/etc/russ/conf

This follows the location of configuration files pre RUSS v7. It specifies:

  • tag of "local"
  • source type of "dir" (directory)
  • location of /etc/russ/conf

To add another entry:

net:dir:/net/gpsc4/be/conf

This specifies:

  • tag of "net"
  • source type of "dir"
  • location of /net/gpsc4/be/conf (which, for example's safe is a network filesystem)

The files at locations specified in the ruservice.sources are copied to the working area using the ruservice sync command. The working area is an effemeral location under system space. Any changes to the sources requires a sync.

Working Area

The ruservice working area is organized as:

/var/run/russ/
  conf/
  pids/
  services/

where:

  • conf contains the files sync'ed from the sources
  • pids contains pid files for each started server
  • services container service address files (which + implicitly references)

ruservice Directives

ruservice treats the first line of the configuration file as special if it starts with #russ:

#russ [<directive>] [...]

If #russ is found, then ruservice-specific directives are loaded which may affect how ruservice does its job.

If the configuration file contains "service=socket" as:

#russ service=socket

then a server is started and a socket file is set up.

If the configuration file contains "service=conffile" as:

#russ service=conffile

a slightly modified/augmented copy of the configuration file is copied to working area.

For the socket approach:

  • It is required when a server needs to perform operations on behalf of (e.g., root), but not as, the connecting user.
  • It is useful when the fastest turnaround time (connect, perform service, close) is required.
  • It is useful when the server is threaded and must maintain state between multiple connections.

For the conffile approach:

  • It is suitable for servers that will run as the connecting user
  • It is suitable to reduce the number of running server processes.

ruservice uses ruspawn to start socket servers. ruspawn automatically cleans up the socket file when the server exits/is killed.

Usage

usage: ruservice clean|list-sync|resync
       ruservice <srcname> sync
       ruservice [-n] <confname> {start|stop|restart|status|list}
       ruservice list|status
       ruservice -h|--help|help

Manage system RUSS servers and configuration.

The file ruservice.sources contains directives for setting up the
configuration files in the ephemeral directory:
	/var/run/russ/conf

The configuration directory is managed using:
clean	Clean configuration directory.
sync	Load configuration directory based on the ruservice.sources
	file.
resync	Call clean+sync.

Once the configuration directory is set up, servers may be managed
by start, stop, restart, status, and list.

The <confname> is one of:
* a configuration filename/path (without the .conf)
* a directory for all configurations under it
* "." for all
* server name (when -n is specified) matching all configurations
  with 'name=<name>' in the #russ header line.

Examples

Managing the Working Area

Sync from all sources:

ruservice . sync

Sync from a single source (e.g., "local"):

ruservice local sync

Sync a single configuration from a source:

ruservice local:ssh sync

This prevents changes to other configurations already in the working area.

Clean the configuration files from the working area:

ruservice clean

Clean and sync the configuration files in working area:

ruservice resync

Stop servers before clean

It is important to stop servers before a "clean" operation is done.

Starting, Stopping, and Checking Servers

A configuration must already be synced to the working area.

Start server:

ruservice ssh start

Stop server:

ruservice ssh stop

Restart (RUSS) ssh server:

ruservice ssh restart

Restart all servers:

ruservice . restart

Get status of all servers:

ruservice . status