3 fef9b495 2025-05-31 xs ### Introduction
5 688c9bfd 2025-06-03 xs R7 is a configuration management framework made to configure nodes with
6 8e44e3d4 2025-06-25 xs configuration files and related operations versioned in a central repository.
7 8e44e3d4 2025-06-25 xs To remain code versioning system agnostic, manual or automated versioning is
8 688c9bfd 2025-06-03 xs left to the user, via makefiles or triggered from r7 `site-config` configuration
9 688c9bfd 2025-06-03 xs file _(See below)_.
11 688c9bfd 2025-06-03 xs The idea is to store hosts configurations in `nodes/hostname` directories that
12 35f45d45 2025-06-04 xs maps each host's `/etc` and to assign those hosts to configuration groups
13 35f45d45 2025-06-04 xs containing the directives to install the configuration and potential
16 8e44e3d4 2025-06-25 xs _Nodes sub-directories are host names understood by the ssh client and
17 688c9bfd 2025-06-03 xs configuration._
19 8e44e3d4 2025-06-25 xs _Currently, r7 requires valid ssh configuration and key files in the repository
20 688c9bfd 2025-06-03 xs `.ssh/` directory._
22 688c9bfd 2025-06-03 xs _Repositories can be initialized with `rset init` or `rset -w
23 688c9bfd 2025-06-03 xs path/to/new-repository init`, the user will then have to provide valid
24 688c9bfd 2025-06-03 xs configurations and keys for `.ssh/` in the newly created directory._
26 688c9bfd 2025-06-03 xs _See [Technical Notes](#technical-notes) for dependencies and supported
29 fef9b495 2025-05-31 xs There is an example of r7 repository:
36 fef9b495 2025-05-31 xs ./groups/common
37 fef9b495 2025-05-31 xs ./groups/test0
38 fef9b495 2025-05-31 xs ./groups/common.dir
39 fef9b495 2025-05-31 xs ./groups/test0.dir
42 fef9b495 2025-05-31 xs ./.ssh/id_ed25519_r7
43 fef9b495 2025-05-31 xs ./.ssh/id_ed25519_r7.pub
46 fef9b495 2025-05-31 xs There is an example of r7 site configuration (`site-config` file):
49 fef9b495 2025-05-31 xs prefix install state doc
50 fef9b495 2025-05-31 xs group common '.*'
51 fef9b495 2025-05-31 xs group test0 hostB hostC
56 8e44e3d4 2025-06-25 xs There is an example of the deployment of that configuration within the r7
60 730e151b 2025-06-02 xs $ r7 run-config
61 730e151b 2025-06-02 xs - (ok) hostA:common::install_nothing
62 730e151b 2025-06-02 xs - (ok) hostA:common::state_uname
63 730e151b 2025-06-02 xs - (ok) hostA:common::doc_tutorial
64 730e151b 2025-06-02 xs - (ok) hostB:common::install_nothing
65 730e151b 2025-06-02 xs - (ok) hostB:common::state_uname
66 730e151b 2025-06-02 xs - (ok) hostB:common::doc_tutorial
67 730e151b 2025-06-02 xs - (ok) hostC:common::install_nothing
68 730e151b 2025-06-02 xs - (ok) hostC:common::state_uname
69 730e151b 2025-06-02 xs - (ok) hostC:common::doc_tutorial
70 730e151b 2025-06-02 xs - (ok) hostB:test0::state_test
71 730e151b 2025-06-02 xs - (ok) hostC:test0::state_test
74 fef9b495 2025-05-31 xs In this example, everything goes fine, groups are executed on each related
75 fef9b495 2025-05-31 xs nodes, note the `'.*'` matching all hosts present in `./nodes`. Groups are POSIX
76 fef9b495 2025-05-31 xs shell scripts that are a collection of functions.
78 fef9b495 2025-05-31 xs There is the `common` group:
81 fef9b495 2025-05-31 xs install_nothing() {
82 fef9b495 2025-05-31 xs echo Nothing installed
85 fef9b495 2025-05-31 xs state_uname() {
89 fef9b495 2025-05-31 xs doc_tutorial() {
90 fef9b495 2025-05-31 xs echo "## Welcome to the R7 tutorial!"
94 fef9b495 2025-05-31 xs And there is the `test0` group:
97 fef9b495 2025-05-31 xs state_test() {
102 730e151b 2025-06-02 xs Any function managed by `r7` needs to be declared in the format `^PREFIX_NAME()`.
104 fef9b495 2025-05-31 xs Group files names can't contain spaces, tabs or newlines, as well for nodes
105 8e44e3d4 2025-06-25 xs `dirnames`. _The ':' character is not recommended as well as it may reduce
106 8e44e3d4 2025-06-25 xs readability of the interactive output._
108 fef9b495 2025-05-31 xs Called groups and node directories are copied to related nodes in `hostname:/tmp/r7/`:
110 fef9b495 2025-05-31 xs /tmp/r7/hostA/ # Contents of test.org/nodes/hostA/
111 fef9b495 2025-05-31 xs /tmp/r7/common.dir # Contents of test.org/groups/common.dir/
112 fef9b495 2025-05-31 xs /tmp/r7/test.dir # Contents of test.org/groups/test.dir
114 fef9b495 2025-05-31 xs Groups may have no `.dir` directory, in this case, nothing is copied.
116 fef9b495 2025-05-31 xs Once the group copy is done, functions are executed in the order of the defined
117 730e151b 2025-06-02 xs prefix (part of the `site-config` file shown before):
119 fef9b495 2025-05-31 xs prefix install state doc
121 4296d94d 2025-06-07 xs This means the functions matching `^install.*()`, `^state.*()` and `^doc.*()`
122 730e151b 2025-06-02 xs (the default `R7_PREFIX`) in the respective declaration order they're found in the
123 fef9b495 2025-05-31 xs related group file will be executed.
125 8e44e3d4 2025-06-25 xs Site configurations are shell scripts sourced by r7 after it's environment is
126 fef9b495 2025-05-31 xs initialized, so `prefix`, `group`, `output-dump`, `summary` are the functions or
127 fef9b495 2025-05-31 xs aliases provided by r7 itself. This allow for scripting from the `site-config`
128 fef9b495 2025-05-31 xs file. Here `output-dump`, and `summary` are called to output potential errors,
129 fef9b495 2025-05-31 xs diffs and permissions changes at the end of the interactive output obtained by
130 8e44e3d4 2025-06-25 xs `r7 run-config`. If nothing happened, nothing is added to the output.
132 fef9b495 2025-05-31 xs ### Errors during remote execution of groups
134 fef9b495 2025-05-31 xs In our previous example, we modify `state_test` so the `test` fails.
137 fef9b495 2025-05-31 xs state_test() {
142 8e44e3d4 2025-06-25 xs And we re-run the configuration to see what's happening.
145 730e151b 2025-06-02 xs $ r7 run-config
146 730e151b 2025-06-02 xs - (ok) hostA:common::install_nothing
147 730e151b 2025-06-02 xs - (ok) hostA:common::state_uname
148 730e151b 2025-06-02 xs - (ok) hostA:common::doc_tutorial
149 730e151b 2025-06-02 xs - (ok) hostB:common::install_nothing
150 730e151b 2025-06-02 xs - (ok) hostB:common::state_uname
151 730e151b 2025-06-02 xs - (ok) hostB:common::doc_tutorial
152 730e151b 2025-06-02 xs - (ok) hostC:common::install_nothing
153 730e151b 2025-06-02 xs - (ok) hostC:common::state_uname
154 730e151b 2025-06-02 xs - (ok) hostC:common::doc_tutorial
155 730e151b 2025-06-02 xs - (error 1) hostB:test0::state_test
156 730e151b 2025-06-02 xs - (error 1) hostC:test0::state_test
157 730e151b 2025-06-02 xs - (error 1) - in hostB test0 state_test (1748622980)
158 730e151b 2025-06-02 xs - (error 1) - in hostC test0 state_test (1748622980)
162 fef9b495 2025-05-31 xs The last two lines are part of the `summary` output.
164 fef9b495 2025-05-31 xs Let's modify the `state_test` function again to add some verbosity to it's
167 fef9b495 2025-05-31 xs _Note that we also change the return value._
170 fef9b495 2025-05-31 xs state_test() {
171 fef9b495 2025-05-31 xs echo something
173 fef9b495 2025-05-31 xs echo >&2 failed
179 fef9b495 2025-05-31 xs This will produce the following summary:
182 730e151b 2025-06-02 xs - (error 22) - in hostB test0 state_test (1748622980)
187 730e151b 2025-06-02 xs - (error 22) - in hostC test0 state_test (1748622980)
193 fef9b495 2025-05-31 xs Diffs and permissions changes are also displayed by the `summary` command. When
194 fef9b495 2025-05-31 xs they're are detected, the captured related output is shown.
196 730e151b 2025-06-02 xs ### Repository initialisation
198 8e44e3d4 2025-06-25 xs Using the `init` command, we can specify the current or a specified
199 730e151b 2025-06-02 xs work directory to be created and act as an r7 repository.
201 8e44e3d4 2025-06-25 xs _Automated versioning of outputs are currently let to the user, a recommended
202 730e151b 2025-06-02 xs place would be the end of the site configuration file._
204 730e151b 2025-06-02 xs This command initializes a new directory called `test.org`:
207 730e151b 2025-06-02 xs r7 -w test.org init
211 730e151b 2025-06-02 xs Once this step is done, it is required to:
213 730e151b 2025-06-02 xs - Copy or initialize the ssh key to the `.ssh` folder in the repository created
214 730e151b 2025-06-02 xs in `.ssh/id_ed25519-r7` and `./ssh/id_ed25519-r7.pub`
216 730e151b 2025-06-02 xs - Adjust the SSH client configuration file in the repository `.ssh/config`
218 8e44e3d4 2025-06-25 xs _Note that it is possible to import additional SSH configurations, like the user
219 730e151b 2025-06-02 xs one from the SSH configuration, but it is advised to keep them separate._
221 730e151b 2025-06-02 xs ### SSH agent handling
223 8e44e3d4 2025-06-25 xs The function `unlock` can be used to set the SSH agent environment, this will
224 730e151b 2025-06-02 xs be required for any automated operation later done by r7:
228 730e151b 2025-06-02 xs . $(command -v r7) # Sourcing r7
230 730e151b 2025-06-02 xs tmux || screen
234 8e44e3d4 2025-06-25 xs #### Tmux configuration
237 8e44e3d4 2025-06-25 xs set -g update-environment -r
240 8e44e3d4 2025-06-25 xs #### Optional Shell configuration
242 8e44e3d4 2025-06-25 xs This is useful for handling multiple tmux sessions.
245 8e44e3d4 2025-06-25 xs # Add this to the shell's rc
246 8e44e3d4 2025-06-25 xs if [ -z "$TMUX" ]; then
247 8e44e3d4 2025-06-25 xs if [ -n "$SSH_TTY" ]; then
248 8e44e3d4 2025-06-25 xs if [ -z "$SSH_AUTH_SOCK" ]; then
249 8e44e3d4 2025-06-25 xs export SSH_AUTH_SOCK="$HOME/.ssh/.auth_socket"
251 8e44e3d4 2025-06-25 xs if [ ! -S "$SSH_AUTH_SOCK" ]; then
252 8e44e3d4 2025-06-25 xs eval $(ssh-agent -a $SSH_AUTH_SOCK) >/dev/null 2>&1
253 8e44e3d4 2025-06-25 xs echo $SSH_AGENT_PID >$HOME/.ssh/.auth_pid
255 8e44e3d4 2025-06-25 xs if [ -z $SSH_AGENT_PID ]; then
256 8e44e3d4 2025-06-25 xs export SSH_AGENT_PID=$(cat $HOME/.ssh/.auth_pid)
258 8e44e3d4 2025-06-25 xs ssh-add "$SSH_ID" 2>/dev/null
264 730e151b 2025-06-02 xs ### Adding new hosts
266 730e151b 2025-06-02 xs For adding a new host, the simplest way is to have pre-configured
267 730e151b 2025-06-02 xs `authorized_keys` for the target user, it is then required to add it to the
268 730e151b 2025-06-02 xs `known_hosts` file. For that, it is possible to use r7 SSH functions:
271 730e151b 2025-06-02 xs . $(command -v r7) # Sourcing r7
272 730e151b 2025-06-02 xs ssh-accept-new hostname
276 730e151b 2025-06-02 xs If resetting the target's user `authorized_keys` file is needed, the following
277 730e151b 2025-06-02 xs function can be used:
280 730e151b 2025-06-02 xs . $(command -v r7) # Sourcing r7
281 730e151b 2025-06-02 xs ssh-authorized-keys-reset hostname
284 730e151b 2025-06-02 xs _**Warning:** This will resets the SSH authorized_keys file for the target user
285 730e151b 2025-06-02 xs (root, by default) and put the `.ssh/id_ed25519-r7.pub` in place._
288 730e151b 2025-06-02 xs Once the host is accepted in the `known_hosts` file, it's possible to import it
289 730e151b 2025-06-02 xs automatically.
291 730e151b 2025-06-02 xs ### Importing hosts configurations
293 730e151b 2025-06-02 xs Avoiding to import the configuration manually is possible with the `import`
297 730e151b 2025-06-02 xs r7 import hostname
300 730e151b 2025-06-02 xs Most common configuration files will be copied in a newly created
301 730e151b 2025-06-02 xs `nodes/hostname` sub-directory.
303 730e151b 2025-06-02 xs ### Writing group files
305 8e44e3d4 2025-06-25 xs Group files collects functions related to the configuration of the operating
306 730e151b 2025-06-02 xs system, networking, services, global and user configurations packages
307 730e151b 2025-06-02 xs installations and application deployments.
309 730e151b 2025-06-02 xs By specifying the execution prefix, the user determines the order of execution
310 730e151b 2025-06-02 xs of the functions declared in the group file.
313 730e151b 2025-06-02 xs service_A() {
314 730e151b 2025-06-02 xs service A enable
315 730e151b 2025-06-02 xs service A restart
318 730e151b 2025-06-02 xs service_B() {
319 730e151b 2025-06-02 xs service B enable
320 730e151b 2025-06-02 xs service B restart
324 730e151b 2025-06-02 xs service A status
328 730e151b 2025-06-02 xs echo "## Service A"
330 730e151b 2025-06-02 xs echo "- [url](http://test.org/)"
335 730e151b 2025-06-02 xs _**file**: `groups/example1`_
337 8e44e3d4 2025-06-25 xs With the default prefix, `install`, `state`, `doc`, the function that will be
338 730e151b 2025-06-02 xs executed are `state_A` and `doc_A`. To test that group file with all the
339 730e151b 2025-06-02 xs functions inside we can call r7 the following way:
342 730e151b 2025-06-02 xs r7 -P 'service state doc' group example1 hostname
345 730e151b 2025-06-02 xs Or using the `-a` flag which will create a prefix automatically with all
346 730e151b 2025-06-02 xs functions present in the group file:
349 730e151b 2025-06-02 xs r7 -a group example1 hostname
352 730e151b 2025-06-02 xs In a real situation, this example will have failing functions because the
353 730e151b 2025-06-02 xs `service` command may not be found or the services named `A` or `B` does not
357 730e151b 2025-06-02 xs ! (error 127) tools0:example1::service_A
358 730e151b 2025-06-02 xs ! (error 127) tools0:example1::service_B
359 730e151b 2025-06-02 xs ! (error 127) tools0:example1::state_A
360 730e151b 2025-06-02 xs - (ok) tools0:example1::doc_A
363 730e151b 2025-06-02 xs We could force the group execution to stop using a combination of the `-e` flag
364 730e151b 2025-06-02 xs and the `error` group function.
367 730e151b 2025-06-02 xs service_A() {
368 730e151b 2025-06-02 xs service A enable &&
369 730e151b 2025-06-02 xs service A restart ||
370 730e151b 2025-06-02 xs error unable to setup service A
373 730e151b 2025-06-02 xs service_B() {
374 730e151b 2025-06-02 xs service B enable &&
375 730e151b 2025-06-02 xs service B restart ||
376 730e151b 2025-06-02 xs error unable to setup service B
380 730e151b 2025-06-02 xs service A status
384 730e151b 2025-06-02 xs echo "## Service A"
386 730e151b 2025-06-02 xs echo "- [url](http://test.org/)"
391 730e151b 2025-06-02 xs _**file:** `groups/example2`_
393 730e151b 2025-06-02 xs Let's run the updated example with the `-s` flag to trigger the summary output.
396 730e151b 2025-06-02 xs rm -fr _output
397 730e151b 2025-06-02 xs r7 -sea group example2 hostname
400 730e151b 2025-06-02 xs This will produce something like the following:
403 730e151b 2025-06-02 xs ! (error) tools0:example2::service_A
404 730e151b 2025-06-02 xs ! (exit) tools0:example2::service_A
405 730e151b 2025-06-02 xs - (error 127) - in tools0 example2 service_A (1748791986)
407 730e151b 2025-06-02 xs /bin/sh: <stdin>[155]: service: not found
408 688c9bfd 2025-06-03 xs :: 1748791986 tools0 ERROR unable to setup service A
412 e50b258b 2025-06-06 xs ### Cleaning functions
414 e50b258b 2025-06-06 xs To remove a function from a group, we need to ensure that this function returned
415 e50b258b 2025-06-06 xs 0 for the last execution.
418 e50b258b 2025-06-06 xs state_function_to_remove() {
420 e50b258b 2025-06-06 xs # not used anymore
425 e50b258b 2025-06-06 xs This would prevent for seeing potential past errors caused by this function in
426 e50b258b 2025-06-06 xs the summary output.
428 730e151b 2025-06-02 xs ### Using the r7 install functions
430 730e151b 2025-06-02 xs The group library comes with the following functions that will allow
431 730e151b 2025-06-02 xs installation of files and triggering actions if necessary: `install`,
432 730e151b 2025-06-02 xs `groupinstall`, `nodeinstall`. They are all shortcuts to an internal
433 730e151b 2025-06-02 xs `r7_install` function, it's just the wrappers changes directory to respectively
434 730e151b 2025-06-02 xs `/tmp/r7`, `/tmp/r7/groupname.dir/` and `/tmp/r7/hostname/`.
436 730e151b 2025-06-02 xs If we want to install files from the group directory we will use something like:
440 730e151b 2025-06-02 xs install_program() {
441 730e151b 2025-06-02 xs groupinstall -m 755 -o root:bin my_program /usr/local/bin
445 730e151b 2025-06-02 xs _We are supposing to have the file `groups/example3.dir/my_program`_
447 730e151b 2025-06-02 xs And if it's something from node, we should use:
450 730e151b 2025-06-02 xs install_program_config() {
451 730e151b 2025-06-02 xs nodeinstall -m 644 -o root:wheel my_config /etc
455 730e151b 2025-06-02 xs We can now chain the `install` functions to configuration checking and
456 730e151b 2025-06-02 xs initialization of programs, services or network features like in the following
457 730e151b 2025-06-02 xs example, in which we install `ntp.conf` from the deployed node directory to
461 730e151b 2025-06-02 xs service_ntpd() {
462 730e151b 2025-06-02 xs nodeinstall -m 644 -o root:wheel ntpd.conf /etc &&
464 730e151b 2025-06-02 xs rcctl enable ntpd &&
465 730e151b 2025-06-02 xs rcctl restart ntpd
469 730e151b 2025-06-02 xs ### Using the r7 node function
471 730e151b 2025-06-02 xs We may want to avoid executing a function or parts of it if the node has no
472 730e151b 2025-06-02 xs related files before executing the installation and actions handling parts. This
473 730e151b 2025-06-02 xs can be done with the help of the `node` function.
476 730e151b 2025-06-02 xs service_ntpd() {
477 730e151b 2025-06-02 xs node ntpd.conf &&
478 730e151b 2025-06-02 xs nodeinstall -m 644 -o root:wheel ntpd.conf /etc &&
480 730e151b 2025-06-02 xs rcctl enable ntpd &&
481 730e151b 2025-06-02 xs rcctl restart ntpd
485 730e151b 2025-06-02 xs Here, `node` will return `31` if there is no file or directory called
486 730e151b 2025-06-02 xs `ntpd.conf` inside the deployed node directory (`/tmp/r7/hostname`).
488 730e151b 2025-06-02 xs `0`, `30` and `31` exit codes are ignored when r7 will search for execution
489 730e151b 2025-06-02 xs errors. This means `30` and `31` exit code are reserved to r7.
491 730e151b 2025-06-02 xs In other terms, this will update the NTP daemon configuration only if
492 730e151b 2025-06-02 xs `ntpd.conf` is present in the node directory, otherwise it is kept by default,
493 730e151b 2025-06-02 xs which is the system provided default `ntpd.conf`.
495 730e151b 2025-06-02 xs ### Sourcing specific files
497 8e44e3d4 2025-06-25 xs Here's an example how to source additional shell from the deployed node
498 730e151b 2025-06-02 xs directory, or elsewhere:
501 730e151b 2025-06-02 xs service_sysrc() {
502 730e151b 2025-06-02 xs sysrc dumpdev=NO
503 730e151b 2025-06-02 xs sysrc kld_list="vmm if_tuntap if_bridge nmdm"
504 730e151b 2025-06-02 xs sysrc microcode_update_enable=YES
505 730e151b 2025-06-02 xs sysrc mountd_enable=YES
506 730e151b 2025-06-02 xs sysrc nfs_server_enable=YES
507 730e151b 2025-06-02 xs sysrc ntpdate_enable=YES
508 730e151b 2025-06-02 xs sysrc powerd_enable=YES
509 730e151b 2025-06-02 xs sysrc rcshutdown_timeout=900
510 730e151b 2025-06-02 xs sysrc rpcbind_enable=YES
511 730e151b 2025-06-02 xs sysrc sshd_enable=YES
512 730e151b 2025-06-02 xs sysrc zfs_enable=YES
513 0b6ecfa4 2025-06-03 xs nodesource sysrc.local
518 730e151b 2025-06-02 xs In this FreeBSD example, we configure the system RC globally with
519 730e151b 2025-06-02 xs `service_sysrc` which apply, if `sysrc.local` is found in the root of the node
520 730e151b 2025-06-02 xs directory, it's sourcing in the current scope via the help of `nodesource
521 730e151b 2025-06-02 xs sysrc.local`.
523 730e151b 2025-06-02 xs The file `nodes/hostname/sysrcl.local` contains the following:
526 730e151b 2025-06-02 xs sysrc ifconfig_igb0=DHCP
527 730e151b 2025-06-02 xs sysrc ifconfig_igb1=up
530 730e151b 2025-06-02 xs ### Other examples
532 35f45d45 2025-06-04 xs Inside the r7 release, a small example groups library can be found in the
533 35f45d45 2025-06-04 xs `groups` directory, that can also be browsed in the
534 35f45d45 2025-06-04 xs [repository](https://got.inda.re/?action=summary&path=r7.git).
536 730e151b 2025-06-02 xs #### System shell profile
538 730e151b 2025-06-02 xs Here we install the `profile` file provided in the `groupname.dir` directory or
539 730e151b 2025-06-02 xs the profile provided by the node directory:
542 730e151b 2025-06-02 xs setup_profile() {
543 730e151b 2025-06-02 xs groupinstall -m 644 -o root:wheel profile /etc
544 730e151b 2025-06-02 xs node profile &&
545 730e151b 2025-06-02 xs nodeinstall -m 644 -o root:wheel profile /etc
551 730e151b 2025-06-02 xs Here we add new users:
554 730e151b 2025-06-02 xs setup_users() {
555 688c9bfd 2025-06-03 xs useradd user1 2>/dev/null || :
556 688c9bfd 2025-06-03 xs useradd user2 2>/dev/null || :
562 730e151b 2025-06-02 xs In the following example, we install a script and call it from a dedicated user crontab.
565 730e151b 2025-06-02 xs mail_admins=admins@test.org
567 730e151b 2025-06-02 xs install_myscript() {
568 730e151b 2025-06-02 xs groupinstall -o root:bin -m 755 myscript /usr/local/bin &&
569 730e151b 2025-06-02 xs useradd -d /var/empty -s /sbin/nologin _myscript
570 730e151b 2025-06-02 xs crontab -u _myscript - <<-/
571 730e151b 2025-06-02 xs MAILTO=$mail_admins
572 730e151b 2025-06-02 xs */5 * * * * myscript
577 730e151b 2025-06-02 xs ### Consulting the output
579 730e151b 2025-06-02 xs After the execution is done, the result are saved in the `_run` directory,
580 730e151b 2025-06-02 xs `output-dump` needs to be called to produce the current `_output` structure.
582 730e151b 2025-06-02 xs The r7 `output` command can then be used to show specific output groups or functions:
588 730e151b 2025-06-02 xs Will show the whole output of the latest groups deployments.
590 730e151b 2025-06-02 xs This format can be used to match specific host, group or function:
593 730e151b 2025-06-02 xs r7 output [hostname [groupname [funcname]]]
599 730e151b 2025-06-02 xs $ r7 output tools0 OpenBSD state_packages\*
600 730e151b 2025-06-02 xs - tools0 OpenBSD state_packages_upgrades
602 730e151b 2025-06-02 xs quirks-7.103 signed on 2025-05-30T01:12:03Z
604 730e151b 2025-06-02 xs - tools0 OpenBSD state_packages_repository
606 730e151b 2025-06-02 xs https://cdn.openbsd.org/pub/OpenBSD
609 8e44e3d4 2025-06-25 xs _Note that the `output` function arguments are using shell's case glob patterns._
611 494d76b7 2025-06-10 xs ### Active nodes
613 494d76b7 2025-06-10 xs A `R7_WORKDIR/.active_nodes` file is automatically created when r7 tries to
614 494d76b7 2025-06-10 xs connect to a list of hosts via the `group` command or function. This serves as a
615 494d76b7 2025-06-10 xs cache of available hosts reachable via SSH login (the username is specified in
616 494d76b7 2025-06-10 xs the SSH configuration file).
618 494d76b7 2025-06-10 xs To add a previously non-available host, simply remove the file and use `group`
619 494d76b7 2025-06-10 xs (here via `run-config`):
622 494d76b7 2025-06-10 xs rm .active_nodes
623 494d76b7 2025-06-10 xs r7 run-config
626 fef9b495 2025-05-31 xs ## r7 command line
630 fef9b495 2025-05-31 xs r7 [options] [command [arguments...]]
636 fef9b495 2025-05-31 xs Show usage and exit
639 fef9b495 2025-05-31 xs Enable debug mode
642 fef9b495 2025-05-31 xs Specify the SSH identity file
645 fef9b495 2025-05-31 xs Specify the SSH client configuration file
648 fef9b495 2025-05-31 xs Set the work directory where `./nodes` and `./groups` can be found
651 fef9b495 2025-05-31 xs Set the run directory (default: `./_run`)
654 fef9b495 2025-05-31 xs Set the output directory (default: `./_output`)
657 fef9b495 2025-05-31 xs Specify the site configuration file (default: `./site-config`)
660 fef9b495 2025-05-31 xs Enable dry run mode; prevents any modification on hosts
663 730e151b 2025-06-02 xs Exit the group execution on the error function
666 fef9b495 2025-05-31 xs Run each host in parallel per group call
669 fef9b495 2025-05-31 xs Show output interactively
672 4296d94d 2025-06-07 xs Specify a prefix, can contain whole function names
675 fef9b495 2025-05-31 xs Select all available prefixes for a group command
678 fef9b495 2025-05-31 xs Apply output-dump and summary after a group command
682 f6bdfddc 2025-06-03 xs | Name | Description |
683 f6bdfddc 2025-06-03 xs | ---- | ----------- |
684 f6bdfddc 2025-06-03 xs | **run-config** | Run the site configuration |
685 f6bdfddc 2025-06-03 xs | **group** | Deploy specified group to hosts |
686 f6bdfddc 2025-06-03 xs | **output-dump** | Dump the run directory to the output directory |
687 f6bdfddc 2025-06-03 xs | **output** | Consult the output |
688 f6bdfddc 2025-06-03 xs | **summary** | Produce a summary of errors and changes |
689 f6bdfddc 2025-06-03 xs | **digraph-host** | Produce a dot digraph for hosts |
690 f6bdfddc 2025-06-03 xs | **digraph-ssh** | Produce a dot digraph of SSH ID's, users and nodes relations |
691 f6bdfddc 2025-06-03 xs | **import** | Import TARGET host in the current nodes directory |
692 f6bdfddc 2025-06-03 xs | **info** | Default command showing active nodes and summary |
693 f6bdfddc 2025-06-03 xs | **init** | Initialize a new work directory |
695 688c9bfd 2025-06-03 xs ## Environment
697 f6bdfddc 2025-06-03 xs | Name | Default value | Description |
698 f6bdfddc 2025-06-03 xs | ---- | ------------- | ------------|
699 f6bdfddc 2025-06-03 xs | R7_DEBUG | no | Enable debug mode |
700 f6bdfddc 2025-06-03 xs | R7_DRYRUN | no | Enable dry-run mode |
701 f6bdfddc 2025-06-03 xs | R7_GROUP_ALLPREFIX | no | Group selects all available prefix |
702 f6bdfddc 2025-06-03 xs | R7_GROUP_SUMMARY | no | Enable output-dump and summary after group execution |
703 f6bdfddc 2025-06-03 xs | R7_GROUP_EXITONERROR | no | Enable exit on error function |
704 f6bdfddc 2025-06-03 xs | R7_PARALLEL | no | Enable group nodes parallel execution |
705 f6bdfddc 2025-06-03 xs | R7_PREFIX | install state doc | Set the r7 group execution prefix |
706 f6bdfddc 2025-06-03 xs | R7_SHOWOUTPUT | no | Show interactive output |
707 f6bdfddc 2025-06-03 xs | R7_WORKDIR | PWD | Set the r7 repository path |
708 f6bdfddc 2025-06-03 xs | R7_SITE_CONFIG | R7_WORKDIR/site-config | Set the r7 `site-config` path |
709 f6bdfddc 2025-06-03 xs | R7_OUTPUTDIR | R7_WORKDIR/_output | Set the r7 output directory path |
710 f6bdfddc 2025-06-03 xs | SSH_CONFIG_DIR | R7_WORKDIR/.ssh | Set the SSH configuration directory path |
711 f6bdfddc 2025-06-03 xs | SSH_CONFIG_FILE | R7_WORKDIR/.ssh/config | Set the SSH configuration file path |
712 f6bdfddc 2025-06-03 xs | SSH_CONTROL_DIR | SSH_CONFIG_DIR/control | Set the SSH control dir path |
713 f6bdfddc 2025-06-03 xs | SSH_IDENTITY_FILE | R7_WORKDIR/.ssh/id_ed25519_r7 | Set the SSH identity file |
714 f6bdfddc 2025-06-03 xs | SSH_KNOWN_HOSTS | R7_WORKDIR/.ssh/known_hosts | Set the SSH known hosts file |
715 f6bdfddc 2025-06-03 xs | SSH_CONNECT_TIMEOUT | 3 | Set the SSH connect timeout |
718 688c9bfd 2025-06-03 xs ## Group variables
720 688c9bfd 2025-06-03 xs Those variables are available during the execution of th group file's functions.
722 688c9bfd 2025-06-03 xs | Name | Description |
723 688c9bfd 2025-06-03 xs | ---- | ----------- |
724 688c9bfd 2025-06-03 xs | trace_id | Current run trace ID |
725 688c9bfd 2025-06-03 xs | groupname | Current group name being executed |
726 688c9bfd 2025-06-03 xs | exitonerror | Cause the error function to exit if equals `yes` |
727 688c9bfd 2025-06-03 xs | nodename | Contains the output of `nodename` |
728 688c9bfd 2025-06-03 xs | nodedir | Contains the output of `nodedir` |
729 688c9bfd 2025-06-03 xs | groupdir | Contains the output of `groupdir` |
732 730e151b 2025-06-02 xs ## Group functions
734 730e151b 2025-06-02 xs Those functions are accessible during the execution of the group file's functions.
735 22b54c5e 2025-06-04 xs Non documented functions are reserved for internal use.
737 730e151b 2025-06-02 xs 1. [trace](#trace)
738 730e151b 2025-06-02 xs 2. [error](#error)
739 730e151b 2025-06-02 xs 3. [node](#node)
740 730e151b 2025-06-02 xs 4. [nodename](#nodename)
741 730e151b 2025-06-02 xs 5. [nodedir](#nodedir)
742 730e151b 2025-06-02 xs 6. [groupdir](#groupdir)
743 730e151b 2025-06-02 xs 7. [install](#install)
744 730e151b 2025-06-02 xs 8. [groupinstall](#groupinstall)
745 730e151b 2025-06-02 xs 9. [nodeinstall](#nodeinstall)
746 3aa5672d 2025-06-04 xs 10. [installdir](#installdir)
747 3aa5672d 2025-06-04 xs 11. [groupinstalldir](#groupinstalldir)
748 3aa5672d 2025-06-04 xs 12. [nodeinstalldir](#nodeinstalldir)
749 3aa5672d 2025-06-04 xs 13. [source](#source)
750 3aa5672d 2025-06-04 xs 14. [groupsource](#groupsource)
751 3aa5672d 2025-06-04 xs 15. [nodesource](#groupsource)
752 6e564797 2025-06-06 xs 16. [template](#template)
753 6e564797 2025-06-06 xs 17. [grouptemplate](#grouptemplate)
754 6e564797 2025-06-06 xs 18. [nodetemplate](#nodetemplate)
760 730e151b 2025-06-02 xs ***Description:***
761 f6bdfddc 2025-06-03 xs Append a trace containing the current node name and `trace_id`
765 730e151b 2025-06-02 xs trace [string...]
770 730e151b 2025-06-02 xs ***Description:***
771 730e151b 2025-06-02 xs Trace an error message that will inform the user of an event in the summary
772 730e151b 2025-06-02 xs output, exit the group execution if `-e` is set
776 730e151b 2025-06-02 xs error [string...]
781 730e151b 2025-06-02 xs ***Description:***
782 f6bdfddc 2025-06-03 xs Returns true if the argument is an existing file or directory inside `/tmp/r7/$(nodename)`, else, returns 31
786 730e151b 2025-06-02 xs node [filename|dirname]
791 730e151b 2025-06-02 xs ***Description:***
792 8e44e3d4 2025-06-25 xs Returns the small host name of the current host
801 730e151b 2025-06-02 xs ***Description:***
802 730e151b 2025-06-02 xs Returns `/tmp/r7/$(nodename)`
811 730e151b 2025-06-02 xs ***Description:***
812 730e151b 2025-06-02 xs Returns `/tmp/r7/$groupname.dir`
821 730e151b 2025-06-02 xs ***Description:***
822 730e151b 2025-06-02 xs Change directory to `/tmp/r7` and install files if changed and sets mode and
823 f6bdfddc 2025-06-03 xs owner, returns true if the file changed, otherwise returns 30
827 730e151b 2025-06-02 xs install [-o owner] [-m mode] source destintaion
830 730e151b 2025-06-02 xs ### groupinstall
832 730e151b 2025-06-02 xs ***Description:***
833 730e151b 2025-06-02 xs Change directory to the current group `.dir` directory in `/tmp/r7` then
834 730e151b 2025-06-02 xs performs like `install`
838 730e151b 2025-06-02 xs groupinstall [-o owner] [-m mode] source destintaion
841 730e151b 2025-06-02 xs ### nodeinstall
843 730e151b 2025-06-02 xs ***Description:***
844 730e151b 2025-06-02 xs Change directory to the current node directory in `/tmp/r7` then
845 730e151b 2025-06-02 xs performs like `install`
849 730e151b 2025-06-02 xs nodeinstall [-o owner] [-m mode] source destintaion
852 3aa5672d 2025-06-04 xs ### installdir
854 3aa5672d 2025-06-04 xs ***Description:***
855 3aa5672d 2025-06-04 xs Install directory calling `install` for each file and checking for permissions
860 3aa5672d 2025-06-04 xs installdir [-o fileowner] [-m filemode] [-O dirowner] [-O dirmode] source
864 3aa5672d 2025-06-04 xs ### groupinstalldir
866 3aa5672d 2025-06-04 xs ***Description:***
867 8e44e3d4 2025-06-25 xs Change directory to the current group directory then call installdir
871 3aa5672d 2025-06-04 xs groupinstalldir [-o fileowner] [-m filemode] [-O dirowner] [-O dirmode] source
875 3aa5672d 2025-06-04 xs ### nodeinstalldir
877 3aa5672d 2025-06-04 xs ***Description:***
878 8e44e3d4 2025-06-25 xs Change directory to the current group directory then call installdir
882 3aa5672d 2025-06-04 xs nodeinstalldir [-o fileowner] [-m filemode] [-O dirowner] [-O dirmode] source
888 730e151b 2025-06-02 xs ***Description:***
889 730e151b 2025-06-02 xs Source a POSIX shell file in the current execution
894 8e44e3d4 2025-06-25 xs fsource filename
897 730e151b 2025-06-02 xs ### groupsource
899 730e151b 2025-06-02 xs ***Description:***
900 09bfe2aa 2025-06-25 xs Change directory to the current group directory then call fsource with the file
901 730e151b 2025-06-02 xs name as argument, produces an error if filename is not found from the group
906 730e151b 2025-06-02 xs groupsource filename
909 730e151b 2025-06-02 xs ### nodesource
911 730e151b 2025-06-02 xs ***Description:***
912 09bfe2aa 2025-06-25 xs Change directory to the current group directory then call node and fsource with the file
913 730e151b 2025-06-02 xs name as argument without producing an error if the filename is not found
917 730e151b 2025-06-02 xs nodesource filename
922 6e564797 2025-06-06 xs ***Description:***
923 6e564797 2025-06-06 xs Template the files passed as arguments with the current environment or by
924 6e564797 2025-06-06 xs sourcing a specified file
928 6e564797 2025-06-06 xs template [-s sourcefile] [file...]
931 6e564797 2025-06-06 xs ### grouptemplate
933 6e564797 2025-06-06 xs ***Description:***
934 6e564797 2025-06-06 xs Change directory to the current group directory before calling template
938 6e564797 2025-06-06 xs grouptemplate [-s sourcefile] [file...]
941 6e564797 2025-06-06 xs ### nodetemplate
943 6e564797 2025-06-06 xs ***Description:***
944 6e564797 2025-06-06 xs Change directory to the current node directory before calling template
948 6e564797 2025-06-06 xs nodetemplate [-s sourcefile] [file...]
953 688c9bfd 2025-06-03 xs Usable from the r7 `site-config` file or sourced in the current shell using:
956 688c9bfd 2025-06-03 xs . $(command -v r7)
959 688c9bfd 2025-06-03 xs Each functions are declared with underscore names and aliased with dashes.
960 688c9bfd 2025-06-03 xs Shorter aliases are also available, list all declared aliases with:
966 22b54c5e 2025-06-04 xs Non documented functions are reserved for internal use.
970 fef9b495 2025-05-31 xs 1. [info](#info)
971 fef9b495 2025-05-31 xs 2. [usage](#usage)
977 fef9b495 2025-05-31 xs ***Description:***
978 fef9b495 2025-05-31 xs Default command showing active nodes and summary, ran when sourced
987 fef9b495 2025-05-31 xs ***Description:***
988 fef9b495 2025-05-31 xs Shows the command line help
995 fef9b495 2025-05-31 xs ## SSH functions
997 fef9b495 2025-05-31 xs 1. [unlock](#unlock)
998 fef9b495 2025-05-31 xs 2. [copy](#copy)
999 fef9b495 2025-05-31 xs 3. [ssh](#ssh)
1000 fef9b495 2025-05-31 xs 4. [ssh-debug](#ssh-debug)
1001 fef9b495 2025-05-31 xs 5. [ssh-known-hosts](#ssh-known-hosts)
1002 fef9b495 2025-05-31 xs 6. [ssh-authorized-keys-reset](#ssh-authorized-keys-reset)
1003 fef9b495 2025-05-31 xs 7. [ssh-accept-new](#ssh-accept-new)
1004 fef9b495 2025-05-31 xs 8. [ssh-control-master-clean](#ssh-control-master-clean)
1005 fef9b495 2025-05-31 xs 9. [ssh-users](#ssh-users)
1006 fef9b495 2025-05-31 xs 10. [ssh-ids](#ssh-ids)
1007 fef9b495 2025-05-31 xs 11. [ssh-authorized-keys](#ssh-authorized-keys)
1008 fef9b495 2025-05-31 xs 12. [ssh-ids-hosts](#ssh-ids-hosts)
1014 fef9b495 2025-05-31 xs ***Description:***
1015 fef9b495 2025-05-31 xs Resets the SSH agent environment and issues ssh-add for SSH_IDENTITY_FILE
1017 fef9b495 2025-05-31 xs ***Usage:***
1024 fef9b495 2025-05-31 xs ***Description:***
1025 fef9b495 2025-05-31 xs r7 openrsync, rsync, scp wrapper; selected in order of availability
1027 fef9b495 2025-05-31 xs ***Usage:***
1029 fef9b495 2025-05-31 xs copy SRC DST
1034 fef9b495 2025-05-31 xs ***Description:***
1035 fef9b495 2025-05-31 xs r7 SSH wrapper; behaves like the standard OpenSSH command
1037 fef9b495 2025-05-31 xs ***Usage:***
1039 fef9b495 2025-05-31 xs ssh OPTION HOST
1042 fef9b495 2025-05-31 xs ### ssh-debug
1044 fef9b495 2025-05-31 xs ***Description:***
1045 fef9b495 2025-05-31 xs r7 SSH with debug connection mode for a specific HOST
1047 fef9b495 2025-05-31 xs ***Usage:***
1049 fef9b495 2025-05-31 xs ssh-debug HOST
1052 fef9b495 2025-05-31 xs ### ssh-known-hosts
1054 fef9b495 2025-05-31 xs ***Description:***
1055 fef9b495 2025-05-31 xs Calls ssh-keygen to dump the SSH known_hosts file
1057 fef9b495 2025-05-31 xs ***Usage:***
1059 fef9b495 2025-05-31 xs ssh-known-hosts
1062 fef9b495 2025-05-31 xs ### ssh-authorized-keys-reset
1064 fef9b495 2025-05-31 xs ***Description:***
1065 fef9b495 2025-05-31 xs Resets SSH authorized_keys on the specified HOST
1067 fef9b495 2025-05-31 xs ***Usage:***
1069 fef9b495 2025-05-31 xs ssh-authorized-keys-reset HOST
1072 fef9b495 2025-05-31 xs ### ssh-accept-new
1074 fef9b495 2025-05-31 xs ***Description:***
1075 fef9b495 2025-05-31 xs Adds a new host entry in the SSH known_hosts file
1077 fef9b495 2025-05-31 xs ***Usage:***
1079 fef9b495 2025-05-31 xs ssh-accept-new HOST
1082 fef9b495 2025-05-31 xs ### ssh-control-master-clean
1084 fef9b495 2025-05-31 xs ***Description:***
1085 fef9b495 2025-05-31 xs Cleans the SSH control master directory
1087 fef9b495 2025-05-31 xs ***Usage:***
1089 fef9b495 2025-05-31 xs ssh-control-master-clean
1092 fef9b495 2025-05-31 xs ### ssh-users
1094 fef9b495 2025-05-31 xs ***Description:***
1095 fef9b495 2025-05-31 xs Searches nodes for authorized_keys_* and returns a list of users
1097 fef9b495 2025-05-31 xs ***Usage:***
1104 fef9b495 2025-05-31 xs ***Description:***
1105 fef9b495 2025-05-31 xs Returns sorted SSH IDs
1107 fef9b495 2025-05-31 xs ***Usage:***
1112 fef9b495 2025-05-31 xs ### ssh-authorized-keys
1114 fef9b495 2025-05-31 xs ***Description:***
1115 fef9b495 2025-05-31 xs Returns the list of authorized_keys from nodes
1117 fef9b495 2025-05-31 xs ***Usage:***
1119 fef9b495 2025-05-31 xs ssh-authorized-keys
1122 fef9b495 2025-05-31 xs ### ssh-ids-hosts
1124 fef9b495 2025-05-31 xs ***Description:***
1125 8e44e3d4 2025-06-25 xs Returns SSH IDs along with matching key file and host name
1127 fef9b495 2025-05-31 xs ***Usage:***
1129 fef9b495 2025-05-31 xs ssh-ids-hosts
1132 fef9b495 2025-05-31 xs ## Deployment functions
1134 fef9b495 2025-05-31 xs 1. [nodes](#nodes)
1135 fef9b495 2025-05-31 xs 2. [nodes-active](#nodes-active)
1136 fef9b495 2025-05-31 xs 3. [run-config](#run-config)
1137 fef9b495 2025-05-31 xs 4. [members](#members)
1138 fef9b495 2025-05-31 xs 5. [group](#group)
1139 fef9b495 2025-05-31 xs 6. [group-functions](#group-functions)
1140 8fe13599 2025-06-05 xs 7. [group-functions-all](#group-functions-all)
1141 8fe13599 2025-06-05 xs 8. [prefix](#prefix)
1147 fef9b495 2025-05-31 xs ***Description:***
1148 fef9b495 2025-05-31 xs Returns a list of available nodes
1150 fef9b495 2025-05-31 xs ***Usage:***
1155 fef9b495 2025-05-31 xs ### nodes-active
1157 fef9b495 2025-05-31 xs ***Description:***
1158 494d76b7 2025-06-10 xs Returns a list of active nodes by detecting SSH availability (a login is done), writes
1159 494d76b7 2025-06-10 xs `R7_WORKDIR/.active_nodes` containing the available hosts
1161 fef9b495 2025-05-31 xs ***Usage:***
1163 fef9b495 2025-05-31 xs nodes-active
1166 fef9b495 2025-05-31 xs ### run-config
1168 fef9b495 2025-05-31 xs ***Description:***
1169 f6bdfddc 2025-06-03 xs Executes `R7_SITE_CONFIG` in the loaded environment
1171 fef9b495 2025-05-31 xs ***Usage:***
1178 fef9b495 2025-05-31 xs ***Description:***
1179 f6bdfddc 2025-06-03 xs Returns a list of active nodes matching a list of grep REGEXES
1181 fef9b495 2025-05-31 xs ***Usage:***
1183 fef9b495 2025-05-31 xs members REGEXES
1188 fef9b495 2025-05-31 xs ***Description:***
1189 fef9b495 2025-05-31 xs Applies GROUPNAME functions (in prefix order) to the provided MEMBERS list
1191 fef9b495 2025-05-31 xs ***Usage:***
1193 fef9b495 2025-05-31 xs group GROUPNAME MEMBERS
1196 fef9b495 2025-05-31 xs ### group-functions
1198 fef9b495 2025-05-31 xs ***Description:***
1199 fef9b495 2025-05-31 xs Returns a list of functions found in the specified GROUPNAME
1201 fef9b495 2025-05-31 xs ***Usage:***
1203 fef9b495 2025-05-31 xs group-functions GROUPNAME
1206 8fe13599 2025-06-05 xs ### group-functions-all
1208 8fe13599 2025-06-05 xs ***Description:***
1209 8fe13599 2025-06-05 xs Returns a list of all group functions found in the current `R7_WORKDIR/groups`
1210 8fe13599 2025-06-05 xs directory with the `group_name::function_name` format
1212 8fe13599 2025-06-05 xs ***Usage:***
1215 8fe13599 2025-06-05 xs group-functions-all
1221 fef9b495 2025-05-31 xs ***Description:***
1222 4296d94d 2025-06-07 xs Sets the current PREFIX for matching function names, can match for the whole
1223 4296d94d 2025-06-07 xs unique name in the group, for executing one specified function only
1225 fef9b495 2025-05-31 xs ***Usage:***
1227 fef9b495 2025-05-31 xs prefix PREFIX
1230 fef9b495 2025-05-31 xs ## Text output functions
1232 fef9b495 2025-05-31 xs 1. [output-dump](#output-dump)
1233 fef9b495 2025-05-31 xs 2. [output-latest](#output-latest)
1234 fef9b495 2025-05-31 xs 3. [output-status](#output-status)
1235 fef9b495 2025-05-31 xs 4. [output-duration](#output-duration)
1236 fef9b495 2025-05-31 xs 5. [output](#output)
1237 730e151b 2025-06-02 xs 6. [output-diffs](#output-diffs)
1238 730e151b 2025-06-02 xs 7. [output-permissions](#output-permissions)
1239 730e151b 2025-06-02 xs 8. [output-errors](#output-errors)
1240 730e151b 2025-06-02 xs 9. [summary](#summary)
1241 730e151b 2025-06-02 xs 10. [trace-id-last](#trace-id-last)
1245 fef9b495 2025-05-31 xs ### output-dump
1247 fef9b495 2025-05-31 xs ***Description:***
1248 fef9b495 2025-05-31 xs Dumps R7_RUNDIR to R7_OUTPUTDIR
1250 fef9b495 2025-05-31 xs ***Usage:***
1255 fef9b495 2025-05-31 xs ### output-latest
1257 fef9b495 2025-05-31 xs ***Description:***
1258 fef9b495 2025-05-31 xs Returns a list of outputs from the latest run
1260 fef9b495 2025-05-31 xs ***Usage:***
1262 fef9b495 2025-05-31 xs output-latest
1265 fef9b495 2025-05-31 xs ### output-status
1267 fef9b495 2025-05-31 xs ***Description:***
1268 fef9b495 2025-05-31 xs Returns a list of current dumped functions exit status codes
1270 fef9b495 2025-05-31 xs ***Usage:***
1272 fef9b495 2025-05-31 xs output-status
1275 fef9b495 2025-05-31 xs ### output-duration
1277 fef9b495 2025-05-31 xs ***Description:***
1278 fef9b495 2025-05-31 xs Returns a list of durations of executed groups
1280 fef9b495 2025-05-31 xs ***Usage:***
1282 fef9b495 2025-05-31 xs output-duration
1287 fef9b495 2025-05-31 xs ***Description:***
1288 fef9b495 2025-05-31 xs Shows the dumped output matching HOST, GROUPNAME, and FUNCTION (or any if unspecified)
1290 fef9b495 2025-05-31 xs ***Usage:***
1292 fef9b495 2025-05-31 xs output HOST GROUPNAME FUNCTION
1295 fef9b495 2025-05-31 xs ### trace-id-last
1297 fef9b495 2025-05-31 xs ***Description:***
1298 fef9b495 2025-05-31 xs Returns the latest execution trace_id
1300 fef9b495 2025-05-31 xs ***Usage:***
1302 fef9b495 2025-05-31 xs trace-id-last
1305 fef9b495 2025-05-31 xs ### output-diffs
1307 fef9b495 2025-05-31 xs ***Description:***
1308 fef9b495 2025-05-31 xs Returns the diffs from the latest execution
1310 fef9b495 2025-05-31 xs ***Usage:***
1312 fef9b495 2025-05-31 xs output-diffs
1315 fef9b495 2025-05-31 xs ### output-permissions
1317 fef9b495 2025-05-31 xs ***Description:***
1318 fef9b495 2025-05-31 xs Returns the latest permission changes
1320 fef9b495 2025-05-31 xs ***Usage:***
1322 fef9b495 2025-05-31 xs output-permissions
1325 fef9b495 2025-05-31 xs ### output-errors
1327 fef9b495 2025-05-31 xs ***Description:***
1328 fef9b495 2025-05-31 xs Returns the latest errors detected
1330 fef9b495 2025-05-31 xs ***Usage:***
1332 fef9b495 2025-05-31 xs output-errors
1337 fef9b495 2025-05-31 xs ***Description:***
1338 fef9b495 2025-05-31 xs Produces a summary of errors, diffs, and permission outputs
1340 fef9b495 2025-05-31 xs ***Usage:***
1345 fef9b495 2025-05-31 xs ## Digraph output
1347 fef9b495 2025-05-31 xs 1. [digraph-host](#digraph-host)
1348 fef9b495 2025-05-31 xs 2. [digraph-ssh-id-hosts](#digraph-ssh-id-hosts)
1352 fef9b495 2025-05-31 xs ### digraph-host
1354 fef9b495 2025-05-31 xs ***Description:***
1355 fef9b495 2025-05-31 xs Returns a directed graph (in DOT format) showing relations among groups, functions, and nodes
1357 fef9b495 2025-05-31 xs ***Usage:***
1359 fef9b495 2025-05-31 xs digraph-host
1362 fef9b495 2025-05-31 xs ### digraph-ssh-id-hosts
1364 fef9b495 2025-05-31 xs ***Description:***
1365 fef9b495 2025-05-31 xs Returns a directed graph (in DOT format) of relations between SSH IDs and hosts
1367 fef9b495 2025-05-31 xs ***Usage:***
1369 fef9b495 2025-05-31 xs digraph-ssh-id-hosts
1372 730e151b 2025-06-02 xs ## HTML output
1374 730e151b 2025-06-02 xs 1. [html](#html)
1378 730e151b 2025-06-02 xs ***Description:***
1379 f6bdfddc 2025-06-03 xs Retunrs a report page with the content of `README.md` in HTML format
1381 730e151b 2025-06-02 xs ***Usage:***
1388 3aa5672d 2025-06-04 xs ## Node importing
1390 3aa5672d 2025-06-04 xs 1. [import](#import)
1394 3aa5672d 2025-06-04 xs ***Description:***
1395 3aa5672d 2025-06-04 xs Import configuration files from a target host
1397 3aa5672d 2025-06-04 xs ***Usage:***
1404 688c9bfd 2025-06-03 xs ## Technical notes
1406 8e44e3d4 2025-06-25 xs - Supported shells are ksh93, oksh, yash and bash
1407 8e44e3d4 2025-06-25 xs - Supported target platforms are POSIX compatible systems
1408 8e44e3d4 2025-06-25 xs - `/bin/sh` or compatible must be set for the user's shell (which is
1409 8e44e3d4 2025-06-25 xs usually the case by default)
1410 8e44e3d4 2025-06-25 xs - `/tmp` must be writable by the user
1411 8e44e3d4 2025-06-25 xs - Supported control node platforms are supposed to be POSIX compatible systems
1412 8e44e3d4 2025-06-25 xs but currently limited to BSD's, Darwin and GNU/Linux
1413 8e44e3d4 2025-06-25 xs - Dependencies are awk, OpenSSH and column
1414 8e44e3d4 2025-06-25 xs - Optional dependencies are openrsync, rsync, column, graphviz and pandoc
1415 e4821e59 2025-06-25 xs - The r7 importer supports the following platforms:
1416 8e44e3d4 2025-06-25 xs - Alpine Linux
1420 8e44e3d4 2025-06-25 xs - DragonFlyBSD
1431 8e44e3d4 2025-06-25 xs - Rocky Linux
1433 8e44e3d4 2025-06-25 xs - Void Linux
1439 8e44e3d4 2025-06-25 xs The provided group library is shared as additional examples WITH NO WARRANTIES of the
1440 f976c0b3 2025-06-05 xs documentation and contain the following third-party files under the ISC License.
1441 f976c0b3 2025-06-05 xs Copyright information are indicated in the LICENSE section of related files.
1443 f976c0b3 2025-06-05 xs - `pf-badhost.sh`
1444 f976c0b3 2025-06-05 xs - `unbound-adblock.sh`
1445 f976c0b3 2025-06-05 xs - `http-ban.sh`
1447 8b145b67 2025-06-04 xs The project is shared under the terms of the ISC license. Any version previous
1448 8b145b67 2025-06-04 xs `0.1.0` needs to be considered obsolete and should not be redistributed. History
1449 8b145b67 2025-06-04 xs in the GIT repository is kept for transparency purpose only.
1451 8b145b67 2025-06-04 xs Below is a copy of the applicable license:
1455 8b145b67 2025-06-04 xs Copyright 2025 xs <xs@inda.re>
1457 8b145b67 2025-06-04 xs Permission to use, copy, modify, and/or distribute this software for any
1458 8b145b67 2025-06-04 xs purpose with or without fee is hereby granted, provided that the above
1459 8b145b67 2025-06-04 xs copyright notice and this permission notice appear in all copies.
1461 8b145b67 2025-06-04 xs THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
1462 8b145b67 2025-06-04 xs REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
1463 8b145b67 2025-06-04 xs FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
1464 8b145b67 2025-06-04 xs INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
1465 8b145b67 2025-06-04 xs LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
1466 8b145b67 2025-06-04 xs OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1467 8b145b67 2025-06-04 xs PERFORMANCE OF THIS SOFTWARE.
