From 91283c7517bd49d9c7cb4114454cdd7644a442a0 Mon Sep 17 00:00:00 2001 From: Simon Ruderich Date: Thu, 8 Apr 2021 08:35:05 +0200 Subject: [PATCH] Add README.adoc --- README.adoc | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 README.adoc diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..2512596 --- /dev/null +++ b/README.adoc @@ -0,0 +1,153 @@ += README + +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 +- *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 unexperienced 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. + +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; + 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 +- *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 + + +== Overview + +This section describes the general concepts, behavior and terminology of +safcm. + +Safcm _synchronizes_ _files_, _packages_, _services_ and _commands_ to remote +_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 +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. + +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 +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. + +The synchronization happens in the following order which cannot be changed: + +. Collect information from remote helper including detected groups +. Build configuration for the host and send it to the remote helper +. Apply the configuration using the remote helper +.. Synchronize files +.. Install packages +.. Enable/Start services +.. Run triggers +.. Run commands + +After the synchronization is complete (or on the first error) the applied +changes are displayed. Multiple hosts are synchronized in parallel. + + +== 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. + +- 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=`). 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, 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 carefully check + the diff output for unwanted changes. + + +== Requirements + +- build the `safcm` binary and remote helper: + * Go >= 1.16 + * GNU make + +- 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*: + * Go support for architecture and operating system + * GNU/Linux with common commands (`stat`, `sha512sum`, `cat`, `rm`, `ln`, + `chmod`) + * SSH server + * to install packages: + ** `apt-get` (Debian or derivative) + * 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. + + +== Authors + +Written by Simon Ruderich . + + +== License + +This program is licensed under GPL version 3 or later. + +Copyright (C) 2021 Simon Ruderich + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . -- 2.43.2