Simple and fast configuration management (safcm) is written in Go and licensed
under GPLv3+. It is:
-- *simple*: to use and implement, obvious concepts and less bugs
+- *simple*: to use and implement, obvious concepts and fewer bugs
- *fast*: to learn and to use, quickly apply new configurations to your hosts
- *configuration management*: sync files, packages, services and run commands
on remote hosts
-The goal is that even inexperienced users (with safcm or configuration
-management in general) should be able to apply configuration with safcm
-quickly. This means all key concepts of safcm must be easy to grasp and for
-each task there should be one obvious way.
+The goal is to enable even inexperienced users (with safcm or configuration
+management in general) to apply configurations with safcm quickly. This means
+all key concepts of safcm must be easy to grasp, and there should be one
+obvious way to perform each task.
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) is evaluated locally to prevent partial configuration;
- errors immediately abort the synchronization
+ (including templates) is evaluated locally to prevent partial application of
+ configurations; errors immediately abort the synchronization
- *remote hosts are untrusted*: clear security boundary between local and
- remote host; data used from remote hosts is marked tainted (detected
+ remote hosts; 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; implemented in a
- memory safe language and using a simple synchronization protocol to prevent
- attacks on the local host; guard against symlink and other TOCTOU attacks;
- extensive test suite
+ "rename", "sync directory" for atomicity and durability; implementation in a
+ memory-safe language and using a simple synchronization protocol to prevent
+ attacks on the local host; guarding against symlink and other TOCTOU
+ attacks; extensive test suite
== Overview
_hosts_. All hosts are explicitly configured. Hosts can be put into _groups_
to apply the same configuration to multiple hosts. The host itself is also
considered a group for host-specific configuration. In addition to manual
-group assignment _detected groups_ assign hosts to groups depending on the
+group assignment, _detected groups_ assign hosts to groups depending on the
output of custom commands on the remote host. The _configuration_ for a group
-contains the files, packages, services and commands which should be applied to
-all hosts which are members of this group.
+contains the files, packages, services, and commands that should be applied to
+all hosts that 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. Strict
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
+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.
+host or its groups. Each path can have _trigger_ commands that are executed
+when the path itself or any subpaths 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
+Conflicts do not apply to packages and services that 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 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,
+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.
+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:
+The synchronization happens in the following fixed order:
. Collect information from remote helper including detected groups
. Build configuration for the host and send it to the remote helper
== Limitations & Gotchas
-Besides some obvious limitations due to the simplicity of safcm there are a
-few issues the user should be aware of. Some of these might get fixed in the
-future, others are due to the design of safcm.
+In addition to the limitations inherent in safcm's simplicity, there are a few
+issues the user should be aware of. Some of these might get fixed in the
+future; others are due to the design of safcm.
-- Commands are executed with `/bin/sh -c` on the remote host which might leak
+- Commands are executed with `/bin/sh -c` on the remote host, which might leak
sensitive information to other users via the command line (unless `/proc` is
mounted with `hidepid=` on GNU/Linux systems). Store sensitive data in a
file and execute or source it as a workaround.
- Permissions of existing files and directories will be overwritten with the
default (root/root or root/wheel, 0644 for files, 0755 for directories)
unless manually configured via `permissions.yaml`. This includes important
- paths like `/root` which often have strict permissions by default, so
+ paths like `/root`, which often have strict permissions by default, so
carefully check the output for unwanted changes.
-- The full file content of all files is sent to the remote during
+- The full content of all files is sent to the remote host during
synchronization. This makes it impractical to synchronize large files with
- safcm. Since most configuration files are small this shouldn't be an issue
+ 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.
+ 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.
+ symlinks, which should reduce the impact of this limitation.
== Requirements
-- to build the `safcm` binary and remote helper:
+- To build the `safcm` binary and remote helper:
* Go >= 1.24
* GNU make
-- local host:
- * Go support for architecture and operating system, see the "$GOOS and
+- Local host:
+ * Go support for architecture and operating system; see the "$GOOS and
$GOARCH" section in the official
https://golang.org/doc/install/source#environment[Go installation guide]
-- *remote hosts*:
+- *Remote hosts*:
* Go support for architecture and operating system
- * Supported operating system:
+ * Supported operating systems:
** GNU/Linux with common commands (`uname`, `id`, `stat`, `sha512sum`,
`cat`, `mkdir`, `mv`, `rm`, `chmod`, `chgrp`)
** FreeBSD (same commands, but uses `sha512`)
** OpenBSD (same commands, but uses `sha512`)
* SSH server
- * to install packages:
+ * To install packages:
** `apt-get` (Debian or derivative)
- * to sync services:
+ * To sync services:
** `systemd`
-Adding support for other operating systems (e.g. BSDs) or distributions
-including package managers (e.g. Arch, Gentoo) is easy. Please send patches.
+Adding support for other operating systems (e.g., BSDs) or distributions and
+their respective package managers (e.g., Arch, Gentoo) is easy. Please send
+patches.
-At the moment the remote helper is built for the following operating systems
+At the moment, the remote helper is built for the following operating systems
($GOOS) and architectures ($GOARCH). To add more architectures simply edit
`cmd/safcm-remote/build.sh`.
ruderich.org/simon / safcm / safcm.git / commitdiff