2 35f45d45 2025-06-04 xs .\" Automatically generated by Pandoc 3.6.2
4 8e44e3d4 2025-06-25 xs .TH "R7" "1" "Tue Jun 3 2025" "v0.2.0" "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 8e44e3d4 2025-06-25 xs configuration files and related operations versioned in a central
10 8e44e3d4 2025-06-25 xs To remain code versioning system agnostic, manual or automated
11 8e44e3d4 2025-06-25 xs versioning 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 8e44e3d4 2025-06-25 xs \f[I]Nodes sub\-directories are host names understood by the ssh client
20 35f45d45 2025-06-04 xs and configuration.\f[R]
22 8e44e3d4 2025-06-25 xs \f[I]Currently, r7 requires valid ssh configuration and key files 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 8e44e3d4 2025-06-25 xs There is an example 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 8e44e3d4 2025-06-25 xs for nodes \f[CR]dirnames\f[R].
114 8e44e3d4 2025-06-25 xs \f[I]The `:' character is not recommended as well as it may reduce
115 8e44e3d4 2025-06-25 xs readability 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 4296d94d 2025-06-07 xs This means the functions matching \f[CR]\[ha]install.*()\f[R],
137 4296d94d 2025-06-07 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 8e44e3d4 2025-06-25 xs Site configurations 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 8e44e3d4 2025-06-25 xs If nothing 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 8e44e3d4 2025-06-25 xs And we re\-run the configuration to see what\[cq]s happening.
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 8e44e3d4 2025-06-25 xs specified work directory to be created and act as an r7 repository.
217 8e44e3d4 2025-06-25 xs \f[I]Automated versioning 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 8e44e3d4 2025-06-25 xs \f[I]Note that it is possible to import additional 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 8e44e3d4 2025-06-25 xs environment, 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
250 8e44e3d4 2025-06-25 xs .SS Tmux configuration
253 8e44e3d4 2025-06-25 xs set \-g update\-environment \-r
255 8e44e3d4 2025-06-25 xs .SS Optional Shell configuration
256 8e44e3d4 2025-06-25 xs This is useful for handling multiple tmux sessions.
259 8e44e3d4 2025-06-25 xs \f[I]# Add this to the shell\[aq]s rc\f[R]
260 8e44e3d4 2025-06-25 xs \f[B]if\f[R] [ \-z \[dq]$TMUX\[dq] ]\f[B];\f[R] \f[B]then\f[R]
261 8e44e3d4 2025-06-25 xs \f[B]if\f[R] [ \-n \[dq]$SSH_TTY\[dq] ]\f[B];\f[R] \f[B]then\f[R]
262 8e44e3d4 2025-06-25 xs \f[B]if\f[R] [ \-z \[dq]$SSH_AUTH_SOCK\[dq] ]\f[B];\f[R] \f[B]then\f[R]
263 8e44e3d4 2025-06-25 xs export SSH_AUTH_SOCK=\[dq]$HOME/.ssh/.auth_socket\[dq]
265 8e44e3d4 2025-06-25 xs \f[B]if\f[R] [ ! \-S \[dq]$SSH_AUTH_SOCK\[dq] ]\f[B];\f[R] \f[B]then\f[R]
266 8e44e3d4 2025-06-25 xs eval $(ssh\-agent \-a $SSH_AUTH_SOCK) >/dev/null 2>&1
267 8e44e3d4 2025-06-25 xs echo $SSH_AGENT_PID >$HOME/.ssh/.auth_pid
269 8e44e3d4 2025-06-25 xs \f[B]if\f[R] [ \-z $SSH_AGENT_PID ]\f[B];\f[R] \f[B]then\f[R]
270 8e44e3d4 2025-06-25 xs export SSH_AGENT_PID=$(cat $HOME/.ssh/.auth_pid)
272 8e44e3d4 2025-06-25 xs ssh\-add \[dq]$SSH_ID\[dq] 2>/dev/null
276 35f45d45 2025-06-04 xs .SS Adding new hosts
277 35f45d45 2025-06-04 xs For adding a new host, the simplest way is to have pre\-configured
278 35f45d45 2025-06-04 xs \f[CR]authorized_keys\f[R] for the target user, it is then required to
279 35f45d45 2025-06-04 xs add it to the \f[CR]known_hosts\f[R] file.
280 35f45d45 2025-06-04 xs For that, it is possible to use r7 SSH functions:
283 35f45d45 2025-06-04 xs \&. $(command \-v r7) \f[I]# Sourcing r7\f[R]
284 35f45d45 2025-06-04 xs ssh\-accept\-new hostname
287 35f45d45 2025-06-04 xs If resetting the target\[cq]s user \f[CR]authorized_keys\f[R] file is
288 35f45d45 2025-06-04 xs needed, the following function can be used:
291 35f45d45 2025-06-04 xs \&. $(command \-v r7) \f[I]# Sourcing r7\f[R]
292 35f45d45 2025-06-04 xs ssh\-authorized\-keys\-reset hostname
295 35f45d45 2025-06-04 xs \f[I]\f[BI]Warning:\f[I] This will resets the SSH authorized_keys file
296 35f45d45 2025-06-04 xs for the target user (root, by default) and put the
297 35f45d45 2025-06-04 xs \f[CI].ssh/id_ed25519\-r7.pub\f[I] in place.\f[R]
299 35f45d45 2025-06-04 xs Once the host is accepted in the \f[CR]known_hosts\f[R] file, it\[cq]s
300 35f45d45 2025-06-04 xs possible to import it automatically.
301 35f45d45 2025-06-04 xs .SS Importing hosts configurations
302 35f45d45 2025-06-04 xs Avoiding to import the configuration manually is possible with the
303 35f45d45 2025-06-04 xs \f[CR]import\f[R] command:
306 35f45d45 2025-06-04 xs r7 import hostname
309 35f45d45 2025-06-04 xs Most common configuration files will be copied in a newly created
310 35f45d45 2025-06-04 xs \f[CR]nodes/hostname\f[R] sub\-directory.
311 35f45d45 2025-06-04 xs .SS Writing group files
312 8e44e3d4 2025-06-25 xs Group files collects functions related to the configuration of the
313 35f45d45 2025-06-04 xs operating system, networking, services, global and user configurations
314 35f45d45 2025-06-04 xs packages installations and application deployments.
316 35f45d45 2025-06-04 xs By specifying the execution prefix, the user determines the order of
317 35f45d45 2025-06-04 xs execution of the functions declared in the group file.
320 35f45d45 2025-06-04 xs service_A() \f[B]{\f[R]
321 35f45d45 2025-06-04 xs service A enable
322 35f45d45 2025-06-04 xs service A restart
325 35f45d45 2025-06-04 xs service_B() \f[B]{\f[R]
326 35f45d45 2025-06-04 xs service B enable
327 35f45d45 2025-06-04 xs service B restart
330 35f45d45 2025-06-04 xs state_A() \f[B]{\f[R]
331 35f45d45 2025-06-04 xs service A status
334 35f45d45 2025-06-04 xs doc_A() \f[B]{\f[R]
335 35f45d45 2025-06-04 xs echo \[dq]## Service A\[dq]
337 35f45d45 2025-06-04 xs echo \[dq]\- [url](http://test.org/)\[dq]
342 35f45d45 2025-06-04 xs \f[I]\f[BI]file\f[I]: \f[CI]groups/example1\f[I]\f[R]
344 35f45d45 2025-06-04 xs With the default prefix, \f[CR]install\f[R], \f[CR]state\f[R],
345 8e44e3d4 2025-06-25 xs \f[CR]doc\f[R], the function that will be executed are
346 35f45d45 2025-06-04 xs \f[CR]state_A\f[R] and \f[CR]doc_A\f[R].
347 35f45d45 2025-06-04 xs To test that group file with all the functions inside we can call r7 the
348 35f45d45 2025-06-04 xs following way:
351 35f45d45 2025-06-04 xs r7 \-P \[aq]service state doc\[aq] group example1 hostname
354 35f45d45 2025-06-04 xs Or using the \f[CR]\-a\f[R] flag which will create a prefix
355 35f45d45 2025-06-04 xs automatically with all functions present in the group file:
358 35f45d45 2025-06-04 xs r7 \-a group example1 hostname
361 35f45d45 2025-06-04 xs In a real situation, this example will have failing functions because
362 35f45d45 2025-06-04 xs the \f[CR]service\f[R] command may not be found or the services named
363 35f45d45 2025-06-04 xs \f[CR]A\f[R] or \f[CR]B\f[R] does not exist.
366 35f45d45 2025-06-04 xs ! (error 127) tools0:example1::service_A
367 35f45d45 2025-06-04 xs ! (error 127) tools0:example1::service_B
368 35f45d45 2025-06-04 xs ! (error 127) tools0:example1::state_A
369 35f45d45 2025-06-04 xs \- (ok) tools0:example1::doc_A
372 35f45d45 2025-06-04 xs We could force the group execution to stop using a combination of the
373 35f45d45 2025-06-04 xs \f[CR]\-e\f[R] flag and the \f[CR]error\f[R] group function.
376 35f45d45 2025-06-04 xs service_A() \f[B]{\f[R]
377 35f45d45 2025-06-04 xs service A enable \f[B]&&\f[R]
378 35f45d45 2025-06-04 xs service A restart \f[B]||\f[R]
379 35f45d45 2025-06-04 xs error unable to setup service A
382 35f45d45 2025-06-04 xs service_B() \f[B]{\f[R]
383 35f45d45 2025-06-04 xs service B enable \f[B]&&\f[R]
384 35f45d45 2025-06-04 xs service B restart \f[B]||\f[R]
385 35f45d45 2025-06-04 xs error unable to setup service B
388 35f45d45 2025-06-04 xs state_A() \f[B]{\f[R]
389 35f45d45 2025-06-04 xs service A status
392 35f45d45 2025-06-04 xs doc_A() \f[B]{\f[R]
393 35f45d45 2025-06-04 xs echo \[dq]## Service A\[dq]
395 35f45d45 2025-06-04 xs echo \[dq]\- [url](http://test.org/)\[dq]
400 35f45d45 2025-06-04 xs \f[I]\f[BI]file:\f[I] \f[CI]groups/example2\f[I]\f[R]
402 35f45d45 2025-06-04 xs Let\[cq]s run the updated example with the \f[CR]\-s\f[R] flag to
403 35f45d45 2025-06-04 xs trigger the summary output.
406 35f45d45 2025-06-04 xs rm \-fr _output
407 35f45d45 2025-06-04 xs r7 \-sea group example2 hostname
410 35f45d45 2025-06-04 xs This will produce something like the following:
413 35f45d45 2025-06-04 xs ! (error) tools0:example2::service_A
414 35f45d45 2025-06-04 xs ! (exit) tools0:example2::service_A
415 35f45d45 2025-06-04 xs \- (error 127) \- in tools0 example2 service_A (1748791986)
417 35f45d45 2025-06-04 xs /bin/sh: <stdin>[155]: service: not found
418 35f45d45 2025-06-04 xs :: 1748791986 tools0 ERROR unable to setup service A
420 2ae3e68f 2025-06-07 xs .SS Cleaning functions
421 2ae3e68f 2025-06-07 xs To remove a function from a group, we need to ensure that this function
422 2ae3e68f 2025-06-07 xs returned 0 for the last execution.
425 2ae3e68f 2025-06-07 xs state_function_to_remove() \f[B]{\f[R]
426 2ae3e68f 2025-06-07 xs \f[I]# old code\f[R]
427 2ae3e68f 2025-06-07 xs \f[I]# not used anymore\f[R]
432 2ae3e68f 2025-06-07 xs This would prevent for seeing potential past errors caused by this
433 2ae3e68f 2025-06-07 xs function in the summary output.
434 35f45d45 2025-06-04 xs .SS Using the r7 install functions
435 35f45d45 2025-06-04 xs The group library comes with the following functions that will allow
436 35f45d45 2025-06-04 xs installation of files and triggering actions if necessary:
437 35f45d45 2025-06-04 xs \f[CR]install\f[R], \f[CR]groupinstall\f[R], \f[CR]nodeinstall\f[R].
438 35f45d45 2025-06-04 xs They are all shortcuts to an internal \f[CR]r7_install\f[R] function,
439 35f45d45 2025-06-04 xs it\[cq]s just the wrappers changes directory to respectively
440 35f45d45 2025-06-04 xs \f[CR]/tmp/r7\f[R], \f[CR]/tmp/r7/groupname.dir/\f[R] and
441 35f45d45 2025-06-04 xs \f[CR]/tmp/r7/hostname/\f[R].
443 35f45d45 2025-06-04 xs If we want to install files from the group directory we will use
444 35f45d45 2025-06-04 xs something like:
447 35f45d45 2025-06-04 xs install_program() \f[B]{\f[R]
448 35f45d45 2025-06-04 xs groupinstall \-m 755 \-o root:bin my_program /usr/local/bin
452 35f45d45 2025-06-04 xs \f[I]We are supposing to have the file
453 35f45d45 2025-06-04 xs \f[CI]groups/example3.dir/my_program\f[I]\f[R]
455 35f45d45 2025-06-04 xs And if it\[cq]s something from node, we should use:
458 35f45d45 2025-06-04 xs install_program_config() \f[B]{\f[R]
459 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel my_config /etc
463 35f45d45 2025-06-04 xs We can now chain the \f[CR]install\f[R] functions to configuration
464 35f45d45 2025-06-04 xs checking and initialization of programs, services or network features
465 35f45d45 2025-06-04 xs like in the following example, in which we install \f[CR]ntp.conf\f[R]
466 35f45d45 2025-06-04 xs from the deployed node directory to \f[CR]/etc\f[R]:
469 35f45d45 2025-06-04 xs service_ntpd() \f[B]{\f[R]
470 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel ntpd.conf /etc \f[B]&&\f[R]
471 35f45d45 2025-06-04 xs ntpd \-n \f[B]&&\f[R]
472 35f45d45 2025-06-04 xs rcctl enable ntpd \f[B]&&\f[R]
473 35f45d45 2025-06-04 xs rcctl restart ntpd
476 35f45d45 2025-06-04 xs .SS Using the r7 node function
477 35f45d45 2025-06-04 xs We may want to avoid executing a function or parts of it if the node has
478 35f45d45 2025-06-04 xs no related files before executing the installation and actions handling
480 35f45d45 2025-06-04 xs This can be done with the help of the \f[CR]node\f[R] function.
483 35f45d45 2025-06-04 xs service_ntpd() \f[B]{\f[R]
484 35f45d45 2025-06-04 xs node ntpd.conf \f[B]&&\f[R]
485 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel ntpd.conf /etc \f[B]&&\f[R]
486 35f45d45 2025-06-04 xs ntpd \-n \f[B]&&\f[R]
487 35f45d45 2025-06-04 xs rcctl enable ntpd \f[B]&&\f[R]
488 35f45d45 2025-06-04 xs rcctl restart ntpd
492 35f45d45 2025-06-04 xs Here, \f[CR]node\f[R] will return \f[CR]31\f[R] if there is no file or
493 35f45d45 2025-06-04 xs directory called \f[CR]ntpd.conf\f[R] inside the deployed node directory
494 35f45d45 2025-06-04 xs (\f[CR]/tmp/r7/hostname\f[R]).
496 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
497 35f45d45 2025-06-04 xs when r7 will search for execution errors.
498 35f45d45 2025-06-04 xs This means \f[CR]30\f[R] and \f[CR]31\f[R] exit code are reserved to r7.
500 35f45d45 2025-06-04 xs In other terms, this will update the NTP daemon configuration only if
501 35f45d45 2025-06-04 xs \f[CR]ntpd.conf\f[R] is present in the node directory, otherwise it is
502 35f45d45 2025-06-04 xs kept by default, which is the system provided default
503 35f45d45 2025-06-04 xs \f[CR]ntpd.conf\f[R].
504 35f45d45 2025-06-04 xs .SS Sourcing specific files
505 8e44e3d4 2025-06-25 xs Here\[cq]s an example how to source additional shell from the deployed
506 35f45d45 2025-06-04 xs node directory, or elsewhere:
509 35f45d45 2025-06-04 xs service_sysrc() \f[B]{\f[R]
510 35f45d45 2025-06-04 xs sysrc dumpdev=NO
511 35f45d45 2025-06-04 xs sysrc kld_list=\[dq]vmm if_tuntap if_bridge nmdm\[dq]
512 35f45d45 2025-06-04 xs sysrc microcode_update_enable=YES
513 35f45d45 2025-06-04 xs sysrc mountd_enable=YES
514 35f45d45 2025-06-04 xs sysrc nfs_server_enable=YES
515 35f45d45 2025-06-04 xs sysrc ntpdate_enable=YES
516 35f45d45 2025-06-04 xs sysrc powerd_enable=YES
517 35f45d45 2025-06-04 xs sysrc rcshutdown_timeout=900
518 35f45d45 2025-06-04 xs sysrc rpcbind_enable=YES
519 35f45d45 2025-06-04 xs sysrc sshd_enable=YES
520 35f45d45 2025-06-04 xs sysrc zfs_enable=YES
521 35f45d45 2025-06-04 xs nodesource sysrc.local
525 35f45d45 2025-06-04 xs In this FreeBSD example, we configure the system RC globally with
526 35f45d45 2025-06-04 xs \f[CR]service_sysrc\f[R] which apply, if \f[CR]sysrc.local\f[R] is found
527 35f45d45 2025-06-04 xs in the root of the node directory, it\[cq]s sourcing in the current
528 35f45d45 2025-06-04 xs scope via the help of \f[CR]nodesource sysrc.local\f[R].
530 35f45d45 2025-06-04 xs The file \f[CR]nodes/hostname/sysrcl.local\f[R] contains the following:
533 35f45d45 2025-06-04 xs sysrc ifconfig_igb0=DHCP
534 35f45d45 2025-06-04 xs sysrc ifconfig_igb1=up
536 35f45d45 2025-06-04 xs .SS Other examples
537 35f45d45 2025-06-04 xs Inside the r7 release, a small example groups library can be found in
538 35f45d45 2025-06-04 xs the \f[CR]groups\f[R] directory, that can also be browsed in the \c
539 35f45d45 2025-06-04 xs .UR https://got.inda.re/?action=summary&path=r7.git
543 35f45d45 2025-06-04 xs .SS System shell profile
544 35f45d45 2025-06-04 xs Here we install the \f[CR]profile\f[R] file provided in the
545 35f45d45 2025-06-04 xs \f[CR]groupname.dir\f[R] directory or the profile provided by the node
549 35f45d45 2025-06-04 xs setup_profile() \f[B]{\f[R]
550 35f45d45 2025-06-04 xs groupinstall \-m 644 \-o root:wheel profile /etc
551 35f45d45 2025-06-04 xs node profile \f[B]&&\f[R]
552 35f45d45 2025-06-04 xs nodeinstall \-m 644 \-o root:wheel profile /etc
556 35f45d45 2025-06-04 xs Here we add new users:
559 35f45d45 2025-06-04 xs setup_users() \f[B]{\f[R]
560 35f45d45 2025-06-04 xs useradd user1 2>/dev/null \f[B]||\f[R] :
561 35f45d45 2025-06-04 xs useradd user2 2>/dev/null \f[B]||\f[R] :
565 35f45d45 2025-06-04 xs In the following example, we install a script and call it from a
566 35f45d45 2025-06-04 xs dedicated user crontab.
569 35f45d45 2025-06-04 xs mail_admins=admins\[at]test.org
571 35f45d45 2025-06-04 xs install_myscript() \f[B]{\f[R]
572 35f45d45 2025-06-04 xs groupinstall \-o root:bin \-m 755 myscript /usr/local/bin \f[B]&&\f[R]
573 35f45d45 2025-06-04 xs useradd \-d /var/empty \-s /sbin/nologin _myscript
574 35f45d45 2025-06-04 xs crontab \-u _myscript \- <<\-/
575 35f45d45 2025-06-04 xs MAILTO=$mail_admins
576 35f45d45 2025-06-04 xs */5 * * * * myscript
580 35f45d45 2025-06-04 xs .SS Consulting the output
581 35f45d45 2025-06-04 xs After the execution is done, the result are saved in the \f[CR]_run\f[R]
582 35f45d45 2025-06-04 xs directory, \f[CR]output\-dump\f[R] needs to be called to produce the
583 35f45d45 2025-06-04 xs current \f[CR]_output\f[R] structure.
585 35f45d45 2025-06-04 xs The r7 \f[CR]output\f[R] command can then be used to show specific
586 35f45d45 2025-06-04 xs output groups or functions:
592 35f45d45 2025-06-04 xs Will show the whole output of the latest groups deployments.
594 35f45d45 2025-06-04 xs This format can be used to match specific host, group or function:
597 35f45d45 2025-06-04 xs r7 output [hostname [groupname [funcname]]]
603 35f45d45 2025-06-04 xs $ r7 output tools0 OpenBSD state_packages\[rs]*
604 35f45d45 2025-06-04 xs \- tools0 OpenBSD state_packages_upgrades
606 35f45d45 2025-06-04 xs quirks\-7.103 signed on 2025\-05\-30T01:12:03Z
608 35f45d45 2025-06-04 xs \- tools0 OpenBSD state_packages_repository
610 35f45d45 2025-06-04 xs https://cdn.openbsd.org/pub/OpenBSD
613 35f45d45 2025-06-04 xs \f[I]Note that the \f[CI]output\f[I] function arguments are using
614 8e44e3d4 2025-06-25 xs shell\[cq]s case glob patterns.\f[R]
615 0198b57b 2025-06-10 xs .SS Active nodes
616 0198b57b 2025-06-10 xs A \f[CR]R7_WORKDIR/.active_nodes\f[R] file is automatically created when
617 0198b57b 2025-06-10 xs r7 tries to connect to a list of hosts via the \f[CR]group\f[R] command
619 0198b57b 2025-06-10 xs This serves as a cache of available hosts reachable via SSH login (the
620 0198b57b 2025-06-10 xs username is specified in the SSH configuration file).
622 0198b57b 2025-06-10 xs To add a previously non\-available host, simply remove the file and use
623 0198b57b 2025-06-10 xs \f[CR]group\f[R] (here via \f[CR]run\-config\f[R]):
626 0198b57b 2025-06-10 xs rm .active_nodes
627 0198b57b 2025-06-10 xs r7 run\-config
629 35f45d45 2025-06-04 xs .SS r7 command line
630 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
633 35f45d45 2025-06-04 xs r7 [options] [command [arguments...]]
637 35f45d45 2025-06-04 xs \f[B]\-h\f[R] Show usage and exit
639 35f45d45 2025-06-04 xs \f[B]\-d\f[R] Enable debug mode
641 35f45d45 2025-06-04 xs \f[B]\-i\f[R] Specify the SSH identity file
643 35f45d45 2025-06-04 xs \f[B]\-F\f[R] Specify the SSH client configuration file
645 35f45d45 2025-06-04 xs \f[B]\-w\f[R] Set the work directory where \f[CR]./nodes\f[R] and
646 35f45d45 2025-06-04 xs \f[CR]./groups\f[R] can be found
648 35f45d45 2025-06-04 xs \f[B]\-r\f[R] Set the run directory (default: \f[CR]./_run\f[R])
650 35f45d45 2025-06-04 xs \f[B]\-o\f[R] Set the output directory (default: \f[CR]./_output\f[R])
652 35f45d45 2025-06-04 xs \f[B]\-c\f[R] Specify the site configuration file (default:
653 35f45d45 2025-06-04 xs \f[CR]./site\-config\f[R])
655 35f45d45 2025-06-04 xs \f[B]\-n\f[R] Enable dry run mode; prevents any modification on hosts
657 35f45d45 2025-06-04 xs \f[B]\-e\f[R] Exit the group execution on the error function
659 35f45d45 2025-06-04 xs \f[B]\-p\f[R] Run each host in parallel per group call
661 35f45d45 2025-06-04 xs \f[B]\-O\f[R] Show output interactively
663 4296d94d 2025-06-07 xs \f[B]\-P\f[R] Specify a prefix, can contain whole function names
665 35f45d45 2025-06-04 xs \f[B]\-a\f[R] Select all available prefixes for a group command
667 35f45d45 2025-06-04 xs \f[B]\-s\f[R] Apply output\-dump and summary after a group command
672 35f45d45 2025-06-04 xs lw(18.7n) lw(51.3n).
680 35f45d45 2025-06-04 xs \f[B]run\-config\f[R]
682 35f45d45 2025-06-04 xs Run the site configuration
685 35f45d45 2025-06-04 xs \f[B]group\f[R]
687 35f45d45 2025-06-04 xs Deploy specified group to hosts
690 35f45d45 2025-06-04 xs \f[B]output\-dump\f[R]
692 35f45d45 2025-06-04 xs Dump the run directory to the output directory
695 35f45d45 2025-06-04 xs \f[B]output\f[R]
697 35f45d45 2025-06-04 xs Consult the output
700 35f45d45 2025-06-04 xs \f[B]summary\f[R]
702 35f45d45 2025-06-04 xs Produce a summary of errors and changes
705 35f45d45 2025-06-04 xs \f[B]digraph\-host\f[R]
707 35f45d45 2025-06-04 xs Produce a dot digraph for hosts
710 35f45d45 2025-06-04 xs \f[B]digraph\-ssh\f[R]
712 35f45d45 2025-06-04 xs Produce a dot digraph of SSH ID\[cq]s, users and nodes relations
715 35f45d45 2025-06-04 xs \f[B]import\f[R]
717 35f45d45 2025-06-04 xs Import TARGET host in the current nodes directory
720 35f45d45 2025-06-04 xs \f[B]info\f[R]
722 35f45d45 2025-06-04 xs Default command showing active nodes and summary
725 35f45d45 2025-06-04 xs \f[B]init\f[R]
727 35f45d45 2025-06-04 xs Initialize a new work directory
730 35f45d45 2025-06-04 xs .SS Environment
734 35f45d45 2025-06-04 xs lw(9.7n) lw(31.4n) lw(29.0n).
738 35f45d45 2025-06-04 xs Default value
748 35f45d45 2025-06-04 xs Enable debug mode
755 35f45d45 2025-06-04 xs Enable dry\-run mode
758 35f45d45 2025-06-04 xs R7_GROUP_ALLPREFIX
762 35f45d45 2025-06-04 xs Group selects all available prefix
765 35f45d45 2025-06-04 xs R7_GROUP_SUMMARY
769 35f45d45 2025-06-04 xs Enable output\-dump and summary after group execution
772 35f45d45 2025-06-04 xs R7_GROUP_EXITONERROR
776 35f45d45 2025-06-04 xs Enable exit on error function
783 35f45d45 2025-06-04 xs Enable group nodes parallel execution
788 35f45d45 2025-06-04 xs install state doc
790 35f45d45 2025-06-04 xs Set the r7 group execution prefix
793 35f45d45 2025-06-04 xs R7_SHOWOUTPUT
797 35f45d45 2025-06-04 xs Show interactive output
804 35f45d45 2025-06-04 xs Set the r7 repository path
807 35f45d45 2025-06-04 xs R7_SITE_CONFIG
809 35f45d45 2025-06-04 xs R7_WORKDIR/site\-config
811 35f45d45 2025-06-04 xs Set the r7 \f[CR]site\-config\f[R] path
816 35f45d45 2025-06-04 xs R7_WORKDIR/_output
818 35f45d45 2025-06-04 xs Set the r7 output directory path
821 35f45d45 2025-06-04 xs SSH_CONFIG_DIR
823 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh
825 35f45d45 2025-06-04 xs Set the SSH configuration directory path
828 35f45d45 2025-06-04 xs SSH_CONFIG_FILE
830 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh/config
832 35f45d45 2025-06-04 xs Set the SSH configuration file path
835 35f45d45 2025-06-04 xs SSH_CONTROL_DIR
837 35f45d45 2025-06-04 xs SSH_CONFIG_DIR/control
839 35f45d45 2025-06-04 xs Set the SSH control dir path
842 35f45d45 2025-06-04 xs SSH_IDENTITY_FILE
844 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh/id_ed25519_r7
846 35f45d45 2025-06-04 xs Set the SSH identity file
849 35f45d45 2025-06-04 xs SSH_KNOWN_HOSTS
851 35f45d45 2025-06-04 xs R7_WORKDIR/.ssh/known_hosts
853 35f45d45 2025-06-04 xs Set the SSH known hosts file
856 35f45d45 2025-06-04 xs SSH_CONNECT_TIMEOUT
860 35f45d45 2025-06-04 xs Set the SSH connect timeout
863 35f45d45 2025-06-04 xs .SS Group variables
864 35f45d45 2025-06-04 xs Those variables are available during the execution of th group
865 35f45d45 2025-06-04 xs file\[cq]s functions.
879 35f45d45 2025-06-04 xs Current run trace ID
884 35f45d45 2025-06-04 xs Current group name being executed
889 35f45d45 2025-06-04 xs Cause the error function to exit if equals \f[CR]yes\f[R]
894 35f45d45 2025-06-04 xs Contains the output of \f[CR]nodename\f[R]
899 35f45d45 2025-06-04 xs Contains the output of \f[CR]nodedir\f[R]
904 35f45d45 2025-06-04 xs Contains the output of \f[CR]groupdir\f[R]
907 35f45d45 2025-06-04 xs .SS Group functions
908 35f45d45 2025-06-04 xs Those functions are accessible during the execution of the group
909 35f45d45 2025-06-04 xs file\[cq]s functions.
910 22b54c5e 2025-06-04 xs Non documented functions are reserved for internal use.
932 35f45d45 2025-06-04 xs groupinstalldir
934 35f45d45 2025-06-04 xs nodeinstalldir
944 2bd0b615 2025-06-06 xs grouptemplate
950 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Append a trace containing the current
951 35f45d45 2025-06-04 xs node name and \f[CR]trace_id\f[R]
953 35f45d45 2025-06-04 xs \f[B]Usage:\f[R]
956 35f45d45 2025-06-04 xs trace [string...]
959 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Trace an error message that will
960 35f45d45 2025-06-04 xs inform the user of an event in the summary output, exit the group
961 35f45d45 2025-06-04 xs execution if \f[CR]\-e\f[R] is set
963 35f45d45 2025-06-04 xs \f[B]Usage:\f[R]
966 35f45d45 2025-06-04 xs error [string...]
969 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns true if the argument is an
970 35f45d45 2025-06-04 xs existing file or directory inside \f[CR]/tmp/r7/$(nodename)\f[R], else,
973 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
976 35f45d45 2025-06-04 xs node [filename\f[B]|\f[R]dirname]
979 8e44e3d4 2025-06-25 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the small host name of the
982 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
988 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns \f[CR]/tmp/r7/$(nodename)\f[R]
990 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
996 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns
997 35f45d45 2025-06-04 xs \f[CR]/tmp/r7/$groupname.dir\f[R]
999 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1005 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to \f[CR]/tmp/r7\f[R]
1006 35f45d45 2025-06-04 xs and install files if changed and sets mode and owner, returns true if
1007 35f45d45 2025-06-04 xs the file changed, otherwise returns 30
1009 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1012 35f45d45 2025-06-04 xs install [\-o owner] [\-m mode] source destintaion
1014 35f45d45 2025-06-04 xs .SS groupinstall
1015 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1016 35f45d45 2025-06-04 xs \f[CR].dir\f[R] directory in \f[CR]/tmp/r7\f[R] then performs like
1017 35f45d45 2025-06-04 xs \f[CR]install\f[R]
1019 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1022 35f45d45 2025-06-04 xs groupinstall [\-o owner] [\-m mode] source destintaion
1024 35f45d45 2025-06-04 xs .SS nodeinstall
1025 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current node
1026 35f45d45 2025-06-04 xs directory in \f[CR]/tmp/r7\f[R] then performs like \f[CR]install\f[R]
1028 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1031 35f45d45 2025-06-04 xs nodeinstall [\-o owner] [\-m mode] source destintaion
1033 35f45d45 2025-06-04 xs .SS installdir
1034 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Install directory calling
1035 35f45d45 2025-06-04 xs \f[CR]install\f[R] for each file and checking for permissions changes.
1037 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1040 35f45d45 2025-06-04 xs installdir [\-o fileowner] [\-m filemode] [\-O dirowner] [\-O dirmode] source
1043 35f45d45 2025-06-04 xs .SS groupinstalldir
1044 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1045 8e44e3d4 2025-06-25 xs directory then call installdir
1047 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1050 35f45d45 2025-06-04 xs groupinstalldir [\-o fileowner] [\-m filemode] [\-O dirowner] [\-O dirmode] source
1053 35f45d45 2025-06-04 xs .SS nodeinstalldir
1054 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1055 8e44e3d4 2025-06-25 xs directory then call installdir
1057 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1060 35f45d45 2025-06-04 xs nodeinstalldir [\-o fileowner] [\-m filemode] [\-O dirowner] [\-O dirmode] source
1064 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Source a POSIX shell file in the
1065 35f45d45 2025-06-04 xs current execution
1067 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1070 8e44e3d4 2025-06-25 xs fsource filename
1072 35f45d45 2025-06-04 xs .SS groupsource
1073 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1074 09bfe2aa 2025-06-25 xs directory then call fsource with the file name as argument, produces an
1075 35f45d45 2025-06-04 xs error if filename is not found from the group directory
1077 2bd0b615 2025-06-06 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1080 35f45d45 2025-06-04 xs groupsource filename
1082 35f45d45 2025-06-04 xs .SS nodesource
1083 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1084 09bfe2aa 2025-06-25 xs directory then call node and fsource with the file name as argument
1085 35f45d45 2025-06-04 xs without producing an error if the filename is not found
1087 2bd0b615 2025-06-06 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1090 35f45d45 2025-06-04 xs nodesource filename
1092 2bd0b615 2025-06-06 xs .SS template
1093 2bd0b615 2025-06-06 xs \f[B]\f[BI]Description:\f[B]\f[R] Template the files passed as arguments
1094 2bd0b615 2025-06-06 xs with the current environment or by sourcing a specified file
1096 2bd0b615 2025-06-06 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1099 2bd0b615 2025-06-06 xs template [\-s sourcefile] [file...]
1101 2bd0b615 2025-06-06 xs .SS grouptemplate
1102 2bd0b615 2025-06-06 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current group
1103 2bd0b615 2025-06-06 xs directory before calling template
1105 2bd0b615 2025-06-06 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1108 2bd0b615 2025-06-06 xs grouptemplate [\-s sourcefile] [file...]
1110 2bd0b615 2025-06-06 xs .SS nodetemplate
1111 2bd0b615 2025-06-06 xs \f[B]\f[BI]Description:\f[B]\f[R] Change directory to the current node
1112 2bd0b615 2025-06-06 xs directory before calling template
1114 2bd0b615 2025-06-06 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1117 2bd0b615 2025-06-06 xs nodetemplate [\-s sourcefile] [file...]
1119 35f45d45 2025-06-04 xs .SH r7 library
1120 35f45d45 2025-06-04 xs Usable from the r7 \f[CR]site\-config\f[R] file or sourced in the
1121 35f45d45 2025-06-04 xs current shell using:
1124 35f45d45 2025-06-04 xs \&. $(command \-v r7)
1127 35f45d45 2025-06-04 xs Each functions are declared with underscore names and aliased with
1129 35f45d45 2025-06-04 xs Shorter aliases are also available, list all declared aliases with:
1135 22b54c5e 2025-06-04 xs Non documented functions are reserved for internal use.
1136 35f45d45 2025-06-04 xs .SS Interface
1144 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Default command showing active nodes
1145 35f45d45 2025-06-04 xs and summary, ran when sourced
1147 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1153 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Shows the command line help
1155 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1160 35f45d45 2025-06-04 xs .SS SSH functions
1170 35f45d45 2025-06-04 xs ssh\-known\-hosts
1172 35f45d45 2025-06-04 xs ssh\-authorized\-keys\-reset
1174 35f45d45 2025-06-04 xs ssh\-accept\-new
1176 35f45d45 2025-06-04 xs ssh\-control\-master\-clean
1182 35f45d45 2025-06-04 xs ssh\-authorized\-keys
1184 35f45d45 2025-06-04 xs ssh\-ids\-hosts
1188 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Resets the SSH agent environment and
1189 35f45d45 2025-06-04 xs issues ssh\-add for SSH_IDENTITY_FILE
1191 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1197 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] r7 openrsync, rsync, scp wrapper;
1198 35f45d45 2025-06-04 xs selected in order of availability
1200 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1203 35f45d45 2025-06-04 xs copy SRC DST
1206 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] r7 SSH wrapper; behaves like the
1207 35f45d45 2025-06-04 xs standard OpenSSH command
1209 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1212 35f45d45 2025-06-04 xs ssh OPTION HOST
1214 35f45d45 2025-06-04 xs .SS ssh\-debug
1215 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] r7 SSH with debug connection mode for
1216 35f45d45 2025-06-04 xs a specific HOST
1218 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1221 35f45d45 2025-06-04 xs ssh\-debug HOST
1223 35f45d45 2025-06-04 xs .SS ssh\-known\-hosts
1224 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Calls ssh\-keygen to dump the SSH
1225 35f45d45 2025-06-04 xs known_hosts file
1227 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1230 35f45d45 2025-06-04 xs ssh\-known\-hosts
1232 35f45d45 2025-06-04 xs .SS ssh\-authorized\-keys\-reset
1233 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Resets SSH authorized_keys on the
1234 35f45d45 2025-06-04 xs specified HOST
1236 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1239 35f45d45 2025-06-04 xs ssh\-authorized\-keys\-reset HOST
1241 35f45d45 2025-06-04 xs .SS ssh\-accept\-new
1242 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Adds a new host entry in the SSH
1243 35f45d45 2025-06-04 xs known_hosts file
1245 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1248 35f45d45 2025-06-04 xs ssh\-accept\-new HOST
1250 35f45d45 2025-06-04 xs .SS ssh\-control\-master\-clean
1251 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Cleans the SSH control master
1254 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1257 35f45d45 2025-06-04 xs ssh\-control\-master\-clean
1259 35f45d45 2025-06-04 xs .SS ssh\-users
1260 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Searches nodes for authorized_keys_*
1261 35f45d45 2025-06-04 xs and returns a list of users
1263 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1268 35f45d45 2025-06-04 xs .SS ssh\-ids
1269 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns sorted SSH IDs
1271 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1276 35f45d45 2025-06-04 xs .SS ssh\-authorized\-keys
1277 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the list of authorized_keys
1280 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1283 35f45d45 2025-06-04 xs ssh\-authorized\-keys
1285 35f45d45 2025-06-04 xs .SS ssh\-ids\-hosts
1286 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns SSH IDs along with matching
1287 8e44e3d4 2025-06-25 xs key file and host name
1289 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1292 35f45d45 2025-06-04 xs ssh\-ids\-hosts
1294 35f45d45 2025-06-04 xs .SS Deployment functions
1298 35f45d45 2025-06-04 xs nodes\-active
1306 35f45d45 2025-06-04 xs group\-functions
1308 805718b0 2025-06-05 xs group\-functions\-all
1314 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of available nodes
1316 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1321 35f45d45 2025-06-04 xs .SS nodes\-active
1322 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of active nodes by
1323 0198b57b 2025-06-10 xs detecting SSH availability (a login is done), writes
1324 0198b57b 2025-06-10 xs \f[CR]R7_WORKDIR/.active_nodes\f[R] containing the available hosts
1326 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1329 35f45d45 2025-06-04 xs nodes\-active
1331 35f45d45 2025-06-04 xs .SS run\-config
1332 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Executes \f[CR]R7_SITE_CONFIG\f[R] in
1333 35f45d45 2025-06-04 xs the loaded environment
1335 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1341 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of active nodes
1342 35f45d45 2025-06-04 xs matching a list of grep REGEXES
1344 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1347 35f45d45 2025-06-04 xs members REGEXES
1350 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Applies GROUPNAME functions (in prefix
1351 35f45d45 2025-06-04 xs order) to the provided MEMBERS list
1353 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1356 35f45d45 2025-06-04 xs group GROUPNAME MEMBERS
1358 35f45d45 2025-06-04 xs .SS group\-functions
1359 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of functions found in
1360 35f45d45 2025-06-04 xs the specified GROUPNAME
1362 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1365 35f45d45 2025-06-04 xs group\-functions GROUPNAME
1367 805718b0 2025-06-05 xs .SS group\-functions\-all
1368 805718b0 2025-06-05 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of all group functions
1369 805718b0 2025-06-05 xs found in the current \f[CR]R7_WORKDIR/groups\f[R] directory with the
1370 805718b0 2025-06-05 xs \f[CR]group_name::function_name\f[R] format
1372 805718b0 2025-06-05 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1375 805718b0 2025-06-05 xs group\-functions\-all
1378 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Sets the current PREFIX for matching
1379 4296d94d 2025-06-07 xs function names, can match for the whole unique name in the group, for
1380 4296d94d 2025-06-07 xs executing one specified function only
1382 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1385 35f45d45 2025-06-04 xs prefix PREFIX
1387 35f45d45 2025-06-04 xs .SS Text output functions
1389 35f45d45 2025-06-04 xs output\-dump
1391 35f45d45 2025-06-04 xs output\-latest
1393 35f45d45 2025-06-04 xs output\-status
1395 35f45d45 2025-06-04 xs output\-duration
1399 35f45d45 2025-06-04 xs output\-diffs
1401 35f45d45 2025-06-04 xs output\-permissions
1403 35f45d45 2025-06-04 xs output\-errors
1407 35f45d45 2025-06-04 xs trace\-id\-last
1410 35f45d45 2025-06-04 xs .SS output\-dump
1411 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Dumps R7_RUNDIR to R7_OUTPUTDIR
1413 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1416 35f45d45 2025-06-04 xs output\-dump
1418 35f45d45 2025-06-04 xs .SS output\-latest
1419 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of outputs from the
1422 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1425 35f45d45 2025-06-04 xs output\-latest
1427 35f45d45 2025-06-04 xs .SS output\-status
1428 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of current dumped
1429 35f45d45 2025-06-04 xs functions exit status codes
1431 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1434 35f45d45 2025-06-04 xs output\-status
1436 35f45d45 2025-06-04 xs .SS output\-duration
1437 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a list of durations of
1438 35f45d45 2025-06-04 xs executed groups
1440 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1443 35f45d45 2025-06-04 xs output\-duration
1446 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Shows the dumped output matching HOST,
1447 35f45d45 2025-06-04 xs GROUPNAME, and FUNCTION (or any if unspecified)
1449 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1452 35f45d45 2025-06-04 xs output HOST GROUPNAME FUNCTION
1454 35f45d45 2025-06-04 xs .SS trace\-id\-last
1455 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the latest execution trace_id
1457 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1460 35f45d45 2025-06-04 xs trace\-id\-last
1462 35f45d45 2025-06-04 xs .SS output\-diffs
1463 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the diffs from the latest
1466 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1469 35f45d45 2025-06-04 xs output\-diffs
1471 35f45d45 2025-06-04 xs .SS output\-permissions
1472 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the latest permission changes
1474 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1477 35f45d45 2025-06-04 xs output\-permissions
1479 35f45d45 2025-06-04 xs .SS output\-errors
1480 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns the latest errors detected
1482 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1485 35f45d45 2025-06-04 xs output\-errors
1488 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Produces a summary of errors, diffs,
1489 35f45d45 2025-06-04 xs and permission outputs
1491 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1496 35f45d45 2025-06-04 xs .SS Digraph output
1498 35f45d45 2025-06-04 xs digraph\-host
1500 35f45d45 2025-06-04 xs digraph\-ssh\-id\-hosts
1503 35f45d45 2025-06-04 xs .SS digraph\-host
1504 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a directed graph (in DOT
1505 35f45d45 2025-06-04 xs format) showing relations among groups, functions, and nodes
1507 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1510 35f45d45 2025-06-04 xs digraph\-host
1512 35f45d45 2025-06-04 xs .SS digraph\-ssh\-id\-hosts
1513 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Returns a directed graph (in DOT
1514 35f45d45 2025-06-04 xs format) of relations between SSH IDs and hosts
1516 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1519 35f45d45 2025-06-04 xs digraph\-ssh\-id\-hosts
1521 35f45d45 2025-06-04 xs .SS HTML output
1525 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Retunrs a report page with the content
1526 35f45d45 2025-06-04 xs of \f[CR]README.md\f[R] in HTML format
1528 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1535 35f45d45 2025-06-04 xs .SS Node importing
1539 35f45d45 2025-06-04 xs \f[B]\f[BI]Description:\f[B]\f[R] Import configuration files from a
1542 35f45d45 2025-06-04 xs \f[B]\f[BI]Usage:\f[B]\f[R]
1549 35f45d45 2025-06-04 xs .SS Technical notes
1551 8e44e3d4 2025-06-25 xs Supported shells are ksh93, oksh, yash and bash
1553 8e44e3d4 2025-06-25 xs Supported target platforms are POSIX compatible systems
1556 8e44e3d4 2025-06-25 xs \f[CR]/bin/sh\f[R] or compatible must be set for the user\[cq]s shell
1557 8e44e3d4 2025-06-25 xs (which is usually the case by default)
1559 8e44e3d4 2025-06-25 xs \f[CR]/tmp\f[R] must be writable by the user
1562 8e44e3d4 2025-06-25 xs Supported control node platforms are supposed to be POSIX compatible
1563 8e44e3d4 2025-06-25 xs systems but currently limited to BSD\[cq]s, Darwin and GNU/Linux
1566 494d76b7 2025-06-10 xs Dependencies are awk, OpenSSH and column
1568 8e44e3d4 2025-06-25 xs Optional dependencies are openrsync, rsync, column, graphviz and pandoc
1571 dd5b0398 2025-06-25 xs The r7 importer supports the following platforms:
1574 8e44e3d4 2025-06-25 xs Alpine Linux
1582 8e44e3d4 2025-06-25 xs DragonFlyBSD
1613 8e44e3d4 2025-06-25 xs The provided group library is shared as additional examples WITH NO
1614 1a4cdaf8 2025-06-05 xs WARRANTIES of the documentation and contain the following third\-party
1615 1a4cdaf8 2025-06-05 xs files under the ISC License.
1616 f976c0b3 2025-06-05 xs Copyright information are indicated in the LICENSE section of related
1619 f976c0b3 2025-06-05 xs \f[CR]pf\-badhost.sh\f[R]
1621 f976c0b3 2025-06-05 xs \f[CR]unbound\-adblock.sh\f[R]
1623 f976c0b3 2025-06-05 xs \f[CR]http\-ban.sh\f[R]
1625 8b145b67 2025-06-04 xs The project is shared under the terms of the ISC license.
1626 8b145b67 2025-06-04 xs Any version previous \f[CR]0.1.0\f[R] needs to be considered obsolete
1627 8b145b67 2025-06-04 xs and should not be redistributed.
1628 8b145b67 2025-06-04 xs History in the GIT repository is kept for transparency purpose only.
1630 8b145b67 2025-06-04 xs Below is a copy of the applicable license:
1635 8b145b67 2025-06-04 xs Copyright 2025 xs <xs\[at]inda.re>
1637 8b145b67 2025-06-04 xs Permission to use, copy, modify, and/or distribute this software for any
1638 8b145b67 2025-06-04 xs purpose with or without fee is hereby granted, provided that the above
1639 8b145b67 2025-06-04 xs copyright notice and this permission notice appear in all copies.
1641 8b145b67 2025-06-04 xs THE SOFTWARE IS PROVIDED \[dq]AS IS\[dq] AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
1642 8b145b67 2025-06-04 xs REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
1643 8b145b67 2025-06-04 xs FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
1644 8b145b67 2025-06-04 xs INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
1645 8b145b67 2025-06-04 xs LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
1646 8b145b67 2025-06-04 xs OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1647 8b145b67 2025-06-04 xs PERFORMANCE OF THIS SOFTWARE.
