rset(1) : pln(5)

Configure systems using any scripting language

overview | download 1.5

Features

Lightweight Execution start in < 0.5 second, task completion in as little as 0.9 seconds.
Real-time Status Standard output and error messages are piped in from target hosts without buffering.
Simple The standard tool chain can be mastered in 1 hour. All of the key operational paradigms are covered in the man pages ( rset(1), pln(5), rinstall(1), rsub(1) ).
Extensible Add capabilities by dropping scripts, executable, or data files into a directory that is shipped to each host.
Portable No dependencies for target BSD, Mac, and Linux machines; even Busybox on Alpine is enough.
Language Independent Shell scripts are most common, but any interpreter that can read on STDIN can be used (Ruby, Python, Perl, ...)
Secure Content visible to each host is explicitly specified in the routes file. Remote hosts can only request public data (source tarballs, packages, etc.)
Sequential All actions are executed in the exact order they were written. The dry-run feature highlights which hosts and labels will be executed.
Predictable Configuration and data are always located relative to the top-level routes file.

Overview

rset(1) matches a host pattern in a routes file and sequentially executes script fragments on remote hosts

# routes.pln

execute_with=sudo
interpreter=/bin/bash

www1: mail/
    nginx.pln
www2: mail/
    nginx.pln

pln(5) is a tab-indented format for embedding scripting languages to be executed in the order they were written

# nginx.pln
interpreter=/bin/ksh -x

packages:
    pkg_add -I ruby
    ln -sf /usr/local/bin/{ruby27,ruby}
    ln -sf /usr/local/bin/{irb27,irb}

services:
    ./rinstall mail/smtpd_relay.conf /etc/mail/smtpd.conf \
        && rcctl restart smtpd

# vim:ts=4:syntax=sh

The minimal directory layout for the example above is

├── _rutils
│   ├── rinstall
│   └── rsub
├── _sources
├── mail
│   └── smtpd_relay.conf
├── nginx.pln
└── routes.pln

Targets are matched using regular expressions, hence this will run on both machines:

$ rset www

Formulas

The following formulas are examples illustrate some of the ways in which pln(5) files can be written to configure services on OpenBSD. The same concepts apply equally well on other platforms.

Networking
Let's Encrypt
WordPress
PostgreSQL

Dial-in Configuration with WireGuard

Security Model

For the most part rset(1) does not trust the remote hosts it manages, and takes several steps to prevent an attacker from reading configuration intended for another host.

  1. Files and directories intended only for specific hosts are explicitly listed for each host. Only the contents of _rutils directory is copied implicitly to all hosts.
  2. Scripts embedded in pln(5) files are not copied, they are piped to the interpreter over SSH. This ensures that temporary files are never left behind containing sensitive information.

Several measures are also taken to prevent the compromise of the host running rset

  1. Large files are serviced by a local web server (darkhttpd by default) which only serves content under _sources.
  2. On OpenBSD, pledge(2) is used to eliminate write access to system resources and to sandbox the http server.

Comparison with other Orchestration Tools

A new generation of light-weight configuration management tools that allow configuration in any scripting language are appearing. The following catalogs differences among those I know about:

rset judo drist
Implementation C Go Shell
Execution Context remote remote remote
SSH ControlMaster always always optional
Allow Parital Configuration yes no no
Parallel Execution no yes no
Interactive debugging over STDIN optional no no
Utility Scripts Always Staged yes yes no
Ad-hoc Operations no yes no
HTTP access to local sources yes no no
File Transfer tar|ssh scp rsync
Remote Working Directory /tmp/rset_staging_N $HOME/.judo/XXXXXX $HOME
Built-in File Diff/Install yes no no
Built-in File Line/Block-Replace yes no no
SSH Agent required optional optional

Last updated on July 02, 2020
Send questions or comments to ericshane@eradman.com