nsscash: store and check hash of deployed files

[nsscash/nsscash.git] / README

diff --git a/README b/README
index c416e42f91ce5512ad65c465937133bd1c72afaa..d9c255fbefd3b14c9aa95ff17290475ecda62929 100644 (file)
--- a/README
+++ b/README
@@ -17,6 +17,31 @@ 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 modification and content hash) 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.
+
+The passwd/group files have the following size restrictions:
+- maximum number of entries: '2^64-1' (uint64_t)
+- maximum passwd entry size: 65543 bytes (including newline)
+- maximum group entry size: 65535 bytes (including newline, only one member)
+- maximum members per group: depends on the user name length,
+                             with 9 bytes per user: 5460 users
+- `nsscash` checks for these restrictions and aborts with an error if they are
+  violated
+
 nsscash is licensed under AGPL version 3 or later.
 
 [1] https://github.com/google/nsscache
@@ -29,6 +54,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
 
@@ -66,6 +95,10 @@ running processes!
 Now configure `nsscash` to run regularly, for example via cron or a systemd
 timer.
 
+To monitor `nsscash` for errors one can use the last modification time of the
+state file (see below). It's written on each successful run and not modified
+if an error occurs.
+
 === CONFIGURATION
 
 Nsscash is configured through a simple configuration file written in TOML. A
@@ -83,10 +116,10 @@ typical configuration looks like this:
     url = "https://example.org/group"
     path = "/etc/group.nsscash"
 
-    // Optional, but useful to deploy files which are not supported by the
-    // nsscash NSS module, but by libc's "files" NSS module. nsscash takes
-    // care of the atomic replacement and updates; an "netgroup: files" entry
-    // in "/etc/nsswitch.conf" makes the netgroups available.
+    # Optional, but useful to deploy files which are not supported by the
+    # nsscash NSS module, but by libc's "files" NSS module. nsscash takes care
+    # of the atomic replacement and updates; an "netgroup: files" entry in
+    # "/etc/nsswitch.conf" makes the netgroups available.
     [[file]]
     type = "plain"
     url = "https://example.org/netgroup"
@@ -94,9 +127,11 @@ typical configuration looks like this:
 
 The following global keys are available:
 
-- `statepath`: Path to a JSON file which stores the last modification time of
-  each file; automatically updated by `nsscash`. Used to fetch data only when
-  something has changed to reduce the required traffic.
+- `statepath`: Path to a JSON file which stores the last modification time and
+  hash of each file; automatically updated by `nsscash`. Used to fetch data
+  only when something has changed to reduce the required traffic, via
+  `If-Modified-Since`. When the hash of a file has changed the download is
+  forced.
 
 Each `file` block describes a single file to download/write. The following
 keys are available: