ndb 14 KB

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