Commit | Line | Data |
---|---|---|
1c15e888 C |
1 | .\" Copyright (c) 1985 The Regents of the University of California. |
2 | .\" All rights reserved. | |
ca67e7b4 | 3 | .\" |
1c15e888 C |
4 | .\" Redistribution and use in source and binary forms are permitted provided |
5 | .\" that: (1) source distributions retain this entire copyright notice and | |
6 | .\" comment, and (2) distributions including binaries display the following | |
7 | .\" acknowledgement: ``This product includes software developed by the | |
8 | .\" University of California, Berkeley and its contributors'' in the | |
9 | .\" documentation or other materials provided with the distribution and in | |
10 | .\" all advertising materials mentioning features or use of this software. | |
11 | .\" Neither the name of the University nor the names of its contributors may | |
12 | .\" be used to endorse or promote products derived from this software without | |
13 | .\" specific prior written permission. | |
14 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED | |
15 | .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF | |
16 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
ca67e7b4 | 17 | .\" |
1c15e888 C |
18 | .\" @(#)named.8 6.8 (Berkeley) 6/24/90 |
19 | .\" | |
20 | .TH NAMED 8 "June 24, 1990" | |
ca67e7b4 C |
21 | .UC 4 |
22 | .SH NAME | |
23 | named \- Internet domain name server | |
24 | .SH SYNOPSIS | |
25 | .B named | |
26 | [ | |
27 | .B \-d | |
28 | .I debuglevel | |
29 | ] [ | |
30 | .B \-p | |
31 | .I port# | |
32 | ] [{\-b} | |
33 | .I bootfile | |
34 | ] | |
35 | .SH DESCRIPTION | |
36 | .I Named | |
37 | is the Internet domain name server. | |
38 | See RFC883 for more information on the Internet name-domain system. | |
39 | Without any arguments, | |
40 | .I named | |
41 | will read the default boot file | |
42 | .IR /etc/named.boot , | |
43 | read any initial data and listen for queries. | |
44 | .PP | |
45 | Options are: | |
46 | .TP | |
47 | .B \-d | |
48 | Print debugging information. | |
49 | A number after the ``d'' determines the level of | |
50 | messages printed. | |
51 | .TP | |
52 | .B \-p | |
53 | Use a different port number. The default is the standard port number | |
54 | as listed in /etc/services. | |
55 | .TP | |
56 | .B \-b | |
57 | Use an alternate boot file. This is optional and allows you to | |
58 | specify a file with a leading dash. | |
59 | .PP | |
60 | Any additional argument is taken as the name of the boot file. | |
61 | The boot file contains information about where the name server is to get | |
62 | its initial data. If multiple boot files are specified, only the last | |
63 | is used. | |
64 | Lines in the boot file cannot be continued on subsequent lines. | |
65 | The following is a small example: | |
66 | .in +2m | |
67 | .nf | |
68 | ||
69 | ; | |
70 | ; boot file for name server | |
71 | ; | |
72 | directory /usr/local/domain | |
73 | ||
74 | .ta \w'forwarders\ 'u +\w'6.32.128.IN-ADDR.ARPA\ 'u +\w'128.32.137.8 128.32.137.3\ 'u | |
75 | ; type domain source host/file backup file | |
76 | ||
77 | cache . root.cache | |
78 | primary Berkeley.EDU berkeley.edu.zone | |
79 | primary 32.128.IN-ADDR.ARPA ucbhosts.rev | |
80 | secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak | |
81 | secondary 6.32.128.IN-ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak | |
82 | primary 0.0.127.IN-ADDR.ARPA localhost.rev | |
83 | forwarders 10.0.0.78 10.2.0.78 | |
84 | ; slave | |
85 | ||
86 | .DT | |
87 | .fi | |
88 | .in | |
89 | The ``directory'' line causes the server to change its | |
90 | working directory to the directory specified. This can | |
91 | be important for the correct processing of $INCLUDE files | |
92 | in primary zone files. | |
93 | .LP | |
94 | The ``cache'' line specifies that data in ``root.cache'' is to be | |
95 | placed in the backup cache. | |
96 | Its main use is to specify data such as locations of root domain servers. | |
97 | This cache is not used during normal operation, | |
98 | but is used as ``hints'' to find the current root servers. | |
99 | The file ``root.cache'' is in the same format as ``berkeley.edu.zone''. | |
100 | There can be more than one ``cache'' file specified. | |
101 | .\"The first such file will be updated under certain conditions to snapshot the | |
102 | .\"cache (see SIGQUIT below). | |
103 | .\"The cache line can also have an optional interval argument after | |
104 | .\"the filename. | |
105 | .\"If an interval is listed, | |
106 | .\"it requests the nameserver to dump the cache contents | |
107 | .\"at that interval (in seconds). | |
108 | .\"The example above requests the nameserver to dump the cache content | |
109 | .\"every 3600 seconds (once an hour). | |
110 | .\"The use of automatic cache file updates is not currently recommended | |
111 | .\"because of the way the cache is currently managed by the server; | |
112 | .\"although the entire cache will be dumped for later reloading, | |
113 | .\"most of the cache contents will be ignored when reloaded. | |
114 | .\"The exact dump interval will vary | |
115 | .\"based on the minimum maintence interval time which is typically about | |
116 | .\"5 minutes. | |
117 | The cache files are processed in such a way as to preserve the | |
118 | time-to-live's | |
119 | of data dumped out. Data for the root nameservers is kept artificially | |
120 | valid if necessary. | |
121 | .LP | |
122 | The first ``primary'' line states that the file ``berkeley.edu.zone'' contains | |
123 | authoritative data for the ``Berkeley.EDU'' zone. | |
124 | The file ``berkeley.edu.zone'' | |
125 | contains data in the master file format described in RFC883. | |
126 | All domain names are relative to the origin, in this | |
127 | case, ``Berkeley.EDU'' (see below for a more detailed description). | |
128 | The second ``primary'' line states that the file ``ucbhosts.rev'' contains | |
129 | authoritative data for the domain ``32.128.IN-ADDR.ARPA,'' which is used | |
130 | to translate addresses in network 128.32 to hostnames. | |
131 | Each master file should begin with an SOA record for the zone | |
132 | (see below). | |
133 | .LP | |
134 | The first ``secondary'' line specifies that all authoritative data | |
135 | under ``CC.Berkeley.EDU'' is to be transferred from the name server | |
136 | at 128.32.137.8. If the transfer fails it will try 128.32.137.3 and | |
137 | continue trying the addresses, up to 10, listed on this line. | |
138 | The secondary copy is also authoritative for the specified domain. | |
139 | The first non-dotted-quad address on this line will be taken | |
140 | as a filename in which to backup the transfered zone. | |
141 | The name server will load the zone from this backup file if it exists | |
142 | when it boots, providing a complete copy even if the master servers | |
143 | are unreachable. | |
144 | Whenever a new copy of the domain is received by automatic zone transfer | |
145 | from one of the master servers, this file will be updated. | |
146 | The second ``secondary'' line states that the address-to-hostname | |
147 | mapping for the subnet 128.32.136 should be obtained from the same list | |
148 | of master servers as the previous zone. | |
149 | .LP | |
150 | The ``forwarders'' line specifies the addresses of sitewide servers | |
151 | that will accept recursive queries from other servers. | |
152 | If the boot file specifies one or more forwarders, then the | |
153 | server will send all queries for data not in the cache to the forwarders first. | |
154 | Each forwarder will be asked in turn until an answer is returned | |
155 | or the list is exhausted. If no answer is forthcoming from a | |
156 | forwarder, the server will continue as it would have without | |
157 | the forwarders line unless it is in ``slave'' mode. | |
158 | The forwarding facility is useful | |
159 | to cause a large sitewide cache to be generated on a master, | |
160 | and to reduce traffic over links to outside servers. | |
161 | It can also be used to allow servers to run that do not have | |
162 | access directly to the Internet, but wish to act as though | |
163 | they do. | |
164 | .LP | |
165 | The ``slave'' line (shown commented out) is used to put the server | |
166 | in slave mode. In this mode, the server will only make queries to | |
167 | forwarders. This option is normally used on machine that wish to | |
168 | run a server but for physical or administrative reasons cannot | |
169 | be given access to the Internet, but have access to a host that | |
170 | does have access. | |
171 | .LP | |
172 | The ``sortlist'' line can be used to indicate networks that are to be | |
173 | preferred over other, unlisted networks. | |
174 | Queries for host addresses from hosts on the same network as the server | |
175 | will receive responses with local network addresses listed first, | |
176 | then addresses on the sort list, then other addresses. | |
177 | This line is only acted on at initial startup. | |
178 | When reloading the nameserver with | |
179 | a SIGHUP, this line will be ignored. | |
180 | .PP | |
181 | The master file consists of control information | |
182 | and a list of resource records for objects in the zone | |
183 | of the forms: | |
184 | .RS | |
185 | .nf | |
186 | ||
187 | $INCLUDE <filename> <opt_domain> | |
188 | $ORIGIN <domain> | |
189 | <domain> <opt_ttl> <opt_class> <type> <resource_record_data> | |
190 | ||
191 | .fi | |
192 | .RE | |
193 | where | |
194 | .I domain | |
195 | is "." for root, "@" for the current origin, or a standard domain | |
196 | name. If | |
197 | .I domain | |
198 | is a standard domain name that does not end with ``.'', the current origin | |
199 | is appended to the domain. Domain names ending with ``.'' are | |
200 | unmodified. | |
201 | The | |
202 | .I opt_domain | |
203 | field is used to define an origin for the data in an included file. | |
204 | It is equivalent to placing a $ORIGIN statement before the first | |
205 | line of the included file. The field is optional. | |
206 | Neither the | |
207 | .I opt_domain | |
208 | field nor $ORIGIN statements in the included file modify the current origin | |
209 | for this file. | |
210 | The | |
211 | .I opt_ttl | |
212 | field is an optional integer number for the time-to-live field. | |
213 | It defaults to zero, meaning the minimum value specified in the SOA | |
214 | record for the zone. | |
215 | The | |
216 | .I opt_class | |
217 | field is the object address type; currently only one type is supported, | |
218 | .BR IN , | |
219 | for objects connected to the DARPA Internet. | |
220 | The | |
221 | .I type | |
222 | field contains one of the following tokens; the data expected in the | |
223 | .I resource_record_data | |
224 | field is in parentheses. | |
225 | .TP "\w'MINFO 'u" | |
226 | A | |
227 | a host address (dotted quad) | |
228 | .IP NS | |
229 | an authoritative name server (domain) | |
230 | .IP MX | |
231 | a mail exchanger (domain) | |
232 | .IP CNAME | |
233 | the canonical name for an alias (domain) | |
234 | .IP SOA | |
235 | marks the start of a zone of authority (domain of originating host, | |
236 | domain address of maintainer, a serial number and the following | |
237 | parameters in seconds: refresh, retry, expire and minimum TTL (see RFC883)) | |
238 | .IP MB | |
239 | a mailbox domain name (domain) | |
240 | .IP MG | |
241 | a mail group member (domain) | |
242 | .IP MR | |
243 | a mail rename domain name (domain) | |
244 | .IP NULL | |
245 | a null resource record (no format or data) | |
246 | .IP WKS | |
247 | a well know service description (not implemented yet) | |
248 | .IP PTR | |
249 | a domain name pointer (domain) | |
250 | .IP HINFO | |
251 | host information (cpu_type OS_type) | |
252 | .IP MINFO | |
253 | mailbox or mail list information (request_domain error_domain) | |
254 | .PP | |
255 | Resource records normally end at the end of a line, | |
256 | but may be continued across lines between opening and closing parentheses. | |
257 | Comments are introduced by semicolons and continue to the end of the line. | |
258 | .PP | |
259 | Each master zone file should begin with an SOA record for the zone. | |
260 | An example SOA record is as follows: | |
261 | .LP | |
262 | .nf | |
263 | @ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. ( | |
264 | 2.89 ; serial | |
265 | 10800 ; refresh | |
266 | 3600 ; retry | |
267 | 3600000 ; expire | |
268 | 86400 ) ; minimum | |
269 | .fi | |
270 | .LP | |
271 | The SOA lists a serial number, which should be changed each time the master | |
272 | file is changed. | |
273 | Secondary servers check the serial number at intervals specified by the refresh | |
274 | time in seconds; if the serial number changes, a zone transfer will be done | |
275 | to load the new data. | |
276 | If a master server cannot be contacted when a refresh is due, the retry time | |
277 | specifies the interval at which refreshes should be attempted until successful. | |
278 | If a master server cannot be contacted within the interval given by the | |
279 | expire time, all data from the zone is discarded by secondary servers. | |
280 | The minimum value is the time-to-live used by records in the file | |
281 | with no explicit time-to-live value. | |
282 | .SH NOTES | |
283 | The boot file directives ``domain'' and ``suffixes'' have been | |
284 | obsoleted by a more useful resolver based implementation of | |
285 | suffixing for partially qualified domain names. The prior mechanisms | |
286 | could fail under a number of situations, especially when then local | |
287 | nameserver did not have complete information. | |
288 | .sp | |
289 | The following signals have the specified effect when sent to the | |
290 | server process using the | |
291 | .IR kill (1) | |
292 | command. | |
293 | .IP SIGHUP | |
294 | Causes server to read named.boot and reload database. | |
295 | .IP SIGINT | |
1c15e888 | 296 | Dumps current data base and cache to /var/tmp/named_dump.db |
ca67e7b4 C |
297 | .\".IP SIGQUIT |
298 | .\"Causes the server to checkpoint the cache into the first ``cache'' file. | |
299 | .IP SIGIOT | |
1c15e888 | 300 | Dumps statistics data into /var/tmp/named.stats if the server is |
ca67e7b4 C |
301 | compiled -DSTATS. Statistics data is appended to the file. |
302 | .IP SIGSYS | |
1c15e888 | 303 | Dumps the profiling data in /var/tmp if the server is compiled |
ca67e7b4 C |
304 | with profiling (server forks, chdirs and exits). |
305 | .IP SIGTERM | |
306 | Dumps the primary and secondary database files. | |
307 | Used to save modified data on shutdown if the | |
308 | server is compiled with dynamic updating enabled. | |
309 | .IP SIGUSR1 | |
310 | Turns on debugging; each SIGUSR1 increments debug level. | |
311 | (SIGEMT on older systems without SIGUSR1) | |
312 | .IP SIGUSR2 | |
313 | Turns off debugging completely. | |
314 | (SIGFPE on older systems without SIGUSR2) | |
315 | .SH FILES | |
316 | .nf | |
1c15e888 C |
317 | .ta \w'/var/tmp/named_dump.db 'u |
318 | /etc/namedb/named.boot name server configuration boot file | |
319 | /var/run/named.pid the process id | |
320 | /var/tmp/named.run debug output | |
321 | /var/tmp/named_dump.db dump of the name server database | |
322 | /var/tmp/named.stats nameserver statistics data | |
ca67e7b4 C |
323 | .fi |
324 | .SH "SEE ALSO" | |
325 | kill(1), gethostbyname(3N), signal(3c), resolver(3), resolver(5), hostname(7), | |
326 | RFC882, RFC883, RFC973, RFC974, | |
327 | \fIName Server Operations Guide for BIND\fR |