nsscash: store and check hash of deployed files

[nsscash/nsscash.git] / README

diff --git a/README b/README
index a6d40b51b51ac234ecbd5477db36a0a3e5028fc8..d9c255fbefd3b14c9aa95ff17290475ecda62929 100644 (file)
--- a/README
+++ b/README
@@ -24,8 +24,8 @@ Nsscash is very careful when deploying the changes:
   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.
+  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).
@@ -33,6 +33,15 @@ Nsscash is very careful when deploying the changes:
   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
@@ -86,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
@@ -103,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"
@@ -114,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: