diff options
Diffstat (limited to 'contrib/bind/man/named.8')
| -rw-r--r-- | contrib/bind/man/named.8 | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/contrib/bind/man/named.8 b/contrib/bind/man/named.8 new file mode 100644 index 0000000000000..fae5d518653a6 --- /dev/null +++ b/contrib/bind/man/named.8 @@ -0,0 +1,435 @@ +.\" ++Copyright++ 1985 +.\" - +.\" Copyright (c) 1985 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" - +.\" Portions Copyright (c) 1993 by Digital Equipment Corporation. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies, and that +.\" the name of Digital Equipment Corporation not be used in advertising or +.\" publicity pertaining to distribution of the document or software without +.\" specific, written prior permission. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL +.\" WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT +.\" CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" - +.\" --Copyright-- +.\" +.\" @(#)named.8 6.6 (Berkeley) 2/14/89 +.\" +.TH @INDOT_U@NAMED @SYS_OPS_EXT_U@ "June 20, 1995" +.UC 4 +.SH NAME +@INDOT@named \- Internet domain name server +.SH SYNOPSIS +.B @INDOT@named +[ +.B \-d +.I debuglevel +] [ +.B \-p +.IR port# [\fB/\fP\fIlocalport#\fP] +] [{\-b} +.I bootfile +] [ +.B \-q +] [ +.B \-r +] +.SH DESCRIPTION +.I Named +is the Internet domain name server. +See RFC's 1033, 1034, and 1035 for more information on the Internet +name-domain system. Without any arguments, +.I named +will read the default boot file +.IR /etc/named.boot , +read any initial data and listen for queries. +.PP +Options are: +.TP +.B \-d +Print debugging information. +A number after the ``d'' determines the level of +messages printed. +.TP +.B \-p +Use nonstandard port numbers. The default is the standard port number +as returned by getservbyname(@LIB_NETWORK_EXT@) for service ``domain''. +The argument can specify two port numbers separated by a slash (``\fB/\fP'') +in which case the first port is that used when contacting remote servers, +and the second one is the service port bound by the local instance of +.IR named . +This is used mostly for debugging purposes. +.TP +.B \-b +Use an alternate boot file. This is optional and allows you to +specify a file with a leading dash. +.TP +.B \-q +Trace all incoming queries if \fInamed\fP has been compiled with +\fIQRYLOG\fP defined. \fINOTE:\fP this option is deprecated in favour +of the boot file directive ``options query-log''. +.TP +.B \-r +Turns recursion off in the server. Answers can come only from local +(primary or secondary) zones. This can be used on root servers. +\fINOTE:\fP this option is deprecated in favour +of the boot file directive ``options no-recursion''. +.PP +Any additional argument is taken as the name of the boot file. +If multiple boot files are specified, only the last is used. +.PP +The boot file contains information about where the name server is to get +its initial data. +Lines in the boot file cannot be continued on subsequent lines. +The following is a small example: +.in +2m +.nf + +; +; boot file for name server +; +directory /usr/local/adm/named + +.ta \w'forwarders\ 'u +\w'6.32.128.IN-ADDR.ARPA\ 'u +\w'128.32.137.8 128.32.137.3\ 'u +; type domain source host/file backup file + +cache . root.cache +primary Berkeley.EDU berkeley.edu.zone +primary 32.128.IN-ADDR.ARPA ucbhosts.rev +secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak +secondary 6.32.128.IN-ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak +primary 0.0.127.IN-ADDR.ARPA localhost.rev +forwarders 10.0.0.78 10.2.0.78 +limit transfers-in 10 +limit datasize 64M +options forward-only query-log fake-iquery +check-names primary fail +check-names secondary warn +check-names response ignore + +.DT +.fi +.in +The ``directory'' line causes the server to change its working directory to +the directory specified. This can be important for the correct processing +of \s-1$INCLUDE\s+1 files in primary zone files. +.LP +The ``cache'' line specifies that data in ``root.cache'' is to be placed in +the backup cache. Its main use is to specify data such as locations of root +domain servers. This cache is not used during normal operation, but is used +as ``hints'' to find the current root servers. The file ``root.cache'' is +in the same format as ``berkeley.edu.zone''. There can be more than one +``cache'' file specified. The ``root.cache'' file should be retrieved +periodically from \s-1FTP.RS.INTERNIC.NET\s+1 since it contains a list of +root servers, and this list changes periodically. +.LP +The first example ``primary'' line states that the file +``berkeley.edu.zone'' contains authoritative data for the ``Berkeley.EDU'' +zone. The file ``berkeley.edu.zone'' contains data in the master file +format described in RFC 883. All domain names are relative to the origin, in +this case, ``Berkeley.EDU'' (see below for a more detailed description). +The second ``primary'' line states that the file ``ucbhosts.rev'' contains +authoritative data for the domain ``32.128.IN-ADDR.ARPA,'' which is used to +translate addresses in network 128.32 to hostnames. Each master file should +begin with an SOA record for the zone (see below). +.LP +The first example ``secondary'' line specifies that all authoritative data +under ``CC.Berkeley.EDU'' is to be transferred from the name server at +128.32.137.8. If the transfer fails it will try 128.32.137.3 and continue +trying the addresses, up to 10, listed on this line. The secondary copy is +also authoritative for the specified domain. The first non-dotted-quad +address on this line will be taken as a filename in which to backup the +transferred zone. The name server will load the zone from this backup file +if it exists when it boots, providing a complete copy even if the master +servers are unreachable. Whenever a new copy of the domain is received by +automatic zone transfer from one of the master servers, this file will be +updated. If no file name is given, a temporary file will be used, and will +be deleted after each successful zone transfer. This is not recommended +since it is a needless waste of bandwidth. The second example ``secondary'' +line states that the address-to-hostname mapping for the subnet 128.32.136 +should be obtained from the same list of master servers as the previous zone. +.LP +The ``forwarders'' line specifies the addresses of sitewide servers that +will accept recursive queries from other servers. If the boot file +specifies one or more forwarders, then the server will send all queries for +data not in the cache to the forwarders first. Each forwarder will be asked +in turn until an answer is returned or the list is exhausted. If no answer +is forthcoming from a forwarder, the server will continue as it would have +without the forwarders line unless it is in ``forward-only'' mode. The +forwarding facility is useful to cause a large sitewide cache to be +generated on a master, and to reduce traffic over links to outside servers. +It can also be used to allow servers to run that do not have direct access +to the Internet, but wish to look up exterior names anyway. +.LP +The ``slave'' line (deprecated) is allowed for backward compatibility. Its +meaning is identical to ``options forward-only''. +.LP +The ``sortlist'' line can be used to indicate networks that are to be +preferred over other networks. Queries for host addresses from hosts on the +same network as the server will receive responses with local network +addresses listed first, then addresses on the sort list, then other +addresses. +.LP +The ``xfrnets'' directive (not shown) can be used to implement primitive +access control. If this directive is given, then your name server will +only answer zone transfer requests from hosts which are on networks listed +in your ``xfrnets'' directives. This directive may also be given as +``tcplist'' for compatibility with older, interim servers. +.LP +The ``include'' directive (not shown) can be used to process the contents +of some other file as though they appeared in place of the ``include'' +directive. This is useful if you have a lot of zones or if you have +logical groupings of zones which are maintained by different people. +The ``include'' directive takes one argument, that being the name of the +file whose contents are to be included. No quotes are necessary around +the file name. +.LP +The ``bogusns'' directive (not shown) tells \s-1BIND\s+1 that no queries +are to be sent to the specified name server addresses (which are specified +as dotted quads, not as domain names). This is useful when you know that +some popular server has bad data in a zone or cache, and you want to avoid +contamination while the problem is being fixed. +.LP +The ``limit'' directive can be used to change \s-1BIND\s+1's internal limits, +some of which (\fBdatasize\fP, for example) are implemented by the system and +others (like \fBtransfers-in\fP) by \s-1BIND\s+1 itself. The number following +the limit name can be scaled by postfixing a ``k,'' ``m,'' or ``g'' for +kilobytes, megabytes, and gigabytes respectively. +\fBdatasize\fP's argument sets the process data size enforced by the kernel. +\fINote:\fP not all systems provide a call to implement this -- on such +systems, the use of the \fBdatasize\fP parameter of ``limit'' will result in +a warning message. +\fBtransfers-in\fP's argument is the number of \fInamed-xfer\fP subprocesses +which \s-1BIND\s+1 will spawn at any one time. +\fBtransfers-per-ns\fP's argument is the maximum number of zone transfers to +be simultaneously initiated to any given remote name server. +.LP +The ``options'' directive introduces a boolean specifier that changes the +behaviour of \s-1BIND\s+1. More than one option can be specified in a single +directive. The currently defined options are as follows: +\fBno-recursion\fP, which will cause \s-1BIND\s+1 to answer with a referral +rather than actual data whenever it receives a query for a name it is not +authoritative for -- don't set this on a server that is listed in any host's +\fIresolv.conf\fP file; +\fBno-fetch-glue\fP, which keeps \s-1BIND\s+1 from fetching missing glue when +constructing the ``additional data'' section of a response; this can be used +in conjunction with \fBno-recursion\fP to prevent \s-1BIND\s+1's cache from +ever growing in size or becoming corrupted; +\fBquery-log\fP, which causes all queries to be logged via +syslog(@SYS_OPS_EXT@) -- this is a lot of data, don't turn it on lightly; +\fBforward-only\fP, which causes the server to query only its forwarders -- +this option is normally used on machine that wishes to run a server but for +physical or administrative reasons cannot be given access to the Internet; +and \fBfake-iquery\fP, which tells \s-1BIND\s+1 to send back a useless and +bogus reply to ``inverse queries'' rather than responding with an error -- +this is helpful if you have a lot of microcomputers or SunOS hosts or both. +.LP +The ``check-names'' directive tells \s-1BIND\s+1 to check names in either +``primary'' or ``secondary'' zone files, or in messages (``response'') +received during recursion (for example, those which would be forwarded back +to a firewalled requestor). For each type of name, +\s-1BIND\s+1 can be told to ``fail'', such that a zone would not be loaded +or a response would not be cached or forwarded, or merely ``warn'' which +would cause a message to be emitted in the system operations logs, or to +``ignore'' the badness of a name and process it in the traditional fashion. +Names are considered good if they match RFC 952's expectations (if they are +host names), or if they consist only of printable \s-1ASCII\s+1 characters +(if they are not host names). +.LP +The ``max-fetch'' directive (not shown) is allowed for backward compatibility; +its meaning is identical to ``limit transfers-in''. +.PP +The master file consists of control information and a list of resource +records for objects in the zone of the forms: +.RS +.nf + +$INCLUDE <filename> <opt_domain> +$ORIGIN <domain> +<domain> <opt_ttl> <opt_class> <type> <resource_record_data> + +.fi +.RE +where +.I domain +is "." for root, "@" for the current origin, or a standard domain +name. If +.I domain +is a standard domain name that does not end with ``.'', the current origin +is appended to the domain. Domain names ending with ``.'' are +unmodified. +The +.I opt_domain +field is used to define an origin for the data in an included file. +It is equivalent to placing a $ORIGIN statement before the first +line of the included file. The field is optional. +Neither the +.I opt_domain +field nor $ORIGIN statements in the included file modify the current origin +for this file. +The +.I opt_ttl +field is an optional integer number for the time-to-live field. +It defaults to zero, meaning the minimum value specified in the SOA +record for the zone. +The +.I opt_class +field is the object address type; currently only one type is supported, +.BR IN , +for objects connected to the DARPA Internet. +The +.I type +field contains one of the following tokens; the data expected in the +.I resource_record_data +field is in parentheses. +.TP "\w'MINFO 'u" +A +a host address (dotted quad) +.IP NS +an authoritative name server (domain) +.IP MX +a mail exchanger (domain), preceded by a preference value (0..32767), +with lower numeric values representing higher logical preferences. +.IP CNAME +the canonical name for an alias (domain) +.IP SOA +marks the start of a zone of authority (domain of originating host, +domain address of maintainer, a serial number and the following +parameters in seconds: refresh, retry, expire and minimum TTL (see RFC 883)). +.IP NULL +a null resource record (no format or data) +.IP RP +a Responsible Person for some domain name (mailbox, TXT-referral) +.IP PTR +a domain name pointer (domain) +.IP HINFO +host information (cpu_type OS_type) +.PP +Resource records normally end at the end of a line, +but may be continued across lines between opening and closing parentheses. +Comments are introduced by semicolons and continue to the end of the line. +.PP +Note that there are other resource record types, not shown here. You should +consult the \s-1BIND\s+1 Operations Guide (``\s-1BOG\s+1'') for the complete +list. Some resource record types may have been standardized in newer RFC's +but not yet implemented in this version of \s-1BIND\s+1. +.PP +Each master zone file should begin with an SOA record for the zone. +An example SOA record is as follows: +.LP +.nf +@ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. ( + 1989020501 ; serial + 10800 ; refresh + 3600 ; retry + 3600000 ; expire + 86400 ) ; minimum +.fi +.LP +The SOA specifies a serial number, which should be changed each time the +master file is changed. Note that the serial number can be given as a +dotted number, but this is a \fIvery\fP unwise thing to do since the +translation to normal integers is via concatenation rather than +multiplication and addition. You can spell out the year, month, day of +month, and 0..99 version number and still fit inside the unsigned 32-bit +size of this field. It's true that we will have to rethink this strategy in +the year 4294 (Greg.) but we're not worried about it. Secondary servers +check the serial number at intervals specified by the refresh time in +seconds; if the serial number changes, a zone transfer will be done to load +the new data. If a master server cannot be contacted when a refresh is due, +the retry time specifies the interval at which refreshes should be attempted. +If a master server cannot be contacted within the interval given by the +expire time, all data from the zone is discarded by secondary servers. The +minimum value is the time-to-live (``\s-1TTL\s+1'') used by records in the +file with no explicit time-to-live value. +.SH NOTES +The boot file directives ``domain'' and ``suffixes'' have been +obsoleted by a more useful resolver-based implementation of +suffixing for partially qualified domain names. The prior mechanisms +could fail under a number of situations, especially when then local +nameserver did not have complete information. +.sp +The following signals have the specified effect when sent to the +server process using the +.IR kill (@CMD_EXT@) +command. +.IP SIGHUP +Causes server to read named.boot and reload the database. If the server +is built with the FORCED_RELOAD compile-time option, then SIGHUP will +also cause the server to check the serial number on all secondary zones. +Normally the serial numbers are only checked at the SOA-specified intervals. +.IP SIGINT +Dumps the current data base and cache to /var/tmp/named_dump.db +.IP SIGIOT +Dumps statistics data into /var/tmp/named.stats if the server is +compiled with -DSTATS. Statistics data is appended to the file. Some +systems use SIGABRT rather than SIGIOT for this. +.IP SIGSYS +Dumps the profiling data in /var/tmp if the server is compiled +with profiling (server forks, chdirs and exits). +.IP SIGTERM +Dumps the primary and secondary database files. +Used to save modified data on shutdown if the +server is compiled with dynamic updating enabled. +.IP SIGUSR1 +Turns on debugging; each SIGUSR1 increments debug level. +(SIGEMT on older systems without SIGUSR1) +.IP SIGUSR2 +Turns off debugging completely. +(SIGFPE on older systems without SIGUSR2) +.IP SIGWINCH +Toggles logging of all incoming queries via syslog(@SYS_OPS_EXT@) +(requires server to have been built with the QRYLOG option). +.SH FILES +.nf +.ta \w'/var/tmp/named_dump.db 'u +/etc/named.boot name server configuration boot file +/etc/named.pid the process id (on older systems) +/var/run/named.pid the process id (on newer systems) +/var/tmp/named_dump.db dump of the name server database +/var/tmp/named.run debug output +/var/tmp/named.stats nameserver statistics data +.fi +.SH "SEE ALSO" +kill(@CMD_EXT@), gethostbyname(@LIB_NETWORK_EXT@), signal(@SYSCALL_EXT@), +resolver(@LIB_NETWORK_EXT@), resolver(@FORMAT_EXT@), hostname(@DESC_EXT@), +RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123, +\fIName Server Operations Guide for \s-1BIND\s+1\fR |