README.adoc

   1 = README
   2
   3 Nsscash (a pun on cache) is a simple file-based cache for NSS similar to
   4 nsscache [1]. The goal is to distribute users/groups/etc. to multiple systems
   5 without having to rely on a (single) stable server. Traditional systems like
   6 LDAP or NIS require a stable server or users/groups cannot be resolved. By
   7 distributing the data to all systems, temporary outages of the server cause no
   8 issues on the clients. In addition the local storage is much faster than
   9 remote network access. To update the local caches polling via HTTP is
  10 performed, for example every minute, only downloading new data if anything has
  11 changed.
  12
  13 Nsscash consists of two parts: `nsscash`, written in Go, which downloads files
  14 via HTTP or HTTPS, parses them, creates indices and writes the result to a
  15 local file. The second part is the NSS module (`libnss_cash.so.2`), written in
  16 C, which provides integration via `/etc/nsswitch.conf`. It's specifically
  17 designed to be very simple and uses the data prepared by `nsscash` for
  18 lookups. To support quick lookups, in O(log n), the files utilize indices.
  19
  20 Nsscash is very careful when deploying the changes:
  21 - All files are updated using the standard "write to temporary file", "sync",
  22   "rename" steps which is atomic on UNIX file systems. The indices are stored
  23   in the same file preventing stale data during the update.
  24 - All errors cause an immediate abort ("fail fast") with a proper error
  25   message and a non-zero exit status. This prevents hiding possibly important
  26   errors. In addition all files are fetched first and then deployed to try to
  27   prevent inconsistent state if only one file can be downloaded. The state
  28   file (containing last file modification and content hash) is only updated
  29   when all operations were successful.
  30 - To prevent unexpected permissions, `nsscash` does not create new files. The
  31   user must create them first and `nsscash` will then re-use the permissions
  32   (without the write bits to discourage manual modifications) and owner/group
  33   when updating the file (see examples below).
  34 - To prevent misconfigurations, empty files (no users/groups) are not
  35   permitted and will not be written to disk. This is designed to prevent the
  36   accidental loss of all users/groups on a system.
  37
  38 The passwd/group files have the following size restrictions:
  39 - maximum number of entries: '2^64-1' (uint64_t)
  40 - maximum passwd entry size: 65543 bytes (including newline)
  41 - maximum group entry size: 65535 bytes (including newline, only one member)
  42 - maximum members per group: depends on the user name length,
  43                              with 9 bytes per user: 5460 users
  44 - `nsscash` checks for these restrictions and aborts with an error if they are
  45   violated
  46
  47 nsscash has an extensive test suite for both the Go and C part testing general
  48 requirements and various corner cases.
  49
  50 nsscash is licensed under AGPL version 3 or later.
  51
  52 [1] https://github.com/google/nsscache
  53
  54
  55 == REQUIREMENTS
  56
  57 - Go, for `nsscash`
  58   - github.com/pkg/errors
  59   - github.com/BurntSushi/toml
  60 - C compiler, for `libnss_cash.so.2`
  61
  62 - HTTP(S) server to provide the passwd/group/etc. files
  63
  64 Tested on Debian Buster, but should work on any GNU/Linux system. With
  65 adaptations to the NSS module it should work on any UNIX-like system which
  66 uses NSS.
  67
  68
  69 == USAGE
  70
  71 Install `libnss_cash.so.2` somewhere in your library search path (see
  72 `/etc/ld.so.conf`), e.g. `/usr/lib/x86_64-linux-gnu/`.
  73
  74 Update `/etc/nsswitch.conf` to include the cash module; `passwd` and `group`
  75 are currently supported. For example:
  76
  77     passwd:         files cash
  78     group:          files cash
  79     [...]
  80
  81 Create the cache files with the proper permissions (`nsscash fetch` won't
  82 create new files to prevent using incorrect permissions):
  83
  84     touch /etc/passwd.nsscash
  85     touch /etc/group.nsscash
  86     chmod 0644 /etc/passwd.nsscash
  87     chmod 0644 /etc/group.nsscash
  88
  89 Configure the `nsscash` configuration file `nsscash.toml`, see below.
  90
  91 Then start `nsscash`:
  92
  93     nsscash fetch /path/to/config/nsscash.toml
  94
  95 This will fetch the configured files and update the local caches. The files
  96 are atomically overwritten (via temporary file, sync, and rename).
  97
  98 Verify the users/groups are available, e.g. with `getent`. If everything
  99 works, remember to reboot the host as changes to `nsswitch.conf` don't affect
 100 running processes!
 101
 102 Now configure `nsscash` to run regularly, for example via cron or a systemd
 103 timer.
 104
 105 To monitor `nsscash` for errors one can use the last modification time of the
 106 state file (see below). It's written on each successful run and not modified
 107 if an error occurs.
 108
 109 === CONFIGURATION
 110
 111 Nsscash is configured through a simple configuration file written in TOML. A
 112 typical configuration looks like this:
 113
 114     statepath = "/var/lib/nsscash/state.json"
 115
 116     [[file]]
 117     type = "passwd"
 118     url = "https://example.org/passwd"
 119     path = "/etc/passwd.nsscash"
 120
 121     [[file]]
 122     type = "group"
 123     url = "https://example.org/group"
 124     path = "/etc/group.nsscash"
 125
 126     # Optional, but useful to deploy files which are not supported by the
 127     # nsscash NSS module, but by libc's "files" NSS module. nsscash takes care
 128     # of the atomic replacement and updates; an "netgroup: files" entry in
 129     # "/etc/nsswitch.conf" makes the netgroups available.
 130     [[file]]
 131     type = "plain"
 132     url = "https://example.org/netgroup"
 133     path = "/etc/netgroup"
 134
 135 The following global keys are available:
 136
 137 - `statepath`: Path to a JSON file which stores the last modification time and
 138   hash of each file; automatically updated by `nsscash`. Used to fetch data
 139   only when something has changed to reduce the required traffic, via
 140   `If-Modified-Since`. When the hash of a file has changed the download is
 141   forced.
 142
 143 Each `file` block describes a single file to download/write. The following
 144 keys are available:
 145
 146 - `type`: Type of this file; can be either `passwd` (for files in
 147   `/etc/passwd` format), `group` (for files in `/etc/group` format), or
 148   `plain` (arbitrary format). Only `passwd` and `group` files are supported by
 149   the nsscash NSS module. But, as explained above, `plain` can be used to
 150   distribute arbitrary files. The type is required as the `.nsscash` files are
 151   pre processed for faster lookups and simpler C code which requires a known
 152   format.
 153
 154 - `url`: URL to fetch the file from; HTTP and HTTPS are supported
 155
 156 - `ca`: Path to a custom CA in PEM format. Restricts HTTPS requests to accept
 157   only certificates signed by this CA. Defaults to the system's certificate
 158   store when omitted. (optional)
 159
 160 - `username`/`password`: Username and password sent via HTTP Basic-Auth to the
 161   webserver. The configuration file must not be readable by other users when
 162   this is used. (optional)
 163
 164 - `path`: Path to store the retrieved file
 165
 166
 167 == AUTHORS
 168
 169 Written by Simon Ruderich <simon@ruderich.org>.
 170
 171
 172 == LICENSE
 173
 174 This program is licensed under AGPL version 3 or later.
 175
 176 Copyright (C) 2019  Simon Ruderich
 177
 178 This program is free software: you can redistribute it and/or modify
 179 it under the terms of the GNU Affero General Public License as published by
 180 the Free Software Foundation, either version 3 of the License, or
 181 (at your option) any later version.
 182
 183 This program is distributed in the hope that it will be useful,
 184 but WITHOUT ANY WARRANTY; without even the implied warranty of
 185 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 186 GNU Affero General Public License for more details.
 187
 188 You should have received a copy of the GNU Affero General Public License
 189 along with this program.  If not, see <https://www.gnu.org/licenses/>.