From 268a4475065fe6a8cd7cc707820982cf5e98f430 Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Wed, 11 May 2005 05:55:41 +0000 Subject: [PATCH] 1856. [doc] Switch Docbook toolchain from DSSSL to XSL. --- bin/check/named-checkconf.docbook | 110 +- bin/check/named-checkzone.docbook | 201 +- bin/dig/dig.docbook | 1433 +- bin/dig/host.docbook | 390 +- bin/dig/nslookup.docbook | 633 +- bin/dnssec/dnssec-keygen.docbook | 350 +- bin/dnssec/dnssec-signzone.docbook | 427 +- bin/named/lwresd.docbook | 316 +- bin/named/named.conf.docbook | 185 +- bin/named/named.docbook | 389 +- bin/nsupdate/nsupdate.docbook | 1190 +- bin/rndc/rndc-confgen.docbook | 292 +- bin/rndc/rndc.conf.docbook | 244 +- bin/rndc/rndc.docbook | 240 +- configure.in | 171 +- doc/arm/.cvsignore | 13 +- doc/arm/Bv9ARM-book.xml | 15632 ++++++++++++------- doc/arm/Makefile.in | 58 +- doc/arm/isc.color.gif | Bin 6384 -> 0 bytes doc/arm/latex-fixup.pl | 45 + doc/arm/nominum-docbook-html.dsl.in | 148 - doc/arm/nominum-docbook-print.dsl.in | 42 - doc/arm/validate.sh.in | 21 - doc/xsl/.cvsignore | 4 + doc/xsl/copyright.xsl | 71 + doc/xsl/isc-docbook-chunk.xsl.in | 63 + doc/xsl/isc-docbook-html.xsl.in | 56 + doc/xsl/isc-docbook-latex.xsl.in | 82 + doc/xsl/isc-manpage.xsl.in | 131 + doc/xsl/pre-latex.xsl | 55 + docutil/docbook2man-wrapper.sh.in | 40 - lib/lwres/man/lwres.docbook | 442 +- lib/lwres/man/lwres_buffer.docbook | 552 +- lib/lwres/man/lwres_config.docbook | 250 +- lib/lwres/man/lwres_context.docbook | 437 +- lib/lwres/man/lwres_gabn.docbook | 385 +- lib/lwres/man/lwres_gai_strerror.docbook | 301 +- lib/lwres/man/lwres_getaddrinfo.docbook | 623 +- lib/lwres/man/lwres_gethostent.docbook | 690 +- lib/lwres/man/lwres_getipnode.docbook | 530 +- lib/lwres/man/lwres_getnameinfo.docbook | 297 +- lib/lwres/man/lwres_getrrsetbyname.docbook | 317 +- lib/lwres/man/lwres_gnba.docbook | 382 +- lib/lwres/man/lwres_hstrerror.docbook | 204 +- lib/lwres/man/lwres_inetntop.docbook | 155 +- lib/lwres/man/lwres_noop.docbook | 368 +- lib/lwres/man/lwres_packet.docbook | 409 +- lib/lwres/man/lwres_resutil.docbook | 343 +- make/rules.in | 57 +- 49 files changed, 17602 insertions(+), 12172 deletions(-) delete mode 100644 doc/arm/isc.color.gif create mode 100644 doc/arm/latex-fixup.pl delete mode 100644 doc/arm/nominum-docbook-html.dsl.in delete mode 100644 doc/arm/nominum-docbook-print.dsl.in delete mode 100644 doc/arm/validate.sh.in create mode 100644 doc/xsl/.cvsignore create mode 100644 doc/xsl/copyright.xsl create mode 100644 doc/xsl/isc-docbook-chunk.xsl.in create mode 100644 doc/xsl/isc-docbook-html.xsl.in create mode 100644 doc/xsl/isc-docbook-latex.xsl.in create mode 100644 doc/xsl/isc-manpage.xsl.in create mode 100644 doc/xsl/pre-latex.xsl delete mode 100644 docutil/docbook2man-wrapper.sh.in diff --git a/bin/check/named-checkconf.docbook b/bin/check/named-checkconf.docbook index e1caf5238f..bbb4556ae7 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 9ed5ce5f21..46b3a62258 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 50b6e5e779..7247cf6c42 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. + 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. - + 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 - - + + FILES + /etc/resolv.conf + + ${HOME}/.digrc + + - -SEE ALSO - - -host1 -, - -named8 -, - -dnssec-keygen8 -, -RFC1035. - - + + SEE ALSO + + host1 + , + + named8 + , + + dnssec-keygen8 + , + RFC1035. + + - -BUGS - -There are probably too many query options. - - - + + BUGS + + There are probably too many query options. + + + diff --git a/bin/dig/host.docbook b/bin/dig/host.docbook index a9272ad29c..70b358b0a4 100644 --- a/bin/dig/host.docbook +++ b/bin/dig/host.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -host -1 -BIND9 - + + host + 1 + BIND9 + - -host -DNS lookup utility - + + host + DNS lookup utility + - - - host - - - - - - - - - - name - server - - + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + Internet Software Consortium + + - -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. - + + + host + + + + + + + + + + name + server + + - -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. - + + DESCRIPTION - -The (all) option is equivalent to setting the - option and asking host to make -a query of type ANY. - + 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. + - -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. - + 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 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). - + + The (all) option is equivalent to setting the + option and asking host to make + a query of type ANY. + - -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. - + + 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. + - -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 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). + - -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. - + + 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. + - -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. - + + 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 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. - + + 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. + - -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. - + + 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. + - -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 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. + - -The option forces host to only -use IPv4 query transport. The option forces -host to only use IPv6 query transport. - + + 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. + - -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). - + + 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 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 option forces host to only + use IPv4 query transport. The option forces + host to only use IPv6 query transport. + - -The can be used to set the memory usage debugging flags -record, usage and -trace. - - + + 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). + - -FILES - -/etc/resolv.conf - - + + 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. + - -SEE ALSO - - -dig1 -, - -named8 -. - + + 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 2767266331..f6aa7ab52c 100644 --- a/bin/dig/nslookup.docbook +++ b/bin/dig/nslookup.docbook @@ -1,4 +1,6 @@ - +]> - - - + - - -Jun 30, 2000 - + + Jun 30, 2000 + - -nslookup -1 -BIND9 - + + nslookup + 1 + BIND9 + - -nslookup -query Internet name servers interactively - + + nslookup + query Internet name servers interactively + - - - nslookup - - name | - - server - - + + + 2004 + Internet Systems Consortium, Inc. ("ISC") + + - -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. - - + + + nslookup + + name | - + server + + - -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. - - - - + + 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. + + - -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. - + + 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. + + + + - -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: - - + + 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. - + + 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. - + + 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. - + + 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 + + root + + + not implemented + + + -finger -not implemented + + finger + + + not implemented + + + -ls -not implemented + + ls + + + not implemented + + + -view -not implemented + + view + + + not implemented + + + -help -not implemented + + help + + + not implemented + + + -? -not implemented + + ? + + + not implemented + + + -exit -Exits the program. + + 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. - - - + + 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) - - + + 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. - 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) - + + + (Default = IN; abbreviation = cl) + + + - nod2 - - Turn debugging mode on. A lot more information is - printed about the packet sent to the server and the - resulting answer. - - (Default = nod2) - + + + 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) + + + - domain=name - - Sets the search list to name. - + + + nod2 + + + Turn debugging mode on. A lot more information is + printed about the packet sent to the server and the + resulting answer. + + + (Default = nod2) + + + - 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) - + + domain=name + + + Sets the search list to name. + + + - port=value - - Change the default TCP/UDP name server port to value. - - (Default = 53; abbreviation = po) - + + + 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) + + + - querytype=value - + + port=value + + + Change the default TCP/UDP name server port to value. + + + (Default = 53; abbreviation = po) + + + - type=value - - Change the top of the information query. - - (Default = A; abbreviations = q, ty) - + + querytype=value + + + + - norecurse - - Tell the name server to query other servers if it does not have the - information. - - (Default = recurse; abbreviation = [no]rec) - + + type=value + + + Change the top of the information query. + + + (Default = A; abbreviations = q, ty) + + + - retry=number - - Set the number of retries to number. - + + + norecurse + + + Tell the name server to query other servers if it does not + have the + information. + + + (Default = recurse; abbreviation = [no]rec) + + + - timeout=number - - Change the initial timeout interval for waiting for a - reply to number seconds. - + + retry=number + + + Set the number of retries to number. + + + - novc - - Always use a virtual circuit when sending requests to the server. - - (Default = novc) - + + 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 -. - - + + FILES + /etc/resolv.conf + + - -Author - -Andrew Cherenson - - - + + SEE ALSO + + dig1 + , + + host1 + , + + named8 + . + + + + + Author + + Andrew Cherenson + + + diff --git a/bin/dnssec/dnssec-keygen.docbook b/bin/dnssec/dnssec-keygen.docbook index ed4de1088e..1be91d31ce 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: + + Kexample.com.+003+26160 - The command would print a string of the form: - - - 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 - - + + FILES + /etc/named.conf + + - -SEE ALSO - - -named8 -, - -rndc8 -, - -BIND 9 Adminstrators Reference Manual -. - - + + SEE ALSO + + named8 + , + + rndc8 + , + + BIND 9 Administrator 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 - - + + Jun 30, 2000 + + + nsupdate + 8 + BIND9 + + + nsupdate + Dynamic DNS update utility + - -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. - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2002 + 2003 + Internet Software Consortium + + - -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. - + + + nsupdate + + + + + + + + + + filename + + - - -local -address -port - - - - -Sends all dynamic update requests using the local -address. + + 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. + + -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. + + 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: + - - -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. - - - + + + 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. + + + - - -class -classname - - - - -Specify the default class. -If no class is specified the default class is -IN. - - - + + + local + address + port + + + + Sends all dynamic update requests using the local + address. - - -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 . - - - + 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. + + + - - -prereq nxdomain -domain-name - - - - -Requires that no resource record of any type exists with name -domain-name. - - - + + + 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 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 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 + + + + 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. - - - + + + 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 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. - - - + + + 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. - - - + + + 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. - - + + + send + + + + Sends the current message. This is equivalent to entering a + blank line. + + + - - -answer - - - - -Displays the answer. - - + + + answer + + + + Displays the answer. + + + - + + - -Lines beginning with a semicolon are comments and are ignored. - + + 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. + + 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. + + + 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.) - - + 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 + + FILES - -/etc/resolv.conf - - -used to identify default name server - - + + + /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}.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 -. - - - - + + 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. - - - + + 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 1f210fd9bb..0509a5e95b 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: + 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: /* */ - C++ style: // to end of line + C++ style: // to end of line - Unix 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. - 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. - 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. - 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. - 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. + 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 aa6011524c..6de50ecb33 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 7cf84a1e5c..16f88edba8 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. -# - -AC_PATH_PROGS(OPENJADE, openjade, openjade) -AC_SUBST(OPENJADE) - # # Look for TeX. # -AC_PATH_PROGS(JADETEX, jadetex, jadetex) -AC_SUBST(JADETEX) +AC_PATH_PROGS(LATEX, latex, latex) +AC_SUBST(LATEX) -AC_PATH_PROGS(PDFJADETEX, pdfjadetex, pdfjadetex) -AC_SUBST(PDFJADETEX) +AC_PATH_PROGS(PDFLATEX, pdflatex, pdflatex) +AC_SUBST(PDFLATEX) + +# +# Look for xsltproc (libxslt) +# + +AC_PATH_PROG(XSLTPROC, xsltproc, xsltproc) +AC_SUBST(XSLTPROC) + +# +# Look for xmllint (libxml2) +# + +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: +# 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. # -# 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 + +docbook_xsl_trees="/usr/pkg/share/xsl /usr/local/share/xsl /usr/share/xsl" + # -catalogpath="" -for d in $sgmltrees +# 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) + +# +# Same dance for db2latex +# +# No idea where this lives except on FreeBSD. +# + +db2latex_xsl_trees="/usr/local/share" + +# +# Look for stylesheets we need. +# + +NOM_PATH_FILE(XSLT_DB2LATEX_STYLE, db2latex/xsl/docbook.xsl, $db2latex_xsl_trees) + +# +# Look for "admonition" image directory. Can't use NOM_PATH_FILE() +# because it's a directory, so just do the same things, inline. +# + +AC_MSG_CHECKING(for db2latex/xsl/figures) +for d in $db2latex_xsl_trees do - catalogpath="$catalogpath $d" - for s in docbook/dsssl-stylesheets - do - catalogpath="$catalogpath $d/$s" - done + dd=$d/db2latex/xsl/figures + if test -d $dd + then + XSLT_DB2LATEX_ADMONITIONS=$dd + AC_MSG_RESULT($dd) + break + fi done -NOM_PATH_FILE(SGMLCATALOG, catalog, $catalogpath) - -# -# Look for the HTML stylesheet html/docbook.dsl, used for -# formatting man pages in HTML. Its location varies, -# so far we have seen: -# -# 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/ -# -# Ditto for the print stylesheet print/docbook.dsl. -# - -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) - -# -# 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/ -# - -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) - -# -# Look for docbook2man-spec.pl -# - -NOM_PATH_FILE(DOCBOOK2MANSPEC, docbook2X/docbook2man-spec.pl, $sgmltrees) +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 eff975abfb..a47eb8f263 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 a0b732506e..54e650d1f7 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 + BIND 9 Administrator Reference Manual - - -2004 -Internet Systems Consortium, Inc. ("ISC") - - -2000-2003 -Internet Software Consortium - - + + + 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. + + 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 + + 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. + + 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 + + This version of the manual corresponds to BIND version 9.3. + - 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. - + + 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 + + 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. + + 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. - + + 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 + + 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. + + 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 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. - + + 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 -. + + 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 -. - + + 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. + + 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. + + 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. + + 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. - + + 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 + + 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. - + + 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 (). + + 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 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. - + + 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. - + + 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 + + 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. + + 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 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. + + 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 + 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. + + 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. + + 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. - + + 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 + + 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. - + + 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. - + + 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 + + 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. + + 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. + + 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 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. + 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 + + <acronym>BIND</acronym> Resource Requirements - -Hardware 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. + + 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. + + 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. + + 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. - - + + 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. + + 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. + + 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. + + Load Balancing -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: + + A primitive form of load balancing can be achieved in + the DNS by using multiple A records for + one name. + - - - - - - - - - -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. + + 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. - + + Name Server Operations - - -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. - - + + 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. + - -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. - - + + + 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. + + + - -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. - + + 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: + + + - + + Administrative Tools + + Administrative tools play an integral part in the management + of a server. + + + - reload - Reload configuration file and zones. - + named-checkconf + + + The named-checkconf program + checks the syntax of a named.conf file. + + + named-checkconf + -jvz + -t directory + filename + + + + - reload zone - class + 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. - + + + Reload the given zone. + + + - refresh zone - class + + refresh zone + class view - Schedule zone maintenance for the given zone. - + + + 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. - + + + 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 + + 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. - + + + 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 + + notify zone + class view - Resend NOTIFY messages for the zone + + + 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. - - + + 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. - + + 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. + + 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. + + 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. + + 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. + + 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 + + + Increment the servers debugging level by one. + + + - trace level - Sets the server's debugging level to an explicit - value. + + trace level + + + Sets the server's debugging level to an explicit + value. + + + - notrace - Sets the server's debugging level to 0. + + notrace + + + Sets the server's debugging level to 0. + + + - flush - Flushes the server's cache. + + 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. + + flushname name + + + Flushes the given name from the server's cache. + + + - recursing - Dump the list of queries named is currently recursing - on. - + + 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. + + recursing + + + Dump the list of queries named is currently recursing + on. + + + -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. + + 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. + -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. + + 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 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 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 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. + + 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: + -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. - + + 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. - - - - - - + + + + + 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 + + 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. + 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. - + + 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 - 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 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. + + 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. + + 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 + + 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. + + 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. + + 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. + + 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. + + 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. + + 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. + + 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. - + + Incremental Zone Transfers (IXFR) -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. - + + 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 . + -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. + + 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. + - 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 + + 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: + -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. + + + 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: + -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 . + + 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 + + + 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. + + 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. + + 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 - 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. + 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. - - - Signing the Zone + + 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. + - The dnssec-signzone program is used to - sign a zone. + + + SIG(0) - 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. + + 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. + - 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. + + 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. + -dnssec-signzone -o child.example zone.child.example + + SIG(0) signing of multiple-message TCP streams is not + supported. + - One output file is produced: - zone.child.example.signed. This file - should be referenced by named.conf as the - input file for the zone. + + The only tool shipped with BIND 9 that + generates SIG(0) signed messages is nsupdate. + - 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. + + + 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. + -Configuring Servers + + 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. + -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. + + 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. + -The public key for any security root must be present in -the configuration file's trusted-keys -statement, as described later in this document. + + 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 - - - IPv6 Support in <acronym>BIND</acronym> 9 + + The dnssec-keygen program is used to + generate keys. + - 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. + + 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. + - 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. + + The following command will generate a 768 bit RSASHA1 key for + the child.example zone: + - 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. + + dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example. + - For an overview of the format and structure of IPv6 addresses, - see . + + 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. + - - Address Lookups Using AAAA Records + + To generate another key with the same properties (but with + a different key tag), repeat the above command. + - The AAAA record is a parallel to the IPv4 A record. It - specifies the entire address in a single record. For - example, + + 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 . + + + + 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 + + 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. + + 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 + + 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. + + 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. + + 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 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. + + 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 + + <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 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 ; + + 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. + + + 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 + + -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. + + 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. + -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. + + 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 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. + + 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. + -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. - - + + 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. + - -Comment Syntax + + 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. + + + -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. + + Comment Syntax - -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. + -/* 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. + + 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: + -# This is the start of a comment. The next line + + + 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 # 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 + + + 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. + + + + + - 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. + + Configuration File Grammar - The following statements are supported: + + 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. + - - - - - - - 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. + + The following statements are supported: + - - <command>acl</command> Statement Grammar + + + + + + + + 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. + + + + + + - acl acl-name { + + 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). + + + <command>acl</command> Statement Definition and + Usage - 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 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). + - The following ACLs are built-in: + + Note that an address match list's name must be defined + with acl before it can be used + elsewhere; no + forward references are allowed. + - - - - - -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. - - - - + + 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>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. + + <command>controls</command> Statement Definition and + Usage - 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. - + + 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. + - - If no port is specified, port 953 - is used. "*" cannot be used for - ip_port. + + 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. + - 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. - + + If no port is specified, port 953 + is used. "*" cannot be used for + ip_port. + - 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. + + 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. + - -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 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. + - 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. + + 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. + -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. - + + 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. - - 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. + 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. + - 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. + + 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. + - -To disable the command channel, use an empty controls -statement: controls { };. - + + 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. + - - - <command>include</command> Statement Grammar - include filename; - - - <command>include</command> Statement Definition and Usage + + To disable the command channel, use an empty controls + statement: controls { };. + - 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>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 - - - <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 ). - + + <command>key</command> Statement Definition and Usage - -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 statement defines a shared + secret key for use with TSIG (see ) + or the command channel + (see ). + -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 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 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. + + 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. + - - - <command>logging</command> Statement Grammar - logging { + + 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. + + 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 + + The <command>channel</command> Phrase -All log output goes to one or more channels; -you can make as many of them as you want. + + 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). + + 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 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. + + 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. + + 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. + + 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: + + 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 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 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 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 + + 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: + -There are four predefined channels that are used for -named's default logging as follows. How they are -used is described in . - + + 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. + + 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. + + 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. - + + 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 + + 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: + -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 + + 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. + + + + + + + + - This is the grammar of the lwres -statement in the named.conf file: + + <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 + + + <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 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 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 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 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 -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. + + <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. - + + 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. + + + -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. + + 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 + + + + + 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. - + 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. - + + 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. - + + 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. - + + 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 - + + 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. - - + + 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. - + + 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). - - + + 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"). + -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, + + + + + + 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. + + 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. + + 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. + + 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. + + 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. + + 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, + + 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. + + + 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). - + + 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-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-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-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-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-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). - + + 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). + + + -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. - - + + 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-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. - - + + 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. + + + -transfer-format - + + 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. + + + - -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. - + + 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-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-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. - + + 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. + + + -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. - + + 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-v6 -The same as transfer-source, -except zone transfers are performed using IPv6. - + + 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. + + + -alt-transfer-source -An alternate transfer source if the one listed in -transfer-source fails and -use-alt-transfer-source is set. - + + transfer-source-v6 + + + The same as transfer-source, + except zone transfers are performed using IPv6. + + + -alt-transfer-source-v6 -An alternate transfer source if the one listed in -transfer-source-v6 fails and -use-alt-transfer-source is set. - + + alt-transfer-source + + + An alternate transfer source if the one listed in + transfer-source 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). - + + alt-transfer-source-v6 + + + An alternate transfer source if the one listed in + transfer-source-v6 fails and + use-alt-transfer-source is + set. + + + -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. - + + 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-v6 -Like notify-source, -but applies to notify messages sent to IPv6 addresses. - + + 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 + + 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. + + -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 . + + Operating System Resource Limits -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. + + 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. - + + coresize + + + The maximum size of a core dump. The default + is default. + + + -files -The maximum number of files the server -may have open concurrently. The default is unlimited. - - + + 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. + + + -stacksize -The maximum amount of stack memory the server -may use. The default is default. - + + 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. + + 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. - + + 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. + + + -host-statistics-max -In BIND 8, specifies the maximum number of host statistic -entries to be kept. -Not implemented in BIND 9. - + + 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. + + + -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. - - + + host-statistics-max + + + In BIND 8, specifies the maximum number of host statistic + entries to be kept. + Not implemented in BIND 9. + + + -tcp-clients -The maximum number of simultaneous client TCP -connections that the server will accept. -The default is 100. - + + 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. + + + -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-clients + + + The maximum number of simultaneous client TCP + connections that the server will accept. + The default is 100. + + + -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. - - + + 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 + - + + 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. - + + 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. + + + -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. - + + 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. + + + -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. - + + 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 + + + + 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, + -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 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 <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 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. - - + + 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. + -Tuning + + + 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). + - + + 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). - + + 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. + + + -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. - + + 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). + + + -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-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. + + + + - -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. - + + 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. + + + - -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. - - + + 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. + + 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. - + + 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. + + + -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. - - + + 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 + + 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. - - - + 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. - + + 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 + + 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 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. - + + 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. - + + 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. - + + 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 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. - + + 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. - - + + 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. - - + + 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. - - + + 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 + + <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 + + <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 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. - + + 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. + + 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. + + 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. + + 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 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. + + 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. + 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. + + 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. + + 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 -. + + 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>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. + + + <command>view</command> Statement Definition and Usage -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. + + 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. + -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. + + 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. + -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. + + 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. + -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. + + 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. + -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. + + 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. + -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. + + + <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 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. - - - + + 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. + -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. - + + 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. + + + + + + + -Zone Options + + 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 - + + 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-query -See the description of -allow-query in - + + allow-notify + + + See the description of + allow-notify in + + + -allow-transfer -See the description of allow-transfer -in . - + + allow-query + + + See the description of + allow-query in + + + -allow-update -See the description of allow-update -in . - + + allow-transfer + + + See the description of allow-transfer + in . + + + -update-policy -Specifies a "Simple Secure Update" policy. See -. - + + allow-update + + + See the description of allow-update + in . + + + -allow-update-forwarding -See the description of allow-update-forwarding -in . - + + update-policy + + + Specifies a "Simple Secure Update" policy. See + . + + + -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. - + + allow-update-forwarding + + + See the description of allow-update-forwarding + in . + + + -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. - - + + 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-wildcard -See the description of -check-wildcard in . - + + 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. + + + -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. - + + check-wildcard + + + See the description of + check-wildcard in . + + + -dialup -See the description of -dialup 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. + + + -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. - - + + dialup + + + See the description of + dialup in . + + + -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. - + + 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. + + + -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. - + + 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. + + + -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. - + + 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-tmp-file -Was an undocumented option in BIND 8. -Ignored in BIND 9. - + + 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. + + + -max-transfer-time-in -See the description of -max-transfer-time-in in . - + + ixfr-tmp-file + + + Was an undocumented option in BIND 8. + Ignored in BIND 9. + + + -max-transfer-idle-in -See the description of -max-transfer-idle-in in . - + + max-transfer-time-in + + + See the description of + max-transfer-time-in in . + + + -max-transfer-time-out -See the description of -max-transfer-time-out in . - + + max-transfer-idle-in + + + See the description of + max-transfer-idle-in in . + + + -max-transfer-idle-out -See the description of -max-transfer-idle-out in . - + + max-transfer-time-out + + + See the description of + max-transfer-time-out in . + + + -notify -See the description of -notify in . - + + max-transfer-idle-out + + + See the description of + max-transfer-idle-out 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. - + + notify + + + See the description of + notify in . + + + -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. - + + 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. + + + -sig-validity-interval -See the description of -sig-validity-interval in . - + + 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. + + + -transfer-source -See the description of -transfer-source in - - + + sig-validity-interval + + + See the description of + sig-validity-interval in . + + + -transfer-source-v6 -See the description of -transfer-source-v6 in - - + + transfer-source + + + See the description of + transfer-source in + + + -alt-transfer-source -See the description of -alt-transfer-source in - - + + transfer-source-v6 + + + See the description of + transfer-source-v6 in + + + -alt-transfer-source-v6 -See the description of -alt-transfer-source-v6 in - - + + alt-transfer-source + + + See the description of + alt-transfer-source in + + + -use-alt-transfer-source -See the description of -use-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 + + + See the description of + notify-source in + + + -notify-source-v6 -See the description of -notify-source-v6 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 . - + + 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 . - + + ixfr-from-differences + + + See the description of + ixfr-from-differences in . + + + -key-directory -See the description of -key-directory in - + + key-directory + + + See the description of + key-directory in + + + -multi-master -See the description of -multi-master 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: + - -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. + + 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 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. - - - + + 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. + -In all cases, the name field must -specify 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. + + + + + + -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 + + In all cases, the name + field must + specify a fully qualified domain name. + - 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 . + + 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 -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: - - - + + 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 . + - -IN -The Internet. - + + 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: + + + + + - -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. - - + + + + IN + + + + + The Internet. + + + - -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. - - + + + + 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 + + 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. + + + -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. + + Discussion of MX Records -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. + + 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 + + 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 + -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. - - + + The <command>chroot</command> Environment -Using the <command>setuid</command> Function + + 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. + + -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. - - + + Using the <command>setuid</command> Function -Dynamic Update Security + + 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. + + + -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. + + Dynamic Update Security -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. + + 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. + -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. + + 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. + + Troubleshooting + + Common Problems + + It's not working; how can I figure out what's wrong? - - - - Incrementing and Changing the Serial Number + + 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. + - 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. + + + + Incrementing and Changing the Serial Number - 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. + + 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. + - 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. + + 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. + - - - Where Can I Get Help? + + 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. + - 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. + + + Where Can I Get Help? - 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> + + 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. + - 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. - + + 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> - 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. - - - + + 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. + -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 - - - + + 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. + + + + - 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 - - - - - + 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 c516b089be..27f7c35e69 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 GIT binary patch literal 0 HcmV?d00001 literal 6384 zcmW-kX*iUP+s0?#%-r`ad$zG;2{o4NGzb&bGm>3BBPEHN5DGP8Cp4s$Mzv1Lm`NK)SZ@A=_6j`PF$>AKGAIDW1>T`aAFI52Zkc{NwlcrGjbw1wJ^%jR%MZM-R{LMC4JvLpTAJ(4dKy*1kFRP;s_ra! z`nIC|eRcQnqu$R=17F^V=Z2;v;@PF?1y!u#9f#bJ7efo<-{RFmyyRR<4Kk|TuGje8 zD2UAYz4p7I;XR)}{PE-0k&$n|fB#ut{?Xalb@5`slcyhQ>fW|@j0k%s2Hs6oRQ6O= z_X%Ep&c7lk;&znY>7JbW{!Q{@|Ixca;gx5S8&k5Id_(T|hn9y#R)xntj7+Snd-5Jj zkpG8K>KR<-efW-(Pw~#clKsaks~ZQNwhqT7oY%EWCCM6Wb-lDv*VDqIeB16THXhga z9l7HZR`Fxy*RQodzyJKzZ=w|JW-iQ=1~WE*DJ#P2N>rP8J6q}w^a?@+j}G21{rA2l9|vx|cz)%}2){55b}0~%!~2DXH8&`ACEFUx9UoUXKf6bJe3w>I;P~X; zKhLW6KCkxSSNpd=32S?NwEbyBcT2qR#o6AM$-S@Ad)m_aUS+-OzBD0vHZ|HjH71yw z?v>2GU0$53ziHKQ%dWA^;mMsH&njq5_uQK*cRjzqhhO+%&e5SAUY=7&y zw=dXz0@lFG)OT&^@7l8lJ1-2sx%#Q6NYr;@TKr^g^7Z$*!KL}n%L^l`E8m8?^2Pl( zM+feVzN;7?ygxBiJ^8VI>T~0axM_B@(;^N%g+|<<6*x1;|k01N{`}+LaWoT%qrKP2!q9P|JMFBt@`GR^NOZnM2lue3{ufHu7Od4KocNc zh)mW%ps>J33Y|lCKoW7CZ@+&50-v5;dR6k|(Fs+%b6b`NFScFy`1tH{Z$;k`aM<>o zMA#^@*cxb4KG88abO%uBi~TY-mF((O{5i6+Pz`trGTNF?U<$Ic@_ zkt`3xT0xLbJFkWI(MHffsevBxi=Vk>%x@6nXEIY4F!H|d86cA7K6;F zoNaIE!P#a#RAi3nYuUa}@$;{JJ}3Ts>*#K9uROm)|8};fn;th|1h0{dLeSLXMINpj zag9RIM$DYwV>2}-lPbG!7rXz&A5LAMZFY~7yyf^}GVGwnVok2q(rjzD)fUE!TpJ_$ z+dylh6&bMLmrzS+`>PfP*#BA70*n3>I724o0*BouL~C40imZP|N!n{lRHtriIihQ8 zt)M4OB_ZLVo6-HN88@>GALB~1%|@j0N!&DRj>YGMnlAGXdKbHrNcM{2lpfl8O_p*? zxCY1KmZlal@$uw{l;LaKcd0G)yq1nKgZh<&*`@=&uBwkuYkbv|JzU-DU{Fa8W8c~m z6?XUD^3-OooV^Um1lQhsKCwtq&|a;tb5FnKzfWweR>Ka>u1){FqC1g{`K(qFYMsFY z?IB|U{LKhPERHcg<+`1uNb3W?y(PC6{kts+YB=5GiW!<=0hGE z-syInK^r0~pk$KXQzn8)S)-=N%WUhRfID~CR)c0;9OpKrh`cV%B+H9k4Ki+?yNr8n zOH1PQ<3rWY8eM2`%jAxU%g>(>!ZUQw3LIWqV0);74SOlZP6U%z>%6Ep+uu>0087~e z5)k)G*t)@i2;U*M{XJo63{@SJu5$8e&&!Fzp^`RoF*zx?+`6BFlHD5^NC&)Xn^4kL zj9ouxr_o$EMw!TEJL%@>IJj?pVdlA8UU+&K*dW2~@b(h0?bnsE$H zz;U-bfc4K6tt-?odS$AX)3@~LwnyBK>|g!PYTe`Mu<8_GDUnV6V|zU5d+zqHR5eE& zkA<1@lht)L;JKYMh_SGiIF8F)v9rS26mrs%ET){N>ZZnC* zPak5;2s;F!=2wH<{0b2$^$`Z<@%XDO3&ClB`yDvdw-$tP{C*L2XZa zA0%npZ#8p@CR4XEd#XIj#K4J3r_Bd3v@>rf0rQKO75YUl+w(g1l`oVv{6XCdCALc6 z*Gtu~mBu+tYIrFvr}e@Ts*_Up-)S2YjfXp(brgy5^K`8w5^ ze$9mYo$Rs4KS?gb-$^HVNWv_IrKT)8ksUn#^T*4dlaox6r(*gMtCWzub>R`1V^R( zfHa+67KTO)_V6_dFz`P~?45$$537T}*~3H>$scFfN!Wn)qtwh#OI1o#JW>~eONCPd zuzV59TrxOtw+*HI3WizLypCQsryxLCwcWCO7D&E@o@b>?`SNn^(s9=l^7e0}CTU&;MKSnQw zVNn+-_(>RwCWPa0e6o-J`KYtL7aF=YsZ3JTE&W*+&dws$SFTFgt^_?Fl%Q0;irVZ~ z*~JMwk*aJr)_%-EX{td>1#A5YCRt#Q_sApgaj)4#$%eH9TaD3;Ios#NK;ruc<}-{< zmc9(|962@5+5BPNOf#U>Ij$luY_rR+1-4Wo)yMfkMcI|lb=oS-_b;cl+ zy?Qf6M+&EbqO~?#^$FmnK~!XIEHpU$&Af4tw7uU!_ZM3!-P%kl_7+n0$8NuNmji8) zya*lnS*P~jlbPk0PiFh=(%Q(^#3T%)st1OiB#Zg5aGVKy;JpoEy)MIUkqw?qc2Yjb zLaKC722M)?)KJa&86~Ei*hwcoc%;jg^?kqeP$~LHhE()$9(bC6#{7KR;quFD6T39y z?JesWFN_PsIUXLGo*8tcf@Ih~g0{^O%zvqRKWw4;@Y3Oc-@!gd4&iob3k+nvO*UUt z(Oq3qPW(KOUz=kq7yi8z-77Y?$xVvbyXTtvmWE}UqERrO>X(MtdE*qJx3hde+S_KU zm11I*uZgC62zxR4!z@*pJgLVLkzFnQIiS|AAc6;#uriUiq)ia)oW`XaT0uz=Q)C6C zXBEKpIFygA#*?NO$KGNA-9~-&MTW%Y@gZF{KMA<DYA;)F)LrTZ7x4#$c1JCcWpLZXb#z~R4@9~l#H282$P(froH%?4>LFue7=+N2*nveB z;?C}T3LCYs`?KaAizBW=h_t^}Lq*e^JQA;UP@hXCI9iy#9!Y}B;l8;*rW~XNm*Pl4 z>C+)+n1>q`WiIlIbxsx+obyaQoK2K5dBZA5RVE%m@|=B86U!1qyq;tkX#!M5%R;qH17C2sTl@ z#pTfksY{3i!%5aD1|F4%-ge5M4#--L_x+7#Qe5*6c<{%6b(N5hD?Xg@CUXr1XrFTc$c>CGY};RUif1O0Bq|0)-I zkwa`}CQsn9eNIK5!kX$Mw45wxA;L(cG18ciu$K5P>G|13d2WN5C7Dt%$(HyUij#=q zz(RRbQ8F3$Br2hgPwHoqUh}ah7+Bmo4O`41)Ivl_UhZKhsR}AKl8U>+Bce($aS}`_ zF9lPA-YxXD;iKGHhy)pA_X=VwBg>5Ghl)blb5Pzqlm!JK&_7ix#_lSxn!U*n07 z`ij^@=U_DMA=;gK*_?ye%tY=LTC+|gb*Yxyg-9Q=&Cw|r3>0eE9D=BZtHI7>T3ySy zd_qKqJ!!par~yau6H~-6ONVPW8xiV!Tl}F7*YUQ{J{gDtyLs(0oCjBDQCTh_o0~Tz z*9Q>jw%C&3RXQ-w0w*P5F3UTH>%lE_aQmXuA38WxfA|&(*usbrQ)AlZBLeE>#mNz) zeY<6uGPm_Ng6lyWDf14EeliNIYn5omZ=s!wIcP`)S6M*MC18~fPLsiDmeUdi;QP5P z2*IzgM5~nO!@9tC4){SDToVFcbio-i_>~$l2Z6)mE;^!v+~&kL!6(Y4gSUm)rE4Hm zxp0`b?hqU-9ScX~F{YZscOrr|OdR4@yDQ0qHa*}^k(=^uP}LREiShZ%CkU>>!?y}* zWO&pBO!jXU22>w~tKACtx$UMVSsMRHW{!`zl48F~R>-af)}SCniPjG&(ajieg@a=L zjW1-?c`{(cbDLmsBU=DJgzALIX`TXnl!Y0R3qxE2q&cvXqmY?PnS~A_Yuy2w5+OP- z?VJ+=hCHVdZD2+O%uy5!p~SD;iaCkh^$$Q@529ps(^tOZ2p1S*0$jpf!xVsPeJny7 zcE+Vpj#>Vfs$`k}rrd_TAB8=b@>l1>q9)*9odXE_;PN5}%_?kilWEIRf>SE1oZ&=B zrnscCy#3hSigH!P5nK>3$pm!BvXh*uT!*Tu>s3uXe`nadKQNzFHL($x%>pjDB})9A ze{Ot`zth3sa;5Tz`^0@4!9yo1G{ON<09r%&ur4Sgk72+t`-R{a3Ija>$~*#p@WC|~ zH}Pl@GZLf_+<)@HB|7+%r=`P_DXy2NsHhZNeCoNJQPxBAPrx< zwDE4w##Zle=(1ab2J>l&+%Hy9p&MYt0;aS;LoP51ac3BaUTNyvYGC<0FvpXbWdPkC z;1&rm(HFeJIXedNWN*PC{>GPgVHySZn~?B|YS=yJ;GH&AH9^1uF}NSX1PRgNX5c4X zwsJEhhHXcR<+qR{%A)0FI6!a*kh`p6DBSd&3uL=1`^11V^aBNMR=1KizvAO_Xe6>8 zOpb~ma_xv3Widk=WklEI*=jbI_ltPMBOF{N4zxRAd{uT3V(Ku$5XL7w<^TEh+*}q|I)+$xf4*dMe6o`haTNMQ z!E@1E zSn%8@+f)XZCn~@?0CN&x*BTI20*o#J5+U%R4lq9i>|Fy&`e~zw0eY9fGaT{moxn4@ z!edw=T0qmBL~J!_e8nS9Hal~hU^aAjJQYuyiVZpF{*wu&D4;!I z=*)GWvtrMP5KU+a7UN~Gi3~$%@KqOKF>h1lu1+uo^D5IKP&*CS9AD*k6VQR_UQ*W4 z>u}FsIe+>oC%Uc8`F(CI72CtnLRdqAkdD({?W}hVHZgKX5WpScroBmuWD)4%5cG=+ zZmf?9N&>kG9Y^*8(=x!q=`+v(xUZ)JSxr>T;KX%B8QNyg_;z+Z#70UmAsooMg}F!p zyPmk6zYTf~oit=VdqF(SR#5nNx-_p%#|W1Aq?WNNIsIR{Tz;F}v7|R5F1W}*w4PRG zyhIl;h@YU$T5RWpp}^l+aM~63feX#D{`;m6h3wQ0ItjL)=PyB^eLuLe&fgD*;2Fk< znbAXED0ki%tLeY)P07(ph@&i z#UVm-YVG}Vy<}oEgw64S+V}=dJayeQ(vT3}0pSzY$%HZ}!4*gUFoynCIgIZy+7>q` zyMffez-@LV^}?j~Ya7N_diCua9!(rhr9@$?k$)DDmJ+kl6{LmG+pKNa+;>RsAzPO-B&bYP3%wMYX16=H3JBaC(PfSKGzqjzA8nZG{p6~sqKc;%@ z*65Q+T`#pNsmMm3uE;faPT|Y@uANdRV_&VN)m`Ov49#nr5$xhBfmS$1QD0V!$ z*KzbNrbUI;qnD+`XllV9A6$jW=$ZQ(-F!T`oTQ%L`I$+44h^h+)IUvTD~)Csq<0Q^xf-$7R>YNU8Q->vQup#D&H=!=Q1J0SB@1=t6iI~=M8FZ<> zDY;hTsyg&1IzEOgHOM4AI7ocK$Hp>nPbfqIw`Jdj?i4!qOk6>y1gDsajpXBGk3yz= zPai(Yk&N_d^rmX%RM38=R-o!v=&t-lvv>F$3AT$xdc(y=&~dN$mxc{B@(Q$-i2^3S574n9dm@i@1V z(R_C4Lz#g>RltL=#<03Dd53JJZO0AYA4*#A=*t|H9cLHm2g|bLblqR% zZnE)I(%g}w>9H3nB~!Tjm9^2YiTkr%Mgb2667dcl7bW-AyBR-!%mwAZ;V_&31FnEA A(EtDd diff --git a/doc/arm/latex-fixup.pl b/doc/arm/latex-fixup.pl new file mode 100644 index 0000000000..9fc5401f87 --- /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 33fc938777..0000000000 --- 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 511d6c48bc..0000000000 --- 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 fa33eda808..0000000000 --- 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 0000000000..d5e85fcfb6 --- /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 0000000000..ddf9ad6bc2 --- /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 0000000000..a70676b649 --- /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 0000000000..46028ab9de --- /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 0000000000..02e6ed1e4d --- /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 0000000000..cb6c00d379 --- /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 0000000000..3e1c814c6c --- /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 23af5542d9..0000000000 --- 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 efad1ce62d..7a55c37505 100644 --- a/lib/lwres/man/lwres.docbook +++ b/lib/lwres/man/lwres.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - - -lwres -3 -BIND9 - - -lwres -introduction to the lightweight resolver library - + + Jun 30, 2000 + - - + + 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. - - + + 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. - - -(6) Call lwres_*request_render(), -or marshall in the data using the primitives -such as lwres_packet_render() -and storing the packet data. - - -(7) Transmit the resulting buffer. - - -(8) Call lwres_*response_parse() -to parse any packets received. - - -(9) Verify that the opcode and serial match a request, and process the -packet specific information contained in the body. - - - -SERVER-SIDE LOW-LEVEL API CALL FLOW - -When implementing the server side of the lightweight resolver -protocol using the lwres library, a sequence of actions like the -following is typically involved in processing each request packet. - - -Note that the same lwres_packet_t is used -in both the _parse() and _render() calls, -with only a few modifications made -to the packet header's contents between uses. This method is recommended -as it keeps the serial, opcode, and other fields correct. - - -(1) When a packet is received, call lwres_*request_parse() to -unmarshall it. This returns a lwres_packet_t (also called pkt, below) -as well as a data specific type, such as lwres_gabnrequest_t. - - -(2) Process the request in the data specific type. - - -(3) Set the pkt.result, -pkt.recvlength as above. All other fields can -be left untouched since they were filled in by the *_parse() call -above. If using lwres_*response_render(), -pkt.pktflags will be set up -properly. Otherwise, the LWRES_LWPACKETFLAG_RESPONSE bit should be -set. - - -(4) Call the data specific rendering function, such as -lwres_gabnresponse_render(). - - -(5) Send the resulting packet to the client. - - - - - -SEE ALSO - - -lwres_gethostent3 -, + + 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. + + + (6) Call lwres_*request_render(), + or marshall in the data using the primitives + such as lwres_packet_render() + and storing the packet data. + + + (7) Transmit the resulting buffer. + + + (8) Call lwres_*response_parse() + to parse any packets received. + + + (9) Verify that the opcode and serial match a request, and process the + packet specific information contained in the body. + + + + SERVER-SIDE LOW-LEVEL API CALL FLOW + + When implementing the server side of the lightweight resolver + protocol using the lwres library, a sequence of actions like the + following is typically involved in processing each request packet. + + + Note that the same lwres_packet_t is used + in both the _parse() and _render() calls, + with only a few modifications made + to the packet header's contents between uses. This method is + recommended + as it keeps the serial, opcode, and other fields correct. + + + (1) When a packet is received, call lwres_*request_parse() to + unmarshall it. This returns a lwres_packet_t (also called pkt, below) + as well as a data specific type, such as lwres_gabnrequest_t. + + + (2) Process the request in the data specific type. + + + (3) Set the pkt.result, + pkt.recvlength as above. All other fields + can + be left untouched since they were filled in by the *_parse() call + above. If using lwres_*response_render(), + pkt.pktflags will be set up + properly. Otherwise, the LWRES_LWPACKETFLAG_RESPONSE bit should be + set. + + + (4) Call the data specific rendering function, such as + lwres_gabnresponse_render(). + + + (5) Send the resulting packet to the client. + + + + + SEE ALSO + + lwres_gethostent3 + , - -lwres_getipnode3 -, + + lwres_getipnode3 + , - -lwres_getnameinfo3 -, + + lwres_getnameinfo3 + , - -lwres_noop3 -, + + lwres_noop3 + , - -lwres_gabn3 -, + + lwres_gabn3 + , - -lwres_gnba3 -, + + lwres_gnba3 + , - -lwres_context3 -, + + lwres_context3 + , - -lwres_config3 -, + + lwres_config3 + , - -resolver5 -, + + resolver5 + , - -lwresd8 -. + + lwresd8 + . - - - + + + diff --git a/lib/lwres/man/lwres_buffer.docbook b/lib/lwres/man/lwres_buffer.docbook index df491413d7..791ca49d69 100644 --- a/lib/lwres/man/lwres_buffer.docbook +++ b/lib/lwres/man/lwres_buffer.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_buffer -3 -BIND9 - + + lwres_buffer + 3 + BIND9 + - -lwres_buffer_init -lwres_buffer_invalidate -lwres_buffer_add -lwres_buffer_subtract -lwres_buffer_clear -lwres_buffer_first -lwres_buffer_forward -lwres_buffer_back -lwres_buffer_getuint8 -lwres_buffer_putuint8 -lwres_buffer_getuint16 -lwres_buffer_putuint16 -lwres_buffer_getuint32 -lwres_buffer_putuint32 -lwres_buffer_putmem -lwres_buffer_getmem -lightweight resolver buffer management - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + - + + lwres_buffer_init + lwres_buffer_invalidate + lwres_buffer_add + lwres_buffer_subtract + lwres_buffer_clear + lwres_buffer_first + lwres_buffer_forward + lwres_buffer_back + lwres_buffer_getuint8 + lwres_buffer_putuint8 + lwres_buffer_getuint16 + lwres_buffer_putuint16 + lwres_buffer_getuint32 + lwres_buffer_putuint32 + lwres_buffer_putmem + lwres_buffer_getmem + lightweight resolver buffer management + - + + + #include <lwres/lwbuffer.h> - + void lwres_buffer_init -lwres_buffer_t *b -void *base -unsigned int length - + lwres_buffer_t *b + void *base + unsigned int length + - + void lwres_buffer_invalidate -lwres_buffer_t *b - + lwres_buffer_t *b + - + void lwres_buffer_add -lwres_buffer_t *b -unsigned int n - + lwres_buffer_t *b + unsigned int n + - + void lwres_buffer_subtract -lwres_buffer_t *b -unsigned int n - + lwres_buffer_t *b + unsigned int n + - + void lwres_buffer_clear -lwres_buffer_t *b - + lwres_buffer_t *b + - + void lwres_buffer_first -lwres_buffer_t *b - + lwres_buffer_t *b + - + void lwres_buffer_forward -lwres_buffer_t *b -unsigned int n - + lwres_buffer_t *b + unsigned int n + - + void lwres_buffer_back -lwres_buffer_t *b -unsigned int n - + lwres_buffer_t *b + unsigned int n + - + lwres_uint8_t lwres_buffer_getuint8 -lwres_buffer_t *b - + lwres_buffer_t *b + - + void lwres_buffer_putuint8 -lwres_buffer_t *b -lwres_uint8_t val - + lwres_buffer_t *b + lwres_uint8_t val + - + lwres_uint16_t lwres_buffer_getuint16 -lwres_buffer_t *b - + lwres_buffer_t *b + - + void lwres_buffer_putuint16 -lwres_buffer_t *b -lwres_uint16_t val - + lwres_buffer_t *b + lwres_uint16_t val + - + lwres_uint32_t lwres_buffer_getuint32 -lwres_buffer_t *b - + lwres_buffer_t *b + - + void lwres_buffer_putuint32 -lwres_buffer_t *b -lwres_uint32_t val - + lwres_buffer_t *b + lwres_uint32_t val + - + void lwres_buffer_putmem -lwres_buffer_t *b -const unsigned char *base -unsigned int length - + lwres_buffer_t *b + const unsigned char *base + unsigned int length + - + void lwres_buffer_getmem -lwres_buffer_t *b -unsigned char *base -unsigned int length - + lwres_buffer_t *b + unsigned char *base + unsigned int length + - + - + -DESCRIPTION - -These functions provide bounds checked access to a region of memory -where data is being read or written. -They are based on, and similar to, the -isc_buffer_ -functions in the ISC library. - - -A buffer is a region of memory, together with a set of related -subregions. -The used region and the -available region are disjoint, and -their union is the buffer's region. -The used region extends from the beginning of the buffer region to the -last used byte. -The available region extends from one byte greater than the last used -byte to the end of the buffer's region. -The size of the used region can be changed using various -buffer commands. -Initially, the used region is empty. - - -The used region is further subdivided into two disjoint regions: the -consumed region and the remaining region. -The union of these two regions is the used region. -The consumed region extends from the beginning of the used region to -the byte before the current offset (if any). -The remaining region the current pointer to the end of the used -region. -The size of the consumed region can be changed using various -buffer commands. -Initially, the consumed region is empty. - - -The active region is an (optional) subregion of the remaining -region. -It extends from the current offset to an offset in the -remaining region. -Initially, the active region is empty. -If the current offset advances beyond the chosen offset, -the active region will also be empty. - - - - + DESCRIPTION + + These functions provide bounds checked access to a region of memory + where data is being read or written. + They are based on, and similar to, the + isc_buffer_ + functions in the ISC library. + + + A buffer is a region of memory, together with a set of related + subregions. + The used region and the + available region are disjoint, and + their union is the buffer's region. + The used region extends from the beginning of the buffer region to the + last used byte. + The available region extends from one byte greater than the last used + byte to the end of the buffer's region. + The size of the used region can be changed using various + buffer commands. + Initially, the used region is empty. + + + The used region is further subdivided into two disjoint regions: the + consumed region and the remaining region. + The union of these two regions is the used region. + The consumed region extends from the beginning of the used region to + the byte before the current offset (if any). + The remaining region the current pointer to the end + of the used + region. + The size of the consumed region can be changed using various + buffer commands. + Initially, the consumed region is empty. + + + The active region is an (optional) subregion of the + remaining + region. + It extends from the current offset to an offset in the + remaining region. + Initially, the active region is empty. + If the current offset advances beyond the chosen offset, + the active region will also be empty. + + /------------entire length---------------\\ /----- used region -----\\/-- available --\\ +----------------------------------------+ | consumed | remaining | | +----------------------------------------+ a b c d e - + + + a == base of buffer. b == current pointer. Can be anywhere between a and d. c == active pointer. Meaningful between b and d. d == used pointer. e == length of buffer. - + + + a-e == entire length of buffer. a-d == used region. a-b == consumed region. b-d == remaining region. b-c == optional active region. - - -lwres_buffer_init() -initializes the -lwres_buffer_t -*b -and assocates it with the memory region of size -length -bytes starting at location -base. - - -lwres_buffer_invalidate() -marks the buffer -*b -as invalid. Invalidating a buffer after use is not required, -but makes it possible to catch its possible accidental use. - - -The functions -lwres_buffer_add() -and -lwres_buffer_subtract() -respectively increase and decrease the used space in -buffer -*b -by -n -bytes. -lwres_buffer_add() -checks for buffer overflow and -lwres_buffer_subtract() -checks for underflow. -These functions do not allocate or deallocate memory. -They just change the value of -used. - - -A buffer is re-initialised by -lwres_buffer_clear(). -The function sets -used , -current -and -active -to zero. - - -lwres_buffer_first -makes the consumed region of buffer -*p -empty by setting -current -to zero (the start of the buffer). - - -lwres_buffer_forward() -increases the consumed region of buffer -*b -by -n -bytes, checking for overflow. -Similarly, -lwres_buffer_back() -decreases buffer -b's -consumed region by -n -bytes and checks for underflow. - - -lwres_buffer_getuint8() -reads an unsigned 8-bit integer from -*b -and returns it. -lwres_buffer_putuint8() -writes the unsigned 8-bit integer -val -to buffer -*b. - - -lwres_buffer_getuint16() -and -lwres_buffer_getuint32() -are identical to -lwres_buffer_putuint8() -except that they respectively read an unsigned 16-bit or 32-bit integer -in network byte order from -b. -Similarly, -lwres_buffer_putuint16() -and -lwres_buffer_putuint32() -writes the unsigned 16-bit or 32-bit integer -val -to buffer -b, -in network byte order. - - -Arbitrary amounts of data are read or written from a lightweight -resolver buffer with -lwres_buffer_getmem() -and -lwres_buffer_putmem() -respectively. -lwres_buffer_putmem() -copies -length -bytes of memory at -base -to -b. -Conversely, -lwres_buffer_getmem() -copies -length -bytes of memory from -b -to -base. - - - + + lwres_buffer_init() + initializes the + lwres_buffer_t + *b + and assocates it with the memory region of size + length + bytes starting at location + base. + + lwres_buffer_invalidate() + marks the buffer *b + as invalid. Invalidating a buffer after use is not required, + but makes it possible to catch its possible accidental use. + + + The functions + lwres_buffer_add() + and + lwres_buffer_subtract() + respectively increase and decrease the used space in + buffer + *b + by + n + bytes. + lwres_buffer_add() + checks for buffer overflow and + lwres_buffer_subtract() + checks for underflow. + These functions do not allocate or deallocate memory. + They just change the value of + used. + + + A buffer is re-initialised by + lwres_buffer_clear(). + The function sets + used, + current + and + active + to zero. + + lwres_buffer_first + makes the consumed region of buffer + *p + empty by setting + current + to zero (the start of the buffer). + + lwres_buffer_forward() + increases the consumed region of buffer + *b + by + n + bytes, checking for overflow. + Similarly, + lwres_buffer_back() + decreases buffer + b's + consumed region by + n + bytes and checks for underflow. + + lwres_buffer_getuint8() + reads an unsigned 8-bit integer from + *b + and returns it. + lwres_buffer_putuint8() + writes the unsigned 8-bit integer + val + to buffer + *b. + + lwres_buffer_getuint16() + and + lwres_buffer_getuint32() + are identical to + lwres_buffer_putuint8() + except that they respectively read an unsigned 16-bit or 32-bit integer + in network byte order from + b. + Similarly, + lwres_buffer_putuint16() + and + lwres_buffer_putuint32() + writes the unsigned 16-bit or 32-bit integer + val + to buffer + b, + in network byte order. + + + Arbitrary amounts of data are read or written from a lightweight + resolver buffer with + lwres_buffer_getmem() + and + lwres_buffer_putmem() + respectively. + lwres_buffer_putmem() + copies + length + bytes of memory at + base + to + b. + Conversely, + lwres_buffer_getmem() + copies + length + bytes of memory from + b + to + base. + + + diff --git a/lib/lwres/man/lwres_config.docbook b/lib/lwres/man/lwres_config.docbook index 6296ff5d4b..a983bed566 100644 --- a/lib/lwres/man/lwres_config.docbook +++ b/lib/lwres/man/lwres_config.docbook @@ -1,4 +1,6 @@ - +]> - - - + - + -Jun 30, 2000 - + Jun 30, 2000 + - -lwres_config -3 -BIND9 - + + lwres_config + 3 + BIND9 + - -lwres_conf_init -lwres_conf_clear -lwres_conf_parse -lwres_conf_print -lwres_conf_get -lightweight resolver configuration - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + - - + + lwres_conf_init + lwres_conf_clear + lwres_conf_parse + lwres_conf_print + lwres_conf_get + lightweight resolver configuration + + + + #include <lwres/lwres.h> - + void lwres_conf_init -lwres_context_t *ctx - + lwres_context_t *ctx + - + void lwres_conf_clear -lwres_context_t *ctx - + lwres_context_t *ctx + - + lwres_result_t lwres_conf_parse -lwres_context_t *ctx -const char *filename - + lwres_context_t *ctx + const char *filename + - + lwres_result_t lwres_conf_print -lwres_context_t *ctx -FILE *fp - + lwres_context_t *ctx + FILE *fp + - + lwres_conf_t * lwres_conf_get -lwres_context_t *ctx - + lwres_context_t *ctx + - + - -DESCRIPTION - -lwres_conf_init() -creates an empty -lwres_conf_t -structure for lightweight resolver context -ctx. - - -lwres_conf_clear() -frees up all the internal memory used by -that -lwres_conf_t -structure in resolver context -ctx. - - -lwres_conf_parse() -opens the file -filename -and parses it to initialise the resolver context -ctx's -lwres_conf_t -structure. - - -lwres_conf_print() -prints the -lwres_conf_t -structure for resolver context -ctx -to the -FILE -fp. - - - + + DESCRIPTION -RETURN VALUES - -lwres_conf_parse() -returns -LWRES_R_SUCCESS -if it successfully read and parsed -filename. -It returns -LWRES_R_FAILURE -if -filename -could not be opened or contained incorrect -resolver statements. - - -lwres_conf_print() -returns -LWRES_R_SUCCESS -unless an error occurred when converting the network addresses to a -numeric host address string. -If this happens, the function returns -LWRES_R_FAILURE. - - - -SEE ALSO - - -stdio3 -, - -resolver5 -. - - -FILES - -/etc/resolv.conf - - - + lwres_conf_init() + creates an empty + lwres_conf_t + structure for lightweight resolver context + ctx. + + + lwres_conf_clear() + frees up all the internal memory used by + that + lwres_conf_t + structure in resolver context + ctx. + + + lwres_conf_parse() + opens the file + filename + and parses it to initialise the resolver context + ctx's + lwres_conf_t + structure. + + + lwres_conf_print() + prints the + lwres_conf_t + structure for resolver context + ctx + to the + FILE + fp. + + + + + RETURN VALUES + + lwres_conf_parse() + returns LWRES_R_SUCCESS + if it successfully read and parsed + filename. + It returns LWRES_R_FAILURE + if filename + could not be opened or contained incorrect + resolver statements. + + + lwres_conf_print() + returns LWRES_R_SUCCESS + unless an error occurred when converting the network addresses to a + numeric host address string. + If this happens, the function returns + LWRES_R_FAILURE. + + + + SEE ALSO + + stdio3 + , + + resolver5 + . + + + + FILES + /etc/resolv.conf + + + diff --git a/lib/lwres/man/lwres_context.docbook b/lib/lwres/man/lwres_context.docbook index 86d01b5b93..cecd036eb4 100644 --- a/lib/lwres/man/lwres_context.docbook +++ b/lib/lwres/man/lwres_context.docbook @@ -1,4 +1,6 @@ - +]> - - - + - + + Jun 30, 2000 + -Jun 30, 2000 - - -lwres_context -3 -BIND9 - - -lwres_context_create -lwres_context_destroy -lwres_context_nextserial -lwres_context_initserial -lwres_context_freemem -lwres_context_allocmem -lwres_context_sendrecv -lightweight resolver context management - - - + + lwres_context + 3 + BIND9 + + + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2003 + Internet Software Consortium + + + + + lwres_context_create + lwres_context_destroy + lwres_context_nextserial + lwres_context_initserial + lwres_context_freemem + lwres_context_allocmem + lwres_context_sendrecv + lightweight resolver context management + + + #include <lwres/lwres.h> - + lwres_result_t lwres_context_create -lwres_context_t **contextp -void *arg -lwres_malloc_t malloc_function -lwres_free_t free_function - + lwres_context_t **contextp + void *arg + lwres_malloc_t malloc_function + lwres_free_t free_function + - + lwres_result_t lwres_context_destroy -lwres_context_t **contextp - + lwres_context_t **contextp + - + void lwres_context_initserial -lwres_context_t *ctx -lwres_uint32_t serial - + lwres_context_t *ctx + lwres_uint32_t serial + - + lwres_uint32_t lwres_context_nextserial -lwres_context_t *ctx - + lwres_context_t *ctx + - + void lwres_context_freemem -lwres_context_t *ctx -void *mem -size_t len - + lwres_context_t *ctx + void *mem + size_t len + - + void lwres_context_allocmem -lwres_context_t *ctx -size_t len - + lwres_context_t *ctx + size_t len + - + void * lwres_context_sendrecv -lwres_context_t *ctx -void *sendbase -int sendlen -void *recvbase -int recvlen -int *recvd_len - + lwres_context_t *ctx + void *sendbase + int sendlen + void *recvbase + int recvlen + int *recvd_len + - - -DESCRIPTION - -lwres_context_create() -creates a -lwres_context_t -structure for use in lightweight resolver operations. -It holds a socket and other data needed for communicating -with a resolver daemon. -The new -lwres_context_t -is returned through -contextp, + + + DESCRIPTION -a pointer to a -lwres_context_t -pointer. This -lwres_context_t -pointer must initially be NULL, and is modified -to point to the newly created -lwres_context_t. + lwres_context_create() + creates a lwres_context_t structure for use in + lightweight resolver operations. It holds a socket and other + data needed for communicating with a resolver daemon. The new + lwres_context_t is returned through + contextp, a pointer to a + lwres_context_t pointer. This + lwres_context_t pointer must initially be NULL, and + is modified to point to the newly created + lwres_context_t. + + + When the lightweight resolver needs to perform dynamic memory + allocation, it will call + malloc_function + to allocate memory and + free_function + to free it. If + malloc_function + and + free_function + are NULL, memory is allocated using + + malloc3 + . + and + + free3 + . - - -When the lightweight resolver needs to perform dynamic memory -allocation, it will call -malloc_function -to allocate memory and -free_function + It is not permitted to have a NULL + malloc_function and a non-NULL + free_function or vice versa. + arg is passed as the first parameter to + the memory allocation functions. If + malloc_function and + free_function are NULL, + arg is unused and should be passed as + NULL. + -to free it. If -malloc_function -and -free_function + + Once memory for the structure has been allocated, + it is initialized using + + lwres_conf_init3 + + and returned via *contextp. + -are NULL, memory is allocated using -.Xr malloc 3 -and - -free3 -. + lwres_context_destroy() + destroys a lwres_context_t, closing its socket. + contextp is a pointer to a pointer to the + context that is to be destroyed. The pointer will be set to + NULL when the context has been destroyed. + -It is not permitted to have a NULL -malloc_function -and a non-NULL -free_function -or vice versa. -arg -is passed as the first parameter to the memory -allocation functions. -If -malloc_function -and -free_function -are NULL, -arg + + The context holds a serial number that is used to identify + resolver request packets and associate responses with the + corresponding requests. This serial number is controlled using + lwres_context_initserial() and + lwres_context_nextserial(). + lwres_context_initserial() sets the serial + number for context *ctx to + serial. + lwres_context_nextserial() increments the + serial number and returns the previous value. + -is unused and should be passed as NULL. - - -Once memory for the structure has been allocated, -it is initialized using - -lwres_conf_init3 - + + Memory for a lightweight resolver context is allocated and freed + using lwres_context_allocmem() and + lwres_context_freemem(). These use + whatever allocations were defined when the context was created + with lwres_context_create(). + lwres_context_allocmem() allocates + len bytes of memory and if successful + returns a pointer to the allocated storage. + lwres_context_freemem() frees + len bytes of space starting at location + mem. + -and returned via -*contextp. + lwres_context_sendrecv() + performs I/O for the context ctx. Data + are read and written from the context's socket. It writes data + from sendbase — typically a + lightweight resolver query packet — and waits for a reply + which is copied to the receive buffer at + recvbase. The number of bytes that were + written to this receive buffer is returned in + *recvd_len. + + - - -lwres_context_destroy() -destroys a -lwres_context_t, + + RETURN VALUES -closing its socket. -contextp -is a pointer to a pointer to the context that is to be destroyed. -The pointer will be set to NULL when the context has been destroyed. - - -The context holds a serial number that is used to identify resolver -request packets and associate responses with the corresponding requests. -This serial number is controlled using -lwres_context_initserial() -and -lwres_context_nextserial(). -lwres_context_initserial() -sets the serial number for context -*ctx -to -serial. + lwres_context_create() + returns LWRES_R_NOMEMORY if memory for + the struct lwres_context could not be allocated, + LWRES_R_SUCCESS otherwise. + + + Successful calls to the memory allocator + lwres_context_allocmem() + return a pointer to the start of the allocated space. + It returns NULL if memory could not be allocated. + + LWRES_R_SUCCESS + is returned when + lwres_context_sendrecv() + completes successfully. + LWRES_R_IOERROR + is returned if an I/O error occurs and + LWRES_R_TIMEOUT + is returned if + lwres_context_sendrecv() + times out waiting for a response. + + + + SEE ALSO + + lwres_conf_init3 + , -lwres_context_nextserial() -increments the serial number and returns the previous value. - - -Memory for a lightweight resolver context is allocated and freed using -lwres_context_allocmem() -and -lwres_context_freemem(). -These use whatever allocations were defined when the context was -created with -lwres_context_create(). -lwres_context_allocmem() -allocates -len -bytes of memory and if successful returns a pointer to the allocated -storage. -lwres_context_freemem() -frees -len -bytes of space starting at location -mem. + + malloc3 + , - - -lwres_context_sendrecv() -performs I/O for the context -ctx. - -Data are read and written from the context's socket. -It writes data from -sendbase -— typically a lightweight resolver query packet — -and waits for a reply which is copied to the receive buffer at -recvbase. - -The number of bytes that were written to this receive buffer is -returned in -*recvd_len. - - - - -RETURN VALUES - -lwres_context_create() -returns -LWRES_R_NOMEMORY -if memory for the -struct lwres_context -could not be allocated, -LWRES_R_SUCCESS -otherwise. - - -Successful calls to the memory allocator -lwres_context_allocmem() -return a pointer to the start of the allocated space. -It returns NULL if memory could not be allocated. - - -LWRES_R_SUCCESS -is returned when -lwres_context_sendrecv() -completes successfully. -LWRES_R_IOERROR -is returned if an I/O error occurs and -LWRES_R_TIMEOUT -is returned if -lwres_context_sendrecv() -times out waiting for a response. - - - -SEE ALSO - - -lwres_conf_init3 -, - - -malloc3 -, - - -free3 - -. - - - + + free3 + . + + + diff --git a/lib/lwres/man/lwres_gabn.docbook b/lib/lwres/man/lwres_gabn.docbook index 0210477e96..3c94d0ad6c 100644 --- a/lib/lwres/man/lwres_gabn.docbook +++ b/lib/lwres/man/lwres_gabn.docbook @@ -1,4 +1,6 @@ - +]> - - - + - + + Jun 30, 2000 + -Jun 30, 2000 - - -lwres_gabn -3 -BIND9 - - -lwres_gabnrequest_render -lwres_gabnresponse_render -lwres_gabnrequest_parse -lwres_gabnresponse_parse -lwres_gabnresponse_free -lwres_gabnrequest_free -lightweight resolver getaddrbyname message handling - - - + + lwres_gabn + 3 + BIND9 + + + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_gabnrequest_render + lwres_gabnresponse_render + lwres_gabnrequest_parse + lwres_gabnresponse_parse + lwres_gabnresponse_free + lwres_gabnrequest_free + lightweight resolver getaddrbyname message handling + + + #include <lwres/lwres.h> - + lwres_result_t lwres_gabnrequest_render -lwres_context_t *ctx -lwres_gabnrequest_t *req -lwres_lwpacket_t *pkt -lwres_buffer_t *b - + lwres_context_t *ctx + lwres_gabnrequest_t *req + lwres_lwpacket_t *pkt + lwres_buffer_t *b + - + lwres_result_t lwres_gabnresponse_render -lwres_context_t *ctx -lwres_gabnresponse_t *req -lwres_lwpacket_t *pkt -lwres_buffer_t *b - + lwres_context_t *ctx + lwres_gabnresponse_t *req + lwres_lwpacket_t *pkt + lwres_buffer_t *b + - + lwres_result_t lwres_gabnrequest_parse -lwres_context_t *ctx -lwres_buffer_t *b -lwres_lwpacket_t *pkt -lwres_gabnrequest_t **structp - + lwres_context_t *ctx + lwres_buffer_t *b + lwres_lwpacket_t *pkt + lwres_gabnrequest_t **structp + - + lwres_result_t lwres_gabnresponse_parse -lwres_context_t *ctx -lwres_buffer_t *b -lwres_lwpacket_t *pkt -lwres_gabnresponse_t **structp - + lwres_context_t *ctx + lwres_buffer_t *b + lwres_lwpacket_t *pkt + lwres_gabnresponse_t **structp + - + void lwres_gabnresponse_free -lwres_context_t *ctx -lwres_gabnresponse_t **structp - + lwres_context_t *ctx + lwres_gabnresponse_t **structp + - + void lwres_gabnrequest_free -lwres_context_t *ctx -lwres_gabnrequest_t **structp - + lwres_context_t *ctx + lwres_gabnrequest_t **structp + - - -DESCRIPTION - -These are low-level routines for creating and parsing -lightweight resolver name-to-address lookup request and -response messages. - -There are four main functions for the getaddrbyname opcode. -One render function converts a getaddrbyname request structure — -lwres_gabnrequest_t — -to the lighweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a getaddrbyname request structure. -Another render function converts the getaddrbyname response structure — -lwres_gabnresponse_t — -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a getaddrbyname response structure. - - -These structures are defined in -<lwres/lwres.h>. -They are shown below. - + + + DESCRIPTION + + These are low-level routines for creating and parsing + lightweight resolver name-to-address lookup request and + response messages. + + + There are four main functions for the getaddrbyname opcode. + One render function converts a getaddrbyname request structure — + lwres_gabnrequest_t — + to the lighweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a getaddrbyname request structure. + Another render function converts the getaddrbyname response structure + — lwres_gabnresponse_t — + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a getaddrbyname response structure. + + + These structures are defined in + <lwres/lwres.h>. + They are shown below. + + #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U - + + + typedef struct lwres_addr lwres_addr_t; typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; - + + + typedef struct { lwres_uint32_t flags; lwres_uint32_t addrtypes; lwres_uint16_t namelen; char *name; } lwres_gabnrequest_t; - + + + typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -142,114 +164,95 @@ typedef struct { size_t baselen; } lwres_gabnresponse_t; - - -lwres_gabnrequest_render() -uses resolver context -ctx -to convert getaddrbyname request structure -req -to canonical format. -The packet header structure -pkt -is initialised and transferred to -buffer -b. + -The contents of -*req -are then appended to the buffer in canonical format. -lwres_gabnresponse_render() -performs the same task, except it converts a getaddrbyname response structure -lwres_gabnresponse_t -to the lightweight resolver's canonical format. - - -lwres_gabnrequest_parse() -uses context -ctx -to convert the contents of packet -pkt -to a -lwres_gabnrequest_t -structure. -Buffer -b -provides space to be used for storing this structure. -When the function succeeds, the resulting -lwres_gabnrequest_t -is made available through -*structp. + lwres_gabnrequest_render() + uses resolver context ctx to convert + getaddrbyname request structure req to + canonical format. The packet header structure + pkt is initialised and transferred to + buffer b. -lwres_gabnresponse_parse() -offers the same semantics as -lwres_gabnrequest_parse() -except it yields a -lwres_gabnresponse_t -structure. - - -lwres_gabnresponse_free() -and -lwres_gabnrequest_free() -release the memory in resolver context -ctx -that was allocated to the -lwres_gabnresponse_t -or -lwres_gabnrequest_t -structures referenced via -structp. + The contents of *req are then appended to + the buffer in canonical format. + lwres_gabnresponse_render() performs the + same task, except it converts a getaddrbyname response structure + lwres_gabnresponse_t to the lightweight resolver's + canonical format. + -Any memory associated with ancillary buffers and strings for those -structures is also discarded. - - - -RETURN VALUES - -The getaddrbyname opcode functions -lwres_gabnrequest_render(), -lwres_gabnresponse_render() -lwres_gabnrequest_parse() -and -lwres_gabnresponse_parse() -all return -LWRES_R_SUCCESS -on success. -They return -LWRES_R_NOMEMORY -if memory allocation fails. -LWRES_R_UNEXPECTEDEND -is returned if the available space in the buffer -b -is too small to accommodate the packet header or the -lwres_gabnrequest_t -and -lwres_gabnresponse_t -structures. -lwres_gabnrequest_parse() -and -lwres_gabnresponse_parse() -will return -LWRES_R_UNEXPECTEDEND -if the buffer is not empty after decoding the received packet. -These functions will return -LWRES_R_FAILURE -if -pktflags -in the packet header structure -lwres_lwpacket_t -indicate that the packet is not a response to an earlier query. - - - -SEE ALSO - - -lwres_packet3 - - - - - + lwres_gabnrequest_parse() + uses context ctx to convert the contents + of packet pkt to a + lwres_gabnrequest_t structure. Buffer + b provides space to be used for storing + this structure. When the function succeeds, the resulting + lwres_gabnrequest_t is made available through + *structp. + + lwres_gabnresponse_parse() offers the same + semantics as lwres_gabnrequest_parse() + except it yields a lwres_gabnresponse_t structure. + + + lwres_gabnresponse_free() + and lwres_gabnrequest_free() release the + memory in resolver context ctx that was + allocated to the lwres_gabnresponse_t or + lwres_gabnrequest_t structures referenced via + structp. + + Any memory associated with ancillary buffers and strings for + those structures is also discarded. + + + + RETURN VALUES + + The getaddrbyname opcode functions + lwres_gabnrequest_render(), + lwres_gabnresponse_render() + lwres_gabnrequest_parse() + and + lwres_gabnresponse_parse() + all return + LWRES_R_SUCCESS + on success. + They return + LWRES_R_NOMEMORY + if memory allocation fails. + LWRES_R_UNEXPECTEDEND + is returned if the available space in the buffer + b + is too small to accommodate the packet header or the + lwres_gabnrequest_t + and + lwres_gabnresponse_t + structures. + lwres_gabnrequest_parse() + and + lwres_gabnresponse_parse() + will return + LWRES_R_UNEXPECTEDEND + if the buffer is not empty after decoding the received packet. + These functions will return + LWRES_R_FAILURE + if + pktflags + in the packet header structure + lwres_lwpacket_t + indicate that the packet is not a response to an earlier query. + + + + SEE ALSO + + lwres_packet3 + + + + diff --git a/lib/lwres/man/lwres_gai_strerror.docbook b/lib/lwres/man/lwres_gai_strerror.docbook index 3af224cc58..c75a484a7b 100644 --- a/lib/lwres/man/lwres_gai_strerror.docbook +++ b/lib/lwres/man/lwres_gai_strerror.docbook @@ -1,4 +1,6 @@ - +]> - - - + - + + Jun 30, 2000 + -Jun 30, 2000 - - -lwres_gai_strerror -3 -BIND9 - - -gai_strerror -print suitable error string - - - + + lwres_gai_strerror + 3 + BIND9 + + + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_gai_strerror + print suitable error string + + + + #include <lwres/netdb.h> - + char * gai_strerror -int ecode - + int ecode + - + - -DESCRIPTION - -lwres_gai_strerror() -returns an error message corresponding to an error code returned by -getaddrinfo(). -The following error codes and their meaning are defined in -include/lwres/netdb.h. - -EAI_ADDRFAMILY - - -address family for hostname not supported - - -EAI_AGAIN - - -temporary failure in name resolution - - -EAI_BADFLAGS - - -invalid value for -ai_flags - - -EAI_FAIL - - -non-recoverable failure in name resolution - - -EAI_FAMILY - - -ai_family not supported - - -EAI_MEMORY - - -memory allocation failure - - -EAI_NODATA - - -no address associated with hostname - - -EAI_NONAME - - -hostname or servname not provided, or not known - - -EAI_SERVICE - - -servname not supported for ai_socktype - - -EAI_SOCKTYPE - - -ai_socktype not supported - - -EAI_SYSTEM - - -system error returned in errno - - - -The message invalid error code is returned if -ecode -is out of range. - - -ai_flags, -ai_family -and -ai_socktype -are elements of the -struct addrinfo -used by -lwres_getaddrinfo(). - - + + DESCRIPTION - -SEE ALSO - - -strerror3 -, + lwres_gai_strerror() + returns an error message corresponding to an error code returned by + getaddrinfo(). + The following error codes and their meaning are defined in + include/lwres/netdb.h. + + + EAI_ADDRFAMILY + + + address family for hostname not supported + + + + + EAI_AGAIN + + + temporary failure in name resolution + + + + + EAI_BADFLAGS + + + invalid value for + ai_flags + + + + + EAI_FAIL + + + non-recoverable failure in name resolution + + + + + EAI_FAMILY + + ai_family not supported + + + + + EAI_MEMORY + + + memory allocation failure + + + + + EAI_NODATA + + + no address associated with hostname + + + + + EAI_NONAME + + + hostname or servname not provided, or not known + + + + + EAI_SERVICE + + + servname not supported for ai_socktype + + + + + EAI_SOCKTYPE + + ai_socktype not supported + + + + + EAI_SYSTEM + + + system error returned in errno + + + + + The message invalid error code is returned if + ecode + is out of range. + + ai_flags, + ai_family + and + ai_socktype + are elements of the + struct addrinfo + used by + lwres_getaddrinfo(). + + - -lwres_getaddrinfo3 -, + + SEE ALSO + + strerror3 + , - -getaddrinfo3 -, + + lwres_getaddrinfo3 + , - -RFC2133 -. - - - + + getaddrinfo3 + , + + + RFC2133 + . + + + diff --git a/lib/lwres/man/lwres_getaddrinfo.docbook b/lib/lwres/man/lwres_getaddrinfo.docbook index 166a61ee06..6034a662c6 100644 --- a/lib/lwres/man/lwres_getaddrinfo.docbook +++ b/lib/lwres/man/lwres_getaddrinfo.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_getaddrinfo -3 -BIND9 - + + lwres_getaddrinfo + 3 + BIND9 + - -lwres_getaddrinfo -lwres_freeaddrinfo -socket address structure to host and service name - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2003 + Internet Software Consortium + + + + + lwres_getaddrinfo + lwres_freeaddrinfo + socket address structure to host and service name + + + #include <lwres/netdb.h> - + int lwres_getaddrinfo -const char *hostname -const char *servname -const struct addrinfo *hints -struct addrinfo **res - + const char *hostname + const char *servname + const struct addrinfo *hints + struct addrinfo **res + - + void lwres_freeaddrinfo -struct addrinfo *ai - + struct addrinfo *ai + - -If the operating system does not provide a -struct addrinfo, -the following structure is used: - - + + If the operating system does not provide a + struct addrinfo, + the following structure is used: + + struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ int ai_family; /* PF_xxx */ @@ -72,301 +86,300 @@ struct addrinfo { struct addrinfo *ai_next; /* next structure in linked list */ }; - + - + - -DESCRIPTION - -lwres_getaddrinfo() -is used to get a list of IP addresses and port numbers for host -hostname -and service -servname. + + DESCRIPTION -The function is the lightweight resolver's implementation of -getaddrinfo() -as defined in RFC2133. -hostname -and -servname -are pointers to null-terminated -strings or -NULL. + lwres_getaddrinfo() + is used to get a list of IP addresses and port numbers for host + hostname and service + servname. -hostname -is either a host name or a numeric host address string: a dotted decimal -IPv4 address or an IPv6 address. -servname -is either a decimal port number or a service name as listed in -/etc/services. - + The function is the lightweight resolver's implementation of + getaddrinfo() as defined in RFC2133. + hostname and + servname are pointers to null-terminated + strings or NULL. - -hints -is an optional pointer to a -struct addrinfo. -This structure can be used to provide hints concerning the type of socket -that the caller supports or wishes to use. -The caller can supply the following structure elements in -*hints: + hostname is either a host name or a + numeric host address string: a dotted decimal IPv4 address or an + IPv6 address. servname is either a + decimal port number or a service name as listed in + /etc/services. + - -ai_family - -The protocol family that should be used. -When -ai_family -is set to -PF_UNSPEC, -it means the caller will accept any protocol family supported by the -operating system. - -ai_socktype - - -denotes the type of socket — -SOCK_STREAM, -SOCK_DGRAM -or -SOCK_RAW -— that is wanted. -When -ai_socktype -is zero the caller will accept any socket type. - - - -ai_protocol - - -indicates which transport protocol is wanted: IPPROTO_UDP or -IPPROTO_TCP. -If -ai_protocol -is zero the caller will accept any protocol. - - - -ai_flags - - -Flag bits. -If the -AI_CANONNAME -bit is set, a successful call to -lwres_getaddrinfo() -will return a null-terminated string containing the canonical name -of the specified hostname in -ai_canonname -of the first -addrinfo -structure returned. -Setting the -AI_PASSIVE -bit indicates that the returned socket address structure is intended -for used in a call to - -bind2 -. + hints + is an optional pointer to a + struct addrinfo. + This structure can be used to provide hints concerning the type of + socket + that the caller supports or wishes to use. + The caller can supply the following structure elements in + *hints: -In this case, if the hostname argument is a -NULL -pointer, then the IP address portion of the socket -address structure will be set to -INADDR_ANY -for an IPv4 address or -IN6ADDR_ANY_INIT -for an IPv6 address. - - -When -ai_flags -does not set the -AI_PASSIVE -bit, the returned socket address structure will be ready -for use in a call to - -connect2 - - -for a connection-oriented protocol or - -connect2 -, + + + ai_family + + + The protocol family that should be used. + When + ai_family + is set to + PF_UNSPEC, + it means the caller will accept any protocol family supported by + the + operating system. + + + + + ai_socktype + + + denotes the type of socket — + SOCK_STREAM, + SOCK_DGRAM + or + SOCK_RAW + — that is wanted. + When + ai_socktype + is zero the caller will accept any socket type. + + + + + ai_protocol + + + indicates which transport protocol is wanted: IPPROTO_UDP or + IPPROTO_TCP. + If + ai_protocol + is zero the caller will accept any protocol. + + + + + ai_flags + + + Flag bits. + If the + AI_CANONNAME + bit is set, a successful call to + lwres_getaddrinfo() + will return a null-terminated string containing the canonical + name + of the specified hostname in + ai_canonname + of the first + addrinfo + structure returned. + Setting the + AI_PASSIVE + bit indicates that the returned socket address structure is + intended + for used in a call to + + bind2 + . - -sendto2 -, + In this case, if the hostname argument is a + NULL + pointer, then the IP address portion of the socket + address structure will be set to + INADDR_ANY + for an IPv4 address or + IN6ADDR_ANY_INIT + for an IPv6 address. + + + When + ai_flags + does not set the + AI_PASSIVE + bit, the returned socket address structure will be ready + for use in a call to + + connect2 + + for a connection-oriented protocol or + + connect2 + , -or - -sendmsg2 - - -if a connectionless protocol was chosen. -The IP address portion of the socket address structure will be -set to the loopback address if -hostname -is a -NULL -pointer and -AI_PASSIVE -is not set in -ai_flags. - - -If -ai_flags -is set to -AI_NUMERICHOST -it indicates that -hostname -should be treated as a numeric string defining an IPv4 or IPv6 address -and no name resolution should be attempted. - - - - - + + sendto2 + , - -All other elements of the struct addrinfo passed -via hints must be zero. - + or + + sendmsg2 + + if a connectionless protocol was chosen. + The IP address portion of the socket address structure will be + set to the loopback address if + hostname + is a + NULL + pointer and + AI_PASSIVE + is not set in + ai_flags. + + + If + ai_flags + is set to + AI_NUMERICHOST + it indicates that + hostname + should be treated as a numeric string defining an IPv4 or IPv6 + address + and no name resolution should be attempted. + + + + + - -A hints of NULL is treated as if -the caller provided a struct addrinfo initialized to zero -with ai_familyset to -PF_UNSPEC. - + + All other elements of the struct addrinfo passed + via hints must be zero. + - -After a successful call to -lwres_getaddrinfo(), -*res -is a pointer to a linked list of one or more -addrinfo -structures. -Each -struct addrinfo -in this list cn be processed by following -the -ai_next -pointer, until a -NULL -pointer is encountered. -The three members -ai_family, -ai_socktype, -and -ai_protocol -in each -returned -addrinfo -structure contain the corresponding arguments for a call to - -socket2 -. -For each -addrinfo -structure in the list, the -ai_addr -member points to a filled-in socket address structure of length -ai_addrlen. - + + A hints of NULL is + treated as if + the caller provided a struct addrinfo initialized to zero + with ai_familyset to + PF_UNSPEC. + - -All of the information returned by -lwres_getaddrinfo() -is dynamically allocated: the addrinfo structures, and the socket -address structures and canonical host name strings pointed to by the -addrinfostructures. -Memory allocated for the dynamically allocated structures created by -a successful call to -lwres_getaddrinfo() -is released by -lwres_freeaddrinfo(). -ai -is a pointer to a -struct addrinfo -created by a call to -lwres_getaddrinfo(). - + + After a successful call to + lwres_getaddrinfo(), + *res + is a pointer to a linked list of one or more + addrinfo + structures. + Each + struct addrinfo + in this list cn be processed by following + the + ai_next + pointer, until a + NULL + pointer is encountered. + The three members + ai_family, + ai_socktype, + and + ai_protocol + in each + returned + addrinfo + structure contain the corresponding arguments for a call to + + socket2 + . + For each + addrinfo + structure in the list, the + ai_addr + member points to a filled-in socket address structure of length + ai_addrlen. + - + + All of the information returned by + lwres_getaddrinfo() + is dynamically allocated: the addrinfo structures, and the socket + address structures and canonical host name strings pointed to by the + addrinfostructures. + Memory allocated for the dynamically allocated structures created by + a successful call to + lwres_getaddrinfo() + is released by + lwres_freeaddrinfo(). + ai + is a pointer to a + struct addrinfo + created by a call to + lwres_getaddrinfo(). + - -RETURN VALUES - -lwres_getaddrinfo() -returns zero on success or one of the error codes listed in - -gai_strerror3 - - -if an error occurs. -If both -hostname -and -servname -are -NULL -lwres_getaddrinfo() -returns -EAI_NONAME. + - - - -SEE ALSO - - -lwres3 -, + + RETURN VALUES - -lwres_getaddrinfo3 -, + lwres_getaddrinfo() + returns zero on success or one of the error codes listed in + + gai_strerror3 + + if an error occurs. If both hostname and + servname are NULL + lwres_getaddrinfo() returns + EAI_NONAME. + + + + SEE ALSO + + lwres3 + , - -lwres_freeaddrinfo3 -, + + lwres_getaddrinfo3 + , - -lwres_gai_strerror3 -, + + lwres_freeaddrinfo3 + , - -RFC2133 -, + + lwres_gai_strerror3 + , - -getservbyname3 -, + + RFC2133 + , - -bind2 -, + + getservbyname3 + , - -connect2 -, + + bind2 + , - -sendto2 -, + + connect2 + , - -sendmsg2 -, + + sendto2 + , - -socket2 -. - + + sendmsg2 + , - - + + socket2 + . + + + + diff --git a/lib/lwres/man/lwres_gethostent.docbook b/lib/lwres/man/lwres_gethostent.docbook index de8f35156c..109e55cd43 100644 --- a/lib/lwres/man/lwres_gethostent.docbook +++ b/lib/lwres/man/lwres_gethostent.docbook @@ -1,6 +1,8 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_gethostent -3 -BIND9 - + + lwres_gethostent + 3 + BIND9 + - -lwres_gethostbyname -lwres_gethostbyname2 -lwres_gethostbyaddr -lwres_gethostent -lwres_sethostent -lwres_endhostent -lwres_gethostbyname_r -lwres_gethostbyaddr_r -lwres_gethostent_r -lwres_sethostent_r -lwres_endhostent_r -lightweight resolver get network host entry - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2001 + Internet Software Consortium + + + + + lwres_gethostbyname + lwres_gethostbyname2 + lwres_gethostbyaddr + lwres_gethostent + lwres_sethostent + lwres_endhostent + lwres_gethostbyname_r + lwres_gethostbyaddr_r + lwres_gethostent_r + lwres_sethostent_r + lwres_endhostent_r + lightweight resolver get network host entry + + + #include <lwres/netdb.h> - + struct hostent * lwres_gethostbyname -const char *name - + const char *name + - + struct hostent * lwres_gethostbyname2 -const char *name -int af - + const char *name + int af + - + struct hostent * lwres_gethostbyaddr -const char *addr -int len -int type - + const char *addr + int len + int type + - + struct hostent * lwres_gethostent -void - + void + - + void lwres_sethostent -int stayopen - + int stayopen + - + void lwres_endhostent -void - + void + - + struct hostent * lwres_gethostbyname_r -const char *name -struct hostent *resbuf -char *buf -int buflen -int *error - + const char *name + struct hostent *resbuf + char *buf + int buflen + int *error + - + struct hostent * lwres_gethostbyaddr_r -const char *addr -int len -int type -struct hostent *resbuf -char *buf -int buflen -int *error - + const char *addr + int len + int type + struct hostent *resbuf + char *buf + int buflen + int *error + - + struct hostent * lwres_gethostent_r -struct hostent *resbuf -char *buf -int buflen -int *error - + struct hostent *resbuf + char *buf + int buflen + int *error + - + void lwres_sethostent_r -int stayopen - + int stayopen + - + void lwres_endhostent_r -void - + void + - + - -DESCRIPTION - -These functions provide hostname-to-address and -address-to-hostname lookups by means of the lightweight resolver. -They are similar to the standard - -gethostent3 - - -functions provided by most operating systems. -They use a -struct hostent -which is usually defined in -<namedb.h>. - - + + DESCRIPTION + + These functions provide hostname-to-address and + address-to-hostname lookups by means of the lightweight resolver. + They are similar to the standard + + gethostent3 + + functions provided by most operating systems. + They use a + struct hostent + which is usually defined in + <namedb.h>. + + struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ @@ -158,250 +169,269 @@ struct hostent { }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ - - -The members of this structure are: - -h_name - - -The official (canonical) name of the host. - - -h_aliases - - -A NULL-terminated array of alternate names (nicknames) for the host. - - -h_addrtype - - -The type of address being returned — -PF_INET -or -PF_INET6. - - -h_length - - -The length of the address in bytes. - - -h_addr_list - - -A NULL -terminated array of network addresses for the host. -Host addresses are returned in network byte order. - - - - - -For backward compatibility with very old software, -h_addr -is the first address in -h_addr_list. - - -lwres_gethostent(), -lwres_sethostent(), -lwres_endhostent(), -lwres_gethostent_r(), -lwres_sethostent_r() -and -lwres_endhostent_r() -provide iteration over the known host entries on systems that -provide such functionality through facilities like -/etc/hosts -or NIS. The lightweight resolver does not currently implement -these functions; it only provides them as stub functions that always -return failure. - + + + The members of this structure are: + + + h_name + + + The official (canonical) name of the host. + + + + + h_aliases + + + A NULL-terminated array of alternate names (nicknames) for the + host. + + + + + h_addrtype + + + The type of address being returned — + PF_INET + or + PF_INET6. + + + + + h_length + + + The length of the address in bytes. + + + + + h_addr_list + + + A NULL + terminated array of network addresses for the host. + Host addresses are returned in network byte order. + + + + + + + For backward compatibility with very old software, + h_addr + is the first address in + h_addr_list. + + lwres_gethostent(), + lwres_sethostent(), + lwres_endhostent(), + lwres_gethostent_r(), + lwres_sethostent_r() + and + lwres_endhostent_r() + provide iteration over the known host entries on systems that + provide such functionality through facilities like + /etc/hosts + or NIS. The lightweight resolver does not currently implement + these functions; it only provides them as stub functions that always + return failure. + - -lwres_gethostbyname() and -lwres_gethostbyname2() look up the hostname -name. -lwres_gethostbyname() always looks for an IPv4 -address while lwres_gethostbyname2() looks for an -address of protocol family af: either -PF_INET or PF_INET6 — IPv4 or IPV6 -addresses respectively. Successful calls of the functions return a -struct hostentfor the name that was looked up. -NULL is returned if the lookups by -lwres_gethostbyname() or -lwres_gethostbyname2() fail. - + lwres_gethostbyname() + and lwres_gethostbyname2() look up the + hostname name. + lwres_gethostbyname() always looks for an + IPv4 address while lwres_gethostbyname2() + looks for an address of protocol family + af: either PF_INET or + PF_INET6 — IPv4 or IPV6 addresses + respectively. Successful calls of the functions return a + struct hostentfor the name that was looked up. + NULL is returned if the lookups by + lwres_gethostbyname() or + lwres_gethostbyname2() fail. + - -Reverse lookups of addresses are performed by -lwres_gethostbyaddr(). -addr is an address of length -len bytes and protocol family -type — PF_INET or -PF_INET6. -lwres_gethostbyname_r() is a thread-safe function -for forward lookups. If an error occurs, an error code is returned in -*error. -resbuf is a pointer to a struct -hostent which is initialised by a successful call to -lwres_gethostbyname_r() . -buf is a buffer of length -len bytes which is used to store the -h_name, h_aliases, and -h_addr_list elements of the struct -hostent returned in resbuf. -Successful calls to lwres_gethostbyname_r() -return resbuf, -which is a pointer to the struct hostent it created. - + + Reverse lookups of addresses are performed by + lwres_gethostbyaddr(). + addr is an address of length + len bytes and protocol family + type — PF_INET or + PF_INET6. + lwres_gethostbyname_r() is a + thread-safe function + for forward lookups. If an error occurs, an error code is returned in + *error. + resbuf is a pointer to a + struct hostent which is initialised by a successful call to + lwres_gethostbyname_r(). + buf is a buffer of length + len bytes which is used to store the + h_name, h_aliases, and + h_addr_list elements of the + struct hostent returned in resbuf. + Successful calls to lwres_gethostbyname_r() + return resbuf, + which is a pointer to the struct hostent it created. + - -lwres_gethostbyaddr_r() is a thread-safe function -that performs a reverse lookup of address addr -which is len bytes long and is of protocol -family type — PF_INET or -PF_INET6. If an error occurs, the error code is returned -in *error. The other function parameters are -identical to those in lwres_gethostbyname_r(). -resbuf is a pointer to a struct -hostent which is initialised by a successful call to -lwres_gethostbyaddr_r(). -buf is a buffer of length -len bytes which is used to store the -h_name, h_aliases, and -h_addr_list elements of the struct -hostent returned in resbuf. Successful -calls to lwres_gethostbyaddr_r() return -resbuf, which is a pointer to the -struct hostent() it created. - + lwres_gethostbyaddr_r() + is a thread-safe function + that performs a reverse lookup of address addr + which is len bytes long and is of + protocol + family type — PF_INET or + PF_INET6. If an error occurs, the error code is returned + in *error. The other function + parameters are + identical to those in lwres_gethostbyname_r(). + resbuf is a pointer to a + struct hostent which is initialised by a successful call to + lwres_gethostbyaddr_r(). + buf is a buffer of length + len bytes which is used to store the + h_name, h_aliases, and + h_addr_list elements of the + struct hostent returned in resbuf. + Successful calls to lwres_gethostbyaddr_r() return + resbuf, which is a pointer to the + struct hostent() it created. + - + - -RETURN VALUES - -The functions -lwres_gethostbyname(), -lwres_gethostbyname2(), -lwres_gethostbyaddr(), -and -lwres_gethostent() -return NULL to indicate an error. In this case the global variable -lwres_h_errno -will contain one of the following error codes defined in -<lwres/netdb.h>: + + RETURN VALUES + + The functions + lwres_gethostbyname(), + lwres_gethostbyname2(), + lwres_gethostbyaddr(), + and + lwres_gethostent() + return NULL to indicate an error. In this case the global variable + lwres_h_errno + will contain one of the following error codes defined in + <lwres/netdb.h>: - -HOST_NOT_FOUND - - -The host or address was not found. - - -TRY_AGAIN - - -A recoverable error occurred, e.g., a timeout. -Retrying the lookup may succeed. - - -NO_RECOVERY - - -A non-recoverable error occurred. - - -NO_DATA - - -The name exists, but has no address information -associated with it (or vice versa in the case -of a reverse lookup). The code NO_ADDRESS -is accepted as a synonym for NO_DATA for backwards -compatibility. - - - - + + + HOST_NOT_FOUND + + + The host or address was not found. + + + + + TRY_AGAIN + + + A recoverable error occurred, e.g., a timeout. + Retrying the lookup may succeed. + + + + + NO_RECOVERY + + + A non-recoverable error occurred. + + + + + NO_DATA + + + The name exists, but has no address information + associated with it (or vice versa in the case + of a reverse lookup). The code NO_ADDRESS + is accepted as a synonym for NO_DATA for backwards + compatibility. + + + + + - - -lwres_hstrerror3 - - -translates these error codes to suitable error messages. - + + lwres_hstrerror3 + + translates these error codes to suitable error messages. + - -lwres_gethostent() -and -lwres_gethostent_r() -always return -NULL. - + lwres_gethostent() + and lwres_gethostent_r() + always return NULL. + - -Successful calls to lwres_gethostbyname_r() and -lwres_gethostbyaddr_r() return -resbuf, a pointer to the struct -hostent that was initialised by these functions. They return -NULL if the lookups fail or if buf -was too small to hold the list of addresses and names referenced by -the h_name, h_aliases, and -h_addr_list elements of the struct -hostent. If buf was too small, both -lwres_gethostbyname_r() and -lwres_gethostbyaddr_r() set the global variable -errno to ERANGE. - + + Successful calls to lwres_gethostbyname_r() and + lwres_gethostbyaddr_r() return + resbuf, a pointer to the + struct hostent that was initialised by these functions. They return + NULL if the lookups fail or if buf + was too small to hold the list of addresses and names referenced by + the h_name, h_aliases, and + h_addr_list elements of the + struct hostent. + If buf was too small, both + lwres_gethostbyname_r() and + lwres_gethostbyaddr_r() set the global + variable + errno to ERANGE. + - - -SEE ALSO - - -gethostent3 -, + + + SEE ALSO + + gethostent3 + , - -lwres_getipnode3 -, + + lwres_getipnode3 + , - -lwres_hstrerror3 - - - - + + lwres_hstrerror3 + + + - -BUGS - -lwres_gethostbyname(), -lwres_gethostbyname2(), -lwres_gethostbyaddr() -and -lwres_endhostent() -are not thread safe; they return pointers to static data and -provide error codes through a global variable. -Thread-safe versions for name and address lookup are provided by -lwres_gethostbyname_r(), -and -lwres_gethostbyaddr_r() -respectively. - - -The resolver daemon does not currently support any non-DNS -name services such as -/etc/hosts -or -NIS, -consequently the above functions don't, either. - - - + + BUGS + lwres_gethostbyname(), + lwres_gethostbyname2(), + lwres_gethostbyaddr() + and + lwres_endhostent() + are not thread safe; they return pointers to static data and + provide error codes through a global variable. + Thread-safe versions for name and address lookup are provided by + lwres_gethostbyname_r(), + and + lwres_gethostbyaddr_r() + respectively. + + + The resolver daemon does not currently support any non-DNS + name services such as + /etc/hosts + or + NIS, + consequently the above functions don't, either. + + + diff --git a/lib/lwres/man/lwres_getipnode.docbook b/lib/lwres/man/lwres_getipnode.docbook index 5225e5a830..8edfe752dc 100644 --- a/lib/lwres/man/lwres_getipnode.docbook +++ b/lib/lwres/man/lwres_getipnode.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_getipnode -3 -BIND9 - + + lwres_getipnode + 3 + BIND9 + - -lwres_getipnodebyname -lwres_getipnodebyaddr -lwres_freehostent -lightweight resolver nodename / address translation API - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + 2003 + Internet Software Consortium + + + + + lwres_getipnodebyname + lwres_getipnodebyaddr + lwres_freehostent + lightweight resolver nodename / address translation API + + + #include <lwres/netdb.h> - + struct hostent * lwres_getipnodebyname -const char *name -int af -int flags -int *error_num - + const char *name + int af + int flags + int *error_num + - + struct hostent * lwres_getipnodebyaddr -const void *src -size_t len -int af -int *error_num - + const void *src + size_t len + int af + int *error_num + - + void lwres_freehostent -struct hostent *he - + struct hostent *he + - + - -DESCRIPTION + + DESCRIPTION - -These functions perform thread safe, protocol independent -nodename-to-address and address-to-nodename -translation as defined in RFC2553. - + + These functions perform thread safe, protocol independent + nodename-to-address and address-to-nodename + translation as defined in RFC2553. + - -They use a -struct hostent -which is defined in -namedb.h: - + + They use a + struct hostent + which is defined in + namedb.h: + + struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ @@ -90,218 +105,225 @@ struct hostent { }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ - + - -The members of this structure are: - -h_name - - -The official (canonical) name of the host. - - -h_aliases - - -A NULL-terminated array of alternate names (nicknames) for the host. - - -h_addrtype - - -The type of address being returned - usually -PF_INET -or -PF_INET6. + + The members of this structure are: + + + h_name + + + The official (canonical) name of the host. + + + + + h_aliases + + + A NULL-terminated array of alternate names (nicknames) for the + host. + + + + + h_addrtype + + + The type of address being returned - usually + PF_INET + or + PF_INET6. - - -h_length - - -The length of the address in bytes. - - -h_addr_list - - -A -NULL -terminated array of network addresses for the host. -Host addresses are returned in network byte order. - - - - - -lwres_getipnodebyname() -looks up addresses of protocol family -af + + + + + h_length + + + The length of the address in bytes. + + + + + h_addr_list + + + A + NULL + terminated array of network addresses for the host. + Host addresses are returned in network byte order. + + + + + -for the hostname -name. + lwres_getipnodebyname() + looks up addresses of protocol family af + for the hostname name. The + flags parameter contains ORed flag bits + to specify the types of addresses that are searched for, and the + types of addresses that are returned. The flag bits are: -The -flags -parameter contains ORed flag bits to -specify the types of addresses that are searched -for, and the types of addresses that are returned. -The flag bits are: - -AI_V4MAPPED - - -This is used with an -af -of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped -IPv6 addresses. - - -AI_ALL - - -This is used with an -af -of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned. -If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped -IPv6 addresses. - - -AI_ADDRCONFIG - - -Only return an IPv6 or IPv4 address if here is an active network -interface of that type. This is not currently implemented -in the BIND 9 lightweight resolver, and the flag is ignored. - - -AI_DEFAULT - - -This default sets the -AI_V4MAPPED -and -AI_ADDRCONFIG -flag bits. - - - - - -lwres_getipnodebyaddr() -performs a reverse lookup -of address -src -which is -len -bytes long. -af -denotes the protocol family, typically -PF_INET -or -PF_INET6. + + + AI_V4MAPPED + + + This is used with an + af + of AF_INET6, and causes IPv4 addresses to be returned as + IPv4-mapped + IPv6 addresses. + + + + + AI_ALL + + + This is used with an + af + of AF_INET6, and causes all known addresses (IPv6 and IPv4) to + be returned. + If AI_V4MAPPED is also set, the IPv4 addresses are return as + mapped + IPv6 addresses. + + + + + AI_ADDRCONFIG + + + Only return an IPv6 or IPv4 address if here is an active network + interface of that type. This is not currently implemented + in the BIND 9 lightweight resolver, and the flag is ignored. + + + + + AI_DEFAULT + + + This default sets the + AI_V4MAPPED + and + AI_ADDRCONFIG + flag bits. + + + + + - - -lwres_freehostent() -releases all the memory associated with -the -struct hostent -pointer -he. + lwres_getipnodebyaddr() + performs a reverse lookup of address src + which is len bytes long. + af denotes the protocol family, typically + PF_INET or PF_INET6. + + lwres_freehostent() + releases all the memory associated with the struct + hostent pointer he. Any memory + allocated for the h_name, + h_addr_list and + h_aliases is freed, as is the memory for + the hostent structure itself. + + + + RETURN VALUES + + If an error occurs, + lwres_getipnodebyname() + and + lwres_getipnodebyaddr() + set + *error_num + to an appropriate error code and the function returns a + NULL + pointer. + The error codes and their meanings are defined in + <lwres/netdb.h>: + + + HOST_NOT_FOUND + + + No such host is known. + + + + + NO_ADDRESS + + + The server recognised the request and the name but no address is + available. Another type of request to the name server for the + domain might return an answer. + + + + + TRY_AGAIN + + + A temporary and possibly transient error occurred, such as a + failure of a server to respond. The request may succeed if + retried. + + + + + NO_RECOVERY + + + An unexpected failure occurred, and retrying the request + is pointless. + + + + + + + lwres_hstrerror3 + + translates these error codes to suitable error messages. + + + + SEE ALSO + + RFC2553 + , -Any memory allocated for the -h_name, + + lwres3 + , -h_addr_list -and -h_aliases -is freed, as is the memory for the -hostent -structure itself. - - - -RETURN VALUES - -If an error occurs, -lwres_getipnodebyname() -and -lwres_getipnodebyaddr() -set -*error_num -to an appropriate error code and the function returns a -NULL -pointer. -The error codes and their meanings are defined in -<lwres/netdb.h>: - -HOST_NOT_FOUND - - -No such host is known. - - -NO_ADDRESS - - -The server recognised the request and the name but no address is -available. Another type of request to the name server for the -domain might return an answer. - - -TRY_AGAIN - - -A temporary and possibly transient error occurred, such as a -failure of a server to respond. The request may succeed if -retried. - - -NO_RECOVERY - - -An unexpected failure occurred, and retrying the request -is pointless. - - - - - - -lwres_hstrerror3 - - -translates these error codes to suitable error messages. - - - -SEE ALSO - - -RFC2553 -, + + lwres_gethostent3 + , - -lwres3 -, + + lwres_getaddrinfo3 + , - -lwres_gethostent3 -, + + lwres_getnameinfo3 + , - -lwres_getaddrinfo3 -, - - -lwres_getnameinfo3 -, - - -lwres_hstrerror3 -. - - - + + lwres_hstrerror3 + . + + + diff --git a/lib/lwres/man/lwres_getnameinfo.docbook b/lib/lwres/man/lwres_getnameinfo.docbook index e51ecb5938..98f0c42ad7 100644 --- a/lib/lwres/man/lwres_getnameinfo.docbook +++ b/lib/lwres/man/lwres_getnameinfo.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_getnameinfo -3 -BIND9 - + + lwres_getnameinfo + 3 + BIND9 + - -lwres_getnameinfo -lightweight resolver socket address structure to hostname and service name - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_getnameinfo + lightweight resolver socket address structure to hostname and + service name + + + + #include <lwres/netdb.h> - + int lwres_getnameinfo -const struct sockaddr *sa -size_t salen -char *host -size_t hostlen -char *serv -size_t servlen -int flags - + const struct sockaddr *sa + size_t salen + char *host + size_t hostlen + char *serv + size_t servlen + int flags + - + - -DESCRIPTION + + DESCRIPTION - This function is equivalent to the -getnameinfo3 - function defined in RFC2133. -lwres_getnameinfo() returns the hostname for the -struct sockaddr sa which is -salen bytes long. The hostname is of length -hostlen and is returned via -*host. The maximum length of the hostname is -1025 bytes: NI_MAXHOST. + + This function is equivalent to the + + getnameinfo3 + function defined in RFC2133. + lwres_getnameinfo() returns the + hostname for the + struct sockaddr sa which + is + salen bytes long. The hostname is of + length + hostlen and is returned via + *host. The maximum length of the + hostname is + 1025 bytes: NI_MAXHOST. + - The name of the service associated with the port number in -sa is returned in *serv. -It is servlen bytes long. The maximum length -of the service name is NI_MAXSERV - 32 bytes. - + The name of the service associated with the port number in + sa is returned in *serv. + It is servlen bytes long. The + maximum length + of the service name is NI_MAXSERV - 32 + bytes. + - The flags argument sets the following -bits: - -NI_NOFQDN - - -A fully qualified domain name is not required for local hosts. -The local part of the fully qualified domain name is returned instead. - -NI_NUMERICHOST - - -Return the address in numeric form, as if calling inet_ntop(), -instead of a host name. - -NI_NAMEREQD - - -A name is required. If the hostname cannot be found in the DNS and -this flag is set, a non-zero error code is returned. -If the hostname is not found and the flag is not set, the -address is returned in numeric form. - -NI_NUMERICSERV - - -The service name is returned as a digit string representing the port number. - -NI_DGRAM - - -Specifies that the service being looked up is a datagram -service, and causes getservbyport() to be called with a second -argument of "udp" instead of its default of "tcp". This is required -for the few ports (512-514) that have different services for UDP and -TCP. - - - - + + The flags argument sets the + following + bits: + + + NI_NOFQDN + + + A fully qualified domain name is not required for local hosts. + The local part of the fully qualified domain name is returned + instead. + + + + + NI_NUMERICHOST + + + Return the address in numeric form, as if calling inet_ntop(), + instead of a host name. + + + + + NI_NAMEREQD + + + A name is required. If the hostname cannot be found in the DNS + and + this flag is set, a non-zero error code is returned. + If the hostname is not found and the flag is not set, the + address is returned in numeric form. + + + + + NI_NUMERICSERV + + + The service name is returned as a digit string representing the + port number. + + + + + NI_DGRAM + + + Specifies that the service being looked up is a datagram + service, and causes getservbyport() to be called with a second + argument of "udp" instead of its default of "tcp". This is + required + for the few ports (512-514) that have different services for UDP + and + TCP. + + + + + + - -RETURN VALUES - -lwres_getnameinfo() -returns 0 on success or a non-zero error code if an error occurs. - - - -SEE ALSO - - -RFC2133 -, - -getservbyport3 -, - -lwres3 -, - -lwres_getnameinfo3 -, - -lwres_getnamebyaddr3 -. - -lwres_net_ntop3 -. - - -BUGS - -RFC2133 fails to define what the nonzero return values of - -getnameinfo3 - -are. - - - + + RETURN VALUES + lwres_getnameinfo() + returns 0 on success or a non-zero error code if an error occurs. + + + + SEE ALSO + + RFC2133 + , + + getservbyport3 + , + + lwres3 + , + + lwres_getnameinfo3 + , + + lwres_getnamebyaddr3 + . + + lwres_net_ntop3 + . + + + + BUGS + + RFC2133 fails to define what the nonzero return values of + + getnameinfo3 + + are. + + + diff --git a/lib/lwres/man/lwres_getrrsetbyname.docbook b/lib/lwres/man/lwres_getrrsetbyname.docbook index 0ff549b47a..32caa0b38f 100644 --- a/lib/lwres/man/lwres_getrrsetbyname.docbook +++ b/lib/lwres/man/lwres_getrrsetbyname.docbook @@ -1,4 +1,6 @@ - +]> - - - + - + + Oct 18, 2000 + -Oct 18, 2000 - - -lwres_getrrsetbyname -3 -BIND9 - - -lwres_getrrsetbyname -lwres_freerrset -retrieve DNS records - - - + + lwres_getrrsetbyname + 3 + BIND9 + + + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_getrrsetbyname + lwres_freerrset + retrieve DNS records + + + #include <lwres/netdb.h> - + int lwres_getrrsetbyname -const char *hostname -unsigned int rdclass -unsigned int rdtype -unsigned int flags -struct rrsetinfo **res - + const char *hostname + unsigned int rdclass + unsigned int rdtype + unsigned int flags + struct rrsetinfo **res + - + void lwres_freerrset -struct rrsetinfo *rrset - + struct rrsetinfo *rrset + - -The following structures are used: - + + The following structures are used: + + struct rdatainfo { unsigned int rdi_length; /* length of data */ unsigned char *rdi_data; /* record data */ }; - + + + struct rrsetinfo { unsigned int rri_flags; /* RRSET_VALIDATED... */ unsigned int rri_rdclass; /* class number */ @@ -75,134 +92,130 @@ struct rrsetinfo { struct rdatainfo *rri_sigs; /* individual signatures */ }; - - + + - -DESCRIPTION - -lwres_getrrsetbyname() -gets a set of resource records associated with a -hostname, + + DESCRIPTION + lwres_getrrsetbyname() + gets a set of resource records associated with a + hostname, class, + and type. + hostname is a pointer a to + null-terminated string. The flags field + is currently unused and must be zero. + + + After a successful call to + lwres_getrrsetbyname(), + *res is a pointer to an + rrsetinfo structure, containing a list of one or + more rdatainfo structures containing resource + records and potentially another list of rdatainfo + structures containing SIG resource records associated with those + records. The members rri_rdclass and + rri_rdtype are copied from the parameters. + rri_ttl and rri_name + are properties of the obtained rrset. The resource records + contained in rri_rdatas and + rri_sigs are in uncompressed DNS wire + format. Properties of the rdataset are represented in the + rri_flags bitfield. If the RRSET_VALIDATED + bit is set, the data has been DNSSEC validated and the + signatures verified. + + + All of the information returned by + lwres_getrrsetbyname() is dynamically + allocated: the rrsetinfo and + rdatainfo structures, and the canonical + host name strings pointed to by the + rrsetinfostructure. -class, + Memory allocated for the dynamically allocated structures + created by a successful call to + lwres_getrrsetbyname() is released by + lwres_freerrset(). -and -type. + rrset is a pointer to a struct + rrset created by a call to + lwres_getrrsetbyname(). + + + + + RETURN VALUES + lwres_getrrsetbyname() + returns zero on success, and one of the following error codes if + an error occurred: + -hostname -is -a pointer a to null-terminated string. The -flags -field is currently unused and must be zero. - - -After a successful call to -lwres_getrrsetbyname(), + + ERRSET_NONAME + + + the name does not exist + + + -*res -is a pointer to an -rrsetinfo -structure, containing a list of one or more -rdatainfo -structures containing resource records and potentially another list of -rdatainfo -structures containing SIG resource records -associated with those records. -The members -rri_rdclass -and -rri_rdtype -are copied from the parameters. -rri_ttl -and -rri_name -are properties of the obtained rrset. -The resource records contained in -rri_rdatas -and -rri_sigs -are in uncompressed DNS wire format. -Properties of the rdataset are represented in the -rri_flags -bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC -validated and the signatures verified. - - -All of the information returned by -lwres_getrrsetbyname() -is dynamically allocated: the -rrsetinfo -and -rdatainfo -structures, -and the canonical host name strings pointed to by the -rrsetinfostructure. + + ERRSET_NODATA + + + the name exists, but does not have data of the desired type + + + -Memory allocated for the dynamically allocated structures created by -a successful call to -lwres_getrrsetbyname() -is released by -lwres_freerrset(). + + ERRSET_NOMEMORY + + + memory could not be allocated + + + -rrset -is a pointer to a -struct rrset -created by a call to -lwres_getrrsetbyname(). + + ERRSET_INVAL + + + a parameter is invalid + + + - - - - - -RETURN VALUES - -lwres_getrrsetbyname() -returns zero on success, and one of the following error -codes if an error occurred: - + + ERRSET_FAIL + + + other failure + + + -ERRSET_NONAME - -the name does not exist - + + + + + + -ERRSET_NODATA - -the name exists, but does not have data of the desired type - + -ERRSET_NOMEMORY - -memory could not be allocated - + + + + SEE ALSO + + lwres3 + . + -ERRSET_INVAL - -a parameter is invalid - - -ERRSET_FAIL - -other failure - - - - - - - - - - - -SEE ALSO - - -lwres3 -. - - - - + + diff --git a/lib/lwres/man/lwres_gnba.docbook b/lib/lwres/man/lwres_gnba.docbook index 665caa825f..24602a2992 100644 --- a/lib/lwres/man/lwres_gnba.docbook +++ b/lib/lwres/man/lwres_gnba.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_gnba -3 -BIND9 - + + lwres_gnba + 3 + BIND9 + - -lwres_gnbarequest_render -lwres_gnbaresponse_render -lwres_gnbarequest_parse -lwres_gnbaresponse_parse -lwres_gnbaresponse_free -lwres_gnbarequest_free -lightweight resolver getnamebyaddress message handling - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + - + + lwres_gnbarequest_render + lwres_gnbaresponse_render + lwres_gnbarequest_parse + lwres_gnbaresponse_parse + lwres_gnbaresponse_free + lwres_gnbarequest_free + lightweight resolver getnamebyaddress message handling + - + + + #include <lwres/lwres.h> - + lwres_result_t lwres_gnbarequest_render -lwres_context_t *ctx -lwres_gnbarequest_t *req -lwres_lwpacket_t *pkt -lwres_buffer_t *b - + lwres_context_t *ctx + lwres_gnbarequest_t *req + lwres_lwpacket_t *pkt + lwres_buffer_t *b + - + lwres_result_t lwres_gnbaresponse_render -lwres_context_t *ctx -lwres_gnbaresponse_t *req -lwres_lwpacket_t *pkt -lwres_buffer_t *b - + lwres_context_t *ctx + lwres_gnbaresponse_t *req + lwres_lwpacket_t *pkt + lwres_buffer_t *b + - + lwres_result_t lwres_gnbarequest_parse -lwres_context_t *ctx -lwres_buffer_t *b -lwres_lwpacket_t *pkt -lwres_gnbarequest_t **structp - + lwres_context_t *ctx + lwres_buffer_t *b + lwres_lwpacket_t *pkt + lwres_gnbarequest_t **structp + - + lwres_result_t lwres_gnbaresponse_parse -lwres_context_t *ctx -lwres_buffer_t *b -lwres_lwpacket_t *pkt -lwres_gnbaresponse_t **structp - + lwres_context_t *ctx + lwres_buffer_t *b + lwres_lwpacket_t *pkt + lwres_gnbaresponse_t **structp + - + void lwres_gnbaresponse_free -lwres_context_t *ctx -lwres_gnbaresponse_t **structp - + lwres_context_t *ctx + lwres_gnbaresponse_t **structp + - + void lwres_gnbarequest_free -lwres_context_t *ctx -lwres_gnbarequest_t **structp - + lwres_context_t *ctx + lwres_gnbarequest_t **structp + - + - -DESCRIPTION - -These are low-level routines for creating and parsing -lightweight resolver address-to-name lookup request and -response messages. - - -There are four main functions for the getnamebyaddr opcode. -One render function converts a getnamebyaddr request structure — -lwres_gnbarequest_t — -to the lightweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a getnamebyaddr request structure. -Another render function converts the getnamebyaddr response structure — -lwres_gnbaresponse_t -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a getnamebyaddr response structure. - - -These structures are defined in -lwres/lwres.h. -They are shown below. - + + DESCRIPTION + + These are low-level routines for creating and parsing + lightweight resolver address-to-name lookup request and + response messages. + + + There are four main functions for the getnamebyaddr opcode. + One render function converts a getnamebyaddr request structure — + lwres_gnbarequest_t — + to the lightweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a getnamebyaddr request structure. + Another render function converts the getnamebyaddr response structure + — + lwres_gnbaresponse_t + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a getnamebyaddr response structure. + + + These structures are defined in + lwres/lwres.h. + They are shown below. + + #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U - + + + typedef struct { lwres_uint32_t flags; lwres_addr_t addr; } lwres_gnbarequest_t; - + + + typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -149,111 +168,92 @@ typedef struct { size_t baselen; } lwres_gnbaresponse_t; - - -lwres_gnbarequest_render() -uses resolver context -ctx -to convert getnamebyaddr request structure -req -to canonical format. -The packet header structure -pkt -is initialised and transferred to -buffer -b. -The contents of -*req -are then appended to the buffer in canonical format. -lwres_gnbaresponse_render() -performs the same task, except it converts a getnamebyaddr response structure -lwres_gnbaresponse_t -to the lightweight resolver's canonical format. - - -lwres_gnbarequest_parse() -uses context -ctx -to convert the contents of packet -pkt -to a -lwres_gnbarequest_t -structure. -Buffer -b -provides space to be used for storing this structure. -When the function succeeds, the resulting -lwres_gnbarequest_t -is made available through -*structp. -lwres_gnbaresponse_parse() -offers the same semantics as -lwres_gnbarequest_parse() -except it yields a -lwres_gnbaresponse_t -structure. - - -lwres_gnbaresponse_free() -and -lwres_gnbarequest_free() -release the memory in resolver context -ctx -that was allocated to the -lwres_gnbaresponse_t -or -lwres_gnbarequest_t -structures referenced via -structp. -Any memory associated with ancillary buffers and strings for those -structures is also discarded. - - - -RETURN VALUES - -The getnamebyaddr opcode functions -lwres_gnbarequest_render(), -lwres_gnbaresponse_render() -lwres_gnbarequest_parse() -and -lwres_gnbaresponse_parse() -all return -LWRES_R_SUCCESS -on success. -They return -LWRES_R_NOMEMORY -if memory allocation fails. -LWRES_R_UNEXPECTEDEND -is returned if the available space in the buffer -b -is too small to accommodate the packet header or the -lwres_gnbarequest_t -and -lwres_gnbaresponse_t -structures. -lwres_gnbarequest_parse() -and -lwres_gnbaresponse_parse() -will return -LWRES_R_UNEXPECTEDEND -if the buffer is not empty after decoding the received packet. -These functions will return -LWRES_R_FAILURE -if -pktflags -in the packet header structure -lwres_lwpacket_t -indicate that the packet is not a response to an earlier query. - - - -SEE ALSO - - -lwres_packet -3 -. - - - + + + lwres_gnbarequest_render() + uses resolver context ctx to convert + getnamebyaddr request structure req to + canonical format. The packet header structure + pkt is initialised and transferred to buffer + b. The contents of *req + are then appended to the buffer in canonical format. + lwres_gnbaresponse_render() performs the + same task, except it converts a getnamebyaddr response structure + lwres_gnbaresponse_t to the lightweight resolver's + canonical format. + + + lwres_gnbarequest_parse() + uses context ctx to convert the contents of + packet pkt to a + lwres_gnbarequest_t structure. Buffer + b provides space to be used for storing this + structure. When the function succeeds, the resulting + lwres_gnbarequest_t is made available through + *structp. + lwres_gnbaresponse_parse() offers the same + semantics as lwres_gnbarequest_parse() + except it yields a lwres_gnbaresponse_t structure. + + + lwres_gnbaresponse_free() + and lwres_gnbarequest_free() release the + memory in resolver context ctx that was + allocated to the lwres_gnbaresponse_t or + lwres_gnbarequest_t structures referenced via + structp. Any memory associated with + ancillary buffers and strings for those structures is also + discarded. + + + + + RETURN VALUES + + The getnamebyaddr opcode functions + lwres_gnbarequest_render(), + lwres_gnbaresponse_render() + lwres_gnbarequest_parse() + and + lwres_gnbaresponse_parse() + all return + LWRES_R_SUCCESS + on success. + They return + LWRES_R_NOMEMORY + if memory allocation fails. + LWRES_R_UNEXPECTEDEND + is returned if the available space in the buffer + b + is too small to accommodate the packet header or the + lwres_gnbarequest_t + and + lwres_gnbaresponse_t + structures. + lwres_gnbarequest_parse() + and + lwres_gnbaresponse_parse() + will return + LWRES_R_UNEXPECTEDEND + if the buffer is not empty after decoding the received packet. + These functions will return + LWRES_R_FAILURE + if + pktflags + in the packet header structure + lwres_lwpacket_t + indicate that the packet is not a response to an earlier query. + + + + SEE ALSO + + lwres_packet3 + . + + + diff --git a/lib/lwres/man/lwres_hstrerror.docbook b/lib/lwres/man/lwres_hstrerror.docbook index e9224de183..c3b4f3a6ac 100644 --- a/lib/lwres/man/lwres_hstrerror.docbook +++ b/lib/lwres/man/lwres_hstrerror.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_hstrerror -3 -BIND9 - + + lwres_hstrerror + 3 + BIND9 + - -lwres_herror -lwres_hstrerror -lightweight resolver error message generation - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_herror + lwres_hstrerror + lightweight resolver error message generation + + + #include <lwres/netdb.h> - + void lwres_herror -const char *s - + const char *s + - + const char * lwres_hstrerror -int err - + int err + - + - -DESCRIPTION + + DESCRIPTION - -lwres_herror() prints the string -s on stderr followed by the string -generated by lwres_hstrerror() for the error code -stored in the global variable lwres_h_errno. - + lwres_herror() + prints the string s on + stderr followed by the string generated by + lwres_hstrerror() for the error code stored + in the global variable lwres_h_errno. + - -lwres_hstrerror() returns an appropriate string -for the error code gievn by err. The values of -the error codes and messages are as follows: + lwres_hstrerror() + returns an appropriate string for the error code gievn by + err. The values of the error codes and + messages are as follows: - -NETDB_SUCCESS - - -Resolver Error 0 (no error) - -HOST_NOT_FOUND - - -Unknown host - -TRY_AGAIN - - -Host name lookup failure - -NO_RECOVERY - - -Unknown server error - -NO_DATA - - -No address associated with name - - - - + + + NETDB_SUCCESS + + Resolver Error 0 (no error) + + + + + HOST_NOT_FOUND + + Unknown host + + + + + TRY_AGAIN + + Host name lookup failure + + + + + NO_RECOVERY + + Unknown server error + + + + + NO_DATA + + No address associated with name + + + + + + - -RETURN VALUES - -The string Unknown resolver error is returned by -lwres_hstrerror() -when the value of -lwres_h_errno -is not a valid error code. - - - -SEE ALSO - - -herror3 -, + + RETURN VALUES + + The string Unknown resolver error is returned by + lwres_hstrerror() + when the value of + lwres_h_errno + is not a valid error code. + + + + SEE ALSO + + herror3 + , - -lwres_hstrerror3 -. - + + lwres_hstrerror3 + . + - - + + diff --git a/lib/lwres/man/lwres_inetntop.docbook b/lib/lwres/man/lwres_inetntop.docbook index 5aeb030d5a..3611d6a905 100644 --- a/lib/lwres/man/lwres_inetntop.docbook +++ b/lib/lwres/man/lwres_inetntop.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_inetntop -3 -BIND9 - + + lwres_inetntop + 3 + BIND9 + - -lwres_net_ntop -lightweight resolver IP address presentation - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_net_ntop + lightweight resolver IP address presentation + + + #include <lwres/net.h> - + const char * lwres_net_ntop -int af -const void *src -char *dst -size_t size - + int af + const void *src + char *dst + size_t size + - + - -DESCRIPTION + + DESCRIPTION - -lwres_net_ntop() converts an IP address of -protocol family af — IPv4 or IPv6 — -at location src from network format to its -conventional representation as a string. For IPv4 addresses, that -string would be a dotted-decimal. An IPv6 address would be -represented in colon notation as described in RFC1884. - + lwres_net_ntop() + converts an IP address of protocol family + af — IPv4 or IPv6 — at + location src from network format to its + conventional representation as a string. For IPv4 addresses, + that string would be a dotted-decimal. An IPv6 address would be + represented in colon notation as described in RFC1884. + - -The generated string is copied to dst provided -size indicates it is long enough to store the -ASCII representation of the address. - + + The generated string is copied to dst + provided + size indicates it is long enough to + store the + ASCII representation of the address. + - - -RETURN VALUES + + + RETURN VALUES - -If successful, the function returns dst: -a pointer to a string containing the presentation format of the -address. lwres_net_ntop() returns -NULL and sets the global variable -errno to EAFNOSUPPORT if -the protocol family given in af is not -supported. - + + If successful, the function returns dst: + a pointer to a string containing the presentation format of the + address. lwres_net_ntop() returns + NULL and sets the global variable + errno to EAFNOSUPPORT if + the protocol family given in af is + not + supported. + - - -SEE ALSO - - -RFC1884 -, - -inet_ntop3 -, - -errno3 -. - - - + + + SEE ALSO + + RFC1884 + , + + inet_ntop3 + , + + errno3 + . + + + diff --git a/lib/lwres/man/lwres_noop.docbook b/lib/lwres/man/lwres_noop.docbook index 92dd099809..cff910b98a 100644 --- a/lib/lwres/man/lwres_noop.docbook +++ b/lib/lwres/man/lwres_noop.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_noop -3 -BIND9 - + + lwres_noop + 3 + BIND9 + - -lwres_nooprequest_render -lwres_noopresponse_render -lwres_nooprequest_parse -lwres_noopresponse_parse -lwres_noopresponse_free -lwres_nooprequest_free -lightweight resolver no-op message handling - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_nooprequest_render + lwres_noopresponse_render + lwres_nooprequest_parse + lwres_noopresponse_parse + lwres_noopresponse_free + lwres_nooprequest_free + lightweight resolver no-op message handling + + + #include <lwres/lwres.h> - + lwres_result_t lwres_nooprequest_render -lwres_context_t *ctx -lwres_nooprequest_t *req -lwres_lwpacket_t *pkt -lwres_buffer_t *b - + lwres_context_t *ctx + lwres_nooprequest_t *req + lwres_lwpacket_t *pkt + lwres_buffer_t *b + - + lwres_result_t lwres_noopresponse_render -lwres_context_t *ctx -lwres_noopresponse_t *req -lwres_lwpacket_t *pkt -lwres_buffer_t *b - + lwres_context_t *ctx + lwres_noopresponse_t *req + lwres_lwpacket_t *pkt + lwres_buffer_t *b + - + lwres_result_t lwres_nooprequest_parse -lwres_context_t *ctx -lwres_buffer_t *b -lwres_lwpacket_t *pkt -lwres_nooprequest_t **structp - + lwres_context_t *ctx + lwres_buffer_t *b + lwres_lwpacket_t *pkt + lwres_nooprequest_t **structp + - + lwres_result_t lwres_noopresponse_parse -lwres_context_t *ctx -lwres_buffer_t *b -lwres_lwpacket_t *pkt -lwres_noopresponse_t **structp - + lwres_context_t *ctx + lwres_buffer_t *b + lwres_lwpacket_t *pkt + lwres_noopresponse_t **structp + - + void lwres_noopresponse_free -lwres_context_t *ctx -lwres_noopresponse_t **structp - + lwres_context_t *ctx + lwres_noopresponse_t **structp + - + void lwres_nooprequest_free -lwres_context_t *ctx -lwres_nooprequest_t **structp - + lwres_context_t *ctx + lwres_nooprequest_t **structp + - - -DESCRIPTION - -These are low-level routines for creating and parsing -lightweight resolver no-op request and response messages. - - -The no-op message is analogous to a ping packet: -a packet is sent to the resolver daemon and is simply echoed back. -The opcode is intended to allow a client to determine if the server is -operational or not. - - -There are four main functions for the no-op opcode. -One render function converts a no-op request structure — -lwres_nooprequest_t — -to the lighweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a no-op request structure. -Another render function converts the no-op response structure — -lwres_noopresponse_t -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a no-op response structure. - - -These structures are defined in -lwres/lwres.h. + + + DESCRIPTION + + These are low-level routines for creating and parsing + lightweight resolver no-op request and response messages. + + + The no-op message is analogous to a ping + packet: + a packet is sent to the resolver daemon and is simply echoed back. + The opcode is intended to allow a client to determine if the server is + operational or not. + + + There are four main functions for the no-op opcode. + One render function converts a no-op request structure — + lwres_nooprequest_t — + to the lighweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a no-op request structure. + Another render function converts the no-op response structure — + lwres_noopresponse_t + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a no-op response structure. + + + These structures are defined in + lwres/lwres.h. -They are shown below. - + They are shown below. + + #define LWRES_OPCODE_NOOP 0x00000000U - + + + typedef struct { lwres_uint16_t datalength; unsigned char *data; } lwres_nooprequest_t; - + + + typedef struct { lwres_uint16_t datalength; unsigned char *data; } lwres_noopresponse_t; -Although the structures have different types, they are identical. -This is because the no-op opcode simply echos whatever data was sent: -the response is therefore identical to the request. - + + + Although the structures have different types, they are identical. + This is because the no-op opcode simply echos whatever data was sent: + the response is therefore identical to the request. + - -lwres_nooprequest_render() uses resolver -context ctx to convert no-op request structure -req to canonical format. The packet header -structure pkt is initialised and transferred to -buffer b. The contents of -*req are then appended to the buffer in -canonical format. lwres_noopresponse_render() -performs the same task, except it converts a no-op response structure -lwres_noopresponse_t to the lightweight resolver's -canonical format. - + lwres_nooprequest_render() + uses resolver context ctx to convert + no-op request structure req to canonical + format. The packet header structure pkt + is initialised and transferred to buffer + b. The contents of + *req are then appended to the buffer in + canonical format. + lwres_noopresponse_render() performs the + same task, except it converts a no-op response structure + lwres_noopresponse_t to the lightweight resolver's + canonical format. + - -lwres_nooprequest_parse() uses context -ctx to convert the contents of packet -pkt to a lwres_nooprequest_t -structure. Buffer b provides space to be used -for storing this structure. When the function succeeds, the resulting -lwres_nooprequest_t is made available through -*structp. -lwres_noopresponse_parse() offers the same -semantics as lwres_nooprequest_parse() except it -yields a lwres_noopresponse_t structure. - + lwres_nooprequest_parse() + uses context ctx to convert the contents + of packet pkt to a + lwres_nooprequest_t structure. Buffer + b provides space to be used for storing + this structure. When the function succeeds, the resulting + lwres_nooprequest_t is made available through + *structp. + lwres_noopresponse_parse() offers the same + semantics as lwres_nooprequest_parse() + except it yields a lwres_noopresponse_t structure. + - -lwres_noopresponse_free() and -lwres_nooprequest_free() release the memory in -resolver context ctx that was allocated to the -lwres_noopresponse_t or lwres_nooprequest_t -structures referenced via structp. - + lwres_noopresponse_free() + and lwres_nooprequest_free() release the + memory in resolver context ctx that was + allocated to the lwres_noopresponse_t or + lwres_nooprequest_t structures referenced via + structp. + - - -RETURN VALUES - -The no-op opcode functions -lwres_nooprequest_render(), + + + RETURN VALUES + + The no-op opcode functions + lwres_nooprequest_render(), -lwres_noopresponse_render() -lwres_nooprequest_parse() -and -lwres_noopresponse_parse() -all return -LWRES_R_SUCCESS -on success. -They return -LWRES_R_NOMEMORY -if memory allocation fails. -LWRES_R_UNEXPECTEDEND -is returned if the available space in the buffer -b -is too small to accommodate the packet header or the -lwres_nooprequest_t -and -lwres_noopresponse_t -structures. -lwres_nooprequest_parse() -and -lwres_noopresponse_parse() -will return -LWRES_R_UNEXPECTEDEND -if the buffer is not empty after decoding the received packet. -These functions will return -LWRES_R_FAILURE -if -pktflags -in the packet header structure -lwres_lwpacket_t -indicate that the packet is not a response to an earlier query. - - - -SEE ALSO - - -lwres_packet3 - - - - - + lwres_noopresponse_render() + lwres_nooprequest_parse() + and + lwres_noopresponse_parse() + all return + LWRES_R_SUCCESS + on success. + They return + LWRES_R_NOMEMORY + if memory allocation fails. + LWRES_R_UNEXPECTEDEND + is returned if the available space in the buffer + b + is too small to accommodate the packet header or the + lwres_nooprequest_t + and + lwres_noopresponse_t + structures. + lwres_nooprequest_parse() + and + lwres_noopresponse_parse() + will return + LWRES_R_UNEXPECTEDEND + if the buffer is not empty after decoding the received packet. + These functions will return + LWRES_R_FAILURE + if + pktflags + in the packet header structure + lwres_lwpacket_t + indicate that the packet is not a response to an earlier query. + + + + SEE ALSO + + lwres_packet3 + + + + diff --git a/lib/lwres/man/lwres_packet.docbook b/lib/lwres/man/lwres_packet.docbook index 2720998e76..1a44f038c5 100644 --- a/lib/lwres/man/lwres_packet.docbook +++ b/lib/lwres/man/lwres_packet.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - -lwres_packet -3 -BIND9 - + + lwres_packet + 3 + BIND9 + - -lwres_lwpacket_renderheader -lwres_lwpacket_parseheader -lightweight resolver packet handling functions - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_lwpacket_renderheader + lwres_lwpacket_parseheader + lightweight resolver packet handling functions + + + #include <lwres/lwpacket.h> - + lwres_result_t lwres_lwpacket_renderheader -lwres_buffer_t *b -lwres_lwpacket_t *pkt - + lwres_buffer_t *b + lwres_lwpacket_t *pkt + - + lwres_result_t lwres_lwpacket_parseheader -lwres_buffer_t *b -lwres_lwpacket_t *pkt - + lwres_buffer_t *b + lwres_lwpacket_t *pkt + - - -DESCRIPTION - -These functions rely on a -struct lwres_lwpacket -which is defined in -lwres/lwpacket.h. + + + DESCRIPTION + + These functions rely on a + struct lwres_lwpacket + which is defined in + lwres/lwpacket.h. + - + typedef struct lwres_lwpacket lwres_lwpacket_t; - + + + struct lwres_lwpacket { lwres_uint32_t length; lwres_uint16_t version; @@ -77,142 +93,197 @@ struct lwres_lwpacket { lwres_uint16_t authlength; }; - + - -The elements of this structure are: - -length - - -the overall packet length, including the entire packet header. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. - -version - - -the header format. There is currently only one format, -LWRES_LWPACKETVERSION_0. + + The elements of this structure are: + + + length + + + the overall packet length, including the entire packet header. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + + + + + version + + + the header format. There is currently only one format, + LWRES_LWPACKETVERSION_0. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. - -pktflags - - -library-defined flags for this packet: for instance whether the packet -is a request or a reply. Flag values can be set, but not defined by -the caller. -This field is filled in by the application wit the exception of the -LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the -lwres_gabn_*() and lwres_gnba_*() calls. - -serial - - -is set by the requestor and is returned in all replies. If two or more -packets from the same source have the same serial number and are from -the same source, they are assumed to be duplicates and the latter ones -may be dropped. -This field must be set by the application. - -opcode - - -indicates the operation. -Opcodes between 0x00000000 and 0x03ffffff are -reserved for use by the lightweight resolver library. Opcodes between -0x04000000 and 0xffffffff are application defined. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. - -result - - -is only valid for replies. -Results between 0x04000000 and 0xffffffff are application defined. -Results between 0x00000000 and 0x03ffffff are reserved for library use. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. - -recvlength - - -is the maximum buffer size that the receiver can handle on requests -and the size of the buffer needed to satisfy a request when the buffer -is too large for replies. -This field is supplied by the application. - -authtype - - -defines the packet level authentication that is used. -Authorisation types between 0x1000 and 0xffff are application defined -and types between 0x0000 and 0x0fff are reserved for library use. -Currently these are not used and must be zero. - -authlen - - -gives the length of the authentication data. -Since packet authentication is currently not used, this must be zero. - - - - -The following opcodes are currently defined: - -NOOP - - -Success is always returned and the packet contents are echoed. -The lwres_noop_*() functions should be used for this type. - -GETADDRSBYNAME - - -returns all known addresses for a given name. -The lwres_gabn_*() functions should be used for this type. - -GETNAMEBYADDR - - -return the hostname for the given address. -The lwres_gnba_*() functions should be used for this type. - - - + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + + + + + pktflags + + + library-defined flags for this packet: for instance whether the + packet + is a request or a reply. Flag values can be set, but not defined + by + the caller. + This field is filled in by the application wit the exception of + the + LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in + the + lwres_gabn_*() and lwres_gnba_*() calls. + + + + + serial + + + is set by the requestor and is returned in all replies. If two + or more + packets from the same source have the same serial number and are + from + the same source, they are assumed to be duplicates and the + latter ones + may be dropped. + This field must be set by the application. + + + + + opcode + + + indicates the operation. + Opcodes between 0x00000000 and 0x03ffffff are + reserved for use by the lightweight resolver library. Opcodes + between + 0x04000000 and 0xffffffff are application defined. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + + + + + result + + + is only valid for replies. + Results between 0x04000000 and 0xffffffff are application + defined. + Results between 0x00000000 and 0x03ffffff are reserved for + library use. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + + + + + recvlength + + + is the maximum buffer size that the receiver can handle on + requests + and the size of the buffer needed to satisfy a request when the + buffer + is too large for replies. + This field is supplied by the application. + + + + + authtype + + + defines the packet level authentication that is used. + Authorisation types between 0x1000 and 0xffff are application + defined + and types between 0x0000 and 0x0fff are reserved for library + use. + Currently these are not used and must be zero. + + + + + authlen + + + gives the length of the authentication data. + Since packet authentication is currently not used, this must be + zero. + + + + + + + The following opcodes are currently defined: + + + NOOP + + + Success is always returned and the packet contents are echoed. + The lwres_noop_*() functions should be used for this type. + + + + + GETADDRSBYNAME + + + returns all known addresses for a given name. + The lwres_gabn_*() functions should be used for this type. + + + + + GETNAMEBYADDR + + + return the hostname for the given address. + The lwres_gnba_*() functions should be used for this type. + + + + + - -lwres_lwpacket_renderheader() transfers the -contents of lightweight resolver packet structure -lwres_lwpacket_t *pkt in network -byte order to the lightweight resolver buffer, -*b. - + lwres_lwpacket_renderheader() + transfers the contents of lightweight resolver packet structure + lwres_lwpacket_t *pkt in + network byte order to the lightweight resolver buffer, + *b. + - -lwres_lwpacket_parseheader() performs the -converse operation. It transfers data in network byte order from -buffer *b to resolver packet -*pkt. The contents of the buffer -b should correspond to a -lwres_lwpacket_t. - + lwres_lwpacket_parseheader() + performs the converse operation. It transfers data in network + byte order from buffer *b to resolver + packet *pkt. The contents of the buffer + b should correspond to a + lwres_lwpacket_t. + - + - -RETURN VALUES - Successful calls to -lwres_lwpacket_renderheader() and -lwres_lwpacket_parseheader() return -LWRES_R_SUCCESS. If there is insufficient -space to copy data between the buffer *b and -lightweight resolver packet *pkt both functions -return LWRES_R_UNEXPECTEDEND. - + + RETURN VALUES + + Successful calls to + lwres_lwpacket_renderheader() and + lwres_lwpacket_parseheader() return + LWRES_R_SUCCESS. If there is insufficient + space to copy data between the buffer *b and + lightweight resolver packet *pkt both + functions + return LWRES_R_UNEXPECTEDEND. + - - + + diff --git a/lib/lwres/man/lwres_resutil.docbook b/lib/lwres/man/lwres_resutil.docbook index 1087a8ee28..8bfc1144b0 100644 --- a/lib/lwres/man/lwres_resutil.docbook +++ b/lib/lwres/man/lwres_resutil.docbook @@ -1,4 +1,6 @@ - +]> - - - + - -Jun 30, 2000 - + + Jun 30, 2000 + - - lwres_resutil - 3 - BIND9 - + + lwres_resutil + 3 + BIND9 + - -lwres_string_parse -lwres_addr_parse -lwres_getaddrsbyname -lwres_getnamebyaddr -lightweight resolver utility functions - - - + + + 2004 + 2005 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium + + + + + lwres_string_parse + lwres_addr_parse + lwres_getaddrsbyname + lwres_getnamebyaddr + lightweight resolver utility functions + + + #include <lwres/lwres.h> - + lwres_result_t lwres_string_parse -lwres_buffer_t *b -char **c -lwres_uint16_t *len - + lwres_buffer_t *b + char **c + lwres_uint16_t *len + - + lwres_result_t lwres_addr_parse -lwres_buffer_t *b -lwres_addr_t *addr - + lwres_buffer_t *b + lwres_addr_t *addr + - + lwres_result_t lwres_getaddrsbyname -lwres_context_t *ctx -const char *name -lwres_uint32_t addrtypes -lwres_gabnresponse_t **structp - + lwres_context_t *ctx + const char *name + lwres_uint32_t addrtypes + lwres_gabnresponse_t **structp + - + lwres_result_t lwres_getnamebyaddr -lwres_context_t *ctx -lwres_uint32_t addrtype -lwres_uint16_t addrlen -const unsigned char *addr -lwres_gnbaresponse_t **structp - + lwres_context_t *ctx + lwres_uint32_t addrtype + lwres_uint16_t addrlen + const unsigned char *addr + lwres_gnbaresponse_t **structp + - + - -DESCRIPTION + + DESCRIPTION - -lwres_string_parse() retrieves a DNS-encoded -string starting the current pointer of lightweight resolver buffer -b: i.e. b->current. -When the function returns, the address of the first byte of the -encoded string is returned via *c and the -length of that string is given by *len. The -buffer's current pointer is advanced to point at the character -following the string length, the encoded string, and the trailing -NULL character. - + lwres_string_parse() + retrieves a DNS-encoded string starting the current pointer of + lightweight resolver buffer b: i.e. + b->current. When the function returns, + the address of the first byte of the encoded string is returned + via *c and the length of that string is + given by *len. The buffer's current + pointer is advanced to point at the character following the + string length, the encoded string, and the trailing + NULL character. + - -lwres_addr_parse() extracts an address from the -buffer b. The buffer's current pointer -b->current is presumed to point at an encoded -address: the address preceded by a 32-bit protocol family identifier -and a 16-bit length field. The encoded address is copied to -addr->address and -addr->length indicates the size in bytes of -the address that was copied. b->current is -advanced to point at the next byte of available data in the buffer -following the encoded address. - + lwres_addr_parse() + extracts an address from the buffer b. + The buffer's current pointer b->current + is presumed to point at an encoded address: the address preceded + by a 32-bit protocol family identifier and a 16-bit length + field. The encoded address is copied to + addr->address and + addr->length indicates the size in bytes + of the address that was copied. + b->current is advanced to point at the + next byte of available data in the buffer following the encoded + address. + - -lwres_getaddrsbyname() -and -lwres_getnamebyaddr() -use the -lwres_gnbaresponse_t -structure defined below: - + lwres_getaddrsbyname() + and lwres_getnamebyaddr() use the + lwres_gnbaresponse_t structure defined below: + + + typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -125,97 +137,100 @@ typedef struct { void *base; size_t baselen; } lwres_gabnresponse_t; - -The contents of this structure are not manipulated directly but -they are controlled through the - -lwres_gabn3 - - -functions. - + - -The lightweight resolver uses -lwres_getaddrsbyname() to perform foward lookups. -Hostname name is looked up using the resolver -context ctx for memory allocation. -addrtypes is a bitmask indicating which type of -addresses are to be looked up. Current values for this bitmask are -LWRES_ADDRTYPE_V4 for IPv4 addresses and -LWRES_ADDRTYPE_V6 for IPv6 addresses. Results of the -lookup are returned in *structp. - + + The contents of this structure are not manipulated directly but + they are controlled through the + + lwres_gabn3 + + functions. + - -lwres_getnamebyaddr() performs reverse lookups. -Resolver context ctx is used for memory -allocation. The address type is indicated by -addrtype: LWRES_ADDRTYPE_V4 or -LWRES_ADDRTYPE_V6. The address to be looked up is given -by addr and its length is -addrlen bytes. The result of the function call -is made available through *structp. - - + + The lightweight resolver uses + lwres_getaddrsbyname() to perform + foward lookups. + Hostname name is looked up using the + resolver + context ctx for memory allocation. + addrtypes is a bitmask indicating + which type of + addresses are to be looked up. Current values for this bitmask are + LWRES_ADDRTYPE_V4 for IPv4 addresses and + LWRES_ADDRTYPE_V6 for IPv6 addresses. Results of the + lookup are returned in *structp. + - -RETURN VALUES - -Successful calls to -lwres_string_parse() -and -lwres_addr_parse() -return -LWRES_R_SUCCESS. -Both functions return -LWRES_R_FAILURE -if the buffer is corrupt or -LWRES_R_UNEXPECTEDEND -if the buffer has less space than expected for the components of the -encoded string or address. - - -lwres_getaddrsbyname() -returns -LWRES_R_SUCCESS -on success and it returns -LWRES_R_NOTFOUND -if the hostname -name -could not be found. - - -LWRES_R_SUCCESS -is returned by a successful call to -lwres_getnamebyaddr(). - + lwres_getnamebyaddr() + performs reverse lookups. Resolver context + ctx is used for memory allocation. The + address type is indicated by addrtype: + LWRES_ADDRTYPE_V4 or + LWRES_ADDRTYPE_V6. The address to be looked up is + given by addr and its length is + addrlen bytes. The result of the + function call is made available through + *structp. + + - -Both -lwres_getaddrsbyname() -and -lwres_getnamebyaddr() -return -LWRES_R_NOMEMORY -when memory allocation requests fail and -LWRES_R_UNEXPECTEDEND -if the buffers used for sending queries and receiving replies are too -small. - + + RETURN VALUES + + Successful calls to + lwres_string_parse() + and + lwres_addr_parse() + return + LWRES_R_SUCCESS. + Both functions return + LWRES_R_FAILURE + if the buffer is corrupt or + LWRES_R_UNEXPECTEDEND + if the buffer has less space than expected for the components of the + encoded string or address. + - - -SEE ALSO - - -lwres_buffer3 -, + lwres_getaddrsbyname() + returns LWRES_R_SUCCESS on success and it + returns LWRES_R_NOTFOUND if the hostname + name could not be found. + + LWRES_R_SUCCESS + is returned by a successful call to + lwres_getnamebyaddr(). + - -lwres_gabn3 -. - + + Both + lwres_getaddrsbyname() + and + lwres_getnamebyaddr() + return + LWRES_R_NOMEMORY + when memory allocation requests fail and + LWRES_R_UNEXPECTEDEND + if the buffers used for sending queries and receiving replies are too + small. + - - + + + SEE ALSO + + lwres_buffer3 + , + + + lwres_gabn3 + . + + + + diff --git a/make/rules.in b/make/rules.in index 9c91a0ac6d..61c8d9ef3a 100644 --- a/make/rules.in +++ b/make/rules.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: rules.in,v 1.50 2005/03/31 04:21:03 marka Exp $ +# $Id: rules.in,v 1.51 2005/05/11 05:55:41 sra Exp $ ### ### Common Makefile rules for BIND 9. @@ -179,6 +179,16 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ INSTALL_DATA = @INSTALL_DATA@ +### +### Programs used when generating documentation. It's ok for these +### not to exist when not generating documentation. +### + +XSLTPROC = @XSLTPROC@ --novalid +PERL = @PERL@ +LATEX = @LATEX@ +PDFLATEX = @PDFLATEX@ + ### ### DocBook -> HTML ### DocBook -> man page @@ -186,42 +196,29 @@ INSTALL_DATA = @INSTALL_DATA@ .SUFFIXES: .docbook .html .1 .2 .3 .4 .5 .6 .7 .8 -OPENJADE = @OPENJADE@ -SGMLCATALOG = @SGMLCATALOG@ -HTMLSTYLE = @HTMLSTYLE@ -XMLDCL = @XMLDCL@ -DOCBOOK2MANSPEC = @DOCBOOK2MANSPEC@ -JADETEX = @JADETEX@ -PDFJADETEX = @PDFJADETEX@ - -ONSGMLS = onsgmls -SGMLSPL = sgmlspl - -# -# Note: this rule assumes the docbook.dsl stylesheet -# is being used. If another stylesheet is used, the -# filename 'r1.htm' in the rule might have to be -# be changed. -# .docbook.html: - ${OPENJADE} -c ${SGMLCATALOG} -t sgml -d ${HTMLSTYLE} $< - echo "" >> r1.htm - cat ${top_srcdir}/docutil/HTML_COPYRIGHT r1.htm > $@ - rm -f r1.htm + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-docbook-html.xsl $< .docbook.1: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $< + .docbook.2: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $< + .docbook.3: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $< + .docbook.4: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $< + .docbook.5: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $< + .docbook.6: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $< + .docbook.7: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $< + .docbook.8: - sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ + ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<