.Dd February 17, 2026
.Dt DRIST 1
.Os
.Man "drist" "Remote script & files deployment helper"
.Sh NAME
drist \- copy files and run a script on remote hosts via ssh
.Sh SYNOPSIS
.B drist
[\-p] [\-d] [\-e sudo|doas] [\-S script] [\-f files-dir] [\-F file] destination [...]
.Sh DESCRIPTION
This utility copies a set of files (or a single file) to one or more remote hosts and executes a script on the remote side. It is designed to be POSIX‑sh compatible and to use ssh for remote operations. The implementation uses a temporary directory in the remote user's home to stage files and removes the temporary directory on completion.
.Sh OPTIONS
.Tp
.B \-p
Enable persistent ssh connections using ControlMaster. A ControlPath socket is created under /tmp with a 1 minute ControlPersist timeout.
.Tp
.B \-d
Truncate the remote host's fully‑qualified name at the first dot when looking for host‑specific files or directories.
.Tp
.B \-e
Run the remote command using a privilege escalation wrapper. The argument can be a command such as
.RS
.nf
sudo
doas
.fi
.RE
If specified as \-e doas the script will use doas to execute the remote command; \-e sudo will use sudo. When used the default EXEC wrapper is replaced with the given binary.
.Tp
.B \-S script
Specify the script file to execute on the remote host. Default: "script" (relative to the files directory or current directory).
.Tp
.B \-f files-dir
Specify a directory of files to copy to the remote host. Default: "files".
.Tp
.B \-F file
Specify a single file to copy to the remote host in addition to the files directory. Default: (none).
.Sh OPERATION
The program accepts either a list of destinations on the command line or a single file containing one destination per line.
For each remote host it performs these steps:
.IP \(bu 2
Create a temporary directory on the remote host using "mktemp -d ~/.drist_files_XXXXXXXXXXXXXXX".
.IP \(bu 2
Copy files from the local files directory (default "files") into the remote temporary directory, preserving relative paths.
.IP \(bu 2
If present, copy a host‑specific files directory named files-<hostname> (hostname optionally truncated) into the same remote temporary staging directory.
.IP \(bu 2
If specified, copy a single file and any host‑specific variants named <file>-<hostname>.
.IP \(bu 2
Upload and execute the script (default "script") from the remote temporary directory. The script is uploaded with execute permission and run with the configured EXEC wrapper (plain sh by default, or the chosen privilege escalation binary).
.IP \(bu 2
Remove the remote temporary directory.
.IP \(bu 2
If persistent connections were enabled, close the ssh ControlMaster connection.
.Sh FILE TRANSFER DETAILS
The tool uses tar piped over ssh to copy files. When copying a directory it:
.IP \(bu 2
Creates a file list of regular files and symlinks (find ... -type f -or -type l) relative to the source directory.
.IP \(bu 2
Uses tar to stream the directory (tar cf - -C . .) into the remote temporary directory, then remaps the staged directory content into the remote user's home directory with another tar pipe.
For a single file the tool:
.IP \(bu 2
Streams the file's directory entry into the remote temporary directory with tar, then moves the staged file into the remote user's home with tar on the remote side.
.Sh SAFETY AND ERRORS
.Tp
.B Remote mktemp failure
If mktemp on the remote host fails the program prints "mktemp error, aborting" and exits with status 1.
.Tp
.B SSH failure
If ssh to a remote host fails while attempting to obtain the host name the program prints "Error while ssh <host>" and exits with status 2.
.Tp
.B Tempdir safety check
When deleting the remote temporary directory the program verifies the directory name contains "drist_files_". If not present the program refuses to remove it and exits with status 2 to avoid accidental deletion.
.Sh EXAMPLES
.Tp
.B drist host1 host2
Upload the default files directory ("files") and execute the default script ("script") on host1 and host2.
.Tp
.B drist \-S deploy.sh \-f site-files \-F config.json hosts.txt
Upload site‑specific files from "site-files", upload "config.json", run "deploy.sh" on each host listed in hosts.txt.
.Tp
.B drist \-p \-e doas host
Use a persistent ssh connection and run the remote script with doas.
.Sh ENVIRONMENT
.Tp
.B SSH_OPTIONS
Custom ssh options may be supplied by setting SSH_PARAMS in the environment before invoking the program. The script itself sets SSH_PARAMS when \-p is used. Note: when \-p is used the script overrides SSH_PARAMS with ControlMaster / ControlPath / ControlPersist options.
.Sh IMPLEMENTATION NOTES
This documentation corresponds to a POSIX sh script with the following notable internal variables and helper functions:
.Tp
.B PRIVILEGES
Flag (0/1) to toggle use of a privilege escalation command.
.Tp
.B PRIVILEGES_BIN
Name of the privilege escalation wrapper (default "doas").
.Tp
.B EXEC
Command prefix used to execute the remote script (default "exec sh -c", changed to PRIVILEGES_BIN when PRIVILEGES=1).
.Tp
.B SSHONCE
Flag to enable persistent ssh ControlMaster socket.
.Tp
.B TRUNCATE
Flag to remove domain suffix from hostname when looking up host‑specific resources.
.Tp
.B USE_FILE, USE_DIR, COPY_FILE
Defaults for script filename, files directory and optional single file to copy.
.Tp
.B SSH_PARAMS
ssh command line options used when invoking ssh.
The key helper functions are:
.Tp
.B copy_files(src_dir, remote_server, remote_tmp)
Copy a directory tree of regular files and symlinks from src_dir into the remote_tmp on remote_server.
.Tp
.B copy_single_file(src_file, remote_server, remote_tmp)
Copy a single file (and any host‑specific companion named src_file-<hostname> if present) into remote_tmp on remote_server.
.Tp
.B remote_script(script_path, remote_server, remote_tmp)
Upload the script and run it on the remote host from the remote_tmp with configured EXEC wrapper.
.Tp
.B create_temp(remote_server)
Create a temporary directory on remote_server, storing the path in a local variable used by subsequent functions.
.Tp
.B delete_temp(remote_server, remote_tmp)
Remove remote_tmp on remote_server after validating its name contains the expected prefix.
.Sh EXIT STATUS
.Tp
.B 0
Success.
.Tp
.B 1
General error (no servers specified, mktemp failure).
.Tp
.B 2
SSH connection error or unexpected temporary directory name.
.Sh SECURITY CONSIDERATIONS
.Tp
.B Use of ssh
This program assumes ssh authentication and host key verification are configured appropriately. It does not perform additional verification of transferred content beyond what ssh/tar provide.
.Tp
.B Temporary directory removal
The script performs a pattern check on the temporary directory name before removal to reduce risk of deleting unintended paths, but exercise caution when running with elevated privileges.
.Sh AUTHOR
Original script authors: Rapenne Solène (2018) and John Kaul (2025). Documentation prepared for mandoc/mdoc(7) formatting.
.Sh SEE ALSO
ssh(1), tar(1), mktemp(1), sh(1), doas(1), sudo(8)
.PP
github.com
