Add applications the the localuser familyicefish_8.99.2icefish/8.99.28.99.2

This proposal allows to use separate names for separate
applications and separate users running on the loopback
interface.

Bug-AGL: SPEC-2968

Change-Id: I7c25e89da9f51c10c59a72670339f2ea55b31997
Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>

1 files changed, 54 insertions, 31 deletions

diff --git a/README.md b/README.md
index 046c275..b946a7b 100644
--- a/README.md
+++ b/README.md
@@ -14,50 +14,73 @@ This code is published with the license MIT (see LICENSE.txt) for details.
 functionality of the GNU C Library (`glibc`) providing host name
 resolution for *"localuser"* family of virtual hostnames.
 
+It defines the family  *"localuser"* of virtual hostnames as one of the
+below names:
+
+- localuser
+- localuser-UID
+- localuser--APPID
+- localuser-UID-APPID
+- localuser---APPID
+
+This can be summarized by the following matrix:
+
+  |------------------|------------------|---------------------|-------------------|
+  |                  | **current user** | **user of UID**     | **no user**       |
+  |------------------|------------------|---------------------|-------------------|
+  | **no APP**       | localuser        | localuser-UID       |                   |
+  | **app of APPID** | localuser--APPID | localuser-UID-APPID | localuser---APPID |
+  |------------------|------------------|---------------------|-------------------|
+
 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:
+It is intended to enable distinct IP for distinct users, distinct application.
 
-```
-127.x.y.z
-```
+The name *localuser* family is resolved to the IPv4 address range 127.128.0.0/9
 
-where x.y.z encode the current user UID in such way that:
+The delivered IPv4 address is structured as follow:
 
-```
-UID = 65536*(x - 128) + 256*y + z
+```text
++--------+--------+--------+--------+
+:01111111:1abbcccc:dddddeee:ffffffff:
++--------+--------+--------+--------+
 ```
 
-Allowed UID are from 0 to 4194303 included.
+When `a` is `1`, the value 11 bits value `bbccccddddd` encodes the APPID
+and the 11 bits value `eeedddddddd` encodes the UID.
+This is represented by the following hostnames: `localuser--APPID`
+and `localuser-UID-APPID`.
 
-And so:
+When `abb` is `011`, the 20 bits value `ccccdddddeeeffffffff` encodes the APPID.
+This is represented by the following hostnames: `localuser---APPID`.
 
-```
-z = [0..255]
-y = [0..255]
-x = [128..191]
-```
+When `abb` is `010`, the 20 bits value `ccccdddddeeeffffffff` encodes the UID.
+This is represented by the following hostnames: `localuser`
+and `localuser-UID`.
 
-The names "localuser-${UID}", where UID is a decimal number, are resolved to addresses:
+The values `000` and `001` of `abb` are reserved for futur use.
 
-```
-127.x.y.z
+Examples:
 
-z = UID % 255
-y = (UID >> 8) % 256
-x = ((UID >> 16) % 256) + 128
-```
+```text
+localuser           => 127.160.0.0   (when user has UID = 0)
+localuser           => 127.160.3.233 (when user has UID = 1001)
 
-Examples:
+localuser-0         => 127.160.0.0
+localuser-45        => 127.160.0.45
+localuser-1024      => 127.160.4.0
+localuser-1048575   => 127.175.255.255
 
-```
-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)
+localuser---0       => 127.176.0.0
+localuser---45      => 127.176.0.45
+localuser---1048575 => 127.191.255.255
+
+localuser-0-0       => 127.192.0.0
+localuser--78       => 127.194.115.233 (when user has UID = 1001)
+localuser-23-54     => 127.193.176.23
+localuser-2047-2047 => 127.255.255.255
 ```
 
 The service also provides the reverse resolution.
@@ -67,7 +90,7 @@ because IPv6 lacks of loopback range.
 
 Example:
 
-```
+```text
 localuser-1024 => ::ffff:127.128.4.0
 ```
 
@@ -78,7 +101,7 @@ For details about NSS integration, see
 
 To install this file:
 
-```
+```sh
 make all && sudo install
 ```
 
@@ -88,7 +111,7 @@ script detect-nssdir.sh.
 If the script detect-nssdir.sh gives the wrong result, just define the
 variable nssdir when calling make, as below:
 
-```
+```sh
 make install nssdir=~/lib
 ```