6.10 The Hosts Shim

3 min read

The shim is the NSS module glibc's hosts database reaches, and on Peios the only one it can reach: glibc is patched so that hosts, like the identity databases, is not configurable and names peios_net whatever nsswitch.conf says. There is no files source behind it and no /etc/hosts for one to read.

6.10.1 Obligations #

A shim MUST:

  1. Forward every question to the native channel (§6.4) as lookup or reverse, one connection per libc call, and render the reply. It MUST NOT hold a connection across calls.
  2. Answer localhost, and any name under it, and the reverse of a loopback address, itself — with no socket. It is the one name a machine can never be without, and the only one the shim knows.
  3. Answer NSS_STATUS_UNAVAIL for everything else when the resolver cannot be reached. There is nothing behind it.
  4. Report an over-full caller buffer as NSS_STATUS_TRYAGAIN, with *errnop = ERANGE and *h_errnop = NETDB_INTERNAL (-1), so glibc retries with a larger one.

A shim MUST NOT read /etc/hosts, /etc/resolv.conf or any file; MUST NOT speak DNS itself; and MUST NOT cache. Each would be a second policy path the resolver cannot see.

The complete buffer-exhaustion triple is required by the glibc NSS interface: NETDB_INTERNAL tells the caller to examine errnop, including its ERANGE buffer-size indication.

6.10.2 Status mapping #

Resolver outcomeNSS statush_errno
found, with addresses of the asked familySUCCESS—
found, none of that familyNOTFOUNDNO_DATA
notfoundNOTFOUNDHOST_NOT_FOUND
unavailableTRYAGAIN (EAGAIN)TRY_AGAIN
Resolver unreachable, or an error replyUNAVAILNO_RECOVERY

The unavailable row is the one that matters: a shim MUST NOT render it as NOTFOUND. A caller that retries gets its answer when the network comes back; a caller told "no such host" may remember that.

h_name is the reply's canonical name. TTLs are reported through ttlp where glibc offers it, as the least TTL among the addresses.

6.10.3 Entry points #

_nss_peios_net_gethostbyname4_r, gethostbyname3_r, gethostbyname2_r, gethostbyname_r, gethostbyaddr2_r, gethostbyaddr_r. The module's SONAME is libnss_peios_net.so.2 and it is installed in glibc's configured library directory; it links against libc and the wire codec and nothing else, since it is loaded into every process that resolves a host.

Edit this page