README

   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.
  23 - All errors cause an immediate abort ("fail fast") with a proper error
  24   message and a non-zero exit status. This prevents hiding possibly important
  25   errors. In addition all files are fetched first and then deployed to try to
  26   prevent inconsistent state if only one file can be downloaded. The state
  27   file (containing last file modifications) is only updated when all
  28   operations were successful.
  29 - To prevent unexpected permissions, `nsscash` does not create new files. The
  30   user must create them first and `nsscash` will then re-use the permissions
  31   and owner/group when updating the file (see examples below).
  32 - To prevent misconfigurations, empty files (no users/groups) are not
  33   permitted and will not be written to disk. This is designed to prevent the
  34   accidental loss of all users/groups on a system.
  35
  36 nsscash is licensed under AGPL version 3 or later.
  37
  38 [1] https://github.com/google/nsscache
  39
  40
  41 == REQUIREMENTS
  42
  43 - Go, for `nsscash`
  44   - github.com/pkg/errors
  45   - github.com/BurntSushi/toml
  46 - C compiler, for `libnss_cash.so.2`
  47
  48 Tested on Debian Stretch and Buster, but should work on any GNU/Linux system.
  49 With adapations to the NSS module it should work on any UNIX-like system which
  50 uses NSS.
  51
  52
  53 == USAGE
  54
  55 Install `libnss_cash.so.2` somewhere in your library search path (see
  56 `/etc/ld.so.conf`), e.g. `/usr/lib/x86_64-linux-gnu/`.
  57
  58 Update `/etc/nsswitch.conf` to include the cash module; `passwd` and `group`
  59 are currently supported. For example:
  60
  61     passwd:         files cash
  62     group:          files cash
  63     [...]
  64
  65 Create the cache files with the proper permissions (`nsscash fetch` won't
  66 create new files to prevent using incorrect permissions):
  67
  68     touch /etc/passwd.nsscash
  69     touch /etc/group.nsscash
  70     chmod 0644 /etc/passwd.nsscash
  71     chmod 0644 /etc/group.nsscash
  72
  73 Configure the `nsscash` configuration file `nsscash.toml`, see below.
  74
  75 Then start `nsscash`:
  76
  77     nsscash fetch /path/to/config/nsscash.toml
  78
  79 This will fetch the configured files and update the local caches. The files
  80 are atomically overwritten (via temporary file, sync, and rename).
  81
  82 Verify the users/groups are available, e.g. with `getent`. If everything
  83 works, remember to reboot the host as changes to `nsswitch.conf` don't affect
  84 running processes!
  85
  86 Now configure `nsscash` to run regularly, for example via cron or a systemd
  87 timer.
  88
  89 === CONFIGURATION
  90
  91 Nsscash is configured through a simple configuration file written in TOML. A
  92 typical configuration looks like this:
  93
  94     statepath = "/var/lib/nsscash/state.json"
  95
  96     [[file]]
  97     type = "passwd"
  98     url = "https://example.org/passwd"
  99     path = "/etc/passwd.nsscash"
 100
 101     [[file]]
 102     type = "group"
 103     url = "https://example.org/group"
 104     path = "/etc/group.nsscash"
 105
 106     // Optional, but useful to deploy files which are not supported by the
 107     // nsscash NSS module, but by libc's "files" NSS module. nsscash takes
 108     // care of the atomic replacement and updates; an "netgroup: files" entry
 109     // in "/etc/nsswitch.conf" makes the netgroups available.
 110     [[file]]
 111     type = "plain"
 112     url = "https://example.org/netgroup"
 113     path = "/etc/netgroup"
 114
 115 The following global keys are available:
 116
 117 - `statepath`: Path to a JSON file which stores the last modification time of
 118   each file; automatically updated by `nsscash`. Used to fetch data only when
 119   something has changed to reduce the required traffic.
 120
 121 Each `file` block describes a single file to download/write. The following
 122 keys are available:
 123
 124 - `type`: Type of this file; can be either `passwd` (for files in
 125   `/etc/passwd` format), `group` (for files in `/etc/group` format), or
 126   `plain` (arbitrary format). Only `passwd` and `group` files are supported by
 127   the nsscash NSS module. But, as explained above, `plain` can be used to
 128   distribute arbitrary files. The type is required as the `.nsscash` files are
 129   pre processed for faster lookups and simpler code which requires a known
 130   format.
 131
 132 - `url`: URL to fetch the file from; HTTP and HTTPS are supported
 133
 134 - `path`: Path to store the retrieved file
 135
 136
 137 == AUTHORS
 138
 139 Written by Simon Ruderich <simon@ruderich.org>.
 140
 141
 142 == LICENSE
 143
 144 This program is licensed under AGPL version 3 or later.
 145
 146 Copyright (C) 2019  Simon Ruderich
 147
 148 This program is free software: you can redistribute it and/or modify
 149 it under the terms of the GNU Affero General Public License as published by
 150 the Free Software Foundation, either version 3 of the License, or
 151 (at your option) any later version.
 152
 153 This program is distributed in the hope that it will be useful,
 154 but WITHOUT ANY WARRANTY; without even the implied warranty of
 155 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 156 GNU Affero General Public License for more details.
 157
 158 You should have received a copy of the GNU Affero General Public License
 159 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 160
 161 // vim: ft=asciidoc