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