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