]> git.lizzy.rs Git - plan9front.git/blob - sys/man/8/ndb
f6da3bbb870af5da4f6b72b6a1582f4749e035ca
[plan9front.git] / sys / man / 8 / ndb
1 .TH NDB 8
2 .SH NAME
3 query, ipquery, mkhash, mkdb, mkhosts, cs, csquery, dns, dnstcp, dnsquery, dnsdebug, dnsgetip, inform \- network database
4 .SH SYNOPSIS
5 .B ndb/query
6 [
7 .B -am
8 ] [
9 .B -f
10 .I dbfile
11 ]
12 .I "attr value"
13 [
14 .I rattr
15 .\" [
16 .\" .I reps
17 .\" ]
18 ]
19 .br
20 .B ndb/ipquery
21 .I "attr value"
22 .I rattr...
23 .br
24 .B ndb/mkhash
25 .I "file attr"
26 .br
27 .B ndb/mkdb
28 .br
29 .B ndb/mkhosts
30 [
31 .I domain
32 [
33 .I dbfile
34 ] ]
35 .br
36 .B ndb/cs
37 [
38 .B -46n
39 ] [
40 .B -f
41 .I dbfile
42 ] [
43 .B -x
44 .I netmtpt
45 ]
46 .br
47 .B ndb/csquery
48 [
49 .B -s
50 ]
51 [
52 .I /net/cs
53 [
54 .I addr...
55 ]
56 ]
57 .br
58 .B ndb/dns
59 [
60 .B -norRs
61 ] [
62 .B -a
63 .I maxage
64 ] [
65 .B -f
66 .I dbfile
67 ] [
68 .B -N
69 .I target
70 ] [
71 .B -x
72 .I netmtpt
73 ] [
74 .B -z
75 .I program
76 ]
77 .br
78 .B ndb/dnstcp
79 [
80 .B -arR
81 ] [
82 .B -f
83 .I dbfile
84 ] [
85 .B -x
86 .I netmtpt
87 ] [
88 .I conn-dir
89 ]
90 .br
91 .B ndb/dnsquery
92 [
93 .B -x
94 ] [
95 .I /net/dns
96 ]
97 .br
98 .B ndb/dnsdebug
99 [
100 .B -rxc
101 ] [
102 .B -f
103 .I dbfile
104 ] [ [
105 .BI @ server
106 ]
107 .I domain-name
108 [
109 .I type
110 ] ]
111 .br
112 .B ndb/dnsgetip
113 [
114 .B -ax
115 ]
116 .I domain-name
117 .br
118 .B ndb/inform
119 [
120 .B -x
121 .I netmtpt
122 ]
123 .SH DESCRIPTION
124 The network database holds administrative information used by
125 network programs such as
126 .IR dhcpd (8),
127 .IR ipconfig (8),
128 .IR con (1),
129 etc.
130 .PP
131 .I Ndb/query
132 searches the database
133 .I dbfile
134 .RB ( /lib/ndb/local
135 by default)
136 for an attribute of type
137 .I attr
138 and value
139 .IR value .
140 If
141 .I rattr
142 is not specified, all entries matched by the search are printed.
143 If
144 .I rattr
145 is specified, the value of the first pair with attribute
146 .I rattr
147 of all the matched entries normally is printed.
148 Under
149 .B -m
150 and
151 .IR rattr ,
152 the values of all pairs with a
153 .I rattr
154 attribute within the first matching entry are printed.
155 Under
156 .B -a
157 and
158 .IR rattr ,
159 all values of pairs with a
160 .I rattr
161 attribute within all entries are printed.
162 .PP
163 .I Ndb/ipquery
164 uses
165 .I ndbipinfo
166 (see
167 .IR ndb (2))
168 to search for the values of the attributes
169 .I rattr
170 corresponding to the system
171 with entries of attribute type
172 .I attr
173 and
174 value
175 .IR value .
176 .PP
177 .I Ndb/inform
178 sends an RFC2136 DNS
179 .I inform
180 packet to a nameserver to associate the host's IP address with its DNS name.
181 This is required if the domain's nameserver is
182 a Microsoft Windows Active Directory controller.
183 The host's domain name will be sent to the AD controller unless 
184 a tuple of the form
185 .BI inform= xxx
186 is found in the host's
187 .I ndb
188 entry.
189 .SS "Database maintenance"
190 .I Ndb/mkhash
191 creates a hash file for all entries with attribute
192 .I attr
193 in database file
194 .IR file .
195 The hash files are used by
196 .I ndb/query
197 and by the ndb library routines.
198 .PP
199 .I Ndb/mkdb
200 is used in concert with
201 .IR awk (1)
202 scripts to convert
203 uucp systems files and IP host files
204 into database files.
205 It is very specific to the situation at Murray Hill.
206 .PP
207 When the database files change underfoot,
208 .I ndb/cs
209 and
210 .I ndb/dns
211 track them properly.  Nonetheless, to keep the database searches efficient
212 it is necessary to run
213 .I ndb/mkhash
214 whenever the files are modified.
215 It may be profitable to control this by a frequent
216 .IR cron (8)
217 job.
218 .PP
219 .I Ndb/mkhosts
220 generates a BSD style
221 .BR hosts ,
222 .BR hosts.txt ,
223 and
224 .B hosts.equiv
225 files from an ndb data base file specified on the
226 command line (default
227 .BR /lib/ndb/local ).
228 For local reasons the files are called
229 .BR hosts.1127 ,
230 .BR astro.txt ,
231 and
232 .BR hosts.equiv .
233 .SS "Connection service"
234 .I Ndb/cs
235 is a server used by
236 .IR dial (2)
237 to translate network names.
238 It is started at boot time.
239 It finds out what networks are configured
240 by looking for
241 .B /net/*/clone
242 when it starts.
243 It can also be told about networks by writing to
244 .B /net/cs
245 a message of the form:
246 .IP
247 .B "add net1 net2 ..."
248 .PP
249 .I Ndb/cs
250 also sets the system name in
251 .B /dev/sysname
252 if it can figure it out.
253 The options are:
254 .TF -n
255 .TP
256 .B -4
257 Only look up IPv4 addresses (A records) when consulting DNS.
258 The default is to also look up v6 addresses (AAAA records).
259 Writing
260 .L ipv4
261 to
262 .B /net/cs
263 will toggle IP v4 look-ups.
264 .TP
265 .B -6
266 Only look up IPv6 addresses in DNS.
267 Writing
268 .L ipv6
269 to
270 .B /net/cs
271 toggles v6 lookups.
272 .TP
273 .B -f
274 supplies the name of the data base file to use,
275 default
276 .BR /lib/ndb/local .
277 .TP
278 .B -n
279 causes cs to do nothing but set the system name.
280 .TP
281 .B -x
282 specifies the mount point of the
283 network.
284 .PD
285 .PP
286 .I Ndb/csquery
287 queries
288 .I ndb/cs
289 to see how it resolves addresses.
290 .I Ndb/csquery
291 prompts for addresses and prints what
292 .I ndb/cs
293 returns.
294 .I Server
295 defaults to
296 .BR /net/cs .
297 If any
298 .I addrs
299 are specified,
300 .I ndb/csquery
301 prints their translations and immediately exits.
302 The exit status will be nil only if all addresses
303 were successfully translated.
304 The
305 .B -s
306 flag sets exit status without printing any results.
307 .br
308 .ne 4
309 .SS "Domain name service"
310 .I Ndb/dns
311 serves
312 .I ndb/cs
313 and remote systems by translating Internet domain names.
314 .I Ndb/dns
315 is started at boot time.
316 By default
317 .I dns
318 serves only requests written to
319 .BR /net/dns .
320 Programs must
321 .I seek
322 to offset 0 before reading or writing
323 .B /net/dns
324 or
325 .BR /net/cs .
326 The options are:
327 .TF -n
328 .TP
329 .B -a
330 sets the maximum time in seconds that an unreferenced
331 domain name will remain cached.
332 The default is one hour (3600).
333 .TP
334 .B -f
335 supplies the name of the data base file to use,
336 default
337 .BR /lib/ndb/local .
338 .TP
339 .B -n
340 whenever a DNS zone that we serve changes, send UDP NOTIFY
341 messages to any dns slaves for that zone
342 (see the
343 .L dnsslave
344 attribute below).
345 .TP
346 .B -N
347 sets the goal for the number of domain names cached to
348 .I target
349 rather than the default of 8,000.
350 .TP
351 .B -o
352 used with
353 .BR -s ,
354 .B -o
355 causes
356 .I dns
357 to assume that it straddles inside and outside networks
358 and that the outside network is mounted on
359 .BR /net.alt .
360 Queries for inside addresses will be sent via
361 .B /net/udp
362 (or
363 .B /net/tcp
364 in response to truncated replies)
365 and those for outside addresses via
366 .B /net.alt/udp
367 (or
368 .BR /net.alt/tcp ).
369 This makes
370 .I dns
371 suitable for serving non-Plan-9 systems in an organization with
372 firewalls, DNS proxies, etc.,
373 particularly if they don't work very well.
374 See `Straddling Server' below for details.
375 .TP
376 .B -r
377 act as a resolver only:
378 send `recursive' queries, asking the other servers
379 to complete lookups.
380 If present,
381 .B /env/DNSSERVER
382 must be a space-separated list of such DNS servers' IP addresses,
383 otherwise optional
384 .IR ndb (6)
385 .B dns
386 attributes name DNS servers to forward queries to.
387 .TP
388 .B -R
389 ignore the `recursive' bit on incoming requests.
390 Do not complete lookups on behalf of remote systems.
391 .TP
392 .B -s
393 also answer domain requests sent to UDP port 53.
394 .TP
395 .B -x
396 specifies the mount point of the
397 network.
398 .TP
399 .B -z
400 whenever we receive a UDP NOTIFY message, run
401 .I program
402 with the domain name of the area as its argument.
403 .PD
404 .PP
405 When the
406 .B -r
407 option is specified, the servers used come from the
408 .I dns
409 attribute in the database.  For example, to specify a set of dns servers that
410 will resolve requests for systems on the network
411 .IR mh-net :
412 .IP
413 .EX
414 ipnet=mh-net ip=135.104.0.0 ipmask=255.255.0.0
415         dns=ns1.cs.bell-labs.com
416         dns=ns2.cs.bell-labs.com
417 dom=ns1.cs.bell-labs.com ip=135.104.1.11
418 dom=ns2.cs.bell-labs.com ip=135.104.1.12
419 .EE
420 .LP
421 The server for a domain is indicated by a database entry containing
422 both a
423 .I dom
424 and a
425 .I ns
426 attribute.
427 .IP
428 .EX
429 dom=
430         ns=A.ROOT-SERVERS.NET
431         ns=B.ROOT-SERVERS.NET
432         ns=C.ROOT-SERVERS.NET
433 dom=A.ROOT-SERVERS.NET ip=198.41.0.4
434 dom=B.ROOT-SERVERS.NET ip=128.9.0.107
435 dom=C.ROOT-SERVERS.NET ip=192.33.4.12
436 .EE
437 .LP
438 The last three lines provide a mapping for the
439 server names to their ip addresses.  This is only
440 a hint and will be superseded from whatever is learned
441 from servers owning the domain.
442 .SS "Authoritative Name Servers"
443 You can also serve a subtree of the domain name space from the local
444 database.  You indicate subtrees that you would like to serve by adding an
445 .B soa=
446 attribute to the root entry.
447 For example, the Bell Labs CS research domain is:
448 .IP
449 .EX
450 dom=cs.bell-labs.com soa=
451         refresh=3600 ttl=3600
452         ns=plan9.bell-labs.com
453         ns=ns1.cs.bell-labs.com
454         ns=ns2.cs.bell-labs.com
455         mb=presotto@plan9.bell-labs.com
456         mx=mail.research.bell-labs.com pref=20
457         mx=plan9.bell-labs.com pref=10
458         dnsslave=nslocum.cs.bell-labs.com
459         dnsslave=vex.cs.bell-labs.com
460 .EE
461 .LP
462 Here, the
463 .B mb
464 entry is the mail address of the person responsible for the
465 domain (default
466 .BR postmaster ).
467 The
468 .B mx
469 entries list mail exchangers for the domain name and
470 .B refresh
471 and
472 .B ttl
473 define the area refresh interval and the minimum TTL for
474 records in this domain.
475 The
476 .B dnsslave
477 entries specify slave DNS servers that should be notified
478 when the domain changes.  The notification also requires
479 the
480 .B -n
481 flag.
482 .
483 .SS "Reverse Domains"
484 You can also serve reverse lookups (returning the name that
485 goes with an IP address) by adding an
486 .B soa=
487 attribute to the entry defining the root of the reverse space.
488 .PP
489 For example, to provide reverse lookup for all addresses in
490 starting with
491 .L 135.104
492 or
493 .LR fd00:: ,
494 .I ndb
495 must contain a record like:
496 .IP
497 .EX
498 dom=104.135.in-addr.arpa soa=
499         dom=d.f.ip6.arpa soa=   # special case, rfc 4193
500         refresh=3600 ttl=3600
501         ns=plan9.bell-labs.com
502         ns=ns1.cs.bell-labs.com
503         ns=ns2.cs.bell-labs.com
504 .EE
505 .LP
506 Notice the form of the reverse address.
507 For IPv4, it's the bytes of the address range you are serving reversed
508 and expressed in decimal, and with
509 .L .in-addr.arpa
510 appended.
511 For IPv6, it's the nibbles (4-bit fields) of the address range you are serving
512 reversed and expressed in hexadecimal, and with
513 .L .ip6.arpa
514 appended.
515 These are the standard forms for a domain name in a PTR record.
516 .PP
517 If such an
518 .B soa
519 entry exists in the database, reverse addresses will
520 automatically be generated from any IP addresses in the database
521 that are under this root.  For example
522 .IP
523 .EX
524 dom=ns1.cs.bell-labs.com ip=135.104.1.11
525 .EE
526 .LP
527 will automatically create both forward and reverse entries for
528 .BR ns1.cs.bell-labs.com .
529 Unlike other DNS servers, there's no way to generate
530 inconsistent forward and reverse entries.
531 .SS "Classless reverse delegation"
532 Following RFC 2317, it is possible to serve reverse DNS data
533 for IPv4 subnets smaller than /24.
534 Declare the non-/24 subnet, the reverse domain and the individual systems.
535 .PP
536 For example,
537 this is how to serve RFC-2317
538 .B ptr
539 records for the subnet
540 .LR 65.14.39.128/123 .
541 .IP
542 .EX
543 ipnet=our-t1 ip=65.14.39.128 ipmask=/123
544 dom=128.39.14.65.in-addr.arpa soa=
545         refresh=3600 ttl=3600
546         ns=ns1.our-domain.com
547         ns=ns2.our-domain.com
548 ip=65.14.39.129 dom=router.our-domain.com
549 .EE
550 .
551 .SS "Delegating Name Service Authority"
552 Delegation of a further subtree to another set of name servers
553 is indicated by an
554 .B soa=delegated
555 attribute.
556 .IP
557 .EX
558 dom=bignose.cs.research.bell-labs.com
559         soa=delegated
560         ns=anna.cs.research.bell-labs.com
561         ns=dj.cs.research.bell-labs.com
562 .EE
563 .LP
564 Nameservers within the delegated domain (as in this example)
565 must have their IP addresses listed elsewhere in
566 .I ndb
567 files.
568 .
569 .SS "Wildcards, MX and CNAME records"
570 Wild-carded domain names can also be used.
571 For example, to specify a mail forwarder for all Bell Labs research systems:
572 .IP
573 .EX
574 dom=*.research.bell-labs.com
575         mx=research.bell-labs.com
576 .EE
577 .LP
578 `Cname' aliases may be established by adding a
579 .B cname
580 attribute giving the real domain name;
581 the name attached to the
582 .B dom
583 attribute is the alias.
584 `Cname' aliases are severely restricted;
585 the aliases may have no other attributes than
586 .B dom
587 and are daily further restricted in their use by new RFCs.
588 .IP
589 .EX
590 cname=anna.cs.bell-labs.com dom=www.cs.bell-labs.com
591 .EE
592 .PP
593 makes
594 .BI www. ...
595 a synonym for the canonical name
596 .BI anna. ... .
597 .SS "Straddling Server"
598 Many companies have an inside network
599 protected from outside access with firewalls.
600 They usually provide internal `root' DNS servers
601 (of varying reliability and correctness)
602 that serve internal domains and pass on DNS queries for
603 outside domains to the outside, relaying the results
604 back and caching them for future use.
605 Some companies don't even let DNS queries nor replies through
606 their firewalls at all, in either direction.
607 .PP
608 In such a situation, running
609 .B "dns -so"
610 on a machine that imports access to the outside network via
611 .B /net.alt
612 from a machine that straddles the firewalls,
613 or that straddles the firewalls itself,
614 will let internal machines query such a machine
615 and receive answers from outside nameservers for outside addresses
616 and inside nameservers for inside addresses, giving the appearance
617 of a unified domain name space,
618 while bypassing the corporate DNS proxies or firewalls.
619 This is different from running
620 .B "dns -s"
621 and
622 .B "dns -sRx /net.alt -f /lib/ndb/external"
623 on the same machine,
624 which keeps the inside and outside namespaces entirely separate.
625 .PP
626 Under
627 .BR -o ,
628 several
629 .I sys
630 names are significant:
631 .BR inside-dom ,
632 .BR inside-ns ,
633 and
634 .BR outside-ns .
635 .I Inside-dom
636 should contain a series of
637 .B dom
638 pairs naming domains internal to the organization.
639 .I Inside-ns
640 should contain a series of
641 .B ip
642 pairs naming the internal DNS `root' servers.
643 .I Outside-ns
644 should contain a series of
645 .B ip
646 pairs naming the external DNS servers to consult.
647 .SS "Zone Transfers and TCP"
648 .I Dnstcp
649 is invoked,
650 usually from
651 .BR /rc/bin/service/tcp53 ,
652 to answer DNS queries with long answers via TCP,
653 notably to transfer a zone within the database
654 .I dbfile
655 (default
656 .BR /lib/ndb/local )
657 to its invoker on the network at
658 .I netmtpt
659 (default
660 .BR /net ).
661 Standard input will be read for DNS requests and the DNS answers
662 will appear on standard output.
663 Recursion is disabled by
664 .BR -R ;
665 acting as a pure resolver is enabled by
666 .BR -r .
667 Unless the
668 .B -a
669 flag is provided, clients requesting DNS zone transfer must be listed
670 with a
671 .B dnsslave
672 attribute for the relevant domain.
673 If
674 .I conn-dir
675 is provided, it is assumed to be a directory within
676 .IB netmtpt /tcp
677 and is used to find the caller's address.
678 .SS "DNS Queries and Debugging"
679 .I Ndb/dnsquery
680 can be used to query
681 .I ndb/dns
682 to see how it resolves requests.
683 .I Ndb/dnsquery
684 prompts for commands of the form
685 .IP
686 .I "domain-name request-type"
687 .LP
688 where
689 .I request-type
690 can be
691 .BR ip ,
692 .BR ipv6 ,
693 .BR mx ,
694 .BR ns ,
695 .BR cname ,
696 .BR ptr ....
697 In the case of the inverse query type,
698 .BR ptr ,
699 .I dnsquery
700 will reverse the ip address and tack on the
701 .B .in-addr.arpa
702 if necessary.
703 The
704 .B -x
705 option switches
706 .I ndb/dnsquery
707 to query the dns server on
708 .B /net.alt
709 instead of
710 .B /net
711 .PP
712 .I Ndb/dnsdebug
713 is like
714 .I ndb/dnsquery
715 but bypasses the local server.
716 It communicates via UDP (and sometimes TCP) with the domain name servers
717 in the same way that the local resolver would and displays
718 all packets received.
719 The query can be specified on the command line or
720 can be prompted for.
721 The queries look like those of
722 .I ndb/dnsquery
723 with one addition.
724 .I Ndb/dnsdebug
725 can be directed to query a particular name server by
726 the command
727 .BI @ name-server\f1.
728 From that point on, all queries go to that name server
729 rather than being resolved by
730 .IR dnsdebug .
731 The
732 .B @
733 command returns query resolution to
734 .IR dnsdebug .
735 Finally, any command preceded by a
736 .BI @ name-server
737 sets the name server only for that command.
738 .PP
739 Normally
740 .I dnsdebug
741 uses the
742 .B /net
743 interface and the database file
744 .BR /lib/ndb/local.
745 The
746 .B -f
747 option supplies the name of the data base file to use.
748 The
749 .B -r
750 option is the same as for
751 .IR ndb/dns .
752 The
753 .B -x
754 option directs
755 .I dnsdebug
756 to use the
757 .B /net.alt
758 interface and
759 .B /lib/ndb/external
760 database file.
761 The
762 .B -c
763 option enables caching which is handy for debugging the dns code.
764 .PP
765 .I Ndb/dnsgetip
766 resolves and prints A and AAAA records without consulting
767 .I ndb/dns .
768 By default,
769 .I ndb/dnsgetip
770 queries A records first and then AAAA records. As with
771 .I ndb/dns,
772 .B /env/DNSSERVER
773 or
774 .IR ndb (6)
775 .B dns
776 attributes are used as the DNS server. The
777 .I -a
778 flag will return all records. The
779 .B -x
780 option switches
781 .I ndb/dnsgetip
782 to query the dns server through
783 .B /net.alt
784 instead of
785 .B /net.
786 .SH EXAMPLES
787 Look up
788 .B helix
789 in
790 .IR ndb .
791 .IP
792 .EX
793 % ndb/query sys helix
794 sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot
795         ip=135.104.117.31 ether=080069020427
796 .EE
797 .br
798 .ne 8
799 .LP
800 Look up
801 .B plan9.bell-labs.com
802 and its IP address in the DNS.
803 .IP
804 .EX
805 % ndb/dnsquery
806 > plan9.bell-labs.com ip
807 plan9.bell-labs.com ip  204.178.31.2
808 > 204.178.31.2 ptr
809 2.31.178.204.in-addr.arpa ptr   plan9.bell-labs.com
810 2.31.178.204.in-addr.arpa ptr   ampl.com
811 >
812 .EE
813 .LP
814 Print the names of all systems that boot via PXE.
815 .IP
816 .EX
817 % ndb/query -a bootf /386/9bootpxe sys
818 .EE
819 .SH FILES
820 .TF /lib/ndb/local.*xxx
821 .TP
822 .B /env/DNSSERVER
823 resolver's DNS servers' IP addresses.
824 .TP
825 .B /lib/ndb/local
826 first database file searched
827 .TP
828 .B /lib/ndb/local.*
829 hash files for
830 .B /lib/ndb/local
831 .TP
832 .B /srv/cs
833 service file for
834 .I ndb/cs
835 .TP
836 .B /net/cs
837 where
838 .B /srv/cs
839 gets mounted
840 .TP
841 .B /srv/dns
842 service file for
843 .I ndb/dns
844 .TP
845 .B /net/dns
846 where
847 .B /srv/dns
848 gets mounted
849 .SH SOURCE
850 .B /sys/src/cmd/ndb
851 .SH SEE ALSO
852 .IR ndb (2),
853 .IR ndb (6)
854 .SH BUGS
855 .I Ndb
856 databases are case-sensitive;
857 ethernet addresses must be in lower-case hexadecimal.