ndb 15 KB

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