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