diff --git a/bin/check/named-checkconf.docbook b/bin/check/named-checkconf.docbook index e1caf5238f213b324dc33b441ca47a0775432599..bbb4556ae7b3e90a250c789b5dc59131dde20e70 100644 --- a/bin/check/named-checkconf.docbook +++ b/bin/check/named-checkconf.docbook @@ -1,4 +1,6 @@ - +]> - - - + June 14, 2000 @@ -29,6 +29,20 @@ BIND9 + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + Internet Software Consortium + + + named-checkconf named configuration file syntax checking tool @@ -47,9 +61,9 @@ DESCRIPTION - - named-checkconf checks the syntax, but not - the semantics, of a named configuration file. + named-checkconf + checks the syntax, but not the semantics, of a named + configuration file. @@ -59,52 +73,53 @@ -t directory - - - chroot to directory so that include - directives in the configuration file are processed as if - run by a similarly chrooted named. - - + + + chroot to directory so that + include + directives in the configuration file are processed as if + run by a similarly chrooted named. + + -v - - - Print the version of the named-checkconf - program and exit. - - + + + Print the version of the named-checkconf + program and exit. + + -z - - - Perform a check load the master zonefiles found in - named.conf. - - + + + Perform a check load the master zonefiles found in + named.conf. + + -j - - - When loading a zonefile read the journal if it exists. - - + + + When loading a zonefile read the journal if it exists. + + filename - - - The name of the configuration file to be checked. If not - specified, it defaults to /etc/named.conf. - - + + + The name of the configuration file to be checked. If not + specified, it defaults to /etc/named.conf. + + @@ -113,17 +128,16 @@ RETURN VALUES - - named-checkconf returns an exit status of 1 if - errors were detected and 0 otherwise. + named-checkconf + returns an exit status of 1 if + errors were detected and 0 otherwise. + SEE ALSO - - - named - 8 + + named8 , BIND 9 Administrator Reference Manual. @@ -131,16 +145,12 @@ AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - diff --git a/bin/check/named-checkzone.docbook b/bin/check/named-checkzone.docbook index 9ed5ce5f214f259c99cb2004f8ada3b98fc12423..46b3a62258b5aa50b15d3a896c15142727d4a691 100644 --- a/bin/check/named-checkzone.docbook +++ b/bin/check/named-checkzone.docbook @@ -1,4 +1,6 @@ - +]> - - - + June 13, 2000 @@ -29,6 +29,20 @@ BIND9 + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + Internet Software Consortium + + + named-checkzone zone file validity checking tool @@ -56,12 +70,11 @@ DESCRIPTION - - named-checkzone checks the syntax and integrity of - a zone file. It performs the same checks as named - does when loading a zone. This makes - named-checkzone useful for checking zone - files before configuring them into a name server. + named-checkzone + checks the syntax and integrity of a zone file. It performs the + same checks as named does when loading a + zone. This makes named-checkzone useful for + checking zone files before configuring them into a name server. @@ -71,78 +84,80 @@ -d - - - Enable debugging. - - + + + Enable debugging. + + -q - - - Quiet mode - exit code only. - - + + + Quiet mode - exit code only. + + -v - - - Print the version of the named-checkzone - program and exit. - - + + + Print the version of the named-checkzone + program and exit. + + -j - When loading the zone file read the journal if it exists. - + When loading the zone file read the journal if it exists. + + -c class - - - Specify the class of the zone. If not specified "IN" is assumed. - - + + + Specify the class of the zone. If not specified "IN" is assumed. + + -k mode - - - Perform "check-name" checks with the specified failure mode. - Possible modes are "fail", - "warn" (default) and - "ignore". - - + + + Perform "check-name" checks with + the specified failure mode. + Possible modes are "fail", + "warn" (default) and + "ignore". + + -n mode - - - Specify whether NS records should be checked to see if they - are addresses. Possible modes are "fail", - "warn" (default) and - "ignore". - - + + + Specify whether NS records should be checked to see if they + are addresses. Possible modes are "fail", + "warn" (default) and + "ignore". + + -o filename - Write zone output to filename. + Write zone output to filename. @@ -151,9 +166,10 @@ -t directory - chroot to directory so that include - directives in the configuration file are processed as if - run by a similarly chrooted named. + chroot to directory so that + include + directives in the configuration file are processed as if + run by a similarly chrooted named. @@ -162,52 +178,54 @@ -w directory - chdir to directory so that relative - filenames in master file $INCLUDE directives work. This - is similar to the directory clause in - named.conf. + chdir to directory so that + relative + filenames in master file $INCLUDE directives work. This + is similar to the directory clause in + named.conf. -D - - - Dump zone file in canonical format. - - + + + Dump zone file in canonical format. + + -W mode - - - Specify whether to check for non-terminal wildcards. - Non-terminal wildcards are almost always the result of a - failure to understand the wildcard matching algorithm (RFC 1034). - Possible modes are "warn" (default) and - "ignore". - - + + + Specify whether to check for non-terminal wildcards. + Non-terminal wildcards are almost always the result of a + failure to understand the wildcard matching algorithm (RFC 1034). + Possible modes are "warn" (default) + and + "ignore". + + zonename - - - The domain name of the zone being checked. - - + + + The domain name of the zone being checked. + + filename - - - The name of the zone file. - - + + + The name of the zone file. + + @@ -216,17 +234,16 @@ RETURN VALUES - - named-checkzone returns an exit status of 1 if - errors were detected and 0 otherwise. + named-checkzone + returns an exit status of 1 if + errors were detected and 0 otherwise. + SEE ALSO - - - named - 8 + + named8 , RFC 1035, BIND 9 Administrator Reference Manual. @@ -235,16 +252,12 @@ AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - diff --git a/bin/dig/dig.docbook b/bin/dig/dig.docbook index 50b6e5e779bd4f0e6b90e6e27e2ebb0614c288da..7247cf6c42dbfeba1ff58fa5d31e0c91a6b11a9c 100644 --- a/bin/dig/dig.docbook +++ b/bin/dig/dig.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - - - -dig -1 -BIND9 - - - -dig -DNS lookup utility - - - - -dig -@server - - - - - - - - - - -name -type -class -queryopt - - - -dig - - - - -dig -global-queryopt -query - - - - -DESCRIPTION - -dig (domain information groper) is a flexible tool -for interrogating DNS name servers. It performs DNS lookups and -displays the answers that are returned from the name server(s) that -were queried. Most DNS administrators use dig to -troubleshoot DNS problems because of its flexibility, ease of use and -clarity of output. Other lookup tools tend to have less functionality -than dig. - - - -Although dig is normally used with command-line -arguments, it also has a batch mode of operation for reading lookup -requests from a file. A brief summary of its command-line arguments -and options is printed when the option is given. -Unlike earlier versions, the BIND9 implementation of -dig allows multiple lookups to be issued from the -command line. - - - -Unless it is told to query a specific name server, -dig will try each of the servers listed in -/etc/resolv.conf. - - - -When no command line arguments or options are given, will perform an -NS query for "." (the root). - - - -It is possible to set per-user defaults for dig via -${HOME}/.digrc. This file is read and any options in it -are applied before the command line arguments. - - - - - -SIMPLE USAGE - - -A typical invocation of dig looks like: - dig @server name type where: - - - -server - -is the name or IP address of the name server to query. This can be an IPv4 -address in dotted-decimal notation or an IPv6 -address in colon-delimited notation. When the supplied -server argument is a hostname, -dig resolves that name before querying that name -server. If no server argument is provided, -dig consults /etc/resolv.conf -and queries the name servers listed there. The reply from the name -server that responds is displayed. - - -name - -is the name of the resource record that is to be looked up. - - -type - -indicates what type of query is required — -ANY, A, MX, SIG, etc. -type can be any valid query type. If no -type argument is supplied, -dig will perform a lookup for an A record. - - - - - - - - -OPTIONS - - -The option sets the source IP address of the query -to address. This must be a valid address on -one of the host's network interfaces or "0.0.0.0" or "::". An optional port -may be specified by appending "#<port>" - - - -The default query class (IN for internet) is overridden by the - option. class is any valid -class, such as HS for Hesiod records or CH for CHAOSNET records. - - - -The option makes dig operate -in batch mode by reading a list of lookup requests to process from the -file filename. The file contains a number of -queries, one per line. Each entry in the file should be organised in -the same way they would be presented as queries to -dig using the command-line interface. - - - -If a non-standard port number is to be queried, the - option is used. port# is -the port number that dig will send its queries -instead of the standard DNS port number 53. This option would be used -to test a name server that has been configured to listen for queries -on a non-standard port number. - - - -The option forces dig to only -use IPv4 query transport. The option forces -dig to only use IPv6 query transport. - - - -The option sets the query type to -type. It can be any valid query type which is -supported in BIND9. The default query type "A", unless the - option is supplied to indicate a reverse lookup. -A zone transfer can be requested by specifying a type of AXFR. When -an incremental zone transfer (IXFR) is required, -type is set to ixfr=N. -The incremental zone transfer will contain the changes made to the zone -since the serial number in the zone's SOA record was -N. - - - -Reverse lookups - mapping addresses to names - are simplified by the - option. addr is an IPv4 -address in dotted-decimal notation, or a colon-delimited IPv6 address. -When this option is used, there is no need to provide the -name, class and -type arguments. dig -automatically performs a lookup for a name like -11.12.13.10.in-addr.arpa and sets the query type and -class to PTR and IN respectively. By default, IPv6 addresses are -looked up using nibble format under the IP6.ARPA domain. -To use the older RFC1886 method using the IP6.INT domain -specify the option. Bit string labels (RFC2874) -are now experimental and are not attempted. - - - -To sign the DNS queries sent by dig and their -responses using transaction signatures (TSIG), specify a TSIG key file -using the option. You can also specify the TSIG -key itself on the command line using the option; -name is the name of the TSIG key and -key is the actual key. The key is a base-64 -encoded string, typically generated by -dnssec-keygen8 -. - -Caution should be taken when using the option on -multi-user systems as the key can be visible in the output from - ps1 - or in the shell's history file. When -using TSIG authentication with dig, the name -server that is queried needs to know the key and algorithm that is -being used. In BIND, this is done by providing appropriate -key and server statements in -named.conf. - - - - - -QUERY OPTIONS - - -dig provides a number of query options which affect -the way in which lookups are made and the results displayed. Some of -these set or reset flag bits in the query header, some determine which -sections of the answer get printed, and others determine the timeout -and retry strategies. - - - -Each query option is identified by a keyword preceded by a plus sign -(+). Some keywords set or reset an option. These may be preceded -by the string no to negate the meaning of that keyword. Other -keywords assign values to options like the timeout interval. They -have the form . -The query options are: - - - - - -Use [do not use] TCP when querying name servers. The default -behaviour is to use UDP unless an AXFR or IXFR query is requested, in -which case a TCP connection is used. - - - - -Use [do not use] TCP when querying name servers. This alternate -syntax to +[no]tcp is provided for backwards -compatibility. The "vc" stands for "virtual circuit". - - - - -Ignore truncation in UDP responses instead of retrying with TCP. By -default, TCP retries are performed. - - - - -Set the search list to contain the single domain -somename, as if specified in a -domain directive in -/etc/resolv.conf, and enable search list -processing as if the +search option were given. - - - - -Use [do not use] the search list defined by the searchlist or domain -directive in resolv.conf (if any). -The search list is not used by default. - - - - -Deprecated, treated as a synonym for +[no]search - - - - -Sets the "aa" flag in the query. - - - - -A synonym for +[no]aaonly. - - - - -Set [do not set] the AD (authentic data) bit in the query. The AD bit -currently has a standard meaning only in responses, not in queries, -but the ability to set the bit in the query is provided for -completeness. - - - - -Set [do not set] the CD (checking disabled) bit in the query. This -requests the server to not perform DNSSEC validation of responses. - - - - -Display [do not display] the CLASS when printing the record. - - - - -Display [do not display] the TTL when printing the record. - - - - -Toggle the setting of the RD (recursion desired) bit in the query. -This bit is set by default, which means dig -normally sends recursive queries. Recursion is automatically disabled -when the +nssearch or -+trace query options are used. - - - - -When this option is set, dig attempts to find the -authoritative name servers for the zone containing the name being -looked up and display the SOA record that each name server has for the -zone. - - - - -Toggle tracing of the delegation path from the root name servers for -the name being looked up. Tracing is disabled by default. When -tracing is enabled, dig makes iterative queries to -resolve the name being looked up. It will follow referrals from the -root servers, showing the answer from each server that was used to -resolve the lookup. - - - - -toggles the printing of the initial comment in the output identifying -the version of dig and the query options that have -been applied. This comment is printed by default. - - - - -Provide a terse answer. The default is to print the answer in a -verbose form. - - - - -Show [or do not show] the IP address and port number that supplied the -answer when the +short option is enabled. If -short form answers are requested, the default is not to show the -source address and port number of the server that provided the answer. - - - - -Toggle the display of comment lines in the output. The default is to -print comments. - - - - -This query option toggles the printing of statistics: when the query -was made, the size of the reply and so on. The default behaviour is -to print the query statistics. - - - - -Print [do not print] the query as it is sent. -By default, the query is not printed. - - - - -Print [do not print] the question section of a query when an answer is -returned. The default is to print the question section as a comment. - - - - -Display [do not display] the answer section of a reply. The default -is to display it. - - - - -Display [do not display] the authority section of a reply. The -default is to display it. - - - - -Display [do not display] the additional section of a reply. -The default is to display it. - - - - -Set or clear all display flags. - - - - - -Sets the timeout for a query to -T seconds. The default time out is 5 seconds. -An attempt to set T to less than 1 will result -in a query timeout of 1 second being applied. - - - - -Sets the number of times to try UDP queries to server to -T instead of the default, 3. If -T is less than or equal to zero, the number of -tries is silently rounded up to 1. - - - - -Sets the number of times to retry UDP queries to server to -T instead of the default, 2. Unlike -+tries, this does not include the initial -query. - - - - -Set the number of dots that have to appear in -name to D for it to be -considered absolute. The default value is that defined using the -ndots statement in /etc/resolv.conf, or 1 if no -ndots statement is present. Names with fewer dots are interpreted as -relative names and will be searched for in the domains listed in the - or directive in -/etc/resolv.conf. - - - - -Set the UDP message buffer size advertised using EDNS0 to -B bytes. The maximum and minimum sizes of this -buffer are 65535 and 0 respectively. Values outside this range are -rounded up or down appropriately. - - - - - -Print records like the SOA records in a verbose multi-line -format with human-readable comments. The default is to print -each record on a single line, to facilitate machine parsing -of the dig output. - - - - -Do not try the next server if you receive a SERVFAIL. The default is -to not try the next server which is the reverse of normal stub resolver -behaviour. - - - - -Attempt to display the contents of messages which are malformed. -The default is to not display malformed answers. - - - - -Requests DNSSEC records be sent by setting the DNSSEC OK bit (DO) -in the OPT record in the additional section of the query. - - - - -Chase DNSSEC signature chains. Requires dig be compiled with --DDIG_SIGCHASE. - - - - -Specify a trusted key to be used with . -Requires dig be compiled with -DDIG_SIGCHASE. - - - - -When chasing DNSSEC signature chains perform a top down validation. -Requires dig be compiled with -DDIG_SIGCHASE. - - - - - - - - - - -MULTIPLE QUERIES - - -The BIND 9 implementation of dig supports -specifying multiple queries on the command line (in addition to -supporting the batch file option). Each of those -queries can be supplied with its own set of flags, options and query -options. - - - -In this case, each query argument represent an -individual query in the command-line syntax described above. Each -consists of any of the standard options and flags, the name to be -looked up, an optional query type and class and any query options that -should be applied to that query. - - - -A global set of query options, which should be applied to all queries, -can also be supplied. These global query options must precede the -first tuple of name, class, type, options, flags, and query options -supplied on the command line. Any global query options (except -the option) can be -overridden by a query-specific set of query options. For example: - + + Jun 30, 2000 + + + + dig + 1 + BIND9 + + + + dig + DNS lookup utility + + + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + 2003 + Internet Software Consortium + + + + + + dig + @server + + + + + + + + + + + name + type + class + queryopt + + + + dig + + + + + dig + global-queryopt + query + + + + + DESCRIPTION + dig + (domain information groper) is a flexible tool + for interrogating DNS name servers. It performs DNS lookups and + displays the answers that are returned from the name server(s) that + were queried. Most DNS administrators use dig to + troubleshoot DNS problems because of its flexibility, ease of use and + clarity of output. Other lookup tools tend to have less functionality + than dig. + + + + Although dig is normally used with + command-line + arguments, it also has a batch mode of operation for reading lookup + requests from a file. A brief summary of its command-line arguments + and options is printed when the option is given. + Unlike earlier versions, the BIND9 implementation of + dig allows multiple lookups to be issued + from the + command line. + + + + Unless it is told to query a specific name server, + dig will try each of the servers listed + in + /etc/resolv.conf. + + + + When no command line arguments or options are given, will perform an + NS query for "." (the root). + + + + It is possible to set per-user defaults for dig via + ${HOME}/.digrc. This file is read and + any options in it + are applied before the command line arguments. + + + + + + SIMPLE USAGE + + + A typical invocation of dig looks like: + dig @server name type + where: + + + + + server + + + is the name or IP address of the name server to query. This can + be an IPv4 + address in dotted-decimal notation or an IPv6 + address in colon-delimited notation. When the supplied + server argument is a + hostname, + dig resolves that name before + querying that name + server. If no server + argument is provided, + dig consults /etc/resolv.conf + and queries the name servers listed there. The reply from the + name + server that responds is displayed. + + + + + + name + + + is the name of the resource record that is to be looked up. + + + + + + type + + + indicates what type of query is required — + ANY, A, MX, SIG, etc. + type can be any valid query + type. If no + type argument is supplied, + dig will perform a lookup for an + A record. + + + + + + + + + + + OPTIONS + + + The option sets the source IP address of the query + to address. This must be a valid + address on + one of the host's network interfaces or "0.0.0.0" or "::". An optional + port + may be specified by appending "#<port>" + + + + The default query class (IN for internet) is overridden by the + option. class is + any valid + class, such as HS for Hesiod records or CH for CHAOSNET records. + + + + The option makes dig + operate + in batch mode by reading a list of lookup requests to process from the + file filename. The file contains a + number of + queries, one per line. Each entry in the file should be organised in + the same way they would be presented as queries to + dig using the command-line interface. + + + + If a non-standard port number is to be queried, the + option is used. port# is + the port number that dig will send its + queries + instead of the standard DNS port number 53. This option would be used + to test a name server that has been configured to listen for queries + on a non-standard port number. + + + + The option forces dig + to only + use IPv4 query transport. The option forces + dig to only use IPv6 query transport. + + + + The option sets the query type to + type. It can be any valid query type + which is + supported in BIND9. The default query type "A", unless the + option is supplied to indicate a reverse lookup. + A zone transfer can be requested by specifying a type of AXFR. When + an incremental zone transfer (IXFR) is required, + type is set to ixfr=N. + The incremental zone transfer will contain the changes made to the zone + since the serial number in the zone's SOA record was + N. + + + + Reverse lookups - mapping addresses to names - are simplified by the + option. addr is + an IPv4 + address in dotted-decimal notation, or a colon-delimited IPv6 address. + When this option is used, there is no need to provide the + name, class and + type arguments. dig + automatically performs a lookup for a name like + 11.12.13.10.in-addr.arpa and sets the + query type and + class to PTR and IN respectively. By default, IPv6 addresses are + looked up using nibble format under the IP6.ARPA domain. + To use the older RFC1886 method using the IP6.INT domain + specify the option. Bit string labels (RFC2874) + are now experimental and are not attempted. + + + + To sign the DNS queries sent by dig and + their + responses using transaction signatures (TSIG), specify a TSIG key file + using the option. You can also specify the TSIG + key itself on the command line using the option; + name is the name of the TSIG key and + key is the actual key. The key is a + base-64 + encoded string, typically generated by + + dnssec-keygen8 + . + + Caution should be taken when using the option on + multi-user systems as the key can be visible in the output from + + ps1 + + or in the shell's history file. When + using TSIG authentication with dig, the name + server that is queried needs to know the key and algorithm that is + being used. In BIND, this is done by providing appropriate + key and server statements in + named.conf. + + + + + + QUERY OPTIONS + + dig + provides a number of query options which affect + the way in which lookups are made and the results displayed. Some of + these set or reset flag bits in the query header, some determine which + sections of the answer get printed, and others determine the timeout + and retry strategies. + + + + Each query option is identified by a keyword preceded by a plus sign + (+). Some keywords set or reset an + option. These may be preceded + by the string no to negate the meaning of + that keyword. Other + keywords assign values to options like the timeout interval. They + have the form . + The query options are: + + + + + + + + Use [do not use] TCP when querying name servers. The default + behaviour is to use UDP unless an AXFR or IXFR query is + requested, in + which case a TCP connection is used. + + + + + + + + + Use [do not use] TCP when querying name servers. This alternate + syntax to +[no]tcp is + provided for backwards + compatibility. The "vc" stands for "virtual circuit". + + + + + + + + + Ignore truncation in UDP responses instead of retrying with TCP. + By + default, TCP retries are performed. + + + + + + + + + Set the search list to contain the single domain + somename, as if specified in + a + domain directive in + /etc/resolv.conf, and enable + search list + processing as if the +search + option were given. + + + + + + + + + Use [do not use] the search list defined by the searchlist or + domain + directive in resolv.conf (if + any). + The search list is not used by default. + + + + + + + + + Deprecated, treated as a synonym for +[no]search + + + + + + + + + Sets the "aa" flag in the query. + + + + + + + + + A synonym for +[no]aaonly. + + + + + + + + + Set [do not set] the AD (authentic data) bit in the query. The + AD bit + currently has a standard meaning only in responses, not in + queries, + but the ability to set the bit in the query is provided for + completeness. + + + + + + + + + Set [do not set] the CD (checking disabled) bit in the query. + This + requests the server to not perform DNSSEC validation of + responses. + + + + + + + + + Display [do not display] the CLASS when printing the record. + + + + + + + + + Display [do not display] the TTL when printing the record. + + + + + + + + + Toggle the setting of the RD (recursion desired) bit in the + query. + This bit is set by default, which means dig + normally sends recursive queries. Recursion is automatically + disabled + when the +nssearch or + +trace query options are + used. + + + + + + + + + When this option is set, dig + attempts to find the + authoritative name servers for the zone containing the name + being + looked up and display the SOA record that each name server has + for the + zone. + + + + + + + + + Toggle tracing of the delegation path from the root name servers + for + the name being looked up. Tracing is disabled by default. When + tracing is enabled, dig makes + iterative queries to + resolve the name being looked up. It will follow referrals from + the + root servers, showing the answer from each server that was used + to + resolve the lookup. + + + + + + + + + toggles the printing of the initial comment in the output + identifying + the version of dig and the query + options that have + been applied. This comment is printed by default. + + + + + + + + + Provide a terse answer. The default is to print the answer in a + verbose form. + + + + + + + + + Show [or do not show] the IP address and port number that + supplied the + answer when the +short option + is enabled. If + short form answers are requested, the default is not to show the + source address and port number of the server that provided the + answer. + + + + + + + + + Toggle the display of comment lines in the output. The default + is to + print comments. + + + + + + + + + This query option toggles the printing of statistics: when the + query + was made, the size of the reply and so on. The default + behaviour is + to print the query statistics. + + + + + + + + + Print [do not print] the query as it is sent. + By default, the query is not printed. + + + + + + + + + Print [do not print] the question section of a query when an + answer is + returned. The default is to print the question section as a + comment. + + + + + + + + + Display [do not display] the answer section of a reply. The + default + is to display it. + + + + + + + + + Display [do not display] the authority section of a reply. The + default is to display it. + + + + + + + + + Display [do not display] the additional section of a reply. + The default is to display it. + + + + + + + + + Set or clear all display flags. + + + + + + + + + + Sets the timeout for a query to + T seconds. The default time + out is 5 seconds. + An attempt to set T to less + than 1 will result + in a query timeout of 1 second being applied. + + + + + + + + + Sets the number of times to try UDP queries to server to + T instead of the default, 3. + If + T is less than or equal to + zero, the number of + tries is silently rounded up to 1. + + + + + + + + + Sets the number of times to retry UDP queries to server to + T instead of the default, 2. + Unlike + +tries, this does not include + the initial + query. + + + + + + + + + Set the number of dots that have to appear in + name to D for it to be + considered absolute. The default value is that defined using + the + ndots statement in /etc/resolv.conf, or 1 if no + ndots statement is present. Names with fewer dots are + interpreted as + relative names and will be searched for in the domains listed in + the + or directive in + /etc/resolv.conf. + + + + + + + + + Set the UDP message buffer size advertised using EDNS0 to + B bytes. The maximum and + minimum sizes of this + buffer are 65535 and 0 respectively. Values outside this range + are + rounded up or down appropriately. + + + + + + + + + Print records like the SOA records in a verbose multi-line + format with human-readable comments. The default is to print + each record on a single line, to facilitate machine parsing + of the dig output. + + + + + + + + + Do not try the next server if you receive a SERVFAIL. The + default is + to not try the next server which is the reverse of normal stub + resolver + behaviour. + + + + + + + + + Attempt to display the contents of messages which are malformed. + The default is to not display malformed answers. + + + + + + + + + Requests DNSSEC records be sent by setting the DNSSEC OK bit + (DO) + in the OPT record in the additional section of the query. + + + + + + + + + Chase DNSSEC signature chains. Requires dig be compiled with + -DDIG_SIGCHASE. + + + + + + + + + Specify a trusted key to be used with + . + Requires dig be compiled with -DDIG_SIGCHASE. + + + + + + + + + When chasing DNSSEC signature chains perform a top down + validation. + Requires dig be compiled with -DDIG_SIGCHASE. + + + + + + + + + + + + + MULTIPLE QUERIES + + + The BIND 9 implementation of dig + supports + specifying multiple queries on the command line (in addition to + supporting the batch file option). Each of those + queries can be supplied with its own set of flags, options and query + options. + + + + In this case, each query argument + represent an + individual query in the command-line syntax described above. Each + consists of any of the standard options and flags, the name to be + looked up, an optional query type and class and any query options that + should be applied to that query. + + + + A global set of query options, which should be applied to all queries, + can also be supplied. These global query options must precede the + first tuple of name, class, type, options, flags, and query options + supplied on the command line. Any global query options (except + the option) can be + overridden by a query-specific set of query options. For example: + dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr -shows how dig could be used from the command line -to make three lookups: an ANY query for www.isc.org, a -reverse lookup of 127.0.0.1 and a query for the NS records of -isc.org. - -A global query option of +qr is applied, so -that dig shows the initial query it made for each -lookup. The final query has a local query option of -+noqr which means that dig -will not print the initial query when it looks up the NS records for -isc.org. - - - - - -FILES - -/etc/resolv.conf - - -${HOME}/.digrc - - - - -SEE ALSO - - -host1 -, - -named8 -, - -dnssec-keygen8 -, -RFC1035. - - - - -BUGS - -There are probably too many query options. - - - + shows how dig could be used from the + command line + to make three lookups: an ANY query for www.isc.org, a + reverse lookup of 127.0.0.1 and a query for the NS records of + isc.org. + + A global query option of +qr is + applied, so + that dig shows the initial query it made + for each + lookup. The final query has a local query option of + +noqr which means that dig + will not print the initial query when it looks up the NS records for + isc.org. + + + + + + FILES + /etc/resolv.conf + + ${HOME}/.digrc + + + + + SEE ALSO + + host1 + , + + named8 + , + + dnssec-keygen8 + , + RFC1035. + + + + + BUGS + + There are probably too many query options. + + + diff --git a/bin/dig/host.docbook b/bin/dig/host.docbook index a9272ad29cb6270049ed41e049e8f27431daf0bb..70b358b0a40fcd136777260cbeaec8edec5a2d7d 100644 --- a/bin/dig/host.docbook +++ b/bin/dig/host.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - - - -host -1 -BIND9 - - - -host -DNS lookup utility - - - - - host - - - - - - - - - - name - server - - - - -DESCRIPTION - -host -is a simple utility for performing DNS lookups. -It is normally used to convert names to IP addresses and vice versa. -When no arguments or options are given, -host -prints a short summary of its command line arguments and options. - - - -name is the domain name that is to be looked -up. It can also be a dotted-decimal IPv4 address or a colon-delimited -IPv6 address, in which case host will by default -perform a reverse lookup for that address. -server is an optional argument which is either -the name or IP address of the name server that host -should query instead of the server or servers listed in -/etc/resolv.conf. - - - -The (all) option is equivalent to setting the - option and asking host to make -a query of type ANY. - - - -When the option is used, host -will attempt to display the SOA records for zone -name from all the listed authoritative name -servers for that zone. The list of name servers is defined by the NS -records that are found for the zone. - - - -The option instructs to make a DNS query of class -class. This can be used to lookup Hesiod or -Chaosnet class resource records. The default class is IN (Internet). - - - -Verbose output is generated by host when the - or option is used. The two -options are equivalent. They have been provided for backwards -compatibility. In previous versions, the option -switched on debugging traces and enabled verbose -output. - - - -List mode is selected by the option. This makes -host perform a zone transfer for zone -name. Transfer the zone printing out the NS, PTR -and address records (A/AAAA). If combined with -all records will be printed. - - - -The -option specifies that reverse lookups of IPv6 addresses should -use the IP6.INT domain as defined in RFC1886. -The default is to use IP6.ARPA. - - - -The option sets the number of dots that have to be -in name for it to be considered absolute. The -default value is that defined using the ndots statement in -/etc/resolv.conf, or 1 if no ndots statement is -present. Names with fewer dots are interpreted as relative names and -will be searched for in the domains listed in the search -or domain directive in -/etc/resolv.conf. - - - -The number of UDP retries for a lookup can be changed with the - option. number indicates -how many times host will repeat a query that does -not get answered. The default number of retries is 1. If -number is negative or zero, the number of -retries will default to 1. - - - -Non-recursive queries can be made via the option. -Setting this option clears the RD — recursion -desired — bit in the query which host makes. -This should mean that the name server receiving the query will not -attempt to resolve name. The - option enables host to mimic -the behaviour of a name server by making non-recursive queries and -expecting to receive answers to those queries that are usually -referrals to other name servers. - - - -By default host uses UDP when making queries. The - option makes it use a TCP connection when querying -the name server. TCP will be automatically selected for queries that -require it, such as zone transfer (AXFR) requests. - - - -The option forces host to only -use IPv4 query transport. The option forces -host to only use IPv6 query transport. - - - -The option is used to select the query type. -type can be any recognised query type: CNAME, -NS, SOA, SIG, KEY, AXFR, etc. When no query type is specified, -host automatically selects an appropriate query -type. By default it looks for A records, but if the - option was given, queries will be made for SOA -records, and if name is a dotted-decimal IPv4 -address or colon-delimited IPv6 address, host will -query for PTR records. If a query type of IXFR is chosen the starting -serial number can be specified by appending an equal followed by the -starting serial number (e.g. -t IXFR=12345678). - - - -The time to wait for a reply can be controlled through the - and options. The - option makes host wait for -wait seconds. If wait -is less than one, the wait interval is set to one second. When the - option is used, host will -effectively wait forever for a reply. The time to wait for a response -will be set to the number of seconds given by the hardware's maximum -value for an integer quantity. - - - -The can be used to set the memory usage debugging flags -record, usage and -trace. - - - - -FILES - -/etc/resolv.conf - - - - -SEE ALSO - - -dig1 -, - -named8 -. - - - - + + Jun 30, 2000 + + + + host + 1 + BIND9 + + + + host + DNS lookup utility + + + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + Internet Software Consortium + + + + + + host + + + + + + + + + + name + server + + + + + DESCRIPTION + + host + is a simple utility for performing DNS lookups. + It is normally used to convert names to IP addresses and vice versa. + When no arguments or options are given, + host + prints a short summary of its command line arguments and options. + + + name is the domain name that is to be + looked + up. It can also be a dotted-decimal IPv4 address or a colon-delimited + IPv6 address, in which case host will by + default + perform a reverse lookup for that address. + server is an optional argument which + is either + the name or IP address of the name server that host + should query instead of the server or servers listed in + /etc/resolv.conf. + + + + The (all) option is equivalent to setting the + option and asking host to make + a query of type ANY. + + + + When the option is used, host + will attempt to display the SOA records for zone + name from all the listed + authoritative name + servers for that zone. The list of name servers is defined by the NS + records that are found for the zone. + + + + The option instructs to make a DNS query of class + class. This can be used to lookup + Hesiod or + Chaosnet class resource records. The default class is IN (Internet). + + + + Verbose output is generated by host when + the + or option is used. The two + options are equivalent. They have been provided for backwards + compatibility. In previous versions, the option + switched on debugging traces and enabled verbose + output. + + + + List mode is selected by the option. This makes + host perform a zone transfer for zone + name. Transfer the zone printing out + the NS, PTR + and address records (A/AAAA). If combined with + all records will be printed. + + + + The + option specifies that reverse lookups of IPv6 addresses should + use the IP6.INT domain as defined in RFC1886. + The default is to use IP6.ARPA. + + + + The option sets the number of dots that have to be + in name for it to be considered + absolute. The + default value is that defined using the ndots statement in + /etc/resolv.conf, or 1 if no ndots + statement is + present. Names with fewer dots are interpreted as relative names and + will be searched for in the domains listed in the search + or domain directive in + /etc/resolv.conf. + + + + The number of UDP retries for a lookup can be changed with the + option. number + indicates + how many times host will repeat a query + that does + not get answered. The default number of retries is 1. If + number is negative or zero, the + number of + retries will default to 1. + + + + Non-recursive queries can be made via the option. + Setting this option clears the RD — recursion + desired — bit in the query which host makes. + This should mean that the name server receiving the query will not + attempt to resolve name. The + option enables host + to mimic + the behaviour of a name server by making non-recursive queries and + expecting to receive answers to those queries that are usually + referrals to other name servers. + + + + By default host uses UDP when making + queries. The + option makes it use a TCP connection when querying + the name server. TCP will be automatically selected for queries that + require it, such as zone transfer (AXFR) requests. + + + + The option forces host to only + use IPv4 query transport. The option forces + host to only use IPv6 query transport. + + + + The option is used to select the query type. + type can be any recognised query + type: CNAME, + NS, SOA, SIG, KEY, AXFR, etc. When no query type is specified, + host automatically selects an appropriate + query + type. By default it looks for A records, but if the + option was given, queries will be made for SOA + records, and if name is a + dotted-decimal IPv4 + address or colon-delimited IPv6 address, host will + query for PTR records. If a query type of IXFR is chosen the starting + serial number can be specified by appending an equal followed by the + starting serial number (e.g. -t IXFR=12345678). + + + + The time to wait for a reply can be controlled through the + and options. The + option makes host + wait for + wait seconds. If wait + is less than one, the wait interval is set to one second. When the + option is used, host + will + effectively wait forever for a reply. The time to wait for a response + will be set to the number of seconds given by the hardware's maximum + value for an integer quantity. + + + + The can be used to set the memory usage debugging + flags + record, usage and + trace. + + + + + FILES + /etc/resolv.conf + + + + + SEE ALSO + + dig1 + , + + named8 + . + + + + diff --git a/bin/dig/nslookup.docbook b/bin/dig/nslookup.docbook index 27672663318c417ecaff792d457986930537786c..f6aa7ab52c460faff4963e4e1888f39515935b9b 100644 --- a/bin/dig/nslookup.docbook +++ b/bin/dig/nslookup.docbook @@ -1,4 +1,6 @@ - +]> - - - + - - -Jun 30, 2000 - - - -nslookup -1 -BIND9 - - - -nslookup -query Internet name servers interactively - - - - - nslookup - - name | - - server - - - - -DESCRIPTION - -Nslookup -is a program to query Internet domain name servers. Nslookup -has two modes: interactive and non-interactive. Interactive mode allows -the user to query name servers for information about various hosts and -domains or to print a list of hosts in a domain. Non-interactive mode is -used to print just the name and requested information for a host or -domain. - - - - -ARGUMENTS - -Interactive mode is entered in the following cases: - - - -when no arguments are given (the default name server will be used) - - - - -when the first argument is a hyphen (-) and the second argument is -the host name or Internet address of a name server. - - - - - - -Non-interactive mode is used when the name or Internet address of the -host to be looked up is given as the first argument. The optional second -argument specifies the host name or address of a name server. - - - -Options can also be specified on the command line if they precede the -arguments and are prefixed with a hyphen. For example, to -change the default query type to host information, and the initial timeout to 10 seconds, type: - - + + Jun 30, 2000 + + + + nslookup + 1 + BIND9 + + + + nslookup + query Internet name servers interactively + + + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + + + + + nslookup + + name | - + server + + + + + DESCRIPTION + Nslookup + is a program to query Internet domain name servers. Nslookup + has two modes: interactive and non-interactive. Interactive mode allows + the user to query name servers for information about various hosts and + domains or to print a list of hosts in a domain. Non-interactive mode + is + used to print just the name and requested information for a host or + domain. + + + + + ARGUMENTS + + Interactive mode is entered in the following cases: + + + + when no arguments are given (the default name server will be used) + + + + + when the first argument is a hyphen (-) and the second argument is + the host name or Internet address of a name server. + + + + + + + Non-interactive mode is used when the name or Internet address of the + host to be looked up is given as the first argument. The optional second + argument specifies the host name or address of a name server. + + + + Options can also be specified on the command line if they precede the + arguments and are prefixed with a hyphen. For example, to + change the default query type to host information, and the initial + timeout to 10 seconds, type: + + nslookup -query=hinfo -timeout=10 - - - - - - - -INTERACTIVE COMMANDS - -host server - -Look up information for host using the current default server or -using server, if specified. If host is an Internet address and -the query type is A or PTR, the name of the host is returned. -If host is a name and does not have a trailing period, the -search list is used to qualify the name. - - - -To look up a host not in the current domain, append a period to -the name. - - -server domain - -lserver domain - -Change the default server to domain; lserver uses the initial -server to look up information about domain, while server uses -the current default server. If an authoritative answer can't be -found, the names of servers that might have the answer are -returned. - - -root -not implemented - -finger -not implemented - -ls -not implemented - -view -not implemented - -help -not implemented - -? -not implemented - -exit -Exits the program. - -set keyword=value -This command is used to change state information that affects -the lookups. Valid keywords are: - - all - - Prints the current values of the frequently used - options to set. Information about the current default - server and host is also printed. - - - - - class=value - - Change the query class to one of: - - IN - the Internet class - CH - the Chaos class - HS - the Hesiod class - ANY - wildcard - - The class specifies the protocol group of the information. - - (Default = IN; abbreviation = cl) - - - - nodebug - - Turn debugging mode on. A lot more information is - printed about the packet sent to the server and the - resulting answer. - - (Default = nodebug; abbreviation = nodeb) - - - nod2 - - Turn debugging mode on. A lot more information is - printed about the packet sent to the server and the - resulting answer. - - (Default = nod2) - - - domain=name - - Sets the search list to name. - - - nosearch - - If the lookup request contains at least one period but - doesn't end with a trailing period, append the domain - names in the domain search list to the request until an - answer is received. - - (Default = search) - - - port=value - - Change the default TCP/UDP name server port to value. - - (Default = 53; abbreviation = po) - - - querytype=value - - - type=value - - Change the top of the information query. - - (Default = A; abbreviations = q, ty) - - - norecurse - - Tell the name server to query other servers if it does not have the - information. - - (Default = recurse; abbreviation = [no]rec) - - - retry=number - - Set the number of retries to number. - - - timeout=number - - Change the initial timeout interval for waiting for a - reply to number seconds. - - - novc - - Always use a virtual circuit when sending requests to the server. - - (Default = novc) - - - - - - - - -FILES - -/etc/resolv.conf - - - - -SEE ALSO - - -dig1 -, - -host1 -, - -named8 -. - - - - -Author - -Andrew Cherenson - - - + + + + + + + + INTERACTIVE COMMANDS + + + host server + + + Look up information for host using the current default server or + using server, if specified. If host is an Internet address and + the query type is A or PTR, the name of the host is returned. + If host is a name and does not have a trailing period, the + search list is used to qualify the name. + + + + To look up a host not in the current domain, append a period to + the name. + + + + + + server domain + + + + + + lserver domain + + + Change the default server to domain; lserver uses the initial + server to look up information about domain, while server uses + the current default server. If an authoritative answer can't be + found, the names of servers that might have the answer are + returned. + + + + + + root + + + not implemented + + + + + + finger + + + not implemented + + + + + + ls + + + not implemented + + + + + + view + + + not implemented + + + + + + help + + + not implemented + + + + + + ? + + + not implemented + + + + + + exit + + + Exits the program. + + + + + + set + keyword=value + + + This command is used to change state information that affects + the lookups. Valid keywords are: + + + all + + + Prints the current values of the frequently used + options to set. + Information about the current default + server and host is also printed. + + + + + + class=value + + + Change the query class to one of: + + + IN + + + the Internet class + + + + + CH + + + the Chaos class + + + + + HS + + + the Hesiod class + + + + + ANY + + + wildcard + + + + + The class specifies the protocol group of the information. + + + + (Default = IN; abbreviation = cl) + + + + + + + nodebug + + + Turn debugging mode on. A lot more information is + printed about the packet sent to the server and the + resulting answer. + + + (Default = nodebug; abbreviation = nodeb) + + + + + + + nod2 + + + Turn debugging mode on. A lot more information is + printed about the packet sent to the server and the + resulting answer. + + + (Default = nod2) + + + + + + domain=name + + + Sets the search list to name. + + + + + + + nosearch + + + If the lookup request contains at least one period but + doesn't end with a trailing period, append the domain + names in the domain search list to the request until an + answer is received. + + + (Default = search) + + + + + + port=value + + + Change the default TCP/UDP name server port to value. + + + (Default = 53; abbreviation = po) + + + + + + querytype=value + + + + + + + type=value + + + Change the top of the information query. + + + (Default = A; abbreviations = q, ty) + + + + + + + norecurse + + + Tell the name server to query other servers if it does not + have the + information. + + + (Default = recurse; abbreviation = [no]rec) + + + + + + retry=number + + + Set the number of retries to number. + + + + + + timeout=number + + + Change the initial timeout interval for waiting for a + reply to number seconds. + + + + + + + novc + + + Always use a virtual circuit when sending requests to the + server. + + + (Default = novc) + + + + + + + + + + + + + FILES + /etc/resolv.conf + + + + + SEE ALSO + + dig1 + , + + host1 + , + + named8 + . + + + + + Author + + Andrew Cherenson + + + diff --git a/bin/dnssec/dnssec-keygen.docbook b/bin/dnssec/dnssec-keygen.docbook index ed4de1088e099e5d304bd9f0a78a2f45a5e57ac8..1be91d31ce12cc8892277fb716bcacf3706db858 100644 --- a/bin/dnssec/dnssec-keygen.docbook +++ b/bin/dnssec/dnssec-keygen.docbook @@ -1,4 +1,6 @@ - +]> - - - + June 30, 2000 @@ -34,6 +34,21 @@ DNSSEC key generation tool + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + 2003 + Internet Software Consortium + + + dnssec-keygen @@ -57,11 +72,10 @@ DESCRIPTION - - dnssec-keygen generates keys for DNSSEC - (Secure DNS), as defined in RFC 2535 and RFC <TBA\>. It can also generate - keys for use with TSIG (Transaction Signatures), as - defined in RFC 2845. + dnssec-keygen + generates keys for DNSSEC (Secure DNS), as defined in RFC 2535 + and RFC <TBA\>. It can also generate keys for use with + TSIG (Transaction Signatures), as defined in RFC 2845. @@ -71,168 +85,173 @@ -a algorithm - - - Selects the cryptographic algorithm. The value of - must be one of RSAMD5 (RSA) or RSASHA1, - DSA, DH (Diffie Hellman), or HMAC-MD5. These values - are case insensitive. - - - Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement algorithm, - and DSA is recommended. For TSIG, HMAC-MD5 is mandatory. - - - Note 2: HMAC-MD5 and DH automatically set the -k flag. - - + + + Selects the cryptographic algorithm. The value of + must be one of RSAMD5 (RSA) or RSASHA1, + DSA, DH (Diffie Hellman), or HMAC-MD5. These values + are case insensitive. + + + Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement + algorithm, + and DSA is recommended. For TSIG, HMAC-MD5 is mandatory. + + + Note 2: HMAC-MD5 and DH automatically set the -k flag. + + -b keysize - - - Specifies the number of bits in the key. The choice of key - size depends on the algorithm used. RSAMD5 / RSASHA1 keys must be between - 512 and 2048 bits. Diffie Hellman keys must be between - 128 and 4096 bits. DSA keys must be between 512 and 1024 - bits and an exact multiple of 64. HMAC-MD5 keys must be - between 1 and 512 bits. - - + + + Specifies the number of bits in the key. The choice of key + size depends on the algorithm used. RSAMD5 / RSASHA1 keys must be + between + 512 and 2048 bits. Diffie Hellman keys must be between + 128 and 4096 bits. DSA keys must be between 512 and 1024 + bits and an exact multiple of 64. HMAC-MD5 keys must be + between 1 and 512 bits. + + -n nametype - - - Specifies the owner type of the key. The value of - must either be ZONE (for a DNSSEC - zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), - USER (for a key associated with a user(KEY)) or OTHER (DNSKEY). These values are - case insensitive. - - + + + Specifies the owner type of the key. The value of + must either be ZONE (for a DNSSEC + zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with + a host (KEY)), + USER (for a key associated with a user(KEY)) or OTHER (DNSKEY). + These values are + case insensitive. + + -c class - - - Indicates that the DNS record containing the key should have - the specified class. If not specified, class IN is used. - - + + + Indicates that the DNS record containing the key should have + the specified class. If not specified, class IN is used. + + -e - - - If generating an RSAMD5/RSASHA1 key, use a large exponent. - - + + + If generating an RSAMD5/RSASHA1 key, use a large exponent. + + -f flag - - - Set the specified flag in the flag field of the KEY/DNSKEY record. - The only recognized flag is KSK (Key Signing Key) DNSKEY. - - + + + Set the specified flag in the flag field of the KEY/DNSKEY record. + The only recognized flag is KSK (Key Signing Key) DNSKEY. + + -g generator - - - If generating a Diffie Hellman key, use this generator. - Allowed values are 2 and 5. If no generator - is specified, a known prime from RFC 2539 will be used - if possible; otherwise the default is 2. - - + + + If generating a Diffie Hellman key, use this generator. + Allowed values are 2 and 5. If no generator + is specified, a known prime from RFC 2539 will be used + if possible; otherwise the default is 2. + + -h - - - Prints a short summary of the options and arguments to - dnssec-keygen. - - + + + Prints a short summary of the options and arguments to + dnssec-keygen. + + -k - - - Generate KEY records rather than DNSKEY records. - - + + + Generate KEY records rather than DNSKEY records. + + -p protocol - - - Sets the protocol value for the generated key. The protocol - is a number between 0 and 255. The default is 3 (DNSSEC). - Other possible values for this argument are listed in - RFC 2535 and its successors. - - + + + Sets the protocol value for the generated key. The protocol + is a number between 0 and 255. The default is 3 (DNSSEC). + Other possible values for this argument are listed in + RFC 2535 and its successors. + + -r randomdev - - - Specifies the source of randomness. If the operating - system does not provide a /dev/random - or equivalent device, the default source of randomness - is keyboard input. randomdev specifies - the name of a character device or file containing random - data to be used instead of the default. The special value - keyboard indicates that keyboard - input should be used. - - + + + Specifies the source of randomness. If the operating + system does not provide a /dev/random + or equivalent device, the default source of randomness + is keyboard input. randomdev + specifies + the name of a character device or file containing random + data to be used instead of the default. The special value + keyboard indicates that keyboard + input should be used. + + -s strength - - - Specifies the strength value of the key. The strength is - a number between 0 and 15, and currently has no defined - purpose in DNSSEC. - - + + + Specifies the strength value of the key. The strength is + a number between 0 and 15, and currently has no defined + purpose in DNSSEC. + + -t type - - - Indicates the use of the key. must be - one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default - is AUTHCONF. AUTH refers to the ability to authenticate - data, and CONF the ability to encrypt data. - - + + + Indicates the use of the key. must be + one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default + is AUTHCONF. AUTH refers to the ability to authenticate + data, and CONF the ability to encrypt data. + + -v level - - - Sets the debugging level. - - + + + Sets the debugging level. + + @@ -241,83 +260,83 @@ GENERATED KEYS - When dnssec-keygen completes successfully, - it prints a string of the form Knnnn.+aaa+iiiii - to the standard output. This is an identification string for - the key it has generated. These strings can be used as arguments - to dnssec-makekeyset. + When dnssec-keygen completes + successfully, + it prints a string of the form Knnnn.+aaa+iiiii + to the standard output. This is an identification string for + the key it has generated. These strings can be used as arguments + to dnssec-makekeyset. - - nnnn is the key name. + nnnn is the key name. - - aaa is the numeric representation of the + aaa is the numeric representation + of the algorithm. - - iiiii is the key identifier (or footprint). + iiiii is the key identifier (or + footprint). - - dnssec-keygen creates two file, with names based - on the printed string. Knnnn.+aaa+iiiii.key - contains the public key, and - Knnnn.+aaa+iiiii.private contains the private - key. + dnssec-keygen + creates two file, with names based + on the printed string. Knnnn.+aaa+iiiii.key + contains the public key, and + Knnnn.+aaa+iiiii.private contains the + private + key. - The .key file contains a DNS KEY record that - can be inserted into a zone file (directly or with a $INCLUDE - statement). + The .key file contains a DNS KEY record + that + can be inserted into a zone file (directly or with a $INCLUDE + statement). - The .private file contains algorithm specific - fields. For obvious security reasons, this file does not have - general read permission. + The .private file contains algorithm + specific + fields. For obvious security reasons, this file does not have + general read permission. - Both .key and .private - files are generated for symmetric encryption algorithm such as - HMAC-MD5, even though the public and private key are equivalent. + Both .key and .private + files are generated for symmetric encryption algorithm such as + HMAC-MD5, even though the public and private key are equivalent. EXAMPLE - To generate a 768-bit DSA key for the domain - example.com, the following command would be - issued: + To generate a 768-bit DSA key for the domain + example.com, the following command would be + issued: - - dnssec-keygen -a DSA -b 768 -n ZONE example.com + dnssec-keygen -a DSA -b 768 -n ZONE example.com - The command would print a string of the form: + The command would print a string of the form: - - Kexample.com.+003+26160 + Kexample.com.+003+26160 - In this example, dnssec-keygen creates - the files Kexample.com.+003+26160.key and - Kexample.com.+003+26160.private + In this example, dnssec-keygen creates + the files Kexample.com.+003+26160.key + and + Kexample.com.+003+26160.private SEE ALSO - - - dnssec-signzone - 8 + + dnssec-signzone8 , BIND 9 Administrator Reference Manual, RFC 2535, @@ -328,14 +347,11 @@ AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - - - + June 30, 2000 @@ -34,6 +34,21 @@ DNSSEC zone signing tool + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + 2003 + Internet Software Consortium + + + dnssec-signzone @@ -63,13 +78,13 @@ DESCRIPTION - - dnssec-signzone signs a zone. It generates - NSEC and RRSIG records and produces a signed version of the - zone. The security status of delegations from the signed zone - (that is, whether the child zones are secure or not) is - determined by the presence or absence of a - keyset file for each child zone. + dnssec-signzone + signs a zone. It generates + NSEC and RRSIG records and produces a signed version of the + zone. The security status of delegations from the signed zone + (that is, whether the child zones are secure or not) is + determined by the presence or absence of a + keyset file for each child zone. @@ -79,256 +94,259 @@ -a - - - Verify all generated signatures. - - + + + Verify all generated signatures. + + -c class - - - Specifies the DNS class of the zone. - - + + + Specifies the DNS class of the zone. + + -k key - - - Treat specified key as a key signing key ignoring any - key flags. This option may be specified multiple times. - - + + + Treat specified key as a key signing key ignoring any + key flags. This option may be specified multiple times. + + -l domain - - - Generate a DLV set in addition to the key (DNSKEY) and DS sets. - The domain is appended to the name of the records. - - + + + Generate a DLV set in addition to the key (DNSKEY) and DS sets. + The domain is appended to the name of the records. + + -d directory - - - Look for keyset files in - as the directory - - + + + Look for keyset files in + as the directory + + -g - - - Generate DS records for child zones from keyset files. - Existing DS records will be removed. - - + + + Generate DS records for child zones from keyset files. + Existing DS records will be removed. + + -s start-time - - - Specify the date and time when the generated RRSIG records - become valid. This can be either an absolute or relative - time. An absolute start time is indicated by a number - in YYYYMMDDHHMMSS notation; 20000530144500 denotes - 14:45:00 UTC on May 30th, 2000. A relative start time is - indicated by +N, which is N seconds from the current time. - If no is specified, the current - time minus 1 hour (to allow for clock skew) is used. - - + + + Specify the date and time when the generated RRSIG records + become valid. This can be either an absolute or relative + time. An absolute start time is indicated by a number + in YYYYMMDDHHMMSS notation; 20000530144500 denotes + 14:45:00 UTC on May 30th, 2000. A relative start time is + indicated by +N, which is N seconds from the current time. + If no is specified, the current + time minus 1 hour (to allow for clock skew) is used. + + -e end-time - - - Specify the date and time when the generated RRSIG records - expire. As with , an absolute - time is indicated in YYYYMMDDHHMMSS notation. A time relative - to the start time is indicated with +N, which is N seconds from - the start time. A time relative to the current time is - indicated with now+N. If no is - specified, 30 days from the start time is used as a default. - - + + + Specify the date and time when the generated RRSIG records + expire. As with , an absolute + time is indicated in YYYYMMDDHHMMSS notation. A time relative + to the start time is indicated with +N, which is N seconds from + the start time. A time relative to the current time is + indicated with now+N. If no is + specified, 30 days from the start time is used as a default. + + -f output-file - - - The name of the output file containing the signed zone. The - default is to append .signed to the - input file. - - + + + The name of the output file containing the signed zone. The + default is to append .signed to + the + input file. + + -h - - - Prints a short summary of the options and arguments to - dnssec-signzone. - - + + + Prints a short summary of the options and arguments to + dnssec-signzone. + + -i interval - - - When a previously signed zone is passed as input, records - may be resigned. The option - specifies the cycle interval as an offset from the current - time (in seconds). If a RRSIG record expires after the - cycle interval, it is retained. Otherwise, it is considered - to be expiring soon, and it will be replaced. - - - The default cycle interval is one quarter of the difference - between the signature end and start times. So if neither - or - are specified, dnssec-signzone generates - signatures that are valid for 30 days, with a cycle - interval of 7.5 days. Therefore, if any existing RRSIG records - are due to expire in less than 7.5 days, they would be - replaced. - - + + + When a previously signed zone is passed as input, records + may be resigned. The option + specifies the cycle interval as an offset from the current + time (in seconds). If a RRSIG record expires after the + cycle interval, it is retained. Otherwise, it is considered + to be expiring soon, and it will be replaced. + + + The default cycle interval is one quarter of the difference + between the signature end and start times. So if neither + or + are specified, dnssec-signzone + generates + signatures that are valid for 30 days, with a cycle + interval of 7.5 days. Therefore, if any existing RRSIG records + are due to expire in less than 7.5 days, they would be + replaced. + + - - - - When signing a zone with a fixed signature lifetime, all - RRSIG records issued at the time of signing expires - simultaneously. If the zone is incrementally signed, i.e. - a previously signed zone is passed as input to the signer, - all expired signatures has to be regenerated at about the - same time. The option specifies a - jitter window that will be used to randomize the signature - expire time, thus spreading incremental signature - regeneration over time. - - - Signature lifetime jitter also to some extent benefits - validators and servers by spreading out cache expiration, - i.e. if large numbers of RRSIGs don't expire at the same time - from all caches there will be less congestion than if all - validators need to refetch at mostly the same time. - - + -j jitter + + + When signing a zone with a fixed signature lifetime, all + RRSIG records issued at the time of signing expires + simultaneously. If the zone is incrementally signed, i.e. + a previously signed zone is passed as input to the signer, + all expired signatures has to be regenerated at about the + same time. The option specifies a + jitter window that will be used to randomize the signature + expire time, thus spreading incremental signature + regeneration over time. + + + Signature lifetime jitter also to some extent benefits + validators and servers by spreading out cache expiration, + i.e. if large numbers of RRSIGs don't expire at the same time + from all caches there will be less congestion than if all + validators need to refetch at mostly the same time. + + -n ncpus - - - Specifies the number of threads to use. By default, one - thread is started for each detected CPU. - - + + + Specifies the number of threads to use. By default, one + thread is started for each detected CPU. + + -o origin - - - The zone origin. If not specified, the name of the zone file - is assumed to be the origin. - - + + + The zone origin. If not specified, the name of the zone file + is assumed to be the origin. + + -p - - - Use pseudo-random data when signing the zone. This is faster, - but less secure, than using real random data. This option - may be useful when signing large zones or when the entropy - source is limited. - - + + + Use pseudo-random data when signing the zone. This is faster, + but less secure, than using real random data. This option + may be useful when signing large zones or when the entropy + source is limited. + + -r randomdev - - - Specifies the source of randomness. If the operating - system does not provide a /dev/random - or equivalent device, the default source of randomness - is keyboard input. randomdev specifies - the name of a character device or file containing random - data to be used instead of the default. The special value - keyboard indicates that keyboard - input should be used. - - + + + Specifies the source of randomness. If the operating + system does not provide a /dev/random + or equivalent device, the default source of randomness + is keyboard input. randomdev + specifies + the name of a character device or file containing random + data to be used instead of the default. The special value + keyboard indicates that keyboard + input should be used. + + -t - - - Print statistics at completion. - - + + + Print statistics at completion. + + -v level - - - Sets the debugging level. - - + + + Sets the debugging level. + + -z - - - Ignore KSK flag on key when determining what to sign. - - + + + Ignore KSK flag on key when determining what to sign. + + zonefile - - - The file containing the zone to be signed. - Sets the debugging level. - - + + + The file containing the zone to be signed. + Sets the debugging level. + + key - - - The keys used to sign the zone. If no keys are specified, the - default all zone keys that have private key files in the - current directory. - - + + + The keys used to sign the zone. If no keys are specified, the + default all zone keys that have private key files in the + current directory. + + @@ -337,34 +355,34 @@ EXAMPLE - The following command signs the example.com - zone with the DSA key generated in the dnssec-keygen - man page. The zone's keys must be in the zone. If there are - keyset files associated with child zones, - they must be in the current directory. - example.com, the following command would be - issued: + The following command signs the example.com + zone with the DSA key generated in the dnssec-keygen + man page. The zone's keys must be in the zone. If there are + keyset files associated with child + zones, + they must be in the current directory. + example.com, the following command would be + issued: - - dnssec-signzone -o example.com db.example.com Kexample.com.+003+26160 + dnssec-signzone -o example.com db.example.com + Kexample.com.+003+26160 - The command would print a string of the form: + The command would print a string of the form: - In this example, dnssec-signzone creates - the file db.example.com.signed. This file - should be referenced in a zone statement in a - named.conf file. + In this example, dnssec-signzone creates + the file db.example.com.signed. This + file + should be referenced in a zone statement in a + named.conf file. SEE ALSO - - - dnssec-keygen - 8 + + dnssec-keygen8 , BIND 9 Administrator Reference Manual, RFC 2535. @@ -373,14 +391,11 @@ AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - - - + June 30, 2000 @@ -34,6 +34,18 @@ lightweight resolver daemon + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + lwresd @@ -54,37 +66,39 @@ DESCRIPTION - - lwresd is the daemon providing name lookup - services to clients that use the BIND 9 lightweight resolver - library. It is essentially a stripped-down, caching-only name - server that answers queries using the BIND 9 lightweight - resolver protocol rather than the DNS protocol. + + lwresd + is the daemon providing name lookup + services to clients that use the BIND 9 lightweight resolver + library. It is essentially a stripped-down, caching-only name + server that answers queries using the BIND 9 lightweight + resolver protocol rather than the DNS protocol. - - lwresd listens for resolver queries on a - UDP port on the IPv4 loopback interface, 127.0.0.1. This - means that lwresd can only be used by - processes running on the local machine. By default UDP port - number 921 is used for lightweight resolver requests and - responses. + + lwresd + listens for resolver queries on a + UDP port on the IPv4 loopback interface, 127.0.0.1. This + means that lwresd can only be used by + processes running on the local machine. By default UDP port + number 921 is used for lightweight resolver requests and + responses. - Incoming lightweight resolver requests are decoded by the - server which then resolves them using the DNS protocol. When - the DNS lookup completes, lwresd encodes - the answers in the lightweight resolver format and returns - them to the client that made the request. + Incoming lightweight resolver requests are decoded by the + server which then resolves them using the DNS protocol. When + the DNS lookup completes, lwresd encodes + the answers in the lightweight resolver format and returns + them to the client that made the request. - If /etc/resolv.conf contains any - entries, lwresd - sends recursive DNS queries to those servers. This is similar - to the use of forwarders in a caching name server. If no - entries are present, or if - forwarding fails, lwresd resolves the - queries autonomously starting at the root name servers, using - a built-in list of root server hints. + If /etc/resolv.conf contains any + entries, lwresd + sends recursive DNS queries to those servers. This is similar + to the use of forwarders in a caching name server. If no + entries are present, or if + forwarding fails, lwresd resolves the + queries autonomously starting at the root name servers, using + a built-in list of root server hints. @@ -93,145 +107,139 @@ - -C config-file - - - Use config-file as the - configuration file instead of the default, - /etc/resolv.conf. + -C config-file + + + Use config-file as the + configuration file instead of the default, + /etc/resolv.conf. - + - -d debug-level - - - Set the daemon's debug level to debug-level. - Debugging traces from lwresd become - more verbose as the debug level increases. + -d debug-level + + + Set the daemon's debug level to debug-level. + Debugging traces from lwresd become + more verbose as the debug level increases. - + - -f - - - Run the server in the foreground (i.e. do not daemonize). + -f + + + Run the server in the foreground (i.e. do not daemonize). - + - -g - - - Run the server in the foreground and force all logging - to stderr. + -g + + + Run the server in the foreground and force all logging + to stderr. - + - -n #cpus - - - Create #cpus worker threads - to take advantage of multiple CPUs. If not specified, - lwresd will try to determine the - number of CPUs present and create one thread per CPU. - If it is unable to determine the number of CPUs, a - single worker thread will be created. + -n #cpus + + + Create #cpus worker threads + to take advantage of multiple CPUs. If not specified, + lwresd will try to determine the + number of CPUs present and create one thread per CPU. + If it is unable to determine the number of CPUs, a + single worker thread will be created. - + - -P port - - - Listen for lightweight resolver queries on port - port. If - not specified, the default is port 921. + -P port + + + Listen for lightweight resolver queries on port + port. If + not specified, the default is port 921. - + - -p port - - - Send DNS lookups to port port. If not - specified, the default is port 53. This provides a - way of testing the lightweight resolver daemon with a - name server that listens for queries on a non-standard - port number. + -p port + + + Send DNS lookups to port port. If not + specified, the default is port 53. This provides a + way of testing the lightweight resolver daemon with a + name server that listens for queries on a non-standard + port number. - + - -s - - - Write memory usage statistics to stdout - on exit. + -s + + + Write memory usage statistics to stdout + on exit. - - - This option is mainly of interest to BIND 9 developers - and may be removed or changed in a future release. - - - + + + This option is mainly of interest to BIND 9 developers + and may be removed or changed in a future release. + + + - -t directory - - - chroot() to directory after - processing the command line arguments, but before - reading the configuration file. + -t directory + + chroot() + to directory after + processing the command line arguments, but before + reading the configuration file. - - - This option should be used in conjunction with the - option, as chrooting a process - running as root doesn't enhance security on most - systems; the way chroot() is - defined allows a process with root privileges to - escape a chroot jail. - - - + + + This option should be used in conjunction with the + option, as chrooting a process + running as root doesn't enhance security on most + systems; the way chroot() is + defined allows a process with root privileges to + escape a chroot jail. + + + - -u user - - - setuid() to user after completing - privileged operations, such as creating sockets that - listen on privileged ports. + -u user + + setuid() + to user after completing + privileged operations, such as creating sockets that + listen on privileged ports. - + - -v - - - Report the version number and exit. + -v + + + Report the version number and exit. - + @@ -244,21 +252,21 @@ - /etc/resolv.conf - - - The default configuration file. + /etc/resolv.conf + + + The default configuration file. - + - /var/run/lwresd.pid - - - The default process-id file. + /var/run/lwresd.pid + + + The default process-id file. - + @@ -267,33 +275,25 @@ SEE ALSO - - - named - 8 - , - - lwres - 3 - , - - resolver - 5 - . + + named8 + , + + lwres3 + , + + resolver5 + . AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - - - - + Aug 13, 2004 @@ -33,6 +33,14 @@ configuration file for named + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + named.conf @@ -41,55 +49,55 @@ DESCRIPTION - - named.conf is the configuration file for - named. Statements are enclosed - in braces and terminated with a semi-colon. Clauses in - the statements are also semi-colon terminated. The usual - comment styles are supported: + named.conf is the configuration file + for + named. Statements are enclosed + in braces and terminated with a semi-colon. Clauses in + the statements are also semi-colon terminated. The usual + comment styles are supported: - C style: /* */ + C style: /* */ - C++ style: // to end of line + C++ style: // to end of line - Unix style: # to end of line + Unix style: # to end of line - -ACL - + + ACL + acl string { address_match_element; ... }; - - + + - -KEY - + + KEY + key domain_name { algorithm string; secret string; }; - - + + - -MASTERS - + + MASTERS + masters string port integer { ( masters | ipv4_address port integer | ipv6_address port integer ) key string ; ... }; - - + + - -SERVER - + + SERVER + server ( ipv4_address/prefixlen | ipv6_address/prefixlen ) { bogus boolean; edns boolean; @@ -105,21 +113,21 @@ server ( ipv4_address/prefixlen support-ixfr boolean; // obsolete }; - - + + - -TRUSTED-KEYS - + + TRUSTED-KEYS + trusted-keys { domain_name flags protocol algorithm key; ... }; - - + + - -CONTROLS - + + CONTROLS + controls { inet ( ipv4_address | ipv6_address | * ) port ( integer | * ) @@ -127,12 +135,12 @@ controls { keys { string; ... } ; unix unsupported; // not implemented }; - - + + - -LOGGING - + + LOGGING + logging { channel string { file log_file; @@ -146,12 +154,12 @@ logging { }; category string { string; ... }; }; - - + + - -LWRES - + + LWRES + lwres { listen-on port integer { ( ipv4_address | ipv6_address ) port integer ; ... @@ -160,12 +168,12 @@ lwres { search { string; ... }; ndots integer; }; - - + + - -OPTIONS - + + OPTIONS + options { avoid-v4-udp-ports { port; ... }; avoid-v6-udp-ports { port; ... }; @@ -307,12 +315,12 @@ options { treat-cr-as-space boolean; // obsolete use-id-pool boolean; // obsolete }; - - + + - -VIEW - + + VIEW + view string optional_class { match-clients { address_match_element; ... }; match-destinations { address_match_element; ... }; @@ -429,12 +437,12 @@ view string optional_class maintain-ixfr-base boolean; // obsolete max-ixfr-log-size size; // obsolete }; - - + + - -ZONE - + + ZONE + zone string optional_class { type ( master | slave | stub | hint | forward | delegation-only ); @@ -508,33 +516,30 @@ zone string optional_class max-ixfr-log-size size; // obsolete pubkey integer integer integer quoted_string; // obsolete }; - - - - -FILES - -/etc/named.conf - - - - -SEE ALSO - - -named8 -, - -rndc8 -, - -BIND 9 Adminstrators Reference Manual -. - - - - - - - - + June 30, 2000 @@ -34,6 +34,19 @@ Internet domain name server + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2003 + Internet Software Consortium + + + named @@ -55,16 +68,17 @@ DESCRIPTION - - named is a Domain Name System (DNS) server, - part of the BIND 9 distribution from ISC. For more - information on the DNS, see RFCs 1033, 1034, and 1035. + named + is a Domain Name System (DNS) server, + part of the BIND 9 distribution from ISC. For more + information on the DNS, see RFCs 1033, 1034, and 1035. - When invoked without arguments, named will - read the default configuration file - /etc/named.conf, read any initial - data, and listen for queries. + When invoked without arguments, named + will + read the default configuration file + /etc/named.conf, read any initial + data, and listen for queries. @@ -73,189 +87,183 @@ - -4 - - - Use IPv4 only even if the host machine is capable of IPv6. - and are mutually - exclusive. + -4 + + + Use IPv4 only even if the host machine is capable of IPv6. + and are mutually + exclusive. - + - -6 - - - Use IPv6 only even if the host machine is capable of IPv4. - and are mutually - exclusive. + -6 + + + Use IPv6 only even if the host machine is capable of IPv4. + and are mutually + exclusive. - + - -c config-file - - - Use config-file as the - configuration file instead of the default, - /etc/named.conf. To - ensure that reloading the configuration file continues - to work after the server has changed its working - directory due to to a possible - option in the configuration - file, config-file should be - an absolute pathname. + -c config-file + + + Use config-file as the + configuration file instead of the default, + /etc/named.conf. To + ensure that reloading the configuration file continues + to work after the server has changed its working + directory due to to a possible + option in the configuration + file, config-file should be + an absolute pathname. - + - -d debug-level - - - Set the daemon's debug level to debug-level. - Debugging traces from named become - more verbose as the debug level increases. + -d debug-level + + + Set the daemon's debug level to debug-level. + Debugging traces from named become + more verbose as the debug level increases. - + - -f - - - Run the server in the foreground (i.e. do not daemonize). + -f + + + Run the server in the foreground (i.e. do not daemonize). - + - -g - - - Run the server in the foreground and force all logging - to stderr. + -g + + + Run the server in the foreground and force all logging + to stderr. - + - -n #cpus - - - Create #cpus worker threads - to take advantage of multiple CPUs. If not specified, - named will try to determine the - number of CPUs present and create one thread per CPU. - If it is unable to determine the number of CPUs, a - single worker thread will be created. + -n #cpus + + + Create #cpus worker threads + to take advantage of multiple CPUs. If not specified, + named will try to determine the + number of CPUs present and create one thread per CPU. + If it is unable to determine the number of CPUs, a + single worker thread will be created. - + - -p port - - - Listen for queries on port port. If not - specified, the default is port 53. + -p port + + + Listen for queries on port port. If not + specified, the default is port 53. - + - -s - - - Write memory usage statistics to stdout on exit. + -s + + + Write memory usage statistics to stdout on exit. - - - This option is mainly of interest to BIND 9 developers - and may be removed or changed in a future release. - - - + + + This option is mainly of interest to BIND 9 developers + and may be removed or changed in a future release. + + + - -t directory - - - chroot() to directory after - processing the command line arguments, but before - reading the configuration file. + -t directory + + chroot() + to directory after + processing the command line arguments, but before + reading the configuration file. - - - This option should be used in conjunction with the - option, as chrooting a process - running as root doesn't enhance security on most - systems; the way chroot() is - defined allows a process with root privileges to - escape a chroot jail. - - - + + + This option should be used in conjunction with the + option, as chrooting a process + running as root doesn't enhance security on most + systems; the way chroot() is + defined allows a process with root privileges to + escape a chroot jail. + + + - -u user - - - setuid() to user after completing - privileged operations, such as creating sockets that - listen on privileged ports. + -u user + + setuid() + to user after completing + privileged operations, such as creating sockets that + listen on privileged ports. - - - On Linux, named uses the kernel's - capability mechanism to drop all root privileges - except the ability to bind() to a - privileged port and set process resource limits. - Unfortunately, this means that the - option only works when named is run - on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or - later, since previous kernels did not allow privileges - to be retained after setuid(). - - - + + + On Linux, named uses the kernel's + capability mechanism to drop all root privileges + except the ability to bind() to + a + privileged port and set process resource limits. + Unfortunately, this means that the + option only works when named is + run + on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or + later, since previous kernels did not allow privileges + to be retained after setuid(). + + + - -v - - - Report the version number and exit. + -v + + + Report the version number and exit. - + - -x cache-file - - - Load data from cache-file into the - cache of the default view. + -x cache-file + + + Load data from cache-file into the + cache of the default view. - - - This option must not be used. It is only of interest - to BIND 9 developers and may be removed or changed in a - future release. - - - + + + This option must not be used. It is only of interest + to BIND 9 developers and may be removed or changed in a + future release. + + + @@ -265,35 +273,35 @@ SIGNALS - In routine operation, signals should not be used to control - the nameserver; rndc should be used - instead. + In routine operation, signals should not be used to control + the nameserver; rndc should be used + instead. - SIGHUP - - - Force a reload of the server. + SIGHUP + + + Force a reload of the server. - + - SIGINT, SIGTERM - - - Shut down the server. + SIGINT, SIGTERM + + + Shut down the server. - + - The result of sending any other signals to the server is undefined. + The result of sending any other signals to the server is undefined. @@ -301,10 +309,10 @@ CONFIGURATION - The named configuration file is too complex - to describe in detail here. A complete description is - provided in the BIND 9 Administrator Reference - Manual. + The named configuration file is too complex + to describe in detail here. A complete description is provided + in the + BIND 9 Administrator Reference Manual. @@ -314,21 +322,21 @@ - /etc/named.conf - - - The default configuration file. + /etc/named.conf + + + The default configuration file. - + - /var/run/named.pid - - - The default process-id file. + /var/run/named.pid + + + The default process-id file. - + @@ -337,33 +345,26 @@ SEE ALSO - - RFC 1033, - RFC 1034, - RFC 1035, - - rndc - 8 - , - - lwresd - 8 - , - BIND 9 Administrator Reference Manual. + RFC 1033, + RFC 1034, + RFC 1035, + + rndc8 + , + + lwresd8 + , + BIND 9 Administrator Reference Manual. AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - - - - + - -Jun 30, 2000 - - -nsupdate -8 -BIND9 - - -nsupdate -Dynamic DNS update utility - - - -nsupdate - - - - - - - - - -filename - - - - -DESCRIPTION - -nsupdate -is used to submit Dynamic DNS Update requests as defined in RFC2136 -to a name server. -This allows resource records to be added or removed from a zone -without manually editing the zone file. -A single update request can contain requests to add or remove more than one -resource record. - - -Zones that are under dynamic control via -nsupdate -or a DHCP server should not be edited by hand. -Manual edits could -conflict with dynamic updates and cause data to be lost. - - -The resource records that are dynamically added or removed with -nsupdate -have to be in the same zone. -Requests are sent to the zone's master server. -This is identified by the MNAME field of the zone's SOA record. - - -The - -option makes -nsupdate -operate in debug mode. -This provides tracing information about the update requests that are -made and the replies received from the name server. - - -Transaction signatures can be used to authenticate the Dynamic DNS -updates. -These use the TSIG resource record type described in RFC2845 or the -SIG(0) record described in RFC3535 and RFC2931. -TSIG relies on a shared secret that should only be known to -nsupdate and the name server. -Currently, the only supported encryption algorithm for TSIG is -HMAC-MD5, which is defined in RFC 2104. -Once other algorithms are defined for TSIG, applications will need to -ensure they select the appropriate algorithm as well as the key when -authenticating each other. -For instance suitable -key -and -server -statements would be added to -/etc/named.conf -so that the name server can associate the appropriate secret key -and algorithm with the IP address of the -client application that will be using TSIG authentication. -SIG(0) uses public key cryptography. To use a SIG(0) key, the public -key must be stored in a KEY record in a zone served by the name server. -nsupdate -does not read -/etc/named.conf. - - -nsupdate -uses the - -or - -option (with an HMAC-MD5 key) to provide the shared secret needed to generate -a TSIG record for authenticating Dynamic DNS update requests. -These options are mutually exclusive. -With the - -option, -nsupdate -reads the shared secret from the file -keyfile, -whose name is of the form -K{name}.+157.+{random}.private. -For historical -reasons, the file -K{name}.+157.+{random}.key -must also be present. When the - -option is used, a signature is generated from -keyname:secret. -keyname -is the name of the key, -and -secret -is the base64 encoded shared secret. -Use of the - -option is discouraged because the shared secret is supplied as a command -line argument in clear text. -This may be visible in the output from - -ps1 - - -or in a history file maintained by the user's shell. - - -The may also be used to specify a SIG(0) key used -to authenticate Dynamic DNS update requests. In this case, the key -specified is not an HMAC-MD5 key. - - -By default -nsupdate -uses UDP to send update requests to the name server unless they are too -large to fit in a UDP request in which case TCP will be used. -The - -option makes -nsupdate -use a TCP connection. -This may be preferable when a batch of update requests is made. - -The option sets the maximum time a update request can -take before it is aborted. The default is 300 seconds. Zero can be used -to disable the timeout. - -The option sets the UDP retry interval. The default is -3 seconds. If zero the interval will be computed from the timeout interval -and number of UDP retries. - -The option sets the number of UDP retries. The default is -3. If zero only one update request will be made. - - - - -INPUT FORMAT - -nsupdate -reads input from -filename -or standard input. -Each command is supplied on exactly one line of input. -Some commands are for administrative purposes. -The others are either update instructions or prerequisite checks on the -contents of the zone. -These checks set conditions that some name or set of -resource records (RRset) either exists or is absent from the zone. -These conditions must be met if the entire update request is to succeed. -Updates will be rejected if the tests for the prerequisite conditions fail. - - -Every update request consists of zero or more prerequisites -and zero or more updates. -This allows a suitably authenticated update request to proceed if some -specified resource records are present or missing from the zone. -A blank input line (or the send command) causes the -accumulated commands to be sent as one Dynamic DNS update request to the -name server. - - -The command formats and their meaning are as follows: - - - -server -servername -port - - - - -Sends all dynamic update requests to the name server -servername. -When no server statement is provided, -nsupdate -will send updates to the master server of the correct zone. -The MNAME field of that zone's SOA record will identify the master -server for that zone. -port -is the port number on -servername -where the dynamic update requests get sent. -If no port number is specified, the default DNS port number of 53 is -used. - - - - -local -address -port - - - - -Sends all dynamic update requests using the local -address. - -When no local statement is provided, -nsupdate -will send updates using an address and port chosen by the system. -port -can additionally be used to make requests come from a specific port. -If no port number is specified, the system will assign one. - - - -zone -zonename - - - - -Specifies that all updates are to be made to the zone -zonename. -If no -zone -statement is provided, -nsupdate -will attempt determine the correct zone to update based on the rest of the input. - - - - - - -class -classname - - - - -Specify the default class. -If no class is specified the default class is -IN. - - - - - - -key -name -secret - - - - -Specifies that all updates are to be TSIG signed using the -keyname keysecret pair. -The key command -overrides any key specified on the command line via - or . - - - - - - -prereq nxdomain -domain-name - - - - -Requires that no resource record of any type exists with name -domain-name. - - - - - - - -prereq yxdomain -domain-name - - - - -Requires that -domain-name -exists (has as at least one resource record, of any type). - - - - - - -prereq nxrrset -domain-name -class -type - - - - -Requires that no resource record exists of the specified -type, -class -and -domain-name. -If -class -is omitted, IN (internet) is assumed. - - - - - - - -prereq yxrrset -domain-name -class -type - - - - -This requires that a resource record of the specified -type, -class -and -domain-name -must exist. -If -class -is omitted, IN (internet) is assumed. - - - - - - -prereq yxrrset -domain-name -class -type -data - - - - -The -data -from each set of prerequisites of this form -sharing a common -type, -class, -and -domain-name -are combined to form a set of RRs. This set of RRs must -exactly match the set of RRs existing in the zone at the -given -type, -class, -and -domain-name. -The -data -are written in the standard text representation of the resource record's -RDATA. - - - - - - -update delete -domain-name -ttl -class -type data - - - - -Deletes any resource records named -domain-name. -If -type -and -data -is provided, only matching resource records will be removed. -The internet class is assumed if -class -is not supplied. The -ttl -is ignored, and is only allowed for compatibility. - - - - - - -update add -domain-name -ttl -class -type -data - - - - -Adds a new resource record with the specified -ttl, -class -and -data. - - - - - - -show - - - - -Displays the current message, containing all of the prerequisites and -updates specified since the last send. - - - - - - -send - - - - -Sends the current message. This is equivalent to entering a blank line. - - - - - -answer - - - - -Displays the answer. - - - - - - -Lines beginning with a semicolon are comments and are ignored. - - - - - -EXAMPLES - -The examples below show how -nsupdate -could be used to insert and delete resource records from the -example.com -zone. -Notice that the input in each example contains a trailing blank line so that -a group of commands are sent as one dynamic update request to the -master name server for -example.com. - - + + Jun 30, 2000 + + + nsupdate + 8 + BIND9 + + + nsupdate + Dynamic DNS update utility + + + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + 2003 + Internet Software Consortium + + + + + + nsupdate + + + + + + + + + + filename + + + + + DESCRIPTION + nsupdate + is used to submit Dynamic DNS Update requests as defined in RFC2136 + to a name server. + This allows resource records to be added or removed from a zone + without manually editing the zone file. + A single update request can contain requests to add or remove more than + one + resource record. + + + Zones that are under dynamic control via + nsupdate + or a DHCP server should not be edited by hand. + Manual edits could + conflict with dynamic updates and cause data to be lost. + + + The resource records that are dynamically added or removed with + nsupdate + have to be in the same zone. + Requests are sent to the zone's master server. + This is identified by the MNAME field of the zone's SOA record. + + + The + + option makes + nsupdate + operate in debug mode. + This provides tracing information about the update requests that are + made and the replies received from the name server. + + + Transaction signatures can be used to authenticate the Dynamic DNS + updates. + These use the TSIG resource record type described in RFC2845 or the + SIG(0) record described in RFC3535 and RFC2931. + TSIG relies on a shared secret that should only be known to + nsupdate and the name server. + Currently, the only supported encryption algorithm for TSIG is + HMAC-MD5, which is defined in RFC 2104. + Once other algorithms are defined for TSIG, applications will need to + ensure they select the appropriate algorithm as well as the key when + authenticating each other. + For instance suitable + key + and + server + statements would be added to + /etc/named.conf + so that the name server can associate the appropriate secret key + and algorithm with the IP address of the + client application that will be using TSIG authentication. + SIG(0) uses public key cryptography. To use a SIG(0) key, the public + key must be stored in a KEY record in a zone served by the name server. + nsupdate + does not read + /etc/named.conf. + + nsupdate + uses the or + option (with an HMAC-MD5 key) to provide the shared secret needed to + generate + a TSIG record for authenticating Dynamic DNS update requests. + These options are mutually exclusive. + With the + + option, + nsupdate + reads the shared secret from the file + keyfile, + whose name is of the form + K{name}.+157.+{random}.private. + For historical + reasons, the file + K{name}.+157.+{random}.key + must also be present. When the + + option is used, a signature is generated from + keyname:secret. + keyname + is the name of the key, + and + secret + is the base64 encoded shared secret. + Use of the + + option is discouraged because the shared secret is supplied as a command + line argument in clear text. + This may be visible in the output from + + ps1 + + or in a history file maintained by the user's shell. + + + The may also be used to specify a SIG(0) key used + to authenticate Dynamic DNS update requests. In this case, the key + specified is not an HMAC-MD5 key. + + + By default + nsupdate + uses UDP to send update requests to the name server unless they are too + large to fit in a UDP request in which case TCP will be used. + The + + option makes + nsupdate + use a TCP connection. + This may be preferable when a batch of update requests is made. + + + The option sets the maximum time a update request + can + take before it is aborted. The default is 300 seconds. Zero can be + used + to disable the timeout. + + + The option sets the UDP retry interval. The default + is + 3 seconds. If zero the interval will be computed from the timeout + interval + and number of UDP retries. + + + The option sets the number of UDP retries. The + default is + 3. If zero only one update request will be made. + + + + + INPUT FORMAT + nsupdate + reads input from + filename + or standard input. + Each command is supplied on exactly one line of input. + Some commands are for administrative purposes. + The others are either update instructions or prerequisite checks on the + contents of the zone. + These checks set conditions that some name or set of + resource records (RRset) either exists or is absent from the zone. + These conditions must be met if the entire update request is to succeed. + Updates will be rejected if the tests for the prerequisite conditions + fail. + + + Every update request consists of zero or more prerequisites + and zero or more updates. + This allows a suitably authenticated update request to proceed if some + specified resource records are present or missing from the zone. + A blank input line (or the send command) + causes the + accumulated commands to be sent as one Dynamic DNS update request to the + name server. + + + The command formats and their meaning are as follows: + + + + + server + servername + port + + + + Sends all dynamic update requests to the name server + servername. + When no server statement is provided, + nsupdate + will send updates to the master server of the correct zone. + The MNAME field of that zone's SOA record will identify the + master + server for that zone. + port + is the port number on + servername + where the dynamic update requests get sent. + If no port number is specified, the default DNS port number of + 53 is + used. + + + + + + + local + address + port + + + + Sends all dynamic update requests using the local + address. + + When no local statement is provided, + nsupdate + will send updates using an address and port chosen by the + system. + port + can additionally be used to make requests come from a specific + port. + If no port number is specified, the system will assign one. + + + + + + + zone + zonename + + + + Specifies that all updates are to be made to the zone + zonename. + If no + zone + statement is provided, + nsupdate + will attempt determine the correct zone to update based on the + rest of the input. + + + + + + + class + classname + + + + Specify the default class. + If no class is specified the + default class is + IN. + + + + + + + key + name + secret + + + + Specifies that all updates are to be TSIG signed using the + keyname keysecret pair. + The key command + overrides any key specified on the command line via + or . + + + + + + + prereq nxdomain + domain-name + + + + Requires that no resource record of any type exists with name + domain-name. + + + + + + + + prereq yxdomain + domain-name + + + + Requires that + domain-name + exists (has as at least one resource record, of any type). + + + + + + + prereq nxrrset + domain-name + class + type + + + + Requires that no resource record exists of the specified + type, + class + and + domain-name. + If + class + is omitted, IN (internet) is assumed. + + + + + + + + prereq yxrrset + domain-name + class + type + + + + This requires that a resource record of the specified + type, + class + and + domain-name + must exist. + If + class + is omitted, IN (internet) is assumed. + + + + + + + prereq yxrrset + domain-name + class + type + data + + + + The + data + from each set of prerequisites of this form + sharing a common + type, + class, + and + domain-name + are combined to form a set of RRs. This set of RRs must + exactly match the set of RRs existing in the zone at the + given + type, + class, + and + domain-name. + The + data + are written in the standard text representation of the resource + record's + RDATA. + + + + + + + update delete + domain-name + ttl + class + type data + + + + Deletes any resource records named + domain-name. + If + type + and + data + is provided, only matching resource records will be removed. + The internet class is assumed if + class + is not supplied. The + ttl + is ignored, and is only allowed for compatibility. + + + + + + + update add + domain-name + ttl + class + type + data + + + + Adds a new resource record with the specified + ttl, + class + and + data. + + + + + + + show + + + + Displays the current message, containing all of the + prerequisites and + updates specified since the last send. + + + + + + + send + + + + Sends the current message. This is equivalent to entering a + blank line. + + + + + + + answer + + + + Displays the answer. + + + + + + + + + Lines beginning with a semicolon are comments and are ignored. + + + + + + EXAMPLES + + The examples below show how + nsupdate + could be used to insert and delete resource records from the + example.com + zone. + Notice that the input in each example contains a trailing blank line so + that + a group of commands are sent as one dynamic update request to the + master name server for + example.com. + + # nsupdate -> update delete oldhost.example.com A -> update add newhost.example.com 86400 A 172.16.1.1 -> send +> update delete oldhost.example.com A +> update add newhost.example.com 86400 A 172.16.1.1 +> send - - -Any A records for -oldhost.example.com -are deleted. -and an A record for -newhost.example.com -it IP address 172.16.1.1 is added. -The newly-added record has a 1 day TTL (86400 seconds) - + + + Any A records for + oldhost.example.com + are deleted. + and an A record for + newhost.example.com + it IP address 172.16.1.1 is added. + The newly-added record has a 1 day TTL (86400 seconds) + # nsupdate -> prereq nxdomain nickname.example.com -> update add nickname.example.com 86400 CNAME somehost.example.com -> send +> prereq nxdomain nickname.example.com +> update add nickname.example.com 86400 CNAME somehost.example.com +> send - - -The prerequisite condition gets the name server to check that there -are no resource records of any type for -nickname.example.com. - -If there are, the update request fails. -If this name does not exist, a CNAME for it is added. -This ensures that when the CNAME is added, it cannot conflict with the -long-standing rule in RFC1034 that a name must not exist as any other -record type if it exists as a CNAME. -(The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have -RRSIG, DNSKEY and NSEC records.) - - - - -FILES - - -/etc/resolv.conf - - -used to identify default name server - - - -K{name}.+157.+{random}.key - - -base-64 encoding of HMAC-MD5 key created by - -dnssec-keygen8 -. - - - -K{name}.+157.+{random}.private - - -base-64 encoding of HMAC-MD5 key created by - -dnssec-keygen8 -. - - - - - - -SEE ALSO - - -RFC2136 -, - -RFC3007 -, - -RFC2104 -, - -RFC2845 -, - -RFC1034 -, - -RFC2535 -, - -RFC2931 -, - -named8 -, - -dnssec-keygen8 -. - - - -BUGS - -The TSIG key is redundantly stored in two separate files. -This is a consequence of nsupdate using the DST library -for its cryptographic operations, and may change in future -releases. - - - + + + The prerequisite condition gets the name server to check that there + are no resource records of any type for + nickname.example.com. + + If there are, the update request fails. + If this name does not exist, a CNAME for it is added. + This ensures that when the CNAME is added, it cannot conflict with the + long-standing rule in RFC1034 that a name must not exist as any other + record type if it exists as a CNAME. + (The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have + RRSIG, DNSKEY and NSEC records.) + + + + + FILES + + + + /etc/resolv.conf + + + used to identify default name server + + + + + + K{name}.+157.+{random}.key + + + base-64 encoding of HMAC-MD5 key created by + + dnssec-keygen8 + . + + + + + + K{name}.+157.+{random}.private + + + base-64 encoding of HMAC-MD5 key created by + + dnssec-keygen8 + . + + + + + + + + + SEE ALSO + + RFC2136 + , + + RFC3007 + , + + RFC2104 + , + + RFC2845 + , + + RFC1034 + , + + RFC2535 + , + + RFC2931 + , + + named8 + , + + dnssec-keygen8 + . + + + + + BUGS + + The TSIG key is redundantly stored in two separate files. + This is a consequence of nsupdate using the DST library + for its cryptographic operations, and may change in future + releases. + + + diff --git a/bin/rndc/rndc-confgen.docbook b/bin/rndc/rndc-confgen.docbook index 1f210fd9bb0d9bbed5d435b6f1741ae086c5ed94..0509a5e95bb67148ec3095ba7daa65062dbe0485 100644 --- a/bin/rndc/rndc-confgen.docbook +++ b/bin/rndc/rndc-confgen.docbook @@ -1,4 +1,6 @@ - +]> - - - + Aug 27, 2001 @@ -34,6 +34,18 @@ rndc key generation tool + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + + 2001 + 2003 + Internet Software Consortium + + + rndc-confgen @@ -52,18 +64,18 @@ DESCRIPTION - - rndc-confgen generates configuration files - for rndc. It can be used as a - convenient alternative to writing the - rndc.conf file - and the corresponding controls - and key - statements in named.conf by hand. - Alternatively, it can be run with the -a - option to set up a rndc.key file and - avoid the need for a rndc.conf file - and a controls statement altogether. + rndc-confgen + generates configuration files + for rndc. It can be used as a + convenient alternative to writing the + rndc.conf file + and the corresponding controls + and key + statements in named.conf by hand. + Alternatively, it can be run with the -a + option to set up a rndc.key file and + avoid the need for a rndc.conf file + and a controls statement altogether. @@ -74,145 +86,152 @@ -a - - - Do automatic rndc configuration. - This creates a file rndc.key - in /etc (or whatever - sysconfdir - was specified as when BIND was built) - that is read by both rndc - and named on startup. The - rndc.key file defines a default - command channel and authentication key allowing - rndc to communicate with - named on the local host - with no further configuration. - - - Running rndc-confgen -a allows - BIND 9 and rndc to be used as drop-in - replacements for BIND 8 and ndc, - with no changes to the existing BIND 8 - named.conf file. - + - If a more elaborate configuration than that - generated by rndc-confgen -a - is required, for example if rndc is to be used remotely, - you should run rndc-confgen without the - -a option and set up a - rndc.conf and - named.conf - as directed. + Do automatic rndc configuration. + This creates a file rndc.key + in /etc (or whatever + sysconfdir + was specified as when BIND was + built) + that is read by both rndc + and named on startup. The + rndc.key file defines a default + command channel and authentication key allowing + rndc to communicate with + named on the local host + with no further configuration. - + + Running rndc-confgen -a allows + BIND 9 and rndc to be used as + drop-in + replacements for BIND 8 and ndc, + with no changes to the existing BIND 8 + named.conf file. + + + If a more elaborate configuration than that + generated by rndc-confgen -a + is required, for example if rndc is to be used remotely, + you should run rndc-confgen without + the + -a option and set up a + rndc.conf and + named.conf + as directed. + + -b keysize - - - Specifies the size of the authentication key in bits. - Must be between 1 and 512 bits; the default is 128. - - + + + Specifies the size of the authentication key in bits. + Must be between 1 and 512 bits; the default is 128. + + -c keyfile - - - Used with the -a option to specify - an alternate location for rndc.key. - - + + + Used with the -a option to specify + an alternate location for rndc.key. + + -h - - - Prints a short summary of the options and arguments to - rndc-confgen. - - + + + Prints a short summary of the options and arguments to + rndc-confgen. + + -k keyname - - - Specifies the key name of the rndc authentication key. - This must be a valid domain name. - The default is rndc-key. - - + + + Specifies the key name of the rndc authentication key. + This must be a valid domain name. + The default is rndc-key. + + -p port - - - Specifies the command channel port where named - listens for connections from rndc. - The default is 953. - - + + + Specifies the command channel port where named + listens for connections from rndc. + The default is 953. + + -r randomfile - - - Specifies a source of random data for generating the - authorization. If the operating - system does not provide a /dev/random - or equivalent device, the default source of randomness - is keyboard input. randomdev specifies - the name of a character device or file containing random - data to be used instead of the default. The special value - keyboard indicates that keyboard - input should be used. - - + + + Specifies a source of random data for generating the + authorization. If the operating + system does not provide a /dev/random + or equivalent device, the default source of randomness + is keyboard input. randomdev + specifies + the name of a character device or file containing random + data to be used instead of the default. The special value + keyboard indicates that keyboard + input should be used. + + -s address - - - Specifies the IP address where named - listens for command channel connections from - rndc. The default is the loopback - address 127.0.0.1. - - + + + Specifies the IP address where named + listens for command channel connections from + rndc. The default is the loopback + address 127.0.0.1. + + -t chrootdir - - - Used with the -a option to specify - a directory where named will run - chrooted. An additional copy of the rndc.key - will be written relative to this directory so that - it will be found by the chrooted named. - - + + + Used with the -a option to specify + a directory where named will run + chrooted. An additional copy of the rndc.key + will be written relative to this directory so that + it will be found by the chrooted named. + + -u user - - - Used with the -a option to set the owner - of the rndc.key file generated. If - -t is also specified only the file in - the chroot area has its owner changed. - - + + + Used with the -a option to set the + owner + of the rndc.key file generated. + If + -t is also specified only the file + in + the chroot area has its owner changed. + + @@ -221,37 +240,31 @@ EXAMPLES - To allow rndc to be used with - no manual configuration, run + To allow rndc to be used with + no manual configuration, run - - rndc-confgen -a + rndc-confgen -a - To print a sample rndc.conf file and - corresponding controls and key - statements to be manually inserted into named.conf, - run + To print a sample rndc.conf file and + corresponding controls and key + statements to be manually inserted into named.conf, + run - - rndc-confgen + rndc-confgen SEE ALSO - - - rndc - 8 + + rndc8 , - rndc.conf - 5 + rndc.conf5 , - named - 8 + named8 , BIND 9 Administrator Reference Manual. @@ -259,14 +272,11 @@ AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - - - + June 30, 2000 @@ -34,6 +34,19 @@ rndc configuration file + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + rndc.conf @@ -42,176 +55,183 @@ DESCRIPTION - - rndc.conf is the configuration file - for rndc, the BIND 9 name server control - utility. This file has a similar structure and syntax to - named.conf. Statements are enclosed - in braces and terminated with a semi-colon. Clauses in - the statements are also semi-colon terminated. The usual - comment styles are supported: - - - C style: /* */ - - - C++ style: // to end of line - - - Unix style: # to end of line - - - rndc.conf is much simpler than - named.conf. The file uses three - statements: an options statement, a server statement - and a key statement. - - - The statement contains five clauses. - The clause is followed by the - name or address of a name server. This host will be used when - no name server is given as an argument to - rndc. The - clause is followed by the name of a key which is identified by - a statement. If no - is provided on the rndc command line, - and no clause is found in a matching - statement, this default key will be - used to authenticate the server's commands and responses. The - clause is followed by the port - to connect to on the remote name server. If no - option is provided on the rndc command - line, and no clause is found in a - matching statement, this default port - will be used to connect. - The and - clauses which - can be used to set the IPv4 and IPv6 source addresses - respectively. - - - After the keyword, the server - statement includes a string which is the hostname or address - for a name server. The statement has three possible clauses: - , and - . The key name must match the - name of a key statement in the file. The port number - specifies the port to connect to. If an - clause is supplied these addresses will be used instead of - the server name. Each address can take a optional port. - If an or - of supplied then these will be used to specify the IPv4 and IPv6 - source addresses respectively. - - - The statement begins with an identifying - string, the name of the key. The statement has two clauses. - identifies the encryption algorithm - for rndc to use; currently only HMAC-MD5 is - supported. This is followed by a secret clause which contains - the base-64 encoding of the algorithm's encryption key. The - base-64 string is enclosed in double quotes. - - - There are two common ways to generate the base-64 string for the - secret. The BIND 9 program rndc-confgen can - be used to generate a random key, or the - mmencode program, also known as - mimencode, can be used to generate a base-64 - string from known input. mmencode does not - ship with BIND 9 but is available on many systems. See the - EXAMPLE section for sample command lines for each. + rndc.conf is the configuration file + for rndc, the BIND 9 name server control + utility. This file has a similar structure and syntax to + named.conf. Statements are enclosed + in braces and terminated with a semi-colon. Clauses in + the statements are also semi-colon terminated. The usual + comment styles are supported: + + + C style: /* */ + + + C++ style: // to end of line + + + Unix style: # to end of line + + rndc.conf is much simpler than + named.conf. The file uses three + statements: an options statement, a server statement + and a key statement. + + + The statement contains five clauses. + The clause is followed by the + name or address of a name server. This host will be used when + no name server is given as an argument to + rndc. The + clause is followed by the name of a key which is identified by + a statement. If no + is provided on the rndc command line, + and no clause is found in a matching + statement, this default key will be + used to authenticate the server's commands and responses. The + clause is followed by the port + to connect to on the remote name server. If no + option is provided on the rndc command + line, and no clause is found in a + matching statement, this default port + will be used to connect. + The and + clauses which + can be used to set the IPv4 and IPv6 source addresses + respectively. + + + After the keyword, the server + statement includes a string which is the hostname or address + for a name server. The statement has three possible clauses: + , and + . The key name must match the + name of a key statement in the file. The port number + specifies the port to connect to. If an + clause is supplied these addresses will be used instead of + the server name. Each address can take a optional port. + If an or + of supplied then these will be used to specify the IPv4 and IPv6 + source addresses respectively. + + + The statement begins with an identifying + string, the name of the key. The statement has two clauses. + identifies the encryption algorithm + for rndc to use; currently only HMAC-MD5 + is + supported. This is followed by a secret clause which contains + the base-64 encoding of the algorithm's encryption key. The + base-64 string is enclosed in double quotes. + + + There are two common ways to generate the base-64 string for the + secret. The BIND 9 program rndc-confgen + can + be used to generate a random key, or the + mmencode program, also known as + mimencode, can be used to generate a + base-64 + string from known input. mmencode does + not + ship with BIND 9 but is available on many systems. See the + EXAMPLE section for sample command lines for each. EXAMPLE - + options { default-server localhost; default-key samplekey; }; - + + + server localhost { key samplekey; }; - + + + server testserver { key testkey; addresses { localhost port 5353; }; }; - + + + key samplekey { algorithm hmac-md5; secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz"; }; - + + + key testkey { algorithm hmac-md5; secret "R3HI8P6BKw9ZwXwN3VZKuQ=="; } + - In the above example, rndc will by default use - the server at localhost (127.0.0.1) and the key called samplekey. - Commands to the localhost server will use the samplekey key, which - must also be defined in the server's configuration file with the - same name and secret. The key statement indicates that samplekey - uses the HMAC-MD5 algorithm and its secret clause contains the - base-64 encoding of the HMAC-MD5 secret enclosed in double quotes. + In the above example, rndc will by + default use + the server at localhost (127.0.0.1) and the key called samplekey. + Commands to the localhost server will use the samplekey key, which + must also be defined in the server's configuration file with the + same name and secret. The key statement indicates that samplekey + uses the HMAC-MD5 algorithm and its secret clause contains the + base-64 encoding of the HMAC-MD5 secret enclosed in double quotes. - If rndc -s testserver is used then rndc will - connect to server on localhost port 5353 using the key testkey. + If rndc -s testserver is used then rndc will + connect to server on localhost port 5353 using the key testkey. - To generate a random secret with rndc-confgen: + To generate a random secret with rndc-confgen: - - rndc-confgen + rndc-confgen - A complete rndc.conf file, including the - randomly generated key, will be written to the standard - output. Commented out and - statements for - named.conf are also printed. + A complete rndc.conf file, including + the + randomly generated key, will be written to the standard + output. Commented out and + statements for + named.conf are also printed. - To generate a base-64 secret with mmencode: + To generate a base-64 secret with mmencode: - - echo "known plaintext for a secret" | mmencode + echo "known plaintext for a secret" | mmencode NAME SERVER CONFIGURATION - The name server must be configured to accept rndc connections and - to recognize the key specified in the rndc.conf - file, using the controls statement in named.conf. - See the sections on the statement in the - BIND 9 Administrator Reference Manual for details. + The name server must be configured to accept rndc connections and + to recognize the key specified in the rndc.conf + file, using the controls statement in named.conf. + See the sections on the statement in the + BIND 9 Administrator Reference Manual for details. SEE ALSO - - - rndc - 8 + + rndc8 , - rndc-confgen - 8 + rndc-confgen8 , - mmencode - 1 + mmencode1 , BIND 9 Administrator Reference Manual. @@ -219,16 +239,12 @@ AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - diff --git a/bin/rndc/rndc.docbook b/bin/rndc/rndc.docbook index aa6011524c8ee8f13899af5fd6b89f5f603a3650..6de50ecb337595da78f10e569d9852341a770d30 100644 --- a/bin/rndc/rndc.docbook +++ b/bin/rndc/rndc.docbook @@ -1,4 +1,6 @@ - +]> - - - + June 30, 2000 @@ -34,6 +34,19 @@ name server control utility + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + rndc @@ -50,31 +63,31 @@ DESCRIPTION - - rndc controls the operation of a name - server. It supersedes the ndc utility - that was provided in old BIND releases. If - rndc is invoked with no command line - options or arguments, it prints a short summary of the - supported commands and the available options and their - arguments. + rndc + controls the operation of a name + server. It supersedes the ndc utility + that was provided in old BIND releases. If + rndc is invoked with no command line + options or arguments, it prints a short summary of the + supported commands and the available options and their + arguments. - - rndc communicates with the name server - over a TCP connection, sending commands authenticated with - digital signatures. In the current versions of - rndc and named named - the only supported authentication algorithm is HMAC-MD5, - which uses a shared secret on each end of the connection. - This provides TSIG-style authentication for the command - request and the name server's response. All commands sent - over the channel must be signed by a key_id known to the - server. + rndc + communicates with the name server + over a TCP connection, sending commands authenticated with + digital signatures. In the current versions of + rndc and named named + the only supported authentication algorithm is HMAC-MD5, + which uses a shared secret on each end of the connection. + This provides TSIG-style authentication for the command + request and the name server's response. All commands sent + over the channel must be signed by a key_id known to the + server. - - rndc reads a configuration file to - determine how to contact the name server and decide what - algorithm and key it should use. + rndc + reads a configuration file to + determine how to contact the name server and decide what + algorithm and key it should use. @@ -84,96 +97,99 @@ -b source-address - - - Use source-address - as the source address for the connection to the server. - Multiple instances are permitted to allow setting of both - the IPv4 and IPv6 source addresses. - - + + + Use source-address + as the source address for the connection to the server. + Multiple instances are permitted to allow setting of both + the IPv4 and IPv6 source addresses. + + -c config-file - - - Use config-file - as the configuration file instead of the default, - /etc/rndc.conf. - - + + + Use config-file + as the configuration file instead of the default, + /etc/rndc.conf. + + -k key-file - - - Use key-file - as the key file instead of the default, - /etc/rndc.key. The key in - /etc/rndc.key will be used to authenticate - commands sent to the server if the config-file - does not exist. - - + + + Use key-file + as the key file instead of the default, + /etc/rndc.key. The key in + /etc/rndc.key will be used to + authenticate + commands sent to the server if the config-file + does not exist. + + -s server - - - server is - the name or address of the server which matches a - server statement in the configuration file for - rndc. If no server is supplied on the - command line, the host named by the default-server clause - in the option statement of the configuration file will be - used. - - + + server is + the name or address of the server which matches a + server statement in the configuration file for + rndc. If no server is supplied on + the + command line, the host named by the default-server clause + in the option statement of the configuration file will be + used. + + -p port - - - Send commands to TCP port - port instead - of BIND 9's default control channel port, 953. - - + + + Send commands to TCP port + port + instead + of BIND 9's default control channel port, 953. + + -V - - - Enable verbose logging. - - + + + Enable verbose logging. + + -y keyid - - - Use the key keyid - from the configuration file. - keyid must be - known by named with the same algorithm and secret string - in order for control message validation to succeed. - If no keyid - is specified, rndc will first look - for a key clause in the server statement of the server - being used, or if no server statement is present for that - host, then the default-key clause of the options statement. - Note that the configuration file contains shared secrets - which are used to send authenticated control commands - to name servers. It should therefore not have general read - or write access. - - + + + Use the key keyid + from the configuration file. + keyid + must be + known by named with the same algorithm and secret string + in order for control message validation to succeed. + If no keyid + is specified, rndc will first look + for a key clause in the server statement of the server + being used, or if no server statement is present for that + host, then the default-key clause of the options statement. + Note that the configuration file contains shared secrets + which are used to send authenticated control commands + to name servers. It should therefore not have general read + or write access. + + @@ -181,44 +197,40 @@ For the complete set of commands supported by rndc, see the BIND 9 Administrator Reference Manual or run - rndc without arguments to see its help message. + rndc without arguments to see its help + message. LIMITATIONS - - rndc does not yet support all the commands of - the BIND 8 ndc utility. + rndc + does not yet support all the commands of + the BIND 8 ndc utility. - There is currently no way to provide the shared secret for a - without using the configuration file. + There is currently no way to provide the shared secret for a + without using the configuration file. - Several error messages could be clearer. + Several error messages could be clearer. SEE ALSO - - - rndc.conf - 5 + + rndc.conf5 , - named - 8 + named8 , - named.conf - 5 + named.conf5 - ndc - 8 + ndc8 , BIND 9 Administrator Reference Manual. @@ -226,16 +238,12 @@ AUTHOR - - Internet Systems Consortium + Internet Systems Consortium - - - - diff --git a/configure.in b/configure.in index 7cf84a1e5c7c21e8c2afd03a17fa9cfd0db5d906..16f88edba869256d908d2ca6ed012d7b2456c15a 100644 --- a/configure.in +++ b/configure.in @@ -18,7 +18,7 @@ AC_DIVERT_PUSH(1)dnl esyscmd([sed "s/^/# /" COPYRIGHT])dnl AC_DIVERT_POP()dnl -AC_REVISION($Revision: 1.375 $) +AC_REVISION($Revision: 1.376 $) AC_INIT(lib/dns/name.c) AC_PREREQ(2.13) @@ -1836,25 +1836,29 @@ AC_SUBST(ISC_PLATFORM_HAVEIFNAMETOINDEX) # a developer editing the documentation source. # -# Directory trees where SGML files are commonly found. -sgmltrees="/usr/pkg/share/sgml /usr/local/share/sgml /usr/share/sgml" - # -# Look for openjade. Plain jade is no longer supported. +# Look for TeX. # -AC_PATH_PROGS(OPENJADE, openjade, openjade) -AC_SUBST(OPENJADE) +AC_PATH_PROGS(LATEX, latex, latex) +AC_SUBST(LATEX) + +AC_PATH_PROGS(PDFLATEX, pdflatex, pdflatex) +AC_SUBST(PDFLATEX) # -# Look for TeX. +# Look for xsltproc (libxslt) # -AC_PATH_PROGS(JADETEX, jadetex, jadetex) -AC_SUBST(JADETEX) +AC_PATH_PROG(XSLTPROC, xsltproc, xsltproc) +AC_SUBST(XSLTPROC) + +# +# Look for xmllint (libxml2) +# -AC_PATH_PROGS(PDFJADETEX, pdfjadetex, pdfjadetex) -AC_SUBST(PDFJADETEX) +AC_PATH_PROG(XMLLINT, xmllint, xmllint) +AC_SUBST(XMLLINT) # # Subroutine for searching for an ordinary file (e.g., a stylesheet) @@ -1891,74 +1895,60 @@ AC_SUBST($1) ]) # -# Look for the SGML catalog. -# Its location varies, so far we have seen: -# -# NetBSD /usr/pkg/share/sgml/docbook/catalog -# FreeBSD /usr/local/share/sgml/docbook/catalog -# Linux /usr/local/share/dsssl/docbook/catalog -# /usr/share/sgml/docbook/dsssl-stylesheets/catalog +# Look for Docbook-XSL stylesheets. Location probably varies by +# system. Guessing where it might be found, based on where SGML stuff +# lives on some systems. FreeBSD is the only one I'm sure of at the +# moment. # -catalogpath="" -for d in $sgmltrees -do - catalogpath="$catalogpath $d" - for s in docbook/dsssl-stylesheets - do - catalogpath="$catalogpath $d/$s" - done -done -NOM_PATH_FILE(SGMLCATALOG, catalog, $catalogpath) + +docbook_xsl_trees="/usr/pkg/share/xsl /usr/local/share/xsl /usr/share/xsl" # -# Look for the HTML stylesheet html/docbook.dsl, used for -# formatting man pages in HTML. Its location varies, -# so far we have seen: +# Look for stylesheets we need. +# + +NOM_PATH_FILE(XSLT_DOCBOOK_STYLE_HTML, docbook/html/docbook.xsl, $docbook_xsl_trees) +NOM_PATH_FILE(XSLT_DOCBOOK_STYLE_XHTML, docbook/xhtml/docbook.xsl, $docbook_xsl_trees) +NOM_PATH_FILE(XSLT_DOCBOOK_STYLE_MAN, docbook/manpages/docbook.xsl, $docbook_xsl_trees) +NOM_PATH_FILE(XSLT_DOCBOOK_CHUNK_HTML, docbook/html/chunk.xsl, $docbook_xsl_trees) +NOM_PATH_FILE(XSLT_DOCBOOK_CHUNK_XHTML, docbook/xhtml/chunk.xsl, $docbook_xsl_trees) + # -# NetBSD /usr/pkg/share/sgml/docbook/dsssl/modular/ -# FreeBSD /usr/local/share/sgml/docbook/dsssl/modular/ -# Linux /usr/local/share/dsssl/docbook/ -# /usr/share/sgml/docbook/dsssl-stylesheets/ +# Same dance for db2latex # -# Ditto for the print stylesheet print/docbook.dsl. +# No idea where this lives except on FreeBSD. # -stylepath="" -for d in $sgmltrees -do - for s in docbook/dsssl/modular dsssl/docbook docbook/dsssl-stylesheets - do - stylepath="$stylepath $d/$s" - done -done -NOM_PATH_FILE(HTMLSTYLE, html/docbook.dsl, $stylepath) -NOM_PATH_FILE(PRINTSTYLE, print/docbook.dsl, $stylepath) +db2latex_xsl_trees="/usr/local/share" # -# Look for XML declarations. -# Its location varies, so far we have seen: -# -# NetBSD /usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/ -# FreeBSD /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/ -# Linux /usr/local/share/dsssl/docbook/dtds/decls/ -# /usr/share/sgml/docbook/dsssl-stylesheets/dtds/decls/ +# Look for stylesheets we need. # -xmlpath="" -for d in $sgmltrees -do - for s in docbook/dsssl/modular dsssl/docbook docbook/dsssl-stylesheets - do - xmlpath="$xmlpath $d/$s" - done -done -NOM_PATH_FILE(XMLDCL, dtds/decls/xml.dcl, $xmlpath) +NOM_PATH_FILE(XSLT_DB2LATEX_STYLE, db2latex/xsl/docbook.xsl, $db2latex_xsl_trees) # -# Look for docbook2man-spec.pl +# Look for "admonition" image directory. Can't use NOM_PATH_FILE() +# because it's a directory, so just do the same things, inline. # -NOM_PATH_FILE(DOCBOOK2MANSPEC, docbook2X/docbook2man-spec.pl, $sgmltrees) +AC_MSG_CHECKING(for db2latex/xsl/figures) +for d in $db2latex_xsl_trees +do + dd=$d/db2latex/xsl/figures + if test -d $dd + then + XSLT_DB2LATEX_ADMONITIONS=$dd + AC_MSG_RESULT($dd) + break + fi +done +if test "X$XSLT_DB2LATEX_ADMONITIONS" = "X" +then + AC_MSG_RESULT(not found) + XSLT_DB2LATEX_ADMONITIONS=db2latex/xsl/figures +fi +AC_SUBST(XSLT_DB2LATEX_ADMONITIONS) # # Substitutions @@ -2016,6 +2006,20 @@ LIBBIND9_API=$srcdir/lib/bind9/api AC_SUBST_FILE(LIBLWRES_API) LIBLWRES_API=$srcdir/lib/lwres/api +# +# Commands to run at the end of config.status. +# Don't just put these into configure, it won't work right if somebody +# runs config.status directly (which autoconf allows). +# + +AC_CONFIG_COMMANDS( + [chmod], + [chmod a+x isc-config.sh]) + +# +# Do it +# + AC_OUTPUT( make/rules make/includes @@ -2086,14 +2090,13 @@ AC_OUTPUT( bin/dnssec/Makefile doc/Makefile doc/arm/Makefile - doc/arm/nominum-docbook-html.dsl - doc/arm/nominum-docbook-print.dsl - doc/arm/validate.sh doc/misc/Makefile - docutil/docbook2man-wrapper.sh isc-config.sh + doc/xsl/isc-docbook-chunk.xsl + doc/xsl/isc-docbook-html.xsl + doc/xsl/isc-docbook-latex.xsl + doc/xsl/isc-manpage.xsl ) -chmod a+x isc-config.sh # Tell Emacs to edit this file in shell mode. # Local Variables: diff --git a/doc/arm/.cvsignore b/doc/arm/.cvsignore index eff975abfb29dbd5287fdc1a2a0529a9013ee59a..a47eb8f263ecb02c44319fc4eff3c1750d4cf94d 100644 --- a/doc/arm/.cvsignore +++ b/doc/arm/.cvsignore @@ -1,8 +1,9 @@ Makefile -gendvi.sh -genhtml.sh -genpdf.sh -validate.sh -nominum-docbook-html.dsl -nominum-docbook-print.dsl catalog +Bv9ARM.aux +Bv9ARM.brf +Bv9ARM.glo +Bv9ARM.idx +Bv9ARM.log +Bv9ARM.out +Bv9ARM.tex diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index a0b732506ec6c115bd9e57b09ce6c16ad43311c5..54e650d1f747f657eae190c7bcd1605bfdd4f7dc 100644 --- a/doc/arm/Bv9ARM-book.xml +++ b/doc/arm/Bv9ARM-book.xml @@ -1,444 +1,661 @@ - + "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" + []> + + + + + BIND 9 Administrator Reference Manual + + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + 2003 + Internet Software Consortium + + + + + Introduction + + The Internet Domain Name System (DNS) + consists of the syntax + to specify the names of entities in the Internet in a hierarchical + manner, the rules used for delegating authority over names, and the + system implementation that actually maps names to Internet + addresses. DNS data is maintained in a + group of distributed + hierarchical databases. + + + + Scope of Document + + + The Berkeley Internet Name Domain + (BIND) implements an + domain name server for a number of operating systems. This + document provides basic information about the installation and + care of the Internet Software Consortium (ISC) + BIND version 9 software package for + system + administrators. + - + + This version of the manual corresponds to BIND version 9.3. + - -BIND 9 Administrator Reference Manual - - - -2004 -Internet Systems Consortium, Inc. ("ISC") - - -2000-2003 -Internet Software Consortium - - - - - Introduction - The Internet Domain Name System (DNS) consists of the syntax - to specify the names of entities in the Internet in a hierarchical - manner, the rules used for delegating authority over names, and the - system implementation that actually maps names to Internet - addresses. DNS data is maintained in a group of distributed - hierarchical databases. - - - Scope of Document - - The Berkeley Internet Name Domain (BIND) implements an - domain name server for a number of operating systems. This - document provides basic information about the installation and - care of the Internet Software Consortium (ISC) - BIND version 9 software package for system - administrators. - - This version of the manual corresponds to BIND version 9.3. - - - Organization of This Document - In this document, Section 1 introduces - the basic DNS and BIND concepts. Section 2 - describes resource requirements for running BIND in various - environments. Information in Section 3 is - task-oriented in its presentation and is - organized functionally, to aid in the process of installing the - BIND 9 software. The task-oriented section is followed by - Section 4, which contains more advanced - concepts that the system administrator may need for implementing - certain options. Section 5 - describes the BIND 9 lightweight - resolver. The contents of Section 6 are - organized as in a reference manual to aid in the ongoing - maintenance of the software. Section 7 - addresses security considerations, and - Section 8 contains troubleshooting help. The - main body of the document is followed by several - Appendices which contain useful reference - information, such as a Bibliography and - historic information related to BIND and the Domain Name - System. - - Conventions Used in This Document - - In this document, we use the following general typographic - conventions: - - - - - + + + Organization of This Document + + In this document, Section 1 introduces + the basic DNS and BIND concepts. Section 2 + describes resource requirements for running BIND in various + environments. Information in Section 3 is + task-oriented in its presentation and is + organized functionally, to aid in the process of installing the + BIND 9 software. The task-oriented + section is followed by + Section 4, which contains more advanced + concepts that the system administrator may need for implementing + certain options. Section 5 + describes the BIND 9 lightweight + resolver. The contents of Section 6 are + organized as in a reference manual to aid in the ongoing + maintenance of the software. Section 7 addresses + security considerations, and + Section 8 contains troubleshooting help. The + main body of the document is followed by several + Appendices which contain useful reference + information, such as a Bibliography and + historic information related to BIND + and the Domain Name + System. + + + + Conventions Used in This Document + + + In this document, we use the following general typographic + conventions: + + + + + + - -To -describe: - -We use the style: + + + To describe: + + + + + We use the style: + + - -a pathname, filename, URL, hostname, -mailing list name, or new term or concept - Fixed width + + + a pathname, filename, URL, hostname, + mailing list name, or new term or concept + + + + + Fixed width + + - literal user -input - Fixed Width Bold + + + literal user + input + + + + + Fixed Width Bold + + - program output - Fixed Width + + + program output + + + + + Fixed Width + + - - - The following conventions are used in descriptions of the -BIND configuration file: - - - - - - To -describe: - We use the style: - - - keywords - Fixed Width - - - variables - Fixed Width - - -Optional input - Text is enclosed in square brackets - - - -The Domain Name System (<acronym>DNS</acronym>) -The purpose of this document is to explain the installation -and upkeep of the BIND software package, and we -begin by reviewing the fundamentals of the Domain Name System -(DNS) as they relate to BIND. - - - -DNS Fundamentals - -The Domain Name System (DNS) is the hierarchical, distributed -database. It stores information for mapping Internet host names to IP -addresses and vice versa, mail routing information, and other data -used by Internet applications. - -Clients look up information in the DNS by calling a -resolver library, which sends queries to one or -more name servers and interprets the responses. -The BIND 9 software distribution contains a -name server, named, and two resolver -libraries, liblwres and libbind. - - - -Domains and Domain Names - -The data stored in the DNS is identified by domain -names that are organized as a tree according to -organizational or administrative boundaries. Each node of the tree, -called a domain, is given a label. The domain name of the -node is the concatenation of all the labels on the path from the -node to the root node. This is represented -in written form as a string of labels listed from right to left and -separated by dots. A label need only be unique within its parent -domain. - -For example, a domain name for a host at the -company Example, Inc. could be -mail.example.com, -where com is the -top level domain to which -ourhost.example.com belongs, -example is -a subdomain of com, and -ourhost is the -name of the host. - -For administrative purposes, the name space is partitioned into -areas called zones, each starting at a node and -extending down to the leaf nodes or to nodes where other zones start. -The data for each zone is stored in a name -server, which answers queries about the zone using the -DNS protocol. - - -The data associated with each domain name is stored in the -form of resource records (RRs). -Some of the supported resource record types are described in -. - -For more detailed information about the design of the DNS and -the DNS protocol, please refer to the standards documents listed in -. - - -Zones -To properly operate a name server, it is important to understand -the difference between a zone -and a domain. - -As we stated previously, a zone is a point of delegation in -the DNS tree. A zone consists of -those contiguous parts of the domain -tree for which a name server has complete information and over which -it has authority. It contains all domain names from a certain point -downward in the domain tree except those which are delegated to -other zones. A delegation point is marked by one or more -NS records in the -parent zone, which should be matched by equivalent NS records at -the root of the delegated zone. - -For instance, consider the example.com -domain which includes names -such as host.aaa.example.com and -host.bbb.example.com even though -the example.com zone includes -only delegations for the aaa.example.com and -bbb.example.com zones. A zone can map -exactly to a single domain, but could also include only part of a -domain, the rest of which could be delegated to other -name servers. Every name in the DNS tree is a -domain, even if it is -terminal, that is, has no -subdomains. Every subdomain is a domain and -every domain except the root is also a subdomain. The terminology is -not intuitive and we suggest that you read RFCs 1033, 1034 and 1035 to -gain a complete understanding of this difficult and subtle -topic. - -Though BIND is called a "domain name server", -it deals primarily in terms of zones. The master and slave -declarations in the named.conf file specify -zones, not domains. When you ask some other site if it is willing to -be a slave server for your domain, you are -actually asking for slave service for some collection of zones. - - -Authoritative Name Servers - -Each zone is served by at least -one authoritative name server, -which contains the complete data for the zone. -To make the DNS tolerant of server and network failures, -most zones have two or more authoritative servers. - - -Responses from authoritative servers have the "authoritative -answer" (AA) bit set in the response packets. This makes them -easy to identify when debugging DNS configurations using tools like -dig (). - -The Primary Master - - -The authoritative server where the master copy of the zone data is maintained is -called the primary master server, or simply the -primary. It loads the zone contents from some -local file edited by humans or perhaps generated mechanically from -some other local file which is edited by humans. This file is called -the zone file or master file. - - -Slave Servers -The other authoritative servers, the slave -servers (also known as secondary servers) load -the zone contents from another server using a replication process -known as a zone transfer. Typically the data are -transferred directly from the primary master, but it is also possible -to transfer it from another slave. In other words, a slave server -may itself act as a master to a subordinate slave server. - - -Stealth Servers - -Usually all of the zone's authoritative servers are listed in -NS records in the parent zone. These NS records constitute -a delegation of the zone from the parent. -The authoritative servers are also listed in the zone file itself, -at the top level or apex -of the zone. You can list servers in the zone's top-level NS -records that are not in the parent's NS delegation, but you cannot -list servers in the parent's delegation that are not present at -the zone's top level. - -A stealth server is a server that is -authoritative for a zone but is not listed in that zone's NS -records. Stealth servers can be used for keeping a local copy of a -zone to speed up access to the zone's records or to make sure that the -zone is available even if all the "official" servers for the zone are -inaccessible. - -A configuration where the primary master server itself is a -stealth server is often referred to as a "hidden primary" -configuration. One use for this configuration is when the primary master -is behind a firewall and therefore unable to communicate directly -with the outside world. - - - - - - -Caching Name Servers - -The resolver libraries provided by most operating systems are -stub resolvers, meaning that they are not capable of -performing the full DNS resolution process by themselves by talking -directly to the authoritative servers. Instead, they rely on a local -name server to perform the resolution on their behalf. Such a server -is called a recursive name server; it performs -recursive lookups for local clients. - -To improve performance, recursive servers cache the results of -the lookups they perform. Since the processes of recursion and -caching are intimately connected, the terms -recursive server and -caching server are often used synonymously. - -The length of time for which a record may be retained in -in the cache of a caching name server is controlled by the -Time To Live (TTL) field associated with each resource record. - - -Forwarding - -Even a caching name server does not necessarily perform -the complete recursive lookup itself. Instead, it can -forward some or all of the queries -that it cannot satisfy from its cache to another caching name server, -commonly referred to as a forwarder. - - -There may be one or more forwarders, -and they are queried in turn until the list is exhausted or an answer -is found. Forwarders are typically used when you do not -wish all the servers at a given site to interact directly with the rest of -the Internet servers. A typical scenario would involve a number -of internal DNS servers and an Internet firewall. Servers unable -to pass packets through the firewall would forward to the server -that can do it, and that server would query the Internet DNS servers -on the internal server's behalf. An added benefit of using the forwarding -feature is that the central machine develops a much more complete -cache of information that all the clients can take advantage -of. - - - - -Name Servers in Multiple Roles - -The BIND name server can simultaneously act as -a master for some zones, a slave for other zones, and as a caching -(recursive) server for a set of local clients. - -However, since the functions of authoritative name service -and caching/recursive name service are logically separate, it is -often advantageous to run them on separate server machines. - -A server that only provides authoritative name service -(an authoritative-only server) can run with -recursion disabled, improving reliability and security. - -A server that is not authoritative for any zones and only provides -recursive service to local -clients (a caching-only server) -does not need to be reachable from the Internet at large and can -be placed inside a firewall. - - - - - - -<acronym>BIND</acronym> Resource Requirements - - -Hardware requirements - -DNS hardware requirements have traditionally been quite modest. -For many installations, servers that have been pensioned off from -active duty have performed admirably as DNS servers. -The DNSSEC and IPv6 features of BIND 9 may prove to be quite -CPU intensive however, so organizations that make heavy use of these -features may wish to consider larger systems for these applications. -BIND 9 is fully multithreaded, allowing full utilization of -multiprocessor systems for installations that need it. -CPU Requirements -CPU requirements for BIND 9 range from i486-class machines -for serving of static zones without caching, to enterprise-class -machines if you intend to process many dynamic updates and DNSSEC -signed zones, serving many thousands of queries per second. - -Memory Requirements -The memory of the server has to be large enough to fit the -cache and zones loaded off disk. The max-cache-size -option can be used to limit the amount of memory used by the cache, -at the expense of reducing cache hit rates and causing more DNS -traffic. -Additionally, if additional section caching -() is enabled, -the max-acache-size can be used to limit the amount -of memory used by the mechanism. -It is still good practice to have enough memory to load -all zone and cache data into memory — unfortunately, the best way -to determine this for a given installation is to watch the name server -in operation. After a few weeks the server process should reach -a relatively stable size where entries are expiring from the cache as -fast as they are being inserted. - -Name Server Intensive Environment Issues -For name server intensive environments, there are two alternative -configurations that may be used. The first is where clients and -any second-level internal name servers query a main name server, which -has enough memory to build a large cache. This approach minimizes -the bandwidth used by external name lookups. The second alternative -is to set up second-level internal name servers to make queries independently. -In this configuration, none of the individual machines needs to -have as much memory or CPU power as in the first alternative, but -this has the disadvantage of making many more external queries, -as none of the name servers share their cached data. - -Supported Operating Systems -ISC BIND 9 compiles and runs on a large number -of Unix-like operating system and on Windows NT / 2000. For an up-to-date -list of supported systems, see the README file in the top level directory -of the BIND 9 source distribution. - - - - -Name Server Configuration -In this section we provide some suggested configurations along -with guidelines for their use. We also address the topic of reasonable -option setting. - - -Sample Configurations - -A Caching-only Name Server -The following sample configuration is appropriate for a caching-only -name server for use by clients internal to a corporation. All queries -from outside clients are refused using the allow-query -option. Alternatively, the same effect could be achieved using suitable -firewall rules. + + + + The following conventions are used in descriptions of the + BIND configuration file: + + + + + + + + To describe: + + + + + We use the style: + + + + + + + keywords + + + + + Fixed Width + + + + + + + variables + + + + + Fixed Width + + + + + + + Optional input + + + + + Text is enclosed in square brackets + + + + + + + + + + The Domain Name System (<acronym>DNS</acronym>) + + The purpose of this document is to explain the installation + and upkeep of the BIND software + package, and we + begin by reviewing the fundamentals of the Domain Name System + (DNS) as they relate to BIND. + + + + DNS Fundamentals + + + The Domain Name System (DNS) is the hierarchical, distributed + database. It stores information for mapping Internet host names to + IP + addresses and vice versa, mail routing information, and other data + used by Internet applications. + + + + Clients look up information in the DNS by calling a + resolver library, which sends queries to one or + more name servers and interprets the responses. + The BIND 9 software distribution + contains a + name server, named, and two resolver + libraries, liblwres and libbind. + + + + Domains and Domain Names + + + The data stored in the DNS is identified by domain names that are organized as a tree according to + organizational or administrative boundaries. Each node of the tree, + called a domain, is given a label. The domain + name of the + node is the concatenation of all the labels on the path from the + node to the root node. This is represented + in written form as a string of labels listed from right to left and + separated by dots. A label need only be unique within its parent + domain. + + + + For example, a domain name for a host at the + company Example, Inc. could be + mail.example.com, + where com is the + top level domain to which + ourhost.example.com belongs, + example is + a subdomain of com, and + ourhost is the + name of the host. + + + + For administrative purposes, the name space is partitioned into + areas called zones, each starting at a node and + extending down to the leaf nodes or to nodes where other zones + start. + The data for each zone is stored in a name server, which answers queries about the zone using the + DNS protocol. + + + + The data associated with each domain name is stored in the + form of resource records (RRs). + Some of the supported resource record types are described in + . + + + + For more detailed information about the design of the DNS and + the DNS protocol, please refer to the standards documents listed in + . + + + + + Zones + + To properly operate a name server, it is important to understand + the difference between a zone + and a domain. + + + + As we stated previously, a zone is a point of delegation in + the DNS tree. A zone consists of + those contiguous parts of the domain + tree for which a name server has complete information and over which + it has authority. It contains all domain names from a certain point + downward in the domain tree except those which are delegated to + other zones. A delegation point is marked by one or more + NS records in the + parent zone, which should be matched by equivalent NS records at + the root of the delegated zone. + + + + For instance, consider the example.com + domain which includes names + such as host.aaa.example.com and + host.bbb.example.com even though + the example.com zone includes + only delegations for the aaa.example.com and + bbb.example.com zones. A zone can + map + exactly to a single domain, but could also include only part of a + domain, the rest of which could be delegated to other + name servers. Every name in the DNS + tree is a + domain, even if it is + terminal, that is, has no + subdomains. Every subdomain is a domain and + every domain except the root is also a subdomain. The terminology is + not intuitive and we suggest that you read RFCs 1033, 1034 and 1035 + to + gain a complete understanding of this difficult and subtle + topic. + + + + Though BIND is called a "domain name + server", + it deals primarily in terms of zones. The master and slave + declarations in the named.conf file + specify + zones, not domains. When you ask some other site if it is willing to + be a slave server for your domain, you are + actually asking for slave service for some collection of zones. + + + + + Authoritative Name Servers + + + Each zone is served by at least + one authoritative name server, + which contains the complete data for the zone. + To make the DNS tolerant of server and network failures, + most zones have two or more authoritative servers. + + + + Responses from authoritative servers have the "authoritative + answer" (AA) bit set in the response packets. This makes them + easy to identify when debugging DNS configurations using tools like + dig (). + + + + The Primary Master + + + The authoritative server where the master copy of the zone data is + maintained is + called the primary master server, or simply + the + primary. It loads the zone contents from + some + local file edited by humans or perhaps generated mechanically from + some other local file which is edited by humans. This file is + called + the zone file or master file. + + + + + Slave Servers + + The other authoritative servers, the slave + servers (also known as secondary servers) + load + the zone contents from another server using a replication process + known as a zone transfer. Typically the data + are + transferred directly from the primary master, but it is also + possible + to transfer it from another slave. In other words, a slave server + may itself act as a master to a subordinate slave server. + + + + + Stealth Servers + + + Usually all of the zone's authoritative servers are listed in + NS records in the parent zone. These NS records constitute + a delegation of the zone from the parent. + The authoritative servers are also listed in the zone file itself, + at the top level or apex + of the zone. You can list servers in the zone's top-level NS + records that are not in the parent's NS delegation, but you cannot + list servers in the parent's delegation that are not present at + the zone's top level. + + + + A stealth server is a server that is + authoritative for a zone but is not listed in that zone's NS + records. Stealth servers can be used for keeping a local copy of + a + zone to speed up access to the zone's records or to make sure that + the + zone is available even if all the "official" servers for the zone + are + inaccessible. + + + + A configuration where the primary master server itself is a + stealth server is often referred to as a "hidden primary" + configuration. One use for this configuration is when the primary + master + is behind a firewall and therefore unable to communicate directly + with the outside world. + + + + + + + + Caching Name Servers + + + The resolver libraries provided by most operating systems are + stub resolvers, meaning that they are not + capable of + performing the full DNS resolution process by themselves by talking + directly to the authoritative servers. Instead, they rely on a + local + name server to perform the resolution on their behalf. Such a + server + is called a recursive name server; it performs + recursive lookups for local clients. + + + + To improve performance, recursive servers cache the results of + the lookups they perform. Since the processes of recursion and + caching are intimately connected, the terms + recursive server and + caching server are often used synonymously. + + + + The length of time for which a record may be retained in + in the cache of a caching name server is controlled by the + Time To Live (TTL) field associated with each resource record. + + + + Forwarding + + + Even a caching name server does not necessarily perform + the complete recursive lookup itself. Instead, it can + forward some or all of the queries + that it cannot satisfy from its cache to another caching name + server, + commonly referred to as a forwarder. + + + + There may be one or more forwarders, + and they are queried in turn until the list is exhausted or an + answer + is found. Forwarders are typically used when you do not + wish all the servers at a given site to interact directly with the + rest of + the Internet servers. A typical scenario would involve a number + of internal DNS servers and an + Internet firewall. Servers unable + to pass packets through the firewall would forward to the server + that can do it, and that server would query the Internet DNS servers + on the internal server's behalf. An added benefit of using the + forwarding + feature is that the central machine develops a much more complete + cache of information that all the clients can take advantage + of. + + + + + + + Name Servers in Multiple Roles + + + The BIND name server can + simultaneously act as + a master for some zones, a slave for other zones, and as a caching + (recursive) server for a set of local clients. + + + + However, since the functions of authoritative name service + and caching/recursive name service are logically separate, it is + often advantageous to run them on separate server machines. + + A server that only provides authoritative name service + (an authoritative-only server) can run with + recursion disabled, improving reliability and security. + + A server that is not authoritative for any zones and only provides + recursive service to local + clients (a caching-only server) + does not need to be reachable from the Internet at large and can + be placed inside a firewall. + + + + + + + + + <acronym>BIND</acronym> Resource Requirements + + + Hardware requirements + + + DNS hardware requirements have + traditionally been quite modest. + For many installations, servers that have been pensioned off from + active duty have performed admirably as DNS servers. + + + The DNSSEC and IPv6 features of BIND 9 + may prove to be quite + CPU intensive however, so organizations that make heavy use of these + features may wish to consider larger systems for these applications. + BIND 9 is fully multithreaded, allowing + full utilization of + multiprocessor systems for installations that need it. + + + + CPU Requirements + + CPU requirements for BIND 9 range from + i486-class machines + for serving of static zones without caching, to enterprise-class + machines if you intend to process many dynamic updates and DNSSEC + signed zones, serving many thousands of queries per second. + + + + + Memory Requirements + + The memory of the server has to be large enough to fit the + cache and zones loaded off disk. The max-cache-size + option can be used to limit the amount of memory used by the cache, + at the expense of reducing cache hit rates and causing more DNS + traffic. + Additionally, if additional section caching + () is enabled, + the max-acache-size can be used to + limit the amount + of memory used by the mechanism. + It is still good practice to have enough memory to load + all zone and cache data into memory — unfortunately, the best + way + to determine this for a given installation is to watch the name server + in operation. After a few weeks the server process should reach + a relatively stable size where entries are expiring from the cache as + fast as they are being inserted. + + + + + Name Server Intensive Environment Issues + + For name server intensive environments, there are two alternative + configurations that may be used. The first is where clients and + any second-level internal name servers query a main name server, which + has enough memory to build a large cache. This approach minimizes + the bandwidth used by external name lookups. The second alternative + is to set up second-level internal name servers to make queries + independently. + In this configuration, none of the individual machines needs to + have as much memory or CPU power as in the first alternative, but + this has the disadvantage of making many more external queries, + as none of the name servers share their cached data. + + + + + Supported Operating Systems + + ISC BIND 9 compiles and runs on a large + number + of Unix-like operating system and on Windows NT / 2000. For an + up-to-date + list of supported systems, see the README file in the top level + directory + of the BIND 9 source distribution. + + + + + + Name Server Configuration + + In this section we provide some suggested configurations along + with guidelines for their use. We also address the topic of reasonable + option setting. + + + + Sample Configurations + + A Caching-only Name Server + + The following sample configuration is appropriate for a caching-only + name server for use by clients internal to a corporation. All + queries + from outside clients are refused using the allow-query + option. Alternatively, the same effect could be achieved using + suitable + firewall rules. + // Two corporate subnets we wish to allow queries from. @@ -454,13 +671,16 @@ zone "0.0.127.in-addr.arpa" { notify no; }; - - -An Authoritative-only Name Server -This sample configuration is for an authoritative-only server -that is the master server for "example.com" -and a slave for the subdomain "eng.example.com". + + + + An Authoritative-only Name Server + + This sample configuration is for an authoritative-only server + that is the master server for "example.com" + and a slave for the subdomain "eng.example.com". + options { @@ -494,418 +714,748 @@ zone "eng.example.com" { masters { 192.168.4.12; }; }; - - - - -Load Balancing - -A primitive form of load balancing can be achieved in -the DNS by using multiple A records for one name. - -For example, if you have three WWW servers with network addresses -of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the -following means that clients will connect to each machine one third -of the time: - - - - - - - - - - -Name -TTL -CLASS -TYPE -Resource Record (RR) Data - - -www -600 -IN -A -10.0.0.1 - - - -600 -IN -A -10.0.0.2 - - - -600 -IN -A -10.0.0.3 - - - - - When a resolver queries for these records, BIND will rotate - them and respond to the query with the records in a different - order. In the example above, clients will randomly receive - records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients - will use the first record returned and discard the rest. - For more detail on ordering responses, check the - rrset-order substatement in the - options statement, see - . - This substatement is not supported in - BIND 9, and only the ordering scheme described above is - available. - - - - -Name Server Operations - - -Tools for Use With the Name Server Daemon -There are several indispensable diagnostic, administrative -and monitoring tools available to the system administrator for controlling -and debugging the name server daemon. We describe several in this -section - -Diagnostic Tools -The dig, host, and -nslookup programs are all command line tools -for manually querying name servers. They differ in style and -output format. - - - - -dig - -The domain information groper (dig) -is the most versatile and complete of these lookup tools. -It has two modes: simple interactive -mode for a single query, and batch mode which executes a query for -each in a list of several query lines. All query options are accessible -from the command line. - - dig - @server - domain - query-type - query-class - +query-option - -dig-option - %comment - -The usual simple use of dig will take the form -dig @server domain query-type query-class -For more information and a list of available commands and -options, see the dig man page. - - - - -host - -The host utility emphasizes simplicity -and ease of use. By default, it converts -between host names and Internet addresses, but its functionality -can be extended with the use of options. - - host - -aCdlrTwv - -c class - -N ndots - -t type - -W timeout - -R retries - hostname - server - -For more information and a list of available commands and -options, see the host man page. - - - - -nslookup - -nslookup has two modes: interactive -and non-interactive. Interactive mode allows the user to query name servers -for information about various hosts and domains or to print a list -of hosts in a domain. Non-interactive mode is used to print just -the name and requested information for a host or domain. - - nslookup - -option - - host-to-find - - server - - -Interactive mode is entered when no arguments are given (the -default name server will be used) or when the first argument is a -hyphen (`-') and the second argument is the host name or Internet address -of a name server. -Non-interactive mode is used when the name or Internet address -of the host to be looked up is given as the first argument. The -optional second argument specifies the host name or address of a name server. -Due to its arcane user interface and frequently inconsistent -behavior, we do not recommend the use of nslookup. -Use dig instead. - - - - - - - - Administrative Tools - Administrative tools play an integral part in the management -of a server. - - - named-checkconf - - The named-checkconf program - checks the syntax of a named.conf file. - - named-checkconf - -jvz - -t directory - filename - - - - - named-checkzone - - The named-checkzone program checks a master file for - syntax and consistency. - - named-checkzone - -djqvD - -c class - -o output - -t directory - -w directory - -k (ignore|warn|fail) - -n (ignore|warn|fail) - -W (ignore|warn) - zone - filename - - - - - rndc - - The remote name daemon control - (rndc) program allows the system - administrator to control the operation of a name server. - If you run rndc without any options - it will display a usage message as follows: - - rndc - -c config - -s server - -p port - -y key - command - command - - command is one of the following: - - - - reload - Reload configuration file and zones. - - - reload zone - class - view - Reload the given zone. - - refresh zone - class + + + + + Load Balancing + + + A primitive form of load balancing can be achieved in + the DNS by using multiple A records for + one name. + + + + For example, if you have three WWW servers with network addresses + of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the + following means that clients will connect to each machine one third + of the time: + + + + + + + + + + + + + + Name + + + + + TTL + + + + + CLASS + + + + + TYPE + + + + + Resource Record (RR) Data + + + + + + + www + + + + + 600 + + + + + IN + + + + + A + + + + + 10.0.0.1 + + + + + + + + + + 600 + + + + + IN + + + + + A + + + + + 10.0.0.2 + + + + + + + + + + 600 + + + + + IN + + + + + A + + + + + 10.0.0.3 + + + + + + + + When a resolver queries for these records, BIND will rotate + them and respond to the query with the records in a different + order. In the example above, clients will randomly receive + records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients + will use the first record returned and discard the rest. + + + For more detail on ordering responses, check the + rrset-order substatement in the + options statement, see + . + This substatement is not supported in + BIND 9, and only the ordering scheme + described above is + available. + + + + + + Name Server Operations + + + Tools for Use With the Name Server Daemon + + There are several indispensable diagnostic, administrative + and monitoring tools available to the system administrator for + controlling + and debugging the name server daemon. We describe several in this + section + + + Diagnostic Tools + + The dig, host, and + nslookup programs are all command + line tools + for manually querying name servers. They differ in style and + output format. + + + + + dig + + + The domain information groper (dig) + is the most versatile and complete of these lookup tools. + It has two modes: simple interactive + mode for a single query, and batch mode which executes a + query for + each in a list of several query lines. All query options are + accessible + from the command line. + + + dig + @server + domain + query-type + query-class + +query-option + -dig-option + %comment + + + The usual simple use of dig will take the form + + + dig @server domain query-type query-class + + + For more information and a list of available commands and + options, see the dig man + page. + + + + + + host + + + The host utility emphasizes + simplicity + and ease of use. By default, it converts + between host names and Internet addresses, but its + functionality + can be extended with the use of options. + + + host + -aCdlrTwv + -c class + -N ndots + -t type + -W timeout + -R retries + hostname + server + + + For more information and a list of available commands and + options, see the host man + page. + + + + + + nslookup + + nslookup + has two modes: interactive and + non-interactive. Interactive mode allows the user to + query name servers for information about various + hosts and domains or to print a list of hosts in a + domain. Non-interactive mode is used to print just + the name and requested information for a host or + domain. + + + nslookup + -option + + host-to-find + - server + + + + Interactive mode is entered when no arguments are given (the + default name server will be used) or when the first argument + is a + hyphen (`-') and the second argument is the host name or + Internet address + of a name server. + + + Non-interactive mode is used when the name or Internet + address + of the host to be looked up is given as the first argument. + The + optional second argument specifies the host name or address + of a name server. + + + Due to its arcane user interface and frequently inconsistent + behavior, we do not recommend the use of nslookup. + Use dig instead. + + + + + + + + + Administrative Tools + + Administrative tools play an integral part in the management + of a server. + + + + + named-checkconf + + + The named-checkconf program + checks the syntax of a named.conf file. + + + named-checkconf + -jvz + -t directory + filename + + + + + + named-checkzone + + + The named-checkzone program + checks a master file for + syntax and consistency. + + + named-checkzone + -djqvD + -c class + -o output + -t directory + -w directory + -k (ignore|warn|fail) + -n (ignore|warn|fail) + -W (ignore|warn) + zone + filename + + + + + + rndc + + + The remote name daemon control + (rndc) program allows the + system + administrator to control the operation of a name server. + If you run rndc without any + options + it will display a usage message as follows: + + + rndc + -c config + -s server + -p port + -y key + command + command + + command + is one of the following: + + + + + + reload + + + Reload configuration file and zones. + + + + + + reload zone + class view - Schedule zone maintenance for the given zone. - + + + Reload the given zone. + + + + + + refresh zone + class + view + + + Schedule zone maintenance for the given zone. + + + - retransfer zone - class + + retransfer zone + + class view - Retransfer the given zone from the master. - + + + Retransfer the given zone from the master. + + + + + - freeze zone + freeze + zone class view - Suspend updates to a dynamic zone. If no zone is specified - then all zones are suspended. This allows manual - edits to be made to a zone normally updated by dynamic update. It - also causes changes in the journal file to be synced into the master - and the journal file to be removed. All dynamic update attempts will - be refused while the zone is frozen. - - - thaw zone + + + Suspend updates to a dynamic zone. If no zone is + specified + then all zones are suspended. This allows manual + edits to be made to a zone normally updated by dynamic + update. It + also causes changes in the journal file to be synced + into the master + and the journal file to be removed. All dynamic + update attempts will + be refused while the zone is frozen. + + + + + + thaw + zone class view - Enable updates to a frozen dynamic zone. If no zone is - specified then all frozen zones are enabled. This causes - the server to reload the zone from disk, and re-enables dynamic updates - after the load has completed. After a zone is thawed, dynamic updates - will no longer be refused. - - - notify zone - class + + + Enable updates to a frozen dynamic zone. If no zone + is + specified then all frozen zones are enabled. This + causes + the server to reload the zone from disk, and + re-enables dynamic updates + after the load has completed. After a zone is thawed, + dynamic updates + will no longer be refused. + + + + + + notify zone + class view - Resend NOTIFY messages for the zone - - reconfig - Reload the configuration file and load new zones, - but do not reload existing zone files even if they have changed. - This is faster than a full reload when there - is a large number of zones because it avoids the need to examine the - modification times of the zones files. - - - - stats - Write server statistics to the statistics file. - - - querylog - Toggle query logging. Query logging can also be enabled - by explicitly directing the queries - category to a channel in the - logging section of - named.conf. - - dumpdb -all|-cache|-zone view ... - Dump the server's caches (default) and / or zones to the - dump file for the specified views. If no view is specified all - views are dumped. - - stop -p - Stop the server, making sure any recent changes - made through dynamic update or IXFR are first saved to the master files - of the updated zones. If -p is specified named's process id is returned. - - halt -p - Stop the server immediately. Recent changes - made through dynamic update or IXFR are not saved to the master files, - but will be rolled forward from the journal files when the server - is restarted. If -p is specified named's process id is returned. - - trace - Increment the servers debugging level by one. - - trace level - Sets the server's debugging level to an explicit - value. - - notrace - Sets the server's debugging level to 0. - - flush - Flushes the server's cache. - - flushname name - Flushes the given name from the server's cache. - - status - Display status of the server. -Note the number of zones includes the internal bind/CH zone -and the default ./IN hint zone if there is not a -explicit root zone configured. - - recursing - Dump the list of queries named is currently recursing - on. - - - - -In BIND 9.2, rndc -supports all the commands of the BIND 8 ndc -utility except ndc start and -ndc restart, which were also -not supported in ndc's channel mode. - -A configuration file is required, since all -communication with the server is authenticated with -digital signatures that rely on a shared secret, and -there is no way to provide that secret other than with a -configuration file. The default location for the -rndc configuration file is -/etc/rndc.conf, but an alternate -location can be specified with the -option. If the configuration file is not found, -rndc will also look in -/etc/rndc.key (or whatever -sysconfdir was defined when -the BIND build was configured). -The rndc.key file is generated by -running rndc-confgen -a as described in -. - -The format of the configuration file is similar to -that of named.conf, but limited to -only four statements, the options, -key, server and -include -statements. These statements are what associate the -secret keys to the servers with which they are meant to -be shared. The order of statements is not -significant. - -The options statement has three clauses: -default-server, default-key, -and default-port. -default-server takes a -host name or address argument and represents the server that will -be contacted if no -option is provided on the command line. -default-key takes -the name of a key as its argument, as defined by a key statement. -default-port specifies the port to which -rndc should connect if no -port is given on the command line or in a -server statement. - -The key statement defines an key to be used -by rndc when authenticating with -named. Its syntax is identical to the -key statement in named.conf. -The keyword key is -followed by a key name, which must be a valid -domain name, though it need not actually be hierarchical; thus, -a string like "rndc_key" is a valid name. -The key statement has two clauses: -algorithm and secret. -While the configuration parser will accept any string as the argument -to algorithm, currently only the string "hmac-md5" -has any meaning. The secret is a base-64 encoded string. - -The server statement associates a key -defined using the key statement with a server. -The keyword server is followed by a -host name or address. The server statement -has two clauses: key and port. -The key clause specifies the name of the key -to be used when communicating with this server, and the -port clause can be used to -specify the port rndc should connect -to on the server. - -A sample minimal configuration file is as follows: + + + Resend NOTIFY messages for the zone + + + + + + reconfig + + + Reload the configuration file and load new zones, + but do not reload existing zone files even if they + have changed. + This is faster than a full reload when there + is a large number of zones because it avoids the need + to examine the + modification times of the zones files. + + + + + + stats + + + Write server statistics to the statistics file. + + + + + + querylog + + + Toggle query logging. Query logging can also be + enabled + by explicitly directing the queries + category to a channel in the + logging section of + named.conf. + + + + + + dumpdb + -all|-cache|-zone + view ... + + + Dump the server's caches (default) and / or zones to + the + dump file for the specified views. If no view is + specified all + views are dumped. + + + + + + stop -p + + + Stop the server, making sure any recent changes + made through dynamic update or IXFR are first saved to + the master files + of the updated zones. If -p is specified named's + process id is returned. + + + + + + halt -p + + + Stop the server immediately. Recent changes + made through dynamic update or IXFR are not saved to + the master files, + but will be rolled forward from the journal files when + the server + is restarted. If -p is specified named's process id + is returned. + + + + + + trace + + + Increment the servers debugging level by one. + + + + + + trace level + + + Sets the server's debugging level to an explicit + value. + + + + + + notrace + + + Sets the server's debugging level to 0. + + + + + + flush + + + Flushes the server's cache. + + + + + + flushname name + + + Flushes the given name from the server's cache. + + + + + + flushname name + + + Flushes the given name from the server's cache. + + + + + + status + + + Display status of the server. + Note the number of zones includes the internal bind/CH zone + and the default ./IN + hint zone if there is not a + explicit root zone configured. + + + + + + recursing + + + Dump the list of queries named is currently recursing + on. + + + + + + recursing + + + Dump the list of queries named is currently recursing + on. + + + + + + + + In BIND 9.2, rndc + supports all the commands of the BIND 8 ndc + utility except ndc start and + ndc restart, which were also + not supported in ndc's + channel mode. + + + + A configuration file is required, since all + communication with the server is authenticated with + digital signatures that rely on a shared secret, and + there is no way to provide that secret other than with a + configuration file. The default location for the + rndc configuration file is + /etc/rndc.conf, but an + alternate + location can be specified with the + option. If the configuration file is not found, + rndc will also look in + /etc/rndc.key (or whatever + sysconfdir was defined when + the BIND build was + configured). + The rndc.key file is + generated by + running rndc-confgen -a as + described in + . + + + + The format of the configuration file is similar to + that of named.conf, but + limited to + only four statements, the options, + key, server and + include + statements. These statements are what associate the + secret keys to the servers with which they are meant to + be shared. The order of statements is not + significant. + + + + The options statement has + three clauses: + default-server, default-key, + and default-port. + default-server takes a + host name or address argument and represents the server + that will + be contacted if no + option is provided on the command line. + default-key takes + the name of a key as its argument, as defined by a key statement. + default-port specifies the + port to which + rndc should connect if no + port is given on the command line or in a + server statement. + + + + The key statement defines an + key to be used + by rndc when authenticating + with + named. Its syntax is + identical to the + key statement in named.conf. + The keyword key is + followed by a key name, which must be a valid + domain name, though it need not actually be hierarchical; + thus, + a string like "rndc_key" is a valid + name. + The key statement has two + clauses: + algorithm and secret. + While the configuration parser will accept any string as the + argument + to algorithm, currently only the string "hmac-md5" + has any meaning. The secret is a base-64 encoded string. + + + + The server statement + associates a key + defined using the key + statement with a server. + The keyword server is followed by a + host name or address. The server statement + has two clauses: key and port. + The key clause specifies the + name of the key + to be used when communicating with this server, and the + port clause can be used to + specify the port rndc should + connect + to on the server. + + + + A sample minimal configuration file is as follows: + + key rndc_key { algorithm "hmac-md5"; @@ -917,275 +1467,407 @@ options { }; -This file, if installed as /etc/rndc.conf, -would allow the command: + + This file, if installed as /etc/rndc.conf, + would allow the command: + -$ rndc reload + + $ rndc reload + + + + to connect to 127.0.0.1 port 953 and cause the name server + to reload, if a name server on the local machine were + running with + following controls statements: + -to connect to 127.0.0.1 port 953 and cause the name server -to reload, if a name server on the local machine were running with -following controls statements: controls { inet 127.0.0.1 allow { localhost; } keys { rndc_key; }; }; -and it had an identical key statement for -rndc_key. - -Running the rndc-confgen program will -conveniently create a rndc.conf -file for you, and also display the -corresponding controls statement that you need to -add to named.conf. Alternatively, -you can run rndc-confgen -a to set up -a rndc.key file and not modify -named.conf at all. - - - - - - - - - -Signals -Certain UNIX signals cause the name server to take specific -actions, as described in the following table. These signals can -be sent using the kill command. - - - - - -SIGHUP -Causes the server to read named.conf and -reload the database. - - -SIGTERM -Causes the server to clean up and exit. - - - -SIGINT - - Causes the server to clean up and exit. - - - - - - + + and it had an identical key statement for + rndc_key. + + + + Running the rndc-confgen + program will + conveniently create a rndc.conf + file for you, and also display the + corresponding controls + statement that you need to + add to named.conf. + Alternatively, + you can run rndc-confgen -a + to set up + a rndc.key file and not + modify + named.conf at all. + + + + + + + + + + + Signals + + Certain UNIX signals cause the name server to take specific + actions, as described in the following table. These signals can + be sent using the kill command. + + + + + + + + + SIGHUP + + + + Causes the server to read named.conf and + reload the database. + + + + + + SIGTERM + + + + Causes the server to clean up and exit. + + + + + + SIGINT + + + + Causes the server to clean up and exit. + + + + + + + + - -Advanced DNS Features - - - -Notify -DNS NOTIFY is a mechanism that allows master -servers to notify their slave servers of changes to a zone's data. In -response to a NOTIFY from a master server, the -slave will check to see that its version of the zone is the -current version and, if not, initiate a zone transfer. - -DNS -For more information about -NOTIFY, see the description of the -notify option in and -the description of the zone option also-notify in -. The NOTIFY -protocol is specified in RFC 1996. - - - - - -Dynamic Update - - Dynamic Update is a method for adding, replacing or deleting - records in a master server by sending it a special form of DNS - messages. The format and meaning of these messages is specified - in RFC 2136. - - Dynamic update is enabled by - including an allow-update or - update-policy clause in the - zone statement. - - Updating of secure zones (zones using DNSSEC) follows - RFC 3007: RRSIG and NSEC records affected by updates are automatically - regenerated by the server using an online zone key. - Update authorization is based - on transaction signatures and an explicit server policy. - - - The journal file - - All changes made to a zone using dynamic update are stored - in the zone's journal file. This file is automatically created - by the server when the first dynamic update takes place. - The name of the journal file is formed by appending the extension - .jnl to the name of the corresponding zone - file unless specifically overridden. The journal file is in a - binary format and should not be edited manually. - - The server will also occasionally write ("dump") - the complete contents of the updated zone to its zone file. - This is not done immediately after - each dynamic update, because that would be too slow when a large - zone is updated frequently. Instead, the dump is delayed by - up to 15 minutes, allowing additional updates to take place. - - When a server is restarted after a shutdown or crash, it will replay - the journal file to incorporate into the zone any updates that took - place after the last zone dump. - - Changes that result from incoming incremental zone transfers are also - journalled in a similar way. - - The zone files of dynamic zones cannot normally be edited by - hand because they are not guaranteed to contain the most recent - dynamic changes - those are only in the journal file. - The only way to ensure that the zone file of a dynamic zone - is up to date is to run rndc stop. - - If you have to make changes to a dynamic zone - manually, the following procedure will work: Disable dynamic updates - to the zone using - rndc freeze zone. - This will also remove the zone's .jnl file - and update the master file. Edit the zone file. Run - rndc unfreeze zone - to reload the changed zone and re-enable dynamic updates. - - - - - - -Incremental Zone Transfers (IXFR) - -The incremental zone transfer (IXFR) protocol is a way for -slave servers to transfer only changed data, instead of having to -transfer the entire zone. The IXFR protocol is specified in RFC -1995. See . - -When acting as a master, BIND 9 -supports IXFR for those zones -where the necessary change history information is available. These -include master zones maintained by dynamic update and slave zones -whose data was obtained by IXFR. For manually maintained master -zones, and for slave zones obtained by performing a full zone -transfer (AXFR), IXFR is supported only if the option -ixfr-from-differences is set -to yes. - - -When acting as a slave, BIND 9 will -attempt to use IXFR unless -it is explicitly disabled. For more information about disabling -IXFR, see the description of the request-ixfr clause -of the server statement. - - -Split DNS -Setting up different views, or visibility, of the DNS space to -internal and external resolvers is usually referred to as a Split -DNS setup. There are several reasons an organization -would want to set up its DNS this way. -One common reason for setting up a DNS system this way is -to hide "internal" DNS information from "external" clients on the -Internet. There is some debate as to whether or not this is actually useful. -Internal DNS information leaks out in many ways (via email headers, -for example) and most savvy "attackers" can find the information -they need using other means. -Another common reason for setting up a Split DNS system is -to allow internal networks that are behind filters or in RFC 1918 -space (reserved IP space, as documented in RFC 1918) to resolve DNS -on the Internet. Split DNS can also be used to allow mail from outside -back in to the internal network. -Here is an example of a split DNS setup: -Let's say a company named Example, Inc. -(example.com) -has several corporate sites that have an internal network with reserved -Internet Protocol (IP) space and an external demilitarized zone (DMZ), -or "outside" section of a network, that is available to the public. -Example, Inc. wants its internal clients -to be able to resolve external hostnames and to exchange mail with -people on the outside. The company also wants its internal resolvers -to have access to certain internal-only zones that are not available -at all outside of the internal network. -In order to accomplish this, the company will set up two sets -of name servers. One set will be on the inside network (in the reserved -IP space) and the other set will be on bastion hosts, which are "proxy" -hosts that can talk to both sides of its network, in the DMZ. -The internal servers will be configured to forward all queries, -except queries for site1.internal, site2.internal, site1.example.com, -and site2.example.com, to the servers in the -DMZ. These internal servers will have complete sets of information -for site1.example.com, site2.example.com, site1.internal, -and site2.internal. -To protect the site1.internal and site2.internal domains, -the internal name servers must be configured to disallow all queries -to these domains from any external hosts, including the bastion -hosts. -The external servers, which are on the bastion hosts, will -be configured to serve the "public" version of the site1 and site2.example.com zones. -This could include things such as the host records for public servers -(www.example.com and ftp.example.com), -and mail exchange (MX) records (a.mx.example.com and b.mx.example.com). -In addition, the public site1 and site2.example.com zones -should have special MX records that contain wildcard (`*') records -pointing to the bastion hosts. This is needed because external mail -servers do not have any other way of looking up how to deliver mail -to those internal hosts. With the wildcard records, the mail will -be delivered to the bastion host, which can then forward it on to -internal hosts. -Here's an example of a wildcard MX record: -* IN MX 10 external1.example.com. -Now that they accept mail on behalf of anything in the internal -network, the bastion hosts will need to know how to deliver mail -to internal hosts. In order for this to work properly, the resolvers on -the bastion hosts will need to be configured to point to the internal -name servers for DNS resolution. -Queries for internal hostnames will be answered by the internal -servers, and queries for external hostnames will be forwarded back -out to the DNS servers on the bastion hosts. -In order for all this to work properly, internal clients will -need to be configured to query only the internal -name servers for DNS queries. This could also be enforced via selective -filtering on the network. -If everything has been set properly, Example, Inc.'s -internal clients will now be able to: - - Look up any hostnames in the site1 and -site2.example.com zones. - - Look up any hostnames in the site1.internal and -site2.internal domains. - - Look up any hostnames on the Internet. - - Exchange mail with internal AND external people. -Hosts on the Internet will be able to: - - Look up any hostnames in the site1 and -site2.example.com zones. - - Exchange mail with anyone in the site1 and -site2.example.com zones. - - Here is an example configuration for the setup we just - described above. Note that this is only configuration information; - for information on how to configure your zone files, see - -Internal DNS server config: + + Advanced DNS Features + + + + Notify + + DNS NOTIFY is a mechanism that allows + master + servers to notify their slave servers of changes to a zone's data. In + response to a NOTIFY from a master + server, the + slave will check to see that its version of the zone is the + current version and, if not, initiate a zone transfer. + + + + DNS + For more information about + NOTIFY, see the description of the + notify option in and + the description of the zone option also-notify in + . The NOTIFY + protocol is specified in RFC 1996. + + + + + + Dynamic Update + + + Dynamic Update is a method for adding, replacing or deleting + records in a master server by sending it a special form of DNS + messages. The format and meaning of these messages is specified + in RFC 2136. + + + + Dynamic update is enabled by + including an allow-update or + update-policy clause in the + zone statement. + + + + Updating of secure zones (zones using DNSSEC) follows + RFC 3007: RRSIG and NSEC records affected by updates are automatically + regenerated by the server using an online zone key. + Update authorization is based + on transaction signatures and an explicit server policy. + + + + The journal file + + + All changes made to a zone using dynamic update are stored + in the zone's journal file. This file is automatically created + by the server when the first dynamic update takes place. + The name of the journal file is formed by appending the extension + .jnl to the name of the + corresponding zone + file unless specifically overridden. The journal file is in a + binary format and should not be edited manually. + + + + The server will also occasionally write ("dump") + the complete contents of the updated zone to its zone file. + This is not done immediately after + each dynamic update, because that would be too slow when a large + zone is updated frequently. Instead, the dump is delayed by + up to 15 minutes, allowing additional updates to take place. + + + + When a server is restarted after a shutdown or crash, it will replay + the journal file to incorporate into the zone any updates that + took + place after the last zone dump. + + + + Changes that result from incoming incremental zone transfers are + also + journalled in a similar way. + + + + The zone files of dynamic zones cannot normally be edited by + hand because they are not guaranteed to contain the most recent + dynamic changes - those are only in the journal file. + The only way to ensure that the zone file of a dynamic zone + is up to date is to run rndc stop. + + + + If you have to make changes to a dynamic zone + manually, the following procedure will work: Disable dynamic updates + to the zone using + rndc freeze zone. + This will also remove the zone's .jnl file + and update the master file. Edit the zone file. Run + rndc unfreeze zone + to reload the changed zone and re-enable dynamic updates. + + + + + + + + Incremental Zone Transfers (IXFR) + + + The incremental zone transfer (IXFR) protocol is a way for + slave servers to transfer only changed data, instead of having to + transfer the entire zone. The IXFR protocol is specified in RFC + 1995. See . + + + + When acting as a master, BIND 9 + supports IXFR for those zones + where the necessary change history information is available. These + include master zones maintained by dynamic update and slave zones + whose data was obtained by IXFR. For manually maintained master + zones, and for slave zones obtained by performing a full zone + transfer (AXFR), IXFR is supported only if the option + ixfr-from-differences is set + to yes. + + + + When acting as a slave, BIND 9 will + attempt to use IXFR unless + it is explicitly disabled. For more information about disabling + IXFR, see the description of the request-ixfr clause + of the server statement. + + + + + Split DNS + + Setting up different views, or visibility, of the DNS space to + internal and external resolvers is usually referred to as a Split DNS setup. There are several reasons an organization + would want to set up its DNS this way. + + + One common reason for setting up a DNS system this way is + to hide "internal" DNS information from "external" clients on the + Internet. There is some debate as to whether or not this is actually + useful. + Internal DNS information leaks out in many ways (via email headers, + for example) and most savvy "attackers" can find the information + they need using other means. + + + Another common reason for setting up a Split DNS system is + to allow internal networks that are behind filters or in RFC 1918 + space (reserved IP space, as documented in RFC 1918) to resolve DNS + on the Internet. Split DNS can also be used to allow mail from outside + back in to the internal network. + + + Here is an example of a split DNS setup: + + + Let's say a company named Example, Inc. + (example.com) + has several corporate sites that have an internal network with + reserved + Internet Protocol (IP) space and an external demilitarized zone (DMZ), + or "outside" section of a network, that is available to the public. + + + Example, Inc. wants its internal clients + to be able to resolve external hostnames and to exchange mail with + people on the outside. The company also wants its internal resolvers + to have access to certain internal-only zones that are not available + at all outside of the internal network. + + + In order to accomplish this, the company will set up two sets + of name servers. One set will be on the inside network (in the + reserved + IP space) and the other set will be on bastion hosts, which are + "proxy" + hosts that can talk to both sides of its network, in the DMZ. + + + The internal servers will be configured to forward all queries, + except queries for site1.internal, site2.internal, site1.example.com, + and site2.example.com, to the servers + in the + DMZ. These internal servers will have complete sets of information + for site1.example.com, site2.example.com, site1.internal, + and site2.internal. + + + To protect the site1.internal and site2.internal domains, + the internal name servers must be configured to disallow all queries + to these domains from any external hosts, including the bastion + hosts. + + + The external servers, which are on the bastion hosts, will + be configured to serve the "public" version of the site1 and site2.example.com zones. + This could include things such as the host records for public servers + (www.example.com and ftp.example.com), + and mail exchange (MX) records (a.mx.example.com and b.mx.example.com). + + + In addition, the public site1 and site2.example.com zones + should have special MX records that contain wildcard (`*') records + pointing to the bastion hosts. This is needed because external mail + servers do not have any other way of looking up how to deliver mail + to those internal hosts. With the wildcard records, the mail will + be delivered to the bastion host, which can then forward it on to + internal hosts. + + + Here's an example of a wildcard MX record: + + * IN MX 10 external1.example.com. + + Now that they accept mail on behalf of anything in the internal + network, the bastion hosts will need to know how to deliver mail + to internal hosts. In order for this to work properly, the resolvers + on + the bastion hosts will need to be configured to point to the internal + name servers for DNS resolution. + + + Queries for internal hostnames will be answered by the internal + servers, and queries for external hostnames will be forwarded back + out to the DNS servers on the bastion hosts. + + + In order for all this to work properly, internal clients will + need to be configured to query only the internal + name servers for DNS queries. This could also be enforced via + selective + filtering on the network. + + + If everything has been set properly, Example, Inc.'s + internal clients will now be able to: + + + + + Look up any hostnames in the site1 + and + site2.example.com zones. + + + + + Look up any hostnames in the site1.internal and + site2.internal domains. + + + + Look up any hostnames on the Internet. + + + Exchange mail with internal AND external people. + + + + Hosts on the Internet will be able to: + + + + + Look up any hostnames in the site1 + and + site2.example.com zones. + + + + + Exchange mail with anyone in the site1 and + site2.example.com zones. + + + + + + Here is an example configuration for the setup we just + described above. Note that this is only configuration information; + for information on how to configure your zone files, see + + + + Internal DNS server config: + + acl internals { 172.16.72.0/24; 192.168.1.0/24; }; @@ -1241,7 +1923,11 @@ zone "site2.internal" { allow-transfer { internals; } }; - External (bastion host) DNS server config: + + + External (bastion host) DNS server config: + + acl internals { 172.16.72.0/24; 192.168.1.0/24; }; @@ -1271,1011 +1957,1620 @@ zone "site2.example.com" { allow-transfer { internals; externals; } }; -In the resolv.conf (or equivalent) on -the bastion host(s): + + + In the resolv.conf (or equivalent) on + the bastion host(s): + + search ... nameserver 172.16.72.2 nameserver 172.16.72.3 nameserver 172.16.72.4 - -TSIG -This is a short guide to setting up Transaction SIGnatures -(TSIG) based transaction security in BIND. It describes changes -to the configuration file as well as what changes are required for -different features, including the process of creating transaction -keys and using transaction signatures with BIND. -BIND primarily supports TSIG for server to server communication. -This includes zone transfer, notify, and recursive query messages. -Resolvers based on newer versions of BIND 8 have limited support -for TSIG. - - TSIG might be most useful for dynamic update. A primary - server for a dynamic zone should use access control to control - updates, but IP-based access control is insufficient. - The cryptographic access control provided by TSIG - is far superior. The nsupdate - program supports TSIG via the and - command line options. - -Generate Shared Keys for Each Pair of Hosts -A shared secret is generated to be shared between host1 and host2. -An arbitrary key name is chosen: "host1-host2.". The key name must -be the same on both hosts. -Automatic Generation -The following command will generate a 128 bit (16 byte) HMAC-MD5 -key as described above. Longer keys are better, but shorter keys -are easier to read. Note that the maximum key length is 512 bits; -keys longer than that will be digested with MD5 to produce a 128 -bit key. - dnssec-keygen -a hmac-md5 -b 128 -n HOST host1-host2. -The key is in the file Khost1-host2.+157+00000.private. -Nothing directly uses this file, but the base-64 encoded string -following "Key:" -can be extracted from the file and used as a shared secret: -Key: La/E5CjG9O+os1jq0a2jdA== -The string "La/E5CjG9O+os1jq0a2jdA==" can -be used as the shared secret. -Manual Generation -The shared secret is simply a random sequence of bits, encoded -in base-64. Most ASCII strings are valid base-64 strings (assuming -the length is a multiple of 4 and only valid characters are used), -so the shared secret can be manually generated. -Also, a known string can be run through mmencode or -a similar program to generate base-64 encoded data. -Copying the Shared Secret to Both Machines -This is beyond the scope of DNS. A secure transport mechanism -should be used. This could be secure FTP, ssh, telephone, etc. -Informing the Servers of the Key's Existence -Imagine host1 and host 2 are -both servers. The following is added to each server's named.conf file: + + + + TSIG + + This is a short guide to setting up Transaction SIGnatures + (TSIG) based transaction security in BIND. It describes changes + to the configuration file as well as what changes are required for + different features, including the process of creating transaction + keys and using transaction signatures with BIND. + + + BIND primarily supports TSIG for server + to server communication. + This includes zone transfer, notify, and recursive query messages. + Resolvers based on newer versions of BIND 8 have limited support + for TSIG. + + + + TSIG might be most useful for dynamic update. A primary + server for a dynamic zone should use access control to control + updates, but IP-based access control is insufficient. + The cryptographic access control provided by TSIG + is far superior. The nsupdate + program supports TSIG via the and + command line options. + + + + Generate Shared Keys for Each Pair of Hosts + + A shared secret is generated to be shared between host1 and host2. + An arbitrary key name is chosen: "host1-host2.". The key name must + be the same on both hosts. + + + Automatic Generation + + The following command will generate a 128 bit (16 byte) HMAC-MD5 + key as described above. Longer keys are better, but shorter keys + are easier to read. Note that the maximum key length is 512 bits; + keys longer than that will be digested with MD5 to produce a 128 + bit key. + + + dnssec-keygen -a hmac-md5 -b 128 -n HOST host1-host2. + + + The key is in the file Khost1-host2.+157+00000.private. + Nothing directly uses this file, but the base-64 encoded string + following "Key:" + can be extracted from the file and used as a shared secret: + + Key: La/E5CjG9O+os1jq0a2jdA== + + The string "La/E5CjG9O+os1jq0a2jdA==" can + be used as the shared secret. + + + + Manual Generation + + The shared secret is simply a random sequence of bits, encoded + in base-64. Most ASCII strings are valid base-64 strings (assuming + the length is a multiple of 4 and only valid characters are used), + so the shared secret can be manually generated. + + + Also, a known string can be run through mmencode or + a similar program to generate base-64 encoded data. + + + + + Copying the Shared Secret to Both Machines + + This is beyond the scope of DNS. A secure transport mechanism + should be used. This could be secure FTP, ssh, telephone, etc. + + + + Informing the Servers of the Key's Existence + + Imagine host1 and host 2 + are + both servers. The following is added to each server's named.conf file: + + key host1-host2. { algorithm hmac-md5; secret "La/E5CjG9O+os1jq0a2jdA=="; }; -The algorithm, hmac-md5, is the only one supported by BIND. -The secret is the one generated above. Since this is a secret, it -is recommended that either named.conf be non-world -readable, or the key directive be added to a non-world readable -file that is included by named.conf. -At this point, the key is recognized. This means that if the -server receives a message signed by this key, it can verify the -signature. If the signature is successfully verified, the -response is signed by the same key. - -Instructing the Server to Use the Key -Since keys are shared between two hosts only, the server must -be told when keys are to be used. The following is added to the named.conf file -for host1, if the IP address of host2 is -10.1.2.3: + + + The algorithm, hmac-md5, is the only one supported by BIND. + The secret is the one generated above. Since this is a secret, it + is recommended that either named.conf be non-world + readable, or the key directive be added to a non-world readable + file that is included by + named.conf. + + + At this point, the key is recognized. This means that if the + server receives a message signed by this key, it can verify the + signature. If the signature is successfully verified, the + response is signed by the same key. + + + + + Instructing the Server to Use the Key + + Since keys are shared between two hosts only, the server must + be told when keys are to be used. The following is added to the named.conf file + for host1, if the IP address of host2 is + 10.1.2.3: + + server 10.1.2.3 { keys { host1-host2. ;}; }; -Multiple keys may be present, but only the first is used. -This directive does not contain any secrets, so it may be in a world-readable -file. -If host1 sends a message that is a request -to that address, the message will be signed with the specified key. host1 will -expect any responses to signed messages to be signed with the same -key. -A similar statement must be present in host2's -configuration file (with host1's address) for host2 to -sign request messages to host1. -TSIG Key Based Access Control -BIND allows IP addresses and ranges to be specified in ACL -definitions and -allow-{ query | transfer | update } directives. -This has been extended to allow TSIG keys also. The above key would -be denoted key host1-host2. -An example of an allow-update directive would be: + + + Multiple keys may be present, but only the first is used. + This directive does not contain any secrets, so it may be in a + world-readable + file. + + + If host1 sends a message that is a request + to that address, the message will be signed with the specified key. host1 will + expect any responses to signed messages to be signed with the same + key. + + + A similar statement must be present in host2's + configuration file (with host1's address) for host2 to + sign request messages to host1. + + + + TSIG Key Based Access Control + + BIND allows IP addresses and ranges + to be specified in ACL + definitions and + allow-{ query | transfer | update } + directives. + This has been extended to allow TSIG keys also. The above key would + be denoted key host1-host2. + + + An example of an allow-update directive would be: + + allow-update { key host1-host2. ;}; - This allows dynamic updates to succeed only if the request - was signed by a key named - "host1-host2.". You may want to read about the more - powerful update-policy statement in . - - - - Errors - - The processing of TSIG signed messages can result in - several errors. If a signed message is sent to a non-TSIG aware - server, a FORMERR will be returned, since the server will not - understand the record. This is a result of misconfiguration, - since the server must be explicitly configured to send a TSIG - signed message to a specific server. - - If a TSIG aware server receives a message signed by an - unknown key, the response will be unsigned with the TSIG - extended error code set to BADKEY. If a TSIG aware server - receives a message with a signature that does not validate, the - response will be unsigned with the TSIG extended error code set - to BADSIG. If a TSIG aware server receives a message with a time - outside of the allowed range, the response will be signed with - the TSIG extended error code set to BADTIME, and the time values - will be adjusted so that the response can be successfully - verified. In any of these cases, the message's rcode is set to - NOTAUTH. - - - - - TKEY - - TKEY is a mechanism for automatically - generating a shared secret between two hosts. There are several - "modes" of TKEY that specify how the key is - generated or assigned. BIND 9 - implements only one of these modes, - the Diffie-Hellman key exchange. Both hosts are required to have - a Diffie-Hellman KEY record (although this record is not required - to be present in a zone). The TKEY process - must use signed messages, signed either by TSIG or SIG(0). The - result of TKEY is a shared secret that can be - used to sign messages with TSIG. TKEY can also - be used to delete shared secrets that it had previously - generated. - - The TKEY process is initiated by a client - or server by sending a signed TKEY query - (including any appropriate KEYs) to a TKEY-aware server. The - server response, if it indicates success, will contain a - TKEY record and any appropriate keys. After - this exchange, both participants have enough information to - determine the shared secret; the exact process depends on the - TKEY mode. When using the Diffie-Hellman - TKEY mode, Diffie-Hellman keys are exchanged, - and the shared secret is derived by both participants. - - - - SIG(0) - - BIND 9 partially supports DNSSEC SIG(0) - transaction signatures as specified in RFC 2535 and RFC2931. SIG(0) - uses public/private keys to authenticate messages. Access control - is performed in the same manner as TSIG keys; privileges can be - granted or denied based on the key name. - - When a SIG(0) signed message is received, it will only be - verified if the key is known and trusted by the server; the server - will not attempt to locate and/or validate the key. - - SIG(0) signing of multiple-message TCP streams is not - supported. - - The only tool shipped with BIND 9 that - generates SIG(0) signed messages is nsupdate. - - - - DNSSEC - - Cryptographic authentication of DNS information is possible - through the DNS Security (DNSSEC-bis) extensions, - defined in RFC <TBA>. This section describes the creation and use - of DNSSEC signed zones. - - In order to set up a DNSSEC secure zone, there are a series - of steps which must be followed. BIND 9 ships - with several tools - that are used in this process, which are explained in more detail - below. In all cases, the option prints a - full list of parameters. Note that the DNSSEC tools require the - keyset files to be in the working directory or the - directory specified by the option, and - that the tools shipped with BIND 9.2.x and earlier are not compatible - with the current ones. - - There must also be communication with the administrators of - the parent and/or child zone to transmit keys. A zone's security - status must be indicated by the parent zone for a DNSSEC capable - resolver to trust its data. This is done through the presense - or absence of a DS record at the delegation - point. - - For other servers to trust data in this zone, they must - either be statically configured with this zone's zone key or the - zone key of another zone above this one in the DNS tree. - - - Generating Keys - - The dnssec-keygen program is used to - generate keys. - - A secure zone must contain one or more zone keys. The - zone keys will sign all other records in the zone, as well as - the zone keys of any secure delegated zones. Zone keys must - have the same name as the zone, a name type of - ZONE, and must be usable for authentication. - It is recommended that zone keys use a cryptographic algorithm - designated as "mandatory to implement" by the IETF; currently - the only one is RSASHA1. - - The following command will generate a 768 bit RSASHA1 key for - the child.example zone: - - dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example. - - Two output files will be produced: - Kchild.example.+005+12345.key and - Kchild.example.+005+12345.private (where - 12345 is an example of a key tag). The key file names contain - the key name (child.example.), algorithm (3 - is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in this case). - The private key (in the .private file) is - used to generate signatures, and the public key (in the - .key file) is used for signature - verification. - - To generate another key with the same properties (but with - a different key tag), repeat the above command. - - The public keys should be inserted into the zone file by - including the .key files using - $INCLUDE statements. + + This allows dynamic updates to succeed only if the request + was signed by a key named + "host1-host2.". + + + You may want to read about the more + powerful update-policy statement in . + + + + + Errors + + + The processing of TSIG signed messages can result in + several errors. If a signed message is sent to a non-TSIG aware + server, a FORMERR will be returned, since the server will not + understand the record. This is a result of misconfiguration, + since the server must be explicitly configured to send a TSIG + signed message to a specific server. + + + + If a TSIG aware server receives a message signed by an + unknown key, the response will be unsigned with the TSIG + extended error code set to BADKEY. If a TSIG aware server + receives a message with a signature that does not validate, the + response will be unsigned with the TSIG extended error code set + to BADSIG. If a TSIG aware server receives a message with a time + outside of the allowed range, the response will be signed with + the TSIG extended error code set to BADTIME, and the time values + will be adjusted so that the response can be successfully + verified. In any of these cases, the message's rcode is set to + NOTAUTH. + + + + + + TKEY + + TKEY + is a mechanism for automatically generating a shared secret + between two hosts. There are several "modes" of + TKEY that specify how the key is generated + or assigned. BIND 9 implements only one of + these modes, the Diffie-Hellman key exchange. Both hosts are + required to have a Diffie-Hellman KEY record (although this + record is not required to be present in a zone). The + TKEY process must use signed messages, + signed either by TSIG or SIG(0). The result of + TKEY is a shared secret that can be used to + sign messages with TSIG. TKEY can also be + used to delete shared secrets that it had previously + generated. + + + + The TKEY process is initiated by a + client + or server by sending a signed TKEY + query + (including any appropriate KEYs) to a TKEY-aware server. The + server response, if it indicates success, will contain a + TKEY record and any appropriate keys. + After + this exchange, both participants have enough information to + determine the shared secret; the exact process depends on the + TKEY mode. When using the + Diffie-Hellman + TKEY mode, Diffie-Hellman keys are + exchanged, + and the shared secret is derived by both participants. + + + + + SIG(0) + + + BIND 9 partially supports DNSSEC SIG(0) + transaction signatures as specified in RFC 2535 and RFC2931. + SIG(0) + uses public/private keys to authenticate messages. Access control + is performed in the same manner as TSIG keys; privileges can be + granted or denied based on the key name. + + + + When a SIG(0) signed message is received, it will only be + verified if the key is known and trusted by the server; the server + will not attempt to locate and/or validate the key. + + + + SIG(0) signing of multiple-message TCP streams is not + supported. + + + + The only tool shipped with BIND 9 that + generates SIG(0) signed messages is nsupdate. + + + + + DNSSEC + + + Cryptographic authentication of DNS information is possible + through the DNS Security (DNSSEC-bis) extensions, + defined in RFC <TBA>. This section describes the creation + and use + of DNSSEC signed zones. + + + + In order to set up a DNSSEC secure zone, there are a series + of steps which must be followed. BIND + 9 ships + with several tools + that are used in this process, which are explained in more detail + below. In all cases, the option prints a + full list of parameters. Note that the DNSSEC tools require the + keyset files to be in the working directory or the + directory specified by the option, and + that the tools shipped with BIND 9.2.x and earlier are not compatible + with the current ones. + + + + There must also be communication with the administrators of + the parent and/or child zone to transmit keys. A zone's security + status must be indicated by the parent zone for a DNSSEC capable + resolver to trust its data. This is done through the presense + or absence of a DS record at the + delegation + point. + + + + For other servers to trust data in this zone, they must + either be statically configured with this zone's zone key or the + zone key of another zone above this one in the DNS tree. + + + + Generating Keys + + + The dnssec-keygen program is used to + generate keys. + + + + A secure zone must contain one or more zone keys. The + zone keys will sign all other records in the zone, as well as + the zone keys of any secure delegated zones. Zone keys must + have the same name as the zone, a name type of + ZONE, and must be usable for + authentication. + It is recommended that zone keys use a cryptographic algorithm + designated as "mandatory to implement" by the IETF; currently + the only one is RSASHA1. + + + + The following command will generate a 768 bit RSASHA1 key for + the child.example zone: + + + + dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example. + + + + Two output files will be produced: + Kchild.example.+005+12345.key and + Kchild.example.+005+12345.private + (where + 12345 is an example of a key tag). The key file names contain + the key name (child.example.), + algorithm (3 + is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in + this case). + The private key (in the .private + file) is + used to generate signatures, and the public key (in the + .key file) is used for signature + verification. + + + + To generate another key with the same properties (but with + a different key tag), repeat the above command. + + + + The public keys should be inserted into the zone file by + including the .key files using + $INCLUDE statements. + + + + + Signing the Zone + + + The dnssec-signzone program is used + to + sign a zone. + + + + Any keyset files corresponding + to secure subzones should be present. The zone signer will + generate NSEC and RRSIG + records for the zone, as well as DS + for + the child zones if '-d' is specified. + If '-d' is not specified then + DS RRsets for + the secure child zones need to be added manually. + + + + The following command signs the zone, assuming it is in a + file called zone.child.example. By + default, all zone keys which have an available private key are + used to generate signatures. + + + + dnssec-signzone -o child.example zone.child.example + + + + One output file is produced: + zone.child.example.signed. This + file + should be referenced by named.conf + as the + input file for the zone. + + + dnssec-signzone + will also produce a keyset and dsset files and optionally a + dlvset file. These are used to provide the parent zone + administators with the DNSKEYs (or their + corresponding DS records) that are the + secure entry point to the zone. + + + + + + Configuring Servers + + + Unlike BIND 8, + BIND 9 does not verify signatures on + load, + so zone keys for authoritative zones do not need to be specified + in the configuration file. + + + + The public key for any security root must be present in + the configuration file's trusted-keys + statement, as described later in this document. + + + + + + + IPv6 Support in <acronym>BIND</acronym> 9 + + + BIND 9 fully supports all currently + defined forms of IPv6 + name to address and address to name lookups. It will also use + IPv6 addresses to make queries when running on an IPv6 capable + system. + + + + For forward lookups, BIND 9 supports + only AAAA + records. The use of A6 records is deprecated by RFC 3363, and the + support for forward lookups in BIND 9 + is + removed accordingly. + However, authoritative BIND 9 name + servers still + load zone files containing A6 records correctly, answer queries + for A6 records, and accept zone transfer for a zone containing A6 + records. + + + + For IPv6 reverse lookups, BIND 9 + supports + the traditional "nibble" format used in the + ip6.arpa domain, as well as the older, deprecated + ip6.int domain. + BIND 9 formerly + supported the "binary label" (also known as "bitstring") format. + The support of binary labels, however, is now completely removed + according to the changes in RFC 3363. + Any applications in BIND 9 do not + understand + the format any more, and will return an error if given. + In particular, an authoritative BIND 9 + name + server rejects to load a zone file containing binary labels. + + + + For an overview of the format and structure of IPv6 addresses, + see . - - - Signing the Zone - - The dnssec-signzone program is used to - sign a zone. - - Any keyset files corresponding - to secure subzones should be present. The zone signer will - generate NSEC and RRSIG - records for the zone, as well as DS for - the child zones if '-d' is specified. - If '-d' is not specified then DS RRsets for - the secure child zones need to be added manually. - - The following command signs the zone, assuming it is in a - file called zone.child.example. By - default, all zone keys which have an available private key are - used to generate signatures. - -dnssec-signzone -o child.example zone.child.example - - One output file is produced: - zone.child.example.signed. This file - should be referenced by named.conf as the - input file for the zone. - - dnssec-signzone will also produce a - keyset and dsset files and optionally a dlvset file. These - are used to provide the parent zone administators with the - DNSKEYs (or their corresponding DS - records) that are the secure entry point to the zone. - - - -Configuring Servers - -Unlike BIND 8, -BIND 9 does not verify signatures on load, -so zone keys for authoritative zones do not need to be specified -in the configuration file. - -The public key for any security root must be present in -the configuration file's trusted-keys -statement, as described later in this document. - - - - - - IPv6 Support in <acronym>BIND</acronym> 9 - - BIND 9 fully supports all currently defined forms of IPv6 - name to address and address to name lookups. It will also use - IPv6 addresses to make queries when running on an IPv6 capable - system. - - For forward lookups, BIND 9 supports only AAAA - records. The use of A6 records is deprecated by RFC 3363, and the - support for forward lookups in BIND 9 is - removed accordingly. - However, authoritative BIND 9 name servers still - load zone files containing A6 records correctly, answer queries - for A6 records, and accept zone transfer for a zone containing A6 - records. - - For IPv6 reverse lookups, BIND 9 supports - the traditional "nibble" format used in the - ip6.arpa domain, as well as the older, deprecated - ip6.int domain. - BIND 9 formerly - supported the "binary label" (also known as "bitstring") format. - The support of binary labels, however, is now completely removed - according to the changes in RFC 3363. - Any applications in BIND 9 do not understand - the format any more, and will return an error if given. - In particular, an authoritative BIND 9 name - server rejects to load a zone file containing binary labels. - - For an overview of the format and structure of IPv6 addresses, - see . - - - Address Lookups Using AAAA Records - - The AAAA record is a parallel to the IPv4 A record. It - specifies the entire address in a single record. For - example, + + Address Lookups Using AAAA Records + + + The AAAA record is a parallel to the IPv4 A record. It + specifies the entire address in a single record. For + example, + $ORIGIN example.com. host 3600 IN AAAA 2001:db8::1 - It is recommended that IPv4-in-IPv6 mapped addresses not - be used. If a host has an IPv4 address, use an A record, not - a AAAA, with ::ffff:192.168.42.1 as the - address. - - - Address to Name Lookups Using Nibble Format - - When looking up an address in nibble format, the address - components are simply reversed, just as in IPv4, and - ip6.arpa. is appended to the resulting name. - For example, the following would provide reverse name lookup for - a host with address - 2001:db8::1. + + It is recommended that IPv4-in-IPv6 mapped addresses not + be used. If a host has an IPv4 address, use an A record, not + a AAAA, with ::ffff:192.168.42.1 as + the + address. + + + + Address to Name Lookups Using Nibble Format + + + When looking up an address in nibble format, the address + components are simply reversed, just as in IPv4, and + ip6.arpa. is appended to the + resulting name. + For example, the following would provide reverse name lookup for + a host with address + 2001:db8::1. + $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR host.example.com. - - + + + - The <acronym>BIND</acronym> 9 Lightweight Resolver -The Lightweight Resolver Library -Traditionally applications have been linked with a stub resolver -library that sends recursive DNS queries to a local caching name -server. -IPv6 once introduced new complexity into the resolution process, -such as following A6 chains and DNAME records, and simultaneous -lookup of IPv4 and IPv6 addresses. Though most of the complexity was -then removed, these are hard or impossible -to implement in a traditional stub resolver. -Instead, BIND 9 provides resolution services to local clients -using a combination of a lightweight resolver library and a resolver -daemon process running on the local host. These communicate using -a simple UDP-based protocol, the "lightweight resolver protocol" -that is distinct from and simpler than the full DNS protocol. -Running a Resolver Daemon - -To use the lightweight resolver interface, the system must -run the resolver daemon lwresd or a local -name server configured with a lwres statement. - -By default, applications using the lightweight resolver library will make -UDP requests to the IPv4 loopback address (127.0.0.1) on port 921. The -address can be overridden by lwserver lines in -/etc/resolv.conf. - -The daemon currently only looks in the DNS, but in the future -it may use other sources such as /etc/hosts, -NIS, etc. - -The lwresd daemon is essentially a -caching-only name server that responds to requests using the lightweight -resolver protocol rather than the DNS protocol. Because it needs -to run on each host, it is designed to require no or minimal configuration. -Unless configured otherwise, it uses the name servers listed on -nameserver lines in /etc/resolv.conf -as forwarders, but is also capable of doing the resolution autonomously if -none are specified. -The lwresd daemon may also be configured with a -named.conf style configuration file, in -/etc/lwresd.conf by default. A name server may also -be configured to act as a lightweight resolver daemon using the -lwres statement in named.conf. - - - -<acronym>BIND</acronym> 9 Configuration Reference - -BIND 9 configuration is broadly similar -to BIND 8; however, there are a few new areas -of configuration, such as views. BIND -8 configuration files should work with few alterations in BIND -9, although more complex configurations should be reviewed to check -if they can be more efficiently implemented using the new features -found in BIND 9. - -BIND 4 configuration files can be converted to the new format -using the shell script -contrib/named-bootconf/named-bootconf.sh. -Configuration File Elements -Following is a list of elements used throughout the BIND configuration -file documentation: - - - - - -acl_name -The name of an address_match_list as -defined by the acl statement. - - -address_match_list -A list of one or more ip_addr, -ip_prefix, key_id, -or acl_name elements, see -. - - -domain_name -A quoted string which will be used as -a DNS name, for example "my.test.domain". - - -dotted_decimal -One to four integers valued 0 through -255 separated by dots (`.'), such as 123, -45.67 or 89.123.45.67. - - -ip4_addr -An IPv4 address with exactly four elements -in dotted_decimal notation. - - -ip6_addr -An IPv6 address, such as 2001:db8::1234. -IPv6 scoped addresses that have ambiguity on their scope zones must be -disambiguated by an appropriate zone ID with the percent character -(`%') as delimiter. -It is strongly recommended to use string zone names rather than -numeric identifiers, in order to be robust against system -configuration changes. -However, since there is no standard mapping for such names and -identifier values, currently only interface names as link identifiers -are supported, assuming one-to-one mapping between interfaces and links. -For example, a link-local address fe80::1 on the -link attached to the interface ne0 -can be specified as fe80::1%ne0. -Note that on most systems link-local addresses always have the -ambiguity, and need to be disambiguated. - - -ip_addr -An ip4_addr or ip6_addr. - - -ip_port -An IP port number. -number is limited to 0 through 65535, with values -below 1024 typically restricted to use by processes running as root. -In some cases an asterisk (`*') character can be used as a placeholder to -select a random high-numbered port. - - -ip_prefix -An IP network specified as an ip_addr, -followed by a slash (`/') and then the number of bits in the netmask. -Trailing zeros in a ip_addr may omitted. -For example, 127/8 is the network 127.0.0.0 with -netmask 255.0.0.0 and 1.2.3.0/28 is -network 1.2.3.0 with netmask 255.255.255.240. - - -key_id -A domain_name representing -the name of a shared key, to be used for transaction security. - - -key_list -A list of one or more key_ids, -separated by semicolons and ending with a semicolon. - - -number -A non-negative 32 bit integer -(i.e., a number between 0 and 4294967295, inclusive). -Its acceptable value might further -be limited by the context in which it is used. - - -path_name -A quoted string which will be used as -a pathname, such as zones/master/my.test.domain. - - -size_spec -A number, the word unlimited, -or the word default. -An unlimited size_spec requests unlimited -use, or the maximum available amount. A default size_spec uses -the limit that was in force when the server was started.A number can -optionally be followed by a scaling factor: K or k for -kilobytes, M or m for -megabytes, and G or g for gigabytes, -which scale by 1024, 1024*1024, and 1024*1024*1024 respectively. -The value must be representable as a 64-bit unsigned integer -(0 to 18446744073709551615, inclusive). -Using unlimited is the best way -to safely set a really large number. - - -yes_or_no -Either yes or no. -The words true and false are -also accepted, as are the numbers 1 and 0. - - -dialup_option -One of yes, -no, notify, -notify-passive, refresh or -passive. -When used in a zone, notify-passive, -refresh, and passive -are restricted to slave and stub zones. - - - -Address Match Lists -Syntax - address_match_list = address_match_list_element ; + + The <acronym>BIND</acronym> 9 Lightweight Resolver + + The Lightweight Resolver Library + + Traditionally applications have been linked with a stub resolver + library that sends recursive DNS queries to a local caching name + server. + + + IPv6 once introduced new complexity into the resolution process, + such as following A6 chains and DNAME records, and simultaneous + lookup of IPv4 and IPv6 addresses. Though most of the complexity was + then removed, these are hard or impossible + to implement in a traditional stub resolver. + + + Instead, BIND 9 provides resolution + services to local clients + using a combination of a lightweight resolver library and a resolver + daemon process running on the local host. These communicate using + a simple UDP-based protocol, the "lightweight resolver protocol" + that is distinct from and simpler than the full DNS protocol. + + + + Running a Resolver Daemon + + + To use the lightweight resolver interface, the system must + run the resolver daemon lwresd or a + local + name server configured with a lwres + statement. + + + + By default, applications using the lightweight resolver library will + make + UDP requests to the IPv4 loopback address (127.0.0.1) on port 921. + The + address can be overridden by lwserver + lines in + /etc/resolv.conf. + + + + The daemon currently only looks in the DNS, but in the future + it may use other sources such as /etc/hosts, + NIS, etc. + + + + The lwresd daemon is essentially a + caching-only name server that responds to requests using the + lightweight + resolver protocol rather than the DNS protocol. Because it needs + to run on each host, it is designed to require no or minimal + configuration. + Unless configured otherwise, it uses the name servers listed on + nameserver lines in /etc/resolv.conf + as forwarders, but is also capable of doing the resolution + autonomously if + none are specified. + + + The lwresd daemon may also be + configured with a + named.conf style configuration file, + in + /etc/lwresd.conf by default. A name + server may also + be configured to act as a lightweight resolver daemon using the + lwres statement in named.conf. + + + + + + + <acronym>BIND</acronym> 9 Configuration Reference + + + BIND 9 configuration is broadly similar + to BIND 8; however, there are a few new + areas + of configuration, such as views. BIND + 8 configuration files should work with few alterations in BIND + 9, although more complex configurations should be reviewed to check + if they can be more efficiently implemented using the new features + found in BIND 9. + + + + BIND 4 configuration files can be + converted to the new format + using the shell script + contrib/named-bootconf/named-bootconf.sh. + + + Configuration File Elements + + Following is a list of elements used throughout the BIND configuration + file documentation: + + + + + + + + + + acl_name + + + + + The name of an address_match_list as + defined by the acl statement. + + + + + + + address_match_list + + + + + A list of one or more + ip_addr, + ip_prefix, key_id, + or acl_name elements, see + . + + + + + + + domain_name + + + + + A quoted string which will be used as + a DNS name, for example "my.test.domain". + + + + + + + dotted_decimal + + + + + One to four integers valued 0 through + 255 separated by dots (`.'), such as 123, + 45.67 or 89.123.45.67. + + + + + + + ip4_addr + + + + + An IPv4 address with exactly four elements + in dotted_decimal notation. + + + + + + + ip6_addr + + + + + An IPv6 address, such as 2001:db8::1234. + IPv6 scoped addresses that have ambiguity on their scope + zones must be + disambiguated by an appropriate zone ID with the percent + character + (`%') as delimiter. + It is strongly recommended to use string zone names rather + than + numeric identifiers, in order to be robust against system + configuration changes. + However, since there is no standard mapping for such names + and + identifier values, currently only interface names as link + identifiers + are supported, assuming one-to-one mapping between + interfaces and links. + For example, a link-local address fe80::1 on the + link attached to the interface ne0 + can be specified as fe80::1%ne0. + Note that on most systems link-local addresses always have + the + ambiguity, and need to be disambiguated. + + + + + + + ip_addr + + + + + An ip4_addr or ip6_addr. + + + + + + + ip_port + + + + + An IP port number. + number is limited to 0 + through 65535, with values + below 1024 typically restricted to use by processes running + as root. + In some cases an asterisk (`*') character can be used as a + placeholder to + select a random high-numbered port. + + + + + + + ip_prefix + + + + + An IP network specified as an ip_addr, + followed by a slash (`/') and then the number of bits in the + netmask. + Trailing zeros in a ip_addr + may omitted. + For example, 127/8 is the + network 127.0.0.0 with + netmask 255.0.0.0 and 1.2.3.0/28 is + network 1.2.3.0 with netmask 255.255.255.240. + + + + + + + key_id + + + + + A domain_name representing + the name of a shared key, to be used for transaction + security. + + + + + + + key_list + + + + + A list of one or more + key_ids, + separated by semicolons and ending with a semicolon. + + + + + + + number + + + + + A non-negative 32 bit integer + (i.e., a number between 0 and 4294967295, inclusive). + Its acceptable value might further + be limited by the context in which it is used. + + + + + + + path_name + + + + + A quoted string which will be used as + a pathname, such as zones/master/my.test.domain. + + + + + + + size_spec + + + + + A number, the word unlimited, + or the word default. + + + An unlimited size_spec requests unlimited + use, or the maximum available amount. A default size_spec uses + the limit that was in force when the server was started. + + + A number can optionally be + followed by a scaling factor: + K or k + for kilobytes, + M or m + for megabytes, and + G or g for gigabytes, + which scale by 1024, 1024*1024, and 1024*1024*1024 + respectively. + + + The value must be representable as a 64-bit unsigned integer + (0 to 18446744073709551615, inclusive). + Using unlimited is the best + way + to safely set a really large number. + + + + + + + yes_or_no + + + + + Either yes or no. + The words true and false are + also accepted, as are the numbers 1 + and 0. + + + + + + + dialup_option + + + + + One of yes, + no, notify, + notify-passive, refresh or + passive. + When used in a zone, notify-passive, + refresh, and passive + are restricted to slave and stub zones. + + + + + + + + Address Match Lists + + Syntax + +address_match_list = address_match_list_element ; address_match_list_element; ... address_match_list_element = ! (ip_address /length | key key_id | acl_name | { address_match_list } ) - -Definition and Usage -Address match lists are primarily used to determine access -control for various server operations. They are also used in -the listen-on and sortlist -statements. The elements -which constitute an address match list can be any of the following: - - an IP address (IPv4 or IPv6) - - an IP prefix (in `/' notation) - - a key ID, as defined by the key statement - - the name of an address match list defined with -the acl statement - - a nested address match list enclosed in braces - -Elements can be negated with a leading exclamation mark (`!'), -and the match list names "any", "none", "localhost", and "localnets" -are predefined. More information on those names can be found in -the description of the acl statement. - -The addition of the key clause made the name of this syntactic -element something of a misnomer, since security keys can be used -to validate access without regard to a host or network address. Nonetheless, -the term "address match list" is still used throughout the documentation. - -When a given IP address or prefix is compared to an address -match list, the list is traversed in order until an element matches. -The interpretation of a match depends on whether the list is being used -for access control, defining listen-on ports, or in a sortlist, -and whether the element was negated. - -When used as an access control list, a non-negated match allows -access and a negated match denies access. If there is no match, -access is denied. The clauses allow-notify, -allow-query, allow-query-cache, -allow-transfer, -allow-update, allow-update-forwarding, -and blackhole all use address match lists. -Similarly, the listen-on option will cause the server to not accept -queries on any of the machine's addresses which do not match the -list. - -Because of the first-match aspect of the algorithm, an element -that defines a subset of another element in the list should come -before the broader element, regardless of whether either is negated. For -example, in -1.2.3/24; ! 1.2.3.13; the 1.2.3.13 element is -completely useless because the algorithm will match any lookup for -1.2.3.13 to the 1.2.3/24 element. -Using ! 1.2.3.13; 1.2.3/24 fixes -that problem by having 1.2.3.13 blocked by the negation but all -other 1.2.3.* hosts fall through. - - - - -Comment Syntax - -The BIND 9 comment syntax allows for comments to appear -anywhere that white space may appear in a BIND configuration -file. To appeal to programmers of all kinds, they can be written -in the C, C++, or shell/perl style. - - -Syntax - -/* This is a BIND comment as in C */ -// This is a BIND comment as in C++ -# This is a BIND comment as in common UNIX shells and perl - - - - Definition and Usage -Comments may appear anywhere that whitespace may appear in -a BIND configuration file. -C-style comments start with the two characters /* (slash, -star) and end with */ (star, slash). Because they are completely -delimited with these characters, they can be used to comment only -a portion of a line or to span multiple lines. -C-style comments cannot be nested. For example, the following -is not valid because the entire comment ends with the first */: - /* This is the start of a comment. + + + + Definition and Usage + + Address match lists are primarily used to determine access + control for various server operations. They are also used in + the listen-on and sortlist + statements. The elements + which constitute an address match list can be any of the + following: + + + + an IP address (IPv4 or IPv6) + + + an IP prefix (in `/' notation) + + + + a key ID, as defined by the key + statement + + + + the name of an address match list defined with + the acl statement + + + + a nested address match list enclosed in braces + + + + + Elements can be negated with a leading exclamation mark (`!'), + and the match list names "any", "none", "localhost", and + "localnets" + are predefined. More information on those names can be found in + the description of the acl statement. + + + + The addition of the key clause made the name of this syntactic + element something of a misnomer, since security keys can be used + to validate access without regard to a host or network address. + Nonetheless, + the term "address match list" is still used throughout the + documentation. + + + + When a given IP address or prefix is compared to an address + match list, the list is traversed in order until an element + matches. + The interpretation of a match depends on whether the list is being + used + for access control, defining listen-on ports, or in a sortlist, + and whether the element was negated. + + + + When used as an access control list, a non-negated match allows + access and a negated match denies access. If there is no match, + access is denied. The clauses allow-notify, + allow-query, allow-query-cache, + allow-transfer, + allow-update, allow-update-forwarding, + and blackhole all use address match + lists. + Similarly, the listen-on option will cause the server to not + accept + queries on any of the machine's addresses which do not match the + list. + + + + Because of the first-match aspect of the algorithm, an element + that defines a subset of another element in the list should come + before the broader element, regardless of whether either is + negated. For + example, in + 1.2.3/24; ! 1.2.3.13; the 1.2.3.13 + element is + completely useless because the algorithm will match any lookup for + 1.2.3.13 to the 1.2.3/24 element. + Using ! 1.2.3.13; 1.2.3/24 fixes + that problem by having 1.2.3.13 blocked by the negation but all + other 1.2.3.* hosts fall through. + + + + + + Comment Syntax + + + The BIND 9 comment syntax allows for + comments to appear + anywhere that white space may appear in a BIND configuration + file. To appeal to programmers of all kinds, they can be written + in the C, C++, or shell/perl style. + + + + Syntax + + + /* This is a BIND comment as in C */ + // This is a BIND comment as in C++ + # This is a BIND comment as in common UNIX shells and perl + + + + Definition and Usage + + Comments may appear anywhere that whitespace may appear in + a BIND configuration file. + + + C-style comments start with the two characters /* (slash, + star) and end with */ (star, slash). Because they are completely + delimited with these characters, they can be used to comment only + a portion of a line or to span multiple lines. + + + C-style comments cannot be nested. For example, the following + is not valid because the entire comment ends with the first */: + + + +/* This is the start of a comment. This is still part of the comment. /* This is an incorrect attempt at nesting a comment. */ This is no longer in any comment. */ - - -C++-style comments start with the two characters // (slash, -slash) and continue to the end of the physical line. They cannot -be continued across multiple physical lines; to have one logical -comment span multiple lines, each line must use the // pair. -For example: - // This is the start of a comment. The next line + + + + + + C++-style comments start with the two characters // (slash, + slash) and continue to the end of the physical line. They cannot + be continued across multiple physical lines; to have one logical + comment span multiple lines, each line must use the // pair. + + + For example: + + + +// This is the start of a comment. The next line // is a new comment, even though it is logically // part of the previous comment. - -Shell-style (or perl-style, if you prefer) comments start -with the character # (number sign) and continue to the end of the -physical line, as in C++ comments. -For example: + + + + + Shell-style (or perl-style, if you prefer) comments start + with the character # (number sign) + and continue to the end of the + physical line, as in C++ comments. + + + For example: + -# This is the start of a comment. The next line + + +# This is the start of a comment. The next line # is a new comment, even though it is logically # part of the previous comment. - - - - You cannot use the semicolon (`;') character - to start a comment such as you would in a zone file. The - semicolon indicates the end of a configuration - statement. - - - - - - -Configuration File Grammar - - A BIND 9 configuration consists of statements and comments. - Statements end with a semicolon. Statements and comments are the - only elements that can appear without enclosing braces. Many - statements contain a block of sub-statements, which are also - terminated with a semicolon. - - The following statements are supported: - - - - - - - - acl - defines a named IP address -matching list, for access control and other uses. - - - controls - declares control channels to be used -by the rndc utility. - - - include - includes a file. - - - key - specifies key information for use in -authentication and authorization using TSIG. - - - logging - specifies what the server logs, and where -the log messages are sent. - - - lwres - configures named to -also act as a light weight resolver daemon (lwresd). - - - masters - defines a named masters list for -inclusion in stub and slave zone masters clauses. - - - options - controls global server configuration -options and sets defaults for other statements. - - - server - sets certain configuration options on -a per-server basis. - - - trusted-keys - defines trusted DNSSEC keys. - - - view - defines a view. - - - zone - defines a zone. - - - - - The logging and - options statements may only occur once per - configuration. - - - <command>acl</command> Statement Grammar - - acl acl-name { + + + + + + You cannot use the semicolon (`;') character + to start a comment such as you would in a zone file. The + semicolon indicates the end of a configuration + statement. + + + + + + + + Configuration File Grammar + + + A BIND 9 configuration consists of + statements and comments. + Statements end with a semicolon. Statements and comments are the + only elements that can appear without enclosing braces. Many + statements contain a block of sub-statements, which are also + terminated with a semicolon. + + + + The following statements are supported: + + + + + + + + + + acl + + + + defines a named IP address + matching list, for access control and other uses. + + + + + + controls + + + + declares control channels to be used + by the rndc utility. + + + + + + include + + + + includes a file. + + + + + + key + + + + specifies key information for use in + authentication and authorization using TSIG. + + + + + + logging + + + + specifies what the server logs, and where + the log messages are sent. + + + + + + lwres + + + + configures named to + also act as a light weight resolver daemon (lwresd). + + + + + + masters + + + + defines a named masters list for + inclusion in stub and slave zone masters clauses. + + + + + + options + + + + controls global server configuration + options and sets defaults for other statements. + + + + + + server + + + + sets certain configuration options on + a per-server basis. + + + + + + trusted-keys + + + + defines trusted DNSSEC keys. + + + + + + view + + + + defines a view. + + + + + + zone + + + + defines a zone. + + + + + + + + + The logging and + options statements may only occur once + per + configuration. + + + + <command>acl</command> Statement Grammar + +acl acl-name { address_match_list }; - - - <command>acl</command> Statement Definition and -Usage - - The acl statement assigns a symbolic - name to an address match list. It gets its name from a primary - use of address match lists: Access Control Lists (ACLs). - - Note that an address match list's name must be defined - with acl before it can be used elsewhere; no - forward references are allowed. - - The following ACLs are built-in: - - - - - - -any -Matches all hosts. - - -none -Matches no hosts. - - -localhost -Matches the IPv4 and IPv6 addresses of all network -interfaces on the system. - - -localnets -Matches any host on an IPv4 or IPv6 network -for which the system has an interface. -Some systems do not provide a way to determine the prefix lengths of -local IPv6 addresses. -In such a case, localnets only matches the local -IPv6 addresses, just like localhost. - - - - - - - - <command>controls</command> Statement Grammar + + + + <command>acl</command> Statement Definition and + Usage + + + The acl statement assigns a symbolic + name to an address match list. It gets its name from a primary + use of address match lists: Access Control Lists (ACLs). + + + + Note that an address match list's name must be defined + with acl before it can be used + elsewhere; no + forward references are allowed. + + + + The following ACLs are built-in: + + + + + + + + + + any + + + + Matches all hosts. + + + + + + none + + + + Matches no hosts. + + + + + + localhost + + + + Matches the IPv4 and IPv6 addresses of all network + interfaces on the system. + + + + + + localnets + + + + Matches any host on an IPv4 or IPv6 network + for which the system has an interface. + Some systems do not provide a way to determine the prefix + lengths of + local IPv6 addresses. + In such a case, localnets + only matches the local + IPv6 addresses, just like localhost. + + + + + + + + + + <command>controls</command> Statement Grammar + controls { inet ( ip_addr | * ) port ip_port allow { address_match_list } keys { key_list }; inet ...; }; - - - -<command>controls</command> Statement Definition and Usage - - The controls statement declares control - channels to be used by system administrators to control the - operation of the name server. These control channels are - used by the rndc utility to send commands to - and retrieve non-DNS results from a name server. - - An inet control channel is a TCP - socket listening at the specified - ip_port on the specified - ip_addr, which can be an IPv4 or IPv6 - address. An ip_addr - of * is interpreted as the IPv4 wildcard - address; connections will be accepted on any of the system's - IPv4 addresses. To listen on the IPv6 wildcard address, - use an ip_addr of ::. - If you will only use rndc on the local host, - using the loopback address (127.0.0.1 - or ::1) is recommended for maximum - security. - - - - If no port is specified, port 953 - is used. "*" cannot be used for - ip_port. - - The ability to issue commands over the control channel is - restricted by the allow and - keys clauses. Connections to the control - channel are permitted based on the - address_match_list. This is for simple - IP address based filtering only; any key_id - elements of the address_match_list are - ignored. - - The primary authorization mechanism of the command - channel is the key_list, which contains - a list of key_ids. - Each key_id in - the key_list is authorized to execute - commands over the control channel. - See in - ) for information about - configuring keys in rndc. - - -If no controls statement is present, -named will set up a default -control channel listening on the loopback address 127.0.0.1 -and its IPv6 counterpart ::1. -In this case, and also when the controls statement -is present but does not have a keys clause, -named will attempt to load the command channel key -from the file rndc.key in -/etc (or whatever sysconfdir -was specified as when BIND was built). -To create a rndc.key file, run -rndc-confgen -a. - - - The rndc.key feature was created to - ease the transition of systems from BIND 8, - which did not have digital signatures on its command channel messages - and thus did not have a keys clause. - -It makes it possible to use an existing BIND 8 -configuration file in BIND 9 unchanged, -and still have rndc work the same way -ndc worked in BIND 8, simply by executing the -command rndc-confgen -a after BIND 9 is -installed. - + + + + <command>controls</command> Statement Definition and + Usage + + + The controls statement declares + control + channels to be used by system administrators to control the + operation of the name server. These control channels are + used by the rndc utility to send + commands to + and retrieve non-DNS results from a name server. + + + + An inet control channel is a TCP + socket listening at the specified + ip_port on the specified + ip_addr, which can be an IPv4 or IPv6 + address. An ip_addr + of * is interpreted as the IPv4 + wildcard + address; connections will be accepted on any of the system's + IPv4 addresses. To listen on the IPv6 wildcard address, + use an ip_addr of ::. + If you will only use rndc on the + local host, + using the loopback address (127.0.0.1 + or ::1) is recommended for + maximum + security. + + + + If no port is specified, port 953 + is used. "*" cannot be used for + ip_port. + + + + The ability to issue commands over the control channel is + restricted by the allow and + keys clauses. Connections to the + control + channel are permitted based on the + address_match_list. This is for + simple + IP address based filtering only; any key_id + elements of the address_match_list + are + ignored. + + + + The primary authorization mechanism of the command + channel is the key_list, which + contains + a list of key_ids. + Each key_id in + the key_list is authorized to execute + commands over the control channel. + See in + ) for information about + configuring keys in rndc. + + + + If no controls statement is present, + named will set up a default + control channel listening on the loopback address 127.0.0.1 + and its IPv6 counterpart ::1. + In this case, and also when the controls statement + is present but does not have a keys + clause, + named will attempt to load the + command channel key + from the file rndc.key in + /etc (or whatever sysconfdir + was specified as when BIND was + built). + To create a rndc.key file, run + rndc-confgen -a. + + + + The rndc.key feature was created to + ease the transition of systems from BIND 8, + which did not have digital signatures on its command channel + messages + and thus did not have a keys clause. + + It makes it possible to use an existing BIND 8 + configuration file in BIND 9 + unchanged, + and still have rndc work the same way + ndc worked in BIND 8, simply by + executing the + command rndc-confgen -a after BIND 9 is + installed. + + + + Since the rndc.key feature + is only intended to allow the backward-compatible usage of + BIND 8 configuration files, this + feature does not + have a high degree of configurability. You cannot easily change + the key name or the size of the secret, so you should make a + rndc.conf with your own key if you + wish to change + those things. The rndc.key file + also has its + permissions set such that only the owner of the file (the user that + named is running as) can access it. + If you + desire greater flexibility in allowing other users to access + rndc commands then you need to create + an + rndc.conf and make it group + readable by a group + that contains the users who should have access. + + + + The UNIX control channel type of BIND + 8 is not supported + in BIND 9, and is not expected to be + added in future + releases. If it is present in the controls statement from a + BIND 8 configuration file, it is + ignored + and a warning is logged. + + + + To disable the command channel, use an empty controls + statement: controls { };. + + + + + <command>include</command> Statement Grammar + include filename; + + + <command>include</command> Statement Definition and + Usage + + + The include statement inserts the + specified file at the point where the include + statement is encountered. The include + statement facilitates the administration of configuration + files + by permitting the reading or writing of some things but not + others. For example, the statement could include private keys + that are readable only by the name server. + + + + + <command>key</command> Statement Grammar - - Since the rndc.key feature - is only intended to allow the backward-compatible usage of - BIND 8 configuration files, this feature does not - have a high degree of configurability. You cannot easily change - the key name or the size of the secret, so you should make a - rndc.conf with your own key if you wish to change - those things. The rndc.key file also has its - permissions set such that only the owner of the file (the user that - named is running as) can access it. If you - desire greater flexibility in allowing other users to access - rndc commands then you need to create an - rndc.conf and make it group readable by a group - that contains the users who should have access. - - The UNIX control channel type of BIND 8 is not supported - in BIND 9, and is not expected to be added in future - releases. If it is present in the controls statement from a - BIND 8 configuration file, it is ignored - and a warning is logged. - - -To disable the command channel, use an empty controls -statement: controls { };. - - - - - <command>include</command> Statement Grammar - include filename; - - - <command>include</command> Statement Definition and Usage - - The include statement inserts the - specified file at the point where the include - statement is encountered. The include - statement facilitates the administration of configuration files - by permitting the reading or writing of some things but not - others. For example, the statement could include private keys - that are readable only by the name server. - - - - <command>key</command> Statement Grammar key key_id { algorithm string; secret string; }; - - - -<command>key</command> Statement Definition and Usage - -The key statement defines a shared -secret key for use with TSIG (see ) -or the command channel -(see ). - - - -The key statement can occur at the top level -of the configuration file or inside a view -statement. Keys defined in top-level key -statements can be used in all views. Keys intended for use in -a controls statement -(see ) -must be defined at the top level. - - -The key_id, also known as the -key name, is a domain name uniquely identifying the key. It can -be used in a server -statement to cause requests sent to that -server to be signed with this key, or in address match lists to -verify that incoming requests have been signed with a key -matching this name, algorithm, and secret. - -The algorithm_id is a string -that specifies a security/authentication algorithm. The only -algorithm currently supported with TSIG authentication is -hmac-md5. The -secret_string is the secret to be -used by the algorithm, and is treated as a base-64 encoded -string. - - - - <command>logging</command> Statement Grammar - logging { + + + + + <command>key</command> Statement Definition and Usage + + + The key statement defines a shared + secret key for use with TSIG (see ) + or the command channel + (see ). + + + + The key statement can occur at the + top level + of the configuration file or inside a view + statement. Keys defined in top-level key + statements can be used in all views. Keys intended for use in + a controls statement + (see ) + must be defined at the top level. + + + + The key_id, also known as the + key name, is a domain name uniquely identifying the key. It can + be used in a server + statement to cause requests sent to that + server to be signed with this key, or in address match lists to + verify that incoming requests have been signed with a key + matching this name, algorithm, and secret. + + + + The algorithm_id is a string + that specifies a security/authentication algorithm. The only + algorithm currently supported with TSIG authentication is + hmac-md5. The + secret_string is the secret + to be + used by the algorithm, and is treated as a base-64 encoded + string. + + + + + <command>logging</command> Statement Grammar + +logging { [ channel channel_name { ( file path name - [ versions ( number | unlimited ) ] + [ versions ( number | unlimited ) ] [ size size spec ] | syslog syslog_facility | stderr @@ -2287,24 +3582,32 @@ string. [ print-time or ; ] }; ] [ category category_name { - channel_name ; [ channel_name ; ... ] + channel_name ; [ channel_name ; ... ] }; ] ... }; - - - -<command>logging</command> Statement Definition and Usage -The logging statement configures a wide -variety of logging options for the name server. Its channel phrase -associates output methods, format options and severity levels with -a name that can then be used with the category phrase -to select how various classes of messages are logged. -Only one logging statement is used to define -as many channels and categories as are wanted. If there is no logging statement, -the logging configuration will be: + + + + <command>logging</command> Statement Definition and + Usage + + + The logging statement configures a + wide + variety of logging options for the name server. Its channel phrase + associates output methods, format options and severity levels with + a name that can then be used with the category phrase + to select how various classes of messages are logged. + + + Only one logging statement is used to + define + as many channels and categories as are wanted. If there is no logging statement, + the logging configuration will be: + logging { category default { default_syslog; default_debug; }; @@ -2312,65 +3615,98 @@ the logging configuration will be: }; -In BIND 9, the logging configuration is only established when -the entire configuration file has been parsed. In BIND 8, it was -established as soon as the logging statement -was parsed. When the server is starting up, all logging messages -regarding syntax errors in the configuration file go to the default -channels, or to standard error if the "" option -was specified. - - -The <command>channel</command> Phrase - -All log output goes to one or more channels; -you can make as many of them as you want. - -Every channel definition must include a destination clause that -says whether messages selected for the channel go to a file, to a -particular syslog facility, to the standard error stream, or are -discarded. It can optionally also limit the message severity level -that will be accepted by the channel (the default is -info), and whether to include a -named-generated time stamp, the category name -and/or severity level (the default is not to include any). - -The null destination clause -causes all messages sent to the channel to be discarded; -in that case, other options for the channel are meaningless. - -The file destination clause directs the channel -to a disk file. It can include limitations -both on how large the file is allowed to become, and how many versions -of the file will be saved each time the file is opened. - -If you use the versions log file option, then -named will retain that many backup versions of the file by -renaming them when opening. For example, if you choose to keep 3 old versions -of the file lamers.log then just before it is opened -lamers.log.1 is renamed to -lamers.log.2, lamers.log.0 is renamed -to lamers.log.1, and lamers.log is -renamed to lamers.log.0. -You can say versions unlimited to not limit -the number of versions. -If a size option is associated with the log file, -then renaming is only done when the file being opened exceeds the -indicated size. No backup versions are kept by default; any existing -log file is simply appended. - -The size option for files is used to limit log -growth. If the file ever exceeds the size, then named will -stop writing to the file unless it has a versions option -associated with it. If backup versions are kept, the files are rolled as -described above and a new one begun. If there is no -versions option, no more data will be written to the log -until some out-of-band mechanism removes or truncates the log to less than the -maximum size. The default behavior is not to limit the size of the -file. - -Example usage of the size and -versions options: + + In BIND 9, the logging configuration + is only established when + the entire configuration file has been parsed. In BIND 8, it was + established as soon as the logging + statement + was parsed. When the server is starting up, all logging messages + regarding syntax errors in the configuration file go to the default + channels, or to standard error if the "" option + was specified. + + + + The <command>channel</command> Phrase + + + All log output goes to one or more channels; + you can make as many of them as you want. + + + + Every channel definition must include a destination clause that + says whether messages selected for the channel go to a file, to a + particular syslog facility, to the standard error stream, or are + discarded. It can optionally also limit the message severity level + that will be accepted by the channel (the default is + info), and whether to include a + named-generated time stamp, the + category name + and/or severity level (the default is not to include any). + + + + The null destination clause + causes all messages sent to the channel to be discarded; + in that case, other options for the channel are meaningless. + + + + The file destination clause directs + the channel + to a disk file. It can include limitations + both on how large the file is allowed to become, and how many + versions + of the file will be saved each time the file is opened. + + + + If you use the versions log file + option, then + named will retain that many backup + versions of the file by + renaming them when opening. For example, if you choose to keep 3 + old versions + of the file lamers.log then just + before it is opened + lamers.log.1 is renamed to + lamers.log.2, lamers.log.0 is renamed + to lamers.log.1, and lamers.log is + renamed to lamers.log.0. + You can say versions unlimited to + not limit + the number of versions. + If a size option is associated with + the log file, + then renaming is only done when the file being opened exceeds the + indicated size. No backup versions are kept by default; any + existing + log file is simply appended. + + + + The size option for files is used + to limit log + growth. If the file ever exceeds the size, then named will + stop writing to the file unless it has a versions option + associated with it. If backup versions are kept, the files are + rolled as + described above and a new one begun. If there is no + versions option, no more data will + be written to the log + until some out-of-band mechanism removes or truncates the log to + less than the + maximum size. The default behavior is not to limit the size of + the + file. + + + + Example usage of the size and + versions options: + channel an_example_channel { file "example.log" versions 3 size 20m; @@ -2379,80 +3715,117 @@ file. }; -The syslog destination clause directs the -channel to the system log. Its argument is a -syslog facility as described in the syslog man -page. Known facilities are kern, user, -mail, daemon, auth, -syslog, lpr, news, -uucp, cron, authpriv, -ftp, local0, local1, -local2, local3, local4, -local5, local6 and -local7, however not all facilities are supported on -all operating systems. -How syslog will handle messages sent to -this facility is described in the syslog.conf man -page. If you have a system which uses a very old version of syslog that -only uses two arguments to the openlog() function, -then this clause is silently ignored. -The severity clause works like syslog's -"priorities", except that they can also be used if you are writing -straight to a file rather than using syslog. -Messages which are not at least of the severity level given will -not be selected for the channel; messages of higher severity levels -will be accepted. -If you are using syslog, then the syslog.conf priorities -will also determine what eventually passes through. For example, -defining a channel facility and severity as daemon and debug but -only logging daemon.warning via syslog.conf will -cause messages of severity info and notice to -be dropped. If the situation were reversed, with named writing -messages of only warning or higher, then syslogd would -print all messages it received from the channel. - -The stderr destination clause directs the -channel to the server's standard error stream. This is intended for -use when the server is running as a foreground process, for example -when debugging a configuration. - -The server can supply extensive debugging information when -it is in debugging mode. If the server's global debug level is greater -than zero, then debugging mode will be active. The global debug -level is set either by starting the named server -with the flag followed by a positive integer, -or by running rndc trace. -The global debug level -can be set to zero, and debugging mode turned off, by running ndc + + The syslog destination clause + directs the + channel to the system log. Its argument is a + syslog facility as described in the syslog man + page. Known facilities are kern, user, + mail, daemon, auth, + syslog, lpr, news, + uucp, cron, authpriv, + ftp, local0, local1, + local2, local3, local4, + local5, local6 and + local7, however not all facilities + are supported on + all operating systems. + How syslog will handle messages + sent to + this facility is described in the syslog.conf man + page. If you have a system which uses a very old version of syslog that + only uses two arguments to the openlog() function, + then this clause is silently ignored. + + + The severity clause works like syslog's + "priorities", except that they can also be used if you are writing + straight to a file rather than using syslog. + Messages which are not at least of the severity level given will + not be selected for the channel; messages of higher severity + levels + will be accepted. + + + If you are using syslog, then the syslog.conf priorities + will also determine what eventually passes through. For example, + defining a channel facility and severity as daemon and debug but + only logging daemon.warning via syslog.conf will + cause messages of severity info and + notice to + be dropped. If the situation were reversed, with named writing + messages of only warning or higher, + then syslogd would + print all messages it received from the channel. + + + + The stderr destination clause + directs the + channel to the server's standard error stream. This is intended + for + use when the server is running as a foreground process, for + example + when debugging a configuration. + + + + The server can supply extensive debugging information when + it is in debugging mode. If the server's global debug level is + greater + than zero, then debugging mode will be active. The global debug + level is set either by starting the named server + with the flag followed by a positive integer, + or by running rndc trace. + The global debug level + can be set to zero, and debugging mode turned off, by running ndc notrace. All debugging messages in the server have a debug -level, and higher debug levels give more detailed output. Channels -that specify a specific debug severity, for example: + level, and higher debug levels give more detailed output. Channels + that specify a specific debug severity, for example: + + channel specific_debug_level { file "foo"; severity debug 3; }; - will get debugging output of level 3 or less any time the -server is in debugging mode, regardless of the global debugging -level. Channels with dynamic severity use the -server's global debug level to determine what messages to print. - If print-time has been turned on, then -the date and time will be logged. print-time may -be specified for a syslog channel, but is usually -pointless since syslog also prints the date and -time. If print-category is requested, then the -category of the message will be logged as well. Finally, if print-severity is -on, then the severity level of the message will be logged. The print- options may -be used in any combination, and will always be printed in the following -order: time, category, severity. Here is an example where all three print- options -are on: - -28-Feb-2000 15:05:32.863 general: notice: running - -There are four predefined channels that are used for -named's default logging as follows. How they are -used is described in . - + + + will get debugging output of level 3 or less any time the + server is in debugging mode, regardless of the global debugging + level. Channels with dynamic + severity use the + server's global debug level to determine what messages to print. + + + If print-time has been turned on, + then + the date and time will be logged. print-time may + be specified for a syslog channel, + but is usually + pointless since syslog also prints + the date and + time. If print-category is + requested, then the + category of the message will be logged as well. Finally, if print-severity is + on, then the severity level of the message will be logged. The print- options may + be used in any combination, and will always be printed in the + following + order: time, category, severity. Here is an example where all + three print- options + are on: + + + + 28-Feb-2000 15:05:32.863 general: notice: running + + + + There are four predefined channels that are used for + named's default logging as follows. + How they are + used is described in . + channel default_syslog { syslog daemon; // send to syslog's daemon @@ -2484,37 +3857,56 @@ channel null { }; -The default_debug channel has the special -property that it only produces output when the server's debug level is -nonzero. It normally writes to a file named.run -in the server's working directory. - -For security reasons, when the "" -command line option is used, the named.run file -is created only after named has changed to the -new UID, and any debug output generated while named is -starting up and still running as root is discarded. If you need -to capture this output, you must run the server with the "" -option and redirect standard error to a file. - -Once a channel is defined, it cannot be redefined. Thus you -cannot alter the built-in channels directly, but you can modify -the default logging by pointing categories at channels you have defined. - - -The <command>category</command> Phrase - -There are many categories, so you can send the logs you want -to see wherever you want, without seeing logs you don't want. If -you don't specify a list of channels for a category, then log messages -in that category will be sent to the default category -instead. If you don't specify a default category, the following -"default default" is used: + + The default_debug channel has the + special + property that it only produces output when the server's debug + level is + nonzero. It normally writes to a file named.run + in the server's working directory. + + + + For security reasons, when the "" + command line option is used, the named.run file + is created only after named has + changed to the + new UID, and any debug output generated while named is + starting up and still running as root is discarded. If you need + to capture this output, you must run the server with the "" + option and redirect standard error to a file. + + + + Once a channel is defined, it cannot be redefined. Thus you + cannot alter the built-in channels directly, but you can modify + the default logging by pointing categories at channels you have + defined. + + + + + The <command>category</command> Phrase + + + There are many categories, so you can send the logs you want + to see wherever you want, without seeing logs you don't want. If + you don't specify a list of channels for a category, then log + messages + in that category will be sent to the default category + instead. If you don't specify a default category, the following + "default default" is used: + + category default { default_syslog; default_debug; }; -As an example, let's say you want to log security events to -a file, but you also want keep the default logging behavior. You'd -specify the following: + + + As an example, let's say you want to log security events to + a file, but you also want keep the default logging behavior. You'd + specify the following: + + channel my_security_channel { file "my_security_file"; severity info; @@ -2524,137 +3916,269 @@ category security { default_syslog; default_debug; }; -To discard all messages in a category, specify the null channel: + + + To discard all messages in a category, specify the null channel: + + category xfer-out { null; }; category notify { null; }; -Following are the available categories and brief descriptions -of the types of log information they contain. More -categories may be added in future BIND releases. - - - - - -default -The default category defines the logging -options for those categories where no specific configuration has been -defined. - - -general -The catch-all. Many things still aren't -classified into categories, and they all end up here. - - -database -Messages relating to the databases used -internally by the name server to store zone and cache data. - - -security -Approval and denial of requests. - - -config -Configuration file parsing and processing. - - -resolver -DNS resolution, such as the recursive -lookups performed on behalf of clients by a caching name server. - - -xfer-in -Zone transfers the server is receiving. - - -xfer-out -Zone transfers the server is sending. - - -notify -The NOTIFY protocol. - - -client -Processing of client requests. - - -unmatched -Messages that named was unable to determine the -class of or for which there was no matching view. -A one line summary is also logged to the client category. -This category is best sent to a file or stderr, by default it is sent to -the null channel. - - -network -Network operations. - - -update -Dynamic updates. - - -update-security -Approval and denial of update requests. - - -queries -Specify where queries should be logged to. - -At startup, specifing the category queries will also -enable query logging unless querylog option has been -specified. - - -The query log entry reports the client's IP address and port number. The -query name, class and type. It also reports whether the Recursion Desired -flag was set (+ if set, - if not set), EDNS was in use (E) or if the -query was signed (S). -client 127.0.0.1#62536: query: www.example.com IN AAAA +SE -client ::1#62537: query: www.example.net IN AAAA -SE - - - - -dispatch -Dispatching of incoming packets to the -server modules where they are to be processed. - - - -dnssec -DNSSEC and TSIG protocol processing. - - - -lame-servers -Lame servers. These are misconfigurations -in remote servers, discovered by BIND 9 when trying to query -those servers during resolution. - - - -delegation-only -Delegation only. Logs queries that have have -been forced to NXDOMAIN as the result of a delegation-only zone or -a delegation-only in a hint or stub zone declaration. - - - - - - - - -<command>lwres</command> Statement Grammar - - This is the grammar of the lwres -statement in the named.conf file: + + + Following are the available categories and brief descriptions + of the types of log information they contain. More + categories may be added in future BIND releases. + + + + + + + + + default + + + + The default category defines the logging + options for those categories where no specific + configuration has been + defined. + + + + + + general + + + + The catch-all. Many things still aren't + classified into categories, and they all end up here. + + + + + + database + + + + Messages relating to the databases used + internally by the name server to store zone and cache + data. + + + + + + security + + + + Approval and denial of requests. + + + + + + config + + + + Configuration file parsing and processing. + + + + + + resolver + + + + DNS resolution, such as the recursive + lookups performed on behalf of clients by a caching name + server. + + + + + + xfer-in + + + + Zone transfers the server is receiving. + + + + + + xfer-out + + + + Zone transfers the server is sending. + + + + + + notify + + + + The NOTIFY protocol. + + + + + + client + + + + Processing of client requests. + + + + + + unmatched + + + + Messages that named was unable to determine the + class of or for which there was no matching view. + A one line summary is also logged to the client category. + This category is best sent to a file or stderr, by + default it is sent to + the null channel. + + + + + + network + + + + Network operations. + + + + + + update + + + + Dynamic updates. + + + + + + update-security + + + + Approval and denial of update requests. + + + + + + queries + + + + Specify where queries should be logged to. + + + At startup, specifing the category queries will also + enable query logging unless querylog option has been + specified. + + + The query log entry reports the client's IP address and + port number. The + query name, class and type. It also reports whether the + Recursion Desired + flag was set (+ if set, - if not set), EDNS was in use + (E) or if the + query was signed (S). + + + client 127.0.0.1#62536: query: www.example.com IN AAAA +SE + + + client ::1#62537: query: www.example.net IN AAAA -SE + + + + + + dispatch + + + + Dispatching of incoming packets to the + server modules where they are to be processed. + + + + + + dnssec + + + + DNSSEC and TSIG protocol processing. + + + + + + lame-servers + + + + Lame servers. These are misconfigurations + in remote servers, discovered by BIND 9 when trying to + query + those servers during resolution. + + + + + + delegation-only + + + + Delegation only. Logs queries that have have + been forced to NXDOMAIN as the result of a + delegation-only zone or + a delegation-only in a + hint or stub zone declaration. + + + + + + + + + + + <command>lwres</command> Statement Grammar + + + This is the grammar of the lwres + statement in the named.conf file: + lwres { listen-on { ip_addr port ip_port ; ip_addr port ip_port ; ... }; @@ -2664,55 +4188,87 @@ statement in the named.conf file: }; - - -<command>lwres</command> Statement Definition and Usage - -The lwres statement configures the name -server to also act as a lightweight resolver server, see -. There may be be multiple -lwres statements configuring -lightweight resolver servers with different properties. - -The listen-on statement specifies a list of -addresses (and ports) that this instance of a lightweight resolver daemon -should accept requests on. If no port is specified, port 921 is used. -If this statement is omitted, requests will be accepted on 127.0.0.1, -port 921. - -The view statement binds this instance of a -lightweight resolver daemon to a view in the DNS namespace, so that the -response will be constructed in the same manner as a normal DNS query -matching this view. If this statement is omitted, the default view is -used, and if there is no default view, an error is triggered. - -The search statement is equivalent to the -search statement in -/etc/resolv.conf. It provides a list of domains -which are appended to relative names in queries. - -The ndots statement is equivalent to the -ndots statement in -/etc/resolv.conf. It indicates the minimum -number of dots in a relative domain name that should result in an -exact match lookup before search path elements are appended. - - - <command>masters</command> Statement Grammar + + + <command>lwres</command> Statement Definition and Usage + + + The lwres statement configures the + name + server to also act as a lightweight resolver server, see + . There may be be multiple + lwres statements configuring + lightweight resolver servers with different properties. + + + + The listen-on statement specifies a + list of + addresses (and ports) that this instance of a lightweight resolver + daemon + should accept requests on. If no port is specified, port 921 is + used. + If this statement is omitted, requests will be accepted on + 127.0.0.1, + port 921. + + + + The view statement binds this + instance of a + lightweight resolver daemon to a view in the DNS namespace, so that + the + response will be constructed in the same manner as a normal DNS + query + matching this view. If this statement is omitted, the default view + is + used, and if there is no default view, an error is triggered. + + + + The search statement is equivalent to + the + search statement in + /etc/resolv.conf. It provides a + list of domains + which are appended to relative names in queries. + + + + The ndots statement is equivalent to + the + ndots statement in + /etc/resolv.conf. It indicates the + minimum + number of dots in a relative domain name that should result in an + exact match lookup before search path elements are appended. + + + + <command>masters</command> Statement Grammar + masters name port ip_port { ( masters_list | ip_addr port ip_port key key ) ; ... } ; - - - <command>masters</command> Statement Definition and Usage -masters lists allow for a common set of masters -to be easily used by multiple stub and slave zones. - - -<command>options</command> Statement Grammar - -This is the grammar of the options -statement in the named.conf file: + + + + + <command>masters</command> Statement Definition and + Usage + masters + lists allow for a common set of masters to be easily used by + multiple stub and slave zones. + + + + + <command>options</command> Statement Grammar + + + This is the grammar of the options + statement in the named.conf file: + options { version version_string; @@ -2830,1265 +4386,2170 @@ statement in the named.conf file: max-acache-size size_spec ; }; - - -<command>options</command> Statement Definition and Usage - -The options statement sets up global options -to be used by BIND. This statement may appear only -once in a configuration file. If there is no options -statement, an options block with each option set to its default will -be used. - - - -directory -The working directory of the server. -Any non-absolute pathnames in the configuration file will be taken -as relative to this directory. The default location for most server -output files (e.g. named.run) is this directory. -If a directory is not specified, the working directory defaults -to `.', the directory from which the server -was started. The directory specified should be an absolute path. - - -key-directory -When performing dynamic update of secure zones, the -directory where the public and private key files should be found, -if different than the current working directory. The directory specified -must be an absolute path. - - -named-xfer -This option is obsolete. -It was used in BIND 8 to -specify the pathname to the named-xfer program. -In BIND 9, no separate named-xfer program is -needed; its functionality is built into the name server. - - - -tkey-domain -The domain appended to the names of all -shared keys generated with TKEY. When a client -requests a TKEY exchange, it may or may not specify -the desired name for the key. If present, the name of the shared -key will be "client specified part" + -"tkey-domain". -Otherwise, the name of the shared key will be "random hex + + + + + <command>options</command> Statement Definition and + Usage + + + The options statement sets up global + options + to be used by BIND. This statement + may appear only + once in a configuration file. If there is no options + statement, an options block with each option set to its default will + be used. + + + + + + directory + + + The working directory of the server. + Any non-absolute pathnames in the configuration file will be + taken + as relative to this directory. The default location for most + server + output files (e.g. named.run) + is this directory. + If a directory is not specified, the working directory + defaults + to `.', the directory from + which the server + was started. The directory specified should be an absolute + path. + + + + + + key-directory + + + When performing dynamic update of secure zones, the + directory where the public and private key files should be + found, + if different than the current working directory. The + directory specified + must be an absolute path. + + + + + + named-xfer + + + This option is obsolete. + It was used in BIND 8 to + specify the pathname to the named-xfer program. + In BIND 9, no separate named-xfer program is + needed; its functionality is built into the name server. + + + + + + + tkey-domain + + + The domain appended to the names of all + shared keys generated with + TKEY. When a client + requests a TKEY exchange, it + may or may not specify + the desired name for the key. If present, the name of the + shared + key will be "client specified part" + + "tkey-domain". + Otherwise, the name of the shared key will be "random hex digits" + "tkey-domain". In most cases, -the domainname should be the server's domain -name. - - -tkey-dhkey -The Diffie-Hellman key used by the server -to generate shared keys with clients using the Diffie-Hellman mode -of TKEY. The server must be able to load the -public and private keys from files in the working directory. In -most cases, the keyname should be the server's host name. - - -dump-file -The pathname of the file the server dumps -the database to when instructed to do so with -rndc dumpdb. -If not specified, the default is named_dump.db. - -memstatistics-file -The pathname of the file the server writes memory -usage statistics to on exit. If not specified, -the default is named.memstats. - - -pid-file -The pathname of the file the server writes its process ID -in. If not specified, the default is /var/run/named.pid. -The pid-file is used by programs that want to send signals to the running -name server. Specifying pid-file none disables the -use of a PID file — no file will be written and any -existing one will be removed. Note that none -is a keyword, not a file name, and therefore is not enclosed in -double quotes. - - -statistics-file -The pathname of the file the server appends statistics -to when instructed to do so using rndc stats. -If not specified, the default is named.stats in the -server's current directory. The format of the file is described -in - - -port - -The UDP/TCP port number the server uses for -receiving and sending DNS protocol traffic. -The default is 53. This option is mainly intended for server testing; -a server using a port other than 53 will not be able to communicate with -the global DNS. - - - -random-device - -The source of entropy to be used by the server. Entropy is primarily needed -for DNSSEC operations, such as TKEY transactions and dynamic update of signed -zones. This options specifies the device (or file) from which to read -entropy. If this is a file, operations requiring entropy will fail when the -file has been exhausted. If not specified, the default value is -/dev/random -(or equivalent) when present, and none otherwise. The -random-device option takes effect during -the initial configuration load at server startup time and -is ignored on subsequent reloads. - - -preferred-glue - -If specified the listed type (A or AAAA) will be emitted before other glue -in the additional section of a query response. -The default is not to preference any type (NONE). - - - -root-delegation-only - -Turn on enforcement of delegation-only in TLDs and root zones with an optional -exclude list. - - -Note some TLDs are NOT delegation only (e.g. "DE", "LV", "US" and "MUSEUM"). - + the domainname should be the + server's domain + name. + + + + + + tkey-dhkey + + + The Diffie-Hellman key used by the server + to generate shared keys with clients using the Diffie-Hellman + mode + of TKEY. The server must be + able to load the + public and private keys from files in the working directory. + In + most cases, the keyname should be the server's host name. + + + + + + dump-file + + + The pathname of the file the server dumps + the database to when instructed to do so with + rndc dumpdb. + If not specified, the default is named_dump.db. + + + + + memstatistics-file + + + The pathname of the file the server writes memory + usage statistics to on exit. If not specified, + the default is + named.memstats. + + + + + + pid-file + + + The pathname of the file the server writes its process ID + in. If not specified, the default is /var/run/named.pid. + The pid-file is used by programs that want to send signals to + the running + name server. Specifying pid-file none disables the + use of a PID file — no file will be written and any + existing one will be removed. Note that none + is a keyword, not a file name, and therefore is not enclosed + in + double quotes. + + + + + + statistics-file + + + The pathname of the file the server appends statistics + to when instructed to do so using rndc stats. + If not specified, the default is named.stats in the + server's current directory. The format of the file is + described + in + + + + + + port + + + The UDP/TCP port number the server uses for + receiving and sending DNS protocol traffic. + The default is 53. This option is mainly intended for server + testing; + a server using a port other than 53 will not be able to + communicate with + the global DNS. + + + + + + random-device + + + The source of entropy to be used by the server. Entropy is + primarily needed + for DNSSEC operations, such as TKEY transactions and dynamic + update of signed + zones. This options specifies the device (or file) from which + to read + entropy. If this is a file, operations requiring entropy will + fail when the + file has been exhausted. If not specified, the default value + is + /dev/random + (or equivalent) when present, and none otherwise. The + random-device option takes + effect during + the initial configuration load at server startup time and + is ignored on subsequent reloads. + + + + + + preferred-glue + + + If specified the listed type (A or AAAA) will be emitted + before other glue + in the additional section of a query response. + The default is not to preference any type (NONE). + + + + + + root-delegation-only + + + Turn on enforcement of delegation-only in TLDs and root zones + with an optional + exclude list. + + + Note some TLDs are NOT delegation only (e.g. "DE", "LV", "US" + and "MUSEUM"). + + options { root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; }; - - -disable-algorithms - -Disable the specified DNSSEC algorithms at and below the specified name. -Multiple disable-algorithms statements are allowed. -Only the most specific will be applied. - - -dnssec-lookaside - -When set dnssec-lookaside provides the -validator with an alternate method to validate DNSKEY records at the -top of a zone. When a DNSKEY is at or below a domain specified by the -deepest dnssec-lookaside, and the normal dnssec validation -has left the key untrusted, the trust-anchor will be append to the key -name and a DLV record will be looked up to see if it can validate the -key. If the DLV record validates a DNSKEY (similarly to the way a DS -record does) the DNSKEY RRset is deemed to be trusted. - - -dnssec-must-be-secure - -Specify heirachies which must / may not be secure (signed and validated). -If yes then named will only accept answers if they -are secure. -If no then normal dnssec validation applies -allowing for insecure answers to be accepted. -The specified domain must be under a trusted-key or -dnssec-lookaside must be active. - - - - -Boolean Options - - - -auth-nxdomain -If yes, then the AA bit -is always set on NXDOMAIN responses, even if the server is not actually -authoritative. The default is no; this is -a change from BIND 8. If you are using very old DNS software, you -may need to set it to yes. - -deallocate-on-exit -This option was used in BIND 8 to enable checking -for memory leaks on exit. BIND 9 ignores the option and always performs -the checks. - -dialup -If yes, then the -server treats all zones as if they are doing zone transfers across -a dial on demand dialup link, which can be brought up by traffic -originating from this server. This has different effects according -to zone type and concentrates the zone maintenance so that it all -happens in a short interval, once every heartbeat-interval and -hopefully during the one call. It also suppresses some of the normal -zone maintenance traffic. The default is no. -The dialup option -may also be specified in the view and -zone statements, -in which case it overrides the global dialup -option. -If the zone is a master zone then the server will send out a NOTIFY -request to all the slaves (default). This should trigger the zone serial -number check in the slave (providing it supports NOTIFY) allowing the slave -to verify the zone while the connection is active. -The set of servers to which NOTIFY is sent can be controlled by -notify and also-notify. -If the -zone is a slave or stub zone, then the server will suppress the regular -"zone up to date" (refresh) queries and only perform them when the -heartbeat-interval expires in addition to sending -NOTIFY requests.Finer control can be achieved by using -notify which only sends NOTIFY messages, -notify-passive which sends NOTIFY messages and -suppresses the normal refresh queries, refresh -which suppresses normal refresh processing and sends refresh queries -when the heartbeat-interval expires, and -passive which just disables normal refresh -processing. - - - - - - - - - -dialup mode -normal refresh -heart-beat refresh -heart-beat notify - - -no (default) -yes -no -no - - -yes -no -yes -yes - - -notify -yes -no -yes - - -refresh -no -yes -no - - -passive -no -no -no - - -notify-passive -no -no -yes - - - - -Note that normal NOTIFY processing is not affected by -dialup. - - - -fake-iquery -In BIND 8, this option -enabled simulating the obsolete DNS query type -IQUERY. BIND 9 never does IQUERY simulation. - - -fetch-glue -This option is obsolete. -In BIND 8, fetch-glue yes -caused the server to attempt to fetch glue resource records it -didn't have when constructing the additional -data section of a response. This is now considered a bad idea -and BIND 9 never does it. - -flush-zones-on-shutdown -When the nameserver exits due receiving SIGTERM, -flush / do not flush any pending zone writes. The default is -flush-zones-on-shutdown no. - - -has-old-clients -This option was incorrectly implemented -in BIND 8, and is ignored by BIND 9. -To achieve the intended effect -of -has-old-clients yes, specify -the two separate options auth-nxdomain yes -and rfc2308-type1 no instead. - - -host-statistics -In BIND 8, this enables keeping of -statistics for every host that the name server interacts with. -Not implemented in BIND 9. - - -maintain-ixfr-base -This option is obsolete. - It was used in BIND 8 to determine whether a transaction log was -kept for Incremental Zone Transfer. BIND 9 maintains a transaction -log whenever possible. If you need to disable outgoing incremental zone -transfers, use provide-ixfr no. - - -minimal-responses -If yes, then when generating -responses the server will only add records to the authority and -additional data sections when they are required (e.g. delegations, -negative responses). This may improve the performance of the server. -The default is no. - - -multiple-cnames -This option was used in BIND 8 to allow -a domain name to have multiple CNAME records in violation of the -DNS standards. BIND 9.2 always strictly -enforces the CNAME rules both in master files and dynamic updates. - - -notify -If yes (the default), -DNS NOTIFY messages are sent when a zone the server is authoritative for -changes, see . The messages are sent to the -servers listed in the zone's NS records (except the master server identified -in the SOA MNAME field), and to any servers listed in the -also-notify option. - -If master-only, notifies are only sent -for master zones. -If explicit, notifies are sent only to -servers explicitly listed using also-notify. -If no, no notifies are sent. - -The notify option may also be -specified in the zone statement, -in which case it overrides the options notify statement. -It would only be necessary to turn off this option if it caused slaves -to crash. - -recursion -If yes, and a -DNS query requests recursion, then the server will attempt to do -all the work required to answer the query. If recursion is off -and the server does not already know the answer, it will return a -referral response. The default is yes. -Note that setting recursion no does not prevent -clients from getting data from the server's cache; it only -prevents new data from being cached as an effect of client queries. -Caching may still occur as an effect the server's internal -operation, such as NOTIFY address lookups. -See also fetch-glue above. - - -rfc2308-type1 -Setting this to yes will -cause the server to send NS records along with the SOA record for negative -answers. The default is no. -Not yet implemented in BIND 9. - - -use-id-pool -This option is obsolete. -BIND 9 always allocates query IDs from a pool. - - -zone-statistics -If yes, the server will collect -statistical data on all zones (unless specifically turned off -on a per-zone basis by specifying zone-statistics no -in the zone statement). These statistics may be accessed -using rndc stats, which will dump them to the file listed -in the statistics-file. See also . - - -use-ixfr -This option is obsolete. -If you need to disable IXFR to a particular server or servers see -the information on the provide-ixfr option -in . See also -. - - -provide-ixfr - - -See the description of -provide-ixfr in - - - -request-ixfr - - -See the description of -request-ixfr in - - - -treat-cr-as-space -This option was used in BIND 8 to make -the server treat carriage return ("\r") characters the same way -as a space or tab character, -to facilitate loading of zone files on a UNIX system that were generated -on an NT or DOS machine. In BIND 9, both UNIX "\n" -and NT/DOS "\r\n" newlines are always accepted, -and the option is ignored. - - -additional-from-auth -additional-from-cache - - - -These options control the behavior of an authoritative server when -answering queries which have additional data, or when following CNAME -and DNAME chains. - - - -When both of these options are set to yes -(the default) and a -query is being answered from authoritative data (a zone -configured into the server), the additional data section of the -reply will be filled in using data from other authoritative zones -and from the cache. In some situations this is undesirable, such -as when there is concern over the correctness of the cache, or -in servers where slave zones may be added and modified by -untrusted third parties. Also, avoiding -the search for this additional data will speed up server operations -at the possible expense of additional queries to resolve what would -otherwise be provided in the additional section. - - - -For example, if a query asks for an MX record for host foo.example.com, -and the record found is "MX 10 mail.example.net", normally the address -records (A and AAAA) for mail.example.net will be provided as well, -if known, even though they are not in the example.com zone. -Setting these options to no disables this behavior and makes -the server only search for additional data in the zone it answers from. - - - -These options are intended for use in authoritative-only -servers, or in authoritative-only views. Attempts to set -them to no without also specifying -recursion no will cause the server to -ignore the options and log a warning message. - - - -Specifying additional-from-cache no actually -disables the use of the cache not only for additional data lookups -but also when looking up the answer. This is usually the desired -behavior in an authoritative-only server where the correctness of -the cached data is an issue. - - - -When a name server is non-recursively queried for a name that is not -below the apex of any served zone, it normally answers with an -"upwards referral" to the root servers or the servers of some other -known parent of the query name. Since the data in an upwards referral -comes from the cache, the server will not be able to provide upwards -referrals when additional-from-cache no -has been specified. Instead, it will respond to such queries -with REFUSED. This should not cause any problems since -upwards referrals are not required for the resolution process. - - - - -match-mapped-addresses -If yes, then an -IPv4-mapped IPv6 address will match any address match -list entries that match the corresponding IPv4 address. -Enabling this option is sometimes useful on IPv6-enabled Linux -systems, to work around a kernel quirk that causes IPv4 -TCP connections such as zone transfers to be accepted -on an IPv6 socket using mapped addresses, causing -address match lists designed for IPv4 to fail to match. -The use of this option for any other purpose is discouraged. - - -ixfr-from-differences - - -When 'yes' and the server loads a new version of a master -zone from its zone file or receives a new version of a slave -file by a non-incremental zone transfer, it will compare -the new version to the previous one and calculate a set -of differences. The differences are then logged in the -zone's journal file such that the changes can be transmitted -to downstream slaves as an incremental zone transfer. - -By allowing incremental zone transfers to be used for -non-dynamic zones, this option saves bandwidth at the -expense of increased CPU and memory consumption at the master. -In particular, if the new version of a zone is completely -different from the previous one, the set of differences -will be of a size comparable to the combined size of the -old and new zone version, and the server will need to -temporarily allocate memory to hold this complete -difference set. - -ixfr-from-differences also accepts master -and slave at the view and options levels which causes -ixfr-from-differences to apply to all master -or slave zones respectively. - - -multi-master - - -This should be set when you have multiple masters for a zone and the -addresses refer to different machines. If 'yes' named will not log -when the serial number on the master is less than what named currently -has. The default is no. - - -dnssec-enable - - -Enable DNSSEC support in named. Unless set to yes -named behaves as if it does not support DNSSEC. -The default is no. - - -querylog - - -Specify whether query logging should be started when named start. -If querylog is not specified then the query logging -is determined by the presence of the logging category queries. - - -check-names - - -This option is used to restrict the character set and syntax of -certain domain names in master files and/or DNS responses received -from the network. The default varies according to usage area. For -master zones the default is fail. -For slave zones the default is warn. -For answer received from the network (response) -the default is ignore. - -The rules for legal hostnames / mail domains are derived from RFC 952 -and RFC 821 as modified by RFC 1123. - -check-names applies to the owner names of A, AAA and -MX records. It also applies to the domain names in the RDATA of NS, SOA and MX -records. It also applies to the RDATA of PTR records where the owner name -indicated that it is a reverse lookup of a hostname (the owner name ends in -IN-ADDR.ARPA, IP6.ARPA, IP6.INT). - - - -check-wildcard - -This option is used to check for non-terminal wildcards. -The use of non-terminal wildcards is almost always as a result of a failure -to understand the wildcard matching algorithm (RFC 1034). This option -affects master zones. The default (yes) is to check -for non-terminal wildcards and issue a warning. - - - - - - - -Forwarding -The forwarding facility can be used to create a large site-wide -cache on a few servers, reducing traffic over links to external -name servers. It can also be used to allow queries by servers that -do not have direct access to the Internet, but wish to look up exterior -names anyway. Forwarding occurs only on those queries for which -the server is not authoritative and does not have the answer in -its cache. - - -forward -This option is only meaningful if the -forwarders list is not empty. A value of first, -the default, causes the server to query the forwarders first, and -if that doesn't answer the question the server will then look for -the answer itself. If only is specified, the -server will only query the forwarders. - - -forwarders -Specifies the IP addresses to be used -for forwarding. The default is the empty list (no forwarding). - - - - -Forwarding can also be configured on a per-domain basis, allowing -for the global forwarding options to be overridden in a variety -of ways. You can set particular domains to use different forwarders, -or have a different forward only/first behavior, -or not forward at all, see . - - -Dual-stack Servers -Dual-stack servers are used as servers of last resort to work around -problems in reachability due the lack of support for either IPv4 or IPv6 -on the host machine. - - -dual-stack-servers -Specifies host names / addresses of machines with access to -both IPv4 and IPv6 transports. If a hostname is used the server must be able -to resolve the name using only the transport it has. If the machine is dual -stacked then the dual-stack-servers have no effect unless -access to a transport has been disabled on the command line -(e.g. named -4). - - - - -Access Control - -Access to the server can be restricted based on the IP address -of the requesting system. See for -details on how to specify IP address lists. - - - -allow-notify -Specifies which hosts are allowed to -notify this server, a slave, of zone changes in addition -to the zone masters. -allow-notify may also be specified in the -zone statement, in which case it overrides the -options allow-notify statement. It is only meaningful -for a slave zone. If not specified, the default is to process notify messages -only from a zone's master. - - -allow-query -Specifies which hosts are allowed to -ask ordinary DNS questions. allow-query may also -be specified in the zone statement, in which -case it overrides the options allow-query statement. -allow-query-cache may also be specified and will -overrides access to the cache. -If not specified, the default is to allow queries from all hosts. - - -allow-query-cache -Specifies which hosts are allowed to get answers -from the cache. If not set allow-query applies. - -The recommended way to set query access to the cache is now via -allow-query-cache rather than allow-query. -Inheritance from allow-query has been retained for -backwards compatability. - -If allow-query-cache is set at the options -level and not set in the view it will still override a -allow-query set at the view level. - - - - -allow-recursion -Specifies which hosts are allowed to -make recursive queries through this server. If not specified, the -default is to allow recursive queries from all hosts. -Note that disallowing recursive queries for a host does not prevent the -host from retrieving data that is already in the server's cache. - - - -allow-update -Specifies which hosts are allowed to -submit Dynamic DNS updates for master zones. The default is to deny -updates from all hosts. Note that allowing updates based -on the requestor's IP address is insecure; see - for details. - - - -allow-update-forwarding -Specifies which hosts are allowed to -submit Dynamic DNS updates to slave zones to be forwarded to the -master. The default is { none; }, which -means that no update forwarding will be performed. To enable -update forwarding, specify -allow-update-forwarding { any; };. -Specifying values other than { none; } or -{ any; } is usually counterproductive, since -the responsibility for update access control should rest with the -master server, not the slaves. -Note that enabling the update forwarding feature on a slave server -may expose master servers relying on insecure IP address based -access control to attacks; see -for more details. - - -allow-v6-synthesis -This option was introduced for the smooth transition from AAAA -to A6 and from "nibble labels" to binary labels. -However, since both A6 and binary labels were then deprecated, -this option was also deprecated. -It is now ignored with some warning messages. - - - -allow-transfer -Specifies which hosts are allowed to -receive zone transfers from the server. allow-transfer may -also be specified in the zone statement, in which -case it overrides the options allow-transfer statement. -If not specified, the default is to allow transfers to all hosts. - - -blackhole -Specifies a list of addresses that the -server will not accept queries from or use to resolve a query. Queries -from these addresses will not be responded to. The default is none. - - - - - - -Interfaces -The interfaces and ports that the server will answer queries -from may be specified using the listen-on option. listen-on takes -an optional port, and an address_match_list. -The server will listen on all interfaces allowed by the address -match list. If a port is not specified, port 53 will be used. -Multiple listen-on statements are allowed. -For example, -listen-on { 5.6.7.8; }; -listen-on port 1234 { !1.2.3.4; 1.2/16; }; - + + -will enable the name server on port 53 for the IP address -5.6.7.8, and on port 1234 of an address on the machine in net -1.2 that is not 1.2.3.4. + + disable-algorithms + + + Disable the specified DNSSEC algorithms at and below the + specified name. + Multiple disable-algorithms + statements are allowed. + Only the most specific will be applied. + + + -If no listen-on is specified, the -server will listen on port 53 on all interfaces. + + dnssec-lookaside + + + When set dnssec-lookaside + provides the + validator with an alternate method to validate DNSKEY records + at the + top of a zone. When a DNSKEY is at or below a domain + specified by the + deepest dnssec-lookaside, and + the normal dnssec validation + has left the key untrusted, the trust-anchor will be append to + the key + name and a DLV record will be looked up to see if it can + validate the + key. If the DLV record validates a DNSKEY (similarly to the + way a DS + record does) the DNSKEY RRset is deemed to be trusted. + + + -The listen-on-v6 option is used to -specify the interfaces and the ports on which the server will listen -for incoming queries sent using IPv6. + + dnssec-must-be-secure + + + Specify heirachies which must / may not be secure (signed and + validated). + If yes then named will only accept + answers if they + are secure. + If no then normal dnssec validation + applies + allowing for insecure answers to be accepted. + The specified domain must be under a trusted-key or + dnssec-lookaside must be + active. + + + + + -When { any; } is specified -as the address_match_list for the -listen-on-v6 option, -the server does not bind a separate socket to each IPv6 interface -address as it does for IPv4 if the operating system has enough API -support for IPv6 (specifically if it conforms to RFC 3493 and RFC 3542). -Instead, it listens on the IPv6 wildcard address. -If the system only has incomplete API support for IPv6, however, -the behavior is the same as that for IPv4. + + Boolean Options + + + + + auth-nxdomain + + + If yes, then the AA bit + is always set on NXDOMAIN responses, even if the server is + not actually + authoritative. The default is no; + this is + a change from BIND 8. If you + are using very old DNS software, you + may need to set it to yes. + + + + + + deallocate-on-exit + + + This option was used in BIND + 8 to enable checking + for memory leaks on exit. BIND 9 ignores the option and always performs + the checks. + + + + + + dialup + + + If yes, then the + server treats all zones as if they are doing zone transfers + across + a dial on demand dialup link, which can be brought up by + traffic + originating from this server. This has different effects + according + to zone type and concentrates the zone maintenance so that + it all + happens in a short interval, once every heartbeat-interval and + hopefully during the one call. It also suppresses some of + the normal + zone maintenance traffic. The default is no. + + + The dialup option + may also be specified in the view and + zone statements, + in which case it overrides the global dialup + option. + + + If the zone is a master zone then the server will send out a + NOTIFY + request to all the slaves (default). This should trigger the + zone serial + number check in the slave (providing it supports NOTIFY) + allowing the slave + to verify the zone while the connection is active. + The set of servers to which NOTIFY is sent can be controlled + by + notify and also-notify. + + + If the + zone is a slave or stub zone, then the server will suppress + the regular + "zone up to date" (refresh) queries and only perform them + when the + heartbeat-interval expires in + addition to sending + NOTIFY requests. + + + Finer control can be achieved by using + notify which only sends NOTIFY + messages, + notify-passive which sends NOTIFY + messages and + suppresses the normal refresh queries, refresh + which suppresses normal refresh processing and sends refresh + queries + when the heartbeat-interval + expires, and + passive which just disables normal + refresh + processing. + + + + + + + + + + + + + dialup mode + + + + + normal refresh + + + + + heart-beat refresh + + + + + heart-beat notify + + + + + + no (default) + + + + yes + + + + + no + + + + + no + + + + + + yes + + + + no + + + + + yes + + + + + yes + + + + + + notify + + + + yes + + + + + no + + + + + yes + + + + + + refresh + + + + no + + + + + yes + + + + + no + + + + + + passive + + + + no + + + + + no + + + + + no + + + + + + notify-passive + + + + no + + + + + no + + + + + yes + + + + + + + + + Note that normal NOTIFY processing is not affected by + dialup. + + + + + + + fake-iquery + + + In BIND 8, this option + enabled simulating the obsolete DNS query type + IQUERY. BIND 9 never does + IQUERY simulation. + + + + + + fetch-glue + + + This option is obsolete. + In BIND 8, fetch-glue yes + caused the server to attempt to fetch glue resource records + it + didn't have when constructing the additional + data section of a response. This is now considered a bad + idea + and BIND 9 never does it. + + + + + + flush-zones-on-shutdown + + + When the nameserver exits due receiving SIGTERM, + flush / do not flush any pending zone writes. The default + is + flush-zones-on-shutdown no. + + + + + + has-old-clients + + + This option was incorrectly implemented + in BIND 8, and is ignored by BIND 9. + To achieve the intended effect + of + has-old-clients yes, specify + the two separate options auth-nxdomain yes + and rfc2308-type1 no instead. + + + + + + host-statistics + + + In BIND 8, this enables keeping of + statistics for every host that the name server interacts + with. + Not implemented in BIND 9. + + + + + + maintain-ixfr-base + + + This option is obsolete. + It was used in BIND 8 to + determine whether a transaction log was + kept for Incremental Zone Transfer. BIND 9 maintains a transaction + log whenever possible. If you need to disable outgoing + incremental zone + transfers, use provide-ixfr no. + + + + + + minimal-responses + + + If yes, then when generating + responses the server will only add records to the authority + and + additional data sections when they are required (e.g. + delegations, + negative responses). This may improve the performance of + the server. + The default is no. + + + + + + multiple-cnames + + + This option was used in BIND + 8 to allow + a domain name to have multiple CNAME records in violation of + the + DNS standards. BIND 9.2 + always strictly + enforces the CNAME rules both in master files and dynamic + updates. + + + + + + notify + + + If yes (the default), + DNS NOTIFY messages are sent when a zone the server is + authoritative for + changes, see . The messages are + sent to the + servers listed in the zone's NS records (except the master + server identified + in the SOA MNAME field), and to any servers listed in the + also-notify option. + + + If master-only, notifies are only + sent + for master zones. + If explicit, notifies are sent only + to + servers explicitly listed using also-notify. + If no, no notifies are sent. + + + The notify option may also be + specified in the zone + statement, + in which case it overrides the options notify statement. + It would only be necessary to turn off this option if it + caused slaves + to crash. + + + + + + recursion + + + If yes, and a + DNS query requests recursion, then the server will attempt + to do + all the work required to answer the query. If recursion is + off + and the server does not already know the answer, it will + return a + referral response. The default is + yes. + Note that setting recursion no does not prevent + clients from getting data from the server's cache; it only + prevents new data from being cached as an effect of client + queries. + Caching may still occur as an effect the server's internal + operation, such as NOTIFY address lookups. + See also fetch-glue above. + + + + + + rfc2308-type1 + + + Setting this to yes will + cause the server to send NS records along with the SOA + record for negative + answers. The default is no. + + + + Not yet implemented in BIND + 9. + + + + + + + use-id-pool + + + This option is obsolete. + BIND 9 always allocates query + IDs from a pool. + + + + + + zone-statistics + + + If yes, the server will collect + statistical data on all zones (unless specifically turned + off + on a per-zone basis by specifying zone-statistics no + in the zone statement). + These statistics may be accessed + using rndc stats, which will + dump them to the file listed + in the statistics-file. See + also . + + + + + + use-ixfr + + + This option is obsolete. + If you need to disable IXFR to a particular server or + servers see + the information on the provide-ixfr option + in . + See also + . + + + + + + provide-ixfr + + + See the description of + provide-ixfr in + + + + + + + request-ixfr + + + See the description of + request-ixfr in + + + + + + + treat-cr-as-space + + + This option was used in BIND + 8 to make + the server treat carriage return ("\r") characters the same way + as a space or tab character, + to facilitate loading of zone files on a UNIX system that + were generated + on an NT or DOS machine. In BIND 9, both UNIX "\n" + and NT/DOS "\r\n" newlines + are always accepted, + and the option is ignored. + + + + + + additional-from-auth + additional-from-cache + + + + These options control the behavior of an authoritative + server when + answering queries which have additional data, or when + following CNAME + and DNAME chains. + + + + When both of these options are set to yes + (the default) and a + query is being answered from authoritative data (a zone + configured into the server), the additional data section of + the + reply will be filled in using data from other authoritative + zones + and from the cache. In some situations this is undesirable, + such + as when there is concern over the correctness of the cache, + or + in servers where slave zones may be added and modified by + untrusted third parties. Also, avoiding + the search for this additional data will speed up server + operations + at the possible expense of additional queries to resolve + what would + otherwise be provided in the additional section. + + + + For example, if a query asks for an MX record for host foo.example.com, + and the record found is "MX 10 mail.example.net", normally the address + records (A and AAAA) for mail.example.net will be provided as well, + if known, even though they are not in the example.com zone. + Setting these options to no + disables this behavior and makes + the server only search for additional data in the zone it + answers from. + + + + These options are intended for use in authoritative-only + servers, or in authoritative-only views. Attempts to set + them to no without also + specifying + recursion no will cause the + server to + ignore the options and log a warning message. + + + + Specifying additional-from-cache no actually + disables the use of the cache not only for additional data + lookups + but also when looking up the answer. This is usually the + desired + behavior in an authoritative-only server where the + correctness of + the cached data is an issue. + + + + When a name server is non-recursively queried for a name + that is not + below the apex of any served zone, it normally answers with + an + "upwards referral" to the root servers or the servers of + some other + known parent of the query name. Since the data in an + upwards referral + comes from the cache, the server will not be able to provide + upwards + referrals when additional-from-cache no + has been specified. Instead, it will respond to such + queries + with REFUSED. This should not cause any problems since + upwards referrals are not required for the resolution + process. + + + + + + + match-mapped-addresses + + + If yes, then an + IPv4-mapped IPv6 address will match any address match + list entries that match the corresponding IPv4 address. + Enabling this option is sometimes useful on IPv6-enabled + Linux + systems, to work around a kernel quirk that causes IPv4 + TCP connections such as zone transfers to be accepted + on an IPv6 socket using mapped addresses, causing + address match lists designed for IPv4 to fail to match. + The use of this option for any other purpose is discouraged. + + + + + + ixfr-from-differences + + + When 'yes' and the server loads a new version of a master + zone from its zone file or receives a new version of a slave + file by a non-incremental zone transfer, it will compare + the new version to the previous one and calculate a set + of differences. The differences are then logged in the + zone's journal file such that the changes can be transmitted + to downstream slaves as an incremental zone transfer. + + + By allowing incremental zone transfers to be used for + non-dynamic zones, this option saves bandwidth at the + expense of increased CPU and memory consumption at the + master. + In particular, if the new version of a zone is completely + different from the previous one, the set of differences + will be of a size comparable to the combined size of the + old and new zone version, and the server will need to + temporarily allocate memory to hold this complete + difference set. + + ixfr-from-differences + also accepts master and + slave at the view and options + levels which causes + ixfr-from-differences to apply to + all master or + slave zones respectively. + + + + + + multi-master + + + This should be set when you have multiple masters for a zone + and the + addresses refer to different machines. If 'yes' named will + not log + when the serial number on the master is less than what named + currently + has. The default is no. + + + + + + dnssec-enable + + + Enable DNSSEC support in named. Unless set to yes + named behaves as if it does not support DNSSEC. + The default is no. + + + + + + querylog + + + Specify whether query logging should be started when named + start. + If querylog is not specified + then the query logging + is determined by the presence of the logging category queries. + + + + + + check-names + + + This option is used to restrict the character set and syntax + of + certain domain names in master files and/or DNS responses + received + from the network. The default varies according to usage + area. For + master zones the default is fail. + For slave zones the default + is warn. + For answer received from the network (response) + the default is ignore. + + + The rules for legal hostnames / mail domains are derived + from RFC 952 + and RFC 821 as modified by RFC 1123. + + check-names + applies to the owner names of A, AAA and + MX records. It also applies to the domain names in the + RDATA of NS, SOA and MX + records. It also applies to the RDATA of PTR records where + the owner name + indicated that it is a reverse lookup of a hostname (the + owner name ends in + IN-ADDR.ARPA, IP6.ARPA, IP6.INT). + + + + + + check-wildcard + + + This option is used to check for non-terminal wildcards. + The use of non-terminal wildcards is almost always as a + result of a failure + to understand the wildcard matching algorithm (RFC 1034). + This option + affects master zones. The default (yes) is to check + for non-terminal wildcards and issue a warning. + + + + + + + + + + Forwarding + + The forwarding facility can be used to create a large site-wide + cache on a few servers, reducing traffic over links to external + name servers. It can also be used to allow queries by servers that + do not have direct access to the Internet, but wish to look up + exterior + names anyway. Forwarding occurs only on those queries for which + the server is not authoritative and does not have the answer in + its cache. + + + + + forward + + + This option is only meaningful if the + forwarders list is not empty. A value of first, + the default, causes the server to query the forwarders + first, and + if that doesn't answer the question the server will then + look for + the answer itself. If only is + specified, the + server will only query the forwarders. + + + + + + forwarders + + + Specifies the IP addresses to be used + for forwarding. The default is the empty list (no + forwarding). + + + + + + + + Forwarding can also be configured on a per-domain basis, allowing + for the global forwarding options to be overridden in a variety + of ways. You can set particular domains to use different + forwarders, + or have a different forward only/first behavior, + or not forward at all, see . + + + + + Dual-stack Servers + + Dual-stack servers are used as servers of last resort to work + around + problems in reachability due the lack of support for either IPv4 + or IPv6 + on the host machine. + + + + + dual-stack-servers + + + Specifies host names / addresses of machines with access to + both IPv4 and IPv6 transports. If a hostname is used the + server must be able + to resolve the name using only the transport it has. If the + machine is dual + stacked then the dual-stack-servers have no effect unless + access to a transport has been disabled on the command line + (e.g. named -4). + + + + + + + + Access Control + + + Access to the server can be restricted based on the IP address + of the requesting system. See for + details on how to specify IP address lists. + + + + + + allow-notify + + + Specifies which hosts are allowed to + notify this server, a slave, of zone changes in addition + to the zone masters. + allow-notify may also be + specified in the + zone statement, in which case + it overrides the + options allow-notify + statement. It is only meaningful + for a slave zone. If not specified, the default is to + process notify messages + only from a zone's master. + + + + + + allow-query + + + Specifies which hosts are allowed to + ask ordinary DNS questions. allow-query may also + be specified in the zone + statement, in which + case it overrides the options allow-query statement. + allow-query-cache may also be + specified and will + overrides access to the cache. + If not specified, the default is to allow queries from all + hosts. + + + + + + allow-query-cache + + + Specifies which hosts are allowed to get answers + from the cache. If not set allow-query applies. + + + The recommended way to set query access to the cache is now + via + allow-query-cache rather than + allow-query. + Inheritance from allow-query + has been retained for + backwards compatability. + + + + If allow-query-cache is set + at the options + level and not set in the view it will still override a + allow-query set at the view + level. + + + + + + + allow-recursion + + + Specifies which hosts are allowed to + make recursive queries through this server. If not + specified, the + default is to allow recursive queries from all hosts. + Note that disallowing recursive queries for a host does not + prevent the + host from retrieving data that is already in the server's + cache. + + + + + + allow-update + + + Specifies which hosts are allowed to + submit Dynamic DNS updates for master zones. The default is + to deny + updates from all hosts. Note that allowing updates based + on the requestor's IP address is insecure; see + for details. + + + + + + allow-update-forwarding + + + Specifies which hosts are allowed to + submit Dynamic DNS updates to slave zones to be forwarded to + the + master. The default is { none; }, + which + means that no update forwarding will be performed. To + enable + update forwarding, specify + allow-update-forwarding { any; };. + Specifying values other than { none; } or + { any; } is usually + counterproductive, since + the responsibility for update access control should rest + with the + master server, not the slaves. + + + Note that enabling the update forwarding feature on a slave + server + may expose master servers relying on insecure IP address + based + access control to attacks; see + for more details. + + + + + + allow-v6-synthesis + + + This option was introduced for the smooth transition from + AAAA + to A6 and from "nibble labels" to binary labels. + However, since both A6 and binary labels were then + deprecated, + this option was also deprecated. + It is now ignored with some warning messages. + + + + + + allow-transfer + + + Specifies which hosts are allowed to + receive zone transfers from the server. allow-transfer may + also be specified in the zone + statement, in which + case it overrides the options allow-transfer statement. + If not specified, the default is to allow transfers to all + hosts. + + + + + + blackhole + + + Specifies a list of addresses that the + server will not accept queries from or use to resolve a + query. Queries + from these addresses will not be responded to. The default + is none. + + + + + + + + + + Interfaces + + The interfaces and ports that the server will answer queries + from may be specified using the listen-on option. listen-on takes + an optional port, and an address_match_list. + The server will listen on all interfaces allowed by the address + match list. If a port is not specified, port 53 will be used. + + + Multiple listen-on statements are + allowed. + For example, + -A list of particular IPv6 addresses can also be specified, in which case -the server listens on a separate socket for each specified address, -regardless of whether the desired API is supported by the system. +listen-on { 5.6.7.8; }; +listen-on port 1234 { !1.2.3.4; 1.2/16; }; + -Multiple listen-on-v6 options can be used. -For example, + + will enable the name server on port 53 for the IP address + 5.6.7.8, and on port 1234 of an address on the machine in net + 1.2 that is not 1.2.3.4. + + + + If no listen-on is specified, the + server will listen on port 53 on all interfaces. + + + + The listen-on-v6 option is used to + specify the interfaces and the ports on which the server will + listen + for incoming queries sent using IPv6. + + + + When { any; } is + specified + as the address_match_list for the + listen-on-v6 option, + the server does not bind a separate socket to each IPv6 interface + address as it does for IPv4 if the operating system has enough API + support for IPv6 (specifically if it conforms to RFC 3493 and RFC + 3542). + Instead, it listens on the IPv6 wildcard address. + If the system only has incomplete API support for IPv6, however, + the behavior is the same as that for IPv4. + + + + A list of particular IPv6 addresses can also be specified, in + which case + the server listens on a separate socket for each specified + address, + regardless of whether the desired API is supported by the system. + + + + Multiple listen-on-v6 options can + be used. + For example, + listen-on-v6 { any; }; listen-on-v6 port 1234 { !2001:db8::/32; any; }; -will enable the name server on port 53 for any IPv6 addresses -(with a single wildcard socket), -and on port 1234 of IPv6 addresses that is not in the prefix -2001:db8::/32 (with separate sockets for each matched address.) + + will enable the name server on port 53 for any IPv6 addresses + (with a single wildcard socket), + and on port 1234 of IPv6 addresses that is not in the prefix + 2001:db8::/32 (with separate sockets for each matched address.) + + + + To make the server not listen on any IPv6 address, use + -To make the server not listen on any IPv6 address, use listen-on-v6 { none; }; -If no listen-on-v6 option is specified, -the server will not listen on any IPv6 address. - -Query Address -If the server doesn't know the answer to a question, it will -query other name servers. query-source specifies -the address and port used for such queries. For queries sent over -IPv6, there is a separate query-source-v6 option. -If address is * or is omitted, -a wildcard IP address (INADDR_ANY) will be used. -If port is * or is omitted, -a random unprivileged port will be used, avoid-v4-udp-ports -and avoid-v6-udp-ports can be used to prevent named -from selecting certain ports. The defaults are + + + If no listen-on-v6 option is + specified, + the server will not listen on any IPv6 address. + + + + + Query Address + + If the server doesn't know the answer to a question, it will + query other name servers. query-source specifies + the address and port used for such queries. For queries sent over + IPv6, there is a separate query-source-v6 option. + If address is * or is omitted, + a wildcard IP address (INADDR_ANY) + will be used. + If port is * or is omitted, + a random unprivileged port will be used, avoid-v4-udp-ports + and avoid-v6-udp-ports can be used + to prevent named + from selecting certain ports. The defaults are + + query-source address * port *; query-source-v6 address * port *; - -The address specified in the query-source option -is used for both UDP and TCP queries, but the port applies only to -UDP queries. TCP queries always use a random -unprivileged port. - -See also transfer-source and -notify-source. - - -Zone Transfers -BIND has mechanisms in place to facilitate zone transfers -and set limits on the amount of load that transfers place on the -system. The following options apply to zone transfers. - - - -also-notify -Defines a global list of IP addresses of name servers -that are also sent NOTIFY messages whenever a fresh copy of the -zone is loaded, in addition to the servers listed in the zone's NS records. -This helps to ensure that copies of the zones will -quickly converge on stealth servers. If an also-notify list -is given in a zone statement, it will override -the options also-notify statement. When a zone notify statement -is set to no, the IP addresses in the global also-notify list will -not be sent NOTIFY messages for that zone. The default is the empty -list (no global notification list). - - -max-transfer-time-in -Inbound zone transfers running longer than -this many minutes will be terminated. The default is 120 minutes -(2 hours). The maximum value is 28 days (40320 minutes). - - -max-transfer-idle-in -Inbound zone transfers making no progress -in this many minutes will be terminated. The default is 60 minutes -(1 hour). The maximum value is 28 days (40320 minutes). - - -max-transfer-time-out -Outbound zone transfers running longer than -this many minutes will be terminated. The default is 120 minutes -(2 hours). The maximum value is 28 days (40320 minutes). - - -max-transfer-idle-out -Outbound zone transfers making no progress -in this many minutes will be terminated. The default is 60 minutes (1 -hour). The maximum value is 28 days (40320 minutes). - - -serial-query-rate -Slave servers will periodically query master servers -to find out if zone serial numbers have changed. Each such query uses -a minute amount of the slave server's network bandwidth. To limit the -amount of bandwidth used, BIND 9 limits the rate at which queries are -sent. The value of the serial-query-rate option, -an integer, is the maximum number of queries sent per second. -The default is 20. - - - -serial-queries -In BIND 8, the serial-queries option -set the maximum number of concurrent serial number queries -allowed to be outstanding at any given time. -BIND 9 does not limit the number of outstanding -serial queries and ignores the serial-queries option. -Instead, it limits the rate at which the queries are sent -as defined using the serial-query-rate option. - - - -transfer-format - - - -Zone transfers can be sent using two different formats, -one-answer and many-answers. -The transfer-format option is used -on the master server to determine which format it sends. -one-answer uses one DNS message per -resource record transferred. -many-answers packs as many resource records as -possible into a message. many-answers is more -efficient, but is only supported by relatively new slave servers, -such as BIND 9, BIND 8.x and patched -versions of BIND 4.9.5. The default is -many-answers. transfer-format -may be overridden on a per-server basis by using the -server statement. - - - - -transfers-in -The maximum number of inbound zone transfers -that can be running concurrently. The default value is 10. -Increasing transfers-in may speed up the convergence -of slave zones, but it also may increase the load on the local system. - - -transfers-out -The maximum number of outbound zone transfers -that can be running concurrently. Zone transfer requests in excess -of the limit will be refused. The default value is 10. - - -transfers-per-ns -The maximum number of inbound zone transfers -that can be concurrently transferring from a given remote name server. -The default value is 2. Increasing transfers-per-ns may -speed up the convergence of slave zones, but it also may increase -the load on the remote name server. transfers-per-ns may -be overridden on a per-server basis by using the transfers phrase -of the server statement. - - -transfer-source -transfer-source determines -which local address will be bound to IPv4 TCP connections used to -fetch zones transferred inbound by the server. It also determines -the source IPv4 address, and optionally the UDP port, used for the -refresh queries and forwarded dynamic updates. If not set, it defaults -to a system controlled value which will usually be the address of -the interface "closest to" the remote end. This address must appear -in the remote end's allow-transfer option for -the zone being transferred, if one is specified. This statement -sets the transfer-source for all zones, but can -be overridden on a per-view or per-zone basis by including a -transfer-source statement within the -view or zone block -in the configuration file. - - -transfer-source-v6 -The same as transfer-source, -except zone transfers are performed using IPv6. - - -alt-transfer-source -An alternate transfer source if the one listed in -transfer-source fails and -use-alt-transfer-source is set. - - -alt-transfer-source-v6 -An alternate transfer source if the one listed in -transfer-source-v6 fails and -use-alt-transfer-source is set. - - -use-alt-transfer-source -Use the alternate transfer sources or not. If views are -specified this defaults to no otherwise it defaults to -yes (for BIND 8 compatibility). - - -notify-source -notify-source determines -which local source address, and optionally UDP port, will be used to -send NOTIFY messages. -This address must appear in the slave server's masters -zone clause or in an allow-notify clause. -This statement sets the notify-source for all zones, -but can be overridden on a per-zone / per-view basis by including a -notify-source statement within the zone -or view block in the configuration file. - - -notify-source-v6 -Like notify-source, -but applies to notify messages sent to IPv6 addresses. - - - - - - - -Bad UDP Port Lists - -avoid-v4-udp-ports and avoid-v6-udp-ports -specify a list of IPv4 and IPv6 UDP ports that will not be used as system -assigned source ports for UDP sockets. These lists prevent named -from choosing as its random source port a port that is blocked by -your firewall. If a query went out with such a source port, the -answer would not get by the firewall and the name server would have -to query again. - - - - -Operating System Resource Limits - -The server's usage of many system resources can be limited. -Scaled values are allowed when specifying resource limits. For -example, 1G can be used instead of -1073741824 to specify a limit of one -gigabyte. unlimited requests unlimited use, or the -maximum available amount. default uses the limit -that was in force when the server was started. See the description of -size_spec in . - -The following options set operating system resource limits for -the name server process. Some operating systems don't support some or -any of the limits. On such systems, a warning will be issued if the -unsupported limit is used. - - - -coresize -The maximum size of a core dump. The default -is default. - - -datasize -The maximum amount of data memory the server -may use. The default is default. -This is a hard limit on server memory usage. -If the server attempts to allocate memory in excess of this -limit, the allocation will fail, which may in turn leave -the server unable to perform DNS service. Therefore, -this option is rarely useful as a way of limiting the -amount of memory used by the server, but it can be used -to raise an operating system data size limit that is -too small by default. If you wish to limit the amount -of memory used by the server, use the -max-cache-size and -recursive-clients -options instead. - - -files -The maximum number of files the server -may have open concurrently. The default is unlimited. - - - -stacksize -The maximum amount of stack memory the server -may use. The default is default. - - - - - - - -Server Resource Limits - -The following options set limits on the server's -resource consumption that are enforced internally by the -server rather than the operating system. - - - -max-ixfr-log-size -This option is obsolete; it is accepted -and ignored for BIND 8 compatibility. The option -max-journal-size performs a similar -function in BIND 8. - - - -max-journal-size -Sets a maximum size for each journal file -(). When the journal file approaches -the specified size, some of the oldest transactions in the journal -will be automatically removed. The default is -unlimited. - - -host-statistics-max -In BIND 8, specifies the maximum number of host statistic -entries to be kept. -Not implemented in BIND 9. - - -recursive-clients -The maximum number of simultaneous recursive lookups -the server will perform on behalf of clients. The default is -1000. Because each recursing client uses a fair -bit of memory, on the order of 20 kilobytes, the value of the -recursive-clients option may have to be decreased -on hosts with limited memory. - - - -tcp-clients -The maximum number of simultaneous client TCP -connections that the server will accept. -The default is 100. - - -max-cache-size -The maximum amount of memory to use for the -server's cache, in bytes. When the amount of data in the cache -reaches this limit, the server will cause records to expire -prematurely so that the limit is not exceeded. In a server with -multiple views, the limit applies separately to the cache of each -view. The default is unlimited, meaning that -records are purged from the cache only when their TTLs expire. - - - -tcp-listen-queue -The listen queue depth. The default and minimum is 3. -If the kernel supports the accept filter "dataready" this also controls how -many TCP connections that will be queued in kernel space waiting for -some data before being passed to accept. Values less than 3 will be -silently raised. - - - - - - - -Periodic Task Intervals - - - -cleaning-interval -The server will remove expired resource records -from the cache every cleaning-interval minutes. -The default is 60 minutes. The maximum value is 28 days (40320 minutes). -If set to 0, no periodic cleaning will occur. - - -heartbeat-interval -The server will perform zone maintenance tasks -for all zones marked as dialup whenever this -interval expires. The default is 60 minutes. Reasonable values are up -to 1 day (1440 minutes). The maximum value is 28 days (40320 minutes). -If set to 0, no zone maintenance for these zones will occur. - - -interface-interval -The server will scan the network interface list -every interface-interval minutes. The default -is 60 minutes. The maximum value is 28 days (40320 minutes). -If set to 0, interface scanning will only occur when -the configuration file is loaded. After the scan, the server will -begin listening for queries on any newly discovered -interfaces (provided they are allowed by the -listen-on configuration), and will -stop listening on interfaces that have gone away. - - -statistics-interval -Name server statistics will be logged -every statistics-interval minutes. The default is -60. The maximum value is 28 days (40320 minutes). -If set to 0, no statistics will be logged. -Not yet implemented in BIND9. - - - - - - -Topology - -All other things being equal, when the server chooses a name server -to query from a list of name servers, it prefers the one that is -topologically closest to itself. The topology statement -takes an address_match_list and interprets it -in a special way. Each top-level list element is assigned a distance. -Non-negated elements get a distance based on their position in the -list, where the closer the match is to the start of the list, the -shorter the distance is between it and the server. A negated match -will be assigned the maximum distance from the server. If there -is no match, the address will get a distance which is further than -any non-negated list element, and closer than any negated element. -For example, + + + + The address specified in the query-source option + is used for both UDP and TCP queries, but the port applies only + to + UDP queries. TCP queries always use a random + unprivileged port. + + + + + See also transfer-source and + notify-source. + + + + + + Zone Transfers + + BIND has mechanisms in place to + facilitate zone transfers + and set limits on the amount of load that transfers place on the + system. The following options apply to zone transfers. + + + + + + also-notify + + + Defines a global list of IP addresses of name servers + that are also sent NOTIFY messages whenever a fresh copy of + the + zone is loaded, in addition to the servers listed in the + zone's NS records. + This helps to ensure that copies of the zones will + quickly converge on stealth servers. If an also-notify list + is given in a zone statement, + it will override + the options also-notify + statement. When a zone notify + statement + is set to no, the IP + addresses in the global also-notify list will + not be sent NOTIFY messages for that zone. The default is + the empty + list (no global notification list). + + + + + + max-transfer-time-in + + + Inbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + + + + + + max-transfer-idle-in + + + Inbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes + (1 hour). The maximum value is 28 days (40320 minutes). + + + + + + max-transfer-time-out + + + Outbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + + + + + + max-transfer-idle-out + + + Outbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes (1 + hour). The maximum value is 28 days (40320 minutes). + + + + + + serial-query-rate + + + Slave servers will periodically query master servers + to find out if zone serial numbers have changed. Each such + query uses + a minute amount of the slave server's network bandwidth. To + limit the + amount of bandwidth used, BIND 9 limits the rate at which + queries are + sent. The value of the serial-query-rate option, + an integer, is the maximum number of queries sent per + second. + The default is 20. + + + + + + serial-queries + + + In BIND 8, the serial-queries + option + set the maximum number of concurrent serial number queries + allowed to be outstanding at any given time. + BIND 9 does not limit the number of outstanding + serial queries and ignores the serial-queries option. + Instead, it limits the rate at which the queries are sent + as defined using the serial-query-rate option. + + + + + + transfer-format + + + + Zone transfers can be sent using two different formats, + one-answer and many-answers. + The transfer-format option is + used + on the master server to determine which format it sends. + one-answer uses one DNS + message per + resource record transferred. + many-answers packs as many + resource records as + possible into a message. many-answers is more + efficient, but is only supported by relatively new slave + servers, + such as BIND 9, BIND 8.x and patched + versions of BIND 4.9.5. The + default is + many-answers. transfer-format + may be overridden on a per-server basis by using the + server statement. + + + + + + + transfers-in + + + The maximum number of inbound zone transfers + that can be running concurrently. The default value is 10. + Increasing transfers-in may + speed up the convergence + of slave zones, but it also may increase the load on the + local system. + + + + + + transfers-out + + + The maximum number of outbound zone transfers + that can be running concurrently. Zone transfer requests in + excess + of the limit will be refused. The default value is 10. + + + + + + transfers-per-ns + + + The maximum number of inbound zone transfers + that can be concurrently transferring from a given remote + name server. + The default value is 2. + Increasing transfers-per-ns + may + speed up the convergence of slave zones, but it also may + increase + the load on the remote name server. transfers-per-ns may + be overridden on a per-server basis by using the transfers phrase + of the server statement. + + + + + + transfer-source + + transfer-source + determines which local address will be bound to IPv4 + TCP connections used to fetch zones transferred + inbound by the server. It also determines the + source IPv4 address, and optionally the UDP port, + used for the refresh queries and forwarded dynamic + updates. If not set, it defaults to a system + controlled value which will usually be the address + of the interface "closest to" the remote end. This + address must appear in the remote end's + allow-transfer option for the + zone being transferred, if one is specified. This + statement sets the + transfer-source for all zones, + but can be overridden on a per-view or per-zone + basis by including a + transfer-source statement within + the view or + zone block in the configuration + file. + + + + + + transfer-source-v6 + + + The same as transfer-source, + except zone transfers are performed using IPv6. + + + + + + alt-transfer-source + + + An alternate transfer source if the one listed in + transfer-source fails and + use-alt-transfer-source is + set. + + + + + + alt-transfer-source-v6 + + + An alternate transfer source if the one listed in + transfer-source-v6 fails and + use-alt-transfer-source is + set. + + + + + + use-alt-transfer-source + + + Use the alternate transfer sources or not. If views are + specified this defaults to no + otherwise it defaults to + yes (for BIND 8 + compatibility). + + + + + + notify-source + + notify-source + determines which local source address, and + optionally UDP port, will be used to send NOTIFY + messages. This address must appear in the slave + server's masters zone clause or + in an allow-notify clause. This + statement sets the notify-source + for all zones, but can be overridden on a per-zone / + per-view basis by including a + notify-source statement within + the zone or + view block in the configuration + file. + + + + + + notify-source-v6 + + + Like notify-source, + but applies to notify messages sent to IPv6 addresses. + + + + + + + + + + Bad UDP Port Lists + avoid-v4-udp-ports + and avoid-v6-udp-ports specify a list + of IPv4 and IPv6 UDP ports that will not be used as system + assigned source ports for UDP sockets. These lists + prevent named from choosing as its random source port a + port that is blocked by your firewall. If a query went + out with such a source port, the answer would not get by + the firewall and the name server would have to query + again. + + + + + Operating System Resource Limits + + + The server's usage of many system resources can be limited. + Scaled values are allowed when specifying resource limits. For + example, 1G can be used instead of + 1073741824 to specify a limit of + one + gigabyte. unlimited requests + unlimited use, or the + maximum available amount. default + uses the limit + that was in force when the server was started. See the description + of + size_spec in . + + + + The following options set operating system resource limits for + the name server process. Some operating systems don't support + some or + any of the limits. On such systems, a warning will be issued if + the + unsupported limit is used. + + + + + + coresize + + + The maximum size of a core dump. The default + is default. + + + + + + datasize + + + The maximum amount of data memory the server + may use. The default is default. + This is a hard limit on server memory usage. + If the server attempts to allocate memory in excess of this + limit, the allocation will fail, which may in turn leave + the server unable to perform DNS service. Therefore, + this option is rarely useful as a way of limiting the + amount of memory used by the server, but it can be used + to raise an operating system data size limit that is + too small by default. If you wish to limit the amount + of memory used by the server, use the + max-cache-size and + recursive-clients + options instead. + + + + + + files + + + The maximum number of files the server + may have open concurrently. The default is unlimited. + + + + + + stacksize + + + The maximum amount of stack memory the server + may use. The default is default. + + + + + + + + + + Server Resource Limits + + + The following options set limits on the server's + resource consumption that are enforced internally by the + server rather than the operating system. + + + + + + max-ixfr-log-size + + + This option is obsolete; it is accepted + and ignored for BIND 8 compatibility. The option + max-journal-size performs a + similar + function in BIND 8. + + + + + + max-journal-size + + + Sets a maximum size for each journal file + (). When the journal file + approaches + the specified size, some of the oldest transactions in the + journal + will be automatically removed. The default is + unlimited. + + + + + + host-statistics-max + + + In BIND 8, specifies the maximum number of host statistic + entries to be kept. + Not implemented in BIND 9. + + + + + + recursive-clients + + + The maximum number of simultaneous recursive lookups + the server will perform on behalf of clients. The default + is + 1000. Because each recursing + client uses a fair + bit of memory, on the order of 20 kilobytes, the value of + the + recursive-clients option may + have to be decreased + on hosts with limited memory. + + + + + + tcp-clients + + + The maximum number of simultaneous client TCP + connections that the server will accept. + The default is 100. + + + + + + max-cache-size + + + The maximum amount of memory to use for the + server's cache, in bytes. When the amount of data in the + cache + reaches this limit, the server will cause records to expire + prematurely so that the limit is not exceeded. In a server + with + multiple views, the limit applies separately to the cache of + each + view. The default is unlimited, meaning that + records are purged from the cache only when their TTLs + expire. + + + + + + tcp-listen-queue + + + The listen queue depth. The default and minimum is 3. + If the kernel supports the accept filter "dataready" this + also controls how + many TCP connections that will be queued in kernel space + waiting for + some data before being passed to accept. Values less than 3 + will be + silently raised. + + + + + + + + + + Periodic Task Intervals + + + + + cleaning-interval + + + The server will remove expired resource records + from the cache every cleaning-interval minutes. + The default is 60 minutes. The maximum value is 28 days + (40320 minutes). + If set to 0, no periodic cleaning will occur. + + + + + + heartbeat-interval + + + The server will perform zone maintenance tasks + for all zones marked as dialup whenever this + interval expires. The default is 60 minutes. Reasonable + values are up + to 1 day (1440 minutes). The maximum value is 28 days + (40320 minutes). + If set to 0, no zone maintenance for these zones will occur. + + + + + + interface-interval + + + The server will scan the network interface list + every interface-interval + minutes. The default + is 60 minutes. The maximum value is 28 days (40320 minutes). + If set to 0, interface scanning will only occur when + the configuration file is loaded. After the scan, the + server will + begin listening for queries on any newly discovered + interfaces (provided they are allowed by the + listen-on configuration), and + will + stop listening on interfaces that have gone away. + + + + + + statistics-interval + + + Name server statistics will be logged + every statistics-interval + minutes. The default is + 60. The maximum value is 28 days (40320 minutes). + If set to 0, no statistics will be logged. + + + Not yet implemented in + BIND9. + + + + + + + + + + + Topology + + + All other things being equal, when the server chooses a name + server + to query from a list of name servers, it prefers the one that is + topologically closest to itself. The topology statement + takes an address_match_list and + interprets it + in a special way. Each top-level list element is assigned a + distance. + Non-negated elements get a distance based on their position in the + list, where the closer the match is to the start of the list, the + shorter the distance is between it and the server. A negated match + will be assigned the maximum distance from the server. If there + is no match, the address will get a distance which is further than + any non-negated list element, and closer than any negated element. + For example, + + topology { 10/8; !1.2.3/24; { 1.2/16; 3/8; }; }; -will prefer servers on network 10 the most, followed by hosts -on network 1.2.0.0 (netmask 255.255.0.0) and network 3, with the -exception of hosts on network 1.2.3 (netmask 255.255.255.0), which -is preferred least of all. -The default topology is + + + will prefer servers on network 10 the most, followed by hosts + on network 1.2.0.0 (netmask 255.255.0.0) and network 3, with the + exception of hosts on network 1.2.3 (netmask 255.255.255.0), which + is preferred least of all. + + + The default topology is + + topology { localhost; localnets; }; -The topology option -is not implemented in BIND 9. - - - - - -The <command>sortlist</command> Statement - -The response to a DNS query may consist of multiple resource -records (RRs) forming a resource records set (RRset). -The name server will normally return the -RRs within the RRset in an indeterminate order -(but see the rrset-order -statement in ). -The client resolver code should rearrange the RRs as appropriate, -that is, using any addresses on the local net in preference to other addresses. -However, not all resolvers can do this or are correctly configured. -When a client is using a local server the sorting can be performed -in the server, based on the client's address. This only requires -configuring the name servers, not all the clients. - -The sortlist statement (see below) takes -an address_match_list and interprets it even -more specifically than the topology statement -does (). -Each top level statement in the sortlist must -itself be an explicit address_match_list with -one or two elements. The first element (which may be an IP address, -an IP prefix, an ACL name or a nested address_match_list) -of each top level list is checked against the source address of -the query until a match is found. -Once the source address of the query has been matched, if -the top level statement contains only one element, the actual primitive -element that matched the source address is used to select the address -in the response to move to the beginning of the response. If the -statement is a list of two elements, then the second element is -treated the same as the address_match_list in -a topology statement. Each top level element -is assigned a distance and the address in the response with the minimum -distance is moved to the beginning of the response. -In the following example, any queries received from any of -the addresses of the host itself will get responses preferring addresses -on any of the locally connected networks. Next most preferred are addresses -on the 192.168.1/24 network, and after that either the 192.168.2/24 -or -192.168.3/24 network with no preference shown between these two -networks. Queries received from a host on the 192.168.1/24 network -will prefer other addresses on that network to the 192.168.2/24 -and -192.168.3/24 networks. Queries received from a host on the 192.168.4/24 -or the 192.168.5/24 network will only prefer other addresses on -their directly connected networks. + + + + The topology option + is not implemented in BIND 9. + + + + + + + The <command>sortlist</command> Statement + + + The response to a DNS query may consist of multiple resource + records (RRs) forming a resource records set (RRset). + The name server will normally return the + RRs within the RRset in an indeterminate order + (but see the rrset-order + statement in ). + The client resolver code should rearrange the RRs as appropriate, + that is, using any addresses on the local net in preference to + other addresses. + However, not all resolvers can do this or are correctly + configured. + When a client is using a local server the sorting can be performed + in the server, based on the client's address. This only requires + configuring the name servers, not all the clients. + + + + The sortlist statement (see below) + takes + an address_match_list and + interprets it even + more specifically than the topology + statement + does (). + Each top level statement in the sortlist must + itself be an explicit address_match_list with + one or two elements. The first element (which may be an IP + address, + an IP prefix, an ACL name or a nested address_match_list) + of each top level list is checked against the source address of + the query until a match is found. + + + Once the source address of the query has been matched, if + the top level statement contains only one element, the actual + primitive + element that matched the source address is used to select the + address + in the response to move to the beginning of the response. If the + statement is a list of two elements, then the second element is + treated the same as the address_match_list in + a topology statement. Each top + level element + is assigned a distance and the address in the response with the + minimum + distance is moved to the beginning of the response. + + + In the following example, any queries received from any of + the addresses of the host itself will get responses preferring + addresses + on any of the locally connected networks. Next most preferred are + addresses + on the 192.168.1/24 network, and after that either the + 192.168.2/24 + or + 192.168.3/24 network with no preference shown between these two + networks. Queries received from a host on the 192.168.1/24 network + will prefer other addresses on that network to the 192.168.2/24 + and + 192.168.3/24 networks. Queries received from a host on the + 192.168.4/24 + or the 192.168.5/24 network will only prefer other addresses on + their directly connected networks. + + sortlist { { localhost; // IF the local host { localnets; // THEN first fit on the @@ -4106,380 +6567,582 @@ their directly connected networks. { { 192.168.4/24; 192.168.5/24; }; // if .4 or .5, prefer that net }; }; -The following example will give reasonable behavior for the -local host and hosts on directly connected networks. It is similar -to the behavior of the address sort in BIND 4.9.x. Responses sent -to queries from the local host will favor any of the directly connected -networks. Responses sent to queries from any other hosts on a directly -connected network will prefer addresses on that same network. Responses -to other queries will not be sorted. + + + The following example will give reasonable behavior for the + local host and hosts on directly connected networks. It is similar + to the behavior of the address sort in BIND 4.9.x. Responses sent + to queries from the local host will favor any of the directly + connected + networks. Responses sent to queries from any other hosts on a + directly + connected network will prefer addresses on that same network. + Responses + to other queries will not be sorted. + + sortlist { { localhost; localnets; }; { localnets; }; }; - -RRset Ordering -When multiple records are returned in an answer it may be -useful to configure the order of the records placed into the response. -The rrset-order statement permits configuration -of the ordering of the records in a multiple record response. -See also the sortlist statement, -. - - -An order_spec is defined as follows: - class class_name type type_name name "domain_name" - order ordering - -If no class is specified, the default is ANY. -If no type is specified, the default is ANY. -If no name is specified, the default is "*". -The legal values for ordering are: - - - - - -fixed -Records are returned in the order they -are defined in the zone file. - - -random -Records are returned in some random order. - - -cyclic -Records are returned in a round-robin -order. - - - -For example: + + + + RRset Ordering + + When multiple records are returned in an answer it may be + useful to configure the order of the records placed into the + response. + The rrset-order statement permits + configuration + of the ordering of the records in a multiple record response. + See also the sortlist statement, + . + + + + An order_spec is defined as + follows: + + + class class_name + type type_name + name "domain_name" + order ordering + + + If no class is specified, the default is ANY. + If no type is specified, the default is ANY. + If no name is specified, the default is "*". + + + The legal values for ordering are: + + + + + + + + + fixed + + + + Records are returned in the order they + are defined in the zone file. + + + + + + random + + + + Records are returned in some random order. + + + + + + cyclic + + + + Records are returned in a round-robin + order. + + + + + + + + For example: + + rrset-order { class IN type A name "host.example.com" order random; order cyclic; }; -will cause any responses for type A records in class IN that -have "host.example.com" as a suffix, to always be returned -in random order. All other records are returned in cyclic order. -If multiple rrset-order statements appear, -they are not combined — the last one applies. - - -The rrset-order statement -is not yet fully implemented in BIND 9. -BIND 9 currently does not support "fixed" ordering. - - - -Tuning - - - -lame-ttl -Sets the number of seconds to cache a -lame server indication. 0 disables caching. (This is -NOT recommended.) -Default is 600 (10 minutes). Maximum value is -1800 (30 minutes). - - - -max-ncache-ttl -To reduce network traffic and increase performance -the server stores negative answers. max-ncache-ttl is -used to set a maximum retention time for these answers in the server -in seconds. The default -max-ncache-ttl is 10800 seconds (3 hours). -max-ncache-ttl cannot exceed 7 days and will -be silently truncated to 7 days if set to a greater value. - - -max-cache-ttl -max-cache-ttl sets -the maximum time for which the server will cache ordinary (positive) -answers. The default is one week (7 days). - - -min-roots -The minimum number of root servers that -is required for a request for the root servers to be accepted. Default -is 2. - -Not implemented in BIND9. - - -sig-validity-interval -Specifies the number of days into the -future when DNSSEC signatures automatically generated as a result -of dynamic updates () -will expire. The default is 30 days. -The maximum value is 10 years (3660 days). The signature -inception time is unconditionally set to one hour before the current time -to allow for a limited amount of clock skew. - - - -min-refresh-time -max-refresh-time -min-retry-time -max-retry-time - -These options control the server's behavior on refreshing a zone -(querying for SOA changes) or retrying failed transfers. -Usually the SOA values for the zone are used, but these values -are set by the master, giving slave server administrators little -control over their contents. - -These options allow the administrator to set a minimum and maximum -refresh and retry time either per-zone, per-view, or globally. -These options are valid for slave and stub zones, -and clamp the SOA refresh and retry times to the specified values. - - - -edns-udp-size - -edns-udp-size sets the advertised EDNS UDP buffer -size. Valid values are 512 to 4096 (values outside this range will be -silently adjusted). The default value is 4096. The usual reason for -setting edns-udp-size to a non default value it to get UDP answers to -pass through broken firewalls that block fragmented packets and/or -block UDP packets that are greater than 512 bytes. - - - - - - -Built-in server information zones - -The server provides some helpful diagnostic information -through a number of built-in zones under the -pseudo-top-level-domain bind in the -CHAOS class. These zones are part of a -built-in view (see ) of class -CHAOS which is separate from the default view of -class IN; therefore, any global server options -such as allow-query do not apply the these zones. -If you feel the need to disable these zones, use the options -below, or hide the built-in CHAOS view by -defining an explicit view of class CHAOS -that matches all clients. - - - -version -The version the server should report -via a query of the name version.bind -with type TXT, class CHAOS. -The default is the real version number of this server. -Specifying version none -disables processing of the queries. - - -hostname -The hostname the server should report via a query of -the name hostname.bind -with type TXT, class CHAOS. -This defaults to the hostname of the machine hosting the name server as -found by gethostname(). The primary purpose of such queries is to -identify which of a group of anycast servers is actually -answering your queries. Specifying hostname none; -disables processing of the queries. - - -server-id -The ID of the server should report via a query of -the name ID.SERVER -with type TXT, class CHAOS. -The primary purpose of such queries is to -identify which of a group of anycast servers is actually -answering your queries. Specifying server-id none; -disables processing of the queries. -Specifying server-id hostname; will cause named to -use the hostname as found by gethostname(). -The default server-id is none. - - - - - - - - -The Statistics File - -The statistics file generated by BIND 9 -is similar, but not identical, to that -generated by BIND 8. - -The statistics dump begins with the line +++ Statistics Dump + + + will cause any responses for type A records in class IN that + have "host.example.com" as a + suffix, to always be returned + in random order. All other records are returned in cyclic order. + + + If multiple rrset-order statements + appear, + they are not combined — the last one applies. + + + + + The rrset-order statement + is not yet fully implemented in BIND 9. + BIND 9 currently does not support "fixed" ordering. + + + + + + Tuning + + + + + lame-ttl + + + Sets the number of seconds to cache a + lame server indication. 0 disables caching. (This is + NOT recommended.) + Default is 600 (10 minutes). + Maximum value is + 1800 (30 minutes). + + + + + + + max-ncache-ttl + + + To reduce network traffic and increase performance + the server stores negative answers. max-ncache-ttl is + used to set a maximum retention time for these answers in + the server + in seconds. The default + max-ncache-ttl is 10800 seconds (3 hours). + max-ncache-ttl cannot exceed + 7 days and will + be silently truncated to 7 days if set to a greater value. + + + + + + max-cache-ttl + + max-cache-ttl + sets the maximum time for which the server will + cache ordinary (positive) answers. The default is + one week (7 days). + + + + + + min-roots + + + The minimum number of root servers that + is required for a request for the root servers to be + accepted. Default + is 2. + + + + Not implemented in BIND9. + + + + + + + sig-validity-interval + + + Specifies the number of days into the + future when DNSSEC signatures automatically generated as a + result + of dynamic updates () + will expire. The default is 30 days. + The maximum value is 10 years (3660 days). The signature + inception time is unconditionally set to one hour before the + current time + to allow for a limited amount of clock skew. + + + + + + min-refresh-time + max-refresh-time + min-retry-time + max-retry-time + + + These options control the server's behavior on refreshing a + zone + (querying for SOA changes) or retrying failed transfers. + Usually the SOA values for the zone are used, but these + values + are set by the master, giving slave server administrators + little + control over their contents. + + + These options allow the administrator to set a minimum and + maximum + refresh and retry time either per-zone, per-view, or + globally. + These options are valid for slave and stub zones, + and clamp the SOA refresh and retry times to the specified + values. + + + + + + edns-udp-size + + edns-udp-size + sets the advertised EDNS UDP buffer size. Valid + values are 512 to 4096 (values outside this range + will be silently adjusted). The default value is + 4096. The usual reason for setting edns-udp-size to + a non default value it to get UDP answers to pass + through broken firewalls that block fragmented + packets and/or block UDP packets that are greater + than 512 bytes. + + + + + + + + + Built-in server information zones + + + The server provides some helpful diagnostic information + through a number of built-in zones under the + pseudo-top-level-domain bind in the + CHAOS class. These zones are part + of a + built-in view (see ) of + class + CHAOS which is separate from the + default view of + class IN; therefore, any global + server options + such as allow-query do not apply + the these zones. + If you feel the need to disable these zones, use the options + below, or hide the built-in CHAOS + view by + defining an explicit view of class CHAOS + that matches all clients. + + + + + + version + + + The version the server should report + via a query of the name version.bind + with type TXT, class CHAOS. + The default is the real version number of this server. + Specifying version none + disables processing of the queries. + + + + + + hostname + + + The hostname the server should report via a query of + the name hostname.bind + with type TXT, class CHAOS. + This defaults to the hostname of the machine hosting the + name server as + found by gethostname(). The primary purpose of such queries + is to + identify which of a group of anycast servers is actually + answering your queries. Specifying hostname none; + disables processing of the queries. + + + + + + server-id + + + The ID of the server should report via a query of + the name ID.SERVER + with type TXT, class CHAOS. + The primary purpose of such queries is to + identify which of a group of anycast servers is actually + answering your queries. Specifying server-id none; + disables processing of the queries. + Specifying server-id hostname; will cause named to + use the hostname as found by gethostname(). + The default server-id is none. + + + + + + + + + + The Statistics File + + + The statistics file generated by BIND 9 + is similar, but not identical, to that + generated by BIND 8. + + + The statistics dump begins with the line +++ Statistics Dump +++ (973798949), where the number in parentheses is a standard -Unix-style timestamp, measured as seconds since January 1, 1970. Following -that line are a series of lines containing a counter type, the value of the -counter, optionally a zone name, and optionally a view name. -The lines without view and zone listed are global statistics for the entire server. -Lines with a zone and view name for the given view and zone (the view name is -omitted for the default view). The statistics dump ends -with the line --- Statistics Dump --- (973798949), where the -number is identical to the number in the beginning line. -The following statistics counters are maintained: - - - - - -success -The number of -successful queries made to the server or zone. A successful query -is defined as query which returns a NOERROR response with at least -one answer RR. - - -referral -The number of queries which resulted -in referral responses. - - -nxrrset -The number of queries which resulted in -NOERROR responses with no data. - - -nxdomain -The number -of queries which resulted in NXDOMAIN responses. - - -failure -The number of queries which resulted in a -failure response other than those above. - - -recursion -The number of queries which caused the server -to perform recursion in order to find the final answer. - - - - - -Each query received by the server will cause exactly one of -success, -referral, -nxrrset, -nxdomain, or -failure -to be incremented, and may additionally cause the -recursion counter to be incremented. - - - - - -Additional Section Caching - - -The additional section cache, also called acache, -is an internal cache to improve the response performance of BIND 9. -When the additional section caching is enabled, BIND 9 will -cache internal short-cut to the additional section content for each -answer RR. -Note that acache is an internal caching mechanism of BIND 9, and is -not relevant to the DNS caching server function. - - - -The additional section caching does not make any difference on the -response content (except the RRsets ordering of the additional -section, see below), but can improve the response performance significantly. -It is particularly effective when BIND 9 acts as an authoritative server -for a zone that has many delegations with many glue RRs. - - - -In order to achieve the maximum performance improvement by acache, -it is recommended to set additional-from-cache -to no, since the current implementation of acache -does not make a short-cut of additional section information from a DNS -cache data. - - - -One obvious disadvantage of acache is that it requires much more -memory for the internal cached data. -Thus, if the response performance does not matter and memory -consumption is much more severe, the acache mechanism can be -disabled by setting use-additional-cache to -no. -It is also possible to specify the upper limit of memory consumption -for acache by max-acache-size. - - - -The additional section caching also has a minor effect on the RRset -ordering in the additional section. -Without acache, the "cyclic" order is effective for the additional -section as well as the answer and authority sections. -However, the additional section caching fixes the ordering when it -first caches an RRset for the additional section, and the same -ordering will be kept in succeeding responses, regardless of the -configuration for rrset-order. -This should be minor, though, since an RRset in the additional section -typically only contains a small number of RRs (and in many cases it -only contains a single RR), in which case the -ordering does not matter much. - - - -The following is a summary of options related to acache. - - - - -use-additional-cache - -If yes, the additional section caching is enabled. -The default value is yes. - - - -acache-cleaning-interval - -The server will remove stale cache entries, based on an LRU based -algorithm, every acache-cleaning-interval minutes. -The default is 60 minutes. -If set to 0, no periodic cleaning will occur. - - - -max-acache-size - -The maximum amount of memory to use for the server's acache, in bytes. -When the amount of data in the acache reaches this limit, the server -will cause more aggressive cleaning so that the limit is not exceeded. -In a server with multiple views, the limit applies separately to the -acache of each view. -The default is unlimited, meaning that -entries are purged from acache only at the periodic cleaning time. - - - - - - - - - - -<command>server</command> Statement Grammar + Unix-style timestamp, measured as seconds since January 1, 1970. + Following + that line are a series of lines containing a counter type, the + value of the + counter, optionally a zone name, and optionally a view name. + The lines without view and zone listed are global statistics for + the entire server. + Lines with a zone and view name for the given view and zone (the + view name is + omitted for the default view). The statistics dump ends + with the line --- Statistics Dump --- (973798949), where the + number is identical to the number in the beginning line. + + + The following statistics counters are maintained: + + + + + + + + + success + + + + The number of + successful queries made to the server or zone. A + successful query + is defined as query which returns a NOERROR response + with at least + one answer RR. + + + + + + referral + + + + The number of queries which resulted + in referral responses. + + + + + + nxrrset + + + + The number of queries which resulted in + NOERROR responses with no data. + + + + + + nxdomain + + + + The number + of queries which resulted in NXDOMAIN responses. + + + + + + failure + + + + The number of queries which resulted in a + failure response other than those above. + + + + + + recursion + + + + The number of queries which caused the server + to perform recursion in order to find the final answer. + + + + + + + + + Each query received by the server will cause exactly one of + success, + referral, + nxrrset, + nxdomain, or + failure + to be incremented, and may additionally cause the + recursion counter to be + incremented. + + + + + + Additional Section Caching + + + The additional section cache, also called acache, + is an internal cache to improve the response performance of BIND + 9. + When the additional section caching is enabled, BIND 9 will + cache internal short-cut to the additional section content for + each + answer RR. + Note that acache is an internal caching mechanism of BIND 9, and + is + not relevant to the DNS caching server function. + + + + The additional section caching does not make any difference on the + response content (except the RRsets ordering of the additional + section, see below), but can improve the response performance + significantly. + It is particularly effective when BIND 9 acts as an authoritative + server + for a zone that has many delegations with many glue RRs. + + + + In order to achieve the maximum performance improvement by acache, + it is recommended to set additional-from-cache + to no, since the current + implementation of acache + does not make a short-cut of additional section information from a + DNS + cache data. + + + + One obvious disadvantage of acache is that it requires much more + memory for the internal cached data. + Thus, if the response performance does not matter and memory + consumption is much more severe, the acache mechanism can be + disabled by setting use-additional-cache to + no. + It is also possible to specify the upper limit of memory + consumption + for acache by max-acache-size. + + + + The additional section caching also has a minor effect on the + RRset + ordering in the additional section. + Without acache, the "cyclic" order is effective for the additional + section as well as the answer and authority sections. + However, the additional section caching fixes the ordering when it + first caches an RRset for the additional section, and the same + ordering will be kept in succeeding responses, regardless of the + configuration for rrset-order. + This should be minor, though, since an RRset in the additional + section + typically only contains a small number of RRs (and in many cases + it + only contains a single RR), in which case the + ordering does not matter much. + + + + The following is a summary of options related to acache. + + + + + + use-additional-cache + + + If yes, the additional section caching is enabled. + The default value is yes. + + + + + + acache-cleaning-interval + + + The server will remove stale cache entries, based on an LRU + based + algorithm, every acache-cleaning-interval minutes. + The default is 60 minutes. + If set to 0, no periodic cleaning will occur. + + + + + + max-acache-size + + + The maximum amount of memory to use for the server's acache, + in bytes. + When the amount of data in the acache reaches this limit, + the server + will cause more aggressive cleaning so that the limit is not + exceeded. + In a server with multiple views, the limit applies + separately to the + acache of each view. + The default is unlimited, + meaning that + entries are purged from acache only at the periodic cleaning + time. + + + + + + + + + + + + <command>server</command> Statement Grammar server ip_addr/prefixlen { bogus yes_or_no ; @@ -4494,124 +7157,195 @@ entries are purged from acache only at the periodic cleaning time. }; - - - -<command>server</command> Statement Definition and Usage - -The server statement defines characteristics -to be associated with a remote name server. If a prefix length is -specified then a range of servers is covered. Only the most specific -server clause applies regardless of the order in -named.conf. - - -The server statement can occur at the top level of the -configuration file or inside a view statement. -If a view statement contains -one or more server statements, only those -apply to the view and any top-level ones are ignored. -If a view contains no server statements, -any top-level server statements are used as -defaults. - - -If you discover that a remote server is giving out bad data, -marking it as bogus will prevent further queries to it. The default -value of bogus is no. -The provide-ixfr clause determines whether -the local server, acting as master, will respond with an incremental -zone transfer when the given remote server, a slave, requests it. -If set to yes, incremental transfer will be provided -whenever possible. If set to no, all transfers -to the remote server will be non-incremental. If not set, the value -of the provide-ixfr option in the view or -global options block is used as a default. - -The request-ixfr clause determines whether -the local server, acting as a slave, will request incremental zone -transfers from the given remote server, a master. If not set, the -value of the request-ixfr option in the view or -global options block is used as a default. - -IXFR requests to servers that do not support IXFR will automatically -fall back to AXFR. Therefore, there is no need to manually list -which servers support IXFR and which ones do not; the global default -of yes should always work. -The purpose of the provide-ixfr and -request-ixfr clauses is -to make it possible to disable the use of IXFR even when both master -and slave claim to support it, for example if one of the servers -is buggy and crashes or corrupts data when IXFR is used. - -The edns clause determines whether the local server -will attempt to use EDNS when communicating with the remote server. The -default is yes. - -The server supports two zone transfer methods. The first, one-answer, -uses one DNS message per resource record transferred. many-answers packs -as many resource records as possible into a message. many-answers is -more efficient, but is only known to be understood by BIND 9, BIND -8.x, and patched versions of BIND 4.9.5. You can specify which method -to use for a server with the transfer-format option. -If transfer-format is not specified, the transfer-format specified -by the options statement will be used. - -transfers is used to limit the number of -concurrent inbound zone transfers from the specified server. If -no transfers clause is specified, the limit is -set according to the transfers-per-ns option. - -The keys clause identifies a -key_id defined by the key statement, -to be used for transaction security (TSIG, ) -when talking to the remote server. -When a request is sent to the remote server, a request signature -will be generated using the key specified here and appended to the -message. A request originating from the remote server is not required -to be signed by this key. - -Although the grammar of the keys clause -allows for multiple keys, only a single key per server is currently -supported. - -The transfer-source and -transfer-source-v6 clauses specify the IPv4 and IPv6 source -address to be used for zone transfer with the remote server, respectively. -For an IPv4 remote server, only transfer-source can -be specified. -Similarly, for an IPv6 remote server, only -transfer-source-v6 can be specified. -Form more details, see the description of -transfer-source and -transfer-source-v6 in -. - - - -<command>trusted-keys</command> Statement Grammar + + + + <command>server</command> Statement Definition and + Usage + + + The server statement defines + characteristics + to be associated with a remote name server. If a prefix length is + specified then a range of servers is covered. Only the most + specific + server clause applies regardless of the order in + named.conf. + + + + The server statement can occur at + the top level of the + configuration file or inside a view + statement. + If a view statement contains + one or more server statements, only + those + apply to the view and any top-level ones are ignored. + If a view contains no server + statements, + any top-level server statements are + used as + defaults. + + + + If you discover that a remote server is giving out bad data, + marking it as bogus will prevent further queries to it. The + default + value of bogus is no. + + + The provide-ixfr clause determines + whether + the local server, acting as master, will respond with an + incremental + zone transfer when the given remote server, a slave, requests it. + If set to yes, incremental transfer + will be provided + whenever possible. If set to no, + all transfers + to the remote server will be non-incremental. If not set, the + value + of the provide-ixfr option in the + view or + global options block is used as a default. + + + + The request-ixfr clause determines + whether + the local server, acting as a slave, will request incremental zone + transfers from the given remote server, a master. If not set, the + value of the request-ixfr option in + the view or + global options block is used as a default. + + + + IXFR requests to servers that do not support IXFR will + automatically + fall back to AXFR. Therefore, there is no need to manually list + which servers support IXFR and which ones do not; the global + default + of yes should always work. + The purpose of the provide-ixfr and + request-ixfr clauses is + to make it possible to disable the use of IXFR even when both + master + and slave claim to support it, for example if one of the servers + is buggy and crashes or corrupts data when IXFR is used. + + + + The edns clause determines whether + the local server + will attempt to use EDNS when communicating with the remote + server. The + default is yes. + + + + The server supports two zone transfer methods. The first, one-answer, + uses one DNS message per resource record transferred. many-answers packs + as many resource records as possible into a message. many-answers is + more efficient, but is only known to be understood by BIND 9, BIND + 8.x, and patched versions of BIND + 4.9.5. You can specify which method + to use for a server with the transfer-format option. + If transfer-format is not + specified, the transfer-format + specified + by the options statement will be + used. + + + transfers + is used to limit the number of concurrent inbound zone + transfers from the specified server. If no + transfers clause is specified, the + limit is set according to the + transfers-per-ns option. + + + + The keys clause identifies a + key_id defined by the key statement, + to be used for transaction security (TSIG, ) + when talking to the remote server. + When a request is sent to the remote server, a request signature + will be generated using the key specified here and appended to the + message. A request originating from the remote server is not + required + to be signed by this key. + + + + Although the grammar of the keys + clause + allows for multiple keys, only a single key per server is + currently + supported. + + + + The transfer-source and + transfer-source-v6 clauses specify + the IPv4 and IPv6 source + address to be used for zone transfer with the remote server, + respectively. + For an IPv4 remote server, only transfer-source can + be specified. + Similarly, for an IPv6 remote server, only + transfer-source-v6 can be + specified. + Form more details, see the description of + transfer-source and + transfer-source-v6 in + . + + + + + + <command>trusted-keys</command> Statement Grammar + trusted-keys { string number number number string ; string number number number string ; ... }; - -<command>trusted-keys</command> Statement Definition -and Usage -The trusted-keys statement defines DNSSEC -security roots. DNSSEC is described in . A security root is defined when the public key for a non-authoritative -zone is known, but cannot be securely obtained through DNS, either -because it is the DNS root zone or because its parent zone is unsigned. -Once a key has been configured as a trusted key, it is treated as -if it had been validated and proven secure. The resolver attempts -DNSSEC validation on all DNS data in subdomains of a security root. -The trusted-keys statement can contain -multiple key entries, each consisting of the key's domain name, -flags, protocol, algorithm, and the base-64 representation of the -key data. - - -<command>view</command> Statement Grammar + + + + <command>trusted-keys</command> Statement Definition + and Usage + + The trusted-keys statement defines + DNSSEC + security roots. DNSSEC is described in . A + security root is defined when the public key for a + non-authoritative + zone is known, but cannot be securely obtained through DNS, either + because it is the DNS root zone or because its parent zone is + unsigned. + Once a key has been configured as a trusted key, it is treated as + if it had been validated and proven secure. The resolver attempts + DNSSEC validation on all DNS data in subdomains of a security + root. + + + The trusted-keys statement can + contain + multiple key entries, each consisting of the key's domain name, + flags, protocol, algorithm, and the base-64 representation of the + key data. + + + + + <command>view</command> Statement Grammar + view view_name class { match-clients { address_match_list } ; @@ -4620,61 +7354,103 @@ key data. view_option; ... zone_statement; ... }; - -<command>view</command> Statement Definition and Usage - -The view statement is a powerful new feature -of BIND 9 that lets a name server answer a DNS query differently -depending on who is asking. It is particularly useful for implementing -split DNS setups without having to run multiple servers. - -Each view statement defines a view of the -DNS namespace that will be seen by a subset of clients. A client matches -a view if its source IP address matches the -address_match_list of the view's -match-clients clause and its destination IP address matches -the address_match_list of the view's -match-destinations clause. If not specified, both -match-clients and match-destinations -default to matching all addresses. In addition to checking IP addresses -match-clients and match-destinations -can also take keys which provide an mechanism for the -client to select the view. A view can also be specified -as match-recursive-only, which means that only recursive -requests from matching clients will match that view. -The order of the view statements is significant — -a client request will be resolved in the context of the first -view that it matches. - -Zones defined within a view statement will -be only be accessible to clients that match the view. - By defining a zone of the same name in multiple views, different -zone data can be given to different clients, for example, "internal" -and "external" clients in a split DNS setup. - -Many of the options given in the options statement -can also be used within a view statement, and then -apply only when resolving queries with that view. When no view-specific -value is given, the value in the options statement -is used as a default. Also, zone options can have default values specified -in the view statement; these view-specific defaults -take precedence over those in the options statement. - -Views are class specific. If no class is given, class IN -is assumed. Note that all non-IN views must contain a hint zone, -since only the IN class has compiled-in default hints. - -If there are no view statements in the config -file, a default view that matches any client is automatically created -in class IN. Any zone statements specified on -the top level of the configuration file are considered to be part of -this default view, and the options statement will -apply to the default view. If any explicit view -statements are present, all zone statements must -occur inside view statements. - -Here is an example of a typical split DNS setup implemented -using view statements. + + + + + <command>view</command> Statement Definition and Usage + + + The view statement is a powerful + new feature + of BIND 9 that lets a name server + answer a DNS query differently + depending on who is asking. It is particularly useful for + implementing + split DNS setups without having to run multiple servers. + + + + Each view statement defines a view + of the + DNS namespace that will be seen by a subset of clients. A client + matches + a view if its source IP address matches the + address_match_list of the view's + match-clients clause and its + destination IP address matches + the address_match_list of the + view's + match-destinations clause. If not + specified, both + match-clients and match-destinations + default to matching all addresses. In addition to checking IP + addresses + match-clients and match-destinations + can also take keys which provide an + mechanism for the + client to select the view. A view can also be specified + as match-recursive-only, which + means that only recursive + requests from matching clients will match that view. + The order of the view statements is + significant — + a client request will be resolved in the context of the first + view that it matches. + + + + Zones defined within a view + statement will + be only be accessible to clients that match the view. + By defining a zone of the same name in multiple views, different + zone data can be given to different clients, for example, + "internal" + and "external" clients in a split DNS setup. + + + + Many of the options given in the options statement + can also be used within a view + statement, and then + apply only when resolving queries with that view. When no + view-specific + value is given, the value in the options statement + is used as a default. Also, zone options can have default values + specified + in the view statement; these + view-specific defaults + take precedence over those in the options statement. + + + + Views are class specific. If no class is given, class IN + is assumed. Note that all non-IN views must contain a hint zone, + since only the IN class has compiled-in default hints. + + + + If there are no view statements in + the config + file, a default view that matches any client is automatically + created + in class IN. Any zone statements + specified on + the top level of the configuration file are considered to be part + of + this default view, and the options + statement will + apply to the default view. If any explicit view + statements are present, all zone + statements must + occur inside view statements. + + + + Here is an example of a typical split DNS setup implemented + using view statements. + + view "internal" { // This should match our internal networks. match-clients { 10.0.0.0/8; }; @@ -4705,10 +7481,13 @@ view "external" { }; }; - -<command>zone</command> -Statement Grammar - zone zone_name class { + + + + <command>zone</command> + Statement Grammar + +zone zone_name class { type ( master | slave | hint | stub | forward | delegation-only ) ; allow-notify { address_match_list } ; allow-query { address_match_list } ; @@ -4755,1100 +7534,2264 @@ Statement Grammar }; - -<command>zone</command> Statement Definition and Usage -Zone Types - - - - - - -master -The server has a master copy of the data -for the zone and will be able to provide authoritative answers for -it. - - -slave -A slave zone is a replica of a master -zone. The masters list specifies one or more IP addresses -of master servers that the slave contacts to update its copy of the zone. -Masters list elements can also be names of other masters lists. -By default, transfers are made from port 53 on the servers; this can -be changed for all servers by specifying a port number before the -list of IP addresses, or on a per-server basis after the IP address. -Authentication to the master can also be done with per-server TSIG keys. -If a file is specified, then the -replica will be written to this file whenever the zone is changed, -and reloaded from this file on a server restart. Use of a file is -recommended, since it often speeds server start-up and eliminates -a needless waste of bandwidth. Note that for large numbers (in the -tens or hundreds of thousands) of zones per server, it is best to -use a two level naming scheme for zone file names. For example, -a slave server for the zone example.com might place -the zone contents into a file called -ex/example.com where ex/ is -just the first two letters of the zone name. (Most operating systems -behave very slowly if you put 100 000 files into -a single directory.) - - -stub -A stub zone is similar to a slave zone, -except that it replicates only the NS records of a master zone instead -of the entire zone. Stub zones are not a standard part of the DNS; -they are a feature specific to the BIND implementation. - - -Stub zones can be used to eliminate the need for glue NS record -in a parent zone at the expense of maintaining a stub zone entry and -a set of name server addresses in named.conf. -This usage is not recommended for new configurations, and BIND 9 -supports it only in a limited way. -In BIND 4/8, zone transfers of a parent zone -included the NS records from stub children of that zone. This meant -that, in some cases, users could get away with configuring child stubs -only in the master server for the parent zone. BIND -9 never mixes together zone data from different zones in this -way. Therefore, if a BIND 9 master serving a parent -zone has child stub zones configured, all the slave servers for the -parent zone also need to have the same child stub zones -configured. - -Stub zones can also be used as a way of forcing the resolution -of a given domain to use a particular set of authoritative servers. -For example, the caching name servers on a private network using -RFC1981 addressing may be configured with stub zones for -10.in-addr.arpa -to use a set of internal name servers as the authoritative -servers for that domain. - - - -forward -A "forward zone" is a way to configure -forwarding on a per-domain basis. A zone statement -of type forward can contain a forward and/or forwarders statement, -which will apply to queries within the domain given by the zone -name. If no forwarders statement is present or -an empty list for forwarders is given, then no -forwarding will be done for the domain, canceling the effects of -any forwarders in the options statement. Thus -if you want to use this type of zone to change the behavior of the -global forward option (that is, "forward first -to", then "forward only", or vice versa, but want to use the same -servers as set globally) you need to re-specify the global forwarders. - - - -hint -The initial set of root name servers is -specified using a "hint zone". When the server starts up, it uses -the root hints to find a root name server and get the most recent -list of root name servers. If no hint zone is specified for class -IN, the server uses a compiled-in default set of root servers hints. -Classes other than IN have no built-in defaults hints. - - -delegation-only -This is used to enforce the delegation only -status of infrastructure zones (e.g. COM, NET, ORG). Any answer that -is received without a explicit or implicit delegation in the authority -section will be treated as NXDOMAIN. This does not apply to the zone -apex. This SHOULD NOT be applied to leaf zones. -delegation-only has no effect on answers received -from forwarders. - - - - -Class -The zone's name may optionally be followed by a class. If -a class is not specified, class IN (for Internet), -is assumed. This is correct for the vast majority of cases. -The hesiod class is -named for an information service from MIT's Project Athena. It is -used to share information about various systems databases, such -as users, groups, printers and so on. The keyword -HS is -a synonym for hesiod. -Another MIT development is CHAOSnet, a LAN protocol created -in the mid-1970s. Zone data for it can be specified with the CHAOS class. - - -Zone Options - - - -journal -Allow the default journal's file name to be overridden. -The default is the zone's file with ".jnl" appended. -This is applicable to master and slave zones. - - - -allow-notify -See the description of -allow-notify in - - -allow-query -See the description of -allow-query in - - -allow-transfer -See the description of allow-transfer -in . - - -allow-update -See the description of allow-update -in . - - -update-policy -Specifies a "Simple Secure Update" policy. See -. - - -allow-update-forwarding -See the description of allow-update-forwarding -in . - - -also-notify -Only meaningful if notify is -active for this zone. The set of machines that will receive a -DNS NOTIFY message -for this zone is made up of all the listed name servers (other than -the primary master) for the zone plus any IP addresses specified -with also-notify. A port may be specified -with each also-notify address to send the notify -messages to a port other than the default of 53. -also-notify is not meaningful for stub zones. -The default is the empty list. - - -check-names - -This option is used to restrict the character set and syntax of -certain domain names in master files and/or DNS responses received from the -network. The default varies according to zone type. For master zones the default is fail. For slave -zones the default is warn. - - - -check-wildcard -See the description of -check-wildcard in . - - -database -Specify the type of database to be used for storing the -zone data. The string following the database keyword -is interpreted as a list of whitespace-delimited words. The first word -identifies the database type, and any subsequent words are passed -as arguments to the database to be interpreted in a way specific -to the database type. -The default is "rbt", BIND 9's native in-memory -red-black-tree database. This database does not take arguments. -Other values are possible if additional database drivers -have been linked into the server. Some sample drivers are included -with the distribution but none are linked in by default. - - -dialup -See the description of -dialup in . - - -delegation-only -The flag only applies to hint and stub zones. If set -to yes then the zone will also be treated as if it -is also a delegation-only type zone. - - - -forward -Only meaningful if the zone has a forwarders -list. The only value causes the lookup to fail -after trying the forwarders and getting no answer, while first would -allow a normal lookup to be tried. - - -forwarders -Used to override the list of global forwarders. -If it is not specified in a zone of type forward, -no forwarding is done for the zone; the global options are not used. - - -ixfr-base -Was used in BIND 8 to specify the name -of the transaction log (journal) file for dynamic update and IXFR. -BIND 9 ignores the option and constructs the name of the journal -file by appending ".jnl" to the name of the -zone file. - - -ixfr-tmp-file -Was an undocumented option in BIND 8. -Ignored in BIND 9. - - -max-transfer-time-in -See the description of -max-transfer-time-in in . - - -max-transfer-idle-in -See the description of -max-transfer-idle-in in . - - -max-transfer-time-out -See the description of -max-transfer-time-out in . - - -max-transfer-idle-out -See the description of -max-transfer-idle-out in . - - -notify -See the description of -notify in . - - -pubkey -In BIND 8, this option was intended for specifying -a public zone key for verification of signatures in DNSSEC signed -zones when they are loaded from disk. BIND 9 does not verify signatures -on load and ignores the option. - - -zone-statistics -If yes, the server will keep statistical -information for this zone, which can be dumped to the -statistics-file defined in the server options. - - -sig-validity-interval -See the description of -sig-validity-interval in . - - -transfer-source -See the description of -transfer-source in - - - -transfer-source-v6 -See the description of -transfer-source-v6 in - - - -alt-transfer-source -See the description of -alt-transfer-source in - - - -alt-transfer-source-v6 -See the description of -alt-transfer-source-v6 in - - - -use-alt-transfer-source -See the description of -use-alt-transfer-source in - - - - -notify-source -See the description of -notify-source in - - - -notify-source-v6 -See the description of -notify-source-v6 in . - - - - -min-refresh-time -max-refresh-time -min-retry-time -max-retry-time - -See the description in . - - -ixfr-from-differences -See the description of -ixfr-from-differences in . - - -key-directory -See the description of -key-directory in - - -multi-master -See the description of -multi-master in . - - - - - -Dynamic Update Policies -BIND 9 supports two alternative methods of granting clients -the right to perform dynamic updates to a zone, -configured by the allow-update and -update-policy option, respectively. -The allow-update clause works the same -way as in previous versions of BIND. It grants given clients the -permission to update any record of any name in the zone. -The update-policy clause is new in BIND -9 and allows more fine-grained control over what updates are allowed. -A set of rules is specified, where each rule either grants or denies -permissions for one or more names to be updated by one or more identities. - If the dynamic update request message is signed (that is, it includes -either a TSIG or SIG(0) record), the identity of the signer can -be determined. -Rules are specified in the update-policy zone -option, and are only meaningful for master zones. When the update-policy statement -is present, it is a configuration error for the allow-update statement -to be present. The update-policy statement only -examines the signer of a message; the source address is not relevant. -This is how a rule definition looks: + + + + <command>zone</command> Statement Definition and Usage + + Zone Types + + + + + + + + + master + + + + + The server has a master copy of the data + for the zone and will be able to provide authoritative + answers for + it. + + + + + + + slave + + + + + A slave zone is a replica of a master + zone. The masters list + specifies one or more IP addresses + of master servers that the slave contacts to update + its copy of the zone. + Masters list elements can also be names of other + masters lists. + By default, transfers are made from port 53 on the + servers; this can + be changed for all servers by specifying a port number + before the + list of IP addresses, or on a per-server basis after + the IP address. + Authentication to the master can also be done with + per-server TSIG keys. + If a file is specified, then the + replica will be written to this file whenever the zone + is changed, + and reloaded from this file on a server restart. Use + of a file is + recommended, since it often speeds server start-up and + eliminates + a needless waste of bandwidth. Note that for large + numbers (in the + tens or hundreds of thousands) of zones per server, it + is best to + use a two level naming scheme for zone file names. For + example, + a slave server for the zone example.com might place + the zone contents into a file called + ex/example.com where ex/ is + just the first two letters of the zone name. (Most + operating systems + behave very slowly if you put 100 000 files into + a single directory.) + + + + + + + stub + + + + + A stub zone is similar to a slave zone, + except that it replicates only the NS records of a + master zone instead + of the entire zone. Stub zones are not a standard part + of the DNS; + they are a feature specific to the BIND implementation. + + + + Stub zones can be used to eliminate the need for glue + NS record + in a parent zone at the expense of maintaining a stub + zone entry and + a set of name server addresses in named.conf. + This usage is not recommended for new configurations, + and BIND 9 + supports it only in a limited way. + In BIND 4/8, zone + transfers of a parent zone + included the NS records from stub children of that + zone. This meant + that, in some cases, users could get away with + configuring child stubs + only in the master server for the parent zone. BIND + 9 never mixes together zone data from different zones + in this + way. Therefore, if a BIND 9 master serving a parent + zone has child stub zones configured, all the slave + servers for the + parent zone also need to have the same child stub + zones + configured. + + + + Stub zones can also be used as a way of forcing the + resolution + of a given domain to use a particular set of + authoritative servers. + For example, the caching name servers on a private + network using + RFC1981 addressing may be configured with stub zones + for + 10.in-addr.arpa + to use a set of internal name servers as the + authoritative + servers for that domain. + + + + + + + forward + + + + + A "forward zone" is a way to configure + forwarding on a per-domain basis. A zone statement + of type forward can + contain a forward + and/or forwarders + statement, + which will apply to queries within the domain given by + the zone + name. If no forwarders + statement is present or + an empty list for forwarders is given, then no + forwarding will be done for the domain, canceling the + effects of + any forwarders in the options statement. Thus + if you want to use this type of zone to change the + behavior of the + global forward option + (that is, "forward first + to", then "forward only", or vice versa, but want to + use the same + servers as set globally) you need to re-specify the + global forwarders. + + + + + + + hint + + + + + The initial set of root name servers is + specified using a "hint zone". When the server starts + up, it uses + the root hints to find a root name server and get the + most recent + list of root name servers. If no hint zone is + specified for class + IN, the server uses a compiled-in default set of root + servers hints. + Classes other than IN have no built-in defaults hints. + + + + + + + delegation-only + + + + + This is used to enforce the delegation only + status of infrastructure zones (e.g. COM, NET, ORG). + Any answer that + is received without a explicit or implicit delegation + in the authority + section will be treated as NXDOMAIN. This does not + apply to the zone + apex. This SHOULD NOT be applied to leaf zones. + + + delegation-only has no + effect on answers received + from forwarders. + + + + + + + + + + Class + + The zone's name may optionally be followed by a class. If + a class is not specified, class IN (for Internet), + is assumed. This is correct for the vast majority of cases. + + + The hesiod class is + named for an information service from MIT's Project Athena. It + is + used to share information about various systems databases, such + as users, groups, printers and so on. The keyword + HS is + a synonym for hesiod. + + + Another MIT development is CHAOSnet, a LAN protocol created + in the mid-1970s. Zone data for it can be specified with the CHAOS class. + + + + + Zone Options + + + + + journal + + + Allow the default journal's file name to be overridden. + The default is the zone's file with ".jnl" appended. + This is applicable to master and slave zones. + + + + + + allow-notify + + + See the description of + allow-notify in + + + + + + allow-query + + + See the description of + allow-query in + + + + + + allow-transfer + + + See the description of allow-transfer + in . + + + + + + allow-update + + + See the description of allow-update + in . + + + + + + update-policy + + + Specifies a "Simple Secure Update" policy. See + . + + + + + + allow-update-forwarding + + + See the description of allow-update-forwarding + in . + + + + + + also-notify + + + Only meaningful if notify + is + active for this zone. The set of machines that will + receive a + DNS NOTIFY message + for this zone is made up of all the listed name servers + (other than + the primary master) for the zone plus any IP addresses + specified + with also-notify. A port + may be specified + with each also-notify + address to send the notify + messages to a port other than the default of 53. + also-notify is not + meaningful for stub zones. + The default is the empty list. + + + + + + check-names + + + This option is used to restrict the character set and + syntax of + certain domain names in master files and/or DNS responses + received from the + network. The default varies according to zone type. For master zones the default is fail. For slave + zones the default is warn. + + + + + + check-wildcard + + + See the description of + check-wildcard in . + + + + + + database + + + Specify the type of database to be used for storing the + zone data. The string following the database keyword + is interpreted as a list of whitespace-delimited words. + The first word + identifies the database type, and any subsequent words are + passed + as arguments to the database to be interpreted in a way + specific + to the database type. + + + The default is "rbt", BIND 9's + native in-memory + red-black-tree database. This database does not take + arguments. + + + Other values are possible if additional database drivers + have been linked into the server. Some sample drivers are + included + with the distribution but none are linked in by default. + + + + + + dialup + + + See the description of + dialup in . + + + + + + delegation-only + + + The flag only applies to hint and stub zones. If set + to yes then the zone will also be + treated as if it + is also a delegation-only type zone. + + + + + + forward + + + Only meaningful if the zone has a forwarders + list. The only value causes + the lookup to fail + after trying the forwarders and getting no answer, while first would + allow a normal lookup to be tried. + + + + + + forwarders + + + Used to override the list of global forwarders. + If it is not specified in a zone of type forward, + no forwarding is done for the zone; the global options are + not used. + + + + + + ixfr-base + + + Was used in BIND 8 to + specify the name + of the transaction log (journal) file for dynamic update + and IXFR. + BIND 9 ignores the option + and constructs the name of the journal + file by appending ".jnl" + to the name of the + zone file. + + + + + + ixfr-tmp-file + + + Was an undocumented option in BIND 8. + Ignored in BIND 9. + + + + + + max-transfer-time-in + + + See the description of + max-transfer-time-in in . + + + + + + max-transfer-idle-in + + + See the description of + max-transfer-idle-in in . + + + + + + max-transfer-time-out + + + See the description of + max-transfer-time-out in . + + + + + + max-transfer-idle-out + + + See the description of + max-transfer-idle-out in . + + + + + + notify + + + See the description of + notify in . + + + + + + pubkey + + + In BIND 8, this option was + intended for specifying + a public zone key for verification of signatures in DNSSEC + signed + zones when they are loaded from disk. BIND 9 does not verify signatures + on load and ignores the option. + + + + + + zone-statistics + + + If yes, the server will keep + statistical + information for this zone, which can be dumped to the + statistics-file defined in + the server options. + + + + + + sig-validity-interval + + + See the description of + sig-validity-interval in . + + + + + + transfer-source + + + See the description of + transfer-source in + + + + + + transfer-source-v6 + + + See the description of + transfer-source-v6 in + + + + + + alt-transfer-source + + + See the description of + alt-transfer-source in + + + + + + alt-transfer-source-v6 + + + See the description of + alt-transfer-source-v6 in + + + + + + use-alt-transfer-source + + + See the description of + use-alt-transfer-source in + + + + + + + notify-source + + + See the description of + notify-source in + + + + + + notify-source-v6 + + + See the description of + notify-source-v6 in . + + + + + + min-refresh-time + max-refresh-time + min-retry-time + max-retry-time + + + See the description in . + + + + + + ixfr-from-differences + + + See the description of + ixfr-from-differences in . + + + + + + key-directory + + + See the description of + key-directory in + + + + + + multi-master + + + See the description of + multi-master in . + + + + + + + + + Dynamic Update Policies + + BIND 9 supports two alternative + methods of granting clients + the right to perform dynamic updates to a zone, + configured by the allow-update + and + update-policy option, + respectively. + + + The allow-update clause works the + same + way as in previous versions of BIND. It grants given clients the + permission to update any record of any name in the zone. + + + The update-policy clause is new + in BIND + 9 and allows more fine-grained control over what updates are + allowed. + A set of rules is specified, where each rule either grants or + denies + permissions for one or more names to be updated by one or more + identities. + If the dynamic update request message is signed (that is, it + includes + either a TSIG or SIG(0) record), the identity of the signer can + be determined. + + + Rules are specified in the update-policy zone + option, and are only meaningful for master zones. When the update-policy statement + is present, it is a configuration error for the allow-update statement + to be present. The update-policy + statement only + examines the signer of a message; the source address is not + relevant. + + + This is how a rule definition looks: + + ( grant | deny ) identity nametype name types -Each rule grants or denies privileges. Once a message has -successfully matched a rule, the operation is immediately granted -or denied and no further rules are examined. A rule is matched -when the signer matches the identity field, the name matches the -name field in accordance with the nametype field, and the type matches -the types specified in the type field. - -The identity field specifies a name or a wildcard name. Normally, this -is the name of the TSIG or SIG(0) key used to sign the update request. When a -TKEY exchange has been used to create a shared secret, the identity of the -shared secret is the same as the identity of the key used to authenticate the -TKEY exchange. When the identity field specifies a -wildcard name, it is subject to DNS wildcard expansion, so the rule will apply -to multiple identities. The identity field must -contain a fully qualified domain name. - -The nametype field has 4 values: -name, subdomain, -wildcard, and self. - - - - - - - -name -Exact-match semantics. This rule matches when the -name being updated is identical to the contents of the -name field. - - -subdomain -This rule matches when the name being updated -is a subdomain of, or identical to, the contents of the -name field. - - -wildcard -The name field is -subject to DNS wildcard expansion, and this rule matches when the name -being updated name is a valid expansion of the wildcard. - - -self -This rule matches when the name being updated -matches the contents of the identity field. -The name field is ignored, but should be -the same as the identity field. The -self nametype is most useful when allowing using -one key per name to update, where the key has the same name as the name -to be updated. The identity would be -specified as * in this case. - - - - -In all cases, the name field must -specify a fully qualified domain name. - -If no types are explicitly specified, this rule matches all types except -SIG, NS, SOA, and NXT. Types may be specified by name, including -"ANY" (ANY matches all types except NXT, which can never be updated). -Note that when an attempt is made to delete all records associated with a -name, the rules are checked for each existing record type. - - - - - - Zone File - - Types of Resource Records and When to Use Them -This section, largely borrowed from RFC 1034, describes the -concept of a Resource Record (RR) and explains when each is used. -Since the publication of RFC 1034, several new RRs have been identified -and implemented in the DNS. These are also included. - - Resource Records - - A domain name identifies a node. Each node has a set of - resource information, which may be empty. The set of resource - information associated with a particular name is composed of - separate RRs. The order of RRs in a set is not significant and - need not be preserved by name servers, resolvers, or other - parts of the DNS. However, sorting of multiple RRs is - permitted for optimization purposes, for example, to specify - that a particular nearby server be tried first. See and . - -The components of a Resource Record are: - - - - - -owner name -the domain name where the RR is found. - - -type -an encoded 16 bit value that specifies -the type of the resource record. - - -TTL -the time to live of the RR. This field -is a 32 bit integer in units of seconds, and is primarily used by -resolvers when they cache RRs. The TTL describes how long a RR can -be cached before it should be discarded. - - -class -an encoded 16 bit value that identifies -a protocol family or instance of a protocol. - - -RDATA -the resource data. The format of the -data is type (and sometimes class) specific. - - - -The following are types of valid RRs: - - - - - -A -a host address. In the IN class, this is a -32-bit IP address. Described in RFC 1035. - - -AAAA -IPv6 address. Described in RFC 1886. - - -A6 -IPv6 address. This can be a partial -address (a suffix) and an indirection to the name where the rest of the -address (the prefix) can be found. Experimental. Described in RFC 2874. - - -AFSDB -location of AFS database servers. -Experimental. Described in RFC 1183. - - -APL -address prefix list. Experimental. -Described in RFC 3123. - - -CERT -holds a digital certificate. -Described in RFC 2538. - - -CNAME -identifies the canonical name of an alias. -Described in RFC 1035. - - -DNAME -Replaces the domain name specified with -another name to be looked up, effectively aliasing an entire -subtree of the domain name space rather than a single record -as in the case of the CNAME RR. -Described in RFC 2672. - - -GPOS -Specifies the global position. Superseded by LOC. - - -HINFO -identifies the CPU and OS used by a host. -Described in RFC 1035. - - -ISDN -representation of ISDN addresses. -Experimental. Described in RFC 1183. - - -KEY -stores a public key associated with a -DNS name. Described in RFC 2535. - - -KX -identifies a key exchanger for this -DNS name. Described in RFC 2230. - - -LOC -for storing GPS info. Described in RFC 1876. -Experimental. - - -MX -identifies a mail exchange for the domain. -a 16 bit preference value (lower is better) -followed by the host name of the mail exchange. -Described in RFC 974, RFC 1035. - - -NAPTR -name authority pointer. Described in RFC 2915. - - -NSAP -a network service access point. -Described in RFC 1706. - - -NS -the authoritative name server for the -domain. Described in RFC 1035. - - -NXT -used in DNSSEC to securely indicate that -RRs with an owner name in a certain name interval do not exist in -a zone and indicate what RR types are present for an existing name. -Described in RFC 2535. - - -PTR -a pointer to another part of the domain -name space. Described in RFC 1035. - - -PX -provides mappings between RFC 822 and X.400 -addresses. Described in RFC 2163. - - -RP -information on persons responsible -for the domain. Experimental. Described in RFC 1183. - - -RT -route-through binding for hosts that -do not have their own direct wide area network addresses. -Experimental. Described in RFC 1183. - - -SIG -("signature") contains data authenticated -in the secure DNS. Described in RFC 2535. - - -SOA -identifies the start of a zone of authority. -Described in RFC 1035. - - -SRV -information about well known network -services (replaces WKS). Described in RFC 2782. - - -TXT -text records. Described in RFC 1035. - - -WKS -information about which well known -network services, such as SMTP, that a domain supports. Historical. - - - -X25 -representation of X.25 network addresses. -Experimental. Described in RFC 1183. - - - -The following classes of resource records -are currently valid in the DNS: - - - - - -IN -The Internet. - - - -CH - -CHAOSnet, a LAN protocol created at MIT in the mid-1970s. -Rarely used for its historical purpose, but reused for BIND's -built-in server information zones, e.g., -version.bind. - - - - -HS - -Hesiod, an information service -developed by MIT's Project Athena. It is used to share information -about various systems databases, such as users, groups, printers -and so on. - - - - - - -The owner name is often implicit, rather than forming an integral -part of the RR. For example, many name servers internally form tree -or hash structures for the name space, and chain RRs off nodes. - The remaining RR parts are the fixed header (type, class, TTL) -which is consistent for all RRs, and a variable part (RDATA) that -fits the needs of the resource being described. -The meaning of the TTL field is a time limit on how long an -RR can be kept in a cache. This limit does not apply to authoritative -data in zones; it is also timed out, but by the refreshing policies -for the zone. The TTL is assigned by the administrator for the -zone where the data originates. While short TTLs can be used to -minimize caching, and a zero TTL prohibits caching, the realities -of Internet performance suggest that these times should be on the -order of days for the typical host. If a change can be anticipated, -the TTL can be reduced prior to the change to minimize inconsistency -during the change, and then increased back to its former value following -the change. -The data in the RDATA section of RRs is carried as a combination -of binary strings and domain names. The domain names are frequently -used as "pointers" to other data in the DNS. -Textual expression of RRs -RRs are represented in binary form in the packets of the DNS -protocol, and are usually represented in highly encoded form when -stored in a name server or resolver. In the examples provided in -RFC 1034, a style similar to that used in master files was employed -in order to show the contents of RRs. In this format, most RRs -are shown on a single line, although continuation lines are possible -using parentheses. -The start of the line gives the owner of the RR. If a line -begins with a blank, then the owner is assumed to be the same as -that of the previous RR. Blank lines are often included for readability. -Following the owner, we list the TTL, type, and class of the -RR. Class and type use the mnemonics defined above, and TTL is -an integer before the type field. In order to avoid ambiguity in -parsing, type and class mnemonics are disjoint, TTLs are integers, -and the type mnemonic is always last. The IN class and TTL values -are often omitted from examples in the interests of clarity. -The resource data or RDATA section of the RR are given using -knowledge of the typical representation for the data. -For example, we might show the RRs carried in a message as: - - - - - -ISI.EDU. -MX -10 VENERA.ISI.EDU. - - - -MX -10 VAXA.ISI.EDU - - -VENERA.ISI.EDU -A -128.9.0.32 - - - -A -10.1.0.52 - - -VAXA.ISI.EDU -A -10.2.0.27 - - - -A -128.9.0.33 - - - -The MX RRs have an RDATA section which consists of a 16 bit -number followed by a domain name. The address RRs use a standard -IP address format to contain a 32 bit internet address. -This example shows six RRs, with two RRs at each of three -domain names. -Similarly we might see: - - - - - -XX.LCS.MIT.EDU. IN -A -10.0.0.44 - - -CH -A -MIT.EDU. 2420 - - - -This example shows two addresses for XX.LCS.MIT.EDU, -each of a different class. - -Discussion of MX Records - -As described above, domain servers store information as a -series of resource records, each of which contains a particular -piece of information about a given domain name (which is usually, -but not always, a host). The simplest way to think of a RR is as -a typed pair of data, a domain name matched with a relevant datum, -and stored with some additional type information to help systems -determine when the RR is relevant. - -MX records are used to control delivery of email. The data -specified in the record is a priority and a domain name. The priority -controls the order in which email delivery is attempted, with the -lowest number first. If two priorities are the same, a server is -chosen randomly. If no servers at a given priority are responding, -the mail transport agent will fall back to the next largest priority. -Priority numbers do not have any absolute meaning — they are relevant -only respective to other MX records for that domain name. The domain -name given is the machine to which the mail will be delivered. It must have -an associated A record — CNAME is not sufficient. -For a given domain, if there is both a CNAME record and an -MX record, the MX record is in error, and will be ignored. Instead, -the mail will be delivered to the server specified in the MX record -pointed to by the CNAME. - - - - - - - - -example.com. -IN -MX -10 -mail.example.com. - - - -IN -MX -10 -mail2.example.com. - - - -IN -MX -20 -mail.backup.org. - - -mail.example.com. -IN -A -10.0.0.1 - - - -mail2.example.com. -IN -A -10.0.0.2 - - - -For example: -Mail delivery will be attempted to mail.example.com and -mail2.example.com (in -any order), and if neither of those succeed, delivery to mail.backup.org will -be attempted. -Setting TTLs -The time to live of the RR field is a 32 bit integer represented -in units of seconds, and is primarily used by resolvers when they -cache RRs. The TTL describes how long a RR can be cached before it -should be discarded. The following three types of TTL are currently -used in a zone file. - - - - - -SOA -The last field in the SOA is the negative -caching TTL. This controls how long other servers will cache no-such-domain -(NXDOMAIN) responses from you.The maximum time for -negative caching is 3 hours (3h). - - -$TTL -The $TTL directive at the top of the -zone file (before the SOA) gives a default TTL for every RR without -a specific TTL set. - - -RR TTLs -Each RR can have a TTL as the second -field in the RR, which will control how long other servers can cache -the it. - - - -All of these TTLs default to units of seconds, though units -can be explicitly specified, for example, 1h30m. -Inverse Mapping in IPv4 -Reverse name resolution (that is, translation from IP address -to name) is achieved by means of the in-addr.arpa domain -and PTR records. Entries in the in-addr.arpa domain are made in -least-to-most significant order, read left to right. This is the -opposite order to the way IP addresses are usually written. Thus, -a machine with an IP address of 10.1.2.3 would have a corresponding -in-addr.arpa name of -3.2.1.10.in-addr.arpa. This name should have a PTR resource record -whose data field is the name of the machine or, optionally, multiple -PTR records if the machine has more than one name. For example, -in the example.com domain: - - - - - - -$ORIGIN -2.1.10.in-addr.arpa - - -3 -IN PTR foo.example.com. - - - - -The $ORIGIN lines in the examples -are for providing context to the examples only-they do not necessarily -appear in the actual usage. They are only used here to indicate -that the example is relative to the listed origin. -Other Zone File Directives -The Master File Format was initially defined in RFC 1035 and -has subsequently been extended. While the Master File Format itself -is class independent all records in a Master File must be of the same -class. -Master File Directives include $ORIGIN, $INCLUDE, -and $TTL. -The <command>$ORIGIN</command> Directive -Syntax: $ORIGIN -domain-name comment -$ORIGIN sets the domain name that will -be appended to any unqualified records. When a zone is first read -in there is an implicit $ORIGIN <zone-name>. The -current $ORIGIN is appended to the domain specified -in the $ORIGIN argument if it is not absolute. -$ORIGIN example.com. -WWW CNAME MAIN-SERVER -is equivalent to -WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. -The <command>$INCLUDE</command> Directive -Syntax: $INCLUDE -filename -origin comment -Read and process the file filename as -if it were included into the file at this point. If origin is -specified the file is processed with $ORIGIN set -to that value, otherwise the current $ORIGIN is -used. -The origin and the current domain name -revert to the values they had prior to the $INCLUDE once -the file has been read. - -RFC 1035 specifies that the current origin should be restored after -an $INCLUDE, but it is silent on whether the current -domain name should also be restored. BIND 9 restores both of them. -This could be construed as a deviation from RFC 1035, a feature, or both. - - -The <command>$TTL</command> Directive -Syntax: $TTL -default-ttl -comment -Set the default Time To Live (TTL) for subsequent records -with undefined TTLs. Valid TTLs are of the range 0-2147483647 seconds. -$TTL is defined in RFC 2308. -<acronym>BIND</acronym> Master File Extension: the <command>$GENERATE</command> Directive - Syntax: $GENERATE range lhs ttl class type rhs comment -$GENERATE is used to create a series of -resource records that only differ from each other by an iterator. $GENERATE can -be used to easily generate the sets of records required to support -sub /24 reverse delegations described in RFC 2317: Classless IN-ADDR.ARPA -delegation. -$ORIGIN 0.0.192.IN-ADDR.ARPA. + + + Each rule grants or denies privileges. Once a message has + successfully matched a rule, the operation is immediately + granted + or denied and no further rules are examined. A rule is matched + when the signer matches the identity field, the name matches the + name field in accordance with the nametype field, and the type + matches + the types specified in the type field. + + + + The identity field specifies a name or a wildcard name. + Normally, this + is the name of the TSIG or SIG(0) key used to sign the update + request. When a + TKEY exchange has been used to create a shared secret, the + identity of the + shared secret is the same as the identity of the key used to + authenticate the + TKEY exchange. When the identity field specifies a + wildcard name, it is subject to DNS wildcard expansion, so the + rule will apply + to multiple identities. The identity field must + contain a fully qualified domain name. + + + + The nametype field has 4 + values: + name, subdomain, + wildcard, and self. + + + + + + + + + + name + + + + + Exact-match semantics. This rule matches when the + name being updated is identical to the contents of the + name field. + + + + + + + subdomain + + + + + This rule matches when the name being updated + is a subdomain of, or identical to, the contents of + the + name field. + + + + + + + wildcard + + + + + The name field + is + subject to DNS wildcard expansion, and this rule + matches when the name + being updated name is a valid expansion of the + wildcard. + + + + + + + self + + + + + This rule matches when the name being updated + matches the contents of the identity field. + The name field + is ignored, but should be + the same as the identity field. The + self nametype is most + useful when allowing using + one key per name to update, where the key has the same + name as the name + to be updated. The identity would be + specified as * in + this case. + + + + + + + + + In all cases, the name + field must + specify a fully qualified domain name. + + + + If no types are explicitly specified, this rule matches all + types except + SIG, NS, SOA, and NXT. Types may be specified by name, including + "ANY" (ANY matches all types except NXT, which can never be + updated). + Note that when an attempt is made to delete all records + associated with a + name, the rules are checked for each existing record type. + + + + + + Zone File + + Types of Resource Records and When to Use Them + + This section, largely borrowed from RFC 1034, describes the + concept of a Resource Record (RR) and explains when each is used. + Since the publication of RFC 1034, several new RRs have been + identified + and implemented in the DNS. These are also included. + + + Resource Records + + + A domain name identifies a node. Each node has a set of + resource information, which may be empty. The set of resource + information associated with a particular name is composed of + separate RRs. The order of RRs in a set is not significant and + need not be preserved by name servers, resolvers, or other + parts of the DNS. However, sorting of multiple RRs is + permitted for optimization purposes, for example, to specify + that a particular nearby server be tried first. See and . + + + + The components of a Resource Record are: + + + + + + + + + + owner name + + + + + the domain name where the RR is found. + + + + + + + type + + + + + an encoded 16 bit value that specifies + the type of the resource record. + + + + + + + TTL + + + + + the time to live of the RR. This field + is a 32 bit integer in units of seconds, and is + primarily used by + resolvers when they cache RRs. The TTL describes how + long a RR can + be cached before it should be discarded. + + + + + + + class + + + + + an encoded 16 bit value that identifies + a protocol family or instance of a protocol. + + + + + + + RDATA + + + + + the resource data. The format of the + data is type (and sometimes class) specific. + + + + + + + + The following are types of valid RRs: + + + + + + + + + + A + + + + + a host address. In the IN class, this is a + 32-bit IP address. Described in RFC 1035. + + + + + + + AAAA + + + + + IPv6 address. Described in RFC 1886. + + + + + + + A6 + + + + + IPv6 address. This can be a partial + address (a suffix) and an indirection to the name + where the rest of the + address (the prefix) can be found. Experimental. + Described in RFC 2874. + + + + + + + AFSDB + + + + + location of AFS database servers. + Experimental. Described in RFC 1183. + + + + + + + APL + + + + + address prefix list. Experimental. + Described in RFC 3123. + + + + + + + CERT + + + + + holds a digital certificate. + Described in RFC 2538. + + + + + + + CNAME + + + + + identifies the canonical name of an alias. + Described in RFC 1035. + + + + + + + DNAME + + + + + Replaces the domain name specified with + another name to be looked up, effectively aliasing an + entire + subtree of the domain name space rather than a single + record + as in the case of the CNAME RR. + Described in RFC 2672. + + + + + + + GPOS + + + + + Specifies the global position. Superseded by LOC. + + + + + + + HINFO + + + + + identifies the CPU and OS used by a host. + Described in RFC 1035. + + + + + + + ISDN + + + + + representation of ISDN addresses. + Experimental. Described in RFC 1183. + + + + + + + KEY + + + + + stores a public key associated with a + DNS name. Described in RFC 2535. + + + + + + + KX + + + + + identifies a key exchanger for this + DNS name. Described in RFC 2230. + + + + + + + LOC + + + + + for storing GPS info. Described in RFC 1876. + Experimental. + + + + + + + MX + + + + + identifies a mail exchange for the domain. + a 16 bit preference value (lower is better) + followed by the host name of the mail exchange. + Described in RFC 974, RFC 1035. + + + + + + + NAPTR + + + + + name authority pointer. Described in RFC 2915. + + + + + + + NSAP + + + + + a network service access point. + Described in RFC 1706. + + + + + + + NS + + + + + the authoritative name server for the + domain. Described in RFC 1035. + + + + + + + NXT + + + + + used in DNSSEC to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Described in RFC 2535. + + + + + + + PTR + + + + + a pointer to another part of the domain + name space. Described in RFC 1035. + + + + + + + PX + + + + + provides mappings between RFC 822 and X.400 + addresses. Described in RFC 2163. + + + + + + + RP + + + + + information on persons responsible + for the domain. Experimental. Described in RFC 1183. + + + + + + + RT + + + + + route-through binding for hosts that + do not have their own direct wide area network + addresses. + Experimental. Described in RFC 1183. + + + + + + + SIG + + + + + ("signature") contains data authenticated + in the secure DNS. Described in RFC 2535. + + + + + + + SOA + + + + + identifies the start of a zone of authority. + Described in RFC 1035. + + + + + + + SRV + + + + + information about well known network + services (replaces WKS). Described in RFC 2782. + + + + + + + TXT + + + + + text records. Described in RFC 1035. + + + + + + + WKS + + + + + information about which well known + network services, such as SMTP, that a domain + supports. Historical. + + + + + + + X25 + + + + + representation of X.25 network addresses. + Experimental. Described in RFC 1183. + + + + + + + + The following classes of resource records + are currently valid in the DNS: + + + + + + + + + + IN + + + + + The Internet. + + + + + + + + CH + + + + + CHAOSnet, a LAN protocol created at MIT in the + mid-1970s. + Rarely used for its historical purpose, but reused for + BIND's + built-in server information zones, e.g., + version.bind. + + + + + + + + HS + + + + + Hesiod, an information service + developed by MIT's Project Athena. It is used to share + information + about various systems databases, such as users, + groups, printers + and so on. + + + + + + + + + + The owner name is often implicit, rather than forming an + integral + part of the RR. For example, many name servers internally form + tree + or hash structures for the name space, and chain RRs off nodes. + The remaining RR parts are the fixed header (type, class, TTL) + which is consistent for all RRs, and a variable part (RDATA) + that + fits the needs of the resource being described. + + + The meaning of the TTL field is a time limit on how long an + RR can be kept in a cache. This limit does not apply to + authoritative + data in zones; it is also timed out, but by the refreshing + policies + for the zone. The TTL is assigned by the administrator for the + zone where the data originates. While short TTLs can be used to + minimize caching, and a zero TTL prohibits caching, the + realities + of Internet performance suggest that these times should be on + the + order of days for the typical host. If a change can be + anticipated, + the TTL can be reduced prior to the change to minimize + inconsistency + during the change, and then increased back to its former value + following + the change. + + + The data in the RDATA section of RRs is carried as a combination + of binary strings and domain names. The domain names are + frequently + used as "pointers" to other data in the DNS. + + + + Textual expression of RRs + + RRs are represented in binary form in the packets of the DNS + protocol, and are usually represented in highly encoded form + when + stored in a name server or resolver. In the examples provided + in + RFC 1034, a style similar to that used in master files was + employed + in order to show the contents of RRs. In this format, most RRs + are shown on a single line, although continuation lines are + possible + using parentheses. + + + The start of the line gives the owner of the RR. If a line + begins with a blank, then the owner is assumed to be the same as + that of the previous RR. Blank lines are often included for + readability. + + + Following the owner, we list the TTL, type, and class of the + RR. Class and type use the mnemonics defined above, and TTL is + an integer before the type field. In order to avoid ambiguity + in + parsing, type and class mnemonics are disjoint, TTLs are + integers, + and the type mnemonic is always last. The IN class and TTL + values + are often omitted from examples in the interests of clarity. + + + The resource data or RDATA section of the RR are given using + knowledge of the typical representation for the data. + + + For example, we might show the RRs carried in a message as: + + + + + + + + + + ISI.EDU. + + + + + MX + + + + + 10 VENERA.ISI.EDU. + + + + + + + + + + MX + + + + + 10 VAXA.ISI.EDU + + + + + + + VENERA.ISI.EDU + + + + + A + + + + + 128.9.0.32 + + + + + + + + + + A + + + + + 10.1.0.52 + + + + + + + VAXA.ISI.EDU + + + + + A + + + + + 10.2.0.27 + + + + + + + + + + A + + + + + 128.9.0.33 + + + + + + + + The MX RRs have an RDATA section which consists of a 16 bit + number followed by a domain name. The address RRs use a + standard + IP address format to contain a 32 bit internet address. + + + This example shows six RRs, with two RRs at each of three + domain names. + + + Similarly we might see: + + + + + + + + + + XX.LCS.MIT.EDU. IN + + + + + A + + + + + 10.0.0.44 + + + + + + + CH + + + + + A + + + + + MIT.EDU. 2420 + + + + + + + + This example shows two addresses for XX.LCS.MIT.EDU, + each of a different class. + + + + + + Discussion of MX Records + + + As described above, domain servers store information as a + series of resource records, each of which contains a particular + piece of information about a given domain name (which is usually, + but not always, a host). The simplest way to think of a RR is as + a typed pair of data, a domain name matched with a relevant datum, + and stored with some additional type information to help systems + determine when the RR is relevant. + + + + MX records are used to control delivery of email. The data + specified in the record is a priority and a domain name. The + priority + controls the order in which email delivery is attempted, with the + lowest number first. If two priorities are the same, a server is + chosen randomly. If no servers at a given priority are responding, + the mail transport agent will fall back to the next largest + priority. + Priority numbers do not have any absolute meaning — they are + relevant + only respective to other MX records for that domain name. The + domain + name given is the machine to which the mail will be delivered. It must have + an associated A record — CNAME is not sufficient. + + + For a given domain, if there is both a CNAME record and an + MX record, the MX record is in error, and will be ignored. + Instead, + the mail will be delivered to the server specified in the MX + record + pointed to by the CNAME. + + + + + + + + + + + + + example.com. + + + + + IN + + + + + MX + + + + + 10 + + + + + mail.example.com. + + + + + + + + + + IN + + + + + MX + + + + + 10 + + + + + mail2.example.com. + + + + + + + + + + IN + + + + + MX + + + + + 20 + + + + + mail.backup.org. + + + + + + + mail.example.com. + + + + + IN + + + + + A + + + + + 10.0.0.1 + + + + + + + + + + mail2.example.com. + + + + + IN + + + + + A + + + + + 10.0.0.2 + + + + + + + + + + For example: + + + Mail delivery will be attempted to mail.example.com and + mail2.example.com (in + any order), and if neither of those succeed, delivery to mail.backup.org will + be attempted. + + + + Setting TTLs + + The time to live of the RR field is a 32 bit integer represented + in units of seconds, and is primarily used by resolvers when they + cache RRs. The TTL describes how long a RR can be cached before it + should be discarded. The following three types of TTL are + currently + used in a zone file. + + + + + + + + + + SOA + + + + + The last field in the SOA is the negative + caching TTL. This controls how long other servers will + cache no-such-domain + (NXDOMAIN) responses from you. + + + The maximum time for + negative caching is 3 hours (3h). + + + + + + + $TTL + + + + + The $TTL directive at the top of the + zone file (before the SOA) gives a default TTL for every + RR without + a specific TTL set. + + + + + + + RR TTLs + + + + + Each RR can have a TTL as the second + field in the RR, which will control how long other + servers can cache + the it. + + + + + + + + All of these TTLs default to units of seconds, though units + can be explicitly specified, for example, 1h30m. + + + + Inverse Mapping in IPv4 + + Reverse name resolution (that is, translation from IP address + to name) is achieved by means of the in-addr.arpa domain + and PTR records. Entries in the in-addr.arpa domain are made in + least-to-most significant order, read left to right. This is the + opposite order to the way IP addresses are usually written. Thus, + a machine with an IP address of 10.1.2.3 would have a + corresponding + in-addr.arpa name of + 3.2.1.10.in-addr.arpa. This name should have a PTR resource record + whose data field is the name of the machine or, optionally, + multiple + PTR records if the machine has more than one name. For example, + in the example.com domain: + + + + + + + + + + $ORIGIN + + + + + 2.1.10.in-addr.arpa + + + + + + + 3 + + + + + IN PTR foo.example.com. + + + + + + + + + The $ORIGIN lines in the examples + are for providing context to the examples only-they do not + necessarily + appear in the actual usage. They are only used here to indicate + that the example is relative to the listed origin. + + + + + Other Zone File Directives + + The Master File Format was initially defined in RFC 1035 and + has subsequently been extended. While the Master File Format + itself + is class independent all records in a Master File must be of the + same + class. + + + Master File Directives include $ORIGIN, $INCLUDE, + and $TTL. + + + The <command>$ORIGIN</command> Directive + + Syntax: $ORIGIN + domain-name + comment + + $ORIGIN + sets the domain name that will be appended to any + unqualified records. When a zone is first read in there + is an implicit $ORIGIN + <zone-name>. + The current $ORIGIN is appended to + the domain specified in the $ORIGIN + argument if it is not absolute. + + + +$ORIGIN example.com. +WWW CNAME MAIN-SERVER + + + + is equivalent to + + + +WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. + + + + + The <command>$INCLUDE</command> Directive + + Syntax: $INCLUDE + filename + +origin + comment + + + Read and process the file filename as + if it were included into the file at this point. If origin is + specified the file is processed with $ORIGIN set + to that value, otherwise the current $ORIGIN is + used. + + + The origin and the current domain name + revert to the values they had prior to the $INCLUDE once + the file has been read. + + + + RFC 1035 specifies that the current origin should be restored + after + an $INCLUDE, but it is silent + on whether the current + domain name should also be restored. BIND 9 restores both of + them. + This could be construed as a deviation from RFC 1035, a + feature, or both. + + + + + The <command>$TTL</command> Directive + + Syntax: $TTL + default-ttl + +comment + + + Set the default Time To Live (TTL) for subsequent records + with undefined TTLs. Valid TTLs are of the range 0-2147483647 + seconds. + + $TTL + is defined in RFC 2308. + + + + + <acronym>BIND</acronym> Master File Extension: the <command>$GENERATE</command> Directive + + Syntax: $GENERATE + range + lhs + ttl + class + type + rhs + comment + + $GENERATE + is used to create a series of resource records that only + differ from each other by an + iterator. $GENERATE can be used to + easily generate the sets of records required to support + sub /24 reverse delegations described in RFC 2317: + Classless IN-ADDR.ARPA delegation. + + +$ORIGIN 0.0.192.IN-ADDR.ARPA. $GENERATE 1-2 0 NS SERVER$.EXAMPLE. -$GENERATE 1-127 $ CNAME $.0 -is equivalent to -0.0.0.192.IN-ADDR.ARPA NS SERVER1.EXAMPLE. +$GENERATE 1-127 $ CNAME $.0 + + + is equivalent to + + +0.0.0.192.IN-ADDR.ARPA NS SERVER1.EXAMPLE. 0.0.0.192.IN-ADDR.ARPA. NS SERVER2.EXAMPLE. 1.0.0.192.IN-ADDR.ARPA. CNAME 1.0.0.0.192.IN-ADDR.ARPA. 2.0.0.192.IN-ADDR.ARPA. CNAME 2.0.0.0.192.IN-ADDR.ARPA. ... 127.0.0.192.IN-ADDR.ARPA. CNAME 127.0.0.0.192.IN-ADDR.ARPA. - - - - - - - - range - This can be one of two forms: start-stop -or start-stop/step. If the first form is used then step is set to - 1. All of start, stop and step must be positive. - - - lhs - lhs describes the -owner name of the resource records to be created. Any single $ symbols -within the lhs side are replaced by the iterator -value. -To get a $ in the output you need to escape the $ -using a backslash \, -e.g. \$. The $ may optionally be followed -by modifiers which change the offset from the iterator, field width and base. -Modifiers are introduced by a { immediately following the -$ as ${offset[,width[,base]]}. -e.g. ${-20,3,d} which subtracts 20 from the current value, -prints the result as a decimal in a zero padded field of with 3. Available -output forms are decimal (d), octal (o) -and hexadecimal (x or X for uppercase). -The default modifier is ${0,0,d}. -If the lhs is not -absolute, the current $ORIGIN is appended to -the name. -For compatibility with earlier versions $$ is still -recognized a indicating a literal $ in the output. - - - ttl - ttl specifies the - ttl of the generated records. If not specified this will be - inherited using the normal ttl inheritance rules. - class and ttl can be - entered in either order. - - - class - class specifies the - class of the generated records. This must match the zone class if - it is specified. - class and ttl can be - entered in either order. - - - type - At present the only supported types are -PTR, CNAME, DNAME, A, AAAA and NS. - - - rhs - rhs is a domain name. It is processed -similarly to lhs. - - - - The $GENERATE directive is a BIND extension -and not part of the standard zone file format. - BIND 8 does not support the optional TTL and CLASS fields. - - - -<acronym>BIND</acronym> 9 Security Considerations -Access Control Lists -Access Control Lists (ACLs), are address match lists that -you can set up and nickname for future use in allow-notify, -allow-query, allow-recursion, -blackhole, allow-transfer, -etc. -Using ACLs allows you to have finer control over who can access -your name server, without cluttering up your config files with huge -lists of IP addresses. -It is a good idea to use ACLs, and to -control access to your server. Limiting access to your server by -outside parties can help prevent spoofing and DoS attacks against -your server. -Here is an example of how to properly apply ACLs: + + + + + + + + + + range + + + + This can be one of two forms: start-stop + or start-stop/step. If the first form is used then step + is set to + 1. All of start, stop and step must be positive. + + + + + + lhs + + + lhs + describes the owner name of the resource records + to be created. Any single $ + symbols within the lhs side + are replaced by the iterator value. + + To get a $ in the output you need to escape the + $ using a backslash + \, + e.g. \$. The + $ may optionally be followed + by modifiers which change the offset from the + iterator, field width and base. + + Modifiers are introduced by a + { immediately following the + $ as + ${offset[,width[,base]]}. + e.g. ${-20,3,d} which + subtracts 20 from the current value, prints the + result as a decimal in a zero padded field of + with 3. + + Available output forms are decimal + (d), octal + (o) and hexadecimal + (x or X + for uppercase). The default modifier is + ${0,0,d}. If the + lhs is not absolute, the + current $ORIGIN is appended + to the name. + + + For compatibility with earlier versions $$ is still + recognized a indicating a literal $ in the output. + + + + + + ttl + + + ttl + specifies the ttl of the generated records. If + not specified this will be inherited using the + normal ttl inheritance rules. + + class + and ttl can be + entered in either order. + + + + + + class + + + class + specifies the class of the generated records. + This must match the zone class if it is + specified. + + class + and ttl can be + entered in either order. + + + + + + type + + + + At present the only supported types are + PTR, CNAME, DNAME, A, AAAA and NS. + + + + + + rhs + + + + rhs is a domain name. It is processed + similarly to lhs. + + + + + + + + The $GENERATE directive is a BIND extension + and not part of the standard zone file format. + + + BIND 8 does not support the optional TTL and CLASS fields. + + + + + + <acronym>BIND</acronym> 9 Security Considerations + + Access Control Lists + + Access Control Lists (ACLs), are address match lists that + you can set up and nickname for future use in allow-notify, + allow-query, allow-recursion, + blackhole, allow-transfer, + etc. + + + Using ACLs allows you to have finer control over who can access + your name server, without cluttering up your config files with huge + lists of IP addresses. + + + It is a good idea to use ACLs, and to + control access to your server. Limiting access to your server by + outside parties can help prevent spoofing and DoS attacks against + your server. + + + Here is an example of how to properly apply ACLs: + + // Set up an ACL named "bogusnets" that will block RFC1918 space, // which is commonly used in spoofing attacks. @@ -5870,916 +9813,1223 @@ zone "example.com" { allow-query { any; }; }; -This allows recursive queries of the server from the outside -unless recursion has been previously disabled. -For more information on how to use ACLs to protect your server, -see the AUSCERT advisory at -ftp://ftp.auscert.org.au/pub/auscert/advisory/AL-1999.004.dns_dos -<command>chroot</command> and <command>setuid</command> (for -UNIX servers) -On UNIX servers, it is possible to run BIND in a chrooted environment -(chroot()) by specifying the "" -option. This can help improve system security by placing BIND in -a "sandbox", which will limit the damage done if a server is compromised. -Another useful feature in the UNIX version of BIND is the -ability to run the daemon as an unprivileged user ( user ). -We suggest running as an unprivileged user when using the chroot feature. -Here is an example command line to load BIND in a chroot() sandbox, -/var/named, and to run named setuid to -user 202: -/usr/local/bin/named -u 202 -t /var/named - -The <command>chroot</command> Environment - -In order for a chroot() environment to -work properly in a particular directory -(for example, /var/named), -you will need to set up an environment that includes everything -BIND needs to run. -From BIND's point of view, /var/named is -the root of the filesystem. You will need to adjust the values of options like -like directory and pid-file to account -for this. - - -Unlike with earlier versions of BIND, you will typically -not need to compile named -statically nor install shared libraries under the new root. -However, depending on your operating system, you may need -to set up things like -/dev/zero, -/dev/random, -/dev/log, and/or -/etc/localtime. - - - -Using the <command>setuid</command> Function - -Prior to running the named daemon, use -the touch utility (to change file access and -modification times) or the chown utility (to -set the user id and/or group id) on files -to which you want BIND -to write. Note that if the named daemon is running as an -unprivileged user, it will not be able to bind to new restricted ports if the -server is reloaded. - - - -Dynamic Update Security - -Access to the dynamic -update facility should be strictly limited. In earlier versions of -BIND the only way to do this was based on the IP -address of the host requesting the update, by listing an IP address or -network prefix in the allow-update zone option. -This method is insecure since the source address of the update UDP packet -is easily forged. Also note that if the IP addresses allowed by the -allow-update option include the address of a slave -server which performs forwarding of dynamic updates, the master can be -trivially attacked by sending the update to the slave, which will -forward it to the master with its own source IP address causing the -master to approve it without question. - -For these reasons, we strongly recommend that updates be -cryptographically authenticated by means of transaction signatures -(TSIG). That is, the allow-update option should -list only TSIG key names, not IP addresses or network -prefixes. Alternatively, the new update-policy -option can be used. - -Some sites choose to keep all dynamically updated DNS data -in a subdomain and delegate that subdomain to a separate zone. This -way, the top-level zone containing critical data such as the IP addresses -of public web and mail servers need not allow dynamic update at -all. - - - - - Troubleshooting - - Common Problems - - It's not working; how can I figure out what's wrong? - - The best solution to solving installation and - configuration issues is to take preventative measures by setting - up logging files beforehand. The log files provide a - source of hints and information that can be used to figure out - what went wrong and how to fix the problem. - - - - - Incrementing and Changing the Serial Number - - Zone serial numbers are just numbers-they aren't date - related. A lot of people set them to a number that represents a - date, usually of the form YYYYMMDDRR. A number of people have been - testing these numbers for Y2K compliance and have set the number - to the year 2000 to see if it will work. They then try to restore - the old serial number. This will cause problems because serial - numbers are used to indicate that a zone has been updated. If the - serial number on the slave server is lower than the serial number - on the master, the slave server will attempt to update its copy of - the zone. - - Setting the serial number to a lower number on the master - server than the slave server means that the slave will not perform - updates to its copy of the zone. - - The solution to this is to add 2147483647 (2^31-1) to the - number, reload the zone and make sure all slaves have updated to - the new zone serial number, then reset the number to what you want - it to be, and reload the zone again. - - - - Where Can I Get Help? - - The Internet Software Consortium (ISC) offers a wide range - of support and service agreements for BIND and DHCP servers. Four - levels of premium support are available and each level includes - support for all ISC programs, significant discounts on products - and training, and a recognized priority on bug fixes and - non-funded feature requests. In addition, ISC offers a standard - support agreement package which includes services ranging from bug - fix announcements to remote support. It also includes training in - BIND and DHCP. - - To discuss arrangements for support, contact - info@isc.org or visit the - ISC web page at http://www.isc.org/services/support/ - to read more. - - - - Appendices - - Acknowledgments - - A Brief History of the <acronym>DNS</acronym> and <acronym>BIND</acronym> - - Although the "official" beginning of the Domain Name - System occurred in 1984 with the publication of RFC 920, the - core of the new system was described in 1983 in RFCs 882 and - 883. From 1984 to 1987, the ARPAnet (the precursor to today's - Internet) became a testbed of experimentation for developing the - new naming/addressing scheme in an rapidly expanding, - operational network environment. New RFCs were written and - published in 1987 that modified the original documents to - incorporate improvements based on the working model. RFC 1034, - "Domain Names-Concepts and Facilities", and RFC 1035, "Domain - Names-Implementation and Specification" were published and - became the standards upon which all DNS implementations are - built. - - - The first working domain name server, called "Jeeves", was -written in 1983-84 by Paul Mockapetris for operation on DEC Tops-20 -machines located at the University of Southern California's Information -Sciences Institute (USC-ISI) and SRI International's Network Information -Center (SRI-NIC). A DNS server for Unix machines, the Berkeley Internet -Name Domain (BIND) package, was written soon after by a group of -graduate students at the University of California at Berkeley under -a grant from the US Defense Advanced Research Projects Administration -(DARPA). Versions of BIND through 4.8.3 were maintained by the Computer -Systems Research Group (CSRG) at UC Berkeley. Douglas Terry, Mark -Painter, David Riggle and Songnian Zhou made up the initial BIND -project team. After that, additional work on the software package -was done by Ralph Campbell. Kevin Dunlap, a Digital Equipment Corporation -employee on loan to the CSRG, worked on BIND for 2 years, from 1985 -to 1987. Many other people also contributed to BIND development -during that time: Doug Kingston, Craig Partridge, Smoot Carl-Mitchell, -Mike Muuss, Jim Bloom and Mike Schwartz. BIND maintenance was subsequently -handled by Mike Karels and O. Kure. - BIND versions 4.9 and 4.9.1 were released by Digital Equipment -Corporation (now Compaq Computer Corporation). Paul Vixie, then -a DEC employee, became BIND's primary caretaker. Paul was assisted -by Phil Almquist, Robert Elz, Alan Barrett, Paul Albitz, Bryan Beecher, Andrew -Partan, Andy Cherenson, Tom Limoncelli, Berthold Paffrath, Fuat -Baran, Anant Kumar, Art Harkin, Win Treese, Don Lewis, Christophe -Wolfhugel, and others. - BIND Version 4.9.2 was sponsored by Vixie Enterprises. Paul -Vixie became BIND's principal architect/programmer. - BIND versions from 4.9.3 onward have been developed and maintained -by the Internet Software Consortium with support being provided -by ISC's sponsors. As co-architects/programmers, Bob Halley and -Paul Vixie released the first production-ready version of BIND version -8 in May 1997. - BIND development work is made possible today by the sponsorship -of several corporations, and by the tireless work efforts of numerous -individuals. - - - - -General <acronym>DNS</acronym> Reference Information - - IPv6 addresses (AAAA) - IPv6 addresses are 128-bit identifiers for interfaces and -sets of interfaces which were introduced in the DNS to facilitate -scalable Internet routing. There are three types of addresses: Unicast, -an identifier for a single interface; Anycast, -an identifier for a set of interfaces; and Multicast, -an identifier for a set of interfaces. Here we describe the global -Unicast address scheme. For more information, see RFC 2374. -The aggregatable global Unicast address format is as follows: - - - - - - - - - -3 -13 -8 -24 -16 -64 bits - - -FP -TLA ID -RES -NLA ID -SLA ID -Interface ID - - -<------ Public Topology -------> - - - - - - - - -<-Site Topology-> - - - - - - - - -<------ Interface Identifier ------> - - - - Where - - - - - - -FP -= -Format Prefix (001) - - -TLA ID -= -Top-Level Aggregation Identifier - - -RES -= -Reserved for future use - - -NLA ID -= -Next-Level Aggregation Identifier - - -SLA ID -= -Site-Level Aggregation Identifier - - -INTERFACE ID -= -Interface Identifier - - - - The Public Topology is provided by the -upstream provider or ISP, and (roughly) corresponds to the IPv4 network section -of the address range. The Site Topology is -where you can subnet this space, much the same as subnetting an -IPv4 /16 network into /24 subnets. The Interface Identifier is -the address of an individual interface on a given network. (With -IPv6, addresses belong to interfaces rather than machines.) - The subnetting capability of IPv6 is much more flexible than -that of IPv4: subnetting can now be carried out on bit boundaries, -in much the same way as Classless InterDomain Routing (CIDR). -The Interface Identifier must be unique on that network. On -ethernet networks, one way to ensure this is to set the address -to the first three bytes of the hardware address, "FFFE", then the -last three bytes of the hardware address. The lowest significant -bit of the first byte should then be complemented. Addresses are -written as 32-bit blocks separated with a colon, and leading zeros -of a block may be omitted, for example: -2001:db8:201:9:a00:20ff:fe81:2b32 -IPv6 address specifications are likely to contain long strings -of zeros, so the architects have included a shorthand for specifying -them. The double colon (`::') indicates the longest possible string -of zeros that can fit, and can be used only once in an address. - - - - Bibliography (and Suggested Reading) - - Request for Comments (RFCs) - Specification documents for the Internet protocol suite, including -the DNS, are published as part of the Request for Comments (RFCs) -series of technical notes. The standards themselves are defined -by the Internet Engineering Task Force (IETF) and the Internet Engineering -Steering Group (IESG). RFCs can be obtained online via FTP at -ftp://www.isi.edu/in-notes/RFCxxx.txt (where xxx is -the number of the RFC). RFCs are also available via the Web at -http://www.ietf.org/rfc/. - - - - - Standards - - RFC974 - - Partridge - C. - - Mail Routing and the Domain System - January 1986 - - - RFC1034 - - Mockapetris - P.V. - - Domain Names — Concepts and Facilities - November 1987 - - - RFC1035 - - Mockapetris - P. V. - Domain Names — Implementation and -Specification - November 1987 - - - - - Proposed Standards - - - RFC2181 - - Elz - R., R. Bush - - Clarifications to the <acronym>DNS</acronym> Specification - July 1997 - - - RFC2308 - - Andrews - M. - - Negative Caching of <acronym>DNS</acronym> Queries - March 1998 - - - RFC1995 - - Ohta - M. - - Incremental Zone Transfer in <acronym>DNS</acronym> - August 1996 - - - RFC1996 - - Vixie - P. - - A Mechanism for Prompt Notification of Zone Changes - August 1996 - - - RFC2136 - - - Vixie - P. - - - S. - Thomson - - - Y. - Rekhter - - - J. - Bound - - - Dynamic Updates in the Domain Name System - April 1997 - - - RFC2845 - - - Vixie - P. - - - O. - Gudmundsson - - - D. - Eastlake - 3rd - - B. - Wellington - - Secret Key Transaction Authentication for <acronym>DNS</acronym> (TSIG) - May 2000 - - - - Proposed Standards Still Under Development - - Note: the following list of -RFCs are undergoing major revision by the IETF. - - - RFC1886 - - - Thomson - S. - - - C. - Huitema - - - <acronym>DNS</acronym> Extensions to support IP version 6 - December 1995 - - - RFC2065 - - - Eastlake - 3rd - D. - - - C. - Kaufman - - - Domain Name System Security Extensions - January 1997 - - - RFC2137 - - Eastlake - 3rd - D. - - Secure Domain Name System Dynamic Update - April 1997 - - - - Other Important RFCs About <acronym>DNS</acronym> Implementation - - RFC1535 - - Gavron - E. - - A Security Problem and Proposed Correction With Widely Deployed <acronym>DNS</acronym> Software. - October 1993 - - - RFC1536 - - - Kumar - A. - - - J. - Postel - - - C. - Neuman - - P. - Danzig - - - S. - Miller - - - Common <acronym>DNS</acronym> Implementation Errors and Suggested Fixes - October 1993 - - - RFC1982 - - - Elz - R. - - - R. - Bush - - - Serial Number Arithmetic - August 1996 - - - - Resource Record Types - - RFC1183 - - - Everhart - C.F. - - - L. A. - Mamakos - - - R. - Ullmann - - - P. - Mockapetris - - - New <acronym>DNS</acronym> RR Definitions - October 1990 - - - RFC1706 - - - Manning - B. - - - R. - Colella - - - <acronym>DNS</acronym> NSAP Resource Records - October 1994 - - - RFC2168 - - - Daniel - R. - - - M. - Mealling - - - Resolution of Uniform Resource Identifiers using -the Domain Name System - June 1997 - - - RFC1876 - - - Davis - C. - - - P. - Vixie - - - T. - Goodwin - - - I. - Dickinson - - - A Means for Expressing Location Information in the Domain -Name System - January 1996 - - - RFC2052 - - - Gulbrandsen - A. - - - P. - Vixie - - - A <acronym>DNS</acronym> RR for Specifying the Location of -Services. - October 1996 - - - RFC2163 - - Allocchio - A. - - Using the Internet <acronym>DNS</acronym> to Distribute MIXER -Conformant Global Address Mapping - January 1998 - - - RFC2230 - - Atkinson - R. - - Key Exchange Delegation Record for the <acronym>DNS</acronym> - October 1997 - - - - <acronym>DNS</acronym> and the Internet - - RFC1101 - - Mockapetris - P. V. - - <acronym>DNS</acronym> Encoding of Network Names and Other Types - April 1989 - - - RFC1123 - - Braden - R. - - Requirements for Internet Hosts - Application and Support - October 1989 - - - RFC1591 - - Postel - J. - Domain Name System Structure and Delegation - March 1994 - - RFC2317 - - - Eidnes - H. - - - G. - de Groot - - - P. - Vixie - - - Classless IN-ADDR.ARPA Delegation - March 1998 - - - - <acronym>DNS</acronym> Operations - - RFC1537 - - Beertema - P. - - Common <acronym>DNS</acronym> Data File Configuration Errors - October 1993 - - - RFC1912 - - Barr - D. - - Common <acronym>DNS</acronym> Operational and Configuration Errors - February 1996 - - - RFC2010 - - - Manning - B. - - - P. - Vixie - - - Operational Criteria for Root Name Servers. - October 1996 - - - RFC2219 - - - Hamilton - M. - - - R. - Wright - - - Use of <acronym>DNS</acronym> Aliases for Network Services. - October 1997 - - - - Other <acronym>DNS</acronym>-related RFCs - - Note: the following list of RFCs, although -DNS-related, are not concerned with implementing software. - - - RFC1464 - - Rosenbaum - R. - - Using the Domain Name System To Store Arbitrary String Attributes - May 1993 - - - RFC1713 - - Romao - A. - - Tools for <acronym>DNS</acronym> Debugging - November 1994 - - RFC1794 - - Brisco - T. - - <acronym>DNS</acronym> Support for Load Balancing - April 1995 - - - RFC2240 - - Vaughan - O. - A Legal Basis for Domain Name Allocation - November 1997 - - - RFC2345 - - - Klensin - J. - - - T. - Wolf - - - G. - Oglesby - - - Domain Names and Company Name Retrieval - May 1998 - - - RFC2352 - - Vaughan - O. - - A Convention For Using Legal Names as Domain Names - May 1998 - - - - Obsolete and Unimplemented Experimental RRs - - RFC1712 - - - Farrell - C. - - - M. - Schulze - - - S. - Pleitner - - - D. - Baldoni - - - <acronym>DNS</acronym> Encoding of Geographical -Location - November 1994 - - - - - - Internet Drafts - Internet Drafts (IDs) are rough-draft working documents of -the Internet Engineering Task Force. They are, in essence, RFCs -in the preliminary stages of development. Implementors are cautioned not -to regard IDs as archival, and they should not be quoted or cited -in any formal documents unless accompanied by the disclaimer that -they are "works in progress." IDs have a lifespan of six months -after which they are deleted unless updated by their authors. - - - - Other Documents About <acronym>BIND</acronym> - - - - - - Albitz - Paul - - - Cricket - Liu - - - <acronym>DNS</acronym> and <acronym>BIND</acronym> - - 1998 - Sebastopol, CA: O'Reilly and Associates - - - - - - - - - + + + This allows recursive queries of the server from the outside + unless recursion has been previously disabled. + + + For more information on how to use ACLs to protect your server, + see the AUSCERT advisory at + + ftp://ftp.auscert.org.au/pub/auscert/advisory/AL-1999.004.dns_dos + + + + + <command>chroot</command> and <command>setuid</command> (for + UNIX servers) + + On UNIX servers, it is possible to run BIND in a chrooted environment + (chroot()) by specifying the "" + option. This can help improve system security by placing BIND in + a "sandbox", which will limit the damage done if a server is + compromised. + + + Another useful feature in the UNIX version of BIND is the + ability to run the daemon as an unprivileged user ( user ). + We suggest running as an unprivileged user when using the chroot feature. + + + Here is an example command line to load BIND in a chroot() sandbox, + /var/named, and to run named setuid to + user 202: + + + /usr/local/bin/named -u 202 -t /var/named + + + + The <command>chroot</command> Environment + + + In order for a chroot() environment + to + work properly in a particular directory + (for example, /var/named), + you will need to set up an environment that includes everything + BIND needs to run. + From BIND's point of view, /var/named is + the root of the filesystem. You will need to adjust the values of + options like + like directory and pid-file to account + for this. + + + Unlike with earlier versions of BIND, you will typically + not need to compile named + statically nor install shared libraries under the new root. + However, depending on your operating system, you may need + to set up things like + /dev/zero, + /dev/random, + /dev/log, and/or + /etc/localtime. + + + + + Using the <command>setuid</command> Function + + + Prior to running the named daemon, + use + the touch utility (to change file + access and + modification times) or the chown + utility (to + set the user id and/or group id) on files + to which you want BIND + to write. Note that if the named + daemon is running as an + unprivileged user, it will not be able to bind to new restricted + ports if the + server is reloaded. + + + + + + Dynamic Update Security + + + Access to the dynamic + update facility should be strictly limited. In earlier versions of + BIND the only way to do this was + based on the IP + address of the host requesting the update, by listing an IP address + or + network prefix in the allow-update + zone option. + This method is insecure since the source address of the update UDP + packet + is easily forged. Also note that if the IP addresses allowed by the + allow-update option include the + address of a slave + server which performs forwarding of dynamic updates, the master can + be + trivially attacked by sending the update to the slave, which will + forward it to the master with its own source IP address causing the + master to approve it without question. + + + + For these reasons, we strongly recommend that updates be + cryptographically authenticated by means of transaction signatures + (TSIG). That is, the allow-update + option should + list only TSIG key names, not IP addresses or network + prefixes. Alternatively, the new update-policy + option can be used. + + + + Some sites choose to keep all dynamically updated DNS data + in a subdomain and delegate that subdomain to a separate zone. This + way, the top-level zone containing critical data such as the IP + addresses + of public web and mail servers need not allow dynamic update at + all. + + + + + + + Troubleshooting + + Common Problems + + It's not working; how can I figure out what's wrong? + + + The best solution to solving installation and + configuration issues is to take preventative measures by setting + up logging files beforehand. The log files provide a + source of hints and information that can be used to figure out + what went wrong and how to fix the problem. + + + + + + Incrementing and Changing the Serial Number + + + Zone serial numbers are just numbers-they aren't date + related. A lot of people set them to a number that represents a + date, usually of the form YYYYMMDDRR. A number of people have been + testing these numbers for Y2K compliance and have set the number + to the year 2000 to see if it will work. They then try to restore + the old serial number. This will cause problems because serial + numbers are used to indicate that a zone has been updated. If the + serial number on the slave server is lower than the serial number + on the master, the slave server will attempt to update its copy of + the zone. + + + + Setting the serial number to a lower number on the master + server than the slave server means that the slave will not perform + updates to its copy of the zone. + + + + The solution to this is to add 2147483647 (2^31-1) to the + number, reload the zone and make sure all slaves have updated to + the new zone serial number, then reset the number to what you want + it to be, and reload the zone again. + + + + + Where Can I Get Help? + + + The Internet Software Consortium + (ISC) offers a wide range + of support and service agreements for BIND and DHCP servers. Four + levels of premium support are available and each level includes + support for all ISC programs, + significant discounts on products + and training, and a recognized priority on bug fixes and + non-funded feature requests. In addition, ISC offers a standard + support agreement package which includes services ranging from bug + fix announcements to remote support. It also includes training in + BIND and DHCP. + + + + To discuss arrangements for support, contact + info@isc.org or visit the + ISC web page at + http://www.isc.org/services/support/ + + to read more. + + + + + Appendices + + Acknowledgments + + A Brief History of the <acronym>DNS</acronym> and <acronym>BIND</acronym> + + + Although the "official" beginning of the Domain Name + System occurred in 1984 with the publication of RFC 920, the + core of the new system was described in 1983 in RFCs 882 and + 883. From 1984 to 1987, the ARPAnet (the precursor to today's + Internet) became a testbed of experimentation for developing the + new naming/addressing scheme in an rapidly expanding, + operational network environment. New RFCs were written and + published in 1987 that modified the original documents to + incorporate improvements based on the working model. RFC 1034, + "Domain Names-Concepts and Facilities", and RFC 1035, "Domain + Names-Implementation and Specification" were published and + became the standards upon which all DNS implementations are + built. + + + + The first working domain name server, called "Jeeves", was + written in 1983-84 by Paul Mockapetris for operation on DEC + Tops-20 + machines located at the University of Southern California's + Information + Sciences Institute (USC-ISI) and SRI International's Network + Information + Center (SRI-NIC). A DNS server for + Unix machines, the Berkeley Internet + Name Domain (BIND) package, was + written soon after by a group of + graduate students at the University of California at Berkeley + under + a grant from the US Defense Advanced Research Projects + Administration + (DARPA). Versions of BIND through + 4.8.3 were maintained by the Computer + Systems Research Group (CSRG) at UC Berkeley. Douglas Terry, Mark + Painter, David Riggle and Songnian Zhou made up the initial BIND + project team. After that, additional work on the software package + was done by Ralph Campbell. Kevin Dunlap, a Digital Equipment + Corporation + employee on loan to the CSRG, worked on BIND for 2 years, from 1985 + to 1987. Many other people also contributed to BIND development + during that time: Doug Kingston, Craig Partridge, Smoot + Carl-Mitchell, + Mike Muuss, Jim Bloom and Mike Schwartz. BIND maintenance was subsequently + handled by Mike Karels and O. Kure. + + + BIND versions 4.9 and 4.9.1 were + released by Digital Equipment + Corporation (now Compaq Computer Corporation). Paul Vixie, then + a DEC employee, became BIND's + primary caretaker. Paul was assisted + by Phil Almquist, Robert Elz, Alan Barrett, Paul Albitz, Bryan + Beecher, Andrew + Partan, Andy Cherenson, Tom Limoncelli, Berthold Paffrath, Fuat + Baran, Anant Kumar, Art Harkin, Win Treese, Don Lewis, Christophe + Wolfhugel, and others. + + + BIND Version 4.9.2 was sponsored by + Vixie Enterprises. Paul + Vixie became BIND's principal + architect/programmer. + + + BIND versions from 4.9.3 onward + have been developed and maintained + by the Internet Software Consortium with support being provided + by ISC's sponsors. As co-architects/programmers, Bob Halley and + Paul Vixie released the first production-ready version of BIND version + 8 in May 1997. + + + BIND development work is made + possible today by the sponsorship + of several corporations, and by the tireless work efforts of + numerous + individuals. + + + + + + General <acronym>DNS</acronym> Reference Information + + IPv6 addresses (AAAA) + + IPv6 addresses are 128-bit identifiers for interfaces and + sets of interfaces which were introduced in the DNS to facilitate + scalable Internet routing. There are three types of addresses: Unicast, + an identifier for a single interface; + Anycast, + an identifier for a set of interfaces; and Multicast, + an identifier for a set of interfaces. Here we describe the global + Unicast address scheme. For more information, see RFC 2374. + + + The aggregatable global Unicast address format is as follows: + + + + + + + + + + + + + + 3 + + + + + 13 + + + + + 8 + + + + + 24 + + + + + 16 + + + + + 64 bits + + + + + + + FP + + + + + TLA ID + + + + + RES + + + + + NLA ID + + + + + SLA ID + + + + + Interface ID + + + + + + + <------ Public Topology + ------> + + + + + + + + + + + + + + + + + + + + + + + + + <-Site Topology-> + + + + + + + + + + + + + + + + + + + + + + + + + <------ Interface Identifier ------> + + + + + + + + Where + + + + + + + + + + FP + + + + + = + + + + + Format Prefix (001) + + + + + + + TLA ID + + + + + = + + + + + Top-Level Aggregation Identifier + + + + + + + RES + + + + + = + + + + + Reserved for future use + + + + + + + NLA ID + + + + + = + + + + + Next-Level Aggregation Identifier + + + + + + + SLA ID + + + + + = + + + + + Site-Level Aggregation Identifier + + + + + + + INTERFACE ID + + + + + = + + + + + Interface Identifier + + + + + + + + + The Public Topology is provided by the + upstream provider or ISP, and (roughly) corresponds to the + IPv4 + network section + of the address range. The Site Topology is + where you can subnet this space, much the same as subnetting an + IPv4 /16 network into /24 subnets. + The Interface Identifier is + the address of an individual interface on a given network. (With + IPv6, addresses belong to interfaces rather than machines.) + + + The subnetting capability of IPv6 is much more flexible than + that of IPv4: subnetting can now be carried out on bit boundaries, + in much the same way as Classless InterDomain Routing (CIDR). + + + The Interface Identifier must be unique on that network. On + ethernet networks, one way to ensure this is to set the address + to the first three bytes of the hardware address, "FFFE", then the + last three bytes of the hardware address. The lowest significant + bit of the first byte should then be complemented. Addresses are + written as 32-bit blocks separated with a colon, and leading zeros + of a block may be omitted, for example: + + 2001:db8:201:9:a00:20ff:fe81:2b32 + + IPv6 address specifications are likely to contain long strings + of zeros, so the architects have included a shorthand for + specifying + them. The double colon (`::') indicates the longest possible + string + of zeros that can fit, and can be used only once in an address. + + + + + Bibliography (and Suggested Reading) + + Request for Comments (RFCs) + + Specification documents for the Internet protocol suite, including + the DNS, are published as part of + the Request for Comments (RFCs) + series of technical notes. The standards themselves are defined + by the Internet Engineering Task Force (IETF) and the Internet + Engineering Steering Group (IESG). RFCs can be obtained online via FTP at + + ftp://www.isi.edu/in-notes/RFCxxx.txt + + (where xxx is + the number of the RFC). RFCs are also available via the Web at + http://www.ietf.org/rfc/. + + + + + Standards + + RFC974 + + Partridge + C. + + Mail Routing and the Domain System + January 1986 + + + RFC1034 + + Mockapetris + P.V. + + Domain Names — Concepts and Facilities + November 1987 + + + RFC1035 + + Mockapetris + P. V. + Domain Names — Implementation and + Specification + November 1987 + + + + + Proposed Standards + + + RFC2181 + + Elz + R., R. Bush + + Clarifications to the <acronym>DNS</acronym> + Specification + July 1997 + + + RFC2308 + + Andrews + M. + + Negative Caching of <acronym>DNS</acronym> + Queries + March 1998 + + + RFC1995 + + Ohta + M. + + Incremental Zone Transfer in <acronym>DNS</acronym> + August 1996 + + + RFC1996 + + Vixie + P. + + A Mechanism for Prompt Notification of Zone Changes + August 1996 + + + RFC2136 + + + Vixie + P. + + + S. + Thomson + + + Y. + Rekhter + + + J. + Bound + + + Dynamic Updates in the Domain Name System + April 1997 + + + RFC2845 + + + Vixie + P. + + + O. + Gudmundsson + + + D. + Eastlake + 3rd + + + B. + Wellington + + + Secret Key Transaction Authentication for <acronym>DNS</acronym> (TSIG) + May 2000 + + + + Proposed Standards Still Under Development + + + Note: the following list of + RFCs are undergoing major revision by the IETF. + + + + RFC1886 + + + Thomson + S. + + + C. + Huitema + + + <acronym>DNS</acronym> Extensions to support IP + version 6 + December 1995 + + + RFC2065 + + + Eastlake + 3rd + D. + + + C. + Kaufman + + + Domain Name System Security Extensions + January 1997 + + + RFC2137 + + Eastlake + 3rd + D. + + Secure Domain Name System Dynamic Update + April 1997 + + + + Other Important RFCs About <acronym>DNS</acronym> + Implementation + + RFC1535 + + Gavron + E. + + A Security Problem and Proposed Correction With Widely + Deployed <acronym>DNS</acronym> Software. + October 1993 + + + RFC1536 + + + Kumar + A. + + + J. + Postel + + + C. + Neuman + + + P. + Danzig + + + S. + Miller + + + Common <acronym>DNS</acronym> Implementation + Errors and Suggested Fixes + October 1993 + + + RFC1982 + + + Elz + R. + + + R. + Bush + + + Serial Number Arithmetic + August 1996 + + + + Resource Record Types + + RFC1183 + + + Everhart + C.F. + + + L. A. + Mamakos + + + R. + Ullmann + + + P. + Mockapetris + + + New <acronym>DNS</acronym> RR Definitions + October 1990 + + + RFC1706 + + + Manning + B. + + + R. + Colella + + + <acronym>DNS</acronym> NSAP Resource Records + October 1994 + + + RFC2168 + + + Daniel + R. + + + M. + Mealling + + + Resolution of Uniform Resource Identifiers using + the Domain Name System + June 1997 + + + RFC1876 + + + Davis + C. + + + P. + Vixie + + + T. + Goodwin + + + I. + Dickinson + + + A Means for Expressing Location Information in the + Domain + Name System + January 1996 + + + RFC2052 + + + Gulbrandsen + A. + + + P. + Vixie + + + A <acronym>DNS</acronym> RR for Specifying the + Location of + Services. + October 1996 + + + RFC2163 + + Allocchio + A. + + Using the Internet <acronym>DNS</acronym> to + Distribute MIXER + Conformant Global Address Mapping + January 1998 + + + RFC2230 + + Atkinson + R. + + Key Exchange Delegation Record for the <acronym>DNS</acronym> + October 1997 + + + + <acronym>DNS</acronym> and the Internet + + RFC1101 + + Mockapetris + P. V. + + <acronym>DNS</acronym> Encoding of Network Names + and Other Types + April 1989 + + + RFC1123 + + Braden + R. + + Requirements for Internet Hosts - Application and + Support + October 1989 + + + RFC1591 + + Postel + J. + + Domain Name System Structure and Delegation + March 1994 + + + RFC2317 + + + Eidnes + H. + + + G. + de Groot + + + P. + Vixie + + + Classless IN-ADDR.ARPA Delegation + March 1998 + + + + <acronym>DNS</acronym> Operations + + RFC1537 + + Beertema + P. + + Common <acronym>DNS</acronym> Data File + Configuration Errors + October 1993 + + + RFC1912 + + Barr + D. + + Common <acronym>DNS</acronym> Operational and + Configuration Errors + February 1996 + + + RFC2010 + + + Manning + B. + + + P. + Vixie + + + Operational Criteria for Root Name Servers. + October 1996 + + + RFC2219 + + + Hamilton + M. + + + R. + Wright + + + Use of <acronym>DNS</acronym> Aliases for + Network Services. + October 1997 + + + + Other <acronym>DNS</acronym>-related RFCs + + + Note: the following list of RFCs, although + DNS-related, are not + concerned with implementing software. + + + + RFC1464 + + Rosenbaum + R. + + Using the Domain Name System To Store Arbitrary String + Attributes + May 1993 + + + RFC1713 + + Romao + A. + + Tools for <acronym>DNS</acronym> Debugging + November 1994 + + + RFC1794 + + Brisco + T. + + <acronym>DNS</acronym> Support for Load + Balancing + April 1995 + + + RFC2240 + + Vaughan + O. + + A Legal Basis for Domain Name Allocation + November 1997 + + + RFC2345 + + + Klensin + J. + + + T. + Wolf + + + G. + Oglesby + + + Domain Names and Company Name Retrieval + May 1998 + + + RFC2352 + + Vaughan + O. + + A Convention For Using Legal Names as Domain Names + May 1998 + + + + Obsolete and Unimplemented Experimental RRs + + RFC1712 + + + Farrell + C. + + + M. + Schulze + + + S. + Pleitner + + + D. + Baldoni + + + <acronym>DNS</acronym> Encoding of Geographical + Location + November 1994 + + + + + + Internet Drafts + + Internet Drafts (IDs) are rough-draft working documents of + the Internet Engineering Task Force. They are, in essence, RFCs + in the preliminary stages of development. Implementors are + cautioned not + to regard IDs as archival, and they should not be quoted or cited + in any formal documents unless accompanied by the disclaimer that + they are "works in progress." IDs have a lifespan of six months + after which they are deleted unless updated by their authors. + + + + Other Documents About <acronym>BIND</acronym> + + + + + + Albitz + Paul + + + Cricket + Liu + + + <acronym>DNS</acronym> and <acronym>BIND</acronym> + + 1998 + Sebastopol, CA: O'Reilly and Associates + + + + + + + + + diff --git a/doc/arm/Makefile.in b/doc/arm/Makefile.in index c516b089be45361b84e7df87a427492d430b7595..27f7c35e693386d80d2e7c3e7a1c3434d83f7949 100644 --- a/doc/arm/Makefile.in +++ b/doc/arm/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.12 2004/03/05 05:04:43 marka Exp $ +# $Id: Makefile.in,v 1.13 2005/05/11 05:55:34 sra Exp $ srcdir = @srcdir@ VPATH = @srcdir@ @@ -23,47 +23,41 @@ top_srcdir = @top_srcdir@ MANOBJS = Bv9ARM.html +PDFOBJS = Bv9ARM.pdf + distclean:: rm -f validate.sh rm -f nominum-docbook-html.dsl nominum-docbook-print.dsl rm -f HTML.index HTML.manifest -doc man:: ${MANOBJS} +doc man:: ${MANOBJS} ${PDFOBJS} -docclean manclean maintainer-clean:: - rm -f *.html +clean:: + rm -f Bv9ARM.aux Bv9ARM.brf Bv9ARM.glo Bv9ARM.idx + rm -f Bv9ARM.log Bv9ARM.out Bv9ARM.tex Bv9ARM.tex.tmp -Bv9ARM.html: Bv9ARM-book.xml nominum-docbook-html.dsl - ${OPENJADE} -v \ - -c ${SGMLCATALOG} \ - -t sgml \ - -d ./nominum-docbook-html.dsl \ - ${XMLDCL} ./Bv9ARM-book.xml - rm -f HTML.index HTML.manifest +docclean manclean maintainer-clean:: clean + rm -f *.html *.pdf -Bv9ARM-book.rtf: Bv9ARM-book.xml nominum-docbook-print.dsl - ${OPENJADE} -v \ - -c ${SGMLCATALOG} \ - -t rtf \ - -d ./nominum-docbook-print.dsl \ - ${XMLDCL} ./Bv9ARM-book.xml +Bv9ARM.html: Bv9ARM-book.xml + ${XSLTPROC} --stringparam root.filename Bv9ARM \ + ${top_srcdir}/doc/xsl/isc-docbook-chunk.xsl \ + Bv9ARM-book.xml -Bv9ARM-book.tex: Bv9ARM-book.xml nominum-docbook-print.dsl - ${OPENJADE} -v \ - -c ${SGMLCATALOG} \ - -d ./nominum-docbook-print.dsl \ - -t tex \ - ${XMLDCL} ./Bv9ARM-book.xml +Bv9ARM.tex: Bv9ARM-book.xml + ${XSLTPROC} ${top_srcdir}/doc/xsl/pre-latex.xsl Bv9ARM-book.xml | \ + ${XSLTPROC} ${top_srcdir}/doc/xsl/isc-docbook-latex.xsl - | \ + @PERL@ latex-fixup.pl >$@.tmp + if test -s $@.tmp; then mv $@.tmp $@; else rm -f $@.tmp; exit 1; fi -Bv9ARM-book.dvi: Bv9ARM-book.tex +Bv9ARM.dvi: Bv9ARM.tex rm -f Bv9ARM-book.aux Bv9ARM-book.dvi Bv9ARM-book.log - ${JADETEX} ./Bv9ARM-book.tex || true - ${JADETEX} ./Bv9ARM-book.tex || true - ${JADETEX} ./Bv9ARM-book.tex || true + ${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@ + ${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@ + ${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@ -Bv9ARM-book.pdf: Bv9ARM-book.tex +Bv9ARM.pdf: Bv9ARM.tex rm -f Bv9ARM-book.aux Bv9ARM-book.pdf Bv9ARM-book.log - ${PDFJADETEX} ./Bv9ARM-book.tex || true - ${PDFJADETEX} ./Bv9ARM-book.tex || true - ${PDFJADETEX} ./Bv9ARM-book.tex || true - + ${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@ + ${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@ + ${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@ diff --git a/doc/arm/isc.color.gif b/doc/arm/isc.color.gif deleted file mode 100644 index 09c327cca65df341b906418f0ff8c4314d6e0e6f..0000000000000000000000000000000000000000 Binary files a/doc/arm/isc.color.gif and /dev/null differ diff --git a/doc/arm/latex-fixup.pl b/doc/arm/latex-fixup.pl new file mode 100644 index 0000000000000000000000000000000000000000..9fc5401f875f50b58b7716bf21a82bde0fcb8d57 --- /dev/null +++ b/doc/arm/latex-fixup.pl @@ -0,0 +1,45 @@ +#!/usr/bin/perl -w +# +# Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC") +# +# 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. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +# AND FITNESS. IN NO EVENT SHALL ISC 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. + +# $Id: latex-fixup.pl,v 1.2 2005/05/11 05:55:33 sra Exp $ + +# Sadly, the final stages of generating a presentable PDF file always +# seem to require some manual tweaking. Doesn't seem to matter what +# typesetting tool one uses, sane forms of automation only go so far, +# at least with present technology. +# +# This script is intended to be a collection of tweaks. The theory is +# that, while we can't avoid the need for tweaking, we can at least +# write the silly things down in a form that a program might be able +# to execute. Undoubtedly everythig in here will break, eventually, +# at which point it will need to be updated, but since the alternative +# is to do the final editing by hand every time, this approach seems +# the lesser of two evils. + +while (<>) { + + # At the moment, the only tweak we have is fixup for a db2latex + # oops. LaTeX2e does not like having tables with duplicate names. + # Perhaps the dblatex project will fix this someday, but we can + # get by with just deleting the offending LaTeX commands for now. + + s/\\addtocounter\{table\}\{-1\}//g; + + # Add any further tweaking here. + + # Write out whatever we have now. + print; +} diff --git a/doc/arm/nominum-docbook-html.dsl.in b/doc/arm/nominum-docbook-html.dsl.in deleted file mode 100644 index 33fc938777a4db03f7c42e7c5ab95d95b8cb8d96..0000000000000000000000000000000000000000 --- a/doc/arm/nominum-docbook-html.dsl.in +++ /dev/null @@ -1,148 +0,0 @@ - -]> - - - - - - - -(define %html-prefix% - ;; Add the specified prefix to HTML output filenames - "Bv9ARM.") - -(define %use-id-as-filename% - ;; Use ID attributes as name for component HTML files? - #t) - -(define %root-filename% - ;; Name for the root HTML document - "Bv9ARM") - -(define %section-autolabel% - ;; REFENTRY section-autolabel - ;; PURP Are sections enumerated? - ;; DESC - ;; If true, unlabeled sections will be enumerated. - ;; /DESC - ;; AUTHOR N/A - ;; /REFENTRY - #t) - -(define %html-ext% - ;; REFENTRY html-ext - ;; PURP Default extension for HTML output files - ;; DESC - ;; The default extension for HTML output files. - ;; /DESC - ;; AUTHOR N/A - ;; /REFENTRY - ".html") - -(define nochunks - ;; REFENTRY nochunks - ;; PURP Suppress chunking of output pages - ;; DESC - ;; If true, the entire source document is formatted as a single HTML - ;; document and output on stdout. - ;; (This option can conveniently be set with '-V nochunks' on the - ;; Jade command line). - ;; /DESC - ;; AUTHOR N/A - ;; /REFENTRY - #f) - -(define rootchunk - ;; REFENTRY rootchunk - ;; PURP Make a chunk for the root element when nochunks is used - ;; DESC - ;; If true, a chunk will be created for the root element, even though - ;; nochunks is specified. This option has no effect if nochunks is not - ;; true. - ;; (This option can conveniently be set with '-V rootchunk' on the - ;; Jade command line). - ;; /DESC - ;; AUTHOR N/A - ;; /REFENTRY - #t) - -(define html-index - ;; REFENTRY html-index - ;; PURP HTML indexing? - ;; DESC - ;; Turns on HTML indexing. If true, then index data will be written - ;; to the file defined by 'html-index-filename'. This data can be - ;; collated and turned into a DocBook index with bin/collateindex.pl. - ;; /DESC - ;; AUTHOR N/A - ;; /REFENTRY - #t) - -(define html-manifest - ;; REFENTRY html-manifest - ;; PURP Write a manifest? - ;; DESC - ;; If not '#f' then the list of HTML files created by the stylesheet - ;; will be written to the file named by 'html-manifest-filename'. - ;; /DESC - ;; AUTHOR N/A - ;; /REFENTRY - #t) - -(define (chunk-element-list) - (list (normalize "preface") - (normalize "chapter") - (normalize "appendix") - (normalize "article") - (normalize "glossary") - (normalize "bibliography") - (normalize "index") - (normalize "colophon") - (normalize "setindex") - (normalize "reference") - (normalize "refentry") - (normalize "part") - (normalize "book") ;; just in case nothing else matches... - (normalize "set") ;; sets are definitely chunks... - )) - -; -; Add some cell padding to tables so that they don't look so cramped -; in Netscape. -; -; The following definition was cut-and-pasted from dbtable.dsl and the -; single line containing the word CELLPADDING was added. -; -(element tgroup - (let* ((wrapper (parent (current-node))) - (frameattr (attribute-string (normalize "frame") wrapper)) - (pgwide (attribute-string (normalize "pgwide") wrapper)) - (footnotes (select-elements (descendants (current-node)) - (normalize "footnote"))) - (border (if (equal? frameattr (normalize "none")) - '(("BORDER" "0")) - '(("BORDER" "1")))) - (width (if (equal? pgwide "1") - (list (list "WIDTH" ($table-width$))) - '())) - (head (select-elements (children (current-node)) (normalize "thead"))) - (body (select-elements (children (current-node)) (normalize "tbody"))) - (feet (select-elements (children (current-node)) (normalize "tfoot")))) - (make element gi: "TABLE" - attributes: (append - '(("CELLPADDING" "3")) - border - width - (if %cals-table-class% - (list (list "CLASS" %cals-table-class%)) - '())) - (process-node-list head) - (process-node-list body) - (process-node-list feet) - (make-table-endnotes)))) - - - - - diff --git a/doc/arm/nominum-docbook-print.dsl.in b/doc/arm/nominum-docbook-print.dsl.in deleted file mode 100644 index 511d6c48bc8c540c5845451b215968fcb4245299..0000000000000000000000000000000000000000 --- a/doc/arm/nominum-docbook-print.dsl.in +++ /dev/null @@ -1,42 +0,0 @@ - -]> - - - - - - - - -(define %generate-book-titlepage% #t) - -(define %section-autolabel% - ;; REFENTRY section-autolabel - ;; PURP Are sections enumerated? - ;; DESC - ;; If true, unlabeled sections will be enumerated. - ;; /DESC - ;; AUTHOR N/A - ;; /REFENTRY - #t) - -;; Margins around cell contents -;; (define %cals-cell-before-row-margin% 20pt) -;; (define %cals-cell-after-row-margin% 20pt) - -;; seems to be a bug in JadeTeX -- we get a wierd indent on table -;; cells for the first line only. This is a workaround. -;; Adam Di Carlo, adam@onshore.com -(define %cals-cell-before-column-margin% 5pt) -(define %cals-cell-after-column-margin% 5pt) - -;; Inheritable start and end indent for cell contents -(define %cals-cell-content-start-indent% 5pt) -(define %cals-cell-content-end-indent% 5pt) - - - - - - diff --git a/doc/arm/validate.sh.in b/doc/arm/validate.sh.in deleted file mode 100644 index fa33eda808d8a2050475430d542098e2fab46141..0000000000000000000000000000000000000000 --- a/doc/arm/validate.sh.in +++ /dev/null @@ -1,21 +0,0 @@ -#!/bin/sh -# -# Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") -# Copyright (C) 2000, 2001 Internet Software Consortium. -# -# 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. -# -# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH -# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY -# AND FITNESS. IN NO EVENT SHALL ISC 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. - -# $Id: validate.sh.in,v 1.3 2004/03/05 05:04:43 marka Exp $ - -nsgmls -sv @SGMLDIR@/docbook/dsssl/modular/dtds/decls/xml.dcl \ - Bv9ARM-book.xml diff --git a/doc/xsl/.cvsignore b/doc/xsl/.cvsignore new file mode 100644 index 0000000000000000000000000000000000000000..d5e85fcfb6cfbf88675e191a5e972a539d872476 --- /dev/null +++ b/doc/xsl/.cvsignore @@ -0,0 +1,4 @@ +isc-docbook-chunk.xsl +isc-docbook-html.xsl +isc-docbook-latex.xsl +isc-manpage.xsl diff --git a/doc/xsl/copyright.xsl b/doc/xsl/copyright.xsl new file mode 100644 index 0000000000000000000000000000000000000000..ddf9ad6bc23502d906938c4f47be7a889f9699c9 --- /dev/null +++ b/doc/xsl/copyright.xsl @@ -0,0 +1,71 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Copyright (C) + + + + + + + + + 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. + + THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS. IN NO EVENT SHALL ISC 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. + + + + + + + + diff --git a/doc/xsl/isc-docbook-chunk.xsl.in b/doc/xsl/isc-docbook-chunk.xsl.in new file mode 100644 index 0000000000000000000000000000000000000000..a70676b6493a34505a2f1a20b43efec0e720cbe3 --- /dev/null +++ b/doc/xsl/isc-docbook-chunk.xsl.in @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + ansi + + + + + + + + + - + + + + + + + + + + + + + diff --git a/doc/xsl/isc-docbook-html.xsl.in b/doc/xsl/isc-docbook-html.xsl.in new file mode 100644 index 0000000000000000000000000000000000000000..46028ab9def272baae3831116d4c91a1727e14d0 --- /dev/null +++ b/doc/xsl/isc-docbook-html.xsl.in @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + ansi + + + + + + + + + - + + + + + + + + + + + + + diff --git a/doc/xsl/isc-docbook-latex.xsl.in b/doc/xsl/isc-docbook-latex.xsl.in new file mode 100644 index 0000000000000000000000000000000000000000..02e6ed1e4d1b2680ca3a8fcc51f24390d216b9e1 --- /dev/null +++ b/doc/xsl/isc-docbook-latex.xsl.in @@ -0,0 +1,82 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ansi + + + + + + , + + + + + + + + % + + + + + + + + + + + \par + + + + + diff --git a/doc/xsl/isc-manpage.xsl.in b/doc/xsl/isc-manpage.xsl.in new file mode 100644 index 0000000000000000000000000000000000000000..cb6c00d379542864f10d7c84d6b3be4a1de9d289 --- /dev/null +++ b/doc/xsl/isc-manpage.xsl.in @@ -0,0 +1,131 @@ + + + + + + + + + + + + + + + + .\" + + + + + + ansi + + + + + + + .hy 0 + .ad l + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .RS .B " + + + + + : + + + :" + + .RE + + + + + .HP + + + + + + + + + + + + + diff --git a/doc/xsl/pre-latex.xsl b/doc/xsl/pre-latex.xsl new file mode 100644 index 0000000000000000000000000000000000000000..3e1c814c6c7fd5f26db8b639f2bfda4f69dde129 --- /dev/null +++ b/doc/xsl/pre-latex.xsl @@ -0,0 +1,55 @@ + + + + + + + + + + + + + + + + --- + + + + + + + + + + + + + + + + + + + + + + diff --git a/docutil/docbook2man-wrapper.sh.in b/docutil/docbook2man-wrapper.sh.in deleted file mode 100644 index 23af5542d9899e7b6ddf7d2e67d53b2dd807ac38..0000000000000000000000000000000000000000 --- a/docutil/docbook2man-wrapper.sh.in +++ /dev/null @@ -1,40 +0,0 @@ -#!/bin/sh -# -# Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") -# Copyright (C) 2001, 2002 Internet Software Consortium. -# -# 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. -# -# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH -# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY -# AND FITNESS. IN NO EVENT SHALL ISC 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. - -# $Id: docbook2man-wrapper.sh.in,v 1.5 2004/03/05 05:04:58 marka Exp $ - -case $# in - 3) ;; - *) echo "$0: wrong number of arguments" >&2; exit 1 ;; -esac - -top_srcdir=$1 -source=$2 -target=$3 - -ONSGMLS=onsgmls -SGMLSPL=sgmlspl -SGMLCATALOG=@SGMLCATALOG@ -DOCBOOK2MANSPEC=@DOCBOOK2MANSPEC@ - -${ONSGMLS} -c ${SGMLCATALOG} $source | ${SGMLSPL} ${DOCBOOK2MANSPEC} -rm -f $target.tmp -grep -v 'auto-generated by docbook2man' $target > $target.tmp -rm -f $target -cat ${top_srcdir}/docutil/MAN_COPYRIGHT > $target -cat $target.tmp >> $target -rm -f manpage.* $target.tmp diff --git a/lib/lwres/man/lwres.docbook b/lib/lwres/man/lwres.docbook index efad1ce62dd5995ccc20101b75fed3b3e022a011..7a55c37505a05369bb15dee5b9c9ee6faf47dfed 100644 --- a/lib/lwres/man/lwres.docbook +++ b/lib/lwres/man/lwres.docbook @@ -1,4 +1,6 @@ - +]> + + - + + Jun 30, 2000 + - - - -Jun 30, 2000 - - -lwres -3 -BIND9 - - -lwres -introduction to the lightweight resolver library - - - - + + lwres + 3 + BIND9 + + + lwres + introduction to the lightweight resolver library + + + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + #include <lwres/lwres.h> - - - -DESCRIPTION - -The BIND 9 lightweight resolver library is a simple, name service -independent stub resolver library. It provides hostname-to-address -and address-to-hostname lookup services to applications by -transmitting lookup requests to a resolver daemon -lwresd -running on the local host. The resover daemon performs the -lookup using the DNS or possibly other name service protocols, -and returns the results to the application through the library. -The library and resolver daemon communicate using a simple -UDP-based protocol. - - - - -OVERVIEW - -The lwresd library implements multiple name service APIs. -The standard -gethostbyname(), -gethostbyaddr(), -gethostbyname_r(), -gethostbyaddr_r(), -getaddrinfo(), -getipnodebyname(), -and -getipnodebyaddr() -functions are all supported. To allow the lwres library to coexist -with system libraries that define functions of the same name, -the library defines these functions with names prefixed by -lwres_. -To define the standard names, applications must include the -header file -<lwres/netdb.h> -which contains macro definitions mapping the standard function names -into -lwres_ -prefixed ones. Operating system vendors who integrate the lwres -library into their base distributions should rename the functions -in the library proper so that the renaming macros are not needed. - - -The library also provides a native API consisting of the functions -lwres_getaddrsbyname() -and -lwres_getnamebyaddr(). -These may be called by applications that require more detailed -control over the lookup process than the standard functions -provide. - - -In addition to these name service independent address lookup -functions, the library implements a new, experimental API -for looking up arbitrary DNS resource records, using the -lwres_getaddrsbyname() -function. - - -Finally, there is a low-level API for converting lookup -requests and responses to and from raw lwres protocol packets. -This API can be used by clients requiring nonblocking operation, -and is also used when implementing the server side of the lwres -protocol, for example in the -lwresd -resolver daemon. The use of this low-level API in clients -and servers is outlined in the following sections. - - - -CLIENT-SIDE LOW-LEVEL API CALL FLOW - -When a client program wishes to make an lwres request using the -native low-level API, it typically performs the following -sequence of actions. - - -(1) Allocate or use an existing lwres_packet_t, -called pkt below. - - -(2) Set pkt.recvlength to the maximum length we will accept. -This is done so the receiver of our packets knows how large our receive -buffer is. The "default" is a constant in -lwres.h: LWRES_RECVLENGTH = 4096. - - -(3) Set pkt.serial -to a unique serial number. This value is echoed -back to the application by the remote server. - - -(4) Set pkt.pktflags. Usually this is set to 0. - - -(5) Set pkt.result to 0. - -