safcm: print unfinished hosts on Ctrl-C

[safcm/safcm.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index 180cdf357b564d0033ba0664b3156e293b81dd3a..7df94dc4e9da07577cb4f9ffee0a89c8a39be04e 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -43,9 +43,9 @@ 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).
+host. Safcm uses https://yaml.org/[YAML] for all configuration files for its
+natural syntax. Strict type checks prevent potential pitfalls of more complex
+YAML syntax. Tasks like copying a file require no explicit configuration.
 
 Files consist of a tree of files (regular files and symbolic links) and
 directories with permissions, user/group and content. Files can use
@@ -63,7 +63,7 @@ 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
+present, has the proper checksum, permissions and user/group 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
@@ -102,10 +102,21 @@ future, others are due to the design of safcm.
   `/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.
+
 - 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
 
@@ -120,8 +131,11 @@ future, others are due to the design of safcm.
 
 - *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)