Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

toc-local

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:

No Format
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:

No Format
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:

No Format
/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:

Code Block
#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:

Code Block
#russ service=socket

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

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

Code Block
#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

No Format
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:

No Format
ruservice . sync

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

No Format
ruservice local sync

Sync a single configuration from a source:

No Format
ruservice local:ssh sync

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

Clean the configuration files from the working area:

No Format
ruservice clean

Clean and sync the configuration files in working area:

No Format
ruservice resync
Warning
titleStop servers before clean

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

Starting, Stopping, and Checking Servers

Warning

A configuration must already be synced to the working area.

Start server:

No Format
ruservice ssh start

Stop server:

No Format
ruservice ssh stop

Restart (RUSS) ssh server:

No Format
ruservice ssh restart

Restart all servers:

No Format
ruservice . restart

Get status of all servers:

No Format
ruservice . status