Features
Lightweight | Execution start in < 0.5 seconds, task completion in as little as 1 second. |
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) stages configuration files and sequentially executes script fragments on remote hosts
# routes.pln execute_with=sudo interpreter=/bin/bash 10.10.0.20: mail/ → www.pln 10.10.0.21: mail/ → www.pln
pln(5) is a tab-indented format for embedding scripting languages to be executed in the order they were written
# www.pln interpreter=/bin/ksh -x packages: → pkg_add -I ruby → ln -sf /usr/local/bin/{ruby32,ruby} → ln -sf /usr/local/bin/{irb32,irb} services: → ./rinstall mail/smtpd_relay.conf /etc/mail/smtpd.conf \ → && rcctl restart smtpd # vim:noexpandtab:syntax=sh:ts=4
The minimal directory layout for the example above is
├── _rutils │ └── renv │ ├── rinstall │ └── rsub ├── _sources ├── mail │ └── smtpd_relay.conf ├── www.pln └── routes.pln
-
_rutils
contains utilities to be shipped to the staging directory on every remote host.rinstall
andrsub
are installed automatically, and provide an easy means of installing and modifying files.renv
provides an interface for setting session-level environment variables. -
_sources
is a directory made available by a built-in web server, typically larger files thatrinstall
can fetch on demand. -
In this example
mail
is also replicated to a temporary staging directory on the remote host since it was listed for export inroutes.pln
-
routes.pln
lists each host to manage along with the rules to run for each.
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.
PicOS Switches and Routers
Juniper Switches and Routers
OpenSMPTD Relay
Login Message
Let's Encrypt
WordPress
WireGuard
Multiple Platforms
Minio Lab
Check and Install
Metabase
Add/Modify Users
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.
-
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. - 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
-
Large files are serviced by a local web server,
miniquark(1),
which only serves content under
_sources
. - On OpenBSD, pledge(2) is used to eliminate write access to system resources and to sandbox the http server.