ndb 9.8 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. .PP
  230. The server for a domain is indicated by a database entry containing
  231. both a
  232. .I dom
  233. and a
  234. .I ns
  235. attribute.
  236. For example, the entry for the Internet root is:
  237. .EX
  238. dom=
  239. ns=A.ROOT-SERVERS.NET
  240. ns=B.ROOT-SERVERS.NET
  241. ns=C.ROOT-SERVERS.NET
  242. dom=A.ROOT-SERVERS.NET ip=198.41.0.4
  243. dom=B.ROOT-SERVERS.NET ip=128.9.0.107
  244. dom=C.ROOT-SERVERS.NET ip=192.33.4.12
  245. .EE
  246. The last three lines provide a mapping for the
  247. server names to their ip addresses. This is only
  248. a hint and will be superseded from whatever is learned
  249. from servers owning the domain.
  250. .PP
  251. You can also serve a subtree of the domain name space from the local
  252. database. You indicate subtrees that you'ld like to serve by
  253. adding an
  254. .B soa=
  255. attribute to the root entry.
  256. For example, the Bell Labs CS research domain is:
  257. .EX
  258. dom=cs.bell-labs.com soa=
  259. refresh=3600 ttl=3600
  260. ns=plan9.bell-labs.com
  261. ns=ns1.cs.bell-labs.com
  262. ns=ns2.cs.bell-labs.com
  263. mb=presotto@plan9.bell-labs.com
  264. mx=mail.research.bell-labs.com pref=20
  265. mx=plan9.bell-labs.com pref=10
  266. dnsslave=nslocum.cs.bell-labs.com
  267. dnsslave=vex.cs.bell-labs.com
  268. .EE
  269. Here, the
  270. .B mb
  271. entry is the mail address of the person responsible for the
  272. domain (default
  273. .BR postmaster ).
  274. The
  275. .B mx
  276. entries list mail exchangers for the domain name and
  277. .B refresh
  278. and
  279. .B ttl
  280. define the area refresh interval and the minimum TTL for
  281. records in this domain.
  282. The
  283. .B dnsslave
  284. entries specify slave DNS servers that should be notified
  285. when the domain changes. The notification also requires
  286. the
  287. .B -n
  288. flag.
  289. .PP
  290. You can also serve reverse lookups (returning the name that
  291. goes with an IP address) by adding an
  292. .B soa=
  293. attribute to the entry defining the root of the reverse space.
  294. For example, to provide reverse lookup for all addresses in
  295. starting with 135.104 you must have a record like:
  296. .EX
  297. dom=104.135.in-addr.arpa soa=
  298. refresh=3600 ttl=3600
  299. ns=plan9.bell-labs.com
  300. ns=ns1.cs.bell-labs.com
  301. ns=ns2.cs.bell-labs.com
  302. .EE
  303. Notice the form of the reverse address, i.e., it's the bytes of the
  304. address range you are serving reversed and with
  305. .B .in-addr.arpa
  306. appended. This is a standard form for a domain name in an IPv4 PTR record.
  307. .PP
  308. If such an entry exists in the database, reverse addresses will
  309. automatically be generated from any IP addresses in the database
  310. that are under this root. For example
  311. .EX
  312. dom=ns1.cs.bell-labs.com ip=135.104.1.11
  313. .EE
  314. will automatically create both forward and reverse entries for
  315. .B ns1.cs.bell-labs.com .
  316. Unlike other DNS servers, there's no way to generate
  317. inconsistent forward and reverse entries.
  318. .PP
  319. Delegation of a further subtree to another set of name servers
  320. is indicated by an
  321. .B soa=delegated
  322. attribute.
  323. .EX
  324. dom=bignose.cs.research.bell-labs.com
  325. soa=delegated
  326. ns=anna.cs.research.bell-labs.com
  327. ns=dj.cs.research.bell-labs.com
  328. .EE
  329. Nameservers within the delegated domain (as in this example)
  330. must have their IP addresses listed elsewhere in
  331. .I ndb
  332. files.
  333. .PP
  334. Wild-carded domain names can also be used.
  335. For example, to specify a mail forwarder for all Bell Labs research systems:
  336. .EX
  337. dom=*.research.bell-labs.com
  338. mx=research.bell-labs.com
  339. .EE
  340. `Cname' aliases may be established by adding a
  341. .B cname
  342. attribute giving the real domain name;
  343. the name attached to the
  344. .B dom
  345. attribute is the alias.
  346. `Cname' aliases are severely restricted;
  347. the aliases may have no other attributes than
  348. .B dom
  349. and are daily further restricted in their use by new RFCs.
  350. .EX
  351. cname=anna.cs.research.bell-labs.com dom=www.cs.research.bell-labs.com
  352. .EE
  353. .I Ndb/dnsquery
  354. can be used to query
  355. .I ndb/dns
  356. to see how it resolves requests.
  357. .I Ndb/dnsquery
  358. prompts for commands of the form
  359. .IP
  360. .I "domain-name request-type"
  361. .LP
  362. where
  363. .I request-type
  364. can be
  365. .BR ip ,
  366. .BR mx ,
  367. .BR ns ,
  368. .BR cname ,
  369. .BR ptr ....
  370. In the case of the inverse query type,
  371. .BR ptr ,
  372. .I dnsquery
  373. will reverse the ip address and tack on the
  374. .B .in-addr.arpa
  375. for you.
  376. .PP
  377. .I Ndb/dnsdebug
  378. is like
  379. .I ndb/dnsquery
  380. but bypasses the local server.
  381. It communicates via UDP with the domain name servers
  382. in the same way that the local resolver would and displays
  383. all packets received.
  384. The query can be specified on the command line or
  385. can be prompted for.
  386. The queries look like those of
  387. .I ndb/dnsquery
  388. with one addition.
  389. .I Ndb/dnsdebug
  390. can be directed to query a particular name server by
  391. the command
  392. .BI @ name-server\f1.
  393. From that point on, all queries go to that name server
  394. rather than being resolved by
  395. .IR dnsdebug .
  396. The
  397. .B @
  398. command returns query resolution to
  399. .IR dnsdebug .
  400. Finally, any command preceded by a
  401. .BI @ name-server
  402. sets the name server only for that command.
  403. .PP
  404. Normally
  405. .I dnsdebug
  406. uses the
  407. .B /net
  408. interface and the database file
  409. .BR /lib/ndb/local.
  410. The
  411. .B -x
  412. option directs
  413. .I dnsdebug
  414. to use the
  415. .B /net.alt
  416. interface and
  417. .B /lib/ndb/external
  418. file.
  419. The
  420. .B -r
  421. option is the same as for
  422. .IR ndb/dns .
  423. .PP
  424. .I Ndb/mkdb
  425. is used in concert with
  426. .IR awk (1)
  427. scripts to convert
  428. uucp systems files and IP host files
  429. into database files.
  430. It is very specific to the situation at Murray Hill.
  431. .PP
  432. When the database files change underfoot,
  433. .I ndb/cs
  434. and
  435. .I ndb/dns
  436. track them properly. Nonetheless, to keep the database searches efficient
  437. it is necessary to run
  438. .I ndb/mkhash
  439. whenever the files are modified.
  440. It may be profitable to control this by a frequent
  441. .IR cron (8)
  442. job.
  443. .PP
  444. .I Ndb/mkhosts
  445. generates a BSD style
  446. .BR hosts ,
  447. .BR hosts.txt ,
  448. and
  449. .B hosts.equiv
  450. files from an ndb data base file specified on the
  451. command line (default
  452. .BR /lib/ndb/local ).
  453. For local reasons the files are called
  454. .BR hosts.1127 ,
  455. .BR astro.txt ,
  456. and
  457. .BR hosts.equiv .
  458. .SH EXAMPLES
  459. .EX
  460. % ndb/query sys helix
  461. sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot
  462. ip=135.104.117.31 ether=080069020427
  463. proto=il
  464. % ndb/dnsquery
  465. > plan9.bell-labs.com ip
  466. plan9.bell-labs.com ip 204.178.31.2
  467. > 204.178.31.2 ptr
  468. 2.31.178.204.in-addr.arpa ptr plan9.bell-labs.com
  469. 2.31.178.204.in-addr.arpa ptr ampl.com
  470. >
  471. .EE
  472. .SH FILES
  473. .TF /lib/ndb/local.*xxx
  474. .TP
  475. .B /lib/ndb/local
  476. first database file searched
  477. .TP
  478. .B /lib/ndb/local.*
  479. hash files for
  480. .B /lib/ndb/local
  481. .TP
  482. .B /srv/cs
  483. service file for
  484. .I ndb/cs
  485. .TP
  486. .B /net/cs
  487. where
  488. .B /srv/cs
  489. gets mounted
  490. .TP
  491. .B /srv/dns
  492. service file for
  493. .I ndb/dns
  494. .TP
  495. .B /net/dns
  496. where
  497. .B /srv/dns
  498. gets mounted
  499. .SH SOURCE
  500. .B /sys/src/cmd/ndb
  501. .SH SEE ALSO
  502. .IR ndb (2)
  503. .IR ndb (6)
  504. .SH BUGS
  505. .I Ndb
  506. databases are case-sensitive;
  507. ethernet addresses must be in lower-case hexadecimal.