From: Simon Ruderich <simon@ruderich.org>
Date: Mon, 10 Jun 2019 21:40:00 +0000 (+0200)
Subject: README: document practices and tested systems
X-Git-Tag: 0.1~66
X-Git-Url: https://ruderich.org/simon/gitweb/?a=commitdiff_plain;h=b84cf93cb9fc399366212fd1aa4c3b8faf18575c;p=nsscash%2Fnsscash.git

README: document practices and tested systems
---

diff --git a/README b/README
index c416e42..a6d40b5 100644
--- a/README
+++ b/README
@@ -17,6 +17,22 @@ C, which provides integration via `/etc/nsswitch.conf`. It's specifically
 designed to be very simple and uses the data prepared by `nsscash` for
 lookups. To support quick lookups, in O(log n), the files utilize indices.
 
+Nsscash is very careful when deploying the changes:
+- All files are updated using the standard "write to temporary file", "sync",
+  "rename" steps which is atomic on UNIX file systems.
+- All errors cause an immediate abort ("fail fast") with a proper error
+  message and a non-zero exit status. This prevents hiding possibly important
+  errors. In addition all files are fetched first and then deployed to try to
+  prevent inconsistent state if only one file can be downloaded. The state
+  file (containing last file modifications) is only updated when all
+  operations were successful.
+- To prevent unexpected permissions, `nsscash` does not create new files. The
+  user must create them first and `nsscash` will then re-use the permissions
+  and owner/group when updating the file (see examples below).
+- To prevent misconfigurations, empty files (no users/groups) are not
+  permitted and will not be written to disk. This is designed to prevent the
+  accidental loss of all users/groups on a system.
+
 nsscash is licensed under AGPL version 3 or later.
 
 [1] https://github.com/google/nsscache
@@ -29,6 +45,10 @@ nsscash is licensed under AGPL version 3 or later.
   - github.com/BurntSushi/toml
 - C compiler, for `libnss_cash.so.2`
 
+Tested on Debian Stretch and Buster, but should work on any GNU/Linux system.
+With adapations to the NSS module it should work on any UNIX-like system which
+uses NSS.
+
 
 == USAGE