1 files changed, 133 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..046c275
--- /dev/null
+++ b/README.md
@@ -0,0 +1,133 @@
+# nss-localuser
+
+- [License](#license)
+- [Overview](#overview)
+- [Install](#documentation)
+
+## License
+
+This code is published with the license MIT (see LICENSE.txt) for details.
+
+## Overview
+
+`nss-localuser` is a plugin for the GNU Name Service Switch (NSS)
+functionality of the GNU C Library (`glibc`) providing host name
+resolution for *"localuser"* family of virtual hostnames.
+
+The delivered NSS service defines one virtual host of name `localuser`
+that resolves to an IP address of the localhost loopback that integrates
+user ID.
+
+It is intended to enable distinct IP for distinct users.
+
+The name "localuser" is resolved to the IPv4 address:
+
+```
+127.x.y.z
+```
+
+where x.y.z encode the current user UID in such way that:
+
+```
+UID = 65536*(x - 128) + 256*y + z
+```
+
+Allowed UID are from 0 to 4194303 included.
+
+And so:
+
+```
+z = [0..255]
+y = [0..255]
+x = [128..191]
+```
+
+The names "localuser-${UID}", where UID is a decimal number, are resolved to addresses:
+
+```
+127.x.y.z
+
+z = UID % 255
+y = (UID >> 8) % 256
+x = ((UID >> 16) % 256) + 128
+```
+
+Examples:
+
+```
+localuser      => 127.128.0.0   (when user has UID = 0)
+localuser      => 127.128.3.233 (when user has UID = 1001)
+localuser-1024 => 127.128.4.0   (for any user)
+```
+
+The service also provides the reverse resolution.
+
+This module provides a value for IPv6: it translates to a IPv4-mapped IPv6 address
+because IPv6 lacks of loopback range.
+
+Example:
+
+```
+localuser-1024 => ::ffff:127.128.4.0
+```
+
+For details about NSS integration, see
+[Gnu libc documentation](https://www.gnu.org/software/libc/manual/html_node/Name-Service-Switch.html).
+
+## Install
+
+To install this file:
+
+```
+make all && sudo install
+```
+
+The installation directory is automatically detected by the tiny
+script detect-nssdir.sh.
+
+If the script detect-nssdir.sh gives the wrong result, just define the
+variable nssdir when calling make, as below:
+
+```
+make install nssdir=~/lib
+```
+
+## Configuration and activation
+
+### Manual setting
+
+To activate the NSS module localuser you have to edit
+`/etc/nsswitch.conf` and add `localuser` to the
+line starting with "`hosts:`".
+
+Your nsswitch file can then look as below:
+
+<pre># /etc/nsswitch.conf
+
+passwd:     files sss systemd
+shadow:     files sss
+group:      files sss systemd
+
+hosts:      <b>localuser</b> files dns myhostname
+
+ethers:     files
+netmasks:   files
+networks:   files
+protocols:  files
+services:   files sss
+
+aliases:    files nisplus</pre>
+
+### Scripted setting
+
+The script activate-localuser.sh can be used to activate,
+deactivate or query the status of localuser activation.
+
+It accepts 0, 1 or 2 arguments.
+
+<pre>usage: activate-localuser.sh [command [file]]
+
+command:    on, yes, true, 1:           activate
+            off, no, false, 0:          deactivate
+            status, test, check, query: status (default)
+file:       file to change (default /etc/nsswitch.conf)</pre>