ref: a9513b7532d1e2fb59159386dd6e4ea28e24bc87
dir: /sys/man/8/ndb/
.TH NDB 8 .SH NAME query, ipquery, mkhash, mkdb, mkhosts, cs, csquery, dns, dnsquery, dnsdebug, dnsgetip, inform \- network database .SH SYNOPSIS .B ndb/query [ .B -acim ] [ .B -f .I dbfile ] [ .B -x .I netmtpt ] .I "attr value" [ .I rattr ]... .br .B ndb/ipquery .I "attr value" .I rattr... .br .B ndb/mkhash .I "file attr" .br .B ndb/mkdb .br .B ndb/mkhosts [ .I domain [ .I dbfile ] ] .br .B ndb/cs [ .B -46n ] [ .B -f .I dbfile ] [ .B -x .I netmtpt ] .br .B ndb/csquery [ .B -s ] [ .I /net/cs [ .I addr... ] ] .br .B ndb/dns [ .B -FnrLR ] [ .B -a .I maxage ] [ .B -c .I cert.pem ] [ .B -f .I dbfile ] [ .B -N .I target ] [ .B -x .I netmtpt ] [ .B -s [ .I addrs... ] ] .br .B ndb/dnsquery [ .B -x ] [ .I /net/dns ] .br .B ndb/dnsdebug [ .B -crdx ] [ .B -f .I dbfile ] [ [ .BI @ server ] .I domain-name [ .I type ] ] .br .B ndb/dnsgetip [ .B -ax ] .I domain-name .br .B ndb/inform [ .B -x .I netmtpt ] .SH DESCRIPTION The network database holds administrative information used by network programs such as .IR dhcpd (8), .IR ipconfig (8), .IR con (1), etc. .PP .I Ndb/query searches the network database for an attribute of type .I attr and value .IR value . If a single .I rattr is specified, only the value of the first matching pair with attribute .I rattr is printed. Under .BR -m , the values of all pairs with a .I rattr attribute within the first matching entry are printed. Under .B -a and with a single .IR rattr , all values of pairs with a .I rattr attribute within all entries are printed. If none or more than one .I rattr where specified, all entries matched by the search are printed in .IR ndb (6) format. When the .B -i flag is present, the type attribute .I attr and its .I value are relating to systems with .B ip= tuples, and the search will return .I rattr attributes inherited from their corresponding .B ipnet= entries. (see the .I ndbipinfo and .I csipinfo functions in .IR ndb (2)). The .B -i flag requires at least one .I rattr and each .I rattr prefixed with a .B @ is resolved to an IP address. When .B -c flag is specified, instead of opening the network database files directly, the connection server mounted on .I netmtpt is consulted. The .I netmtpt can be changed using the .B -x option (default .BR /net ). Without the .B -c flag, the network database is searched directly by opening .I dbfile .RB ( /lib/ndb/local by default). .PP .I Ndb/ipquery uses .I ndbipinfo (see .IR ndb (2)) to search for the values of the attributes .I rattr corresponding to the systems with entries of attribute type .I attr and value .IR value . .PP .I Ndb/inform sends an RFC2136 DNS .I inform packet to a nameserver 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 .BI inform= xxx is found in the host's .I ndb entry. .SS "Database maintenance" .I Ndb/mkhash creates a hash file for all entries with attribute .I attr in database file .IR file . The hash files are used by .I ndb/query and by the ndb library routines. .PP .I Ndb/mkdb is used in concert with .IR 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. .PP When the database files change underfoot, .I ndb/cs and .I ndb/dns track them properly. Nonetheless, to keep the database searches efficient it is necessary to run .I ndb/mkhash whenever the files are modified. It may be profitable to control this by a frequent .IR cron (8) job. .PP .I Ndb/mkhosts generates a BSD style .BR hosts , .BR hosts.txt , and .B hosts.equiv files from an ndb data base file specified on the command line (default .BR /lib/ndb/local ). For local reasons the files are called .BR hosts.1127 , .BR astro.txt , and .BR hosts.equiv . .SS "Connection service" .I Ndb/cs is a server used by .IR dial (2) to translate network names. It is started at boot time. It finds out what networks are configured by looking for .B /net/*/clone when it starts. It can also be told about networks by writing to .B /net/cs a message of the form: .IP .B "add net1 net2 ..." .PP .I Ndb/cs also sets the system name in .B /dev/sysname if it can figure it out. The options are: .TF -n .TP .B -4 Only look up IPv4 addresses (A records) when consulting DNS. The default is to also look up v6 addresses (AAAA records). Writing .L ipv4 to .B /net/cs will toggle IP v4 look-ups. .TP .B -6 Only look up IPv6 addresses in DNS. Writing .L ipv6 to .B /net/cs toggles v6 lookups. .TP .B -f supplies the name of the data base file to use, default .BR /lib/ndb/local . .TP .B -n causes cs to do nothing but set the system name. .TP .B -x specifies the mount point of the network. .PD .PP .I Ndb/csquery queries .I ndb/cs to see how it resolves addresses. .I Ndb/csquery prompts for addresses and prints what .I ndb/cs returns. .I Server defaults to .BR /net/cs . If any .I addrs are specified, .I ndb/csquery prints their translations and immediately exits. The exit status will be nil only if all addresses were successfully translated. The .B -s flag sets exit status without printing any results. .br .ne 4 .SS "Domain name service" .I Ndb/dns serves .I ndb/cs and remote systems by translating Internet domain names. .I Ndb/dns is started at boot time. By default .I dns serves only requests written to .BR /net/dns . Programs must .I seek to offset 0 before reading or writing .B /net/dns or .BR /net/cs . The options are: .TF -n .TP .B -a sets the maximum time in seconds that an unreferenced domain name will remain cached. The default is one hour (3600). .TP .B -f supplies the name of the data base file to use, default .BR /lib/ndb/local . .TP .B -n whenever a DNS zone that we serve changes, send UDP NOTIFY messages to any dns slaves for that zone (see the .L dnsslave attribute below). .TP .B -N sets the goal for the number of domain names cached to .I target rather than the default of 8,000. .TP .B -r act as a resolver only: send `recursive' queries, asking the other servers to complete lookups. If present, .B /env/DNSSERVER or .B /env/DOTSERVER must be a space-separated list of such DNS (or DoT) servers' IP addresses, otherwise optional .IR ndb (6) .B dns attributes name DNS servers to forward queries to. Note that when .B DOTSERVER is specified, .B DNSSERVER are ignored. .TP .B -R ignore the `recursive' bit on all incoming requests. Do not complete lookups on behalf of remote systems. .TP .B -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. .TP .B -s also answer domain requests sent to IP .I addrs on UDP/TCP port 53. If no IP .I addrs are given, listen on any interface on network mount point .IR netmtpt . .TP .B -c When a certificate .I 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 certificate or public key thumbprint into .BR /sys/lib/tls/dns . .TP .B -x specifies the mount point of the network. .PD .PP When the .B -r option is specified, the servers used come from the .I dns attribute in the database. For example, to specify a set of dns servers that will resolve requests for systems on the network .IR mh-net : .IP .EX 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 .EE .LP The server for a domain is indicated by a database entry containing both a .I dom and a .I ns attribute. .IP .EX 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 .EE .LP 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. .SS "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 .B soa= attribute to the root entry. For example, the Bell Labs CS research domain is: .IP .EX 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 .EE .LP Here, the .B mb entry is the mail address of the person responsible for the domain (default .BR postmaster ). The .B mx entries list mail exchangers for the domain name and .B refresh and .B ttl define the area refresh interval and the minimum TTL for records in this domain. The .B dnsslave entries specify slave DNS servers that should be notified when the domain changes. The notification also requires the .B -n flag. . .SS "Reverse Domains" You can also serve reverse lookups (returning the name that goes with an IP address) by adding an .B soa= attribute to the entry defining the root of the reverse space. .PP For example, to provide reverse lookup for all addresses in starting with .L 135.104 or .LR fd00:: , .I ndb must contain a record like: .IP .EX 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 .EE .LP 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 .L .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 .L .ip6.arpa appended. These are the standard forms for a domain name in a PTR record. .PP If such an .B 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 .IP .EX dom=ns1.cs.bell-labs.com ip=135.104.1.11 .EE .LP will automatically create both forward and reverse entries for .BR ns1.cs.bell-labs.com . Unlike other DNS servers, there's no way to generate inconsistent forward and reverse entries. .SS "Classless reverse delegation" Following RFC 2317, it is possible to serve reverse DNS data for IPv4 subnets smaller than /24. Declare the non-/24 subnet, the reverse domain and the individual systems. .PP For example, this is how to serve RFC-2317 .B ptr records for the subnet .LR 65.14.39.128/123 . .IP .EX 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 .EE . .SS "Delegating Name Service Authority" Delegation of a further subtree to another set of name servers is indicated by an .B soa=delegated attribute. .IP .EX dom=bignose.cs.research.bell-labs.com soa=delegated ns=anna.cs.research.bell-labs.com ns=dj.cs.research.bell-labs.com .EE .LP Nameservers within the delegated domain (as in this example) must have their IP addresses listed elsewhere in .I ndb files. . .SS "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: .IP .EX dom=*.research.bell-labs.com mx=research.bell-labs.com .EE .LP `Cname' aliases may be established by adding a .B cname attribute giving the real domain name; the name attached to the .B dom attribute is the alias. `Cname' aliases are severely restricted; the aliases may have no other attributes than .B dom and are daily further restricted in their use by new RFCs. .IP .EX cname=anna.cs.bell-labs.com dom=www.cs.bell-labs.com .EE .PP makes .BI www. ... a synonym for the canonical name .BI anna. ... . .SS "Zone Transfers and TCP" TCP clients requesting DNS zone transfer must be listed with a .B dnsslave attribute for the relevant domain. A value of .B * means any client is accepted. .SS "DNS Queries and Debugging" .I Ndb/dnsquery can be used to query .I ndb/dns to see how it resolves requests. .I Ndb/dnsquery prompts for commands of the form .IP [ .B ! ] .I "domain-name request-type" .LP where .I request-type can be .BR ip , .BR ipv6 , .BR mx , .BR ns , .BR cname , .BR ptr .... In the case of the inverse query type, .BR ptr , .I dnsquery will reverse the ip address and tack on the .B .in-addr.arpa if necessary. If the command starts with an exclamation mark .B ! then the response is returned in .IR ndb (6) format. The .B -x option switches .I ndb/dnsquery to query the dns server on .B /net.alt instead of .BR /net . .PP .I Ndb/dnsdebug is like .I 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 .I ndb/dnsquery with one addition. .I Ndb/dnsdebug can be directed to query a particular name server by the command .BI @ name-server\f1. From that point on, all queries go to that name server rather than being resolved by .IR dnsdebug . The .B @ command returns query resolution to .IR dnsdebug . Finally, any command preceded by a .BI @ name-server sets the name server only for that command. .PP Normally .I dnsdebug uses the .B /net interface and the database file .BR /lib/ndb/local. The .B -f option supplies the name of the data base file to use. The .B -r option is the same as for .IR ndb/dns . The .B -x option directs .I dnsdebug to use the .B /net.alt interface and .B /lib/ndb/external database file. The .B -c option enables caching which is handy for debugging the dns code. .PP .I Ndb/dnsgetip resolves and prints A and AAAA records without consulting .IR ndb/dns . By default, .I ndb/dnsgetip queries A records first and then AAAA records. As with .I ndb/dns, .B /env/DNSSERVER or .IR ndb (6) .B dns attributes are used as the DNS server. The .I -a flag will return all records. The .B -x option switches .I ndb/dnsgetip to query the dns server through .B /net.alt instead of .B /net. .SH EXAMPLES Look up .B helix in .IR ndb . .IP .EX % ndb/query sys helix sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot ip=135.104.117.31 ether=080069020427 .EE .br .ne 8 .LP Look up .B plan9.bell-labs.com and its IP address in the DNS. .IP .EX % 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 > .EE .LP Print the names of all systems that boot via PXE. .IP .EX % ndb/query -a bootf /386/9bootpxe sys .EE .SH FILES .TF /lib/ndb/local.*xxx .TP .B /env/DNSSERVER resolver's DNS servers' IP addresses .TP .B /env/DOTSERVER resolver's DNS over TLS servers' IP addresses .TP .B /sys/lib/tls/dns resolver's certificate / public-key thumbprints .TP .B /lib/ndb/local first database file searched .TP .B /lib/ndb/local.* hash files for .B /lib/ndb/local .TP .B /srv/cs service file for .I ndb/cs .TP .B /net/cs where .B /srv/cs gets mounted .TP .B /srv/dns service file for .I ndb/dns .TP .B /net/dns where .B /srv/dns gets mounted .SH SOURCE .B /sys/src/cmd/ndb .SH SEE ALSO .IR ndb (2), .IR ndb (6) .SH BUGS .I Ndb databases are case-sensitive; ethernet addresses must be in lower-case hexadecimal.