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