ndb 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520
  1. .TH NDB 8
  2. .SH NAME
  3. query, mkhash, mkdb, cs, csquery, dns, dnsquery, ipquery, dnsdebug, mkhosts \- network database
  4. .SH SYNOPSIS
  5. .B ndb/query
  6. [
  7. .B -f
  8. .I dbfile
  9. ]
  10. .I "attr value"
  11. [
  12. .I rattr
  13. ]
  14. .br
  15. .B ndb/ipquery
  16. .I "attr value"
  17. .I rattr...
  18. .br
  19. .B ndb/mkhash
  20. .I "file attr"
  21. .br
  22. .B ndb/cs
  23. [
  24. .B -n
  25. ] [
  26. .B -f
  27. .I dbfile
  28. ] [
  29. .B -x
  30. .I netmtpt
  31. ]
  32. .br
  33. .B ndb/csquery
  34. [
  35. .B -s
  36. ]
  37. [
  38. .B server
  39. [
  40. .I addr...
  41. ]
  42. ]
  43. .br
  44. .B ndb/dns
  45. [
  46. .B -rRsn
  47. ] [
  48. .B -f
  49. .I dbfile
  50. ] [
  51. .B -x
  52. .I netmtpt
  53. ] [
  54. .B -z
  55. .I program
  56. ]
  57. .br
  58. .B ndb/dnsquery
  59. .br
  60. .B ndb/dnsdebug
  61. [
  62. .B -rx
  63. ]
  64. [ [
  65. .BI @ server
  66. ]
  67. .I domain-name
  68. [
  69. .I type
  70. ] ]
  71. .br
  72. .B ndb/mkdb
  73. .SH DESCRIPTION
  74. The network database holds administrative information used by
  75. network programs such as
  76. .IR dhcpd (8),
  77. .IR ipconfig (8),
  78. .IR con (1),
  79. etc.
  80. .PP
  81. .I Ndb/query
  82. searches the database for an attribute of type
  83. .I attr
  84. and value
  85. .IR value .
  86. If
  87. .I rattr
  88. is not specified, all entries matched by the search are returned.
  89. If
  90. .I rattr
  91. is specified, the value of the first pair with attribute
  92. .I rattr
  93. of all the matched entries is returned.
  94. .PP
  95. .I Ndb/ipquery
  96. uses
  97. .I ndbipinfo
  98. (see
  99. .IR ndb (2))
  100. to search for the values of the attributes
  101. .I rattr
  102. corresponding to the system
  103. with entries of attribute type
  104. .I attr
  105. and
  106. value
  107. .IR value .
  108. .PP
  109. .I Ndb/mkhash
  110. creates a hash file for all entries with attribute
  111. .I attr
  112. in database file
  113. .IR file .
  114. The hash files are used by
  115. .I ndb/query
  116. and by the ndb library routines.
  117. .PP
  118. .I Ndb/cs
  119. is a server used by
  120. .IR dial (2)
  121. to translate network names.
  122. It is started at boot time.
  123. It finds out what networks are configured
  124. by looking for
  125. .B /net/*/clone
  126. when it starts.
  127. It can also be told about networks by writing
  128. to
  129. .B /net/cs
  130. a message of the form:
  131. .IP
  132. .B "add net1 net2 ..."
  133. .PP
  134. .I Ndb/cs
  135. also sets the system name in
  136. .B /dev/sysname
  137. if it can figure it out.
  138. The options are:
  139. .TP
  140. .B -f
  141. supplies the name of the data base file to use,
  142. default
  143. .BR /lib/ndb/local .
  144. .TP
  145. .B -x
  146. specifies the mount point of the
  147. network.
  148. .TP
  149. .B -n
  150. causes cs to do nothing but set the system name.
  151. .PP
  152. .I Ndb/csquery
  153. can be used to query
  154. .I ndb/cs
  155. to see how it resolves addresses.
  156. .I Ndb/csquery
  157. prompts for addresses and prints out what
  158. .I ndb/cs
  159. returns.
  160. .I Server
  161. defaults to
  162. .BR /net/cs .
  163. If any
  164. .I addrs
  165. are specified,
  166. .I ndb/csquery
  167. prints their translations and immediately exits.
  168. The exit status will be nil only if all addresses
  169. were successfully translated
  170. The
  171. .B -s
  172. flag sets exit status without printing any results.
  173. .PP
  174. .I Ndb/dns
  175. is a server used by
  176. .I ndb/cs
  177. and by remote systems to translate Internet domain names.
  178. .I Ndb/dns
  179. is started at boot time.
  180. By default
  181. .I dns
  182. serves only requests written to
  183. .BR /net/dns .
  184. The options are:
  185. .TP
  186. .B -f
  187. supplies the name of the data base file to use,
  188. default
  189. .BR /lib/ndb/local .
  190. .TP
  191. .B -x
  192. specifies the mount point of the
  193. network.
  194. .TP
  195. .B -s
  196. also answer domain requests sent to UDP port 53.
  197. .TP
  198. .B -n
  199. whenever a zone that we serve changes, send UDP NOTIFY
  200. messages to any dns slaves for that zone.
  201. .TP
  202. .B -z
  203. whenever we receive a UDP NOTIFY message, run
  204. .I program
  205. with the domain name of the area as its argument.
  206. .TP
  207. .B -r
  208. send `recursive' queries, asking the other servers
  209. to complete lookups.
  210. .TP
  211. .B -R
  212. ignore the `recursive' bit on incoming requests.
  213. do not complete lookups on behalf of remote systems.
  214. .PD
  215. .PP
  216. When the
  217. .B -r
  218. option is specified, the servers used come from the
  219. .I dns
  220. attribute in the database. For example, to specify a set of dns servers that
  221. will resolve requests for systems on the network
  222. .IR mh-net :
  223. .EX
  224. ipnet=mh-net ip=135.104.0.0 ipmask=255.255.0.0
  225. dns=ns1.cs.bell-labs.com
  226. dns=ns2.cs.bell-labs.com
  227. dom=ns1.cs.bell-labs.com ip=135.104.1.11
  228. dom=ns2.cs.bell-labs.com ip=135.104.1.12
  229. .EE
  230. .PP
  231. The server for a domain is indicated by a database entry containing
  232. both a
  233. .I dom
  234. and a
  235. .I ns
  236. attribute.
  237. For example, the entry for the Internet root is:
  238. .EX
  239. dom=
  240. ns=A.ROOT-SERVERS.NET
  241. ns=B.ROOT-SERVERS.NET
  242. ns=C.ROOT-SERVERS.NET
  243. dom=A.ROOT-SERVERS.NET ip=198.41.0.4
  244. dom=B.ROOT-SERVERS.NET ip=128.9.0.107
  245. dom=C.ROOT-SERVERS.NET ip=192.33.4.12
  246. .EE
  247. The last three lines provide a mapping for the
  248. server names to their ip addresses. This is only
  249. a hint and will be superseded from whatever is learned
  250. from servers owning the domain.
  251. .PP
  252. You can also serve a subtree of the domain name space from the local
  253. database. You indicate subtrees that you'ld like to serve by
  254. adding an
  255. .B soa=
  256. attribute to the root entry.
  257. For example, the Bell Labs CS research domain is:
  258. .EX
  259. dom=cs.bell-labs.com soa=
  260. refresh=3600 ttl=3600
  261. ns=plan9.bell-labs.com
  262. ns=ns1.cs.bell-labs.com
  263. ns=ns2.cs.bell-labs.com
  264. mb=presotto@plan9.bell-labs.com
  265. mx=mail.research.bell-labs.com pref=20
  266. mx=plan9.bell-labs.com pref=10
  267. dnsslave=nslocum.cs.bell-labs.com
  268. dnsslave=vex.cs.bell-labs.com
  269. .EE
  270. Here, the
  271. .B mb
  272. entry is the mail address of the person responsible for the
  273. domain (default
  274. .BR postmaster ).
  275. The
  276. .B mx
  277. entries list mail exchangers for the domain name and
  278. .B refresh
  279. and
  280. .B ttl
  281. define the area refresh interval and the minimum TTL for
  282. records in this domain.
  283. The
  284. .B dnsslave
  285. entries specify slave DNS servers that should be notified
  286. when the domain changes. The notification also requires
  287. the
  288. .B -n
  289. flag.
  290. .PP
  291. You can also serve reverse lookups (returning the name that
  292. goes with an IP address) by adding an
  293. .B soa=
  294. attribute to the entry defining the root of the reverse space.
  295. For example, to provide reverse lookup for all addresses in
  296. starting with 135.104 you must have a record like:
  297. .EX
  298. dom=104.135.in-addr.arpa soa=
  299. refresh=3600 ttl=3600
  300. ns=plan9.bell-labs.com
  301. ns=ns1.cs.bell-labs.com
  302. ns=ns2.cs.bell-labs.com
  303. .EE
  304. Notice the form of the reverse address, i.e., it's the bytes of the
  305. address range you are serving reversed and with
  306. .B .in-addr.arpa
  307. appended. This is a standard form for a domain name in an IPv4 PTR record.
  308. .PP
  309. If such an entry exists in the database, reverse addresses will
  310. automatically be generated from any IP addresses in the database
  311. that are under this root. For example
  312. .EX
  313. dom=ns1.cs.bell-labs.com ip=135.104.1.11
  314. .EE
  315. will automatically create both forward and reverse entries for
  316. .B ns1.cs.bell-labs.com .
  317. Unlike other DNS servers, there's no way to generate
  318. inconsistent forward and reverse entries.
  319. .PP
  320. Delegation of a further subtree to another set of name servers
  321. is indicated by an
  322. .B soa=delegated
  323. attribute.
  324. .EX
  325. dom=bignose.cs.research.bell-labs.com
  326. soa=delegated
  327. ns=anna.cs.research.bell-labs.com
  328. ns=dj.cs.research.bell-labs.com
  329. .EE
  330. Nameservers within the delegated domain (as in this example)
  331. must have their IP addresses listed elsewhere in
  332. .I ndb
  333. files.
  334. .PP
  335. Wild-carded domain names can also be used.
  336. For example, to specify a mail forwarder for all Bell Labs research systems:
  337. .EX
  338. dom=*.research.bell-labs.com
  339. mx=research.bell-labs.com
  340. .EE
  341. `Cname' aliases may be established by adding a
  342. .B cname
  343. attribute giving the real domain name;
  344. the name attached to the
  345. .B dom
  346. attribute is the alias.
  347. `Cname' aliases are severely restricted;
  348. the aliases may have no other attributes than
  349. .B dom
  350. and are daily further restricted in their use by new RFCs.
  351. .EX
  352. cname=anna.cs.research.bell-labs.com dom=www.cs.research.bell-labs.com
  353. .EE
  354. .I Ndb/dnsquery
  355. can be used to query
  356. .I ndb/dns
  357. to see how it resolves requests.
  358. .I Ndb/dnsquery
  359. prompts for commands of the form
  360. .IP
  361. .I "domain-name request-type"
  362. .LP
  363. where
  364. .I request-type
  365. can be
  366. .BR ip ,
  367. .BR mx ,
  368. .BR ns ,
  369. .BR cname ,
  370. .BR ptr ....
  371. In the case of the inverse query type,
  372. .BR ptr ,
  373. .I dnsquery
  374. will reverse the ip address and tack on the
  375. .B .in-addr.arpa
  376. for you.
  377. .PP
  378. .I Ndb/dnsdebug
  379. is like
  380. .I ndb/dnsquery
  381. but bypasses the local server.
  382. It communicates via UDP with the domain name servers
  383. in the same way that the local resolver would and displays
  384. all packets received.
  385. The query can be specified on the command line or
  386. can be prompted for.
  387. The queries look like those of
  388. .I ndb/dnsquery
  389. with one addition.
  390. .I Ndb/dnsdebug
  391. can be directed to query a particular name server by
  392. the command
  393. .BI @ name-server\f1.
  394. From that point on, all queries go to that name server
  395. rather than being resolved by
  396. .IR dnsdebug .
  397. The
  398. .B @
  399. command returns query resolution to
  400. .IR dnsdebug .
  401. Finally, any command preceded by a
  402. .BI @ name-server
  403. sets the name server only for that command.
  404. .PP
  405. Normally
  406. .I dnsdebug
  407. uses the
  408. .B /net
  409. interface and the database file
  410. .BR /lib/ndb/local.
  411. The
  412. .B -x
  413. option directs
  414. .I dnsdebug
  415. to use the
  416. .B /net.alt
  417. interface and
  418. .B /lib/ndb/external
  419. file.
  420. The
  421. .B -r
  422. option is the same as for
  423. .IR ndb/dns .
  424. .PP
  425. .I Ndb/mkdb
  426. is used in concert with
  427. .IR awk (1)
  428. scripts to convert
  429. uucp systems files and IP host files
  430. into database files.
  431. It is very specific to the situation at Murray Hill.
  432. .PP
  433. When the database files change underfoot,
  434. .I ndb/cs
  435. and
  436. .I ndb/dns
  437. track them properly. Nonetheless, to keep the database searches efficient
  438. it is necessary to run
  439. .I ndb/mkhash
  440. whenever the files are modified.
  441. It may be profitable to control this by a frequent
  442. .IR cron (8)
  443. job.
  444. .PP
  445. .I Ndb/mkhosts
  446. generates a BSD style
  447. .BR hosts ,
  448. .BR hosts.txt ,
  449. and
  450. .B hosts.equiv
  451. files from an ndb data base file specified on the
  452. command line (default
  453. .BR /lib/ndb/local ).
  454. For local reasons the files are called
  455. .BR hosts.1127 ,
  456. .BR astro.txt ,
  457. and
  458. .BR hosts.equiv .
  459. .SH EXAMPLES
  460. .EX
  461. % ndb/query sys helix
  462. sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot
  463. ip=135.104.117.31 ether=080069020427
  464. proto=il
  465. % ndb/dnsquery
  466. > plan9.bell-labs.com ip
  467. plan9.bell-labs.com ip 204.178.31.2
  468. > 204.178.31.2 ptr
  469. 2.31.178.204.in-addr.arpa ptr plan9.bell-labs.com
  470. 2.31.178.204.in-addr.arpa ptr ampl.com
  471. >
  472. .EE
  473. .SH FILES
  474. .TF /lib/ndb/local.*xxx
  475. .TP
  476. .B /lib/ndb/local
  477. first database file searched
  478. .TP
  479. .B /lib/ndb/local.*
  480. hash files for
  481. .B /lib/ndb/local
  482. .TP
  483. .B /srv/cs
  484. service file for
  485. .I ndb/cs
  486. .TP
  487. .B /net/cs
  488. where
  489. .B /srv/cs
  490. gets mounted
  491. .TP
  492. .B /srv/dns
  493. service file for
  494. .I ndb/dns
  495. .TP
  496. .B /net/dns
  497. where
  498. .B /srv/dns
  499. gets mounted
  500. .SH SOURCE
  501. .B /sys/src/cmd/ndb
  502. .SH SEE ALSO
  503. .IR ndb (2)
  504. .IR ndb (6)
  505. .SH BUGS
  506. .I Ndb
  507. databases are case-sensitive;
  508. ethernet addresses must be in lower-case hexadecimal.