NDB(8) NDB(8)
NAME
query, ipquery, mkhash, mkdb, mkhosts, cs, csquery, dns,
dnsquery, dnsdebug, dnsgetip, inform - network database
SYNOPSIS
ndb/query [ -acim ] [ -f dbfile ] [ -x netmtpt ] attr value
[ rattr ]...
ndb/ipquery attr value rattr...
ndb/mkhash file attr
ndb/mkdb
ndb/mkhosts [ domain [ dbfile ] ]
ndb/cs [ -46n ] [ -f dbfile ] [ -x netmtpt ]
ndb/csquery [ -s ] [ /net/cs [ addr... ] ]
ndb/dns [ -FnrLR ] [ -a maxage ] [ -c cert.pem ] [ -f dbfile
] [ -N target ] [ -x netmtpt ] [ -s [ addrs... ] ]
ndb/dnsquery [ -x ] [ /net/dns ]
ndb/dnsdebug [ -crdx ] [ -f dbfile ] [ [ @server ] domain-
name [ type ] ]
ndb/dnsgetip [ -ax ] domain-name
ndb/inform [ -x netmtpt ]
DESCRIPTION
The network database holds administrative information used
by network programs such as dhcpd(8), ipconfig(8), con(1),
etc.
Ndb/query searches the network database for an attribute of
type attr and value value. If a single rattr is specified,
only the value of the first matching pair with attribute
rattr is printed. Under -m, the values of all pairs with a
rattr attribute within the first matching entry are printed.
Under -a and with a single rattr, all values of pairs with a
rattr attribute within all entries are printed. If none or
more than one rattr where specified, all entries matched by
the search are printed in ndb(6) format. When the -i flag
is present, the type attribute attr and its value are relat-
ing to systems with ip= tuples, and the search will return
rattr attributes inherited from their corresponding ipnet=
entries. (see the ndbipinfo and csipinfo functions in
ndb(2)). The -i flag requires at least one rattr and each
rattr prefixed with a @ is resolved to an IP address. When
-c flag is specified, instead of opening the network data-
base files directly, the connection server mounted on
netmtpt is consulted. The netmtpt can be changed using the
-x option (default /net). Without the -c flag, the network
database is searched directly by opening dbfile
(/lib/ndb/local by default).
Ndb/ipquery uses ndbipinfo (see ndb(2)) to search for the
values of the attributes rattr corresponding to the systems
Page 1 Plan 9 (printed 12/22/24)
NDB(8) NDB(8)
with entries of attribute type attr and value value.
Ndb/inform sends an RFC2136 DNS inform packet to a name-
server to associate the host's IP address with its DNS name.
This is required if the domain's nameserver is a Microsoft
Windows Active Directory controller. The host's domain name
will be sent to the AD controller unless a tuple of the form
inform=xxx is found in the host's ndb entry.
Database maintenance
Ndb/mkhash creates a hash file for all entries with
attribute attr in database file file. The hash files are
used by ndb/query and by the ndb library routines.
Ndb/mkdb is used in concert with awk(1) scripts to convert
uucp systems files and IP host files into database files.
It is very specific to the situation at Murray Hill.
When the database files change underfoot, ndb/cs and ndb/dns
track them properly. Nonetheless, to keep the database
searches efficient it is necessary to run ndb/mkhash when-
ever the files are modified. It may be profitable to con-
trol this by a frequent cron(8) job.
Ndb/mkhosts generates a BSD style hosts, hosts.txt, and
hosts.equiv files from an ndb data base file specified on
the command line (default /lib/ndb/local). For local rea-
sons the files are called hosts.1127, astro.txt, and
hosts.equiv.
Connection service
Ndb/cs is a server used by dial(2) to translate network
names. It is started at boot time. It finds out what net-
works are configured by looking for /net/*/clone when it
starts. It can also be told about networks by writing to
/net/cs a message of the form:
add net1 net2 ...
Ndb/cs also sets the system name in /dev/sysname if it can
figure it out. The options are:
-4 Only look up IPv4 addresses (A records) when consulting
DNS. The default is to also look up v6 addresses (AAAA
records). Writing `ipv4' to /net/cs will toggle IP v4
look-ups.
-6 Only look up IPv6 addresses in DNS. Writing `ipv6' to
/net/cs toggles v6 lookups.
-f supplies the name of the data base file to use, default
/lib/ndb/local.
-n causes cs to do nothing but set the system name.
-x specifies the mount point of the network.
Page 2 Plan 9 (printed 12/22/24)
NDB(8) NDB(8)
Ndb/csquery queries ndb/cs to see how it resolves addresses.
Ndb/csquery prompts for addresses and prints what ndb/cs
returns. Server defaults to /net/cs. If any addrs are
specified, ndb/csquery prints their translations and immedi-
ately exits. The exit status will be nil only if all
addresses were successfully translated. The -s flag sets
exit status without printing any results.
Domain name service
Ndb/dns serves ndb/cs and remote systems by translating
Internet domain names. Ndb/dns is started at boot time. By
default dns serves only requests written to /net/dns. Pro-
grams must seek to offset 0 before reading or writing
/net/dns or /net/cs. The options are:
-a sets the maximum time in seconds that an unreferenced
domain name will remain cached. The default is one hour
(3600).
-f supplies the name of the data base file to use, default
/lib/ndb/local.
-n whenever a DNS zone that we serve changes, send UDP
NOTIFY messages to any dns slaves for that zone (see the
`dnsslave' attribute below).
-N sets the goal for the number of domain names cached to
target rather than the default of 8,000.
-r act as a resolver only: send `recursive' queries, asking
the other servers to complete lookups. If present,
/env/DNSSERVER or /env/DOTSERVER must be a space-
separated list of such DNS (or DoT) servers' IP
addresses, otherwise optional ndb(6) dns attributes name
DNS servers to forward queries to. Note that when
DOTSERVER is specified, DNSSERVER are ignored.
-R ignore the `recursive' bit on all incoming requests. Do
not complete lookups on behalf of remote systems.
-L ignore the `recursive' bit on incoming requests from
non-local IP addresses. IP addresses are local when
they are contained within the network prefix of an
interface. This allows running as a authoritative
server while also serving recursive queries for systems
on local networks.
-s also answer domain requests sent to IP addrs on UDP/TCP
port 53. If no IP addrs are given, listen on any inter-
face on network mount point netmtpt.
-c When a certificate cert.pem is specified, also listen on
TCP port 853 and handle DNS requests over TLS. Clients
wanting to connect to this service must add the certifi-
cate or public key thumbprint into /sys/lib/tls/dns.
-x specifies the mount point of the network.
When the -r option is specified, the servers used come from
the dns attribute in the database. For example, to specify
a set of dns servers that will resolve requests for systems
Page 3 Plan 9 (printed 12/22/24)
NDB(8) NDB(8)
on the network mh-net:
ipnet=mh-net ip=135.104.0.0 ipmask=255.255.0.0
dns=ns1.cs.bell-labs.com
dns=ns2.cs.bell-labs.com
dom=ns1.cs.bell-labs.com ip=135.104.1.11
dom=ns2.cs.bell-labs.com ip=135.104.1.12
The server for a domain is indicated by a database entry
containing both a dom and a ns attribute.
dom=
ns=A.ROOT-SERVERS.NET
ns=B.ROOT-SERVERS.NET
ns=C.ROOT-SERVERS.NET
dom=A.ROOT-SERVERS.NET ip=198.41.0.4
dom=B.ROOT-SERVERS.NET ip=128.9.0.107
dom=C.ROOT-SERVERS.NET ip=192.33.4.12
The last three lines provide a mapping for the server names
to their ip addresses. This is only a hint and will be
superseded from whatever is learned from servers owning the
domain.
Authoritative Name Servers
You can also serve a subtree of the domain name space from
the local database. You indicate subtrees that you would
like to serve by adding an soa= attribute to the root entry.
For example, the Bell Labs CS research domain is:
dom=cs.bell-labs.com soa=
refresh=3600 ttl=3600
ns=plan9.bell-labs.com
ns=ns1.cs.bell-labs.com
ns=ns2.cs.bell-labs.com
mb=presotto@plan9.bell-labs.com
mx=mail.research.bell-labs.com pref=20
mx=plan9.bell-labs.com pref=10
dnsslave=nslocum.cs.bell-labs.com
dnsslave=vex.cs.bell-labs.com
Here, the mb entry is the mail address of the person respon-
sible for the domain (default postmaster). The mx entries
list mail exchangers for the domain name and refresh and ttl
define the area refresh interval and the minimum TTL for
records in this domain. The dnsslave entries specify slave
DNS servers that should be notified when the domain changes.
The notification also requires the -n flag.
Reverse Domains
You can also serve reverse lookups (returning the name that
goes with an IP address) by adding an soa= attribute to the
Page 4 Plan 9 (printed 12/22/24)
NDB(8) NDB(8)
entry defining the root of the reverse space.
For example, to provide reverse lookup for all addresses in
starting with `135.104' or `fd00::', ndb must contain a
record like:
dom=104.135.in-addr.arpa soa=
dom=d.f.ip6.arpa soa= # special case, rfc 4193
refresh=3600 ttl=3600
ns=plan9.bell-labs.com
ns=ns1.cs.bell-labs.com
ns=ns2.cs.bell-labs.com
Notice the form of the reverse address. For IPv4, it's the
bytes of the address range you are serving reversed and
expressed in decimal, and with `.in-addr.arpa' appended.
For IPv6, it's the nibbles (4-bit fields) of the address
range you are serving reversed and expressed in hexadecimal,
and with `.ip6.arpa' appended. These are the standard forms
for a domain name in a PTR record.
If such an soa entry exists in the database, reverse
addresses will automatically be generated from any IP
addresses in the database that are under this root. For
example
dom=ns1.cs.bell-labs.com ip=135.104.1.11
will automatically create both forward and reverse entries
for ns1.cs.bell-labs.com. Unlike other DNS servers, there's
no way to generate inconsistent forward and reverse entries.
Classless reverse delegation
Following RFC 2317, it is possible to serve reverse DNS data
for IPv4 subnets smaller than /24. Declare the non-/24 sub-
net, the reverse domain and the individual systems.
For example, this is how to serve RFC-2317 ptr records for
the subnet `65.14.39.128/123'.
ipnet=our-t1 ip=65.14.39.128 ipmask=/123
dom=128.39.14.65.in-addr.arpa soa=
refresh=3600 ttl=3600
ns=ns1.our-domain.com
ns=ns2.our-domain.com
ip=65.14.39.129 dom=router.our-domain.com
Delegating Name Service Authority
Delegation of a further subtree to another set of name
servers is indicated by an soa=delegated attribute.
dom=bignose.cs.research.bell-labs.com
Page 5 Plan 9 (printed 12/22/24)
NDB(8) NDB(8)
soa=delegated
ns=anna.cs.research.bell-labs.com
ns=dj.cs.research.bell-labs.com
Nameservers within the delegated domain (as in this example)
must have their IP addresses listed elsewhere in ndb files.
Wildcards, MX and CNAME records
Wild-carded domain names can also be used. For example, to
specify a mail forwarder for all Bell Labs research systems:
dom=*.research.bell-labs.com
mx=research.bell-labs.com
`Cname' aliases may be established by adding a cname
attribute giving the real domain name; the name attached to
the dom attribute is the alias. `Cname' aliases are
severely restricted; the aliases may have no other
attributes than dom and are daily further restricted in
their use by new RFCs.
cname=anna.cs.bell-labs.com dom=www.cs.bell-labs.com
makes www.... a synonym for the canonical name anna.....
Zone Transfers and TCP
TCP clients requesting DNS zone transfer must be listed with
a dnsslave attribute for the relevant domain. A value of *
means any client is accepted.
DNS Queries and Debugging
Ndb/dnsquery can be used to query ndb/dns to see how it
resolves requests. Ndb/dnsquery prompts for commands of the
form
[ ! ] domain-name request-type
where request-type can be ip, ipv6, mx, ns, cname, ptr....
In the case of the inverse query type, ptr, dnsquery will
reverse the ip address and tack on the .in-addr.arpa if nec-
essary. If the command starts with an exclamation mark !
then the response is returned in ndb(6) format. The -x
option switches ndb/dnsquery to query the dns server on
/net.alt instead of /net.
Ndb/dnsdebug is like ndb/dnsquery but bypasses the local
server. It communicates via UDP (and sometimes TCP) with
the domain name servers in the same way that the local
resolver would and displays all packets received. The query
can be specified on the command line or can be prompted for.
The queries look like those of ndb/dnsquery with one addi-
tion. Ndb/dnsdebug can be directed to query a particular
Page 6 Plan 9 (printed 12/22/24)
NDB(8) NDB(8)
name server by the command @name-server. From that point
on, all queries go to that name server rather than being
resolved by dnsdebug. The @ command returns query resolution
to dnsdebug. Finally, any command preceded by a @name-server
sets the name server only for that command.
Normally dnsdebug uses the /net interface and the database
file /lib/ndb/local. The -f option supplies the name of the
data base file to use. The -r option is the same as for
ndb/dns. The -x option directs dnsdebug to use the /net.alt
interface and /lib/ndb/external database file. The -c
option enables caching which is handy for debugging the dns
code.
Ndb/dnsgetip resolves and prints A and AAAA records without
consulting ndb/dns. By default, ndb/dnsgetip queries A
records first and then AAAA records. As with ndb/dns,
/env/DNSSERVER or ndb(6) dns attributes are used as the DNS
server. The -a flag will return all records. The -x option
switches ndb/dnsgetip to query the dns server through
/net.alt instead of /net.
EXAMPLES
Look up helix in ndb.
% ndb/query sys helix
sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot
ip=135.104.117.31 ether=080069020427
Look up plan9.bell-labs.com and its IP address in the DNS.
% ndb/dnsquery
> plan9.bell-labs.com ip
plan9.bell-labs.com ip 204.178.31.2
> 204.178.31.2 ptr
2.31.178.204.in-addr.arpa ptr plan9.bell-labs.com
2.31.178.204.in-addr.arpa ptr ampl.com
>
Print the names of all systems that boot via PXE.
% ndb/query -a bootf /386/9bootpxe sys
FILES
/env/DNSSERVER resolver's DNS servers' IP addresses
/env/DOTSERVER resolver's DNS over TLS servers' IP
addresses
/sys/lib/tls/dns resolver's certificate / public-key
thumbprints
/lib/ndb/local first database file searched
/lib/ndb/local.* hash files for /lib/ndb/local
/srv/cs service file for ndb/cs
Page 7 Plan 9 (printed 12/22/24)
NDB(8) NDB(8)
/net/cs where /srv/cs gets mounted
/srv/dns service file for ndb/dns
/net/dns where /srv/dns gets mounted
SOURCE
/sys/src/cmd/ndb
SEE ALSO
ndb(2), ndb(6)
BUGS
Ndb databases are case-sensitive; ethernet addresses must be
in lower-case hexadecimal.
Page 8 Plan 9 (printed 12/22/24)