X-Git-Url: https://ruderich.org/simon/gitweb/?a=blobdiff_plain;f=README.adoc;h=6d85d51bb297dd8ce9abd085f5c198b26a26a191;hb=e4c6a178848145c8dba68ed054cbb48dcecccf65;hp=8f1684f0d6aed68ba41ae6e0da7fcb2441bf9d68;hpb=17be12938b1a5b5544fed65e2fc78220e75ff5d8;p=safcm%2Fsafcm.git diff --git a/README.adoc b/README.adoc index 8f1684f..6d85d51 100644 --- a/README.adoc +++ b/README.adoc @@ -17,12 +17,13 @@ It can also be read as "saf(e) configuration management" as it combines simplicity and safety in the following principles: - *fail fast*: catch (user) errors as soon as possible; host configuration - (including templates) evaluated locally to prevent partial configuration; + (including templates) is evaluated locally to prevent partial configuration; errors immediately abort the synchronization -- *remote hosts untrusted*: clear security boundary between local and remote - host; data used from remote hosts is marked (detected groups); all output - from remote hosts is escaped to prevent terminal injection attacks; each - host only receives its configuration and no data from other hosts +- *remote hosts are untrusted*: clear security boundary between local and + remote host; data used from remote hosts is marked tainted (detected + groups); all output from remote hosts is escaped to prevent terminal + injection attacks; each host only receives its own configuration and no data + from other hosts - *safety and security*: create files with "write to temporary file", "sync", "rename", "sync directory" for atomicity and durability; guard against symlink and other TOCTOU attacks; extensive test suite @@ -43,33 +44,34 @@ contains the files, packages, services and commands which should be applied to all hosts which are members of this group. The configuration of all managed hosts is stored in a directory on the local -host. Safcm uses https://yaml.org/[YAML] for all configuration files for its -natural syntax. Strict type checks prevent potential pitfalls of more complex -YAML syntax. Tasks like copying a file require no explicit configuration (see -the documentation for details). - -Files consist of a tree of files (regular files and symbolic links) and -directories with permissions, user/group and content. Files can use -_templates_ for dynamic content depending on the host or its groups. Each path -can have _trigger_ commands which are executed when the path itself or any -sub-paths are modified during synchronization. Packages are package names of -the remote operating system. Services are service names of the remote -operating system. Commands are shell commands passed to `/bin/sh`. - -When files with the same path are present in multiple groups of a host an -explicit _group order_ must be configured to resolve the conflict. Conflicts -do not apply to packages and services which are simply merged from all groups. -Commands are appended so that the same command can be executed multiple times. - -To sync the configuration to a remote host the local `safcm` binary connects +host. Safcm uses https://yaml.org/[YAML] for all configuration files. Strict +type checks prevent potential pitfalls due to the complex YAML syntax. Tasks +like copying a file require no explicit configuration. + +Files (regular files and symbolic links) and directories, including +permissions, user/group and content are kept in a regular filesystem tree on +the local host. Files can use _templates_ for dynamic content depending on the +host or its groups. Each path can have _trigger_ commands which are executed +when the path itself or any sub-paths are modified during synchronization. +Packages are package names of the remote operating system. Services are +service names of the remote operating system. Commands are shell commands +passed to `/bin/sh`. + +When files with the same path are present in multiple groups of a host, an +explicit _group priority_ must be configured to resolve the conflict. +Conflicts do not apply to packages and services which are simply merged from +all groups. Commands are appended so that the same command can be executed +multiple times. + +To sync the configuration to a remote host, the local `safcm` binary connects to it via `ssh`. It then copies a _remote helper_ binary to `/tmp` on the -remote host to later perform the actual sync. If the remote helper is already -present, has the proper checksum, permissions and user then the copy is -skipped. `safcm` then queries the remote host for information, including -operating system, architecture and detected groups. With all relevant data -collected it assigns the host its groups, evaluates the configuration -including templates and finally sends it to the remote helper which then -applies it to the remote host. +remote host to perform the actual sync later. If the remote helper is already +present, has the proper checksum, permissions and user/group then the copying +step is skipped. `safcm` then queries the remote host for information, +including operating system, architecture and detected groups. With all +relevant data collected, it assigns the host to its groups, evaluates the +configuration including templates and finally sends the new configuration to +the remote helper which then applies it to the remote host. The synchronization happens in the following order which cannot be changed: @@ -103,10 +105,10 @@ future, others are due to the design of safcm. `/root` which often have strict permissions by default, so carefully check the diff output for unwanted changes. -- Full file content of all files is sent to the remote during synchronization. - This makes it impractical to synchronize large files with safcm. As most - configuration files are small this shouldn't be an issue for common - scenarios. +- The full file content of all files is sent to the remote during + synchronization. This makes it impractical to synchronize large files with + safcm. Since most configuration files are small this shouldn't be an issue + for common scenarios. - Quoted strings in the output are quoted using Go's `%q` format string. The result is similar -- but not identical -- to quoted strings in regular shell @@ -121,7 +123,7 @@ future, others are due to the design of safcm. == Requirements -- build the `safcm` binary and remote helper: +- to build the `safcm` binary and remote helper: * Go >= 1.16 * GNU make