Skip to end of metadata
Go to start of metadata

The rubb tool replaces ruservice in every respect. ruservice exists only to redirect to rubb.

Contents

Introduction

The rubb tool allows a user to manage RUSS bulletin boards (BB). BBs host RUSS services. When used with the "+" plus server, one or more BBs can be searched.

There are two kinds of BBs: system and user. System BBs are managed by administrators and use the system space. User BBs are user-specific and use the user space. System BBs can host services by a socket (running program) and configuration files (runs on demand). User BBs host service by configuration files only.

System BBs are set up using a bb.sources file. This file specifies the configuration sources used to set up. The rubb "sync" command syncronizes from the sources to the BB. User BBs cannot be set up using a bb.sources file. Instead, the rubb "install" command is used.

BB Sources File

The bb.sources file specifies the configuration sources and uses the format:

<bbname>:<tag>:<sourcetype>:<source>

The default bb.sources file is at /etc/russ/bb.sources and is initially configured as:

system:local:dir:/etc/russ/conf

It specifies:

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

Some of these settings are familiar as they continue to reference the standard source of the configurations. This makes upgrading to RUSS v7 easy.

To add another entry:

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

This specifies:

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

When the rubb "sync" command is run, the files at locations specified in the bb.sources are installed to the BB area. Any changes to the sources requires another sync. The system BB area is an ephmeral and is setup from scratch at boot time.

BB Area

The system BB area is organized as:

/var/run/russ/
  bb/
    <bbname>/
      conf/
      pids/
      services/

where:

  • <bbname> is a unique BB name (default system BB is named "system")
  • conf contains the configuration files sync'ed from the sources
  • pids contains pid files for each started server
  • services holds service socket files or configuration files (without the .conf ending) that have been "start"ed

The user BB area is organized as:

~/.russ/
  bb/
    <bbname>/
      conf/
      services/

where:

  • conf contains the installed configuration files
  • services holds configuration files (without the .conf ending) the have been "start"ed

Configuration File Directives

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

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

If #russ is found, then rubb-specific directives may affect what rubb does.

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.

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

Usage

usage: rubb [<options>] <cmd> [<cmdoptions>]
       rubb -h|--help|help

Manage system or user RUSS bulletin boards (BB). A BB hosts RUSS
services. Although the services can be accessed directly using a
path, the standard way is to use the ("+") plus service. By default,
the plus server searches for services at some system ("system") and
user ("override", "fallback") BBs.

System BBs can host services by either a socket (running) or
configuration file (run on demand). The user BBs host services by
configuration only.

For system BBs, a bb.sources file is used to specify the
configuration sources used to set up. Use the "sync" command to
syncronize from the sources to the BB. The default sources file is
at:
    /etc/russ/bb.sources

System BBs are located at:
    /var/run/russ/bb

For user BBs, configurations are installed using the the "install"
command.

Options:
--bb <bbname>   Operate on the named BB. System default is "system",
                User default is "override".
--sources <path>
                (system) Alternate path of the bb.sources file.

Operations:
clean           Clean BB.
install <filename> [<newname>]
                Install configuration (filename ends with .conf). Use
                <newname> to override name derived from <filename>.
list [-l]       List BB entries. Use -l for details.
list-bb         List BBs.
list-sources    (system) List sources from sources file.
remove <name>   Remove configuration.
restart         Restart server.
resync          (system) Call clean+sync.
show <name>     Show configuration.
start           Start server. Make available for use.
status          Report status of servers.
stop            Stop server. Make unavailable for user.
sync [<tag>,...]
                (system) Syncronize local configuration used sources
                specified in a bb.sources file. Use <tag> to limit
                sources to use.

Examples

Managing System BBs

System Defaults

  • The default system BB is "system".
  • The default system sources file is /etc/russ/bb.sources.

List BBs:

rubb list-bb

List sources by tag name:

rubb list-sources

Sync from all sources:

rubb sync

Sync BB from a single source identified by the tag (e.g., "local"):

rubb sync local

Clean the BB:

rubb clean

Clean and sync the BB (does not start servers):

rubb resync

List BB servers:

rubb list

Managing User BBs

User Defaults

  • The default user BB is "override".
  • There is not use sources file.

List BB servers:

rubb list

Install server configuration (own copy of debug.conf) to BB:

rubb install /etc/russ/conf/debug.conf

Install server configuration to an alternate name (debugx; name with .conf) to BB:

rubb install /etc/russ/conf/debug.conf debugx

Remove server configuration from BB:

rubb remove debugx

Starting, Stopping, and Checking Servers

Start all BB servers:

rubb start

Start named BB servers:

rubb start ssh

Stop all BB servers:

rubb stop

Stop named BB servers:

rubb stop ssh,debug

Restart all BB servers:

rubb restart

Restart named BB servers:

ruservice restart ssh,debug

Get status of all BB servers:

rubb status

Get detailed status of all BB servers:

rubb status -l