via HTTP or HTTPS, parses them, creates indices and writes the result to a
local file. The second part is the NSS module (`libnss_cash.so.2`), written in
C, which provides integration via `/etc/nsswitch.conf`. It's specifically
-designed to be very simple and uses the prepared data for lookups. To support
-quick lookups, in O(log n), the files utilize indices.
+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. The indices are stored
+ in the same file preventing stale data during the update.
+- 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
+ (without the write bits to discourage manual modifications) 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 has an extensive test suite for both the Go and C part testing general
+requirements and various corner cases.
nsscash is licensed under AGPL version 3 or later.
- github.com/BurntSushi/toml
- C compiler, for `libnss_cash.so.2`
+- HTTP(S) server to provide the passwd/group/etc. files
+
+Tested on Debian Buster, but should work on any GNU/Linux system. With
+adaptations to the NSS module it should work on any UNIX-like system which
+uses NSS.
+
== USAGE
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
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"
The following global keys are available:
-- `statepath`: Path to a JSON file which stores the last modification time of
- each file; automatically updated by `nsswitch`. 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:
`plain` (arbitrary format). Only `passwd` and `group` files are supported by
the nsscash NSS module. But, as explained above, `plain` can be used to
distribute arbitrary files. The type is required as the `.nsscash` files are
- pre processed for faster lookups and simpler code which requires a known
+ pre processed for faster lookups and simpler C code which requires a known
format.
- `url`: URL to fetch the file from; HTTP and HTTPS are supported
+- `ca`: Path to a custom CA in PEM format. Restricts HTTPS requests to accept
+ only certificates signed by this CA. Defaults to the system's certificate
+ store when omitted. (optional)
+
+- `username`/`password`: Username and password sent via HTTP Basic-Auth to the
+ webserver. The configuration file must not be readable by other users when
+ this is used. (optional)
+
- `path`: Path to store the retrieved file
ruderich.org/simon / nsscash / nsscash.git / blobdiff