[scanner] initial documentation

Note: still needs to patch main cdist(1) manpage
This commit is contained in:
fnux 2021-04-26 14:39:26 +02:00
parent 3a9dd5b166
commit 2232435c22
No known key found for this signature in database
GPG key ID: 4502C902C00A1E12
3 changed files with 100 additions and 32 deletions

View file

@ -19,38 +19,6 @@
#
#
#
# Interface to be implemented:
# - cdist scan --mode {scan, trigger, install, config}, --mode can be repeated
# scan: scan / listen for icmp6 replies
# trigger: send trigger to multicast
# config: configure newly detected hosts
# install: install newly detected hosts
#
# Scanner logic
# - save results to configdir:
# basedir = ~/.cdist/scan/<ipv6-address>
# last_seen = ~/.cdist/scan/<ipv6-address>/last_seen -- record unix time
# or similar
# last_configured = ~/.cdist/scan/<ipv6-address>/last_configured -- record
# unix time or similar
# last_installed = ~/.cdist/scan/<ipv6-address>/last_configured -- record
# unix time or similar
#
#
#
#
# cdist scan --list
# Show all known hosts including last seen flag
#
# Logic for reconfiguration:
#
# - record when configured last time
# - introduce a parameter --reconfigure-after that takes time argument
# - reconfigure if a) host alive and b) reconfigure-after time passed
#
from multiprocessing import Process
import os
import logging

99
docs/src/cdist-scan.rst Normal file
View file

@ -0,0 +1,99 @@
Scan
=====
Description
-----------
Runs cdist as a daemon that discover/watch on hosts and reconfigure them
periodically. It is especially useful in netboot-based environment where hosts
boot unconfigured, and to ensure your infrastructure stays in sync with your
configuration.
This feature is still consider to be in **beta** stage.
Usage (Examples)
----------------
Discover hosts on local network and configure those whose name is resolved by
the name mapper script.
.. code-block:: sh
$ cdist scan --beta --interface eth0 \
--mode scan --name-mapper path/to/script \
--mode trigger --mode config
List known hosts and exit.
.. code-block:: sh
$ cdist scan --beta --list --name-mapper path/to/script
Please refer to `cdist(1)` for a detailed list of parameters.
Modes
-----
The scanner has 3 modes that can be independently toggled. If the `--mode`
parameter is not specified, only `tigger` and `scan` are enabled (= hosts are
not configured).
trigger
Send ICMPv6 requests to specific hosts or broadcast over IPv6 link-local to
trigger detection by the `scan` module.
scan
Watch for incoming ICMPv6 replies and optionally configure detected hosts.
config
Enable configuration of hosts detected by `scan`.
Name Mapper Script
------------------
The name mapper script takes an IPv6 address as first argument and writes the
resolved name to stdout - if any. The script must be executable.
Simplest script:
.. code-block:: sh
#!/bin/sh
case "$1" in
"fe80::20d:b9ff:fe57:3524")
printf "my-host-01"
;;
"fe80::7603:bdff:fe05:89bb")
printf "my-host-02"
;;
esac
Resolving name from `PTR` DNS record:
.. code-block:: sh
#!/bin/sh
for cmd in dig sed; do
if ! command -v $cmd > /dev/null; then
exit 1
fi
done
dig +short -x "$1" | sed -e 's/.$//'
Trigger Source Script
---------------------
This script returns a list of addresses (separated by a newline) to be used by
`trigger` mode. It is not used to map names. The script must be executable.
Simplest script:
.. code-block:: sh
#!/bin/sh
cat << EOF
server1.domain.tld
server2.domain.tld
server3.domain.tld
EOF

View file

@ -34,6 +34,7 @@ It natively supports IPv6 since the first release.
cdist-parallelization
cdist-inventory
cdist-preos
cdist-scan
cdist-integration
cdist-reference
cdist-best-practice