sys/man/8/ndb

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