README.adoc

   1 = README
   2
   3 Simple and fast configuration management (safcm) is written in Go and licensed
   4 under GPLv3+. It is:
   5
   6 - *simple*: to use and implement, obvious concepts and less bugs
   7 - *fast*: to learn and to use, quickly apply new configurations to your hosts
   8 - *configuration management*: sync files, packages, services and run commands
   9   on remote hosts
  10
  11 The goal is that even inexperienced users (with safcm or configuration
  12 management in general) should be able to apply configuration with safcm
  13 quickly. This means all key concepts of safcm must be easy to grasp and for
  14 each task there should be one obvious way.
  15
  16 It can also be read as "saf(e) configuration management" as it combines
  17 simplicity and safety in the following principles:
  18
  19 - *fail fast*: catch (user) errors as soon as possible; host configuration
  20   (including templates) is evaluated locally to prevent partial configuration;
  21   errors immediately abort the synchronization
  22 - *remote hosts are untrusted*: clear security boundary between local and
  23   remote host; data used from remote hosts is marked tainted (detected
  24   groups); all output from remote hosts is escaped to prevent terminal
  25   injection attacks; each host only receives its own configuration and no data
  26   from other hosts
  27 - *safety and security*: create files with "write to temporary file", "sync",
  28   "rename", "sync directory" for atomicity and durability; implemented in a
  29   memory safe language and using a simple synchronization protocol to prevent
  30   attacks on the local host; guard against symlink and other TOCTOU attacks;
  31   extensive test suite
  32
  33
  34 == Overview
  35
  36 This section describes the general concepts, behavior and terminology of
  37 safcm.
  38
  39 Safcm _synchronizes_ _files_, _packages_, _services_ and _commands_ to remote
  40 _hosts_. All hosts are explicitly configured. Hosts can be put into _groups_
  41 to apply the same configuration to multiple hosts. The host itself is also
  42 considered a group for host-specific configuration. In addition to manual
  43 group assignment _detected groups_ assign hosts to groups depending on the
  44 output of custom commands on the remote host. The configuration for a group
  45 contains the files, packages, services and commands which should be applied to
  46 all hosts which are members of this group.
  47
  48 The configuration of all managed hosts is stored in a directory on the local
  49 host. Safcm uses https://yaml.org/[YAML] for all configuration files. Strict
  50 type checks prevent potential pitfalls due to the complex YAML syntax. Tasks
  51 like copying a file require no explicit configuration.
  52
  53 Files (regular files and symbolic links) and directories, including
  54 permissions, user/group and content are kept in a regular filesystem tree on
  55 the local host. Files can use _templates_ for dynamic content depending on the
  56 host or its groups. Each path can have _trigger_ commands which are executed
  57 when the path itself or any sub-paths are modified during synchronization.
  58 Packages are package names of the remote operating system. Services are
  59 service names of the remote operating system. Commands are shell commands
  60 passed to `/bin/sh`.
  61
  62 When files with the same path are present in multiple groups of a host, an
  63 explicit _group priority_ must be configured to resolve the conflict.
  64 Conflicts do not apply to packages and services which are simply merged from
  65 all groups. Commands are appended so that the same command can be executed
  66 multiple times.
  67
  68 To sync the configuration to a remote host, the local `safcm` binary connects
  69 to it via `ssh`. It then copies a _remote helper_ binary to `/tmp` on the
  70 remote host to perform the actual sync later. If the remote helper is already
  71 present, has the proper checksum, permissions and user/group then the copying
  72 step is skipped. `safcm` then queries the remote host for information,
  73 including operating system, architecture and detected groups. With all
  74 relevant data collected, it assigns the host to its groups, evaluates the
  75 configuration including templates and finally sends the new configuration to
  76 the remote helper which then applies it to the remote host.
  77
  78 The synchronization happens in the following order which cannot be changed:
  79
  80 . Collect information from remote helper including detected groups
  81 . Build configuration for the host and send it to the remote helper
  82 . Apply the configuration using the remote helper
  83 .. Synchronize files
  84 .. Install packages
  85 .. Enable/Start services
  86 .. Run triggers
  87 .. Run commands
  88
  89 After the synchronization is complete (or on the first error) the applied
  90 changes are displayed. Multiple hosts are synchronized in parallel.
  91
  92
  93 == Limitations & Gotchas
  94
  95 Besides some obvious limitations due to the simplicity of safcm there are a
  96 few issues the user should be aware of. Some of these might get fixed in the
  97 future, others are due to the design of safcm.
  98
  99 - Commands are executed with `/bin/sh -c` on the remote host which might leak
 100   sensitive information to other users via the command line (unless `/proc` is
 101   mounted with `hidepid=` on GNU/Linux systems). Store sensitive data in a
 102   file and execute or source it as a workaround.
 103
 104 - Permissions of existing files and directories will be overwritten with the
 105   default (root/root or root/wheel, 0644 for files, 0755 for directories)
 106   unless manually configured via `permissions.yaml`. This includes important
 107   paths like `/root` which often have strict permissions by default, so
 108   carefully check the output for unwanted changes.
 109
 110 - The full file content of all files is sent to the remote during
 111   synchronization. This makes it impractical to synchronize large files with
 112   safcm. Since most configuration files are small this shouldn't be an issue
 113   for common scenarios.
 114
 115 - Quoted strings in the output are quoted using Go's `%q` format string. The
 116   result is similar -- but not identical -- to quoted strings in regular shell
 117   scripts which can be confusing.
 118
 119 - Permissions of symlinks are ignored on BSD systems. They are always shown to
 120   have `0777` as permissions even though the current umask controls the actual
 121   permissions when creating new symlinks. Existing symlinks with different
 122   permissions are not updated. Most BSDs ignore the permissions when following
 123   symlinks which should reduce the impact of this limitation.
 124
 125
 126 == Requirements
 127
 128 - to build the `safcm` binary and remote helper:
 129   * Go >= 1.16 (for `go:embed`, `io/fs`)
 130   * GNU make
 131
 132 - local host:
 133   * Go support for architecture and operating system, see the "$GOOS and
 134     $GOARCH" section in the official
 135     https://golang.org/doc/install/source#environment[Go installation guide]
 136
 137 - *remote hosts*:
 138   * Go support for architecture and operating system
 139   * Supported operating system:
 140     ** GNU/Linux with common commands (`uname`, `id`, `stat`, `sha512sum`,
 141        `cat`, `mktemp`, `rm`, `ln`, `chmod`)
 142     ** FreeBSD (same commands, but uses `sha512`)
 143     ** OpenBSD (same commands, but uses `sha512`)
 144   * SSH server
 145   * to install packages:
 146     ** `apt-get` (Debian or derivative)
 147   * to sync services:
 148     ** `systemd`
 149
 150 Adding support for other operating systems (e.g. BSDs) or distributions
 151 including package managers (e.g. Arch, Gentoo) is easy. Please send patches.
 152
 153 At the moment the remote helper is built for the following operating systems
 154 ($GOOS) and architectures ($GOARCH). To add more architectures simply edit
 155 `cmd/safcm-remote/build.sh`.
 156
 157     - freebsd: amd64
 158     - linux: amd64, armv7
 159     - openbsd: amd64
 160
 161
 162 == Authors
 163
 164 Written by Simon Ruderich <simon@ruderich.org>.
 165
 166
 167 == License
 168
 169 This program is licensed under GPL version 3 or later.
 170
 171 Copyright (C) 2021  Simon Ruderich
 172
 173 This program is free software: you can redistribute it and/or modify
 174 it under the terms of the GNU General Public License as published by
 175 the Free Software Foundation, either version 3 of the License, or
 176 (at your option) any later version.
 177
 178 This program is distributed in the hope that it will be useful,
 179 but WITHOUT ANY WARRANTY; without even the implied warranty of
 180 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 181 GNU General Public License for more details.
 182
 183 You should have received a copy of the GNU General Public License
 184 along with this program.  If not, see <http://www.gnu.org/licenses/>.