rset.1

.\"
.\" Copyright (c) 2018 Eric Radman <ericshane@eradman.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd September 24, 2024
.Dt RSET 1
.Os
.Sh NAME
.Nm rset
.Nd remote staging and execution tool
.Sh SYNOPSIS
.Nm rset
.Op Fl AenRtv
.Op Fl E Ar environment
.Op Fl F Ar sshconfig_file
.Op Fl f Ar routes_file
.Op Fl x Ar label_pattern
.Ar hostname ...
.Nm rset
.Op Fl ev
.Op Fl E Ar environment
.Op Fl F Ar sshconfig_file
.Op Fl f Ar routes_file
.Op Fl x Ar label_pattern
.Fl o Ar log_directory
.Fl p Ar workers
.Ar hostname ...
.Sh DESCRIPTION
.Nm
evaluates script fragments written in Progressive Label Notation
.Pq Xr pln 5 ,
executing each script in sequence using ssh connection multiplexing.
.Nm
accepts one or more hostnames which match the labels in
.Ar routes_file .
.Pp
The arguments are as follows:
.Bl -tag -width Ds
.It Fl A
Download files listed in label export paths to the local
.Pa _archive
directory in the format
.Sq hostname:basename(filename) .
Absolute paths are permitted, or paths relative to the staging directory.
.It Fl e
Exit immediately if any label returns non-zero exit status.
.It Fl n
Do not connect to remote hosts.
May be combined with
.Fl x
to highlight label names that match.
Special text defined between { and } is still executed locally.
.It Fl R
Send files listed in label export paths from the local
.Pa _archive
directory.
This is the reverse of
.Fl A .
.It Fl t
Allow TTY input by copying the content of each label to the remote host instead
of opening a pipe to the interpreter.
.It Fl v
Print the HTTP log messages after each label is executed.
.It Fl E
Set one or more environment variables using the format
.Sq name="value" ... .
.It Fl F
Specify a
.Pa config
file for
.Xr ssh 1
to use.
.It Fl f
Specify a
.Ar routes_file .
This file is composed of labels which correspond to
hostnames or IP addresses which are matched against
.Ar hostname .
The default is
.Pa routes.pln .
.It Fl o
Log directory to use for background workers.
Each log file is created for each worker using the format
.Ql YYYY-MM-DD_HHMMSS.n .
.It Fl p
Parallel execution distributed across the specified number of workers.
The log directory must also be specified using
.Fl o .
A summary of results is displayed using the
.Pa rexec-summary
script located in the search path.
.It Fl x
Execute labels matching the specified regex.
By default only labels beginning with [0-9a-z] are evaluated.
.El
.Sh ENVIRONMENT
Status messages for each stage of execution may be customized by setting
.Ev RSET_HOST_CONNECT ,
.Ev RSET_HOST_CONNECT_ERROR ,
.Ev RSET_LABEL_EXEC_BEGIN ,
.Ev RSET_LABEL_EXEC_END ,
.Ev RSET_LABEL_EXEC_ERROR ,
and
.Ev RSET_HOST_DISCONNECT .
.Pp
Setting
.Ev RSET_HOST_CONNECT
disables the default status messages and is the only required variable.
These have no effect in conjunction with the
.Fl n
flag.
The following variables are interpolated:
.Pp
.Bl -tag -compact -width 4n
.It Li \%%e
exit code
.It Li \%%l
label name
.It Li \%%h
hostname
.It Li \%%s
session identifier
.It Li \%%T
rfc-3339 timestamp
.It Li \%%%
literal
.Ql %
.El
.Pp
Execution on the remote host sets the following environment variables:
.Bl -tag -width "RSET_ENVIRON"
.It Ev INSTALL_URL
Used by
.Xr rinstall 1
for fetching content from
.Pa _sources .
.It Ev SD
Staging directory where
.Nm
unpacks utilities and configuration files.
.El
.Pp
Environment state may set for the duration of the ssh session
using
.Xr renv 1
using
.Ql name=value
as the first argument.
.Sh FILES
Available hosts and the pathnames to labeled scripts to run are read from
.Pa routes.pln ,
located in the current directory.
.Pp
A ssh master is established at the beginning of a session and all subsequent
interactions with a host are run over a socket at
.Pa /tmp/rset_control_{hostname} .
.Pp
The local directory
.Pa _rutils
is created if it does not exist, and is shipped to the remote host at the
beginning of each execution to directory named
.Pa /tmp/rset_staging_{http_port} .
.Sh OPTIONS
The following options are recognized when parsing a
.Xr pln 5
file:
.Ss \&environment=
Space separated list of environment variables.
Only values matching the pattern
.Ql name="value"
are added to the environment on the remote host.
.Ss \&environment_file=
Path to a file which defines environment variables validated by
.Xr renv 1 .
.Ss \&interpreter=
The interpreter to run a script fragment with.
Defaults to
.Pa /bin/sh ,
but any language may be used that is capable of reading scripts over STDIN.
.Ss \&local_interpreter=
The interpreter to evaluate content that is prepended to a script
Defaults to
.Pa /bin/sh .
.Ss \&execute_with=
Command for elevating privileges, such as
.Xr doas 1
and
.Xr sudo 8 .
.Sh SINGLE USE OPTIONS
The following are effective only for the subsequent label:
.Ss \&begin=
Execute a script using the
.Sq local_interpreter
before the label is executed on the remote lost.
.Ss \&end=
Execute a script using the
.Sq local_interpreter
after the label is executed on the remote host.
.Sh SEE ALSO
.Xr miniquark 1 ,
.Xr rinstall 1 ,
.Xr rsub 1 ,
.Xr ssh_config 5 ,
.Xr re_format 7