2 35f45d45 2025-06-04 xs .\" Automatically generated by Pandoc 3.6.2
4 da6cbc9d 2025-06-05 xs .TH "R7" "1" "Tue Jun 3 2025" "v0.1.3" "User Manual"
6 35f45d45 2025-06-04 xs .SS Introduction
7 35f45d45 2025-06-04 xs R7 is a configuration management framework made to configure nodes with
8 35f45d45 2025-06-04 xs configuration files and related operations versionned in a central
10 35f45d45 2025-06-04 xs To remain code versionning system agnostic, manual or automated
11 35f45d45 2025-06-04 xs versionning is left to the user, via makefiles or triggered from r7
12 35f45d45 2025-06-04 xs \f[CR]site\-config\f[R] configuration file \f[I](See below)\f[R].
14 35f45d45 2025-06-04 xs The idea is to store hosts configurations in \f[CR]nodes/hostname\f[R]
15 35f45d45 2025-06-04 xs directories that maps each host\[cq]s \f[CR]/etc\f[R] and to assign
16 35f45d45 2025-06-04 xs those hosts to configuration groups containing the directives to install
17 35f45d45 2025-06-04 xs the configuration and potential requirements.
19 35f45d45 2025-06-04 xs \f[I]Nodes sub\-directories are hostnames understood by the ssh client
20 35f45d45 2025-06-04 xs and configuration.\f[R]
22 35f45d45 2025-06-04 xs \f[I]Currently, r7 requires valid ssh configuration and keyfiles in the
23 35f45d45 2025-06-04 xs repository \f[CI].ssh/\f[I] directory.\f[R]
25 35f45d45 2025-06-04 xs \f[I]Repositories can be initialized with \f[CI]rset init\f[I] or
26 35f45d45 2025-06-04 xs \f[CI]rset \-w path/to/new\-repository init\f[I], the user will then
27 35f45d45 2025-06-04 xs have to provide valid configurations and keys for \f[CI].ssh/\f[I] in
28 35f45d45 2025-06-04 xs the newly created directory.\f[R]
30 35f45d45 2025-06-04 xs \f[I]See Technical Notes for dependencies and supported platforms.\f[R]
32 35f45d45 2025-06-04 xs There is an example of r7 repository:
36 35f45d45 2025-06-04 xs \&./nodes/hostA
37 35f45d45 2025-06-04 xs \&./nodes/hostB
38 35f45d45 2025-06-04 xs \&./nodes/hostC
40 35f45d45 2025-06-04 xs \&./groups/common
41 35f45d45 2025-06-04 xs \&./groups/test0
42 35f45d45 2025-06-04 xs \&./groups/common.dir
43 35f45d45 2025-06-04 xs \&./groups/test0.dir
45 35f45d45 2025-06-04 xs \&./.ssh/config
46 35f45d45 2025-06-04 xs \&./.ssh/id_ed25519_r7
47 35f45d45 2025-06-04 xs \&./.ssh/id_ed25519_r7.pub
48 35f45d45 2025-06-04 xs \&./site\-config
51 35f45d45 2025-06-04 xs There is an example of r7 site configuration (\f[CR]site\-config\f[R]
55 35f45d45 2025-06-04 xs prefix install state doc
56 35f45d45 2025-06-04 xs group common \[aq].*\[aq]
57 35f45d45 2025-06-04 xs group test0 hostB hostC
62 35f45d45 2025-06-04 xs There is an exemple of the deployment of that configuration within the
63 35f45d45 2025-06-04 xs r7 repository:
66 35f45d45 2025-06-04 xs $ r7 run\-config
67 35f45d45 2025-06-04 xs \- (ok) hostA:common::install_nothing
68 35f45d45 2025-06-04 xs \- (ok) hostA:common::state_uname
69 35f45d45 2025-06-04 xs \- (ok) hostA:common::doc_tutorial
70 35f45d45 2025-06-04 xs \- (ok) hostB:common::install_nothing
71 35f45d45 2025-06-04 xs \- (ok) hostB:common::state_uname
72 35f45d45 2025-06-04 xs \- (ok) hostB:common::doc_tutorial
73 35f45d45 2025-06-04 xs \- (ok) hostC:common::install_nothing
74 35f45d45 2025-06-04 xs \- (ok) hostC:common::state_uname
75 35f45d45 2025-06-04 xs \- (ok) hostC:common::doc_tutorial
76 35f45d45 2025-06-04 xs \- (ok) hostB:test0::state_test
77 35f45d45 2025-06-04 xs \- (ok) hostC:test0::state_test
80 35f45d45 2025-06-04 xs In this example, everything goes fine, groups are executed on each
81 35f45d45 2025-06-04 xs related nodes, note the \f[CR]\[aq].*\[aq]\f[R] matching all hosts
82 35f45d45 2025-06-04 xs present in \f[CR]./nodes\f[R].
83 35f45d45 2025-06-04 xs Groups are POSIX shell scripts that are a collection of functions.
85 35f45d45 2025-06-04 xs There is the \f[CR]common\f[R] group:
88 35f45d45 2025-06-04 xs install_nothing() \f[B]{\f[R]
89 35f45d45 2025-06-04 xs echo Nothing installed
92 35f45d45 2025-06-04 xs state_uname() \f[B]{\f[R]
96 35f45d45 2025-06-04 xs doc_tutorial() \f[B]{\f[R]
97 35f45d45 2025-06-04 xs echo \[dq]## Welcome to the R7 tutorial!\[dq]
101 35f45d45 2025-06-04 xs And there is the \f[CR]test0\f[R] group:
104 35f45d45 2025-06-04 xs state_test() \f[B]{\f[R]
105 35f45d45 2025-06-04 xs test 1 \-eq 1
109 35f45d45 2025-06-04 xs Any function managed by \f[CR]r7\f[R] needs to be declared in the format
110 35f45d45 2025-06-04 xs \f[CR]\[ha]PREFIX_NAME()\f[R].
112 35f45d45 2025-06-04 xs Group files names can\[cq]t contain spaces, tabs or newlines, as well
113 35f45d45 2025-06-04 xs for nodes dirnames.
114 35f45d45 2025-06-04 xs \f[I]The `:' character is not recommanded as well as it may reduce
115 35f45d45 2025-06-04 xs lisibility of the interactive output.\f[R]
117 35f45d45 2025-06-04 xs Called groups and node directories are copied to related nodes in
118 35f45d45 2025-06-04 xs \f[CR]hostname:/tmp/r7/\f[R]:
121 35f45d45 2025-06-04 xs /tmp/r7/hostA/ # Contents of test.org/nodes/hostA/
122 35f45d45 2025-06-04 xs /tmp/r7/common.dir # Contents of test.org/groups/common.dir/
123 35f45d45 2025-06-04 xs /tmp/r7/test.dir # Contents of test.org/groups/test.dir
126 35f45d45 2025-06-04 xs Groups may have no \f[CR].dir\f[R] directory, in this case, nothing is
129 35f45d45 2025-06-04 xs Once the group copy is done, functions are executed in the order of the
130 35f45d45 2025-06-04 xs defined prefix (part of the \f[CR]site\-config\f[R] file shown before):
133 35f45d45 2025-06-04 xs prefix install state doc
136 35f45d45 2025-06-04 xs This means the functions matching \f[CR]\[ha]install_.*()\f[R],
137 35f45d45 2025-06-04 xs \f[CR]\[ha]state_.*()\f[R] and \f[CR]\[ha]doc_.*()\f[R] (the default
138 35f45d45 2025-06-04 xs \f[CR]R7_PREFIX\f[R]) in the respective declaration order they\[cq]re
139 35f45d45 2025-06-04 xs found in the related group file will be executed.
141 35f45d45 2025-06-04 xs Site confiurations are shell scripts sourced by r7 after it\[cq]s
142 35f45d45 2025-06-04 xs environment is initialized, so \f[CR]prefix\f[R], \f[CR]group\f[R],
143 35f45d45 2025-06-04 xs \f[CR]output\-dump\f[R], \f[CR]summary\f[R] are the functions or aliases
144 35f45d45 2025-06-04 xs provided by r7 itself.
145 35f45d45 2025-06-04 xs This allow for scripting from the \f[CR]site\-config\f[R] file.
146 35f45d45 2025-06-04 xs Here \f[CR]output\-dump\f[R], and \f[CR]summary\f[R] are called to
147 35f45d45 2025-06-04 xs output potential errors, diffs and permissions changes at the end of the
148 35f45d45 2025-06-04 xs interactive output obtained by \f[CR]r7 run\-config\f[R].
149 35f45d45 2025-06-04 xs If nothing catched happened, nothing is added to the output.
150 35f45d45 2025-06-04 xs .SS Errors during remote execution of groups
151 35f45d45 2025-06-04 xs In our previous example, we modify \f[CR]state_test\f[R] so the
152 35f45d45 2025-06-04 xs \f[CR]test\f[R] fails.
155 35f45d45 2025-06-04 xs state_test() \f[B]{\f[R]
156 35f45d45 2025-06-04 xs test 1 \-eq 2
160 35f45d45 2025-06-04 xs And we re\-run the configuration to see what\[cq]s happenning.
163 35f45d45 2025-06-04 xs $ r7 run\-config
164 35f45d45 2025-06-04 xs \- (ok) hostA:common::install_nothing
165 35f45d45 2025-06-04 xs \- (ok) hostA:common::state_uname
166 35f45d45 2025-06-04 xs \- (ok) hostA:common::doc_tutorial
167 35f45d45 2025-06-04 xs \- (ok) hostB:common::install_nothing
168 35f45d45 2025-06-04 xs \- (ok) hostB:common::state_uname
169 35f45d45 2025-06-04 xs \- (ok) hostB:common::doc_tutorial
170 35f45d45 2025-06-04 xs \- (ok) hostC:common::install_nothing
171 35f45d45 2025-06-04 xs \- (ok) hostC:common::state_uname
172 35f45d45 2025-06-04 xs \- (ok) hostC:common::doc_tutorial
173 35f45d45 2025-06-04 xs \- (error 1) hostB:test0::state_test
174 35f45d45 2025-06-04 xs \- (error 1) hostC:test0::state_test
175 35f45d45 2025-06-04 xs \- (error 1) \- in hostB test0 state_test (1748622980)
176 35f45d45 2025-06-04 xs \- (error 1) \- in hostC test0 state_test (1748622980)
179 35f45d45 2025-06-04 xs The last two lines are part of the \f[CR]summary\f[R] output.
181 35f45d45 2025-06-04 xs Let\[cq]s modify the \f[CR]state_test\f[R] function again to add some
182 35f45d45 2025-06-04 xs verbosity to it\[cq]s output.
184 35f45d45 2025-06-04 xs \f[I]Note that we also change the return value.\f[R]
187 35f45d45 2025-06-04 xs state_test() \f[B]{\f[R]
188 35f45d45 2025-06-04 xs echo something
189 35f45d45 2025-06-04 xs false \f[B]||\f[R] \f[B]{\f[R]
190 35f45d45 2025-06-04 xs echo >&2 failed
191 35f45d45 2025-06-04 xs \f[B]return\f[R] 22
196 35f45d45 2025-06-04 xs This will produce the following summary:
199 35f45d45 2025-06-04 xs \- (error 22) \- in hostB test0 state_test (1748622980)
204 35f45d45 2025-06-04 xs \- (error 22) \- in hostC test0 state_test (1748622980)
210 35f45d45 2025-06-04 xs Diffs and permissions changes are also displayed by the
211 35f45d45 2025-06-04 xs \f[CR]summary\f[R] command.
212 35f45d45 2025-06-04 xs When they\[cq]re are detected, the captured related output is shown.
213 35f45d45 2025-06-04 xs .SS Repository initialisation
214 35f45d45 2025-06-04 xs Using the \f[CR]init\f[R] command, we can specify the current or a
215 35f45d45 2025-06-04 xs specifed work directory to be created and act as an r7 repository.
217 35f45d45 2025-06-04 xs \f[I]Automated versionning of outputs are currently let to the user, a
218 35f45d45 2025-06-04 xs recommended place would be the end of the site configuration file.\f[R]
220 35f45d45 2025-06-04 xs This command initializes a new directory called \f[CR]test.org\f[R]:
223 35f45d45 2025-06-04 xs r7 \-w test.org init
227 35f45d45 2025-06-04 xs Once this step is done, it is required to:
229 35f45d45 2025-06-04 xs Copy or initialize the ssh key to the \f[CR].ssh\f[R] folder in the
230 35f45d45 2025-06-04 xs repository created in \f[CR].ssh/id_ed25519\-r7\f[R] and
231 35f45d45 2025-06-04 xs \f[CR]./ssh/id_ed25519\-r7.pub\f[R]
233 35f45d45 2025-06-04 xs Adjust the SSH client configuration file in the repository
234 35f45d45 2025-06-04 xs \f[CR].ssh/config\f[R]
236 35f45d45 2025-06-04 xs \f[I]Note that it is possible to import additionnal SSH configurations,
237 35f45d45 2025-06-04 xs like the user one from the SSH configuration, but it is advised to keep
238 35f45d45 2025-06-04 xs them separate.\f[R]
239 35f45d45 2025-06-04 xs .SS SSH agent handling
240 35f45d45 2025-06-04 xs The function \f[CR]unlock\f[R] can be used to set the SSH agent
241 35f45d45 2025-06-04 xs environement, this will be required for any automated operation later
246 35f45d45 2025-06-04 xs \&. $(command \-v r7) \f[I]# Sourcing r7\f[R]
248 35f45d45 2025-06-04 xs tmux \f[B]||\f[R] screen
251 35f45d45 2025-06-04 xs \f[I]\f[BI]\f[B]Warning:\f[BI]\f[I] Unlock will terminate any running
252 35f45d45 2025-06-04 xs \f[CI]ssh\-agent\f[I] instances.\f[R]
253 35f45d45 2025-06-04 xs .SS Adding new hosts
254 35f45d45 2025-06-04 xs For adding a new host, the simplest way is to have pre\-configured
255 35f45d45 2025-06-04 xs \f[CR]authorized_keys\f[R] for the target user, it is then required to
256 35f45d45 2025-06-04 xs add it to the \f[CR]known_hosts\f[R] file.
257 35f45d45 2025-06-04 xs For that, it is possible to use r7 SSH functions:
260 35f45d45 2025-06-04 xs \&. $(command \-v r7) \f[I]# Sourcing r7\f[R]
261 35f45d45 2025-06-04 xs ssh\-accept\-new hostname
264 35f45d45 2025-06-04 xs If resetting the target\[cq]s user \f[CR]authorized_keys\f[R] file is
265 35f45d45 2025-06-04 xs needed, the following function can be used:
268 35f45d45 2025-06-04 xs \&. $(command \-v r7) \f[I]# Sourcing r7\f[R]
269 35f45d45 2025-06-04 xs ssh\-authorized\-keys\-reset hostname
272 35f45d45 2025-06-04 xs \f[I]\f[BI]Warning:\f[I] This will resets the SSH authorized_keys file
273 35f45d45 2025-06-04 xs for the target user (root, by default) and put the
274 35f45d45 2025-06-04 xs \f[CI].ssh/id_ed25519\-r7.pub\f[I] in place.\f[R]
276 35f45d45 2025-06-04 xs Once the host is accepted in the \f[CR]known_hosts\f[R] file, it\[cq]s
277 35f45d45 2025-06-04 xs possible to import it automatically.
278 35f45d45 2025-06-04 xs .SS Importing hosts configurations
279 35f45d45 2025-06-04 xs \f[I]This feature currently only support OpenBSD.\f[R]
281 35f45d45 2025-06-04 xs Avoiding to import the configuration manually is possible with the
282 35f45d45 2025-06-04 xs \f[CR]import\f[R] command:
285 35f45d45 2025-06-04 xs r7 import hostname
288 35f45d45 2025-06-04 xs Most common configuration files will be copied in a newly created
289 35f45d45 2025-06-04 xs \f[CR]nodes/hostname\f[R] sub\-directory.
290 35f45d45 2025-06-04 xs .SS Writing group files
291 35f45d45 2025-06-04 xs Group files collects fonctions related to the configuration of the
292 35f45d45 2025-06-04 xs operating system, networking, services, global and user configurations
293 35f45d45 2025-06-04 xs packages installations and application deployments.
295 35f45d45 2025-06-04 xs By specifying the execution prefix, the user determines the order of
296 35f45d45 2025-06-04 xs execution of the functions declared in the group file.
299 35f45d45 2025-06-04 xs service_A() \f[B]{\f[R]
300 35f45d45 2025-06-04 xs service A enable
301 35f45d45 2025-06-04 xs service A restart
304 35f45d45 2025-06-04 xs service_B() \f[B]{\f[R]
305 35f45d45 2025-06-04 xs service B enable
306 35f45d45 2025-06-04 xs service B restart
309 35f45d45 2025-06-04 xs state_A() \f[B]{\f[R]
310 35f45d45 2025-06-04 xs service A status
313 35f45d45 2025-06-04 xs doc_A() \f[B]{\f[R]
314 35f45d45 2025-06-04 xs echo \[dq]## Service A\[dq]
316 35f45d45 2025-06-04 xs echo \[dq]\- [url](http://test.org/)\[dq]
321 35f45d45 2025-06-04 xs \f[I]\f[BI]file\f[I]: \f[CI]groups/example1\f[I]\f[R]
323 35f45d45 2025-06-04 xs With the default prefix, \f[CR]install\f[R], \f[CR]state\f[R],
324 35f45d45 2025-06-04 xs \f[CR]doc\f[R], the fonction that will be executed are
325 35f45d45 2025-06-04 xs \f[CR]state_A\f[R] and \f[CR]doc_A\f[R].
326 35f45d45 2025-06-04 xs To test that group file with all the functions inside we can call r7 the
327 35f45d45 2025-06-04 xs following way:
330 35f45d45 2025-06-04 xs r7 \-P \[aq]service state doc\[aq] group example1 hostname
333 35f45d45 2025-06-04 xs Or using the \f[CR]\-a\f[R] flag which will create a prefix
334 35f45d45 2025-06-04 xs automatically with all functions present in the group file:
337 35f45d45 2025-06-04 xs r7 \-a group example1 hostname
340 35f45d45 2025-06-04 xs In a real situation, this example will have failing functions because
341 35f45d45 2025-06-04 xs the \f[CR]service\f[R] command may not be found or the services named
342 35f45d45 2025-06-04 xs \f[CR]A\f[R] or \f[CR]B\f[R] does not exist.
345 35f45d45 2025-06-04 xs ! (error 127) tools0:example1::service_A
346 35f45d45 2025-06-04 xs ! (error 127) tools0:example1::service_B
347 35f45d45 2025-06-04 xs ! (error 127) tools0:example1::state_A
348 35f45d45 2025-06-04 xs \- (ok) tools0:example1::doc_A
351 35f45d45 2025-06-04 xs We could force the group execution to stop using a combination of the
352 35f45d45 2025-06-04 xs \f[CR]\-e\f[R] flag and the \f[CR]error\f[R] group function.
355 35f45d45 2025-06-04 xs service_A() \f[B]{\f[R]
356 35f45d45 2025-06-04 xs service A enable \f[B]&&\f[R]
357 35f45d45 2025-06-04 xs service A restart \f[B]||\f[R]
358 35f45d45 2025-06-04 xs error unable to setup service A
361 35f45d45 2025-06-04 xs service_B() \f[B]{\f[R]
362 35f45d45 2025-06-04 xs service B enable \f[B]&&\f[R]
363 35f45d45 2025-06-04 xs service B restart \f[B]||\f[R]
364 35f45d45 2025-06-04 xs error unable to setup service B
367 35f45d45 2025-06-04 xs state_A() \f[B]{\f[R]
368 35f45d45 2025-06-04 xs service A status
371 35f45d45 2025-06-04 xs doc_A() \f[B]{\f[R]
372 35f45d45 2025-06-04 xs echo \[dq]## Service A\[dq]
374 35f45d45 2025-06-04 xs echo \[dq]\- [url](http://test.org/)\[dq]
379 35f45d45 2025-06-04 xs \f[I]\f[BI]file:\f[I] \f[CI]groups/example2\f[I]\f[R]
381 35f45d45 2025-06-04 xs Let\[cq]s run the updated example with the \f[CR]\-s\f[R] flag to
382 35f45d45 2025-06-04 xs trigger the summary output.
385 35f45d45 2025-06-04 xs rm \-fr _output
386 35f45d45 2025-06-04 xs r7 \-sea group example2 hostname
389 35f45d45 2025-06-04 xs This will produce something like the following:
392 35f45d45 2025-06-04 xs ! (error) tools0:example2::service_A
393 35f45d45 2025-06-04 xs ! (exit) tools0:example2::service_A
394 35f45d45 2025-06-04 xs \- (error 127) \- in tools0 example2 service_A (1748791986)
396 35f45d45 2025-06-04 xs /bin/sh: <stdin>[155]: service: not found
397 35f45d45 2025-06-04 xs :: 1748791986 tools0 ERROR unable to setup service A
399 35f45d45 2025-06-04 xs .SS Using the r7 install functions
400 35f45d45 2025-06-04 xs The group library comes with the following functions that will allow
401 35f45d45 2025-06-04 xs installation of files and triggering actions if necessary:
402 35f45d45 2025-06-04 xs \f[CR]install\f[R], \f[CR]groupinstall\f[R], \f[CR]nodeinstall\f[R].
403 35f45d45 2025-06-04 xs They are all shortcuts to an internal \f[CR]r7_install\f[R] function,
404 35f45d45 2025-06-04 xs it\[cq]s just the wrappers changes directory to respectively
405 35f45d45 2025-06-04 xs \f[CR]/tmp/r7\f[R], \f[CR]/tmp/r7/groupname.dir/\f[R] and
406 35f45d45 2025-06-04 xs \f[CR]/tmp/r7/hostname/\f[R].
408 35f45d45 2025-06-04 xs If we want to install files from the group directory we will use
409 35f45d45 2025-06-04 xs something like:
412 35f45d45 2025-06-04 xs install_program() \f[B]{\f[R]
413 35f45d45 2025-06-04 xs groupinstall \-m 755 \-o root:bin my_program /usr/local/bin
417 35f45d45 2025-06-04 xs \f[I]We are supposing to have the file
418 35f45d45 2025-06-04 xs \f[CI]groups/example3.dir/my_program\f[I]\f[R]
420 35f45d45 2025-06-04 xs And if it\[cq]s something from node, we should use:
423 35f45d45 2025-06-04 xs install_program_config() \f[B]{\f[R]
424 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel my_config /etc
428 35f45d45 2025-06-04 xs We can now chain the \f[CR]install\f[R] functions to configuration
429 35f45d45 2025-06-04 xs checking and initialization of programs, services or network features
430 35f45d45 2025-06-04 xs like in the following example, in which we install \f[CR]ntp.conf\f[R]
431 35f45d45 2025-06-04 xs from the deployed node directory to \f[CR]/etc\f[R]:
434 35f45d45 2025-06-04 xs service_ntpd() \f[B]{\f[R]
435 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel ntpd.conf /etc \f[B]&&\f[R]
436 35f45d45 2025-06-04 xs ntpd \-n \f[B]&&\f[R]
437 35f45d45 2025-06-04 xs rcctl enable ntpd \f[B]&&\f[R]
438 35f45d45 2025-06-04 xs rcctl restart ntpd
441 35f45d45 2025-06-04 xs .SS Using the r7 node function
442 35f45d45 2025-06-04 xs We may want to avoid executing a function or parts of it if the node has
443 35f45d45 2025-06-04 xs no related files before executing the installation and actions handling
445 35f45d45 2025-06-04 xs This can be done with the help of the \f[CR]node\f[R] function.
448 35f45d45 2025-06-04 xs service_ntpd() \f[B]{\f[R]
449 35f45d45 2025-06-04 xs node ntpd.conf \f[B]&&\f[R]
450 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel ntpd.conf /etc \f[B]&&\f[R]
451 35f45d45 2025-06-04 xs ntpd \-n \f[B]&&\f[R]
452 35f45d45 2025-06-04 xs rcctl enable ntpd \f[B]&&\f[R]
453 35f45d45 2025-06-04 xs rcctl restart ntpd
457 35f45d45 2025-06-04 xs Here, \f[CR]node\f[R] will return \f[CR]31\f[R] if there is no file or
458 35f45d45 2025-06-04 xs directory called \f[CR]ntpd.conf\f[R] inside the deployed node directory
459 35f45d45 2025-06-04 xs (\f[CR]/tmp/r7/hostname\f[R]).
461 35f45d45 2025-06-04 xs \f[CR]0\f[R], \f[CR]30\f[R] and \f[CR]31\f[R] exit codes are ignored
462 35f45d45 2025-06-04 xs when r7 will search for execution errors.
463 35f45d45 2025-06-04 xs This means \f[CR]30\f[R] and \f[CR]31\f[R] exit code are reserved to r7.
465 35f45d45 2025-06-04 xs In other terms, this will update the NTP daemon configuration only if
466 35f45d45 2025-06-04 xs \f[CR]ntpd.conf\f[R] is present in the node directory, otherwise it is
467 35f45d45 2025-06-04 xs kept by default, which is the system provided default
468 35f45d45 2025-06-04 xs \f[CR]ntpd.conf\f[R].
469 35f45d45 2025-06-04 xs .SS Sourcing specific files
470 35f45d45 2025-06-04 xs Here\[cq]s an example how to source additionnal shell from the deployed
471 35f45d45 2025-06-04 xs node directory, or elsewhere:
474 35f45d45 2025-06-04 xs service_sysrc() \f[B]{\f[R]
475 35f45d45 2025-06-04 xs sysrc dumpdev=NO
476 35f45d45 2025-06-04 xs sysrc kld_list=\[dq]vmm if_tuntap if_bridge nmdm\[dq]
477 35f45d45 2025-06-04 xs sysrc microcode_update_enable=YES
478 35f45d45 2025-06-04 xs sysrc mountd_enable=YES
479 35f45d45 2025-06-04 xs sysrc nfs_server_enable=YES
480 35f45d45 2025-06-04 xs sysrc ntpdate_enable=YES
481 35f45d45 2025-06-04 xs sysrc powerd_enable=YES
482 35f45d45 2025-06-04 xs sysrc rcshutdown_timeout=900
483 35f45d45 2025-06-04 xs sysrc rpcbind_enable=YES
484 35f45d45 2025-06-04 xs sysrc sshd_enable=YES
485 35f45d45 2025-06-04 xs sysrc zfs_enable=YES
486 35f45d45 2025-06-04 xs nodesource sysrc.local
490 35f45d45 2025-06-04 xs In this FreeBSD example, we configure the system RC globally with
491 35f45d45 2025-06-04 xs \f[CR]service_sysrc\f[R] which apply, if \f[CR]sysrc.local\f[R] is found
492 35f45d45 2025-06-04 xs in the root of the node directory, it\[cq]s sourcing in the current
493 35f45d45 2025-06-04 xs scope via the help of \f[CR]nodesource sysrc.local\f[R].
495 35f45d45 2025-06-04 xs The file \f[CR]nodes/hostname/sysrcl.local\f[R] contains the following:
498 35f45d45 2025-06-04 xs sysrc ifconfig_igb0=DHCP
499 35f45d45 2025-06-04 xs sysrc ifconfig_igb1=up
501 35f45d45 2025-06-04 xs .SS Other examples
502 35f45d45 2025-06-04 xs Inside the r7 release, a small example groups library can be found in
503 35f45d45 2025-06-04 xs the \f[CR]groups\f[R] directory, that can also be browsed in the \c
504 35f45d45 2025-06-04 xs .UR https://got.inda.re/?action=summary&path=r7.git
508 35f45d45 2025-06-04 xs .SS System shell profile
509 35f45d45 2025-06-04 xs Here we install the \f[CR]profile\f[R] file provided in the
510 35f45d45 2025-06-04 xs \f[CR]groupname.dir\f[R] directory or the profile provided by the node
514 35f45d45 2025-06-04 xs setup_profile() \f[B]{\f[R]
515 35f45d45 2025-06-04 xs groupinstall \-m 644 \-o root:wheel profile /etc
516 35f45d45 2025-06-04 xs node profile \f[B]&&\f[R]
517 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel profile /etc
521 35f45d45 2025-06-04 xs Here we add new users:
524 35f45d45 2025-06-04 xs setup_users() \f[B]{\f[R]
525 35f45d45 2025-06-04 xs useradd user1 2>/dev/null \f[B]||\f[R] :
526 35f45d45 2025-06-04 xs useradd user2 2>/dev/null \f[B]||\f[R] :
530 35f45d45 2025-06-04 xs In the following example, we install a script and call it from a
531 35f45d45 2025-06-04 xs dedicated user crontab.
534 35f45d45 2025-06-04 xs mail_admins=admins\[at]test.org
536 35f45d45 2025-06-04 xs install_myscript() \f[B]{\f[R]
537 35f45d45 2025-06-04 xs groupinstall \-o root:bin \-m 755 myscript /usr/local/bin \f[B]&&\f[R]
538 35f45d45 2025-06-04 xs useradd \-d /var/empty \-s /sbin/nologin _myscript
539 35f45d45 2025-06-04 xs crontab \-u _myscript \- <<\-/
540 35f45d45 2025-06-04 xs MAILTO=$mail_admins
541 35f45d45 2025-06-04 xs */5 * * * * myscript
545 35f45d45 2025-06-04 xs .SS Consulting the output
546 35f45d45 2025-06-04 xs After the execution is done, the result are saved in the \f[CR]_run\f[R]
547 35f45d45 2025-06-04 xs directory, \f[CR]output\-dump\f[R] needs to be called to produce the
548 35f45d45 2025-06-04 xs current \f[CR]_output\f[R] structure.
550 35f45d45 2025-06-04 xs The r7 \f[CR]output\f[R] command can then be used to show specific
551 35f45d45 2025-06-04 xs output groups or functions:
557 35f45d45 2025-06-04 xs Will show the whole output of the latest groups deployments.
559 35f45d45 2025-06-04 xs This format can be used to match specific host, group or function:
562 35f45d45 2025-06-04 xs r7 output [hostname [groupname [funcname]]]
568 35f45d45 2025-06-04 xs $ r7 output tools0 OpenBSD state_packages\[rs]*
569 35f45d45 2025-06-04 xs \- tools0 OpenBSD state_packages_upgrades
571 35f45d45 2025-06-04 xs quirks\-7.103 signed on 2025\-05\-30T01:12:03Z
573 35f45d45 2025-06-04 xs \- tools0 OpenBSD state_packages_repository
575 35f45d45 2025-06-04 xs https://cdn.openbsd.org/pub/OpenBSD
578 35f45d45 2025-06-04 xs \f[I]Note that the \f[CI]output\f[I] function arguments are using
579 35f45d45 2025-06-04 xs shell\[cq]s case globbing patterns.\f[R]
580 35f45d45 2025-06-04 xs .SS r7 command line
581 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
584 35f45d45 2025-06-04 xs r7 [options] [command [arguments...]]
588 35f45d45 2025-06-04 xs \f[B]\-h\f[R] Show usage and exit
590 35f45d45 2025-06-04 xs \f[B]\-d\f[R] Enable debug mode
592 35f45d45 2025-06-04 xs \f[B]\-i\f[R] Specify the SSH identity file
594 35f45d45 2025-06-04 xs \f[B]\-F\f[R] Specify the SSH client configuration file
596 35f45d45 2025-06-04 xs \f[B]\-w\f[R] Set the work directory where \f[CR]./nodes\f[R] and
597 35f45d45 2025-06-04 xs \f[CR]./groups\f[R] can be found
599 35f45d45 2025-06-04 xs \f[B]\-r\f[R] Set the run directory (default: \f[CR]./_run\f[R])
601 35f45d45 2025-06-04 xs \f[B]\-o\f[R] Set the output directory (default: \f[CR]./_output\f[R])
603 35f45d45 2025-06-04 xs \f[B]\-c\f[R] Specify the site configuration file (default:
604 35f45d45 2025-06-04 xs \f[CR]./site\-config\f[R])
606 35f45d45 2025-06-04 xs \f[B]\-n\f[R] Enable dry run mode; prevents any modification on hosts
608 35f45d45 2025-06-04 xs \f[B]\-e\f[R] Exit the group execution on the error function
610 35f45d45 2025-06-04 xs \f[B]\-p\f[R] Run each host in parallel per group call
612 35f45d45 2025-06-04 xs \f[B]\-O\f[R] Show output interactively
614 35f45d45 2025-06-04 xs \f[B]\-P\f[R] Specify a prefix
616 35f45d45 2025-06-04 xs \f[B]\-a\f[R] Select all available prefixes for a group command
618 35f45d45 2025-06-04 xs \f[B]\-s\f[R] Apply output\-dump and summary after a group command
623 35f45d45 2025-06-04 xs lw(18.7n) lw(51.3n).
631 35f45d45 2025-06-04 xs \f[B]run\-config\f[R]
633 35f45d45 2025-06-04 xs Run the site configuration
636 35f45d45 2025-06-04 xs \f[B]group\f[R]
638 35f45d45 2025-06-04 xs Deploy specified group to hosts
641 35f45d45 2025-06-04 xs \f[B]output\-dump\f[R]
643 35f45d45 2025-06-04 xs Dump the run directory to the output directory
646 35f45d45 2025-06-04 xs \f[B]output\f[R]
648 35f45d45 2025-06-04 xs Consult the output
651 35f45d45 2025-06-04 xs \f[B]summary\f[R]
653 35f45d45 2025-06-04 xs Produce a summary of errors and changes
656 35f45d45 2025-06-04 xs \f[B]digraph\-host\f[R]
658 35f45d45 2025-06-04 xs Produce a dot digraph for hosts
661 35f45d45 2025-06-04 xs \f[B]digraph\-ssh\f[R]
663 35f45d45 2025-06-04 xs Produce a dot digraph of SSH ID\[cq]s, users and nodes relations
666 35f45d45 2025-06-04 xs \f[B]import\f[R]
668 35f45d45 2025-06-04 xs Import TARGET host in the current nodes directory
671 35f45d45 2025-06-04 xs \f[B]info\f[R]
673 35f45d45 2025-06-04 xs Default command showing active nodes and summary
676 35f45d45 2025-06-04 xs \f[B]init\f[R]
678 35f45d45 2025-06-04 xs Initialize a new work directory
681 35f45d45 2025-06-04 xs .SS Environment
685 35f45d45 2025-06-04 xs lw(9.7n) lw(31.4n) lw(29.0n).
689 35f45d45 2025-06-04 xs Default value
699 35f45d45 2025-06-04 xs Enable debug mode
706 35f45d45 2025-06-04 xs Enable dry\-run mode
709 35f45d45 2025-06-04 xs R7_GROUP_ALLPREFIX
713 35f45d45 2025-06-04 xs Group selects all available prefix
716 35f45d45 2025-06-04 xs R7_GROUP_SUMMARY
720 35f45d45 2025-06-04 xs Enable output\-dump and summary after group execution
723 35f45d45 2025-06-04 xs R7_GROUP_EXITONERROR
727 35f45d45 2025-06-04 xs Enable exit on error function
734 35f45d45 2025-06-04 xs Enable group nodes parallel execution
739 35f45d45 2025-06-04 xs install state doc
741 35f45d45 2025-06-04 xs Set the r7 group execution prefix
744 35f45d45 2025-06-04 xs R7_SHOWOUTPUT
748 35f45d45 2025-06-04 xs Show interactive output
755 35f45d45 2025-06-04 xs Set the r7 repository path
758 35f45d45 2025-06-04 xs R7_SITE_CONFIG
760 35f45d45 2025-06-04 xs R7_WORKDIR/site\-config
762 35f45d45 2025-06-04 xs Set the r7 \f[CR]site\-config\f[R] path
767 35f45d45 2025-06-04 xs R7_WORKDIR/_output
769 35f45d45 2025-06-04 xs Set the r7 output directory path
772 35f45d45 2025-06-04 xs SSH_CONFIG_DIR
774 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh
776 35f45d45 2025-06-04 xs Set the SSH configuration directory path
779 35f45d45 2025-06-04 xs SSH_CONFIG_FILE
781 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh/config
783 35f45d45 2025-06-04 xs Set the SSH configuration file path
786 35f45d45 2025-06-04 xs SSH_CONTROL_DIR
788 35f45d45 2025-06-04 xs SSH_CONFIG_DIR/control
790 35f45d45 2025-06-04 xs Set the SSH control dir path
793 35f45d45 2025-06-04 xs SSH_IDENTITY_FILE
795 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh/id_ed25519_r7
797 35f45d45 2025-06-04 xs Set the SSH identity file
800 35f45d45 2025-06-04 xs SSH_KNOWN_HOSTS
802 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh/known_hosts
804 35f45d45 2025-06-04 xs Set the SSH known hosts file
807 35f45d45 2025-06-04 xs SSH_CONNECT_TIMEOUT
811 35f45d45 2025-06-04 xs Set the SSH connect timeout
814 35f45d45 2025-06-04 xs .SS Group variables
815 35f45d45 2025-06-04 xs Those variables are available during the execution of th group
816 35f45d45 2025-06-04 xs file\[cq]s functions.
830 35f45d45 2025-06-04 xs Current run trace ID
835 35f45d45 2025-06-04 xs Current group name being executed
840 35f45d45 2025-06-04 xs Cause the error function to exit if equals \f[CR]yes\f[R]
845 35f45d45 2025-06-04 xs Contains the output of \f[CR]nodename\f[R]
850 35f45d45 2025-06-04 xs Contains the output of \f[CR]nodedir\f[R]
855 35f45d45 2025-06-04 xs Contains the output of \f[CR]groupdir\f[R]
858 35f45d45 2025-06-04 xs .SS Group functions
859 35f45d45 2025-06-04 xs Those functions are accessible during the execution of the group
860 35f45d45 2025-06-04 xs file\[cq]s functions.
861 22b54c5e 2025-06-04 xs Non documented functions are reserved for internal use.
883 35f45d45 2025-06-04 xs groupinstalldir
885 35f45d45 2025-06-04 xs nodeinstalldir
895 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Append a trace containing the current
896 35f45d45 2025-06-04 xs node name and \f[CR]trace_id\f[R]
898 35f45d45 2025-06-04 xs \f[B]Usage:\f[R]
901 35f45d45 2025-06-04 xs trace [string...]
904 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Trace an error message that will
905 35f45d45 2025-06-04 xs inform the user of an event in the summary output, exit the group
906 35f45d45 2025-06-04 xs execution if \f[CR]\-e\f[R] is set
908 35f45d45 2025-06-04 xs \f[B]Usage:\f[R]
911 35f45d45 2025-06-04 xs error [string...]
914 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns true if the argument is an
915 35f45d45 2025-06-04 xs existing file or directory inside \f[CR]/tmp/r7/$(nodename)\f[R], else,
918 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
921 35f45d45 2025-06-04 xs node [filename\f[B]|\f[R]dirname]
924 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the small hostname of the
927 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
933 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns \f[CR]/tmp/r7/$(nodename)\f[R]
935 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
941 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns
942 35f45d45 2025-06-04 xs \f[CR]/tmp/r7/$groupname.dir\f[R]
944 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
950 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to \f[CR]/tmp/r7\f[R]
951 35f45d45 2025-06-04 xs and install files if changed and sets mode and owner, returns true if
952 35f45d45 2025-06-04 xs the file changed, otherwise returns 30
954 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
957 35f45d45 2025-06-04 xs install [\-o owner] [\-m mode] source destintaion
959 35f45d45 2025-06-04 xs .SS groupinstall
960 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
961 35f45d45 2025-06-04 xs \f[CR].dir\f[R] directory in \f[CR]/tmp/r7\f[R] then performs like
962 35f45d45 2025-06-04 xs \f[CR]install\f[R]
964 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
967 35f45d45 2025-06-04 xs groupinstall [\-o owner] [\-m mode] source destintaion
969 35f45d45 2025-06-04 xs .SS nodeinstall
970 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current node
971 35f45d45 2025-06-04 xs directory in \f[CR]/tmp/r7\f[R] then performs like \f[CR]install\f[R]
973 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
976 35f45d45 2025-06-04 xs nodeinstall [\-o owner] [\-m mode] source destintaion
978 35f45d45 2025-06-04 xs .SS installdir
979 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Install directory calling
980 35f45d45 2025-06-04 xs \f[CR]install\f[R] for each file and checking for permissions changes.
982 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
985 35f45d45 2025-06-04 xs installdir [\-o fileowner] [\-m filemode] [\-O dirowner] [\-O dirmode] source
988 35f45d45 2025-06-04 xs .SS groupinstalldir
989 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
990 35f45d45 2025-06-04 xs directoy then call installdir
992 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
995 35f45d45 2025-06-04 xs groupinstalldir [\-o fileowner] [\-m filemode] [\-O dirowner] [\-O dirmode] source
998 35f45d45 2025-06-04 xs .SS nodeinstalldir
999 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1000 35f45d45 2025-06-04 xs directoy then call installdir
1002 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1005 35f45d45 2025-06-04 xs nodeinstalldir [\-o fileowner] [\-m filemode] [\-O dirowner] [\-O dirmode] source
1009 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Source a POSIX shell file in the
1010 35f45d45 2025-06-04 xs current execution
1012 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1015 35f45d45 2025-06-04 xs source filename
1017 35f45d45 2025-06-04 xs .SS groupsource
1018 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1019 35f45d45 2025-06-04 xs directory then call source with the file name as argument, produces an
1020 35f45d45 2025-06-04 xs error if filename is not found from the group directory
1023 35f45d45 2025-06-04 xs groupsource filename
1025 35f45d45 2025-06-04 xs .SS nodesource
1026 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1027 35f45d45 2025-06-04 xs directory then call node and source with the file name as argument
1028 35f45d45 2025-06-04 xs without producing an error if the filename is not found
1031 35f45d45 2025-06-04 xs nodesource filename
1033 35f45d45 2025-06-04 xs .SH r7 library
1034 35f45d45 2025-06-04 xs Usable from the r7 \f[CR]site\-config\f[R] file or sourced in the
1035 35f45d45 2025-06-04 xs current shell using:
1038 35f45d45 2025-06-04 xs \&. $(command \-v r7)
1041 35f45d45 2025-06-04 xs Each functions are declared with underscore names and aliased with
1043 35f45d45 2025-06-04 xs Shorter aliases are also available, list all declared aliases with:
1049 22b54c5e 2025-06-04 xs Non documented functions are reserved for internal use.
1050 35f45d45 2025-06-04 xs .SS Interface
1058 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Default command showing active nodes
1059 35f45d45 2025-06-04 xs and summary, ran when sourced
1061 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1067 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Shows the command line help
1069 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1074 35f45d45 2025-06-04 xs .SS SSH functions
1084 35f45d45 2025-06-04 xs ssh\-known\-hosts
1086 35f45d45 2025-06-04 xs ssh\-authorized\-keys\-reset
1088 35f45d45 2025-06-04 xs ssh\-accept\-new
1090 35f45d45 2025-06-04 xs ssh\-control\-master\-clean
1096 35f45d45 2025-06-04 xs ssh\-authorized\-keys
1098 35f45d45 2025-06-04 xs ssh\-ids\-hosts
1102 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Resets the SSH agent environment and
1103 35f45d45 2025-06-04 xs issues ssh\-add for SSH_IDENTITY_FILE
1105 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1111 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] r7 openrsync, rsync, scp wrapper;
1112 35f45d45 2025-06-04 xs selected in order of availability
1114 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1117 35f45d45 2025-06-04 xs copy SRC DST
1120 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] r7 SSH wrapper; behaves like the
1121 35f45d45 2025-06-04 xs standard OpenSSH command
1123 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1126 35f45d45 2025-06-04 xs ssh OPTION HOST
1128 35f45d45 2025-06-04 xs .SS ssh\-debug
1129 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] r7 SSH with debug connection mode for
1130 35f45d45 2025-06-04 xs a specific HOST
1132 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1135 35f45d45 2025-06-04 xs ssh\-debug HOST
1137 35f45d45 2025-06-04 xs .SS ssh\-known\-hosts
1138 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Calls ssh\-keygen to dump the SSH
1139 35f45d45 2025-06-04 xs known_hosts file
1141 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1144 35f45d45 2025-06-04 xs ssh\-known\-hosts
1146 35f45d45 2025-06-04 xs .SS ssh\-authorized\-keys\-reset
1147 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Resets SSH authorized_keys on the
1148 35f45d45 2025-06-04 xs specified HOST
1150 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1153 35f45d45 2025-06-04 xs ssh\-authorized\-keys\-reset HOST
1155 35f45d45 2025-06-04 xs .SS ssh\-accept\-new
1156 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Adds a new host entry in the SSH
1157 35f45d45 2025-06-04 xs known_hosts file
1159 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1162 35f45d45 2025-06-04 xs ssh\-accept\-new HOST
1164 35f45d45 2025-06-04 xs .SS ssh\-control\-master\-clean
1165 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Cleans the SSH control master
1168 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1171 35f45d45 2025-06-04 xs ssh\-control\-master\-clean
1173 35f45d45 2025-06-04 xs .SS ssh\-users
1174 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Searches nodes for authorized_keys_*
1175 35f45d45 2025-06-04 xs and returns a list of users
1177 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1182 35f45d45 2025-06-04 xs .SS ssh\-ids
1183 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns sorted SSH IDs
1185 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1190 35f45d45 2025-06-04 xs .SS ssh\-authorized\-keys
1191 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the list of authorized_keys
1194 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1197 35f45d45 2025-06-04 xs ssh\-authorized\-keys
1199 35f45d45 2025-06-04 xs .SS ssh\-ids\-hosts
1200 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns SSH IDs along with matching
1201 35f45d45 2025-06-04 xs keyfile and hostname
1203 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1206 35f45d45 2025-06-04 xs ssh\-ids\-hosts
1208 35f45d45 2025-06-04 xs .SS Deployment functions
1212 35f45d45 2025-06-04 xs nodes\-active
1220 35f45d45 2025-06-04 xs group\-functions
1226 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of available nodes
1228 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1233 35f45d45 2025-06-04 xs .SS nodes\-active
1234 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of active nodes by
1235 35f45d45 2025-06-04 xs detecting SSH availability
1237 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1240 35f45d45 2025-06-04 xs nodes\-active
1242 35f45d45 2025-06-04 xs .SS run\-config
1243 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Executes \f[CR]R7_SITE_CONFIG\f[R] in
1244 35f45d45 2025-06-04 xs the loaded environment
1246 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1252 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of active nodes
1253 35f45d45 2025-06-04 xs matching a list of grep REGEXES
1255 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1258 35f45d45 2025-06-04 xs members REGEXES
1261 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Applies GROUPNAME functions (in prefix
1262 35f45d45 2025-06-04 xs order) to the provided MEMBERS list
1264 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1267 35f45d45 2025-06-04 xs group GROUPNAME MEMBERS
1269 35f45d45 2025-06-04 xs .SS group\-functions
1270 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of functions found in
1271 35f45d45 2025-06-04 xs the specified GROUPNAME
1273 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1276 35f45d45 2025-06-04 xs group\-functions GROUPNAME
1279 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Sets the current PREFIX for matching
1280 35f45d45 2025-06-04 xs function names
1282 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1285 35f45d45 2025-06-04 xs prefix PREFIX
1287 35f45d45 2025-06-04 xs .SS Text output functions
1289 35f45d45 2025-06-04 xs output\-dump
1291 35f45d45 2025-06-04 xs output\-latest
1293 35f45d45 2025-06-04 xs output\-status
1295 35f45d45 2025-06-04 xs output\-duration
1299 35f45d45 2025-06-04 xs output\-diffs
1301 35f45d45 2025-06-04 xs output\-permissions
1303 35f45d45 2025-06-04 xs output\-errors
1307 35f45d45 2025-06-04 xs trace\-id\-last
1310 35f45d45 2025-06-04 xs .SS output\-dump
1311 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Dumps R7_RUNDIR to R7_OUTPUTDIR
1313 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1316 35f45d45 2025-06-04 xs output\-dump
1318 35f45d45 2025-06-04 xs .SS output\-latest
1319 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of outputs from the
1322 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1325 35f45d45 2025-06-04 xs output\-latest
1327 35f45d45 2025-06-04 xs .SS output\-status
1328 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of current dumped
1329 35f45d45 2025-06-04 xs functions exit status codes
1331 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1334 35f45d45 2025-06-04 xs output\-status
1336 35f45d45 2025-06-04 xs .SS output\-duration
1337 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of durations of
1338 35f45d45 2025-06-04 xs executed groups
1340 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1343 35f45d45 2025-06-04 xs output\-duration
1346 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Shows the dumped output matching HOST,
1347 35f45d45 2025-06-04 xs GROUPNAME, and FUNCTION (or any if unspecified)
1349 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1352 35f45d45 2025-06-04 xs output HOST GROUPNAME FUNCTION
1354 35f45d45 2025-06-04 xs .SS trace\-id\-last
1355 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the latest execution trace_id
1357 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1360 35f45d45 2025-06-04 xs trace\-id\-last
1362 35f45d45 2025-06-04 xs .SS output\-diffs
1363 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the diffs from the latest
1366 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1369 35f45d45 2025-06-04 xs output\-diffs
1371 35f45d45 2025-06-04 xs .SS output\-permissions
1372 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the latest permission changes
1374 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1377 35f45d45 2025-06-04 xs output\-permissions
1379 35f45d45 2025-06-04 xs .SS output\-errors
1380 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the latest errors detected
1382 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1385 35f45d45 2025-06-04 xs output\-errors
1388 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Produces a summary of errors, diffs,
1389 35f45d45 2025-06-04 xs and permission outputs
1391 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1396 35f45d45 2025-06-04 xs .SS Digraph output
1398 35f45d45 2025-06-04 xs digraph\-host
1400 35f45d45 2025-06-04 xs digraph\-ssh\-id\-hosts
1403 35f45d45 2025-06-04 xs .SS digraph\-host
1404 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a directed graph (in DOT
1405 35f45d45 2025-06-04 xs format) showing relations among groups, functions, and nodes
1407 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1410 35f45d45 2025-06-04 xs digraph\-host
1412 35f45d45 2025-06-04 xs .SS digraph\-ssh\-id\-hosts
1413 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a directed graph (in DOT
1414 35f45d45 2025-06-04 xs format) of relations between SSH IDs and hosts
1416 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1419 35f45d45 2025-06-04 xs digraph\-ssh\-id\-hosts
1421 35f45d45 2025-06-04 xs .SS HTML output
1425 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Retunrs a report page with the content
1426 35f45d45 2025-06-04 xs of \f[CR]README.md\f[R] in HTML format
1428 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1435 35f45d45 2025-06-04 xs .SS Node importing
1439 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Import configuration files from a
1442 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1449 35f45d45 2025-06-04 xs .SS Technical notes
1451 35f45d45 2025-06-04 xs Supported shells are ksh93, oksh, yash and bash.
1453 35f45d45 2025-06-04 xs Supported platforms are OpenBSD, FreeBSD, NetBSD and GNU/Linux.
1455 35f45d45 2025-06-04 xs Busybox support is planned.
1457 35f45d45 2025-06-04 xs Optional dependencies are openrsync, rsync, column, graphviz and pandoc.
1459 35f45d45 2025-06-04 xs The HTML output is a work in progress.
1463 f976c0b3 2025-06-05 xs The provided group library is shared as additionnal examples of the
1464 f976c0b3 2025-06-05 xs documentation and contain the following third\-party files under the ISC
1466 f976c0b3 2025-06-05 xs Copyright information are indicated in the LICENSE section of related
1469 f976c0b3 2025-06-05 xs \f[CR]pf\-badhost.sh\f[R]
1471 f976c0b3 2025-06-05 xs \f[CR]unbound\-adblock.sh\f[R]
1473 f976c0b3 2025-06-05 xs \f[CR]http\-ban.sh\f[R]
1475 8b145b67 2025-06-04 xs The project is shared under the terms of the ISC license.
1476 8b145b67 2025-06-04 xs Any version previous \f[CR]0.1.0\f[R] needs to be considered obsolete
1477 8b145b67 2025-06-04 xs and should not be redistributed.
1478 8b145b67 2025-06-04 xs History in the GIT repository is kept for transparency purpose only.
1480 8b145b67 2025-06-04 xs Below is a copy of the applicable license:
1485 8b145b67 2025-06-04 xs Copyright 2025 xs <xs\[at]inda.re>
1487 8b145b67 2025-06-04 xs Permission to use, copy, modify, and/or distribute this software for any
1488 8b145b67 2025-06-04 xs purpose with or without fee is hereby granted, provided that the above
1489 8b145b67 2025-06-04 xs copyright notice and this permission notice appear in all copies.
1491 8b145b67 2025-06-04 xs THE SOFTWARE IS PROVIDED \[dq]AS IS\[dq] AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
1492 8b145b67 2025-06-04 xs REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
1493 8b145b67 2025-06-04 xs FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
1494 8b145b67 2025-06-04 xs INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
1495 8b145b67 2025-06-04 xs LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
1496 8b145b67 2025-06-04 xs OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1497 8b145b67 2025-06-04 xs PERFORMANCE OF THIS SOFTWARE.
