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 unexperienced 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) evaluated locally to prevent partial configuration;
  21   errors immediately abort the synchronization
  22 - *remote hosts untrusted*: clear security boundary between local and remote
  23   host; data used from remote hosts is marked (detected groups); all output
  24   from remote hosts is escaped to prevent terminal injection attacks; each
  25   host only receives its configuration and no data from other hosts
  26 - *safety and security*: create files with "write to temporary file", "sync",
  27   "rename", "sync directory" for atomicity and durability; guard against
  28   symlink and other TOCTOU attacks; extensive test suite
  29
  30
  31 == Overview
  32
  33 This section describes the general concepts, behavior and terminology of
  34 safcm.
  35
  36 Safcm _synchronizes_ _files_, _packages_, _services_ and _commands_ to remote
  37 _hosts_. All hosts are explicitly configured. Hosts can be put into _groups_
  38 to apply the same configuration to multiple hosts. The host itself is also
  39 considered a group for host-specific configuration. In addition to manual
  40 group assignment _detected groups_ assign hosts to groups depending on the
  41 output of custom commands on the remote host. The configuration for a group
  42 contains the files, packages, services and commands which should be applied to
  43 all hosts which are members of this group.
  44
  45 The configuration of all managed hosts is stored in a directory on the local
  46 host. Safcm uses https://yaml.org/[YAML] for all configuration files. However,
  47 tasks like copying a file require no explicit configuration (see the
  48 documentation for details).
  49
  50 Files consist of a tree of files (regular files and symbolic links) and
  51 directories with permissions, user/group and content. Files can use
  52 _templates_ for dynamic content depending on the host or its groups. Each path
  53 can have _trigger_ commands which are executed when the path itself or any
  54 sub-paths are modified during synchronization. Packages are package names of
  55 the remote operating system. Services are service names of the remote
  56 operating system. Commands are shell commands passed to `/bin/sh`.
  57
  58 When files with the same path are present in multiple groups of a host an
  59 explicit _group order_ must be configured to resolve the conflict. Conflicts
  60 do not apply to packages and services which are simply merged from all groups.
  61 Commands are appended so that the same command can be executed multiple times.
  62
  63 To sync the configuration to a remote host the local `safcm` binary connects
  64 to it via `ssh`. It then copies a _remote helper_ binary to `/tmp` on the
  65 remote host to later perform the actual sync. If the remote helper is already
  66 present, has the proper checksum, permissions and user then the copy is
  67 skipped. `safcm` then queries the remote host for information, including
  68 operating system, architecture and detected groups. With all relevant data
  69 collected it assigns the host its groups, evaluates the configuration
  70 including templates and finally sends it to the remote helper which then
  71 applies it to the remote host.
  72
  73 The synchronization happens in the following order which cannot be changed:
  74
  75 . Collect information from remote helper including detected groups
  76 . Build configuration for the host and send it to the remote helper
  77 . Apply the configuration using the remote helper
  78 .. Synchronize files
  79 .. Install packages
  80 .. Enable/Start services
  81 .. Run triggers
  82 .. Run commands
  83
  84 After the synchronization is complete (or on the first error) the applied
  85 changes are displayed. Multiple hosts are synchronized in parallel.
  86
  87
  88 == Limitations & Gotchas
  89
  90 Besides some obvious limitations due to the simplicity of safcm there are a
  91 few issues the user should be aware of. Some of these might get fixed in the
  92 future, others are due to the design of safcm.
  93
  94 - Commands are executed with `/bin/sh -c` on the remote host which might leak
  95   sensitive information to other users via the command line (unless `/proc` is
  96   mounted with `hidepid=`). Store sensitive data in a file and execute or
  97   source it as a workaround.
  98
  99 - Permissions of existing files and directories will be overwritten with the
 100   default (root/root, 0644 for files, 0755 for directories) unless manually
 101   configured via `permissions.yaml`. This includes important paths like
 102   `/root` which often have strict permissions by default, so carefully check
 103   the diff output for unwanted changes.
 104
 105 - Quoted strings in the output are quoted using Go's `%q` format string. The
 106   result is similar -- but not identical -- to quoted strings in regular shell
 107   scripts which can be confusing.
 108
 109
 110 == Requirements
 111
 112 - build the `safcm` binary and remote helper:
 113   * Go >= 1.16
 114   * GNU make
 115
 116 - local host:
 117   * Go support for architecture and operating system, see the "$GOOS and
 118     $GOARCH" section in the official
 119     https://golang.org/doc/install/source#environment[Go installation guide]
 120
 121 - *remote hosts*:
 122   * Go support for architecture and operating system
 123   * GNU/Linux with common commands (`stat`, `sha512sum`, `cat`, `rm`, `ln`,
 124     `chmod`)
 125   * SSH server
 126   * to install packages:
 127     ** `apt-get` (Debian or derivative)
 128   * to sync services:
 129     ** `systemd`
 130
 131 Adding support for other operating systems (e.g. BSDs) or distributions
 132 including package managers (e.g. Arch, Gentoo) is easy. Please send patches.
 133
 134
 135 == Authors
 136
 137 Written by Simon Ruderich <simon@ruderich.org>.
 138
 139
 140 == License
 141
 142 This program is licensed under GPL version 3 or later.
 143
 144 Copyright (C) 2021  Simon Ruderich
 145
 146 This program is free software: you can redistribute it and/or modify
 147 it under the terms of the GNU General Public License as published by
 148 the Free Software Foundation, either version 3 of the License, or
 149 (at your option) any later version.
 150
 151 This program is distributed in the hope that it will be useful,
 152 but WITHOUT ANY WARRANTY; without even the implied warranty of
 153 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 154 GNU General Public License for more details.
 155
 156 You should have received a copy of the GNU General Public License
 157 along with this program.  If not, see <http://www.gnu.org/licenses/>.