X-Git-Url: https://ruderich.org/simon/gitweb/?a=blobdiff_plain;f=README.adoc;h=6d85d51bb297dd8ce9abd085f5c198b26a26a191;hb=c82fb9a1ad0301b1f5465944df05ee01937e6e3f;hp=180cdf357b564d0033ba0664b3156e293b81dd3a;hpb=b5e2d93b0bc818bea7f694ac7128c1920d508f43;p=safcm%2Fsafcm.git diff --git a/README.adoc b/README.adoc index 180cdf3..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,32 +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. However, -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: @@ -102,14 +105,25 @@ 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. +- 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 scripts which can be confusing. +- Permissions of symlinks are ignored on BSD systems. They are always shown to + have `0777` as permissions even though the current umask controls the actual + permissions when creating new symlinks. Existing symlinks with different + permissions are not updated. Most BSDs ignore the permissions when following + symlinks which should reduce the impact of this limitation. + == Requirements -- build the `safcm` binary and remote helper: +- to build the `safcm` binary and remote helper: * Go >= 1.16 * GNU make @@ -120,8 +134,11 @@ future, others are due to the design of safcm. - *remote hosts*: * Go support for architecture and operating system - * GNU/Linux with common commands (`stat`, `sha512sum`, `cat`, `rm`, `ln`, - `chmod`) + * Supported operating system: + ** GNU/Linux with common commands (`uname`, `id`, `stat`, `sha512sum`, + `cat`, `mktemp`, `rm`, `ln`, `chmod`) + ** FreeBSD (same commands, but uses `sha512`) + ** OpenBSD (same commands, but uses `sha512`) * SSH server * to install packages: ** `apt-get` (Debian or derivative)