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