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
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:
`/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
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
- *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)
ruderich.org/simon / safcm / safcm.git / blobdiff