+++ /dev/null
-= README
-
-Nsscash (a pun on cache) is a simple file-based cache for NSS similar to
-nsscache [1]. The goal is to distribute users/groups/etc. to multiple systems
-without having to rely on a (single) stable server. Traditional systems like
-LDAP or NIS require a stable server or users/groups cannot be resolved. By
-distributing the data to all systems, temporary outages of the server cause no
-issues on the clients. In addition the local storage is much faster than
-remote network access. To update the local caches polling via HTTP is
-performed, for example every minute, only downloading new data if anything has
-changed.
-
-Nsscash consists of two parts: `nsscash`, written in Go, which downloads files
-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 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.
-
-[1] https://github.com/google/nsscache
-
-
-== REQUIREMENTS
-
-- Go, for `nsscash`
- - github.com/pkg/errors
- - 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
-
-Install `libnss_cash.so.2` somewhere in your library search path (see
-`/etc/ld.so.conf`), e.g. `/usr/lib/x86_64-linux-gnu/`.
-
-Update `/etc/nsswitch.conf` to include the cash module; `passwd` and `group`
-are currently supported. For example:
-
- passwd: files cash
- group: files cash
- [...]
-
-Create the cache files with the proper permissions (`nsscash fetch` won't
-create new files to prevent using incorrect permissions):
-
- touch /etc/passwd.nsscash
- touch /etc/group.nsscash
- chmod 0644 /etc/passwd.nsscash
- chmod 0644 /etc/group.nsscash
-
-Configure the `nsscash` configuration file `nsscash.toml`, see below.
-
-Then start `nsscash`:
-
- nsscash fetch /path/to/config/nsscash.toml
-
-This will fetch the configured files and update the local caches. The files
-are atomically overwritten (via temporary file, sync, and rename).
-
-Verify the users/groups are available, e.g. with `getent`. If everything
-works, remember to reboot the host as changes to `nsswitch.conf` don't affect
-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
-typical configuration looks like this:
-
- statepath = "/var/lib/nsscash/state.json"
-
- [[file]]
- type = "passwd"
- url = "https://example.org/passwd"
- path = "/etc/passwd.nsscash"
-
- [[file]]
- type = "group"
- 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.
- [[file]]
- type = "plain"
- url = "https://example.org/netgroup"
- path = "/etc/netgroup"
-
-The following global keys are available:
-
-- `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:
-
-- `type`: Type of this file; can be either `passwd` (for files in
- `/etc/passwd` format), `group` (for files in `/etc/group` format), or
- `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 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
-
-
-== AUTHORS
-
-Written by Simon Ruderich <simon@ruderich.org>.
-
-
-== LICENSE
-
-This program is licensed under AGPL version 3 or later.
-
-Copyright (C) 2019 Simon Ruderich
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program. If not, see <https://www.gnu.org/licenses/>.
-
-// vim: ft=asciidoc
ruderich.org/simon / nsscash / nsscash.git / blobdiff