named-checkconf checks the syntax, but not - the semantics, of a named configuration file. -
chroot to directory so that include - directives in the configuration file are processed as if - run by a similarly chrooted named. -
Print the version of the named-checkconf - program and exit. -
Perform a check load the master zonefiles found in - named.conf. -
When loading a zonefile read the journal if it exists. -
The name of the configuration file to be checked. If not - specified, it defaults to /etc/named.conf. -
named-checkconf returns an exit status of 1 if - errors were detected and 0 otherwise. -
named-checkconf — named configuration file syntax checking tool
+named-checkconf [-v] [-j] [-t ] {filename} [directory-z]
named-checkconf + checks the syntax, but not the semantics, of a named + configuration file. +
+directory
+ chroot to directory so that
+ include
+ directives in the configuration file are processed as if
+ run by a similarly chrooted named.
+
+ Print the version of the named-checkconf + program and exit. +
+ Perform a check load the master zonefiles found in
+ named.conf.
+
+ When loading a zonefile read the journal if it exists. +
+ The name of the configuration file to be checked. If not
+ specified, it defaults to /etc/named.conf.
+
named-checkzone [-d] [-j] [-q] [-v] [-c class] [-k mode] [-n mode] [-o filename] [-t directory] [-w directory] [-D] [-W mode] {zonename} {filename}
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. -
Enable debugging. -
Quiet mode - exit code only. -
Print the version of the named-checkzone - program and exit. -
When loading the zone file read the journal if it exists. -
Specify the class of the zone. If not specified "IN" is assumed. -
Perform "check-name" checks with the specified failure mode. - 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". -
Write zone output to filename. -
chroot to directory so that include - directives in the configuration file are processed as if - run by a similarly chrooted named. -
chdir to directory so that relative - filenames in master file $INCLUDE directives work. This - is similar to the directory clause in - named.conf. -
Dump zone file in canonical format. -
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". -
The domain name of the zone being checked. -
The name of the zone file. -
named-checkzone returns an exit status of 1 if - errors were detected and 0 otherwise. -
named-checkzone — zone file validity checking tool
+named-checkzone [-d] [-j] [-q] [-v] [-c ] [class-k ] [mode-n ] [mode-o ] [filename-t ] [directory-w ] [directory-D] [-W ] {zonename} {filename}mode
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. +
++ Enable debugging. +
+ Quiet mode - exit code only. +
+ Print the version of the named-checkzone + program and exit. +
+ When loading the zone file read the journal if it exists. +
class+ Specify the class of the zone. If not specified "IN" is assumed. +
mode+ Perform "check-name" checks with + the specified failure mode. + Possible modes are "fail", + "warn" (default) and + "ignore". +
mode+ Specify whether NS records should be checked to see if they + are addresses. Possible modes are "fail", + "warn" (default) and + "ignore". +
filename
+ Write zone output to filename.
+
directory
+ chroot to directory so that
+ include
+ directives in the configuration file are processed as if
+ run by a similarly chrooted named.
+
directory
+ chdir to directory so that
+ relative
+ filenames in master file $INCLUDE directives work. This
+ is similar to the directory clause in
+ named.conf.
+
+ Dump zone file in canonical format. +
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". +
+ The domain name of the zone being checked. +
+ The name of the zone file. +
dig — DNS lookup utility
+dig [@server] [-b ] [address-c ] [class-f ] [filename-k ] [filename-p ] [port#-t ] [type-x ] [addr-y ] [name:key-4] [-6] [name] [type] [class] [queryopt...]
dig [-h]
dig [global-queryopt...] [query...]
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 -h 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.
+
+ 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.
+
+
+
+ The -b 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
+ -c option. class is
+ any valid
+ class, such as HS for Hesiod records or CH for CHAOSNET records.
+
+ The -f 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
+ -p 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 -4 option forces dig
+ to only
+ use IPv4 query transport. The -6 option forces
+ dig to only use IPv6 query transport.
+
+ The -t 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
+ -x 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
+ -x 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 -i 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 -k option. You can also specify the TSIG
+ key itself on the command line using the -y 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-keygen(8).
-
-
dig [@server] [-b address] [-c class] [-f filename] [-k filename] [-p port#] [-t type] [-x addr] [-y name:key] [-4] [-6] [name] [type] [class] [queryopt...]
dig [-h]
dig [global-queryopt...] [query...]
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 -h 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.
A typical invocation of dig looks like: -
dig @server name typewhere: + Caution should be taken when using the
-y option on
+ multi-user systems as the key can be visible in the output from
+ ps(1)
+ 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.
+
+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 +keyword=value.
+ The query options are:
-
serveris 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.
nameis the name of the resource record that is to be looked up.
typeindicates 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.
The -b 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
--c option. class is any valid
-class, such as HS for Hesiod records or CH for CHAOSNET records.
The -f 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
--p 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 -4 option forces dig to only
-use IPv4 query transport. The -6 option forces
-dig to only use IPv6 query transport.
The -t 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
--x 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
--x 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 -i 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 -k option. You can also specify the TSIG
-key itself on the command line using the -y 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-keygen(8).
+
+[no]tcp+ 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. +
+[no]vc
+ 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".
+
+[no]ignore+ Ignore truncation in UDP responses instead of retrying with TCP. + By + default, TCP retries are performed. +
+domain=somename
+ 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.
+
+[no]search
+ 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.
+
+[no]defname
+ Deprecated, treated as a synonym for +[no]search
+
+[no]aaonly+ Sets the "aa" flag in the query. +
+[no]aaflag
+ A synonym for +[no]aaonly.
+
+[no]adflag+ 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. +
+[no]cdflag+ Set [do not set] the CD (checking disabled) bit in the query. + This + requests the server to not perform DNSSEC validation of + responses. +
+[no]cl+ Display [do not display] the CLASS when printing the record. +
+[no]ttlid+ Display [do not display] the TTL when printing the record. +
+[no]recurse
+ 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.
+
+[no]nssearch+ 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. +
+[no]trace+ 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. +
+[no]cmd+ 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. +
+[no]short+ Provide a terse answer. The default is to print the answer in a + verbose form. +
+[no]identify
+ 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.
+
+[no]comments+ Toggle the display of comment lines in the output. The default + is to + print comments. +
+[no]stats+ 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. +
+[no]qr+ Print [do not print] the query as it is sent. + By default, the query is not printed. +
+[no]question+ 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. +
+[no]answer+ Display [do not display] the answer section of a reply. The + default + is to display it. +
+[no]authority+ Display [do not display] the authority section of a reply. The + default is to display it. +
+[no]additional+ Display [do not display] the additional section of a reply. + The default is to display it. +
+[no]all+ Set or clear all display flags. +
+time=T
-Caution should be taken when using the -y option on
-multi-user systems as the key can be visible in the output from
-ps(1) 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.
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 +keyword=value.
-The query options are:
+ 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.
+
+tries=T
+ 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.
+
+retry=T
+ 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.
+
+ndots=D
+ 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
+ search or domain directive in
+ /etc/resolv.conf.
+
+bufsize=B
+ 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.
+
+[no]multiline+ 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. +
+[no]fail+ 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. +
+[no]besteffort+ Attempt to display the contents of messages which are malformed. + The default is to not display malformed answers. +
+[no]dnssec+ Requests DNSSEC records be sent by setting the DNSSEC OK bit + (DO) + in the OPT record in the additional section of the query. +
+[no]sigchase+ Chase DNSSEC signature chains. Requires dig be compiled with + -DDIG_SIGCHASE. +
+trusted-key=####
+ Specify a trusted key to be used with
+ +sigchase.
+ Requires dig be compiled with -DDIG_SIGCHASE.
+
+[no]topdown+ When chasing DNSSEC signature chains perform a top down + validation. + Requires dig be compiled with -DDIG_SIGCHASE. +
-
+[no]tcpUse [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.
+[no]vcUse [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".
+[no]ignoreIgnore truncation in UDP responses instead of retrying with TCP. By -default, TCP retries are performed.
+domain=somenameSet 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.
+[no]searchUse [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.
+[no]defnameDeprecated, treated as a synonym for +[no]search
+[no]aaonlySets the "aa" flag in the query.
+[no]aaflagA synonym for +[no]aaonly.
+[no]adflagSet [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.
+[no]cdflagSet [do not set] the CD (checking disabled) bit in the query. This -requests the server to not perform DNSSEC validation of responses.
+[no]clDisplay [do not display] the CLASS when printing the record.
+[no]ttlidDisplay [do not display] the TTL when printing the record.
+[no]recurseToggle 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.
+[no]nssearchWhen 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.
+[no]traceToggle 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.
+[no]cmdtoggles 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.
+[no]shortProvide a terse answer. The default is to print the answer in a -verbose form.
+[no]identifyShow [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.
+[no]commentsToggle the display of comment lines in the output. The default is to -print comments.
+[no]statsThis 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.
+[no]qrPrint [do not print] the query as it is sent. -By default, the query is not printed.
+[no]questionPrint [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.
+[no]answerDisplay [do not display] the answer section of a reply. The default -is to display it.
+[no]authorityDisplay [do not display] the authority section of a reply. The -default is to display it.
+[no]additionalDisplay [do not display] the additional section of a reply. -The default is to display it.
+[no]allSet or clear all display flags.
+time=T
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.
+tries=TSets 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.
+retry=TSets 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.
+ndots=DSet 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
-search or domain directive in
-/etc/resolv.conf.
+bufsize=BSet 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.
+[no]multilinePrint 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.
+[no]failDo 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.
+[no]besteffortAttempt to display the contents of messages which are malformed. -The default is to not display malformed answers.
+[no]dnssecRequests DNSSEC records be sent by setting the DNSSEC OK bit (DO) -in the OPT record in the additional section of the query.
+[no]sigchaseChase DNSSEC signature chains. Requires dig be compiled with --DDIG_SIGCHASE.
+trusted-key=####Specify a trusted key to be used with +sigchase.
-Requires dig be compiled with -DDIG_SIGCHASE.
+[no]topdownWhen chasing DNSSEC signature chains perform a top down validation. -Requires dig be compiled with -DDIG_SIGCHASE.
The BIND 9 implementation of dig supports
-specifying multiple queries on the command line (in addition to
-supporting the -f 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 +[no]cmd 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. + +
+ The BIND 9 implementation of dig
+ supports
+ specifying multiple queries on the command line (in addition to
+ supporting the -f 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 +[no]cmd option) can be
+ overridden by a query-specific set of query options. For example:
+
+dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr ++
+ shows how dig could be used from the
+ command line
+ to make three lookups: an ANY query for www.isc.org, a
+ reverse lookup of 127.0.0.1 and a query for the NS records of
+ isc.org.
-A global query option of +qr is applied, so
-that dig shows the initial query it made for each
-lookup. The final query has a local query option of
-+noqr which means that dig
-will not print the initial query when it looks up the NS records for
-isc.org.
+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.
+
+host [-aCdlnrTwv] [-c class] [-N ndots] [-R number] [-t type] [-W wait] [-m flag] [-4] [-6] {name} [server]
host -is a simple utility for performing DNS lookups. -It is normally used to convert names to IP addresses and vice versa. -When no arguments or options are given, -host -prints a short summary of its command line arguments and options.
name is the domain name that is to be looked
-up. It can also be a dotted-decimal IPv4 address or a colon-delimited
-IPv6 address, in which case host will by default
-perform a reverse lookup for that address.
-server is an optional argument which is either
-the name or IP address of the name server that host
-should query instead of the server or servers listed in
-/etc/resolv.conf.
The -a (all) option is equivalent to setting the
--v option and asking host to make
-a query of type ANY.
When the -C option is used, host
-will attempt to display the SOA records for zone
-name from all the listed authoritative name
-servers for that zone. The list of name servers is defined by the NS
-records that are found for the zone.
The -c option instructs to make a DNS query of class
-class. This can be used to lookup Hesiod or
-Chaosnet class resource records. The default class is IN (Internet).
Verbose output is generated by host when the
--d or -v option is used. The two
-options are equivalent. They have been provided for backwards
-compatibility. In previous versions, the -d option
-switched on debugging traces and -v enabled verbose
-output.
List mode is selected by the -l 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 -a
-all records will be printed.
The -i
-option specifies that reverse lookups of IPv6 addresses should
-use the IP6.INT domain as defined in RFC1886.
-The default is to use IP6.ARPA.
The -N option sets the number of dots that have to be
-in name for it to be considered absolute. The
-default value is that defined using the ndots statement in
-/etc/resolv.conf, or 1 if no ndots statement is
-present. Names with fewer dots are interpreted as relative names and
-will be searched for in the domains listed in the search
-or domain directive in
-/etc/resolv.conf.
The number of UDP retries for a lookup can be changed with the
--R option. number indicates
-how many times host will repeat a query that does
-not get answered. The default number of retries is 1. If
-number is negative or zero, the number of
-retries will default to 1.
Non-recursive queries can be made via the -r 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
--r option enables host to mimic
-the behaviour of a name server by making non-recursive queries and
-expecting to receive answers to those queries that are usually
-referrals to other name servers.
By default host uses UDP when making queries. The
--T 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 -4 option forces host to only
-use IPv4 query transport. The -6 option forces
-host to only use IPv6 query transport.
The -t 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
--C option was given, queries will be made for SOA
-records, and if name is a dotted-decimal IPv4
-address or colon-delimited IPv6 address, host will
-query for PTR records. If a query type of IXFR is chosen the starting
-serial number can be specified by appending an equal followed by the
-starting serial number (e.g. -t IXFR=12345678).
The time to wait for a reply can be controlled through the
--W and -w options. The
--W option makes host wait for
-wait seconds. If wait
-is less than one, the wait interval is set to one second. When the
--w 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 -m can be used to set the memory usage debugging flags
-record, usage and
-trace.
host — DNS lookup utility
+host [-aCdlnrTwv] [-c ] [class-N ] [ndots-R ] [number-t ] [type-W ] [wait-m ] [flag-4] [-6] {name} [server]
host + is a simple utility for performing DNS lookups. + It is normally used to convert names to IP addresses and vice versa. + When no arguments or options are given, + host + prints a short summary of its command line arguments and options. +
+name is the domain name that is to be
+ looked
+ up. It can also be a dotted-decimal IPv4 address or a colon-delimited
+ IPv6 address, in which case host will by
+ default
+ perform a reverse lookup for that address.
+ server is an optional argument which
+ is either
+ the name or IP address of the name server that host
+ should query instead of the server or servers listed in
+ /etc/resolv.conf.
+
+ The -a (all) option is equivalent to setting the
+ -v option and asking host to make
+ a query of type ANY.
+
+ When the -C option is used, host
+ will attempt to display the SOA records for zone
+ name from all the listed
+ authoritative name
+ servers for that zone. The list of name servers is defined by the NS
+ records that are found for the zone.
+
+ The -c option instructs to make a DNS query of class
+ class. This can be used to lookup
+ Hesiod or
+ Chaosnet class resource records. The default class is IN (Internet).
+
+ Verbose output is generated by host when
+ the
+ -d or -v option is used. The two
+ options are equivalent. They have been provided for backwards
+ compatibility. In previous versions, the -d option
+ switched on debugging traces and -v enabled verbose
+ output.
+
+ List mode is selected by the -l 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 -a
+ all records will be printed.
+
+ The -i
+ option specifies that reverse lookups of IPv6 addresses should
+ use the IP6.INT domain as defined in RFC1886.
+ The default is to use IP6.ARPA.
+
+ The -N option sets the number of dots that have to be
+ in name for it to be considered
+ absolute. The
+ default value is that defined using the ndots statement in
+ /etc/resolv.conf, or 1 if no ndots
+ statement is
+ present. Names with fewer dots are interpreted as relative names and
+ will be searched for in the domains listed in the search
+ or domain directive in
+ /etc/resolv.conf.
+
+ The number of UDP retries for a lookup can be changed with the
+ -R option. number
+ indicates
+ how many times host will repeat a query
+ that does
+ not get answered. The default number of retries is 1. If
+ number is negative or zero, the
+ number of
+ retries will default to 1.
+
+ Non-recursive queries can be made via the -r 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
+ -r option enables host
+ to mimic
+ the behaviour of a name server by making non-recursive queries and
+ expecting to receive answers to those queries that are usually
+ referrals to other name servers.
+
+ By default host uses UDP when making
+ queries. The
+ -T 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 -4 option forces host to only
+ use IPv4 query transport. The -6 option forces
+ host to only use IPv6 query transport.
+
+ The -t 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
+ -C option was given, queries will be made for SOA
+ records, and if name is a
+ dotted-decimal IPv4
+ address or colon-delimited IPv6 address, host will
+ query for PTR records. If a query type of IXFR is chosen the starting
+ serial number can be specified by appending an equal followed by the
+ starting serial number (e.g. -t IXFR=12345678).
+
+ The time to wait for a reply can be controlled through the
+ -W and -w options. The
+ -W option makes host
+ wait for
+ wait seconds. If wait
+ is less than one, the wait interval is set to one second. When the
+ -w 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 -m can be used to set the memory usage debugging
+ flags
+ record, usage and
+ trace.
+
nslookup — query Internet name servers interactively
+nslookup [-option] [name | -] [server]
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. +
++ Interactive mode is entered in the following cases: +
++ when no arguments are given (the default name server will be used) +
+ when the first argument is a hyphen (-) and the second argument is + the host name or Internet address of a name server. +
+
++ Non-interactive mode is used when the name or Internet address of the + host to be looked up is given as the first argument. The optional second + argument specifies the host name or address of a name server. +
++ Options can also be specified on the command line if they precede the + arguments and are prefixed with a hyphen. For example, to + change the default query type to host information, and the initial + timeout to 10 seconds, type: +
++nslookup -query=hinfo -timeout=10 +
+
++ Look up information for host using the current default server or + using server, if specified. If host is an Internet address and + the query type is A or PTR, the name of the host is returned. + If host is a name and does not have a trailing period, the + search list is used to qualify the name. +
++ To look up a host not in the current domain, append a period to + the name. +
+server domainlserver domain
+ Change the default server to domain; lserver uses the initial
+ server to look up information about domain, while server uses
+ the current default server. If an authoritative answer can't be
+ found, the names of servers that might have the answer are
+ returned.
+
root+ not implemented +
finger+ not implemented +
ls+ not implemented +
view+ not implemented +
help+ not implemented +
?+ not implemented +
exit+ Exits the program. +
set
+ keyword[=value]+ This command is used to change state information that affects + the lookups. Valid keywords are: +
+all+ Prints the current values of the frequently used + options to set. + Information about the current default + server and host is also printed. +
class=value+ Change the query class to one of: +
+IN+ the Internet class +
CH+ the Chaos class +
HS+ the Hesiod class +
ANY+ wildcard +
+ The class specifies the protocol group of the information. - - - -
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.
Interactive mode is entered in the following cases: -
when no arguments are given (the default name server will be used)
when the first argument is a hyphen (-) and the second argument is -the host name or Internet address of a name server.
Non-interactive mode is used when the name or Internet address of the -host to be looked up is given as the first argument. The optional second -argument specifies the host name or address of a name server.
Options can also be specified on the command line if they precede the -arguments and are prefixed with a hyphen. For example, to -change the default query type to host information, and the initial timeout to 10 seconds, type: -
Look up information for host using the current default server or -using server, if specified. If host is an Internet address and -the query type is A or PTR, the name of the host is returned. -If host is a name and does not have a trailing period, the -search list is used to qualify the name.
To look up a host not in the current domain, append a period to -the name.
server domainlserver domainChange 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.
rootnot implemented
fingernot implemented
lsnot implemented
viewnot implemented
helpnot implemented
?not implemented
exitExits the program.
set keyword[=value]This command is used to change state information that affects -the lookups. Valid keywords are: -
allPrints the current values of the frequently used - options to set. Information about the current default - server and host is also printed. -
class=valueChange the query class to one of: -
INthe Internet class
CHthe Chaos class
HSthe Hesiod class
ANYwildcard
(Default = IN; abbreviation = cl) -
[no]debugTurn debugging mode on. A lot more information is - printed about the packet sent to the server and the - resulting answer. -
(Default = nodebug; abbreviation = [no]deb) -
[no]d2Turn debugging mode on. A lot more information is - printed about the packet sent to the server and the - resulting answer. -
(Default = nod2) -
domain=nameSets the search list to name. -
[no]searchIf the lookup request contains at least one period but - doesn't end with a trailing period, append the domain - names in the domain search list to the request until an - answer is received. -
(Default = search) -
port=valueChange the default TCP/UDP name server port to value. -
(Default = 53; abbreviation = po) -
querytype=valuetype=valueChange the top of the information query. -
(Default = A; abbreviations = q, ty) -
[no]recurseTell the name server to query other servers if it does not have the - information. -
(Default = recurse; abbreviation = [no]rec) -
retry=numberSet the number of retries to number. -
timeout=numberChange the initial timeout interval for waiting for a - reply to number seconds. -
[no]vcAlways use a virtual circuit when sending requests to the server. -
(Default = novc) -
+ (Default = IN; abbreviation = cl) +
+
+ [no]debug+ Turn debugging mode on. A lot more information is + printed about the packet sent to the server and the + resulting answer. +
++ (Default = nodebug; abbreviation = [no]deb) +
+
+ [no]d2+ Turn debugging mode on. A lot more information is + printed about the packet sent to the server and the + resulting answer. +
++ (Default = nod2) +
+domain=name
+ Sets the search list to name.
+
+ [no]search+ If the lookup request contains at least one period but + doesn't end with a trailing period, append the domain + names in the domain search list to the request until an + answer is received. +
++ (Default = search) +
+port=value
+ Change the default TCP/UDP name server port to value.
+
+ (Default = 53; abbreviation = po) +
+querytype=valuetype=value+ Change the top of the information query. +
++ (Default = A; abbreviations = q, ty) +
+
+ [no]recurse+ Tell the name server to query other servers if it does not + have the + information. +
++ (Default = recurse; abbreviation = [no]rec) +
+retry=number+ Set the number of retries to number. +
timeout=number+ Change the initial timeout interval for waiting for a + reply to number seconds. +
+ [no]vc+ Always use a virtual circuit when sending requests to the + server. +
++ (Default = novc) +
++
+dnssec-keygen {-a algorithm} {-b keysize} {-n nametype} [-c class] [-e] [-f flag] [-g generator] [-h] [-k] [-p protocol] [-r randomdev] [-s strength] [-t type] [-v level] {name}
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. -
Selects the cryptographic algorithm. The value of
- algorithm 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. -
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 owner type of the key. The value of
- nametype 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.
-
Indicates that the DNS record containing the key should have - the specified class. If not specified, class IN is used. -
If generating an RSAMD5/RSASHA1 key, use a large exponent. -
Set the specified flag in the flag field of the KEY/DNSKEY record. - The only recognized flag is KSK (Key Signing Key) DNSKEY. -
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. -
Prints a short summary of the options and arguments to - dnssec-keygen. -
Generate KEY records rather than DNSKEY records. -
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. -
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 strength value of the key. The strength is - a number between 0 and 15, and currently has no defined - purpose in DNSSEC. -
Indicates the use of the key. type 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.
-
Sets the debugging level. -
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. -
aaa is the numeric representation of the + +
+ +dnssec-keygen — DNSSEC key generation tool
+dnssec-keygen {-a algorithm} {-b keysize} {-n nametype} [-c ] [class-e] [-f ] [flag-g ] [generator-h] [-k] [-p ] [protocol-r ] [randomdev-s ] [strength-t ] [type-v ] {name}level
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. +
+algorithm
+ Selects the cryptographic algorithm. The value of
+ algorithm 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. +
+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. +
nametype
+ Specifies the owner type of the key. The value of
+ nametype 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.
+
class+ Indicates that the DNS record containing the key should have + the specified class. If not specified, class IN is used. +
+ If generating an RSAMD5/RSASHA1 key, use a large exponent. +
flag+ Set the specified flag in the flag field of the KEY/DNSKEY record. + The only recognized flag is KSK (Key Signing Key) DNSKEY. +
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. +
+ Prints a short summary of the options and arguments to + dnssec-keygen. +
+ Generate KEY records rather than DNSKEY records. +
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. +
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.
+
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. +
type
+ Indicates the use of the key. type 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.
+
level+ Sets the debugging level. +
+ 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.
+
aaa is the numeric representation
+ of the
algorithm.
-
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. -
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. -
Both .key and .private - files are generated for symmetric encryption algorithm such as - HMAC-MD5, even though the public and private key are equivalent. -
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 -
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 -
dnssec-signzone(8), - BIND 9 Administrator Reference Manual, - RFC 2535, - RFC 2845, - RFC 2539. -
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.
+
+ 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.
+
+ Both .key and .private
+ files are generated for symmetric encryption algorithm such as
+ HMAC-MD5, even though the public and private key are equivalent.
+
+ 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
+
+ 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
+
dnssec-signzone [-a] [-c class] [-d directory] [-e end-time] [-f output-file] [-g] [-h] [-k key] [-l domain] [-i interval] [-j jitter] [-n nthreads] [-o origin] [-p] [-r randomdev] [-s start-time] [-t] [-v level] [-z] {zonefile} [key...]
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. -
Verify all generated signatures. -
Specifies the DNS class of the zone. -
Treat specified key as a key signing key ignoring any - key flags. This option may be specified multiple times. -
Generate a DLV set in addition to the key (DNSKEY) and DS sets. - The domain is appended to the name of the records. -
Look for keyset files in
- directory as the directory
-
Generate DS records for child zones from keyset files. - Existing DS records will be removed. -
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 start-time 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
- expire. As with start-time, 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 end-time is
- specified, 30 days from the start time is used as a default.
-
The name of the output file containing the signed zone. The - default is to append .signed to the - input file. -
Prints a short summary of the options and arguments to - dnssec-signzone. -
When a previously signed zone is passed as input, records
- may be resigned. The interval 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
- end-time or start-time
- 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 jitter 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. -
Specifies the number of threads to use. By default, one - thread is started for each detected CPU. -
The zone origin. If not specified, the name of the zone file - is assumed to be the origin. -
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. -
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. -
Print statistics at completion. -
Sets the debugging level. -
Ignore KSK flag on key when determining what to sign. -
The file containing the zone to be signed. - Sets the debugging level. -
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 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 -
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. -
dnssec-signzone — DNSSEC zone signing tool
+dnssec-signzone [-a] [-c ] [class-d ] [directory-e ] [end-time-f ] [output-file-g] [-h] [-k ] [key-l ] [domain-i ] [interval-j ] [jitter-n ] [nthreads-o ] [origin-p] [-r ] [randomdev-s ] [start-time-t] [-v ] [level-z] {zonefile} [key...]
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.
+
+ Verify all generated signatures. +
class+ Specifies the DNS class of the zone. +
key+ Treat specified key as a key signing key ignoring any + key flags. This option may be specified multiple times. +
domain+ Generate a DLV set in addition to the key (DNSKEY) and DS sets. + The domain is appended to the name of the records. +
directory
+ Look for keyset files in
+ directory as the directory
+
+ Generate DS records for child zones from keyset files. + Existing DS records will be removed. +
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 start-time is specified, the current
+ time minus 1 hour (to allow for clock skew) is used.
+
end-time
+ Specify the date and time when the generated RRSIG records
+ expire. As with start-time, 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 end-time is
+ specified, 30 days from the start time is used as a default.
+
output-file
+ The name of the output file containing the signed zone. The
+ default is to append .signed to
+ the
+ input file.
+
+ Prints a short summary of the options and arguments to + dnssec-signzone. +
interval
+ When a previously signed zone is passed as input, records
+ may be resigned. The interval 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
+ end-time or start-time
+ 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.
+
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 jitter 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. +
+ncpus+ Specifies the number of threads to use. By default, one + thread is started for each detected CPU. +
origin+ The zone origin. If not specified, the name of the zone file + is assumed to be the origin. +
+ 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. +
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.
+
+ Print statistics at completion. +
level+ Sets the debugging level. +
+ Ignore KSK flag on key when determining what to sign. +
+ The file containing the zone to be signed. + Sets the debugging level. +
+ 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 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
+
+ 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.
+
lwresd [-C config-file] [-d debug-level] [-f] [-g] [-i pid-file] [-n #cpus] [-P port] [-p port] [-s] [-t directory] [-u user] [-v]
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. -
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
- nameserver entries, lwresd
- sends recursive DNS queries to those servers. This is similar
- to the use of forwarders in a caching name server. If no
- nameserver 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.
-
Use config-file as the - configuration file instead of the default, - /etc/resolv.conf. -
Set the daemon's debug level to debug-level. - Debugging traces from lwresd become - more verbose as the debug level increases. -
Run the server in the foreground (i.e. do not daemonize). -
Run the server in the foreground and force all logging - to stderr. -
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. -
Listen for lightweight resolver queries on port - port. If - not specified, the default is port 921. -
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. -
Write memory usage statistics to stdout - on exit. -
Note: This option is mainly of interest to BIND 9 developers - and may be removed or changed in a future release. -
chroot() to directory after
- processing the command line arguments, but before
- reading the configuration file.
-
| Warning |
This option should be used in conjunction with the
- |
setuid() to user after completing
- privileged operations, such as creating sockets that
- listen on privileged ports.
-
Report the version number and exit. -
The default configuration file. -
The default process-id file. -
lwresd — lightweight resolver daemon
+lwresd [-C ] [config-file-d ] [debug-level-f] [-g] [-i ] [pid-file-n ] [#cpus-P ] [port-p ] [port-s] [-t ] [directory-u ] [user-v]
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. +
++ 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
+ nameserver entries, lwresd
+ sends recursive DNS queries to those servers. This is similar
+ to the use of forwarders in a caching name server. If no
+ nameserver 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.
+
config-file
+ Use config-file as the
+ configuration file instead of the default,
+ /etc/resolv.conf.
+
debug-level
+ Set the daemon's debug level to debug-level.
+ Debugging traces from lwresd become
+ more verbose as the debug level increases.
+
+ Run the server in the foreground (i.e. do not daemonize). +
+ Run the server in the foreground and force all logging
+ to stderr.
+
#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.
+
port
+ Listen for lightweight resolver queries on port
+ port. If
+ not specified, the default is port 921.
+
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.
+
+ 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. +
+directorychroot()
+ to directory after
+ processing the command line arguments, but before
+ reading the configuration file.
+
+ This option should be used in conjunction with the
+ -u 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.
+
usersetuid()
+ to user after completing
+ privileged operations, such as creating sockets that
+ listen on privileged ports.
+
+ Report the version number and exit. +
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: // to end of line -
Unix style: # to end of line -
masters string [ port integer ] {
- ( masters | ipv4_address [port integer] |
- ipv6_address [port integer] ) [ key string ]; ...
-};
server ( ipv4_address[/prefixlen] | ipv6_address[/prefixlen] ) {
- bogus boolean;
- edns boolean;
- provide-ixfr boolean;
- request-ixfr boolean;
- keys server_key;
- transfers integer;
- transfer-format ( many-answers | one-answer );
- transfer-source ( ipv4_address | * )
- [ port ( integer | * ) ];
- transfer-source-v6 ( ipv6_address | * )
- [ port ( integer | * ) ];
+
+
named.conf — configuration file for named
named.conf
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: // to end of line +
++ Unix style: # to end of line +
+
+acl string { address_match_element; ... };
- support-ixfr boolean; // obsolete
-};
+masters string [ port integer ] {
+ ( masters | ipv4_address [port integer] |
+ ipv6_address [port integer] ) [ key string ]; ...
+};
+
+server ( ipv4_address[/prefixlen] | ipv6_address[/prefixlen] ) {
+ bogus boolean;
+ edns boolean;
+ provide-ixfr boolean;
+ request-ixfr boolean;
+ keys server_key;
+ transfers integer;
+ transfer-format ( many-answers | one-answer );
+ transfer-source ( ipv4_address | * )
+ [ port ( integer | * ) ];
+ transfer-source-v6 ( ipv6_address | * )
+ [ port ( integer | * ) ];
+
+ support-ixfr boolean; // obsolete
+};
+
+controls {
+ inet ( ipv4_address | ipv6_address | * )
+ [ port ( integer | * ) ]
+ allow { address_match_element; ... }
+ [ keys { string; ... } ];
+ unix unsupported; // not implemented
+};
+
+logging {
+ channel string {
+ file log_file;
+ syslog optional_facility;
null;
stderr;
- severity log_severity;
- print-time boolean;
- print-severity boolean;
- print-category boolean;
+ severity log_severity;
+ print-time boolean;
+ print-severity boolean;
+ print-category boolean;
};
- category string { string; ... };
-};
+lwres {
+ listen-on [ port integer ] {
+ ( ipv4_address | ipv6_address ) [ port integer ]; ...
};
- view string optional_class;
- search { string; ... };
- ndots integer;
-};
options {
- avoid-v4-udp-ports { port; ... };
- avoid-v6-udp-ports { port; ... };
- blackhole { address_match_element; ... };
- coresize size;
- datasize size;
- directory quoted_string;
- dump-file quoted_string;
- files size;
- heartbeat-interval integer;
- host-statistics boolean; // not implemented
- host-statistics-max number; // not implemented
- hostname ( quoted_string | none );
- interface-interval integer;
- listen-on [ port integer ] { address_match_element; ... };
- listen-on-v6 [ port integer ] { address_match_element; ... };
- match-mapped-addresses boolean;
- memstatistics-file quoted_string;
- pid-file ( quoted_string | none );
- port integer;
- querylog boolean;
- recursing-file quoted_string;
- random-device quoted_string;
- recursive-clients integer;
- serial-query-rate integer;
- server-id ( quoted_string | none |;
- stacksize size;
- statistics-file quoted_string;
- statistics-interval integer; // not yet implemented
- tcp-clients integer;
- tcp-listen-queue integer;
- tkey-dhkey quoted_string integer;
- tkey-gssapi-credential quoted_string;
- tkey-domain quoted_string;
- transfers-per-ns integer;
- transfers-in integer;
- transfers-out integer;
- use-ixfr boolean;
- version ( quoted_string | none );
- allow-recursion { address_match_element; ... };
- sortlist { address_match_element; ... };
- topology { address_match_element; ... }; // not implemented
- auth-nxdomain boolean; // default changed
- minimal-responses boolean;
- recursion boolean;
- rrset-order {
- [ class string ] [ type string ]
- [ name quoted_string ] string string; ...
+ view string optional_class;
+ search { string; ... };
+ ndots integer;
+};
+
+options {
+ avoid-v4-udp-ports { port; ... };
+ avoid-v6-udp-ports { port; ... };
+ blackhole { address_match_element; ... };
+ coresize size;
+ datasize size;
+ directory quoted_string;
+ dump-file quoted_string;
+ files size;
+ heartbeat-interval integer;
+ host-statistics boolean; // not implemented
+ host-statistics-max number; // not implemented
+ hostname ( quoted_string | none );
+ interface-interval integer;
+ listen-on [ port integer ] { address_match_element; ... };
+ listen-on-v6 [ port integer ] { address_match_element; ... };
+ match-mapped-addresses boolean;
+ memstatistics-file quoted_string;
+ pid-file ( quoted_string | none );
+ port integer;
+ querylog boolean;
+ recursing-file quoted_string;
+ random-device quoted_string;
+ recursive-clients integer;
+ serial-query-rate integer;
+ server-id ( quoted_string | none |;
+ stacksize size;
+ statistics-file quoted_string;
+ statistics-interval integer; // not yet implemented
+ tcp-clients integer;
+ tcp-listen-queue integer;
+ tkey-dhkey quoted_string integer;
+ tkey-gssapi-credential quoted_string;
+ tkey-domain quoted_string;
+ transfers-per-ns integer;
+ transfers-in integer;
+ transfers-out integer;
+ use-ixfr boolean;
+ version ( quoted_string | none );
+ allow-recursion { address_match_element; ... };
+ sortlist { address_match_element; ... };
+ topology { address_match_element; ... }; // not implemented
+ auth-nxdomain boolean; // default changed
+ minimal-responses boolean;
+ recursion boolean;
+ rrset-order {
+ [ class string ] [ type string ]
+ [ name quoted_string ] string string; ...
};
- provide-ixfr boolean;
- request-ixfr boolean;
- rfc2308-type1 boolean; // not yet implemented
- additional-from-auth boolean;
- additional-from-cache boolean;
- query-source querysource4;
- query-source-v6 querysource6;
- cleaning-interval integer;
- min-roots integer; // not implemented
- lame-ttl integer;
- max-ncache-ttl integer;
- max-cache-ttl integer;
- transfer-format ( many-answers | one-answer );
- max-cache-size size_no_default;
- check-names ( master | slave | response )
- ( fail | warn | ignore );
- cache-file quoted_string;
- suppress-initial-notify boolean; // not yet implemented
- preferred-glue string;
- dual-stack-servers [ port integer ] {
- ( quoted_string [port integer] |
- ipv4_address [port integer] |
- ipv6_address [port integer] ); ...
+ provide-ixfr boolean;
+ request-ixfr boolean;
+ rfc2308-type1 boolean; // not yet implemented
+ additional-from-auth boolean;
+ additional-from-cache boolean;
+ query-source querysource4;
+ query-source-v6 querysource6;
+ cleaning-interval integer;
+ min-roots integer; // not implemented
+ lame-ttl integer;
+ max-ncache-ttl integer;
+ max-cache-ttl integer;
+ transfer-format ( many-answers | one-answer );
+ max-cache-size size_no_default;
+ check-names ( master | slave | response )
+ ( fail | warn | ignore );
+ cache-file quoted_string;
+ suppress-initial-notify boolean; // not yet implemented
+ preferred-glue string;
+ dual-stack-servers [ port integer ] {
+ ( quoted_string [port integer] |
+ ipv4_address [port integer] |
+ ipv6_address [port integer] ); ...
}
- edns-udp-size integer;
- root-delegation-only [ exclude { quoted_string; ... } ];
- disable-algorithms string { string; ... };
- dnssec-enable boolean;
- dnssec-lookaside string trust-anchor string;
- dnssec-must-be-secure string boolean;
+ edns-udp-size integer;
+ root-delegation-only [ exclude { quoted_string; ... } ];
+ disable-algorithms string { string; ... };
+ dnssec-enable boolean;
+ dnssec-lookaside string trust-anchor string;
+ dnssec-must-be-secure string boolean;
- dialup dialuptype;
- ixfr-from-differences ixfrdiff;
+ dialup dialuptype;
+ ixfr-from-differences ixfrdiff;
- allow-query { address_match_element; ... };
- allow-query-cache { address_match_element; ... };
- allow-transfer { address_match_element; ... };
- allow-update { address_match_element; ... };
- allow-update-forwarding { address_match_element; ... };
+ allow-query { address_match_element; ... };
+ allow-query-cache { address_match_element; ... };
+ allow-transfer { address_match_element; ... };
+ allow-update { address_match_element; ... };
+ allow-update-forwarding { address_match_element; ... };
- notify notifytype;
- notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
- notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
- notify-delay seconds;
- also-notify [ port integer ] { ( ipv4_address | ipv6_address )
- [ port integer ]; ... };
- allow-notify { address_match_element; ... };
+ notify notifytype;
+ notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
+ notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
+ notify-delay seconds;
+ also-notify [ port integer ] { ( ipv4_address | ipv6_address )
+ [ port integer ]; ... };
+ allow-notify { address_match_element; ... };
- forward ( first | only );
- forwarders [ port integer ] {
- ( ipv4_address | ipv6_address ) [ port integer ]; ...
+ forward ( first | only );
+ forwarders [ port integer ] {
+ ( ipv4_address | ipv6_address ) [ port integer ]; ...
};
- max-journal-size size_no_default;
- max-transfer-time-in integer;
- max-transfer-time-out integer;
- max-transfer-idle-in integer;
- max-transfer-idle-out integer;
- max-retry-time integer;
- min-retry-time integer;
- max-refresh-time integer;
- min-refresh-time integer;
- multi-master boolean;
- sig-validity-interval integer;
+ max-journal-size size_no_default;
+ max-transfer-time-in integer;
+ max-transfer-time-out integer;
+ max-transfer-idle-in integer;
+ max-transfer-idle-out integer;
+ max-retry-time integer;
+ min-retry-time integer;
+ max-refresh-time integer;
+ min-refresh-time integer;
+ multi-master boolean;
+ sig-validity-interval integer;
- transfer-source ( ipv4_address | * )
- [ port ( integer | * ) ];
- transfer-source-v6 ( ipv6_address | * )
- [ port ( integer | * ) ];
+ transfer-source ( ipv4_address | * )
+ [ port ( integer | * ) ];
+ transfer-source-v6 ( ipv6_address | * )
+ [ port ( integer | * ) ];
- alt-transfer-source ( ipv4_address | * )
- [ port ( integer | * ) ];
- alt-transfer-source-v6 ( ipv6_address | * )
- [ port ( integer | * ) ];
- use-alt-transfer-source boolean;
+ alt-transfer-source ( ipv4_address | * )
+ [ port ( integer | * ) ];
+ alt-transfer-source-v6 ( ipv6_address | * )
+ [ port ( integer | * ) ];
+ use-alt-transfer-source boolean;
- zone-statistics boolean;
- key-directory quoted_string;
+ zone-statistics boolean;
+ key-directory quoted_string;
- allow-v6-synthesis { address_match_element; ... }; // obsolete
- deallocate-on-exit boolean; // obsolete
- fake-iquery boolean; // obsolete
- fetch-glue boolean; // obsolete
- has-old-clients boolean; // obsolete
- maintain-ixfr-base boolean; // obsolete
- max-ixfr-log-size size; // obsolete
- multiple-cnames boolean; // obsolete
- named-xfer quoted_string; // obsolete
- serial-queries integer; // obsolete
- treat-cr-as-space boolean; // obsolete
- use-id-pool boolean; // obsolete
-};
view string optional_class {
- match-clients { address_match_element; ... };
- match-destinations { address_match_element; ... };
- match-recursive-only boolean;
+ allow-v6-synthesis { address_match_element; ... }; // obsolete
+ deallocate-on-exit boolean; // obsolete
+ fake-iquery boolean; // obsolete
+ fetch-glue boolean; // obsolete
+ has-old-clients boolean; // obsolete
+ maintain-ixfr-base boolean; // obsolete
+ max-ixfr-log-size size; // obsolete
+ multiple-cnames boolean; // obsolete
+ named-xfer quoted_string; // obsolete
+ serial-queries integer; // obsolete
+ treat-cr-as-space boolean; // obsolete
+ use-id-pool boolean; // obsolete
+};
+
+view string optional_class {
+ match-clients { address_match_element; ... };
+ match-destinations { address_match_element; ... };
+ match-recursive-only boolean;
- key string {
- algorithm string;
- secret string;
+ key string {
+ algorithm string;
+ secret string;
};
- zone string optional_class {
+ zone string optional_class {
...
};
- server ( ipv4_address[/prefixlen] | ipv6_address[/prefixlen] ) {
+ server ( ipv4_address[/prefixlen] | ipv6_address[/prefixlen] ) {
...
};
- trusted-keys {
- string integer integer integer quoted_string; ...
+ trusted-keys {
+ string integer integer integer quoted_string; ...
};
- allow-recursion { address_match_element; ... };
- sortlist { address_match_element; ... };
- topology { address_match_element; ... }; // not implemented
- auth-nxdomain boolean; // default changed
- minimal-responses boolean;
- recursion boolean;
- rrset-order {
- [ class string ] [ type string ]
- [ name quoted_string ] string string; ...
+ allow-recursion { address_match_element; ... };
+ sortlist { address_match_element; ... };
+ topology { address_match_element; ... }; // not implemented
+ auth-nxdomain boolean; // default changed
+ minimal-responses boolean;
+ recursion boolean;
+ rrset-order {
+ [ class string ] [ type string ]
+ [ name quoted_string ] string string; ...
};
- provide-ixfr boolean;
- request-ixfr boolean;
- rfc2308-type1 boolean; // not yet implemented
- additional-from-auth boolean;
- additional-from-cache boolean;
- query-source querysource4;
- query-source-v6 querysource6;
- cleaning-interval integer;
- min-roots integer; // not implemented
- lame-ttl integer;
- max-ncache-ttl integer;
- max-cache-ttl integer;
- transfer-format ( many-answers | one-answer );
- max-cache-size size_no_default;
- check-names ( master | slave | response )
- ( fail | warn | ignore );
- cache-file quoted_string;
- suppress-initial-notify boolean; // not yet implemented
- preferred-glue string;
- dual-stack-servers [ port integer ] {
- ( quoted_string [port integer] |
- ipv4_address [port integer] |
- ipv6_address [port integer] ); ...
+ provide-ixfr boolean;
+ request-ixfr boolean;
+ rfc2308-type1 boolean; // not yet implemented
+ additional-from-auth boolean;
+ additional-from-cache boolean;
+ query-source querysource4;
+ query-source-v6 querysource6;
+ cleaning-interval integer;
+ min-roots integer; // not implemented
+ lame-ttl integer;
+ max-ncache-ttl integer;
+ max-cache-ttl integer;
+ transfer-format ( many-answers | one-answer );
+ max-cache-size size_no_default;
+ check-names ( master | slave | response )
+ ( fail | warn | ignore );
+ cache-file quoted_string;
+ suppress-initial-notify boolean; // not yet implemented
+ preferred-glue string;
+ dual-stack-servers [ port integer ] {
+ ( quoted_string [port integer] |
+ ipv4_address [port integer] |
+ ipv6_address [port integer] ); ...
};
- edns-udp-size integer;
- root-delegation-only [ exclude { quoted_string; ... } ];
- disable-algorithms string { string; ... };
- dnssec-enable boolean;
- dnssec-lookaside string trust-anchor string;
+ edns-udp-size integer;
+ root-delegation-only [ exclude { quoted_string; ... } ];
+ disable-algorithms string { string; ... };
+ dnssec-enable boolean;
+ dnssec-lookaside string trust-anchor string;
- dnssec-must-be-secure string boolean;
- dialup dialuptype;
- ixfr-from-differences ixfrdiff;
+ dnssec-must-be-secure string boolean;
+ dialup dialuptype;
+ ixfr-from-differences ixfrdiff;
- allow-query { address_match_element; ... };
- allow-query-cache { address_match_element; ... };
- allow-transfer { address_match_element; ... };
- allow-update { address_match_element; ... };
- allow-update-forwarding { address_match_element; ... };
+ allow-query { address_match_element; ... };
+ allow-query-cache { address_match_element; ... };
+ allow-transfer { address_match_element; ... };
+ allow-update { address_match_element; ... };
+ allow-update-forwarding { address_match_element; ... };
- notify notifytype;
- notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
- notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
- notify-delay seconds;
- also-notify [ port integer ] { ( ipv4_address | ipv6_address )
- [ port integer ]; ... };
- allow-notify { address_match_element; ... };
+ notify notifytype;
+ notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
+ notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
+ notify-delay seconds;
+ also-notify [ port integer ] { ( ipv4_address | ipv6_address )
+ [ port integer ]; ... };
+ allow-notify { address_match_element; ... };
- forward ( first | only );
- forwarders [ port integer ] {
- ( ipv4_address | ipv6_address ) [ port integer ]; ...
+ forward ( first | only );
+ forwarders [ port integer ] {
+ ( ipv4_address | ipv6_address ) [ port integer ]; ...
};
- max-journal-size size_no_default;
- max-transfer-time-in integer;
- max-transfer-time-out integer;
- max-transfer-idle-in integer;
- max-transfer-idle-out integer;
- max-retry-time integer;
- min-retry-time integer;
- max-refresh-time integer;
- min-refresh-time integer;
- multi-master boolean;
- sig-validity-interval integer;
+ max-journal-size size_no_default;
+ max-transfer-time-in integer;
+ max-transfer-time-out integer;
+ max-transfer-idle-in integer;
+ max-transfer-idle-out integer;
+ max-retry-time integer;
+ min-retry-time integer;
+ max-refresh-time integer;
+ min-refresh-time integer;
+ multi-master boolean;
+ sig-validity-interval integer;
- transfer-source ( ipv4_address | * )
- [ port ( integer | * ) ];
- transfer-source-v6 ( ipv6_address | * )
- [ port ( integer | * ) ];
+ transfer-source ( ipv4_address | * )
+ [ port ( integer | * ) ];
+ transfer-source-v6 ( ipv6_address | * )
+ [ port ( integer | * ) ];
- alt-transfer-source ( ipv4_address | * )
- [ port ( integer | * ) ];
- alt-transfer-source-v6 ( ipv6_address | * )
- [ port ( integer | * ) ];
- use-alt-transfer-source boolean;
+ alt-transfer-source ( ipv4_address | * )
+ [ port ( integer | * ) ];
+ alt-transfer-source-v6 ( ipv6_address | * )
+ [ port ( integer | * ) ];
+ use-alt-transfer-source boolean;
- zone-statistics boolean;
- key-directory quoted_string;
+ zone-statistics boolean;
+ key-directory quoted_string;
- allow-v6-synthesis { address_match_element; ... }; // obsolete
- fetch-glue boolean; // obsolete
- maintain-ixfr-base boolean; // obsolete
- max-ixfr-log-size size; // obsolete
-};
zone string optional_class {
- type ( master | slave | stub | hint |
- forward | delegation-only );
- file quoted_string;
+ allow-v6-synthesis { address_match_element; ... }; // obsolete
+ fetch-glue boolean; // obsolete
+ maintain-ixfr-base boolean; // obsolete
+ max-ixfr-log-size size; // obsolete
+};
+
+zone string optional_class {
+ type ( master | slave | stub | hint |
+ forward | delegation-only );
+ file quoted_string;
- masters [ port integer ] {
- ( masters |
- ipv4_address [port integer] |
- ipv6_address [ port integer ] ) [ key string ]; ...
+ masters [ port integer ] {
+ ( masters |
+ ipv4_address [port integer] |
+ ipv6_address [ port integer ] ) [ key string ]; ...
};
- database string;
- delegation-only boolean;
- check-names ( fail | warn | ignore );
- dialup dialuptype;
- ixfr-from-differences boolean;
- journal quoted_string;
+ database string;
+ delegation-only boolean;
+ check-names ( fail | warn | ignore );
+ dialup dialuptype;
+ ixfr-from-differences boolean;
+ journal quoted_string;
- allow-query { address_match_element; ... };
- allow-transfer { address_match_element; ... };
- allow-update { address_match_element; ... };
- allow-update-forwarding { address_match_element; ... };
- update-policy {
- ( grant | deny ) string
- ( name | subdomain | wildcard | self ) string
- rrtypelist; ...
+ allow-query { address_match_element; ... };
+ allow-transfer { address_match_element; ... };
+ allow-update { address_match_element; ... };
+ allow-update-forwarding { address_match_element; ... };
+ update-policy {
+ ( grant | deny ) string
+ ( name | subdomain | wildcard | self ) string
+ rrtypelist; ...
};
- notify notifytype;
- notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
- notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
- notify-delay seconds;
- also-notify [ port integer ] { ( ipv4_address | ipv6_address )
- [ port integer ]; ... };
- allow-notify { address_match_element; ... };
+ notify notifytype;
+ notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
+ notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
+ notify-delay seconds;
+ also-notify [ port integer ] { ( ipv4_address | ipv6_address )
+ [ port integer ]; ... };
+ allow-notify { address_match_element; ... };
- forward ( first | only );
- forwarders [ port integer ] {
- ( ipv4_address | ipv6_address ) [ port integer ]; ...
+ forward ( first | only );
+ forwarders [ port integer ] {
+ ( ipv4_address | ipv6_address ) [ port integer ]; ...
};
- max-journal-size size_no_default;
- max-transfer-time-in integer;
- max-transfer-time-out integer;
- max-transfer-idle-in integer;
- max-transfer-idle-out integer;
- max-retry-time integer;
- min-retry-time integer;
- max-refresh-time integer;
- min-refresh-time integer;
- multi-master boolean;
- sig-validity-interval integer;
+ max-journal-size size_no_default;
+ max-transfer-time-in integer;
+ max-transfer-time-out integer;
+ max-transfer-idle-in integer;
+ max-transfer-idle-out integer;
+ max-retry-time integer;
+ min-retry-time integer;
+ max-refresh-time integer;
+ min-refresh-time integer;
+ multi-master boolean;
+ sig-validity-interval integer;
- transfer-source ( ipv4_address | * )
- [ port ( integer | * ) ];
- transfer-source-v6 ( ipv6_address | * )
- [ port ( integer | * ) ];
+ transfer-source ( ipv4_address | * )
+ [ port ( integer | * ) ];
+ transfer-source-v6 ( ipv6_address | * )
+ [ port ( integer | * ) ];
- alt-transfer-source ( ipv4_address | * )
- [ port ( integer | * ) ];
- alt-transfer-source-v6 ( ipv6_address | * )
- [ port ( integer | * ) ];
- use-alt-transfer-source boolean;
+ alt-transfer-source ( ipv4_address | * )
+ [ port ( integer | * ) ];
+ alt-transfer-source-v6 ( ipv6_address | * )
+ [ port ( integer | * ) ];
+ use-alt-transfer-source boolean;
- zone-statistics boolean;
- key-directory quoted_string;
+ zone-statistics boolean;
+ key-directory quoted_string;
- ixfr-base quoted_string; // obsolete
- ixfr-tmp-file quoted_string; // obsolete
- maintain-ixfr-base boolean; // obsolete
- max-ixfr-log-size size; // obsolete
- pubkey integer integer integer quoted_string; // obsolete
-};
quoted_string; // obsoletequoted_string; // obsoleteboolean; // obsoletesize; // obsoleteinteger integer integer quoted_string; // obsoletenamed [-4] [-6] [-c config-file] [-d debug-level] [-f] [-g] [-n #cpus] [-p port] [-s] [-t directory] [-u user] [-v] [-x cache-file]
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. -
Use IPv4 only even if the host machine is capable of IPv6.
- -4 and -6 are mutually
- exclusive.
-
Use IPv6 only even if the host machine is capable of IPv4.
- -4 and -6 are mutually
- exclusive.
-
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
- directory option in the configuration
- file, config-file should be
- an absolute pathname.
-
Set the daemon's debug level to debug-level. - Debugging traces from named become - more verbose as the debug level increases. -
Run the server in the foreground (i.e. do not daemonize). -
Run the server in the foreground and force all logging - to stderr. -
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. -
Listen for queries on port port. If not - specified, the default is port 53. -
Write memory usage statistics to stdout on exit. -
Note: This option is mainly of interest to BIND 9 developers - and may be removed or changed in a future release. -
chroot() to directory after
- processing the command line arguments, but before
- reading the configuration file.
-
| Warning |
This option should be used in conjunction with the
- |
setuid() to user after completing
- privileged operations, such as creating sockets that
- listen on privileged ports.
-
Note: 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-u- 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 aftersetuid(). -
Report the version number and exit. -
Load data from cache-file into the - cache of the default view. -
| Warning |
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. - |
In routine operation, signals should not be used to control - the nameserver; rndc should be used - instead. -
Force a reload of the server. -
Shut down the server. -
The result of sending any other signals to the server is undefined. -
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 default configuration file. -
The default process-id file. -
RFC 1033, - RFC 1034, - RFC 1035, - rndc(8), - lwresd(8), - BIND 9 Administrator Reference Manual. -
named — Internet domain name server
+named [-4] [-6] [-c ] [config-file-d ] [debug-level-f] [-g] [-n ] [#cpus-p ] [port-s] [-t ] [directory-u ] [user-v] [-x ]cache-file
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.
+
+ Use IPv4 only even if the host machine is capable of IPv6.
+ -4 and -6 are mutually
+ exclusive.
+
+ Use IPv6 only even if the host machine is capable of IPv4.
+ -4 and -6 are mutually
+ exclusive.
+
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
+ directory option in the configuration
+ file, config-file should be
+ an absolute pathname.
+
debug-level
+ Set the daemon's debug level to debug-level.
+ Debugging traces from named become
+ more verbose as the debug level increases.
+
+ Run the server in the foreground (i.e. do not daemonize). +
+ Run the server in the foreground and force all logging
+ to stderr.
+
#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.
+
port
+ Listen for queries on port port. If not
+ specified, the default is port 53.
+
+ 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. +
+directorychroot()
+ to directory after
+ processing the command line arguments, but before
+ reading the configuration file.
+
+ This option should be used in conjunction with the
+ -u 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.
+
usersetuid()
+ 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 -u
+ 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().
+
+ Report the version number and exit. +
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. +
++ In routine operation, signals should not be used to control + the nameserver; rndc should be used + instead. +
++ Force a reload of the server. +
+ Shut down the server. +
+ The result of sending any other signals to the server is undefined. +
++ The named configuration file is too complex + to describe in detail here. A complete description is provided + in the + BIND 9 Administrator Reference Manual. +
+/etc/named.conf+ The default configuration file. +
/var/run/named.pid+ The default process-id file. +
nsupdate — Dynamic DNS update utility
+nsupdate [-d] [[-y ] | [keyname:secret-k ]] [keyfile-t ] [timeout-u ] [udptimeout-r ] [udpretries-v] [filename]
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
+ -d
+ 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 -y or -k
+ 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
+ -k
+ 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
+ -y
+ 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
+ -y
+ 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
+ ps(1)
+ or in a history file maintained by the user's shell.
+
+ The -k 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
+ -v
+ option makes
+ nsupdate
+ use a TCP connection.
+ This may be preferable when a batch of update requests is made.
+
+ The -t 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 -u 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 -r option sets the number of UDP retries. The
+ default is
+ 3. If zero only one update request will be made.
+
nsupdate
+ reads input from
+ filename
+ or standard input.
+ Each command is supplied on exactly one line of input.
+ Some commands are for administrative purposes.
+ The others are either update instructions or prerequisite checks on the
+ contents of the zone.
+ These checks set conditions that some name or set of
+ resource records (RRset) either exists or is absent from the zone.
+ These conditions must be met if the entire update request is to succeed.
+ Updates will be rejected if the tests for the prerequisite conditions
+ fail.
+
+ Every update request consists of zero or more prerequisites + and zero or more updates. + This allows a suitably authenticated update request to proceed if some + specified resource records are present or missing from the zone. + A blank input line (or the send command) + causes the + accumulated commands to be sent as one Dynamic DNS update request to the + name server. +
++ The command formats and their meaning are as follows: +
+server {servername} [port]
+ Sends all dynamic update requests to the name server
+ servername.
+ When no server statement is provided,
+ nsupdate
+ will send updates to the master server of the correct zone.
+ The MNAME field of that zone's SOA record will identify the
+ master
+ server for that zone.
+ port
+ is the port number on
+ servername
+ where the dynamic update requests get sent.
+ If no port number is specified, the default DNS port number of
+ 53 is
+ used.
+
local {address} [port]
+ Sends all dynamic update requests using the local
+ address.
-
+ When no local statement is provided,
+ nsupdate
+ will send updates using an address and port chosen by the
+ system.
+ port
+ can additionally be used to make requests come from a specific
+ port.
+ If no port number is specified, the system will assign one.
+
zone {zonename}
+ Specifies that all updates are to be made to the zone
+ zonename.
+ If no
+ zone
+ statement is provided,
+ nsupdate
+ will attempt determine the correct zone to update based on the
+ rest of the input.
+
class {classname}
+ Specify the default class.
+ If no class is specified the
+ default class is
+ IN.
+
key {name} {secret}
+ Specifies that all updates are to be TSIG signed using the
+ keyname keysecret pair.
+ The key command
+ overrides any key specified on the command line via
+ -y or -k.
+
prereq nxdomain {domain-name}
+ Requires that no resource record of any type exists with name
+ domain-name.
+
prereq yxdomain {domain-name}
+ Requires that
+ domain-name
+ exists (has as at least one resource record, of any type).
+
prereq nxrrset {domain-name} [class] {type}
+ Requires that no resource record exists of the specified
+ type,
+ class
+ and
+ domain-name.
+ If
+ class
+ is omitted, IN (internet) is assumed.
+
prereq yxrrset {domain-name} [class] {type}
+ This requires that a resource record of the specified
+ type,
+ class
+ and
+ domain-name
+ must exist.
+ If
+ class
+ is omitted, IN (internet) is assumed.
+
prereq yxrrset {domain-name} [class] {type} {data...}
+ The
+ data
+ from each set of prerequisites of this form
+ sharing a common
+ type,
+ class,
+ and
+ domain-name
+ are combined to form a set of RRs. This set of RRs must
+ exactly match the set of RRs existing in the zone at the
+ given
+ type,
+ class,
+ and
+ domain-name.
+ The
+ data
+ are written in the standard text representation of the resource
+ record's
+ RDATA.
+
update delete {domain-name} [ttl] [class] [type [data...]]
+ Deletes any resource records named
+ domain-name.
+ If
+ type
+ and
+ data
+ is provided, only matching resource records will be removed.
+ The internet class is assumed if
+ class
+ is not supplied. The
+ ttl
+ is ignored, and is only allowed for compatibility.
+
update add {domain-name} {ttl} [class] {type} {data...}
+ Adds a new resource record with the specified
+ ttl,
+ class
+ and
+ data.
+
show
+ Displays the current message, containing all of the + prerequisites and + updates specified since the last send. +
send
+ Sends the current message. This is equivalent to entering a + blank line. +
answer
+ Displays the answer. +
+
++ Lines beginning with a semicolon are comments and are ignored. +
++ 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 [-d] [-y keyname:secret | -k keyfile] [-t timeout] [-u udptimeout] [-r udpretries] [-v] [filename]
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
--d
-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
--y
-or
--k
-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
--k
-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
--y
-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
--y
-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
-ps(1)
-or in a history file maintained by the user's shell.
The -k 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
--v
-option makes
-nsupdate
-use a TCP connection.
-This may be preferable when a batch of update requests is made.
The -t 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 -u 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 -r option sets the number of UDP retries. The default is
-3. If zero only one update request will be made.
nsupdate
-reads input from
-filename
-or standard input.
-Each command is supplied on exactly one line of input.
-Some commands are for administrative purposes.
-The others are either update instructions or prerequisite checks on the
-contents of the zone.
-These checks set conditions that some name or set of
-resource records (RRset) either exists or is absent from the zone.
-These conditions must be met if the entire update request is to succeed.
-Updates will be rejected if the tests for the prerequisite conditions fail.
Every update request consists of zero or more prerequisites -and zero or more updates. -This allows a suitably authenticated update request to proceed if some -specified resource records are present or missing from the zone. -A blank input line (or the send command) causes the -accumulated commands to be sent as one Dynamic DNS update request to the -name server.
The command formats and their meaning are as follows: -
server {servername} [port]
Sends all dynamic update requests to the name server
-servername.
-When no server statement is provided,
-nsupdate
-will send updates to the master server of the correct zone.
-The MNAME field of that zone's SOA record will identify the master
-server for that zone.
-port
-is the port number on
-servername
-where the dynamic update requests get sent.
-If no port number is specified, the default DNS port number of 53 is
-used.
local {address} [port]
Sends all dynamic update requests using the local
-address.
+
+# nsupdate +> 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) +
++# nsupdate +> 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.
-When no local statement is provided,
-nsupdate
-will send updates using an address and port chosen by the system.
-port
-can additionally be used to make requests come from a specific port.
-If no port number is specified, the system will assign one.
zone {zonename}
Specifies that all updates are to be made to the zone
-zonename.
-If no
-zone
-statement is provided,
-nsupdate
-will attempt determine the correct zone to update based on the rest of the input.
class {classname}
Specify the default class.
-If no class is specified the default class is
-IN.
key {name} {secret}
Specifies that all updates are to be TSIG signed using the
-keyname keysecret pair.
-The key command
-overrides any key specified on the command line via
--y or -k.
prereq nxdomain {domain-name}
Requires that no resource record of any type exists with name
-domain-name.
prereq yxdomain {domain-name}
Requires that
-domain-name
-exists (has as at least one resource record, of any type).
prereq nxrrset {domain-name} [class] {type}
Requires that no resource record exists of the specified
-type,
-class
-and
-domain-name.
-If
-class
-is omitted, IN (internet) is assumed.
prereq yxrrset {domain-name} [class] {type}
This requires that a resource record of the specified
-type,
-class
-and
-domain-name
-must exist.
-If
-class
-is omitted, IN (internet) is assumed.
prereq yxrrset {domain-name} [class] {type} {data...}
The
-data
-from each set of prerequisites of this form
-sharing a common
-type,
-class,
-and
-domain-name
-are combined to form a set of RRs. This set of RRs must
-exactly match the set of RRs existing in the zone at the
-given
-type,
-class,
-and
-domain-name.
-The
-data
-are written in the standard text representation of the resource record's
-RDATA.
update delete {domain-name} [ttl] [class] [type [data...]]
Deletes any resource records named
-domain-name.
-If
-type
-and
-data
-is provided, only matching resource records will be removed.
-The internet class is assumed if
-class
-is not supplied. The
-ttl
-is ignored, and is only allowed for compatibility.
update add {domain-name} {ttl} [class] {type} {data...}
Adds a new resource record with the specified
-ttl,
-class
-and
-data.
show
Displays the current message, containing all of the prerequisites and -updates specified since the last send.
send
Sends the current message. This is equivalent to entering a blank line.
answer
Displays the answer.
Lines beginning with a semicolon are comments and are ignored.
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
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
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.)
/etc/resolv.confused to identify default name server
K{name}.+157.+{random}.keybase-64 encoding of HMAC-MD5 key created by -dnssec-keygen(8).
K{name}.+157.+{random}.privatebase-64 encoding of HMAC-MD5 key created by -dnssec-keygen(8).
/etc/resolv.conf+ used to identify default name server +
K{name}.+157.+{random}.key+ base-64 encoding of HMAC-MD5 key created by + dnssec-keygen(8). +
K{name}.+157.+{random}.private+ base-64 encoding of HMAC-MD5 key created by + dnssec-keygen(8). +
rndc-confgen [-a] [-b keysize] [-c keyfile] [-h] [-k keyname] [-p port] [-r randomfile] [-s address] [-t chrootdir] [-u user]
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. -
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. -
Specifies the size of the authentication key in bits. - Must be between 1 and 512 bits; the default is 128. -
Used with the -a option to specify - an alternate location for rndc.key. -
Prints a short summary of the options and arguments to - rndc-confgen. -
Specifies the key name of the rndc authentication key.
- This must be a valid domain name.
- The default is rndc-key.
-
Specifies the command channel port where named - listens for connections from rndc. - The default is 953. -
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 the IP address where named - listens for command channel connections from - rndc. The default is the loopback - address 127.0.0.1. -
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 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. -
To allow rndc to be used with - no manual configuration, run -
rndc-confgen -a -
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 — rndc key generation tool
+rndc-confgen [-a] [-b ] [keysize-c ] [keyfile-h] [-k ] [keyname-p ] [port-r ] [randomfile-s ] [address-t ] [chrootdir-u ]user
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.
+
+ 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.
+
keysize+ Specifies the size of the authentication key in bits. + Must be between 1 and 512 bits; the default is 128. +
keyfile
+ Used with the -a option to specify
+ an alternate location for rndc.key.
+
+ Prints a short summary of the options and arguments to + rndc-confgen. +
keyname
+ Specifies the key name of the rndc authentication key.
+ This must be a valid domain name.
+ The default is rndc-key.
+
port+ Specifies the command channel port where named + listens for connections from rndc. + The default is 953. +
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.
+
address+ Specifies the IP address where named + listens for command channel connections from + rndc. The default is the loopback + address 127.0.0.1. +
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.
+
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.
+
rndc.conf is the configuration file - for rndc, the BIND 9 name server control - utility. This file has a similar structure and syntax to - named.conf. Statements are enclosed - in braces and terminated with a semi-colon. Clauses in - the statements are also semi-colon terminated. The usual - comment styles are supported: -
C style: /* */ -
C++ style: // to end of line -
Unix style: # to end of line -
rndc.conf is much simpler than - named.conf. The file uses three - statements: an options statement, a server statement - and a key statement. -
The options statement contains five clauses.
- The default-server 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 default-key
- clause is followed by the name of a key which is identified by
- a key statement. If no
- keyid is provided on the rndc command line,
- and no key clause is found in a matching
- server statement, this default key will be
- used to authenticate the server's commands and responses. The
- default-port clause is followed by the port
- to connect to on the remote name server. If no
- port option is provided on the rndc command
- line, and no port clause is found in a
- matching server statement, this default port
- will be used to connect.
- The default-source-address and
- default-source-address-v6 clauses which
- can be used to set the IPv4 and IPv6 source addresses
- respectively.
-
After the server keyword, the server
- statement includes a string which is the hostname or address
- for a name server. The statement has three possible clauses:
- key, port and
- addresses. 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 addresses
- clause is supplied these addresses will be used instead of
- the server name. Each address can take a optional port.
- If an source-address or source-address-v6
- of supplied then these will be used to specify the IPv4 and IPv6
- source addresses respectively.
-
The key statement begins with an identifying
- string, the name of the key. The statement has two clauses.
- algorithm 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. -
options {
+
+
+
+rndc.conf
+
+
+
+
+
+Name
+rndc.conf — rndc configuration file
+
+
+Synopsis
+rndc.conf
+
+
+DESCRIPTION
+rndc.conf is the configuration file
+ for rndc, the BIND 9 name server control
+ utility. This file has a similar structure and syntax to
+ named.conf. Statements are enclosed
+ in braces and terminated with a semi-colon. Clauses in
+ the statements are also semi-colon terminated. The usual
+ comment styles are supported:
+
+
+ C style: /* */
+
+
+ C++ style: // to end of line
+
+
+ Unix style: # to end of line
+
+rndc.conf is much simpler than
+ named.conf. The file uses three
+ statements: an options statement, a server statement
+ and a key statement.
+
+
+ The options statement contains five clauses.
+ The default-server 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 default-key
+ clause is followed by the name of a key which is identified by
+ a key statement. If no
+ keyid is provided on the rndc command line,
+ and no key clause is found in a matching
+ server statement, this default key will be
+ used to authenticate the server's commands and responses. The
+ default-port clause is followed by the port
+ to connect to on the remote name server. If no
+ port option is provided on the rndc command
+ line, and no port clause is found in a
+ matching server statement, this default port
+ will be used to connect.
+ The default-source-address and
+ default-source-address-v6 clauses which
+ can be used to set the IPv4 and IPv6 source addresses
+ respectively.
+
+
+ After the server keyword, the server
+ statement includes a string which is the hostname or address
+ for a name server. The statement has three possible clauses:
+ key, port and
+ addresses. 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 addresses
+ clause is supplied these addresses will be used instead of
+ the server name. Each address can take a optional port.
+ If an source-address or source-address-v6
+ of supplied then these will be used to specify the IPv4 and IPv6
+ source addresses respectively.
+
+
+ The key statement begins with an identifying
+ string, the name of the key. The statement has two clauses.
+ algorithm identifies the encryption algorithm
+ for rndc to use; currently only HMAC-MD5
+ is
+ supported. This is followed by a secret clause which contains
+ the base-64 encoding of the algorithm's encryption key. The
+ base-64 string is enclosed in double quotes.
+
+
+ There are two common ways to generate the base-64 string for the
+ secret. The BIND 9 program rndc-confgen
+ can
+ be used to generate a random key, or the
+ mmencode program, also known as
+ mimencode, can be used to generate a
+ base-64
+ string from known input. mmencode does
+ not
+ ship with BIND 9 but is available on many systems. See the
+ EXAMPLE section for sample command lines for each.
+
+
+
+EXAMPLE
+
+ options {
default-server localhost;
default-key samplekey;
};
-
+
+
+
+
server localhost {
key samplekey;
};
-
+
+
+
+
server testserver {
key testkey;
addresses { localhost port 5353; };
};
-
+
+
+
+
key samplekey {
algorithm hmac-md5;
secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
};
-
+
+
+
+
key testkey {
algorithm hmac-md5;
secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
}
- In the above example, rndc will by default use
- the server at localhost (127.0.0.1) and the key called samplekey.
- Commands to the localhost server will use the samplekey key, which
- must also be defined in the server's configuration file with the
- same name and secret. The key statement indicates that samplekey
- uses the HMAC-MD5 algorithm and its secret clause contains the
- base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
-
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:
-
rndc-confgen
-
A complete rndc.conf file, including the
- randomly generated key, will be written to the standard
- output. Commented out key and
- controls statements for
- named.conf are also printed.
-
To generate a base-64 secret with 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 controls statement in the
- BIND 9 Administrator Reference Manual for details.
-
+
+
+
+
+ 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.
+
+
+ To generate a random secret with rndc-confgen:
+
+rndc-confgen
+
+
+ A complete rndc.conf file, including
+ the
+ randomly generated key, will be written to the standard
+ output. Commented out key and
+ controls statements for
+ named.conf are also printed.
+
+
+ To generate a base-64 secret with 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 controls statement in the
+ BIND 9 Administrator Reference Manual for details.
+
+
+
+
+rndc [-b source-address] [-c config-file] [-k key-file] [-s server] [-p port] [-V] [-y key_id] {command}
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 reads a configuration file to - determine how to contact the name server and decide what - algorithm and key it should use. -
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 config-file - as the configuration file instead of the default, - /etc/rndc.conf. -
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. -
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. -
Send commands to TCP port - port instead - of BIND 9's default control channel port, 953. -
Enable verbose logging. -
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. -
For the complete set of commands supported by rndc, + +
+ +rndc — name server control utility
+rndc [-b ] [source-address-c ] [config-file-k ] [key-file-s ] [server-p ] [port-V] [-y ] {command}key_id
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 + reads a configuration file to + determine how to contact the name server and decide what + algorithm and key it should use. +
+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.
+
config-file
+ Use config-file
+ as the configuration file instead of the default,
+ /etc/rndc.conf.
+
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.
+
serverserver 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.
+
port
+ Send commands to TCP port
+ port
+ instead
+ of BIND 9's default control channel port, 953.
+
+ Enable verbose logging. +
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.
+
+ 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 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
- key_id without using the configuration file.
-
Several error messages could be clearer. -
rndc.conf(5), - named(8), - named.conf(5) - ndc(8), - BIND 9 Administrator Reference Manual. -
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
+ key_id without using the configuration file.
+
+ Several error messages could be clearer. +
+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.
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.
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.
In this document, we use the following general typographic - conventions:
|
To -describe: |
We use the style: |
|
a pathname, filename, URL, hostname, -mailing list name, or new term or concept | Fixed width |
literal user -input | Fixed Width Bold |
program output | Fixed Width |
The following conventions are used in descriptions of the -BIND configuration file:
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 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. -
The data stored in the DNS is identified by domain -names that are organized as a tree according to -organizational or administrative boundaries. Each node of the tree, -called a domain, is given a label. The domain name of the -node is the concatenation of all the labels on the path from the -node to the root node. This is represented -in written form as a string of labels listed from right to left and -separated by dots. A label need only be unique within its parent -domain.
For example, a domain name for a host at the -company Example, Inc. could be -mail.example.com, -where com is the -top level domain to which -ourhost.example.com belongs, -example is -a subdomain of com, and -ourhost is the -name of the host.
For administrative purposes, the name space is partitioned into -areas called zones, each starting at a node and -extending down to the leaf nodes or to nodes where other zones start. -The data for each zone is stored in a name -server, which answers queries about the zone using the -DNS protocol. -
The data associated with each domain name is stored in the -form of resource records (RRs). -Some of the supported resource record types are described in -Section 6.3.1.
For more detailed information about the design of the DNS and -the DNS protocol, please refer to the standards documents listed in -Section A.3.1.
To properly operate a name server, it is important to understand -the difference between a zone -and a domain.
As we stated previously, a zone is a point of delegation in -the DNS tree. A zone consists of -those contiguous parts of the domain -tree for which a name server has complete information and over which -it has authority. It contains all domain names from a certain point -downward in the domain tree except those which are delegated to -other zones. A delegation point is marked by one or more -NS records in the -parent zone, which should be matched by equivalent NS records at -the root of the delegated zone.
For instance, consider the example.com -domain which includes names -such as host.aaa.example.com and -host.bbb.example.com even though -the example.com zone includes -only delegations for the aaa.example.com and -bbb.example.com zones. A zone can map -exactly to a single domain, but could also include only part of a -domain, the rest of which could be delegated to other -name servers. Every name in the DNS tree is a -domain, even if it is -terminal, that is, has no -subdomains. Every subdomain is a domain and -every domain except the root is also a subdomain. The terminology is -not intuitive and we suggest that you read RFCs 1033, 1034 and 1035 to -gain a complete understanding of this difficult and subtle -topic.
Though BIND is called a "domain name server", -it deals primarily in terms of zones. The master and slave -declarations in the named.conf file specify -zones, not domains. When you ask some other site if it is willing to -be a slave server for your domain, you are -actually asking for slave service for some collection of zones.
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 (Section 3.3.1.1).
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 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.
Usually all of the zone's authoritative servers are listed in -NS records in the parent zone. These NS records constitute -a delegation of the zone from the parent. -The authoritative servers are also listed in the zone file itself, -at the top level or apex -of the zone. You can list servers in the zone's top-level NS -records that are not in the parent's NS delegation, but you cannot -list servers in the parent's delegation that are not present at -the zone's top level.
A stealth server is a server that is -authoritative for a zone but is not listed in that zone's NS -records. Stealth servers can be used for keeping a local copy of a -zone to speed up access to the zone's records or to make sure that the -zone is available even if all the "official" servers for the zone are -inaccessible.
A configuration where the primary master server itself is a -stealth server is often referred to as a "hidden primary" -configuration. One use for this configuration is when the primary master -is behind a firewall and therefore unable to communicate directly -with the outside world.
The resolver libraries provided by most operating systems are -stub resolvers, meaning that they are not capable of -performing the full DNS resolution process by themselves by talking -directly to the authoritative servers. Instead, they rely on a local -name server to perform the resolution on their behalf. Such a server -is called a recursive name server; it performs -recursive lookups for local clients.
To improve performance, recursive servers cache the results of -the lookups they perform. Since the processes of recursion and -caching are intimately connected, the terms -recursive server and -caching server are often used synonymously.
The length of time for which a record may be retained in -in the cache of a caching name server is controlled by the -Time To Live (TTL) field associated with each resource record. -
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.
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. + + +
+ +Table of Contents
+ ++ 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. +
++ 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. +
++ 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. +
++ In this document, we use the following general typographic + conventions: +
+|
+ + To describe: + + |
+
+ + We use the style: + + |
+
|
+ + a pathname, filename, URL, hostname, + mailing list name, or new term or concept + + |
+
+
+ |
+
|
+ + literal user + input + + |
+
+
+ |
+
|
+ + program output + + |
+
+
+ |
+
+ The following conventions are used in descriptions of the + BIND configuration file:
+|
+ + To describe: + + |
+
+ + We use the style: + + |
+
|
+ + keywords + + |
+
+
+ |
+
|
+ + variables + + |
+
+
+ |
+
|
+ + Optional input + + |
+
+ + [Text is enclosed in square brackets] + + |
+
+
++ 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 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. +
++ The data stored in the DNS is identified by domain names that are organized as a tree according to + organizational or administrative boundaries. Each node of the tree, + called a domain, is given a label. The domain + name of the + node is the concatenation of all the labels on the path from the + node to the root node. This is represented + in written form as a string of labels listed from right to left and + separated by dots. A label need only be unique within its parent + domain. +
+
+ For example, a domain name for a host at the
+ company Example, Inc. could be
+ mail.example.com,
+ where com is the
+ top level domain to which
+ ourhost.example.com belongs,
+ example is
+ a subdomain of com, and
+ ourhost is the
+ name of the host.
+
+ For administrative purposes, the name space is partitioned into + areas called zones, each starting at a node and + extending down to the leaf nodes or to nodes where other zones + start. + The data for each zone is stored in a name server, which answers queries about the zone using the + DNS protocol. +
++ The data associated with each domain name is stored in the + form of resource records (RRs). + Some of the supported resource record types are described in + the section called “Types of Resource Records and When to Use Them”. +
++ For more detailed information about the design of the DNS and + the DNS protocol, please refer to the standards documents listed in + the section called “Request for Comments (RFCs)”. +
++ To properly operate a name server, it is important to understand + the difference between a zone + and a domain. +
++ As we stated previously, a zone is a point of delegation in + the DNS tree. A zone consists of + those contiguous parts of the domain + tree for which a name server has complete information and over which + it has authority. It contains all domain names from a certain point + downward in the domain tree except those which are delegated to + other zones. A delegation point is marked by one or more + NS records in the + parent zone, which should be matched by equivalent NS records at + the root of the delegated zone. +
+
+ For instance, consider the example.com
+ domain which includes names
+ such as host.aaa.example.com and
+ host.bbb.example.com even though
+ the example.com zone includes
+ only delegations for the aaa.example.com and
+ bbb.example.com zones. A zone can
+ map
+ exactly to a single domain, but could also include only part of a
+ domain, the rest of which could be delegated to other
+ name servers. Every name in the DNS
+ tree is a
+ domain, even if it is
+ terminal, that is, has no
+ subdomains. Every subdomain is a domain and
+ every domain except the root is also a subdomain. The terminology is
+ not intuitive and we suggest that you read RFCs 1033, 1034 and 1035
+ to
+ gain a complete understanding of this difficult and subtle
+ topic.
+
+ Though BIND is called a "domain name
+ server",
+ it deals primarily in terms of zones. The master and slave
+ declarations in the named.conf file
+ specify
+ zones, not domains. When you ask some other site if it is willing to
+ be a slave server for your domain, you are
+ actually asking for slave service for some collection of zones.
+
+ Each zone is served by at least + one authoritative name server, + which contains the complete data for the zone. + To make the DNS tolerant of server and network failures, + most zones have two or more authoritative servers. +
++ Responses from authoritative servers have the "authoritative + answer" (AA) bit set in the response packets. This makes them + easy to identify when debugging DNS configurations using tools like + dig (the section called “Diagnostic Tools”). +
++ 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 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. +
++ Usually all of the zone's authoritative servers are listed in + NS records in the parent zone. These NS records constitute + a delegation of the zone from the parent. + The authoritative servers are also listed in the zone file itself, + at the top level or apex + of the zone. You can list servers in the zone's top-level NS + records that are not in the parent's NS delegation, but you cannot + list servers in the parent's delegation that are not present at + the zone's top level. +
++ A stealth server is a server that is + authoritative for a zone but is not listed in that zone's NS + records. Stealth servers can be used for keeping a local copy of + a + zone to speed up access to the zone's records or to make sure that + the + zone is available even if all the "official" servers for the zone + are + inaccessible. +
++ A configuration where the primary master server itself is a + stealth server is often referred to as a "hidden primary" + configuration. One use for this configuration is when the primary + master + is behind a firewall and therefore unable to communicate directly + with the outside world. +
++ The resolver libraries provided by most operating systems are + stub resolvers, meaning that they are not + capable of + performing the full DNS resolution process by themselves by talking + directly to the authoritative servers. Instead, they rely on a + local + name server to perform the resolution on their behalf. Such a + server + is called a recursive name server; it performs + recursive lookups for local clients. +
++ To improve performance, recursive servers cache the results of + the lookups they perform. Since the processes of recursion and + caching are intimately connected, the terms + recursive server and + caching server are often used synonymously. +
++ The length of time for which a record may be retained in + in the cache of a caching name server is controlled by the + Time To Live (TTL) field associated with each resource record. +
++ 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. +
++ The BIND name server can + simultaneously act as + a master for some zones, a slave for other zones, and as a caching + (recursive) server for a set of local clients. +
++ However, since the functions of authoritative name service + and caching/recursive name service are logically separate, it is + often advantageous to run them on separate server machines. -A server that only provides authoritative name service -(an authoritative-only server) can run with -recursion disabled, improving reliability and security. + A server that 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.
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 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.
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 -(Section 6.2.16.18) 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.
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.
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.
Table of Contents
+ ++ 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 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. +
++ 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 + (the section called “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. +
++ 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. +
+In this section we provide some suggested configurations along -with guidelines for their use. We also address the topic of reasonable -option setting.
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. + + + + +Chapter 3. Name Server Configuration + + + + + + + + ++ ++++Table of Contents
+ ++ In this section we provide some suggested configurations along + with guidelines for their use. We also address the topic of reasonable + option setting. +
++ ++ ++ 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. acl corpnets { 192.168.4.0/24; 192.168.7.0/24; }; options { directory "/etc/namedb"; // Working directory @@ -139,29 +90,18 @@ zone "0.0.127.in-addr.arpa" { file "localhost.rev"; notify no; }; -+3.1.2. 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 { +++ ++ 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 { directory "/etc/namedb"; // Working directory allow-query-cache { none; }; // Do not allow access to cache allow-query { any; }; // This is the default @@ -191,1252 +131,565 @@ zone "eng.example.com" { // IP address of eng.example.com master server masters { 192.168.4.12; }; }; -3.2. Load Balancing
A primitive form of load balancing can be achieved in -the DNS by using multiple A records for one name.
For example, if you have three WWW servers with network addresses -of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the -following means that clients will connect to each machine one third -of the time:
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 - RRset Ordering. - This substatement is not supported in - BIND 9, and only the ordering scheme described above is - available.
+3.3. Name Server Operations
\ No newline at end of file + +3.3.1. 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
3.3.1.1. Diagnostic Tools
The dig, host, and -nslookup programs are all command line tools -for manually querying name servers. They differ in style and -output format. -
- dig
The domain information groper (dig) -is the most versatile and complete of these lookup tools. -It has two modes: simple interactive -mode for a single query, and batch mode which executes a query for -each in a list of several query lines. All query options are accessible -from the command line.
dig [@server] domain [query-type] [query-class] [+query-option] [-dig-option] [%comment]
The usual simple use of dig will take the form
dig @server domain query-type query-class
For more information and a list of available commands and -options, see the dig man page.
- host
The host utility emphasizes simplicity -and ease of use. By default, it converts -between host names and Internet addresses, but its functionality -can be extended with the use of options.
host [-aCdlrTwv] [-c class] [-N ndots] [-t type] [-W timeout] [-R retries] hostname [server]
For more information and a list of available commands and -options, see the host man page.
- nslookup
nslookup has two modes: interactive -and non-interactive. Interactive mode allows the user to query name servers -for information about various hosts and domains or to print a list -of hosts in a domain. Non-interactive mode is used to print just -the name and requested information for a host or domain.
nslookup [-option...] [host-to-find | - [server]]
Interactive mode is entered when no arguments are given (the -default name server will be used) or when the first argument is a -hyphen (`-') and the second argument is the host name or Internet address -of a name server.
Non-interactive mode is used when the name or Internet address -of the host to be looked up is given as the first argument. The -optional second argument specifies the host name or address of a name server.
Due to its arcane user interface and frequently inconsistent -behavior, we do not recommend the use of nslookup. -Use dig instead.
+3.3.1.2. Administrative Tools
Administrative tools play an integral part in the management -of a server.
+
- named-checkconf
The named-checkconf program - checks the syntax of a named.conf file.
named-checkconf [-jvz] [-t directory] [filename]
- named-checkzone
The named-checkzone program checks a master file for - syntax and consistency.
named-checkzone [-djqvD] [-c class] [-o output] [-t directory] [-w directory] [-k (ignore|warn|fail)] [-n (ignore|warn|fail)] [-W (ignore|warn)] zone [filename]
- rndc
The remote name daemon control - (rndc) program allows the system - administrator to control the operation of a name server. - If you run rndc without any options - it will display a usage message as follows:
rndc [-c config] [-s server] [-p port] [-y key] command [command...]
command is one of the following:
- reload
Reload configuration file and zones.
- reload zone - [class - [view]]
Reload the given zone.
- refresh zone - [class - [view]]
Schedule zone maintenance for the given zone.
- retransfer zone - [class - [view]]
Retransfer the given zone from the master.
- freeze [zone - [class - [view]]]
Suspend updates to a dynamic zone. If no zone is specified - then all zones are suspended. This allows manual - edits to be made to a zone normally updated by dynamic update. It - also causes changes in the journal file to be synced into the master - and the journal file to be removed. All dynamic update attempts will - be refused while the zone is frozen.
- thaw [zone - [class - [view]]]
Enable updates to a frozen dynamic zone. If no zone is - specified then all frozen zones are enabled. This causes - the server to reload the zone from disk, and re-enables dynamic updates - after the load has completed. After a zone is thawed, dynamic updates - will no longer be refused.
- notify zone - [class - [view]]
Resend NOTIFY messages for the zone
- reconfig
Reload the configuration file and load new zones, - but do not reload existing zone files even if they have changed. - This is faster than a full reload when there - is a large number of zones because it avoids the need to examine the - modification times of the zones files. -
- stats
Write server statistics to the statistics file.
- querylog
Toggle query logging. Query logging can also be enabled - by explicitly directing the queries - category to a channel in the - logging section of - named.conf.
- dumpdb [-all|-cache|-zone] [view ...]
Dump the server's caches (default) and / or zones to the - dump file for the specified views. If no view is specified all - views are dumped.
- stop [-p]
Stop the server, making sure any recent changes - made through dynamic update or IXFR are first saved to the master files - of the updated zones. If -p is specified named's process id is returned.
- halt [-p]
Stop the server immediately. Recent changes - made through dynamic update or IXFR are not saved to the master files, - but will be rolled forward from the journal files when the server - is restarted. If -p is specified named's process id is returned.
- trace
Increment the servers debugging level by one.
- trace level
Sets the server's debugging level to an explicit - value.
- notrace
Sets the server's debugging level to 0.
- flush
Flushes the server's cache.
- flushname name
Flushes the given name from the server's cache.
- status
Display status of the server. -Note the number of zones includes the internal bind/CH zone -and the default ./IN hint zone if there is not a -explicit root zone configured.
- recursing
Dump the list of queries named is currently recursing - on. -
In BIND 9.2, rndc -supports all the commands of the BIND 8 ndc -utility except ndc start and -ndc restart, which were also -not supported in ndc's channel mode.
A configuration file is required, since all -communication with the server is authenticated with -digital signatures that rely on a shared secret, and -there is no way to provide that secret other than with a -configuration file. The default location for the -rndc configuration file is -/etc/rndc.conf, but an alternate -location can be specified with the
-c-option. If the configuration file is not found, -rndc will also look in -/etc/rndc.key (or whatever -sysconfdirwas defined when -the BIND build was configured). -The rndc.key file is generated by -running rndc-confgen -a as described in -Section 6.2.4.The format of the configuration file is similar to -that of named.conf, but limited to -only four statements, the options, -key, server and -include -statements. These statements are what associate the -secret keys to the servers with which they are meant to -be shared. The order of statements is not -significant.
The options statement has three clauses: -default-server, default-key, -and default-port. -default-server takes a -host name or address argument and represents the server that will -be contacted if no
-s-option is provided on the command line. -default-key takes -the name of a key as its argument, as defined by a key statement. -default-port specifies the port to which -rndc should connect if no -port is given on the command line or in a -server statement.The key statement defines an key to be used -by rndc when authenticating with -named. Its syntax is identical to the -key statement in named.conf. -The keyword key is -followed by a key name, which must be a valid -domain name, though it need not actually be hierarchical; thus, -a string like "rndc_key" is a valid name. -The key statement has two clauses: -algorithm and secret. -While the configuration parser will accept any string as the argument -to algorithm, currently only the string "hmac-md5" -has any meaning. The secret is a base-64 encoded string.
The server statement associates a key -defined using the key statement with a server. -The keyword server is followed by a -host name or address. The server statement -has two clauses: key and port. -The key clause specifies the name of the key -to be used when communicating with this server, and the -port clause can be used to -specify the port rndc should connect -to on the server.
A sample minimal configuration file is as follows:
key rndc_key { +++ +++ A primitive form of load balancing can be achieved in + the DNS by using multiple A records for + one name. +
++ For example, if you have three WWW servers with network addresses + of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the + following means that clients will connect to each machine one third + of the time: +
+++
+ + ++ + + + + + ++ ++ Name +
++ ++ TTL +
++ ++ CLASS +
++ ++ TYPE +
++ ++ Resource Record (RR) Data +
++ ++ ++
+www++ ++
+600++ ++
+IN++ ++
+A++ ++
+10.0.0.1++ ++ + ++ ++
+600++ ++
+IN++ ++
+A++ ++
+10.0.0.2++ + ++ + ++ ++
+600++ ++
+IN++ ++
+A++ ++
+10.0.0.3++ When a resolver queries for these records, BIND will rotate + them and respond to the query with the records in a different + order. In the example above, clients will randomly receive + records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients + will use the first record returned and discard the rest. +
++ For more detail on ordering responses, check the + rrset-order substatement in the + options statement, see + RRset Ordering. + This substatement is not supported in + BIND 9, and only the ordering scheme + described above is + available. +
++ ++ ++ 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 +
++ +++ The dig, host, and + nslookup programs are all command + line tools + for manually querying name servers. They differ in style and + output format. +
+++
- dig
+- +
++ The domain information groper (dig) + is the most versatile and complete of these lookup tools. + It has two modes: simple interactive + mode for a single query, and batch mode which executes a + query for + each in a list of several query lines. All query options are + accessible + from the command line. +
++
dig[@server]domain[query-type] [query-class] [+query-option] [-dig-option] [%comment]+ The usual simple use of dig will take the form +
++ dig @server domain query-type query-class +
++ For more information and a list of available commands and + options, see the dig man + page. +
+- host
+- +
++ The host utility emphasizes + simplicity + and ease of use. By default, it converts + between host names and Internet addresses, but its + functionality + can be extended with the use of options. +
++
host[-aCdlrTwv] [-cclass] [-Nndots] [-ttype] [-Wtimeout] [-Rretries]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 play an integral part in the management + of a server. +
++
- +named-checkconf +
+- +
++ The named-checkconf program + checks the syntax of a
+named.conffile. ++
named-checkconf[-jvz] [-tdirectory] [filename]- +named-checkzone +
+- +
++ The named-checkzone program + checks a master file for + syntax and consistency. +
++
named-checkzone[-djqvD] [-cclass] [-ooutput] [-tdirectory] [-wdirectory] [-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[-cconfig] [-sserver] [-pport] [-ykey]command[command...]command + is one of the following: +
+++
- +
reload- +
+ Reload configuration file and zones. +
- +
reloadzone+ [class+ [view]]- +
+ Reload the given zone. +
- +
refreshzone+ [class+ [view]]- +
+ Schedule zone maintenance for the given zone. +
- +
retransferzone+ + [class+ [view]]- +
+ Retransfer the given zone from the master. +
- +
freeze + [zone+ [class+ [view]]]- +
+ Suspend updates to a dynamic zone. If no zone is + specified + then all zones are suspended. This allows manual + edits to be made to a zone normally updated by dynamic + update. It + also causes changes in the journal file to be synced + into the master + and the journal file to be removed. All dynamic + update attempts will + be refused while the zone is frozen. +
- +
thaw + [zone+ [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. +
- +
notifyzone+ [class+ [view]]- +
+ Resend NOTIFY messages for the zone +
- +
reconfig- +
+ Reload the configuration file and load new zones, + but do not reload existing zone files even if they + have changed. + This is faster than a full reload when there + is a large number of zones because it avoids the need + to examine the + modification times of the zones files. +
- +
stats- +
+ Write server statistics to the statistics file. +
- +
querylog- +
+ Toggle query logging. Query logging can also be + enabled + by explicitly directing the queries + category to a channel in the + logging section of +
named.conf. +- +
dumpdb + [-all|-cache|-zone] + [view ...]- +
+ Dump the server's caches (default) and / or zones to + the + dump file for the specified views. If no view is + specified all + views are dumped. +
- +
stop [-p]- +
+ Stop the server, making sure any recent changes + made through dynamic update or IXFR are first saved to + the master files + of the updated zones. If -p is specified named's + process id is returned. +
- +
halt [-p]- +
+ Stop the server immediately. Recent changes + made through dynamic update or IXFR are not saved to + the master files, + but will be rolled forward from the journal files when + the server + is restarted. If -p is specified named's process id + is returned. +
- +
trace- +
+ Increment the servers debugging level by one. +
- +
tracelevel- +
+ Sets the server's debugging level to an explicit + value. +
- +
notrace- +
+ Sets the server's debugging level to 0. +
- +
flush- +
+ Flushes the server's cache. +
- +
flushnamename- +
+ Flushes the given name from the server's cache. +
- +
flushnamename- +
+ Flushes the given name from the server's cache. +
- +
status- +
+ Display status of the server. + Note the number of zones includes the internal bind/CH zone + and the default ./IN + hint zone if there is not a + explicit root zone configured. +
- +
recursing- +
+ Dump the list of queries named is currently recursing + on. +
- +
recursing- +
+ Dump the list of queries named is currently recursing + on. +
+ In BIND 9.2, rndc + supports all the commands of the BIND 8 ndc + utility except ndc start and + ndc restart, which were also + not supported in ndc's + channel mode. +
++ A configuration file is required, since all + communication with the server is authenticated with + digital signatures that rely on a shared secret, and + there is no way to provide that secret other than with a + configuration file. The default location for the + rndc configuration file is +
+/etc/rndc.conf, but an + alternate + location can be specified with the-c+ option. If the configuration file is not found, + rndc will also look in +/etc/rndc.key(or whatever +sysconfdirwas defined when + the BIND build was + configured). + Therndc.keyfile is + generated by + running rndc-confgen -a as + described in + the section called “controls Statement Definition and + Usage”. ++ The format of the configuration file is similar to + that of
+named.conf, but + limited to + only four statements, the options, + key, server and + include + statements. These statements are what associate the + secret keys to the servers with which they are meant to + be shared. The order of statements is not + significant. ++ The options statement has + three clauses: + default-server, default-key, + and default-port. + default-server takes a + host name or address argument and represents the server + that will + be contacted if no
+-s+ 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
+keyis + 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
+serveris followed by a + host name or address. The server statement + has two clauses: key and port. + The key clause specifies the + name of the key + to be used when communicating with this server, and the + port clause can be used to + specify the port rndc should + connect + to on the server. ++ A sample minimal configuration file is as follows: +
++key rndc_key { algorithm "hmac-md5"; secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; }; @@ -1444,213 +697,114 @@ options { default-server 127.0.0.1; default-key rndc_key; }; -This file, if installed as /etc/rndc.conf, -would allow the command:
$ 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:
controls { +++ This file, if installed as
+/etc/rndc.conf, + would allow the command: ++
+$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: +
++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. -
3.3.2. 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.
+ 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 tonamed.conf. + Alternatively, + you can run rndc-confgen -a + to set up + arndc.keyfile and not + modify +named.confat all. +
+ 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 |
+
|
+ SIGTERM + |
+
+ + Causes the server to clean up and exit. + + |
+
|
+ SIGINT + |
+
+ + Causes the server to clean up and exit. + + |
+
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 Section 6.2.16.1 and -the description of the zone option also-notify in -Section 6.2.16.7. The NOTIFY -protocol is specified in RFC 1996. -
Dynamic Update is a method for adding, replacing or deleting - records in a master server by sending it a special form of DNS - messages. The format and meaning of these messages is specified - in RFC 2136.
Dynamic update is enabled by - including an allow-update or - update-policy clause in the - zone statement.
Updating of secure zones (zones using DNSSEC) follows - RFC 3007: RRSIG and NSEC records affected by updates are automatically - regenerated by the server using an online zone key. - Update authorization is based - on transaction signatures and an explicit server policy.
All changes made to a zone using dynamic update are stored - in the zone's journal file. This file is automatically created - by the server when the first dynamic update takes place. - The name of the journal file is formed by appending the extension - .jnl to the name of the corresponding zone - file unless specifically overridden. The journal file is in a - binary format and should not be edited manually.
The server will also occasionally write ("dump") - the complete contents of the updated zone to its zone file. - This is not done immediately after - each dynamic update, because that would be too slow when a large - zone is updated frequently. Instead, the dump is delayed by - up to 15 minutes, allowing additional updates to take place.
When a server is restarted after a shutdown or crash, it will replay - the journal file to incorporate into the zone any updates that took - place after the last zone dump.
Changes that result from incoming incremental zone transfers are also - journalled in a similar way.
The zone files of dynamic zones cannot normally be edited by - hand because they are not guaranteed to contain the most recent - dynamic changes - those are only in the journal file. - The only way to ensure that the zone file of a dynamic zone - is up to date is to run rndc stop.
If you have to make changes to a dynamic zone - manually, the following procedure will work: Disable dynamic updates - to the zone using - rndc freeze zone. - This will also remove the zone's .jnl file - and update the master file. Edit the zone file. Run - rndc unfreeze zone - to reload the changed zone and re-enable dynamic updates.
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 Proposed Standards.
When acting as a master, BIND 9 -supports IXFR for those zones -where the necessary change history information is available. These -include master zones maintained by dynamic update and slave zones -whose data was obtained by IXFR. For manually maintained master -zones, and for slave zones obtained by performing a full zone -transfer (AXFR), IXFR is supported only if the option -ixfr-from-differences is set -to yes. -
When acting as a slave, BIND 9 will -attempt to use IXFR unless -it is explicitly disabled. For more information about disabling -IXFR, see the description of the request-ixfr clause -of the server statement.
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 Section 3.1
Internal DNS server config:
+ + + + +Chapter 4. Advanced DNS Features + + + + + + + + ++ ++++Table of Contents
++
+- Notify
+- Dynamic Update
+- +
- Incremental Zone Transfers (IXFR)
+- Split DNS
+- TSIG
+- +
- TKEY
+- SIG(0)
+- DNSSEC
+- +
- IPv6 Support in BIND 9
+- +
+ +++ 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 the section called “Boolean Options” and + the description of the zone option also-notify in + the section called “Zone Transfers”. The NOTIFY + protocol is specified in RFC 1996. +
++ +++ Dynamic Update is a method for adding, replacing or deleting + records in a master server by sending it a special form of DNS + messages. The format and meaning of these messages is specified + in RFC 2136. +
++ Dynamic update is enabled by + including an allow-update or + update-policy clause in the + zone statement. +
++ Updating of secure zones (zones using DNSSEC) follows + RFC 3007: RRSIG and NSEC records affected by updates are automatically + regenerated by the server using an online zone key. + Update authorization is based + on transaction signatures and an explicit server policy. +
++ +++ 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 +
+.jnlto the name of the + corresponding zone + file unless specifically overridden. The journal file is in a + binary format and should not be edited manually. ++ The server will also occasionally write ("dump") + the complete contents of the updated zone to its zone file. + This is not done immediately after + each dynamic update, because that would be too slow when a large + zone is updated frequently. Instead, the dump is delayed by + up to 15 minutes, allowing additional updates to take place. +
++ When a server is restarted after a shutdown or crash, it will replay + the journal file to incorporate into the zone any updates that + took + place after the last zone dump. +
++ Changes that result from incoming incremental zone transfers are + also + journalled in a similar way. +
++ The zone files of dynamic zones cannot normally be edited by + hand because they are not guaranteed to contain the most recent + dynamic changes - those are only in the journal file. + The only way to ensure that the zone file of a dynamic zone + is up to date is to run rndc stop. +
++ If you have to make changes to a dynamic zone + manually, the following procedure will work: Disable dynamic updates + to the zone using + rndc freeze
+zone. + This will also remove the zone's.jnlfile + and update the master file. Edit the zone file. Run + rndc unfreezezone+ to reload the changed zone and re-enable dynamic updates. ++ +++ 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 Proposed Standards. +
++ When acting as a master, BIND 9 + supports IXFR for those zones + where the necessary change history information is available. These + include master zones maintained by dynamic update and slave zones + whose data was obtained by IXFR. For manually maintained master + zones, and for slave zones obtained by performing a full zone + transfer (AXFR), IXFR is supported only if the option + ixfr-from-differences is set + to
+yes. ++ When acting as a slave, BIND 9 will + attempt to use IXFR unless + it is explicitly disabled. For more information about disabling + IXFR, see the description of the request-ixfr clause + of the server statement. +
++ ++ 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, + andsite2.example.com, to the servers + in the + DMZ. These internal servers will have complete sets of information + forsite1.example.com,site2.example.com,site1.internal, + andsite2.internal. ++ To protect the
+site1.internalandsite2.internaldomains, + 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
+site1andsite2.example.comzones. + This could include things such as the host records for public servers + (www.example.comandftp.example.com), + and mail exchange (MX) records (a.mx.example.comandb.mx.example.com). ++ In addition, the public
+site1andsite2.example.comzones + 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.comzones. +- + Look up any hostnames in the
+site1.internaland +site2.internaldomains. +- 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.comzones. +- + Exchange mail with anyone in the
+site1and +site2.example.comzones. ++ 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 the section called “Sample Configurations” +
++ Internal DNS server config: +
++ acl internals { 172.16.72.0/24; 192.168.1.0/24; }; -acl externals {bastion-ips-go-here; }; +acl externals {bastion-ips-go-here; }; options { ... ... forward only; forwarders { // forward to external servers -bastion-ips-go-here; +bastion-ips-go-here; }; allow-transfer { none; }; // sample allow-transfer (no one) allow-query { internals; externals; }; // restrict query access @@ -659,12 +394,12 @@ zone "site2.internal" { allow-query { internals }; allow-transfer { internals; } }; -External (bastion host) DNS server config:
acl internals { 172.16.72.0/24; 192.168.1.0/24; }; +++ External (bastion host) DNS server config: +
++acl internals { 172.16.72.0/24; 192.168.1.0/24; }; acl externals { bastion-ips-go-here; }; @@ -691,915 +426,524 @@ zone "site2.example.com" { masters { another_bastion_host_maybe; }; allow-transfer { internals; externals; } }; -In the resolv.conf (or equivalent) on -the bastion host(s):
search ... +++ 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 -\ No newline at end of file + +4.5. 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
-kand --ycommand line options.4.5.1. 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.
4.5.1.1. 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.
4.5.1.2. 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.
4.5.2. 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.
+4.5.3. 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. { +++ ++ 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
+-kand +-ycommand line options. ++ +++ 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. +
++ +++ 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. ++ +++ 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. +
++ +++ This is beyond the scope of DNS. A secure transport mechanism + should be used. This could be secure FTP, ssh, telephone, etc. +
++ ++ Imagine host1 and host 2 + are + both servers. The following is added to each server's
+named.conffile: ++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.
+4.5.4. 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 { +++ 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.confbe 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. +
++ ++ 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.conffile + 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.
4.5.5. 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 Section 6.2.24.4.
4.5.6. Errors
The processing of TSIG signed messages can result in - several errors. If a signed message is sent to a non-TSIG aware - server, a FORMERR will be returned, since the server will not - understand the record. This is a result of misconfiguration, - since the server must be explicitly configured to send a TSIG - signed message to a specific server.
If a TSIG aware server receives a message signed by an - unknown key, the response will be unsigned with the TSIG - extended error code set to BADKEY. If a TSIG aware server - receives a message with a signature that does not validate, the - response will be unsigned with the TSIG extended error code set - to BADSIG. If a TSIG aware server receives a message with a time - outside of the allowed range, the response will be signed with - the TSIG extended error code set to BADTIME, and the time values - will be adjusted so that the response can be successfully - verified. In any of these cases, the message's rcode is set to - NOTAUTH.
4.6. 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.
4.7. 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.
4.8. 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
-hoption 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-hoption, 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.
4.8.1. 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. -
4.8.2. 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.
4.8.3. 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.
+4.9. IPv6 Support in BIND 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 Section A.2.1.
+4.9.1. 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. +++ 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. +
++ +++ 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 the section called “Dynamic Update Policies”. +
++ +++ The processing of TSIG signed messages can result in + several errors. If a signed message is sent to a non-TSIG aware + server, a FORMERR will be returned, since the server will not + understand the record. This is a result of misconfiguration, + since the server must be explicitly configured to send a TSIG + signed message to a specific server. +
++ If a TSIG aware server receives a message signed by an + unknown key, the response will be unsigned with the TSIG + extended error code set to BADKEY. If a TSIG aware server + receives a message with a signature that does not validate, the + response will be unsigned with the TSIG extended error code set + to BADSIG. If a TSIG aware server receives a message with a time + outside of the allowed range, the response will be signed with + the TSIG extended error code set to BADTIME, and the time values + will be adjusted so that the response can be successfully + verified. In any of these cases, the message's rcode is set to + NOTAUTH. +
++ ++TKEY + 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. +
++ +++ 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. +
++ +++ 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
+-hoption 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-hoption, 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
+DSrecord 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. +
++ +++ 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.examplezone: ++
+dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.++ Two output files will be produced: +
+Kchild.example.+005+12345.keyand +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 +.keyfile) 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
+.keyfiles using + $INCLUDE statements. ++ +++ The dnssec-signzone program is used + to + sign a zone. +
++ Any
+keysetfiles corresponding + to secure subzones should be present. The zone signer will + generateNSECandRRSIG+ records for the zone, as well asDS+ 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 bynamed.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 + correspondingDSrecords) that are the + secure entry point to the zone. ++ +++ 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. +
++ ++ 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 the section called “IPv6 addresses (AAAA)”. +
++ ++ 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.
+4.9.2. Address to Name Lookups Using Nibble Format
When looking up an address in nibble format, the address - components are simply reversed, just as in IPv4, and - ip6.arpa. is appended to the resulting name. - For example, the following would provide reverse name lookup for - a host with address - 2001:db8::1.
$ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. +++ 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.1as + the + address. ++ ++ 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. -
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.
To use the lightweight resolver interface, the system must -run the resolver daemon lwresd or a local -name server configured with a lwres statement.
By default, applications using the lightweight resolver library will make -UDP requests to the IPv4 loopback address (127.0.0.1) on port 921. The -address can be overridden by lwserver lines in -/etc/resolv.conf.
The daemon currently only looks in the DNS, but in the future -it may use other sources such as /etc/hosts, -NIS, etc.
The lwresd daemon is essentially a -caching-only name server that responds to requests using the lightweight -resolver protocol rather than the DNS protocol. Because it needs -to run on each host, it is designed to require no or minimal configuration. -Unless configured otherwise, it uses the name servers listed on -nameserver lines in /etc/resolv.conf -as forwarders, but is also capable of doing the resolution autonomously if -none are specified.
The lwresd daemon may also be configured with a -named.conf style configuration file, in -/etc/lwresd.conf by default. A name server may also -be configured to act as a lightweight resolver daemon using the -lwres statement in named.conf.
Table of Contents
+ ++ 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. +
++ To use the lightweight resolver interface, the system must + run the resolver daemon lwresd or a + local + name server configured with a lwres + statement. +
+
+ By default, applications using the lightweight resolver library will
+ make
+ UDP requests to the IPv4 loopback address (127.0.0.1) on port 921.
+ The
+ address can be overridden by lwserver
+ lines in
+ /etc/resolv.conf.
+
+ The daemon currently only looks in the DNS, but in the future
+ it may use other sources such as /etc/hosts,
+ NIS, etc.
+
+ The lwresd daemon is essentially a
+ caching-only name server that responds to requests using the
+ lightweight
+ resolver protocol rather than the DNS protocol. Because it needs
+ to run on each host, it is designed to require no or minimal
+ configuration.
+ Unless configured otherwise, it uses the name servers listed on
+ nameserver lines in /etc/resolv.conf
+ as forwarders, but is also capable of doing the resolution
+ autonomously if
+ none are specified.
+
+ The lwresd daemon may also be
+ configured with a
+ named.conf style configuration file,
+ in
+ /etc/lwresd.conf by default. A name
+ server may also
+ be configured to act as a lightweight resolver daemon using the
+ lwres statement in named.conf.
+
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.
Following is a list of elements used throughout the BIND configuration -file documentation:
| The name of an |
| A list of one or more |
| A quoted string which will be used as -a DNS name, for example "my.test.domain". |
| One to four integers valued 0 through -255 separated by dots (`.'), such as 123, -45.67 or 89.123.45.67. |
| An IPv4 address with exactly four elements
-in |
| 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. |
| An |
| An IP port |
| An IP network specified as an |
| A |
| A list of one or more |
| 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. |
| A quoted string which will be used as -a pathname, such as zones/master/my.test.domain. |
| A number, the word unlimited, -or the word default.
An A The value must be representable as a 64-bit unsigned integer
-(0 to 18446744073709551615, inclusive).
-Using |
| Either yes or no. -The words true and false are -also accepted, as are the numbers 1 and 0. |
| 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_list= address_match_list_element ; - [ address_match_list_element; ... ] -address_match_list_element= [ ! ] (ip_address [/length] | + + + + +Chapter 6. BIND 9 Configuration Reference + + + + + + + + ++ ++++Table of Contents
++
+- Configuration File Elements
+- +
- Configuration File Grammar
+- +
+
- acl Statement Grammar
+- acl Statement Definition and + Usage
+- controls Statement Grammar
+- controls Statement Definition and + Usage
+- include Statement Grammar
+- include Statement Definition and + Usage
+- key Statement Grammar
+- key Statement Definition and Usage
+- logging Statement Grammar
+- logging Statement Definition and + Usage
+- lwres Statement Grammar
+- lwres Statement Definition and Usage
+- masters Statement Grammar
+- masters Statement Definition and + Usage
+- options Statement Grammar
+- options Statement Definition and + Usage
+- server Statement Grammar
+- server Statement Definition and + Usage
+- trusted-keys Statement Grammar
+- trusted-keys Statement Definition + and Usage
+- view Statement Grammar
+- view Statement Definition and Usage
+- zone + Statement Grammar
+- zone Statement Definition and Usage
+- Zone File
+- +
+ 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. ++ ++ Following is a list of elements used throughout the BIND configuration + file documentation: +
+++
+ + ++ + + ++ ++
+acl_name++ ++ The name of an
+address_match_listas + defined by the acl statement. ++ ++ ++
+address_match_list++ ++ A list of one or more +
+ip_addr, +ip_prefix,key_id, + oracl_nameelements, see + the section called “Address Match Lists”. ++ ++ ++
+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_decimalnotation. ++ ++ ++
+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_addrorip6_addr. ++ ++ ++
+ip_port++ ++ An IP port
+number. +numberis 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 aip_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_namerepresenting + 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 worddefault. ++ An
+unlimitedsize_specrequests unlimited + use, or the maximum available amount. Adefault size_specuses + the limit that was in force when the server was started. ++ A
+numbercan optionally be + followed by a scaling factor: +Kork+ for kilobytes, +Morm+ for megabytes, and +Gorgfor 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
+unlimitedis the best + way + to safely set a really large number. ++ ++ ++
+yes_or_no++ ++ Either
+yesorno. + The wordstrueandfalseare + also accepted, as are the numbers1+ and0. ++ + ++ ++
+dialup_option++ ++ One of
+yes, +no,notify, +notify-passive,refreshor +passive. + When used in a zone,notify-passive, +refresh, andpassive+ are restricted to slave and stub zones. ++ ++ +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 } ) -6.1.1.2. Definition and Usage
Address match lists are primarily used to determine access -control for various server operations. They are also used in -the listen-on and sortlist -statements. The elements -which constitute an address match list can be any of the following:
an IP address (IPv4 or IPv6)
an IP prefix (in `/' notation)
a key ID, as defined by the key statement
the name of an address match list defined with -the acl statement
a nested address match list enclosed in braces
Elements can be negated with a leading exclamation mark (`!'), -and the match list names "any", "none", "localhost", and "localnets" -are predefined. More information on those names can be found in -the description of the acl statement.
The addition of the key clause made the name of this syntactic -element something of a misnomer, since security keys can be used -to validate access without regard to a host or network address. Nonetheless, -the term "address match list" is still used throughout the documentation.
When a given IP address or prefix is compared to an address -match list, the list is traversed in order until an element matches. -The interpretation of a match depends on whether the list is being used -for access control, defining listen-on ports, or in a sortlist, -and whether the element was negated.
When used as an access control list, a non-negated match allows -access and a negated match denies access. If there is no match, -access is denied. The clauses allow-notify, -allow-query, allow-query-cache, -allow-transfer, -allow-update, allow-update-forwarding, -and blackhole all use address match lists. -Similarly, the listen-on option will cause the server to not accept -queries on any of the machine's addresses which do not match the -list.
Because of the first-match aspect of the algorithm, an element -that defines a subset of another element in the list should come -before the broader element, regardless of whether either is negated. For -example, in -1.2.3/24; ! 1.2.3.13; the 1.2.3.13 element is -completely useless because the algorithm will match any lookup for -1.2.3.13 to the 1.2.3/24 element. -Using ! 1.2.3.13; 1.2.3/24 fixes -that problem by having 1.2.3.13 blocked by the negation but all -other 1.2.3.* hosts fall through.
+6.1.2. Comment Syntax
The BIND 9 comment syntax allows for comments to appear -anywhere that white space may appear in a BIND configuration -file. To appeal to programmers of all kinds, they can be written -in the C, C++, or shell/perl style.
6.1.2.1. 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-+6.1.2.2. 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. +++ +++ Address match lists are primarily used to determine access + control for various server operations. They are also used in + the listen-on and sortlist + statements. The elements + which constitute an address match list can be any of the + following: +
+++
- an IP address (IPv4 or IPv6)
+- an IP prefix (in `/' notation)
+- + a key ID, as defined by the key + statement +
+- the name of an address match list defined with + the acl statement +
+- a nested address match list enclosed in braces
++ Elements can be negated with a leading exclamation mark (`!'), + and the match list names "any", "none", "localhost", and + "localnets" + are predefined. More information on those names can be found in + the description of the acl statement. +
++ The addition of the key clause made the name of this syntactic + element something of a misnomer, since security keys can be used + to validate access without regard to a host or network address. + Nonetheless, + the term "address match list" is still used throughout the + documentation. +
++ When a given IP address or prefix is compared to an address + match list, the list is traversed in order until an element + matches. + The interpretation of a match depends on whether the list is being + used + for access control, defining listen-on ports, or in a sortlist, + and whether the element was negated. +
++ When used as an access control list, a non-negated match allows + access and a negated match denies access. If there is no match, + access is denied. The clauses allow-notify, + allow-query, allow-query-cache, + allow-transfer, + allow-update, allow-update-forwarding, + and blackhole all use address match + lists. + Similarly, the listen-on option will cause the server to not + accept + queries on any of the machine's addresses which do not match the + list. +
++ Because of the first-match aspect of the algorithm, an element + that defines a subset of another element in the list should come + before the broader element, regardless of whether either is + negated. For + example, in + 1.2.3/24; ! 1.2.3.13; the 1.2.3.13 + element is + completely useless because the algorithm will match any lookup for + 1.2.3.13 to the 1.2.3/24 element. + Using ! 1.2.3.13; 1.2.3/24 fixes + that problem by having 1.2.3.13 blocked by the negation but all + other 1.2.3.* hosts fall through. +
++ ++ 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++
++ ++ 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. --
Warning 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.
+6.2. Configuration File Grammar
A BIND 9 configuration consists of statements and comments. - Statements end with a semicolon. Statements and comments are the - only elements that can appear without enclosing braces. Many - statements contain a block of sub-statements, which are also - terminated with a semicolon.
The following statements are supported:
acl
defines a named IP address -matching list, for access control and other uses.
controls
declares control channels to be used -by the rndc utility.
include
includes a file.
key
specifies key information for use in -authentication and authorization using TSIG.
logging
specifies what the server logs, and where -the log messages are sent.
lwres
configures named to -also act as a light weight resolver daemon (lwresd).
masters
defines a named masters list for -inclusion in stub and slave zone masters clauses.
options
controls global server configuration -options and sets defaults for other statements.
server
sets certain configuration options on -a per-server basis.
trusted-keys
defines trusted DNSSEC keys.
view
defines a view.
zone
defines a zone.
The logging and - options statements may only occur once per - configuration.
+6.2.1. acl Statement Grammar
acl acl-name { +++ +
+++Warning
++ 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. +
++ The following statements are supported: +
+++
+ + ++ + + ++ +acl
++ ++ defines a named IP address + matching list, for access control and other uses. +
++ ++ +controls
++ ++ declares control channels to be used + by the rndc utility. +
++ ++ +include
++ ++ includes a file. +
++ ++ +key
++ ++ specifies key information for use in + authentication and authorization using TSIG. +
++ ++ +logging
++ ++ specifies what the server logs, and where + the log messages are sent. +
++ ++ +lwres
++ ++ configures named to + also act as a light weight resolver daemon (lwresd). +
++ ++ +masters
++ ++ defines a named masters list for + inclusion in stub and slave zone masters clauses. +
++ ++ +options
++ ++ controls global server configuration + options and sets defaults for other statements. +
++ ++ +server
++ ++ sets certain configuration options on + a per-server basis. +
++ ++ +trusted-keys
++ ++ defines trusted DNSSEC keys. +
++ ++ +view
++ ++ defines a view. +
++ + ++ +zone
++ ++ defines a zone. +
++ The logging and + options statements may only occur once + per + configuration. +
+6.2.2. acl Statement Definition and -Usage
The acl statement assigns a symbolic - name to an address match list. It gets its name from a primary - use of address match lists: Access Control Lists (ACLs).
Note that an address match list's name must be defined - with acl before it can be used elsewhere; no - forward references are allowed.
The following ACLs are built-in:
any
Matches all hosts.
none
Matches no hosts.
localhost
Matches the IPv4 and IPv6 addresses of all network -interfaces on the system.
localnets
Matches any host on an IPv4 or IPv6 network -for which the system has an interface. -Some systems do not provide a way to determine the prefix lengths of -local IPv6 addresses. -In such a case, localnets only matches the local -IPv6 addresses, just like localhost. -
+6.2.3. controls Statement Grammar
controls { - inet ( ip_addr | * ) [ port ip_port ] allow { address_match_list } - keys { key_list }; - [ inet ...; ] +++ +++ The acl statement assigns a symbolic + name to an address match list. It gets its name from a primary + use of address match lists: Access Control Lists (ACLs). +
++ Note that an address match list's name must be defined + with acl before it can be used + elsewhere; no + forward references are allowed. +
++ The following ACLs are built-in: +
+++
+ + ++ + + ++ +any
++ ++ Matches all hosts. +
++ ++ +none
++ ++ Matches no hosts. +
++ ++ +localhost
++ ++ Matches the IPv4 and IPv6 addresses of all network + interfaces on the system. +
++ + ++ +localnets
++ ++ Matches any host on an IPv4 or IPv6 network + for which the system has an interface. + Some systems do not provide a way to determine the prefix + lengths of + local IPv6 addresses. + In such a case, localnets + only matches the local + IPv6 addresses, just like localhost. +
++ +controls { + inet ( ip_addr | * ) [ port ip_port ] allow {address_match_list} + keys {key_list}; + [ inet ...; ] }; -+6.2.4. controls Statement Definition and Usage
The controls statement declares control - channels to be used by system administrators to control the - operation of the name server. These control channels are - used by the rndc utility to send commands to - and retrieve non-DNS results from a name server.
An inet control channel is a TCP - socket listening at the specified - ip_port on the specified - ip_addr, which can be an IPv4 or IPv6 - address. An ip_addr - of * is interpreted as the IPv4 wildcard - address; connections will be accepted on any of the system's - IPv4 addresses. To listen on the IPv6 wildcard address, - use an ip_addr of ::. - If you will only use rndc on the local host, - using the loopback address (127.0.0.1 - or ::1) is recommended for maximum - security. -
If no port is specified, port 953 - is used. "*" cannot be used for - ip_port.
The ability to issue commands over the control channel is - restricted by the allow and - keys clauses. Connections to the control - channel are permitted based on the - address_match_list. This is for simple - IP address based filtering only; any key_id - elements of the address_match_list are - ignored. -
The primary authorization mechanism of the command - channel is the key_list, which contains - a list of key_ids. - Each key_id in - the key_list is authorized to execute - commands over the control channel. - See Remote Name Daemon Control application in - Section 3.3.1.2) for information about - configuring keys in rndc.
If no controls statement is present, -named will set up a default -control channel listening on the loopback address 127.0.0.1 -and its IPv6 counterpart ::1. -In this case, and also when the controls statement -is present but does not have a keys clause, -named will attempt to load the command channel key -from the file rndc.key in -/etc (or whatever
sysconfdir-was specified as when BIND was built). -To create a rndc.key file, run -rndc-confgen -a. -The rndc.key feature was created to - ease the transition of systems from BIND 8, - which did not have digital signatures on its command channel messages - and thus did not have a keys clause. + +
+ ++ The controls statement declares + control + channels to be used by system administrators to control the + operation of the name server. These control channels are + used by the rndc utility to send + commands to + and retrieve non-DNS results from a name server. +
++ An inet control channel is a TCP + socket listening at the specified + ip_port on the specified + ip_addr, which can be an IPv4 or IPv6 + address. An ip_addr + of
+*is interpreted as the IPv4 + wildcard + address; connections will be accepted on any of the system's + IPv4 addresses. To listen on the IPv6 wildcard address, + use an ip_addr of::. + If you will only use rndc on the + local host, + using the loopback address (127.0.0.1+ or::1) is recommended for + maximum + security. ++ If no port is specified, port 953 + is used. "
+*" cannot be used for + ip_port. ++ The ability to issue commands over the control channel is + restricted by the allow and + keys clauses. Connections to the + control + channel are permitted based on the + address_match_list. This is for + simple + IP address based filtering only; any key_id + elements of the address_match_list + are + ignored. +
++ The primary authorization mechanism of the command + channel is the key_list, which + contains + a list of key_ids. + Each key_id in + the key_list is authorized to execute + commands over the control channel. + See Remote Name Daemon Control application in + the section called “Administrative Tools”) for information about + configuring keys in rndc. +
++ If no controls statement is present, + named will set up a default + control channel listening on the loopback address 127.0.0.1 + and its IPv6 counterpart ::1. + In this case, and also when the controls statement + is present but does not have a keys + clause, + named will attempt to load the + command channel key + from the file
+rndc.keyin +/etc(or whateversysconfdir+ was specified as when BIND was + built). + To create arndc.keyfile, run +rndc-confgen -a. ++ The
rndc.keyfeature was created to + ease the transition of systems from BIND 8, + which did not have digital signatures on its command channel + messages + and thus did not have a keys clause. -It makes it possible to use an existing BIND 8 -configuration file in BIND 9 unchanged, -and still have rndc work the same way -ndc worked in BIND 8, simply by executing the -command rndc-confgen -a after BIND 9 is -installed. -Since the rndc.key feature - is only intended to allow the backward-compatible usage of - BIND 8 configuration files, this feature does not - have a high degree of configurability. You cannot easily change - the key name or the size of the secret, so you should make a - rndc.conf with your own key if you wish to change - those things. The rndc.key file also has its - permissions set such that only the owner of the file (the user that - named is running as) can access it. If you - desire greater flexibility in allowing other users to access - rndc commands then you need to create an - rndc.conf and make it group readable by a group - that contains the users who should have access.
The UNIX control channel type of BIND 8 is not supported - in BIND 9, and is not expected to be added in future - releases. If it is present in the controls statement from a - BIND 8 configuration file, it is ignored - and a warning is logged.
To disable the command channel, use an empty controls -statement: controls { };. -
6.2.5. include Statement Grammar
include filename;6.2.6. include 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.
+ +6.2.7. key Statement Grammar
key key_id { - algorithm string; - secret string; + 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 + commandrndc-confgen -aafter BIND 9 is + installed. + ++ Since the
+rndc.keyfeature + 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.confwith your own key if you + wish to change + those things. Therndc.keyfile + 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.confand make it group + readable by a group + that contains the users who should have access. ++ The UNIX control channel type of BIND + 8 is not supported + in BIND 9, and is not expected to be + added in future + releases. If it is present in the controls statement from a + BIND 8 configuration file, it is + ignored + and a warning is logged. +
++ To disable the command channel, use an empty controls + statement: controls { };. +
++ +++ 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. +
+6.2.8. key Statement Definition and Usage
The key statement defines a shared -secret key for use with TSIG (see Section 4.5) -or the command channel -(see Section 6.2.4). -
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 Section 6.2.4) -must be defined at the top level. -
The key_id, also known as the -key name, is a domain name uniquely identifying the key. It can -be used in a server -statement to cause requests sent to that -server to be signed with this key, or in address match lists to -verify that incoming requests have been signed with a key -matching this name, algorithm, and secret.
The algorithm_id is a string -that specifies a security/authentication algorithm. The only -algorithm currently supported with TSIG authentication is -hmac-md5. The -secret_string is the secret to be -used by the algorithm, and is treated as a base-64 encoded -string.
+6.2.9. logging Statement Grammar
logging { - [ channel channel_name { - ( file path name - [ versions ( number | unlimited ) ] - [ size size spec ] - | syslog syslog_facility - | stderr - | null ); - [ severity (+critical|error|warning|notice| -info|debug[ level ] |dynamic); ] - [ print-categoryyesorno; ] - [ print-severityyesorno; ] - [ print-timeyesorno; ] ++ +++ The key statement defines a shared + secret key for use with TSIG (see the section called “TSIG”) + or the command channel + (see the section called “controls 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 the section called “controls Statement Definition and + Usage”) + must be defined at the top level. +
++ The
+key_id, also known as the + key name, is a domain name uniquely identifying the key. It can + be used in a server + statement to cause requests sent to that + server to be signed with this key, or in address match lists to + verify that incoming requests have been signed with a key + matching this name, algorithm, and secret. ++ The
+algorithm_idis a string + that specifies a security/authentication algorithm. The only + algorithm currently supported with TSIG authentication is +hmac-md5. The +secret_stringis the secret + to be + used by the algorithm, and is treated as a base-64 encoded + string. ++ +logging { + [ channelchannel_name{ + ( filepath name+ [ versions (number| unlimited ) ] + [ sizesize spec] + | syslogsyslog_facility+ | stderr + | null ); + [ severity (critical|error|warning|notice| +info|debug[level] |dynamic); ] + [ print-categoryyesorno; ] + [ print-severityyesorno; ] + [ print-timeyesorno; ] }; ] - [ category category_name { - channel_name ; [ channel_name ; ... ] + [ categorycategory_name{ +channel_name; [channel_name; ... ] }; ] ... }; -+6.2.10. logging 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 { +++ +++ 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; }; category unmatched { null; }; }; -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 "
-g" option -was specified.6.2.10.1. The channel Phrase
All log output goes to one or more channels; -you can make as many of them as you want.
Every channel definition must include a destination clause that -says whether messages selected for the channel go to a file, to a -particular syslog facility, to the standard error stream, or are -discarded. It can optionally also limit the message severity level -that will be accepted by the channel (the default is -info), and whether to include a -named-generated time stamp, the category name -and/or severity level (the default is not to include any).
The null destination clause -causes all messages sent to the channel to be discarded; -in that case, other options for the channel are meaningless.
The file destination clause directs the channel -to a disk file. It can include limitations -both on how large the file is allowed to become, and how many versions -of the file will be saved each time the file is opened.
If you use the versions log file option, then -named will retain that many backup versions of the file by -renaming them when opening. For example, if you choose to keep 3 old versions -of the file lamers.log then just before it is opened -lamers.log.1 is renamed to -lamers.log.2, lamers.log.0 is renamed -to lamers.log.1, and lamers.log is -renamed to lamers.log.0. -You can say versions unlimited to not limit -the number of versions. -If a size option is associated with the log file, -then renaming is only done when the file being opened exceeds the -indicated size. No backup versions are kept by default; any existing -log file is simply appended.
The size option for files is used to limit log -growth. If the file ever exceeds the size, then named will -stop writing to the file unless it has a versions option -associated with it. If backup versions are kept, the files are rolled as -described above and a new one begun. If there is no -versions option, no more data will be written to the log -until some out-of-band mechanism removes or truncates the log to less than the -maximum size. The default behavior is not to limit the size of the -file.
Example usage of the size and -versions options:
channel an_example_channel { +++ 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 "
+-g" option + was specified. ++ ++ All log output goes to one or more channels; + you can make as many of them as you want. +
++ Every channel definition must include a destination clause that + says whether messages selected for the channel go to a file, to a + particular syslog facility, to the standard error stream, or are + discarded. It can optionally also limit the message severity level + that will be accepted by the channel (the default is + info), and whether to include a + named-generated time stamp, the + category name + and/or severity level (the default is not to include any). +
++ The null destination clause + causes all messages sent to the channel to be discarded; + in that case, other options for the channel are meaningless. +
++ The file destination clause directs + the channel + to a disk file. It can include limitations + both on how large the file is allowed to become, and how many + versions + of the file will be saved each time the file is opened. +
++ If you use the versions log file + option, then + named will retain that many backup + versions of the file by + renaming them when opening. For example, if you choose to keep 3 + old versions + of the file
+lamers.logthen just + before it is opened +lamers.log.1is renamed to +lamers.log.2,lamers.log.0is renamed + tolamers.log.1, andlamers.logis + renamed tolamers.log.0. + You can say versions unlimited to + not limit + the number of versions. + If a size option is associated with + the log file, + then renaming is only done when the file being opened exceeds the + indicated size. No backup versions are kept by default; any + existing + log file is simply appended. ++ The size option for files is used + to limit log + growth. If the file ever exceeds the size, then named will + stop writing to the file unless it has a versions option + associated with it. If backup versions are kept, the files are + rolled as + described above and a new one begun. If there is no + versions option, no more data will + be written to the log + until some out-of-band mechanism removes or truncates the log to + less than the + maximum size. The default behavior is not to limit the size of + the + file. +
++ Example usage of the size and + versions options: +
+channel an_example_channel { file "example.log" versions 3 size 20m; print-time yes; print-category yes; }; -The syslog destination clause directs the -channel to the system log. Its argument is a -syslog facility as described in the syslog man -page. Known facilities are kern, user, -mail, daemon, auth, -syslog, lpr, news, -uucp, cron, authpriv, -ftp, local0, local1, -local2, local3, local4, -local5, local6 and -local7, however not all facilities are supported on -all operating systems. -How syslog will handle messages sent to -this facility is described in the syslog.conf man -page. If you have a system which uses a very old version of syslog that -only uses two arguments to the openlog() function, -then this clause is silently ignored.
The severity clause works like syslog's -"priorities", except that they can also be used if you are writing -straight to a file rather than using syslog. -Messages which are not at least of the severity level given will -not be selected for the channel; messages of higher severity levels -will be accepted.
If you are using syslog, then the syslog.conf priorities -will also determine what eventually passes through. For example, -defining a channel facility and severity as daemon and debug but -only logging daemon.warning via syslog.conf will -cause messages of severity info and notice to -be dropped. If the situation were reversed, with named writing -messages of only warning or higher, then syslogd would -print all messages it received from the channel.
The stderr destination clause directs the -channel to the server's standard error stream. This is intended for -use when the server is running as a foreground process, for example -when debugging a configuration.
The server can supply extensive debugging information when -it is in debugging mode. If the server's global debug level is greater -than zero, then debugging mode will be active. The global debug -level is set either by starting the named server -with the
-dflag 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:channel specific_debug_level { +++ The syslog destination clause + directs the + channel to the system log. Its argument is a + syslog facility as described in the syslog man + page. Known facilities are kern, user, + mail, daemon, auth, + syslog, lpr, news, + uucp, cron, authpriv, + ftp, local0, local1, + local2, local3, local4, + local5, local6 and + local7, however not all facilities + are supported on + all operating systems. + How syslog will handle messages + sent to + this facility is described in the syslog.conf man + page. If you have a system which uses a very old version of syslog that + only uses two arguments to the openlog() function, + then this clause is silently ignored. +
++ The severity clause works like syslog's + "priorities", except that they can also be used if you are writing + straight to a file rather than using syslog. + Messages which are not at least of the severity level given will + not be selected for the channel; messages of higher severity + levels + will be accepted. +
++ If you are using syslog, then the syslog.conf priorities + will also determine what eventually passes through. For example, + defining a channel facility and severity as daemon and debug but + only logging daemon.warning via syslog.conf will + cause messages of severity info and + notice to + be dropped. If the situation were reversed, with named writing + messages of only warning or higher, + then syslogd would + print all messages it received from the channel. +
++ The stderr destination clause + directs the + channel to the server's standard error stream. This is intended + for + use when the server is running as a foreground process, for + example + when debugging a configuration. +
++ The server can supply extensive debugging information when + it is in debugging mode. If the server's global debug level is + greater + than zero, then debugging mode will be active. The global debug + level is set either by starting the named server + with the
+-dflag 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: +channel specific_debug_level { file "foo"; severity debug 3; }; -will get debugging output of level 3 or less any time the -server is in debugging mode, regardless of the global debugging -level. Channels with dynamic severity use the -server's global debug level to determine what messages to print.
If print-time has been turned on, then -the date and time will be logged. print-time may -be specified for a syslog channel, but is usually -pointless since syslog also prints the date and -time. If print-category is requested, then the -category of the message will be logged as well. Finally, if print-severity is -on, then the severity level of the message will be logged. The print- options may -be used in any combination, and will always be printed in the following -order: time, category, severity. Here is an example where all three print- options -are on:
28-Feb-2000 15:05:32.863 general: notice: running
There are four predefined channels that are used for -named's default logging as follows. How they are -used is described in Section 6.2.10.2. -
channel default_syslog { +++ will get debugging output of level 3 or less any time the + server is in debugging mode, regardless of the global debugging + level. Channels with dynamic + severity use the + server's global debug level to determine what messages to print. +
++ If print-time has been turned on, + then + the date and time will be logged. print-time may + be specified for a syslog channel, + but is usually + pointless since syslog also prints + the date and + time. If print-category is + requested, then the + category of the message will be logged as well. Finally, if print-severity is + on, then the severity level of the message will be logged. The print- options may + be used in any combination, and will always be printed in the + following + order: time, category, severity. Here is an example where all + three print- options + are on: +
++
+28-Feb-2000 15:05:32.863 general: notice: running++ There are four predefined channels that are used for + named's default logging as follows. + How they are + used is described in the section called “The category Phrase”. +
+channel default_syslog { syslog daemon; // send to syslog's daemon // facility severity info; // only send priority info @@ -2394,78 +1319,52 @@ channel null { null; // toss anything sent to // this channel }; -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 "
-u" -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 "-g" -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.
+6.2.10.2. The category Phrase
There are many categories, so you can send the logs you want -to see wherever you want, without seeing logs you don't want. If -you don't specify a list of channels for a category, then log messages -in that category will be sent to the default category -instead. If you don't specify a default category, the following -"default default" is used:
category default { default_syslog; default_debug; }; -As an example, let's say you want to log security events to -a file, but you also want keep the default logging behavior. You'd -specify the following:
channel my_security_channel { +++ 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 "
+-u" + command line option is used, thenamed.runfile + 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 "-g" + 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. +
++ ++ 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: +
+channel my_security_channel { file "my_security_file"; severity info; }; @@ -2473,4877 +1372,2157 @@ category security { my_security_channel; default_syslog; default_debug; -};To discard all messages in a category, specify the null channel:
category xfer-out { null; }; +};++ 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. -
+6.2.11. lwres 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] ; ... ] }; ] - [ view view_name; ] - [ search { domain_name ; [ domain_name ; ... ] }; ] - [ ndots number; ] +++ 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.conffile: +lwres { + [ listen-on {ip_addr[portip_port] ; [ip_addr[portip_port] ; ... ] }; ] + [ viewview_name; ] + [ search {domain_name; [domain_name; ... ] }; ] + [ ndotsnumber; ] }; -6.2.12. lwres Statement Definition and Usage
The lwres statement configures the name -server to also act as a lightweight resolver server, see -Section 5.2. There may be be multiple -lwres statements configuring -lightweight resolver servers with different properties.
The listen-on statement specifies a list of -addresses (and ports) that this instance of a lightweight resolver daemon -should accept requests on. If no port is specified, port 921 is used. -If this statement is omitted, requests will be accepted on 127.0.0.1, -port 921.
The view statement binds this instance of a -lightweight resolver daemon to a view in the DNS namespace, so that the -response will be constructed in the same manner as a normal DNS query -matching this view. If this statement is omitted, the default view is -used, and if there is no default view, an error is triggered.
The search statement is equivalent to the -search statement in -/etc/resolv.conf. It provides a list of domains -which are appended to relative names in queries.
The ndots statement is equivalent to the -ndots statement in -/etc/resolv.conf. It indicates the minimum -number of dots in a relative domain name that should result in an -exact match lookup before search path elements are appended.
6.2.13. masters Statement Grammar
masters name [port ip_port] { ( masters_list | ip_addr [port ip_port] [key key] ) ; [...] } ; -6.2.14. masters Statement Definition and Usage
masters lists allow for a common set of masters -to be easily used by multiple stub and slave zones.
+6.2.15. options Statement Grammar
This is the grammar of the options -statement in the named.conf file:
options { - [ version version_string; ] - [ hostname hostname_string; ] - [ server-id server_id_string; ] - [ directory path_name; ] - [ key-directory path_name; ] - [ named-xfer path_name; ] - [ tkey-domain domainname; ] - [ tkey-dhkey key_name key_tag; ] - [ dump-file path_name; ] - [ memstatistics-file path_name; ] - [ pid-file path_name; ] - [ statistics-file path_name; ] - [ zone-statistics yes_or_no; ] - [ auth-nxdomain yes_or_no; ] - [ deallocate-on-exit yes_or_no; ] - [ dialup dialup_option; ] - [ fake-iquery yes_or_no; ] - [ fetch-glue yes_or_no; ] - [ flush-zones-on-shutdown yes_or_no; ] - [ has-old-clients yes_or_no; ] - [ host-statistics yes_or_no; ] - [ host-statistics-max number; ] - [ minimal-responses yes_or_no; ] - [ multiple-cnames yes_or_no; ] - [ notify yes_or_no | explicit | master-only; ] - [ recursion yes_or_no; ] - [ rfc2308-type1 yes_or_no; ] - [ use-id-pool yes_or_no; ] - [ maintain-ixfr-base yes_or_no; ] - [ dnssec-enable yes_or_no; ] - [ dnssec-lookaside domain trust-anchor domain; ] - [ dnssec-must-be-secure domain yes_or_no; ] - [ forward ( only | first ); ] - [ forwarders { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ; ... ] }; ] - [ dual-stack-servers [port ip_port] { ( domain_name [port ip_port] | ip_addr [port ip_port] ) ; ... }; ] - [ check-names ( master | slave | response )( warn | fail | ignore ); ] - [ check-wildcard yes_or_no; ] - [ allow-notify { address_match_list }; ] - [ allow-query { address_match_list }; ] - [ allow-query-cache { address_match_list }; ] - [ allow-transfer { address_match_list }; ] - [ allow-recursion { address_match_list }; ] - [ allow-update { address_match_list }; ] - [ allow-update-forwarding { address_match_list }; ] - [ allow-v6-synthesis { address_match_list }; ] - [ blackhole { address_match_list }; ] - [ avoid-v4-udp-ports { port_list }; ] - [ avoid-v6-udp-ports { port_list }; ] - [ listen-on [ port ip_port ] { address_match_list }; ] - [ listen-on-v6 [ port ip_port ] { address_match_list }; ] - [ query-source ( ( ip4_addr | * ) [ port ( ip_port | * ) ] | [ address ( ip4_addr | * ) ] [ port ( ip_port | * ) ] ) ; ] - [ query-source-v6 ( ( ip6_addr | * ) [ port ( ip_port | * ) ] | [ address ( ip6_addr | * ) ] [ port ( ip_port | * ) ] ) ; ] - [ max-transfer-time-in number; ] - [ max-transfer-time-out number; ] - [ max-transfer-idle-in number; ] - [ max-transfer-idle-out number; ] - [ tcp-clients number; ] - [ recursive-clients number; ] - [ serial-query-rate number; ] - [ serial-queries number; ] - [ tcp-listen-queue number; ] - [ transfer-format ( one-answer | many-answers ); ] - [ transfers-in number; ] - [ transfers-out number; ] - [ transfers-per-ns number; ] - [ transfer-source (ip4_addr |+*) [port ip_port] ; ] - [ transfer-source-v6 (ip6_addr |*) [port ip_port] ; ] - [ alt-transfer-source (ip4_addr |*) [port ip_port] ; ] - [ alt-transfer-source-v6 (ip6_addr |*) [port ip_port] ; ] - [ use-alt-transfer-source yes_or_no; ] - [ notify-source (ip4_addr |*) [port ip_port] ; ] - [ notify-source-v6 (ip6_addr |*) [port ip_port] ; ] - [ also-notify { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ; ... ] }; ] - [ max-ixfr-log-size number; ] - [ max-journal-size size_spec; ] - [ coresize size_spec ; ] - [ datasize size_spec ; ] - [ files size_spec ; ] - [ stacksize size_spec ; ] - [ cleaning-interval number; ] - [ heartbeat-interval number; ] - [ interface-interval number; ] - [ statistics-interval number; ] - [ topology { address_match_list }]; - [ sortlist { address_match_list }]; - [ rrset-order { order_spec ; [ order_spec ; ... ] ] }; - [ lame-ttl number; ] - [ max-ncache-ttl number; ] - [ max-cache-ttl number; ] - [ sig-validity-interval number ; ] - [ min-roots number; ] - [ use-ixfr yes_or_no ; ] - [ provide-ixfr yes_or_no; ] - [ request-ixfr yes_or_no; ] - [ treat-cr-as-space yes_or_no ; ] - [ min-refresh-time number ; ] - [ max-refresh-time number ; ] - [ min-retry-time number ; ] - [ max-retry-time number ; ] - [ port ip_port; ] - [ additional-from-auth yes_or_no ; ] - [ additional-from-cache yes_or_no ; ] - [ random-device path_name ; ] - [ max-cache-size size_spec ; ] - [ match-mapped-addresses yes_or_no; ] - [ preferred-glue ( A | AAAA | NONE ); ] - [ edns-udp-size number; ] - [ root-delegation-only [ exclude { namelist } ] ; ] - [ querylog yes_or_no ; ] - [ disable-algorithms domain { algorithm; [ algorithm; ] }; ] - [ use-additional-cache yes_or_no ; ] - [ acache-cleaning-interval number; ] - [ max-acache-size size_spec ; ] ++ +++ The lwres statement configures the + name + server to also act as a lightweight resolver server, see + the section called “Running a Resolver Daemon”. There may be be multiple + lwres statements configuring + lightweight resolver servers with different properties. +
++ The listen-on statement specifies a + list of + addresses (and ports) that this instance of a lightweight resolver + daemon + should accept requests on. If no port is specified, port 921 is + used. + If this statement is omitted, requests will be accepted on + 127.0.0.1, + port 921. +
++ The view statement binds this + instance of a + lightweight resolver daemon to a view in the DNS namespace, so that + the + response will be constructed in the same manner as a normal DNS + query + matching this view. If this statement is omitted, the default view + is + used, and if there is no default view, an error is triggered. +
++ The search statement is equivalent to + the + search statement in +
+/etc/resolv.conf. It provides a + list of domains + which are appended to relative names in queries. ++ The ndots statement is equivalent to + the + ndots statement in +
+/etc/resolv.conf. It indicates the + minimum + number of dots in a relative domain name that should result in an + exact match lookup before search path elements are appended. ++ +++masters+name[portip_port] { (masters_list|ip_addr[portip_port] [keykey] ) ; [...] } ; ++ ++masters + lists allow for a common set of masters to be easily used by + multiple stub and slave zones. +
++ ++ This is the grammar of the options + statement in the
+named.conffile: +options { + [ versionversion_string; ] + [ hostnamehostname_string; ] + [ server-idserver_id_string; ] + [ directorypath_name; ] + [ key-directorypath_name; ] + [ named-xferpath_name; ] + [ tkey-domaindomainname; ] + [ tkey-dhkeykey_namekey_tag; ] + [ dump-filepath_name; ] + [ memstatistics-filepath_name; ] + [ pid-filepath_name; ] + [ statistics-filepath_name; ] + [ zone-statisticsyes_or_no; ] + [ auth-nxdomainyes_or_no; ] + [ deallocate-on-exityes_or_no; ] + [ dialupdialup_option; ] + [ fake-iqueryyes_or_no; ] + [ fetch-glueyes_or_no; ] + [ flush-zones-on-shutdownyes_or_no; ] + [ has-old-clientsyes_or_no; ] + [ host-statisticsyes_or_no; ] + [ host-statistics-maxnumber; ] + [ minimal-responsesyes_or_no; ] + [ multiple-cnamesyes_or_no; ] + [ notifyyes_or_no|explicit|master-only; ] + [ recursionyes_or_no; ] + [ rfc2308-type1yes_or_no; ] + [ use-id-poolyes_or_no; ] + [ maintain-ixfr-baseyes_or_no; ] + [ dnssec-enableyes_or_no; ] + [ dnssec-lookasidedomaintrust-anchordomain; ] + [ dnssec-must-be-securedomain yes_or_no; ] + [ forward (only|first); ] + [ forwarders {ip_addr[portip_port] ; [ip_addr[portip_port] ; ... ] }; ] + [ dual-stack-servers [portip_port] { (domain_name[portip_port] |ip_addr[portip_port] ) ; ... }; ] + [ check-names (master|slave|response)(warn|fail|ignore); ] + [ check-wildcardyes_or_no; ] + [ allow-notify {address_match_list}; ] + [ allow-query {address_match_list}; ] + [ allow-query-cache {address_match_list}; ] + [ allow-transfer {address_match_list}; ] + [ allow-recursion {address_match_list}; ] + [ allow-update {address_match_list}; ] + [ allow-update-forwarding {address_match_list}; ] + [ allow-v6-synthesis {address_match_list}; ] + [ blackhole {address_match_list}; ] + [ avoid-v4-udp-ports {port_list}; ] + [ avoid-v6-udp-ports {port_list}; ] + [ listen-on [ portip_port] {address_match_list}; ] + [ listen-on-v6 [ portip_port] {address_match_list}; ] + [ query-source ( (ip4_addr|*) [ port (ip_port|*) ] | [ address (ip4_addr|*) ] [ port (ip_port|*) ] ) ; ] + [ query-source-v6 ( (ip6_addr|*) [ port (ip_port|*) ] | [ address (ip6_addr|*) ] [ port (ip_port|*) ] ) ; ] + [ max-transfer-time-innumber; ] + [ max-transfer-time-outnumber; ] + [ max-transfer-idle-innumber; ] + [ max-transfer-idle-outnumber; ] + [ tcp-clientsnumber; ] + [ recursive-clientsnumber; ] + [ serial-query-ratenumber; ] + [ serial-queriesnumber; ] + [ tcp-listen-queuenumber; ] + [ transfer-format( one-answer | many-answers ); ] + [ transfers-innumber; ] + [ transfers-outnumber; ] + [ transfers-per-nsnumber; ] + [ transfer-source (ip4_addr|*) [portip_port] ; ] + [ transfer-source-v6 (ip6_addr|*) [portip_port] ; ] + [ alt-transfer-source (ip4_addr|*) [portip_port] ; ] + [ alt-transfer-source-v6 (ip6_addr|*) [portip_port] ; ] + [ use-alt-transfer-sourceyes_or_no; ] + [ notify-source (ip4_addr|*) [portip_port] ; ] + [ notify-source-v6 (ip6_addr|*) [portip_port] ; ] + [ also-notify {ip_addr[portip_port] ; [ip_addr[portip_port] ; ... ] }; ] + [ max-ixfr-log-sizenumber; ] + [ max-journal-sizesize_spec; ] + [ coresizesize_spec; ] + [ datasizesize_spec; ] + [ filessize_spec; ] + [ stacksizesize_spec; ] + [ cleaning-intervalnumber; ] + [ heartbeat-intervalnumber; ] + [ interface-intervalnumber; ] + [ statistics-intervalnumber; ] + [ topology {address_match_list}]; + [ sortlist {address_match_list}]; + [ rrset-order {order_spec; [order_spec; ... ] ] }; + [ lame-ttlnumber; ] + [ max-ncache-ttlnumber; ] + [ max-cache-ttlnumber; ] + [ sig-validity-intervalnumber; ] + [ min-rootsnumber; ] + [ use-ixfryes_or_no; ] + [ provide-ixfryes_or_no; ] + [ request-ixfryes_or_no; ] + [ treat-cr-as-spaceyes_or_no; ] + [ min-refresh-timenumber; ] + [ max-refresh-timenumber; ] + [ min-retry-timenumber; ] + [ max-retry-timenumber; ] + [ portip_port; ] + [ additional-from-authyes_or_no; ] + [ additional-from-cacheyes_or_no; ] + [ random-devicepath_name; ] + [ max-cache-sizesize_spec; ] + [ match-mapped-addressesyes_or_no; ] + [ preferred-glue (A|AAAA|NONE); ] + [ edns-udp-sizenumber; ] + [ root-delegation-only [ exclude {namelist} ] ; ] + [ querylogyes_or_no; ] + [ disable-algorithmsdomain{algorithm; [algorithm; ] }; ] + [ use-additional-cacheyes_or_no; ] + [ acache-cleaning-intervalnumber; ] + [ max-acache-sizesize_spec; ] }; -+6.2.16. options Statement Definition and Usage
The options statement sets up global options -to be used by BIND. This statement may appear only -once in a configuration file. If there is no options -statement, an options block with each option set to its default will -be used.
+
- directory
The working directory of the server. -Any non-absolute pathnames in the configuration file will be taken -as relative to this directory. The default location for most server -output files (e.g. named.run) is this directory. -If a directory is not specified, the working directory defaults -to `.', the directory from which the server -was started. The directory specified should be an absolute path.
- key-directory
When performing dynamic update of secure zones, the -directory where the public and private key files should be found, -if different than the current working directory. The directory specified -must be an absolute path.
- named-xfer
This option is obsolete. -It was used in BIND 8 to -specify the pathname to the named-xfer program. -In BIND 9, no separate named-xfer program is -needed; its functionality is built into the name server.
- tkey-domain
The domain appended to the names of all -shared keys generated with TKEY. When a client -requests a TKEY exchange, it may or may not specify -the desired name for the key. If present, the name of the shared -key will be "
client specified part" + -"tkey-domain". -Otherwise, the name of the shared key will be "random hex -digits" + "tkey-domain". In most cases, -the domainname should be the server's domain -name.- tkey-dhkey
The Diffie-Hellman key used by the server -to generate shared keys with clients using the Diffie-Hellman mode -of TKEY. The server must be able to load the -public and private keys from files in the working directory. In -most cases, the keyname should be the server's host name.
- dump-file
The pathname of the file the server dumps -the database to when instructed to do so with -rndc dumpdb. -If not specified, the default is named_dump.db.
- memstatistics-file
The pathname of the file the server writes memory -usage statistics to on exit. If not specified, -the default is named.memstats.
- pid-file
The pathname of the file the server writes its process ID -in. If not specified, the default is /var/run/named.pid. -The pid-file is used by programs that want to send signals to the running -name server. Specifying pid-file none disables the -use of a PID file — no file will be written and any -existing one will be removed. Note that none -is a keyword, not a file name, and therefore is not enclosed in -double quotes.
- statistics-file
The pathname of the file the server appends statistics -to when instructed to do so using rndc stats. -If not specified, the default is named.stats in the -server's current directory. The format of the file is described -in Section 6.2.16.17
- port
The UDP/TCP port number the server uses for -receiving and sending DNS protocol traffic. -The default is 53. This option is mainly intended for server testing; -a server using a port other than 53 will not be able to communicate with -the global DNS. -
- random-device
The source of entropy to be used by the server. Entropy is primarily needed -for DNSSEC operations, such as TKEY transactions and dynamic update of signed -zones. This options specifies the device (or file) from which to read -entropy. If this is a file, operations requiring entropy will fail when the -file has been exhausted. If not specified, the default value is -/dev/random -(or equivalent) when present, and none otherwise. The -random-device option takes effect during -the initial configuration load at server startup time and -is ignored on subsequent reloads.
- preferred-glue
If specified the listed type (A or AAAA) will be emitted before other glue -in the additional section of a query response. -The default is not to preference any type (NONE). -
- root-delegation-only
Turn on enforcement of delegation-only in TLDs and root zones with an optional -exclude list. -
Note some TLDs are NOT delegation only (e.g. "DE", "LV", "US" and "MUSEUM"). -
options { +++ ++ The options statement sets up global + options + to be used by BIND. This statement + may appear only + once in a configuration file. If there is no options + statement, an options block with each option set to its default will + be used. +
++
- directory
+- +
+ The working directory of the server. + Any non-absolute pathnames in the configuration file will be + taken + as relative to this directory. The default location for most + server + output files (e.g.
named.run) + is this directory. + If a directory is not specified, the working directory + defaults + to `.', the directory from + which the server + was started. The directory specified should be an absolute + path. +- key-directory
+- +
+ When performing dynamic update of secure zones, the + directory where the public and private key files should be + found, + if different than the current working directory. The + directory specified + must be an absolute path. +
- named-xfer
+- +
+ This option is obsolete. + It was used in BIND 8 to + specify the pathname to the named-xfer program. + In BIND 9, no separate named-xfer program is + needed; its functionality is built into the name server. +
- tkey-domain
+- +
+ The domain appended to the names of all + shared keys generated with + TKEY. When a client + requests a TKEY exchange, it + may or may not specify + the desired name for the key. If present, the name of the + shared + key will be "
client specified part" + + "tkey-domain". + Otherwise, the name of the shared key will be "random hex +digits" + "tkey-domain". In most cases, + the domainname should be the + server's domain + name. +- tkey-dhkey
+- +
+ The Diffie-Hellman key used by the server + to generate shared keys with clients using the Diffie-Hellman + mode + of TKEY. The server must be + able to load the + public and private keys from files in the working directory. + In + most cases, the keyname should be the server's host name. +
- dump-file
+- +
+ The pathname of the file the server dumps + the database to when instructed to do so with + rndc dumpdb. + If not specified, the default is
named_dump.db. +- memstatistics-file
+- +
+ The pathname of the file the server writes memory + usage statistics to on exit. If not specified, + the default is +
named.memstats. +- pid-file
+- +
+ The pathname of the file the server writes its process ID + in. If not specified, the default is
/var/run/named.pid. + The pid-file is used by programs that want to send signals to + the running + name server. Specifying pid-file none disables the + use of a PID file — no file will be written and any + existing one will be removed. Note that none + is a keyword, not a file name, and therefore is not enclosed + in + double quotes. +- statistics-file
+- +
+ The pathname of the file the server appends statistics + to when instructed to do so using rndc stats. + If not specified, the default is
named.statsin the + server's current directory. The format of the file is + described + in the section called “The Statistics File” +- port
+- +
+ The UDP/TCP port number the server uses for + receiving and sending DNS protocol traffic. + The default is 53. This option is mainly intended for server + testing; + a server using a port other than 53 will not be able to + communicate with + the global DNS. +
- random-device
+- +
+ The source of entropy to be used by the server. Entropy is + primarily needed + for DNSSEC operations, such as TKEY transactions and dynamic + update of signed + zones. This options specifies the device (or file) from which + to read + entropy. If this is a file, operations requiring entropy will + fail when the + file has been exhausted. If not specified, the default value + is +
/dev/random+ (or equivalent) when present, and none otherwise. The + random-device option takes + effect during + the initial configuration load at server startup time and + is ignored on subsequent reloads. +- preferred-glue
+- +
+ If specified the listed type (A or AAAA) will be emitted + before other glue + in the additional section of a query response. + The default is not to preference any type (NONE). +
- root-delegation-only
+- +
+ Turn on enforcement of delegation-only in TLDs and root zones + with an optional + exclude list. +
++ Note some TLDs are NOT delegation only (e.g. "DE", "LV", "US" + and "MUSEUM"). +
++options { root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; }; -- disable-algorithms
Disable the specified DNSSEC algorithms at and below the specified name. -Multiple disable-algorithms statements are allowed. -Only the most specific will be applied. -
- dnssec-lookaside
When set dnssec-lookaside provides the -validator with an alternate method to validate DNSKEY records at the -top of a zone. When a DNSKEY is at or below a domain specified by the -deepest dnssec-lookaside, and the normal dnssec validation -has left the key untrusted, the trust-anchor will be append to the key -name and a DLV record will be looked up to see if it can validate the -key. If the DLV record validates a DNSKEY (similarly to the way a DS -record does) the DNSKEY RRset is deemed to be trusted. -
- dnssec-must-be-secure
Specify heirachies which must / may not be secure (signed and validated). -If yes then named will only accept answers if they -are secure. -If no then normal dnssec validation applies -allowing for insecure answers to be accepted. -The specified domain must be under a trusted-key or -dnssec-lookaside must be active. -
6.2.16.1. 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 Section 4.1. 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.
Note: 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 Section 6.2.16.17. -
- 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 Section 6.2.18. See also -Section 4.3. -
- provide-ixfr
See the description of -provide-ixfr in -Section 6.2.18 -
- request-ixfr
See the description of -request-ixfr in -Section 6.2.18 -
- 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. -
6.2.16.2. 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. Ifonlyis 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 Section 6.2.23.
6.2.16.3. 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).
6.2.16.4. Access Control
Access to the server can be restricted based on the IP address -of the requesting system. See Section 6.1.1 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. -
Note: 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 -Section 7.3 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 Section 7.3 -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.
+6.2.16.5. 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; }; ++ +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
yesthen named will only accept + answers if they + are secure. + Ifnothen 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. ++ ++++
- auth-nxdomain
+- +
+ If
yes, then the AA bit + is always set on NXDOMAIN responses, even if the server is + not actually + authoritative. The default isno; + this is + a change from BIND 8. If you + are using very old DNS software, you + may need to set it toyes. +- 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 isno. ++ 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 +
+notifywhich only sends NOTIFY + messages, +notify-passivewhich 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 +passivewhich 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-nxdomainyes+ and rfc2308-type1noinstead. +- 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 isno. +- 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 section called “Notify”. 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. + Ifexplicit, notifies are sent only + to + servers explicitly listed using also-notify. + Ifno, 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
+yeswill + cause the server to send NS records along with the SOA + record for negative + answers. The default isno. +++Note
++ 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 the section called “The Statistics File”. +- 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 the section called “server Statement Definition and + Usage”. + See also + the section called “Incremental Zone Transfers (IXFR)”. +
- provide-ixfr
+- +
+ See the description of + provide-ixfr in + the section called “server Statement Definition and + Usage” +
- request-ixfr
+- +
+ See the description of + request-ixfr in + the section called “server Statement Definition and + Usage” +
- 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) formail.example.netwill 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 isno. +- 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. +
+ +++ 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. Ifonlyis + 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 the section called “zone + Statement Grammar”. +
++ +++ 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 to the server can be restricted based on the IP address + of the requesting system. See the section called “Address Match Lists” 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. +
+++Note
++ 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 + the section called “Dynamic Update Security” 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 the section called “Dynamic Update Security” + 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. ++ ++ 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.
If no listen-on is specified, the -server will listen on port 53 on all interfaces.
The listen-on-v6 option is used to -specify the interfaces and the ports on which the server will listen -for incoming queries sent using IPv6.
When
{ any; }is specified -as theaddress_match_listfor the -listen-on-v6 option, -the server does not bind a separate socket to each IPv6 interface -address as it does for IPv4 if the operating system has enough API -support for IPv6 (specifically if it conforms to RFC 3493 and RFC 3542). -Instead, it listens on the IPv6 wildcard address. -If the system only has incomplete API support for IPv6, however, -the behavior is the same as that for IPv4.A list of particular IPv6 addresses can also be specified, in which case -the server listens on a separate socket for each specified address, -regardless of whether the desired API is supported by the system.
Multiple listen-on-v6 options can be used. -For example,
listen-on-v6 { any; }; +++ will enable the name server on port 53 for the IP address + 5.6.7.8, and on port 1234 of an address on the machine in net + 1.2 that is not 1.2.3.4. +
++ If no listen-on is specified, the + server will listen on port 53 on all interfaces. +
++ The listen-on-v6 option is used to + specify the interfaces and the ports on which the server will + listen + for incoming queries sent using IPv6. +
++ When
+{ any; }+is + specified + as the
+address_match_listfor the + listen-on-v6 option, + the server does not bind a separate socket to each IPv6 interface + address as it does for IPv4 if the operating system has enough API + support for IPv6 (specifically if it conforms to RFC 3493 and RFC + 3542). + Instead, it listens on the IPv6 wildcard address. + If the system only has incomplete API support for IPv6, however, + the behavior is the same as that for IPv4. ++ A list of particular IPv6 addresses can also be specified, in + which case + the server listens on a separate socket for each specified + address, + regardless of whether the desired API is supported by the system. +
++ Multiple listen-on-v6 options can + be used. + For example, +
+listen-on-v6 { any; }; listen-on-v6 port 1234 { !2001:db8::/32; any; }; -will enable the name server on port 53 for any IPv6 addresses -(with a single wildcard socket), -and on port 1234 of IPv6 addresses that is not in the prefix -2001:db8::/32 (with separate sockets for each matched address.)
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.
+6.2.16.6. 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 *; +++ 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 +
+listen-on-v6 { none; }; +++ If no listen-on-v6 option is + specified, + the server will not listen on any IPv6 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 *; -Note: 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.
Note: See also transfer-source and -notify-source.
6.2.16.7. Zone Transfers
BIND has mechanisms in place to facilitate zone transfers -and set limits on the amount of load that transfers place on the -system. The following options apply to zone transfers.
- also-notify
Defines a global list of IP addresses of name servers -that are also sent NOTIFY messages whenever a fresh copy of the -zone is loaded, in addition to the servers listed in the zone's NS records. -This helps to ensure that copies of the zones will -quickly converge on stealth servers. If an also-notify list -is given in a zone statement, it will override -the options also-notify statement. When a zone notify statement -is set to no, the IP addresses in the global also-notify list will -not be sent NOTIFY messages for that zone. The default is the empty -list (no global notification list).
- max-transfer-time-in
Inbound zone transfers running longer than -this many minutes will be terminated. The default is 120 minutes -(2 hours). The maximum value is 28 days (40320 minutes).
- max-transfer-idle-in
Inbound zone transfers making no progress -in this many minutes will be terminated. The default is 60 minutes -(1 hour). The maximum value is 28 days (40320 minutes).
- max-transfer-time-out
Outbound zone transfers running longer than -this many minutes will be terminated. The default is 120 minutes -(2 hours). The maximum value is 28 days (40320 minutes).
- max-transfer-idle-out
Outbound zone transfers making no progress -in this many minutes will be terminated. The default is 60 minutes (1 -hour). The maximum value is 28 days (40320 minutes).
- serial-query-rate
Slave servers will periodically query master servers -to find out if zone serial numbers have changed. Each such query uses -a minute amount of the slave server's network bandwidth. To limit the -amount of bandwidth used, BIND 9 limits the rate at which queries are -sent. The value of the serial-query-rate option, -an integer, is the maximum number of queries sent per second. -The default is 20. -
- serial-queries
In BIND 8, the serial-queries option -set the maximum number of concurrent serial number queries -allowed to be outstanding at any given time. -BIND 9 does not limit the number of outstanding -serial queries and ignores the serial-queries option. -Instead, it limits the rate at which the queries are sent -as defined using the serial-query-rate option. -
- transfer-format
Zone transfers can be sent using two different formats, -one-answer and many-answers. -The transfer-format option is used -on the master server to determine which format it sends. -one-answer uses one DNS message per -resource record transferred. -many-answers packs as many resource records as -possible into a message. many-answers is more -efficient, but is only supported by relatively new slave servers, -such as BIND 9, BIND 8.x and patched -versions of BIND 4.9.5. The default is -many-answers. transfer-format -may be overridden on a per-server basis by using the -server statement. -
- transfers-in
The maximum number of inbound zone transfers -that can be running concurrently. The default value is 10. -Increasing transfers-in may speed up the convergence -of slave zones, but it also may increase the load on the local system.
- transfers-out
The maximum number of outbound zone transfers -that can be running concurrently. Zone transfer requests in excess -of the limit will be refused. The default value is 10.
- transfers-per-ns
The maximum number of inbound zone transfers -that can be concurrently transferring from a given remote name server. -The default value is 2. Increasing transfers-per-ns may -speed up the convergence of slave zones, but it also may increase -the load on the remote name server. transfers-per-ns may -be overridden on a per-server basis by using the transfers phrase -of the server statement.
- transfer-source
transfer-source determines -which local address will be bound to IPv4 TCP connections used to -fetch zones transferred inbound by the server. It also determines -the source IPv4 address, and optionally the UDP port, used for the -refresh queries and forwarded dynamic updates. If not set, it defaults -to a system controlled value which will usually be the address of -the interface "closest to" the remote end. This address must appear -in the remote end's allow-transfer option for -the zone being transferred, if one is specified. This statement -sets the transfer-source for all zones, but can -be overridden on a per-view or per-zone basis by including a -transfer-source statement within the -view or zone block -in the configuration file.
- transfer-source-v6
The same as transfer-source, -except zone transfers are performed using IPv6.
- alt-transfer-source
An alternate transfer source if the one listed in -transfer-source fails and -use-alt-transfer-source is set.
- alt-transfer-source-v6
An alternate transfer source if the one listed in -transfer-source-v6 fails and -use-alt-transfer-source is set.
- use-alt-transfer-source
Use the alternate transfer sources or not. If views are -specified this defaults to no otherwise it defaults to -yes (for BIND 8 compatibility).
- notify-source
notify-source determines -which local source address, and optionally UDP port, will be used to -send NOTIFY messages. -This address must appear in the slave server's masters -zone clause or in an allow-notify clause. -This statement sets the notify-source for all zones, -but can be overridden on a per-zone / per-view basis by including a -notify-source statement within the zone -or view block in the configuration file.
- notify-source-v6
Like notify-source, -but applies to notify messages sent to IPv6 addresses.
6.2.16.8. 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. -
6.2.16.9. Operating System Resource Limits
The server's usage of many system resources can be limited. -Scaled values are allowed when specifying resource limits. For -example, 1G can be used instead of -1073741824 to specify a limit of one -gigabyte. unlimited requests unlimited use, or the -maximum available amount. default uses the limit -that was in force when the server was started. See the description of -size_spec in Section 6.1.
The following options set operating system resource limits for -the name server process. Some operating systems don't support some or -any of the limits. On such systems, a warning will be issued if the -unsupported limit is used.
- coresize
The maximum size of a core dump. The default -is default.
- datasize
The maximum amount of data memory the server -may use. The default is default. -This is a hard limit on server memory usage. -If the server attempts to allocate memory in excess of this -limit, the allocation will fail, which may in turn leave -the server unable to perform DNS service. Therefore, -this option is rarely useful as a way of limiting the -amount of memory used by the server, but it can be used -to raise an operating system data size limit that is -too small by default. If you wish to limit the amount -of memory used by the server, use the -max-cache-size and -recursive-clients -options instead. -
- files
The maximum number of files the server -may have open concurrently. The default is unlimited. -
- stacksize
The maximum amount of stack memory the server -may use. The default is default.
6.2.16.10. 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 -(Section 4.2.1). When the journal file approaches -the specified size, some of the oldest transactions in the journal -will be automatically removed. The default is -unlimited.
- host-statistics-max
In BIND 8, specifies the maximum number of host statistic -entries to be kept. -Not implemented in BIND 9. -
- recursive-clients
The maximum number of simultaneous recursive lookups -the server will perform on behalf of clients. The default is -1000. Because each recursing client uses a fair -bit of memory, on the order of 20 kilobytes, the value of the -recursive-clients option may have to be decreased -on hosts with limited memory. -
- tcp-clients
The maximum number of simultaneous client TCP -connections that the server will accept. -The default is 100.
- max-cache-size
The maximum amount of memory to use for the -server's cache, in bytes. When the amount of data in the cache -reaches this limit, the server will cause records to expire -prematurely so that the limit is not exceeded. In a server with -multiple views, the limit applies separately to the cache of each -view. The default is unlimited, meaning that -records are purged from the cache only when their TTLs expire. -
- tcp-listen-queue
The listen queue depth. The default and minimum is 3. -If the kernel supports the accept filter "dataready" this also controls how -many TCP connections that will be queued in kernel space waiting for -some data before being passed to accept. Values less than 3 will be -silently raised. -
6.2.16.11. Periodic Task Intervals
- cleaning-interval
The server will remove expired resource records -from the cache every cleaning-interval minutes. -The default is 60 minutes. The maximum value is 28 days (40320 minutes). -If set to 0, no periodic cleaning will occur.
- heartbeat-interval
The server will perform zone maintenance tasks -for all zones marked as dialup whenever this -interval expires. The default is 60 minutes. Reasonable values are up -to 1 day (1440 minutes). The maximum value is 28 days (40320 minutes). -If set to 0, no zone maintenance for these zones will occur.
- interface-interval
The server will scan the network interface list -every interface-interval minutes. The default -is 60 minutes. The maximum value is 28 days (40320 minutes). -If set to 0, interface scanning will only occur when -the configuration file is loaded. After the scan, the server will -begin listening for queries on any newly discovered -interfaces (provided they are allowed by the -listen-on configuration), and will -stop listening on interfaces that have gone away.
- statistics-interval
Name server statistics will be logged -every statistics-interval minutes. The default is -60. The maximum value is 28 days (40320 minutes). -If set to 0, no statistics will be logged.
Note: Not yet implemented in BIND9.
+6.2.16.12. Topology
All other things being equal, when the server chooses a name server -to query from a list of name servers, it prefers the one that is -topologically closest to itself. The topology statement -takes an address_match_list and interprets it -in a special way. Each top-level list element is assigned a distance. -Non-negated elements get a distance based on their position in the -list, where the closer the match is to the start of the list, the -shorter the distance is between it and the server. A negated match -will be assigned the maximum distance from the server. If there -is no match, the address will get a distance which is further than -any non-negated list element, and closer than any negated element. -For example,
topology { ++++Note
++ 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. +
+++Note
++ See also transfer-source and + notify-source. +
++ +++ BIND has mechanisms in place to + facilitate zone transfers + and set limits on the amount of load that transfers place on the + system. The following options apply to zone transfers. +
+++
- also-notify
+- +
+ Defines a global list of IP addresses of name servers + that are also sent NOTIFY messages whenever a fresh copy of + the + zone is loaded, in addition to the servers listed in the + zone's NS records. + This helps to ensure that copies of the zones will + quickly converge on stealth servers. If an also-notify list + is given in a zone statement, + it will override + the options also-notify + statement. When a zone notify + statement + is set to no, the IP + addresses in the global also-notify list will + not be sent NOTIFY messages for that zone. The default is + the empty + list (no global notification list). +
- max-transfer-time-in
+- +
+ Inbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). +
- max-transfer-idle-in
+- +
+ Inbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes + (1 hour). The maximum value is 28 days (40320 minutes). +
- max-transfer-time-out
+- +
+ Outbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). +
- max-transfer-idle-out
+- +
+ Outbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes (1 + hour). The maximum value is 28 days (40320 minutes). +
- serial-query-rate
+- +
+ Slave servers will periodically query master servers + to find out if zone serial numbers have changed. Each such + query uses + a minute amount of the slave server's network bandwidth. To + limit the + amount of bandwidth used, BIND 9 limits the rate at which + queries are + sent. The value of the serial-query-rate option, + an integer, is the maximum number of queries sent per + second. + The default is 20. +
- serial-queries
+- +
+ In BIND 8, the serial-queries + option + set the maximum number of concurrent serial number queries + allowed to be outstanding at any given time. + BIND 9 does not limit the number of outstanding + serial queries and ignores the serial-queries option. + Instead, it limits the rate at which the queries are sent + as defined using the serial-query-rate option. +
- transfer-format
+- +
+ Zone transfers can be sent using two different formats, + one-answer and many-answers. + The transfer-format option is + used + on the master server to determine which format it sends. + one-answer uses one DNS + message per + resource record transferred. + many-answers packs as many + resource records as + possible into a message. many-answers is more + efficient, but is only supported by relatively new slave + servers, + such as BIND 9, BIND 8.x and patched + versions of BIND 4.9.5. The + default is + many-answers. transfer-format + may be overridden on a per-server basis by using the + server statement. +
- transfers-in
+- +
+ The maximum number of inbound zone transfers + that can be running concurrently. The default value is
10. + Increasing transfers-in may + speed up the convergence + of slave zones, but it also may increase the load on the + local system. +- transfers-out
+- +
+ The maximum number of outbound zone transfers + that can be running concurrently. Zone transfer requests in + excess + of the limit will be refused. The default value is
10. +- transfers-per-ns
+- +
+ The maximum number of inbound zone transfers + that can be concurrently transferring from a given remote + name server. + The default value is
2. + Increasing transfers-per-ns + may + speed up the convergence of slave zones, but it also may + increase + the load on the remote name server. transfers-per-ns may + be overridden on a per-server basis by using the transfers phrase + of the server statement. +- transfer-source
+- +
transfer-source + determines which local address will be bound to IPv4 + TCP connections used to fetch zones transferred + inbound by the server. It also determines the + source IPv4 address, and optionally the UDP port, + used for the refresh queries and forwarded dynamic + updates. If not set, it defaults to a system + controlled value which will usually be the address + of the interface "closest to" the remote end. This + address must appear in the remote end's + allow-transfer option for the + zone being transferred, if one is specified. This + statement sets the + transfer-source for all zones, + but can be overridden on a per-view or per-zone + basis by including a + transfer-source statement within + the view or + zone block in the configuration + file. +
- transfer-source-v6
+- +
+ The same as transfer-source, + except zone transfers are performed using IPv6. +
- alt-transfer-source
+- +
+ An alternate transfer source if the one listed in + transfer-source fails and + use-alt-transfer-source is + set. +
- alt-transfer-source-v6
+- +
+ An alternate transfer source if the one listed in + transfer-source-v6 fails and + use-alt-transfer-source is + set. +
- use-alt-transfer-source
+- +
+ Use the alternate transfer sources or not. If views are + specified this defaults to no + otherwise it defaults to + yes (for BIND 8 + compatibility). +
- notify-source
+- +
notify-source + determines which local source address, and + optionally UDP port, will be used to send NOTIFY + messages. This address must appear in the slave + server's masters zone clause or + in an allow-notify clause. This + statement sets the notify-source + for all zones, but can be overridden on a per-zone / + per-view basis by including a + notify-source statement within + the zone or + view block in the configuration + file. +
- notify-source-v6
+- +
+ Like notify-source, + but applies to notify messages sent to IPv6 addresses. +
+ ++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 the section called “Configuration File Elements”. +
++ The following options set operating system resource limits for + the name server process. Some operating systems don't support + some or + any of the limits. On such systems, a warning will be issued if + the + unsupported limit is used. +
+++
- coresize
+- +
+ The maximum size of a core dump. The default + is
default. +- datasize
+- +
+ The maximum amount of data memory the server + may use. The default is
default. + This is a hard limit on server memory usage. + If the server attempts to allocate memory in excess of this + limit, the allocation will fail, which may in turn leave + the server unable to perform DNS service. Therefore, + this option is rarely useful as a way of limiting the + amount of memory used by the server, but it can be used + to raise an operating system data size limit that is + too small by default. If you wish to limit the amount + of memory used by the server, use the + max-cache-size and + recursive-clients + options instead. +- files
+- +
+ The maximum number of files the server + may have open concurrently. The default is
unlimited. +- stacksize
+- +
+ The maximum amount of stack memory the server + may use. The default is
default. ++ +++ 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 + (the section called “The journal file”). When the journal file + approaches + the specified size, some of the oldest transactions in the + journal + will be automatically removed. The default is +
unlimited. +- host-statistics-max
+- +
+ In BIND 8, specifies the maximum number of host statistic + entries to be kept. + Not implemented in BIND 9. +
- recursive-clients
+- +
+ The maximum number of simultaneous recursive lookups + the server will perform on behalf of clients. The default + is +
1000. Because each recursing + client uses a fair + bit of memory, on the order of 20 kilobytes, the value of + the + recursive-clients option may + have to be decreased + on hosts with limited memory. +- tcp-clients
+- +
+ The maximum number of simultaneous client TCP + connections that the server will accept. + The default is
100. +- max-cache-size
+- +
+ The maximum amount of memory to use for the + server's cache, in bytes. When the amount of data in the + cache + reaches this limit, the server will cause records to expire + prematurely so that the limit is not exceeded. In a server + with + multiple views, the limit applies separately to the cache of + each + view. The default is
unlimited, meaning that + records are purged from the cache only when their TTLs + expire. +- tcp-listen-queue
+- +
+ The listen queue depth. The default and minimum is 3. + If the kernel supports the accept filter "dataready" this + also controls how + many TCP connections that will be queued in kernel space + waiting for + some data before being passed to accept. Values less than 3 + will be + silently raised. +
+ ++++
- cleaning-interval
+- +
+ The server will remove expired resource records + from the cache every cleaning-interval minutes. + The default is 60 minutes. The maximum value is 28 days + (40320 minutes). + If set to 0, no periodic cleaning will occur. +
- heartbeat-interval
+- +
+ The server will perform zone maintenance tasks + for all zones marked as dialup whenever this + interval expires. The default is 60 minutes. Reasonable + values are up + to 1 day (1440 minutes). The maximum value is 28 days + (40320 minutes). + If set to 0, no zone maintenance for these zones will occur. +
- interface-interval
+- +
+ The server will scan the network interface list + every interface-interval + minutes. The default + is 60 minutes. The maximum value is 28 days (40320 minutes). + If set to 0, interface scanning will only occur when + the configuration file is loaded. After the scan, the + server will + begin listening for queries on any newly discovered + interfaces (provided they are allowed by the + listen-on configuration), and + will + stop listening on interfaces that have gone away. +
- statistics-interval
+- +
++ Name server statistics will be logged + every statistics-interval + minutes. The default is + 60. The maximum value is 28 days (40320 minutes). + If set to 0, no statistics will be logged. +
+++Note
++ Not yet implemented in + BIND9. +
++ ++ 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
topology { localhost; localnets; }; -Note: The topology option -is not implemented in BIND 9. -
+6.2.16.13. The sortlist 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 Section 6.2.16.14). -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 (Section 6.2.16.12). -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 { +};++ 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; }; ++++Note
++ The topology option + is not implemented in BIND 9. +
++ ++ 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 section called “RRset Ordering”). + 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 (the section called “Topology”). + 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 192.168.1/24; // following nets @@ -7359,1539 +3538,782 @@ CLASS="programlisting" { 192.168.1/24; 192.168.2/24; }; }; }; { { 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.
sortlist { +};++ 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; }; }; -+6.2.16.14. 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, -Section 6.2.16.13. -
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 { +++ ++ 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, + the section called “The sortlist Statement”. +
++ An order_spec is defined as + follows: +
++ [class
+class_name] + [typetype_name] + [name"domain_name"] + orderordering++ 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.
Note: The rrset-order statement -is not yet fully implemented in BIND 9. -BIND 9 currently does not support "fixed" ordering. -
6.2.16.15. Tuning
- lame-ttl
Sets the number of seconds to cache a -lame server indication. 0 disables caching. (This is -NOT recommended.) -Default is 600 (10 minutes). Maximum value is -1800 (30 minutes).
- max-ncache-ttl
To reduce network traffic and increase performance -the server stores negative answers. max-ncache-ttl is -used to set a maximum retention time for these answers in the server -in seconds. The default -max-ncache-ttl is 10800 seconds (3 hours). -max-ncache-ttl cannot exceed 7 days and will -be silently truncated to 7 days if set to a greater value.
- max-cache-ttl
max-cache-ttl sets -the maximum time for which the server will cache ordinary (positive) -answers. The default is one week (7 days).
- min-roots
The minimum number of root servers that -is required for a request for the root servers to be accepted. Default -is 2.
Note: Not implemented in BIND9.
- sig-validity-interval
Specifies the number of days into the -future when DNSSEC signatures automatically generated as a result -of dynamic updates (Section 4.2) -will expire. The default is 30 days. -The maximum value is 10 years (3660 days). The signature -inception time is unconditionally set to one hour before the current time -to allow for a limited amount of clock skew.
- min-refresh-time, max-refresh-time, min-retry-time, max-retry-time
These options control the server's behavior on refreshing a zone -(querying for SOA changes) or retrying failed transfers. -Usually the SOA values for the zone are used, but these values -are set by the master, giving slave server administrators little -control over their contents. -
These options allow the administrator to set a minimum and maximum -refresh and retry time either per-zone, per-view, or globally. -These options are valid for slave and stub zones, -and clamp the SOA refresh and retry times to the specified values. -
- edns-udp-size
edns-udp-size sets the advertised EDNS UDP buffer -size. Valid values are 512 to 4096 (values outside this range will be -silently adjusted). The default value is 4096. The usual reason for -setting edns-udp-size to a non default value it to get UDP answers to -pass through broken firewalls that block fragmented packets and/or -block UDP packets that are greater than 512 bytes. -
6.2.16.16. 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 Section 6.2.21) of class -CHAOS which is separate from the default view of -class IN; therefore, any global server options -such as allow-query do not apply the these zones. -If you feel the need to disable these zones, use the options -below, or hide the built-in CHAOS view by -defining an explicit view of class CHAOS -that matches all clients.
- version
The version the server should report -via a query of the name version.bind -with type TXT, class CHAOS. -The default is the real version number of this server. -Specifying version none -disables processing of the queries.
- hostname
The hostname the server should report via a query of -the name hostname.bind -with type TXT, class CHAOS. -This defaults to the hostname of the machine hosting the name server as -found by gethostname(). The primary purpose of such queries is to -identify which of a group of anycast servers is actually -answering your queries. Specifying hostname none; -disables processing of the queries.
- server-id
The ID of the server should report via a query of -the name ID.SERVER -with type TXT, class CHAOS. -The primary purpose of such queries is to -identify which of a group of anycast servers is actually -answering your queries. Specifying server-id none; -disables processing of the queries. -Specifying server-id hostname; will cause named to -use the hostname as found by gethostname(). -The default server-id is none. -
6.2.16.17. The Statistics File
The statistics file generated by BIND 9 -is similar, but not identical, to that -generated by BIND 8. -
The statistics dump begins with the line +++ Statistics Dump -+++ (973798949), where the number in parentheses is a standard -Unix-style timestamp, measured as seconds since January 1, 1970. Following -that line are a series of lines containing a counter type, the value of the -counter, optionally a zone name, and optionally a view name. -The lines without view and zone listed are global statistics for the entire server. -Lines with a zone and view name for the given view and zone (the view name is -omitted for the default view). The statistics dump ends -with the line --- Statistics Dump --- (973798949), where the -number is identical to the number in the beginning line.
The following statistics counters are maintained:
success
The number of -successful queries made to the server or zone. A successful query -is defined as query which returns a NOERROR response with at least -one answer RR.
referral
The number of queries which resulted -in referral responses.
nxrrset
The number of queries which resulted in -NOERROR responses with no data.
nxdomain
The number -of queries which resulted in NXDOMAIN responses.
failure
The number of queries which resulted in a -failure response other than those above.
recursion
The number of queries which caused the server -to perform recursion in order to find the final answer.
Each query received by the server will cause exactly one of -success, -referral, -nxrrset, -nxdomain, or -failure -to be incremented, and may additionally cause the -recursion counter to be incremented. -
6.2.16.18. Additional Section Caching
The additional section cache, also called acache, -is an internal cache to improve the response performance of BIND 9. -When the additional section caching is enabled, BIND 9 will -cache internal short-cut to the additional section content for each -answer RR. -Note that acache is an internal caching mechanism of BIND 9, and is -not relevant to the DNS caching server function. -
The additional section caching does not make any difference on the -response content (except the RRsets ordering of the additional -section, see below), but can improve the response performance significantly. -It is particularly effective when BIND 9 acts as an authoritative server -for a zone that has many delegations with many glue RRs. -
In order to achieve the maximum performance improvement by acache, -it is recommended to set additional-from-cache -to no, since the current implementation of acache -does not make a short-cut of additional section information from a DNS -cache data. -
One obvious disadvantage of acache is that it requires much more -memory for the internal cached data. -Thus, if the response performance does not matter and memory -consumption is much more severe, the acache mechanism can be -disabled by setting use-additional-cache to -no. -It is also possible to specify the upper limit of memory consumption -for acache by max-acache-size. -
The additional section caching also has a minor effect on the RRset -ordering in the additional section. -Without acache, the "cyclic" order is effective for the additional -section as well as the answer and authority sections. -However, the additional section caching fixes the ordering when it -first caches an RRset for the additional section, and the same -ordering will be kept in succeeding responses, regardless of the -configuration for rrset-order. -This should be minor, though, since an RRset in the additional section -typically only contains a small number of RRs (and in many cases it -only contains a single RR), in which case the -ordering does not matter much. -
The following is a summary of options related to acache. -
- use-additional-cache
If yes, the additional section caching is enabled. -The default value is yes. -
- acache-cleaning-interval
The server will remove stale cache entries, based on an LRU based -algorithm, every acache-cleaning-interval minutes. -The default is 60 minutes. -If set to 0, no periodic cleaning will occur. -
- max-acache-size
The maximum amount of memory to use for the server's acache, in bytes. -When the amount of data in the acache reaches this limit, the server -will cause more aggressive cleaning so that the limit is not exceeded. -In a server with multiple views, the limit applies separately to the -acache of each view. -The default is unlimited, meaning that -entries are purged from acache only at the periodic cleaning time. -
+6.2.17. server Statement Grammar
server ip_addr[/prefixlen] { - [ bogus yes_or_no ; ] - [ provide-ixfr yes_or_no ; ] - [ request-ixfr yes_or_no ; ] - [ edns yes_or_no ; ] - [ transfers number ; ] - [ transfer-format ( one-answer | many-answers ) ; ]] - [ keys { string ; [ string ; [...]] } ; ] - [ transfer-source (ip4_addr |+*) [port ip_port] ; ] - [ transfer-source-v6 (ip6_addr |*) [port ip_port] ; ] ++ 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. +
+++Note
++ The rrset-order statement + is not yet fully implemented in BIND 9. + BIND 9 currently does not support "fixed" ordering. +
++ ++++
- 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
10800seconds (3 hours). + max-ncache-ttl cannot exceed + 7 days and will + be silently truncated to 7 days if set to a greater value. +- max-cache-ttl
+- +
max-cache-ttl + sets the maximum time for which the server will + cache ordinary (positive) answers. The default is + one week (7 days). +
- min-roots
+- +
++ The minimum number of root servers that + is required for a request for the root servers to be + accepted. Default + is
+2. +++Note
++ Not implemented in BIND9. +
+- sig-validity-interval
+- +
+ Specifies the number of days into the + future when DNSSEC signatures automatically generated as a + result + of dynamic updates (the section called “Dynamic Update”) + will expire. The default is
30days. + The maximum value is 10 years (3660 days). The signature + inception time is unconditionally set to one hour before the + current time + to allow for a limited amount of clock skew. +- +min-refresh-time, max-refresh-time, min-retry-time, max-retry-time +
+- +
++ These options control the server's behavior on refreshing a + zone + (querying for SOA changes) or retrying failed transfers. + Usually the SOA values for the zone are used, but these + values + are set by the master, giving slave server administrators + little + control over their contents. +
++ These options allow the administrator to set a minimum and + maximum + refresh and retry time either per-zone, per-view, or + globally. + These options are valid for slave and stub zones, + and clamp the SOA refresh and retry times to the specified + values. +
+- edns-udp-size
+- +
edns-udp-size + sets the advertised EDNS UDP buffer size. Valid + values are 512 to 4096 (values outside this range + will be silently adjusted). The default value is + 4096. The usual reason for setting edns-udp-size to + a non default value it to get UDP answers to pass + through broken firewalls that block fragmented + packets and/or block UDP packets that are greater + than 512 bytes. +
+ +++ The server provides some helpful diagnostic information + through a number of built-in zones under the + pseudo-top-level-domain
+bindin the + CHAOS class. These zones are part + of a + built-in view (see the section called “view Statement Grammar”) of + class + CHAOS which is separate from the + default view of + class IN; therefore, any global + server options + such as allow-query do not apply + the these zones. + If you feel the need to disable these zones, use the options + below, or hide the built-in CHAOS + view by + defining an explicit view of class CHAOS + that matches all clients. +++
- version
+- +
+ The version the server should report + via a query of the name
version.bind+ with type TXT, class CHAOS. + The default is the real version number of this server. + Specifying version none + disables processing of the queries. +- hostname
+- +
+ The hostname the server should report via a query of + the name
hostname.bind+ with type TXT, class CHAOS. + This defaults to the hostname of the machine hosting the + name server as + found by gethostname(). The primary purpose of such queries + is to + identify which of a group of anycast servers is actually + answering your queries. Specifying hostname none; + disables processing of the queries. +- server-id
+- +
+ The ID of the server should report via a query of + the name
ID.SERVER+ with type TXT, class CHAOS. + The primary purpose of such queries is to + identify which of a group of anycast servers is actually + answering your queries. Specifying server-id none; + disables processing of the queries. + Specifying server-id hostname; will cause named to + use the hostname as found by gethostname(). + The default server-id is none. ++ +++ The statistics file generated by BIND 9 + is similar, but not identical, to that + generated by BIND 8. +
++ The statistics dump begins with the line +++ Statistics Dump ++++ (973798949), where the number in parentheses is a standard + Unix-style timestamp, measured as seconds since January 1, 1970. + Following + that line are a series of lines containing a counter type, the + value of the + counter, optionally a zone name, and optionally a view name. + The lines without view and zone listed are global statistics for + the entire server. + Lines with a zone and view name for the given view and zone (the + view name is + omitted for the default view). The statistics dump ends + with the line --- Statistics Dump --- (973798949), where the + number is identical to the number in the beginning line. +
++ The following statistics counters are maintained: +
+++
+ + ++ + + ++ +success
++ ++ The number of + successful queries made to the server or zone. A + successful query + is defined as query which returns a NOERROR response + with at least + one answer RR. +
++ ++ +referral
++ ++ The number of queries which resulted + in referral responses. +
++ ++ +nxrrset
++ ++ The number of queries which resulted in + NOERROR responses with no data. +
++ ++ +nxdomain
++ ++ The number + of queries which resulted in NXDOMAIN responses. +
++ ++ +failure
++ ++ The number of queries which resulted in a + failure response other than those above. +
++ + ++ +recursion
++ ++ The number of queries which caused the server + to perform recursion in order to find the final answer. +
++ Each query received by the server will cause exactly one of + success, + referral, + nxrrset, + nxdomain, or + failure + to be incremented, and may additionally cause the + recursion counter to be + incremented. +
++ +++ The additional section cache, also called acache, + is an internal cache to improve the response performance of BIND + 9. + When the additional section caching is enabled, BIND 9 will + cache internal short-cut to the additional section content for + each + answer RR. + Note that acache is an internal caching mechanism of BIND 9, and + is + not relevant to the DNS caching server function. +
++ The additional section caching does not make any difference on the + response content (except the RRsets ordering of the additional + section, see below), but can improve the response performance + significantly. + It is particularly effective when BIND 9 acts as an authoritative + server + for a zone that has many delegations with many glue RRs. +
++ In order to achieve the maximum performance improvement by acache, + it is recommended to set additional-from-cache + to no, since the current + implementation of acache + does not make a short-cut of additional section information from a + DNS + cache data. +
++ One obvious disadvantage of acache is that it requires much more + memory for the internal cached data. + Thus, if the response performance does not matter and memory + consumption is much more severe, the acache mechanism can be + disabled by setting use-additional-cache to + no. + It is also possible to specify the upper limit of memory + consumption + for acache by max-acache-size. +
++ The additional section caching also has a minor effect on the + RRset + ordering in the additional section. + Without acache, the "cyclic" order is effective for the additional + section as well as the answer and authority sections. + However, the additional section caching fixes the ordering when it + first caches an RRset for the additional section, and the same + ordering will be kept in succeeding responses, regardless of the + configuration for rrset-order. + This should be minor, though, since an RRset in the additional + section + typically only contains a small number of RRs (and in many cases + it + only contains a single RR), in which case the + ordering does not matter much. +
++ The following is a summary of options related to acache. +
+++
- use-additional-cache
+- +
+ If yes, the additional section caching is enabled. + The default value is yes. +
- acache-cleaning-interval
+- +
+ The server will remove stale cache entries, based on an LRU + based + algorithm, every acache-cleaning-interval minutes. + The default is 60 minutes. + If set to 0, no periodic cleaning will occur. +
- max-acache-size
+- +
+ The maximum amount of memory to use for the server's acache, + in bytes. + When the amount of data in the acache reaches this limit, + the server + will cause more aggressive cleaning so that the limit is not + exceeded. + In a server with multiple views, the limit applies + separately to the + acache of each view. + The default is
unlimited, + meaning that + entries are purged from acache only at the periodic cleaning + time. ++ +serverip_addr[/prefixlen]{ + [ bogusyes_or_no; ] + [ provide-ixfryes_or_no; ] + [ request-ixfryes_or_no; ] + [ ednsyes_or_no; ] + [ transfersnumber; ] + [ transfer-format( one-answer | many-answers ); ]] + [ keys{ string ; [ string ; [...]] }; ] + [ transfer-source (ip4_addr|*) [portip_port] ; ] + [ transfer-source-v6 (ip6_addr|*) [portip_port] ; ] }; -6.2.18. server Statement Definition and Usage
The server statement defines characteristics -to be associated with a remote name server. If a prefix length is -specified then a range of servers is covered. Only the most specific -server clause applies regardless of the order in -named.conf.
The server statement can occur at the top level of the -configuration file or inside a view statement. -If a view statement contains -one or more server statements, only those -apply to the view and any top-level ones are ignored. -If a view contains no server statements, -any top-level server statements are used as -defaults. -
If you discover that a remote server is giving out bad data, -marking it as bogus will prevent further queries to it. The default -value of bogus is no.
The provide-ixfr clause determines whether -the local server, acting as master, will respond with an incremental -zone transfer when the given remote server, a slave, requests it. -If set to yes, incremental transfer will be provided -whenever possible. If set to no, all transfers -to the remote server will be non-incremental. If not set, the value -of the provide-ixfr option in the view or -global options block is used as a default.
The request-ixfr clause determines whether -the local server, acting as a slave, will request incremental zone -transfers from the given remote server, a master. If not set, the -value of the request-ixfr option in the view or -global options block is used as a default.
IXFR requests to servers that do not support IXFR will automatically -fall back to AXFR. Therefore, there is no need to manually list -which servers support IXFR and which ones do not; the global default -of yes should always work. -The purpose of the provide-ixfr and -request-ixfr clauses is -to make it possible to disable the use of IXFR even when both master -and slave claim to support it, for example if one of the servers -is buggy and crashes or corrupts data when IXFR is used.
The edns clause determines whether the local server -will attempt to use EDNS when communicating with the remote server. The -default is yes.
The server supports two zone transfer methods. The first, one-answer, -uses one DNS message per resource record transferred. many-answers packs -as many resource records as possible into a message. many-answers is -more efficient, but is only known to be understood by BIND 9, BIND -8.x, and patched versions of BIND 4.9.5. You can specify which method -to use for a server with the transfer-format option. -If transfer-format is not specified, the transfer-format specified -by the options statement will be used.
transfers is used to limit the number of -concurrent inbound zone transfers from the specified server. If -no transfers clause is specified, the limit is -set according to the transfers-per-ns option.
The keys clause identifies a -key_id defined by the key statement, -to be used for transaction security (TSIG, Section 4.5) -when talking to the remote server. -When a request is sent to the remote server, a request signature -will be generated using the key specified here and appended to the -message. A request originating from the remote server is not required -to be signed by this key.
Although the grammar of the keys clause -allows for multiple keys, only a single key per server is currently -supported.
The transfer-source and -transfer-source-v6 clauses specify the IPv4 and IPv6 source -address to be used for zone transfer with the remote server, respectively. -For an IPv4 remote server, only transfer-source can -be specified. -Similarly, for an IPv6 remote server, only -transfer-source-v6 can be specified. -Form more details, see the description of -transfer-source and -transfer-source-v6 in -Section 6.2.16.7.
+6.2.19. trusted-keys Statement Grammar
trusted-keys { - string number number number string ; - [ string number number number string ; [...]] +++ +++ The server statement defines + characteristics + to be associated with a remote name server. If a prefix length is + specified then a range of servers is covered. Only the most + specific + server clause applies regardless of the order in +
+named.conf. ++ The server statement can occur at + the top level of the + configuration file or inside a view + statement. + If a view statement contains + one or more server statements, only + those + apply to the view and any top-level ones are ignored. + If a view contains no server + statements, + any top-level server statements are + used as + defaults. +
++ If you discover that a remote server is giving out bad data, + marking it as bogus will prevent further queries to it. The + default + value of bogus is no. +
++ The provide-ixfr clause determines + whether + the local server, acting as master, will respond with an + incremental + zone transfer when the given remote server, a slave, requests it. + If set to yes, incremental transfer + will be provided + whenever possible. If set to no, + all transfers + to the remote server will be non-incremental. If not set, the + value + of the provide-ixfr option in the + view or + global options block is used as a default. +
++ The request-ixfr clause determines + whether + the local server, acting as a slave, will request incremental zone + transfers from the given remote server, a master. If not set, the + value of the request-ixfr option in + the view or + global options block is used as a default. +
++ IXFR requests to servers that do not support IXFR will + automatically + fall back to AXFR. Therefore, there is no need to manually list + which servers support IXFR and which ones do not; the global + default + of yes should always work. + The purpose of the provide-ixfr and + request-ixfr clauses is + to make it possible to disable the use of IXFR even when both + master + and slave claim to support it, for example if one of the servers + is buggy and crashes or corrupts data when IXFR is used. +
++ The edns clause determines whether + the local server + will attempt to use EDNS when communicating with the remote + server. The + default is yes. +
++ The server supports two zone transfer methods. The first, one-answer, + uses one DNS message per resource record transferred. many-answers packs + as many resource records as possible into a message. many-answers is + more efficient, but is only known to be understood by BIND 9, BIND + 8.x, and patched versions of BIND + 4.9.5. You can specify which method + to use for a server with the transfer-format option. + If transfer-format is not + specified, the transfer-format + specified + by the options statement will be + used. +
+transfers + is used to limit the number of concurrent inbound zone + transfers from the specified server. If no + transfers clause is specified, the + limit is set according to the + transfers-per-ns option. +
++ The keys clause identifies a + key_id defined by the key statement, + to be used for transaction security (TSIG, the section called “TSIG”) + when talking to the remote server. + When a request is sent to the remote server, a request signature + will be generated using the key specified here and appended to the + message. A request originating from the remote server is not + required + to be signed by this key. +
++ Although the grammar of the keys + clause + allows for multiple keys, only a single key per server is + currently + supported. +
++ The transfer-source and + transfer-source-v6 clauses specify + the IPv4 and IPv6 source + address to be used for zone transfer with the remote server, + respectively. + For an IPv4 remote server, only transfer-source can + be specified. + Similarly, for an IPv6 remote server, only + transfer-source-v6 can be + specified. + Form more details, see the description of + transfer-source and + transfer-source-v6 in + the section called “Zone Transfers”. +
++ +trusted-keys { +stringnumbernumbernumberstring; + [stringnumbernumbernumberstring; [...]] }; -6.2.20. trusted-keys Statement Definition -and Usage
The trusted-keys statement defines DNSSEC -security roots. DNSSEC is described in Section 4.8. 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.
+6.2.21. view Statement Grammar
view view_name - [class] { - match-clients { address_match_list } ; - match-destinations { address_match_list } ; - match-recursive-only yes_or_no ; - [ view_option; ...] - [ zone_statement; ...] +++ +++ The trusted-keys statement defines + DNSSEC + security roots. DNSSEC is described in the section called “DNSSEC”. 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. +
++ +viewview_name+ [class] { + match-clients {address_match_list} ; + match-destinations {address_match_list} ; + match-recursive-onlyyes_or_no; + [view_option; ...] + [zone_statement; ...] }; -+6.2.22. view Statement Definition and Usage
The view statement is a powerful new feature -of BIND 9 that lets a name server answer a DNS query differently -depending on who is asking. It is particularly useful for implementing -split DNS setups without having to run multiple servers.
Each view statement defines a view of the -DNS namespace that will be seen by a subset of clients. A client matches -a view if its source IP address matches the -
address_match_listof the view's -match-clients clause and its destination IP address matches -theaddress_match_listof the view's -match-destinations clause. If not specified, both -match-clients and match-destinations -default to matching all addresses. In addition to checking IP addresses -match-clients and match-destinations -can also take keys which provide an mechanism for the -client to select the view. A view can also be specified -as match-recursive-only, which means that only recursive -requests from matching clients will match that view. -The order of the view statements is significant — -a client request will be resolved in the context of the first -view that it matches.Zones defined within a view statement will -be only be accessible to clients that match the view. - By defining a zone of the same name in multiple views, different -zone data can be given to different clients, for example, "internal" -and "external" clients in a split DNS setup.
Many of the options given in the options statement -can also be used within a view statement, and then -apply only when resolving queries with that view. When no view-specific -value is given, the value in the options statement -is used as a default. Also, zone options can have default values specified -in the view statement; these view-specific defaults -take precedence over those in the options statement.
Views are class specific. If no class is given, class IN -is assumed. Note that all non-IN views must contain a hint zone, -since only the IN class has compiled-in default hints.
If there are no view statements in the config -file, a default view that matches any client is automatically created -in class IN. Any zone statements specified on -the top level of the configuration file are considered to be part of -this default view, and the options statement will -apply to the default view. If any explicit view -statements are present, all zone statements must -occur inside view statements.
Here is an example of a typical split DNS setup implemented -using view statements.
view "internal" { +++ ++ The view statement is a powerful + new feature + of BIND 9 that lets a name server + answer a DNS query differently + depending on who is asking. It is particularly useful for + implementing + split DNS setups without having to run multiple servers. +
++ Each view statement defines a view + of the + DNS namespace that will be seen by a subset of clients. A client + matches + a view if its source IP address matches the +
+address_match_listof the view's + match-clients clause and its + destination IP address matches + theaddress_match_listof the + view's + match-destinations clause. If not + specified, both + match-clients and match-destinations + default to matching all addresses. In addition to checking IP + addresses + match-clients and match-destinations + can also take keys which provide an + mechanism for the + client to select the view. A view can also be specified + as match-recursive-only, which + means that only recursive + requests from matching clients will match that view. + The order of the view statements is + significant — + a client request will be resolved in the context of the first + view that it matches. ++ Zones defined within a view + statement will + be only be accessible to clients that match the view. + By defining a zone of the same name in multiple views, different + zone data can be given to different clients, for example, + "internal" + and "external" clients in a split DNS setup. +
++ Many of the options given in the options statement + can also be used within a view + statement, and then + apply only when resolving queries with that view. When no + view-specific + value is given, the value in the options statement + is used as a default. Also, zone options can have default values + specified + in the view statement; these + view-specific defaults + take precedence over those in the options statement. +
++ Views are class specific. If no class is given, class IN + is assumed. Note that all non-IN views must contain a hint zone, + since only the IN class has compiled-in default hints. +
++ If there are no view statements in + the config + file, a default view that matches any client is automatically + created + in class IN. Any zone statements + specified on + the top level of the configuration file are considered to be part + of + this default view, and the options + statement will + apply to the default view. If any explicit view + statements are present, all zone + statements must + occur inside view statements. +
++ Here is an example of a typical split DNS setup implemented + using view statements. +
+view "internal" { // This should match our internal networks. match-clients { 10.0.0.0/8; }; @@ -8920,3664 +4342,2122 @@ view "external" { file "example-external.db"; }; }; -+6.2.23. zone -Statement Grammar
zone zone_name [class] [{ +++ +zonezone_name[class] [{ type ( master | slave | hint | stub | forward | delegation-only ) ; - [ allow-notify { address_match_list } ; ] - [ allow-query { address_match_list } ; ] - [ allow-transfer { address_match_list } ; ] - [ allow-update { address_match_list } ; ] - [ update-policy { update_policy_rule [...] } ; ] - [ allow-update-forwarding { address_match_list } ; ] - [ also-notify { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ; ... ] }; ] - [ check-names (warn|fail|ignore) ; ] - [ check-wildcard yes_or_no; ] - [ dialup dialup_option ; ] - [ delegation-only yes_or_no ; ] - [ file string ; ] - [ journal string ; ] - [ forward (only|first) ; ] - [ forwarders { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ; ... ] }; ] - [ ixfr-base string ; ] - [ ixfr-tmp-file string ; ] - [ maintain-ixfr-base yes_or_no ; ] - [ masters [port ip_port] { ( masters_list | ip_addr [port ip_port] [key key] ) ; [...] } ; ] - [ max-ixfr-log-size number ; ] - [ max-transfer-idle-in number ; ] - [ max-transfer-idle-out number ; ] - [ max-transfer-time-in number ; ] - [ max-transfer-time-out number ; ] - [ notify yes_or_no | explicit | master-only ; ] - [ pubkey number number number string ; ] - [ transfer-source (ip4_addr |*) [port ip_port] ; ] - [ transfer-source-v6 (ip6_addr |*) [port ip_port] ; ] - [ alt-transfer-source (ip4_addr |*) [port ip_port] ; ] - [ alt-transfer-source-v6 (ip6_addr |*) [port ip_port] ; ] - [ use-alt-transfer-source yes_or_no; ] - [ notify-source (ip4_addr |*) [port ip_port] ; ] - [ notify-source-v6 (ip6_addr |*) [port ip_port] ; ] - [ zone-statistics yes_or_no ; ] - [ sig-validity-interval number ; ] - [ database string ; ] - [ min-refresh-time number ; ] - [ max-refresh-time number ; ] - [ min-retry-time number ; ] - [ max-retry-time number ; ] - [ multi-master yes_or_no ; ] - [ key-directory path_name; ] + [ allow-notify {address_match_list} ; ] + [ allow-query {address_match_list} ; ] + [ allow-transfer {address_match_list} ; ] + [ allow-update {address_match_list} ; ] + [ update-policy {update_policy_rule[...] } ; ] + [ allow-update-forwarding {address_match_list} ; ] + [ also-notify {ip_addr[portip_port] ; [ip_addr[portip_port] ; ... ] }; ] + [ check-names (warn|fail|ignore) ; ] + [ check-wildcardyes_or_no; ] + [ dialupdialup_option; ] + [ delegation-onlyyes_or_no; ] + [ filestring; ] + [ journalstring; ] + [ forward (only|first) ; ] + [ forwarders {ip_addr[portip_port] ; [ip_addr[portip_port] ; ... ] }; ] + [ ixfr-basestring; ] + [ ixfr-tmp-filestring; ] + [ maintain-ixfr-baseyes_or_no; ] + [ masters [portip_port] { (masters_list|ip_addr[portip_port] [keykey] ) ; [...] } ; ] + [ max-ixfr-log-sizenumber; ] + [ max-transfer-idle-innumber; ] + [ max-transfer-idle-outnumber; ] + [ max-transfer-time-innumber; ] + [ max-transfer-time-outnumber; ] + [ notifyyes_or_no|explicit|master-only; ] + [ pubkeynumbernumbernumberstring; ] + [ transfer-source (ip4_addr|*) [portip_port] ; ] + [ transfer-source-v6 (ip6_addr|*) [portip_port] ; ] + [ alt-transfer-source (ip4_addr|*) [portip_port] ; ] + [ alt-transfer-source-v6 (ip6_addr|*) [portip_port] ; ] + [ use-alt-transfer-sourceyes_or_no; ] + [ notify-source (ip4_addr|*) [portip_port] ; ] + [ notify-source-v6 (ip6_addr|*) [portip_port] ; ] + [ zone-statisticsyes_or_no; ] + [ sig-validity-intervalnumber; ] + [ databasestring; ] + [ min-refresh-timenumber; ] + [ max-refresh-timenumber; ] + [ min-retry-timenumber; ] + [ max-retry-timenumber; ] + [ multi-masteryes_or_no; ] + [ key-directorypath_name; ] -}]; -+6.2.24. zone Statement Definition and Usage
+6.2.24.1. Zone Types
+
masterThe server has a master copy of the data -for the zone and will be able to provide authoritative answers for -it.
slaveA 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. -
+}]; + + ++ ++ ++
+ + ++ + + ++ ++
+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.commight place + the zone contents into a file called +ex/example.comwhereex/is + just the first two letters of the zone name. (Most + operating systems + behave very slowly if you put 100 000 files into + a single directory.) ++ + ++
+stub++ + A stub zone is similar to a slave zone, + except that it replicates only the NS records of a + master zone instead + of the entire zone. Stub zones are not a standard part + of the DNS; + they are a feature specific to the BIND implementation. +
-Stub zones can be used to eliminate the need for glue NS record -in a parent zone at the expense of maintaining a stub zone entry and -a set of name server addresses in named.conf. -This usage is not recommended for new configurations, and BIND 9 -supports it only in a limited way. -In BIND 4/8, zone transfers of a parent zone -included the NS records from stub children of that zone. This meant -that, in some cases, users could get away with configuring child stubs -only in the master server for the parent zone. BIND -9 never mixes together zone data from different zones in this -way. Therefore, if a BIND 9 master serving a parent -zone has child stub zones configured, all the slave servers for the -parent zone also need to have the same child stub zones -configured.
++ Stub zones can be used to eliminate the need for glue + NS record + in a parent zone at the expense of maintaining a stub + zone entry and + a set of name server addresses in
-named.conf. + This usage is not recommended for new configurations, + and BIND 9 + supports it only in a limited way. + In BIND 4/8, zone + transfers of a parent zone + included the NS records from stub children of that + zone. This meant + that, in some cases, users could get away with + configuring child stubs + only in the master server for the parent zone. BIND + 9 never mixes together zone data from different zones + in this + way. Therefore, if a BIND 9 master serving a parent + zone has child stub zones configured, all the slave + servers for the + parent zone also need to have the same child stub + zones + configured. +Stub zones can also be used as a way of forcing the resolution -of a given domain to use a particular set of authoritative servers. -For example, the caching name servers on a private network using -RFC1981 addressing may be configured with stub zones for -10.in-addr.arpa -to use a set of internal name servers as the authoritative -servers for that domain.
-
forwardA "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.
-
hintThe 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-onlyThis 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-onlyhas no effect on answers received -from forwarders.6.2.24.2. 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.
6.2.24.3. 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 Section 6.2.16.4
- allow-query
See the description of -allow-query in Section 6.2.16.4
- allow-transfer
See the description of allow-transfer -in Section 6.2.16.4.
- allow-update
See the description of allow-update -in Section 6.2.16.4.
- update-policy
Specifies a "Simple Secure Update" policy. See -Section 6.2.24.4.
- allow-update-forwarding
See the description of allow-update-forwarding -in Section 6.2.16.4.
- also-notify
Only meaningful if notify is -active for this zone. The set of machines that will receive a -DNS NOTIFY message -for this zone is made up of all the listed name servers (other than -the primary master) for the zone plus any IP addresses specified -with also-notify. A port may be specified -with each also-notify address to send the notify -messages to a port other than the default of 53. -also-notify is not meaningful for stub zones. -The default is the empty list.
- check-names
This option is used to restrict the character set and syntax of -certain domain names in master files and/or DNS responses received from the -network. The default varies according to zone type. For master zones the default is fail. For slave -zones the default is warn. -
- check-wildcard
See the description of -check-wildcard in Section 6.2.16.1.
- database
Specify the type of database to be used for storing the -zone data. The string following the database keyword -is interpreted as a list of whitespace-delimited words. The first word -identifies the database type, and any subsequent words are passed -as arguments to the database to be interpreted in a way specific -to the database type.
The default is "rbt", BIND 9's native in-memory -red-black-tree database. This database does not take arguments.
Other values are possible if additional database drivers -have been linked into the server. Some sample drivers are included -with the distribution but none are linked in by default.
- dialup
See the description of -dialup in Section 6.2.16.1.
- delegation-only
The flag only applies to hint and stub zones. If set -to yes then the zone will also be treated as if it -is also a delegation-only type zone. -
- forward
Only meaningful if the zone has a forwarders -list. The only value causes the lookup to fail -after trying the forwarders and getting no answer, while first would -allow a normal lookup to be tried.
- forwarders
Used to override the list of global forwarders. -If it is not specified in a zone of type forward, -no forwarding is done for the zone; the global options are not used.
- ixfr-base
Was used in BIND 8 to specify the name -of the transaction log (journal) file for dynamic update and IXFR. -BIND 9 ignores the option and constructs the name of the journal -file by appending ".jnl" to the name of the -zone file.
- ixfr-tmp-file
Was an undocumented option in BIND 8. -Ignored in BIND 9.
- max-transfer-time-in
See the description of -max-transfer-time-in in Section 6.2.16.7.
- max-transfer-idle-in
See the description of -max-transfer-idle-in in Section 6.2.16.7.
- max-transfer-time-out
See the description of -max-transfer-time-out in Section 6.2.16.7.
- max-transfer-idle-out
See the description of -max-transfer-idle-out in Section 6.2.16.7.
- notify
See the description of -notify in Section 6.2.16.1.
- pubkey
In BIND 8, this option was intended for specifying -a public zone key for verification of signatures in DNSSEC signed -zones when they are loaded from disk. BIND 9 does not verify signatures -on load and ignores the option.
- zone-statistics
If yes, the server will keep statistical -information for this zone, which can be dumped to the -statistics-file defined in the server options.
- sig-validity-interval
See the description of -sig-validity-interval in Section 6.2.16.15.
- transfer-source
See the description of -transfer-source in Section 6.2.16.7 -
- transfer-source-v6
See the description of -transfer-source-v6 in Section 6.2.16.7 -
- alt-transfer-source
See the description of -alt-transfer-source in Section 6.2.16.7 -
- alt-transfer-source-v6
See the description of -alt-transfer-source-v6 in Section 6.2.16.7 -
- use-alt-transfer-source
See the description of -use-alt-transfer-source in Section 6.2.16.7 -
- notify-source
See the description of -notify-source in Section 6.2.16.7 -
- notify-source-v6
See the description of -notify-source-v6 in Section 6.2.16.7. -
- min-refresh-time, max-refresh-time, min-retry-time, max-retry-time
See the description in Section 6.2.16.15. -
- ixfr-from-differences
See the description of -ixfr-from-differences in Section 6.2.16.1.
- key-directory
See the description of -key-directory in Section 6.2.16
- multi-master
See the description of -multi-master in Section 6.2.16.1.
6.2.24.4. Dynamic Update Policies
BIND 9 supports two alternative methods of granting clients -the right to perform dynamic updates to a zone, -configured by the allow-update and -update-policy option, respectively.
The allow-update clause works the same -way as in previous versions of BIND. It grants given clients the -permission to update any record of any name in the zone.
The update-policy clause is new in BIND -9 and allows more fine-grained control over what updates are allowed. -A set of rules is specified, where each rule either grants or denies -permissions for one or more names to be updated by one or more identities. - If the dynamic update request message is signed (that is, it includes -either a TSIG or SIG(0) record), the identity of the signer can -be determined.
Rules are specified in the update-policy zone -option, and are only meaningful for master zones. When the update-policy statement -is present, it is a configuration error for the allow-update statement -to be present. The update-policy statement only -examines the signer of a message; the source address is not relevant.
This is how a rule definition looks:
( grant | deny ) identity nametype name [ types ] -Each rule grants or denies privileges. Once a message has -successfully matched a rule, the operation is immediately granted -or denied and no further rules are examined. A rule is matched -when the signer matches the identity field, the name matches the -name field in accordance with the nametype field, and the type matches -the types specified in the type field.
The identity field specifies a name or a wildcard name. Normally, this -is the name of the TSIG or SIG(0) key used to sign the update request. When a -TKEY exchange has been used to create a shared secret, the identity of the -shared secret is the same as the identity of the key used to authenticate the -TKEY exchange. When the identity field specifies a -wildcard name, it is subject to DNS wildcard expansion, so the rule will apply -to multiple identities. The identity field must -contain a fully qualified domain name.
The nametype field has 4 values: -
name,subdomain, -wildcard, andself. -
nameExact-match semantics. This rule matches when the -name being updated is identical to the contents of the -name field.
subdomainThis rule matches when the name being updated -is a subdomain of, or identical to, the contents of the -name field.
wildcardThe 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.
selfThis 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 -
selfnametype is most useful when allowing using -one key per name to update, where the key has the same name as the name -to be updated. The identity would be -specified as*in this case.In all cases, the name field must -specify a fully qualified domain name.
If no types are explicitly specified, this rule matches all types except -SIG, NS, SOA, and NXT. Types may be specified by name, including -"ANY" (ANY matches all types except NXT, which can never be updated). -Note that when an attempt is made to delete all records associated with a -name, the rules are checked for each existing record type. -
6.3. Zone File
6.3.1. 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.
6.3.1.1. Resource Records
A domain name identifies a node. Each node has a set of - resource information, which may be empty. The set of resource - information associated with a particular name is composed of - separate RRs. The order of RRs in a set is not significant and - need not be preserved by name servers, resolvers, or other - parts of the DNS. However, sorting of multiple RRs is - permitted for optimization purposes, for example, to specify - that a particular nearby server be tried first. See Section 6.2.16.13 and Section 6.2.16.14.
The components of a Resource Record are:
owner name
the domain name where the RR is found.
type
an encoded 16 bit value that specifies -the type of the resource record.
TTL
the time to live of the RR. This field -is a 32 bit integer in units of seconds, and is primarily used by -resolvers when they cache RRs. The TTL describes how long a RR can -be cached before it should be discarded.
class
an encoded 16 bit value that identifies -a protocol family or instance of a protocol.
RDATA
the resource data. The format of the -data is type (and sometimes class) specific.
The following are types of valid RRs:
A
a host address. In the IN class, this is a -32-bit IP address. Described in RFC 1035.
AAAA
IPv6 address. Described in RFC 1886.
A6
IPv6 address. This can be a partial -address (a suffix) and an indirection to the name where the rest of the -address (the prefix) can be found. Experimental. Described in RFC 2874.
AFSDB
location of AFS database servers. -Experimental. Described in RFC 1183.
APL
address prefix list. Experimental. -Described in RFC 3123.
CERT
holds a digital certificate. -Described in RFC 2538.
CNAME
identifies the canonical name of an alias. -Described in RFC 1035.
DNAME
Replaces the domain name specified with -another name to be looked up, effectively aliasing an entire -subtree of the domain name space rather than a single record -as in the case of the CNAME RR. -Described in RFC 2672.
GPOS
Specifies the global position. Superseded by LOC.
HINFO
identifies the CPU and OS used by a host. -Described in RFC 1035.
ISDN
representation of ISDN addresses. -Experimental. Described in RFC 1183.
KEY
stores a public key associated with a -DNS name. Described in RFC 2535.
KX
identifies a key exchanger for this -DNS name. Described in RFC 2230.
LOC
for storing GPS info. Described in RFC 1876. -Experimental.
MX
identifies a mail exchange for the domain. -a 16 bit preference value (lower is better) -followed by the host name of the mail exchange. -Described in RFC 974, RFC 1035.
NAPTR
name authority pointer. Described in RFC 2915.
NSAP
a network service access point. -Described in RFC 1706.
NS
the authoritative name server for the -domain. Described in RFC 1035.
NXT
used in DNSSEC to securely indicate that -RRs with an owner name in a certain name interval do not exist in -a zone and indicate what RR types are present for an existing name. -Described in RFC 2535.
PTR
a pointer to another part of the domain -name space. Described in RFC 1035.
PX
provides mappings between RFC 822 and X.400 -addresses. Described in RFC 2163.
RP
information on persons responsible -for the domain. Experimental. Described in RFC 1183.
RT
route-through binding for hosts that -do not have their own direct wide area network addresses. -Experimental. Described in RFC 1183.
SIG
("signature") contains data authenticated -in the secure DNS. Described in RFC 2535.
SOA
identifies the start of a zone of authority. -Described in RFC 1035.
SRV
information about well known network -services (replaces WKS). Described in RFC 2782.
TXT
text records. Described in RFC 1035.
WKS
information about which well known -network services, such as SMTP, that a domain supports. Historical. -
X25
representation of X.25 network addresses. -Experimental. Described in RFC 1183.
The following classes of resource records -are currently valid in the DNS:
IN
The Internet.
CH
CHAOSnet, a LAN protocol created at MIT in the mid-1970s. -Rarely used for its historical purpose, but reused for BIND's -built-in server information zones, e.g., -version.bind. -
HS
Hesiod, an information service -developed by MIT's Project Athena. It is used to share information -about various systems databases, such as users, groups, printers -and so on. -
The owner name is often implicit, rather than forming an integral -part of the RR. For example, many name servers internally form tree -or hash structures for the name space, and chain RRs off nodes. - The remaining RR parts are the fixed header (type, class, TTL) -which is consistent for all RRs, and a variable part (RDATA) that -fits the needs of the resource being described.
The meaning of the TTL field is a time limit on how long an -RR can be kept in a cache. This limit does not apply to authoritative -data in zones; it is also timed out, but by the refreshing policies -for the zone. The TTL is assigned by the administrator for the -zone where the data originates. While short TTLs can be used to -minimize caching, and a zero TTL prohibits caching, the realities -of Internet performance suggest that these times should be on the -order of days for the typical host. If a change can be anticipated, -the TTL can be reduced prior to the change to minimize inconsistency -during the change, and then increased back to its former value following -the change.
The data in the RDATA section of RRs is carried as a combination -of binary strings and domain names. The domain names are frequently -used as "pointers" to other data in the DNS.
6.3.1.2. 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:
This example shows two addresses for XX.LCS.MIT.EDU, -each of a different class.
6.3.2. Discussion of MX Records
As described above, domain servers store information as a -series of resource records, each of which contains a particular -piece of information about a given domain name (which is usually, -but not always, a host). The simplest way to think of a RR is as -a typed pair of data, a domain name matched with a relevant datum, -and stored with some additional type information to help systems -determine when the RR is relevant.
MX records are used to control delivery of email. The data -specified in the record is a priority and a domain name. The priority -controls the order in which email delivery is attempted, with the -lowest number first. If two priorities are the same, a server is -chosen randomly. If no servers at a given priority are responding, -the mail transport agent will fall back to the next largest priority. -Priority numbers do not have any absolute meaning — they are relevant -only respective to other MX records for that domain name. The domain -name given is the machine to which the mail will be delivered. It must have -an associated A record — CNAME is not sufficient.
For a given domain, if there is both a CNAME record and an -MX record, the MX record is in error, and will be ignored. Instead, -the mail will be delivered to the server specified in the MX record -pointed to by the CNAME.
example.com.
IN
MX
10
mail.example.com.
IN
MX
10
mail2.example.com.
IN
MX
20
mail.backup.org.
mail.example.com.
IN
A
10.0.0.1
mail2.example.com.
IN
A
10.0.0.2
For example:
Mail delivery will be attempted to mail.example.com and -mail2.example.com (in -any order), and if neither of those succeed, delivery to mail.backup.org will -be attempted.
6.3.3. 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.
6.3.4. 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:
Note: 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.
6.3.5. 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.
6.3.5.1. The $ORIGIN 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-SERVERis equivalent to
WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM.6.3.5.2. The $INCLUDE 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.
Note: -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. -
6.3.5.3. The $TTL 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.
6.3.6. BIND Master File Extension: the $GENERATE 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. ++ 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-onlyhas no + effect on answers received + from forwarders. ++ +++ The zone's name may optionally be followed by a class. If + a class is not specified, class
+IN(forInternet), + is assumed. This is correct for the vast majority of cases. ++ The
+hesiodclass 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 +HSis + 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
+CHAOSclass. ++ ++++
- 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 the section called “Access Control” +
- allow-query
+- +
+ See the description of + allow-query in the section called “Access Control” +
- allow-transfer
+- +
+ See the description of allow-transfer + in the section called “Access Control”. +
- allow-update
+- +
+ See the description of allow-update + in the section called “Access Control”. +
- update-policy
+- +
+ Specifies a "Simple Secure Update" policy. See + the section called “Dynamic Update Policies”. +
- allow-update-forwarding
+- +
+ See the description of allow-update-forwarding + in the section called “Access Control”. +
- also-notify
+- +
+ Only meaningful if notify + is + active for this zone. The set of machines that will + receive a +
DNS NOTIFYmessage + for this zone is made up of all the listed name servers + (other than + the primary master) for the zone plus any IP addresses + specified + with also-notify. A port + may be specified + with each also-notify + address to send the notify + messages to a port other than the default of 53. + also-notify is not + meaningful for stub zones. + The default is the empty list. +- check-names
+- +
+ This option is used to restrict the character set and + syntax of + certain domain names in master files and/or DNS responses + received from the + network. The default varies according to zone type. For master zones the default is fail. For slave + zones the default is warn. +
- check-wildcard
+- +
+ See the description of + check-wildcard in the section called “Boolean Options”. +
- database
+- +
++ Specify the type of database to be used for storing the + zone data. The string following the database keyword + is interpreted as a list of whitespace-delimited words. + The first word + identifies the database type, and any subsequent words are + passed + as arguments to the database to be interpreted in a way + specific + to the database type. +
++ The default is
+"rbt", BIND 9's + native in-memory + red-black-tree database. This database does not take + arguments. ++ Other values are possible if additional database drivers + have been linked into the server. Some sample drivers are + included + with the distribution but none are linked in by default. +
+- dialup
+- +
+ See the description of + dialup in the section called “Boolean Options”. +
- delegation-only
+- +
+ The flag only applies to hint and stub zones. If set + to
yesthen the zone will also be + treated as if it + is also a delegation-only type zone. +- forward
+- +
+ Only meaningful if the zone has a forwarders + list. The only value causes + the lookup to fail + after trying the forwarders and getting no answer, while first would + allow a normal lookup to be tried. +
- forwarders
+- +
+ Used to override the list of global forwarders. + If it is not specified in a zone of type forward, + no forwarding is done for the zone; the global options are + not used. +
- ixfr-base
+- +
+ Was used in BIND 8 to + specify the name + of the transaction log (journal) file for dynamic update + and IXFR. + BIND 9 ignores the option + and constructs the name of the journal + file by appending "
.jnl" + to the name of the + zone file. +- ixfr-tmp-file
+- +
+ Was an undocumented option in BIND 8. + Ignored in BIND 9. +
- max-transfer-time-in
+- +
+ See the description of + max-transfer-time-in in the section called “Zone Transfers”. +
- max-transfer-idle-in
+- +
+ See the description of + max-transfer-idle-in in the section called “Zone Transfers”. +
- max-transfer-time-out
+- +
+ See the description of + max-transfer-time-out in the section called “Zone Transfers”. +
- max-transfer-idle-out
+- +
+ See the description of + max-transfer-idle-out in the section called “Zone Transfers”. +
- notify
+- +
+ See the description of + notify in the section called “Boolean 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. +
- zone-statistics
+- +
+ If
yes, the server will keep + statistical + information for this zone, which can be dumped to the + statistics-file defined in + the server options. +- sig-validity-interval
+- +
+ See the description of + sig-validity-interval in the section called “Tuning”. +
- transfer-source
+- +
+ See the description of + transfer-source in the section called “Zone Transfers” +
- transfer-source-v6
+- +
+ See the description of + transfer-source-v6 in the section called “Zone Transfers” +
- alt-transfer-source
+- +
+ See the description of + alt-transfer-source in the section called “Zone Transfers” +
- alt-transfer-source-v6
+- +
+ See the description of + alt-transfer-source-v6 in the section called “Zone Transfers” +
- use-alt-transfer-source
+- +
+ See the description of + use-alt-transfer-source in the section called “Zone Transfers” +
- notify-source
+- +
+ See the description of + notify-source in the section called “Zone Transfers” +
- notify-source-v6
+- +
+ See the description of + notify-source-v6 in the section called “Zone Transfers”. +
- +min-refresh-time, max-refresh-time, min-retry-time, max-retry-time +
+- +
+ See the description in the section called “Tuning”. +
- ixfr-from-differences
+- +
+ See the description of + ixfr-from-differences in the section called “Boolean Options”. +
- key-directory
+- +
+ See the description of + key-directory in the section called “options Statement Definition and + Usage” +
- multi-master
+- +
+ See the description of + multi-master in the section called “Boolean Options”. +
+ +++ 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 )+identitynametypename[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
+identityfield specifies a + wildcard name, it is subject to DNS wildcard expansion, so the + rule will apply + to multiple identities. Theidentityfield must + contain a fully qualified domain name. ++ The
+nametypefield has 4 + values: +name,subdomain, +wildcard, andself. +++
+ + ++ + + ++ ++
+name++ ++ Exact-match semantics. This rule matches when the + name being updated is identical to the contents of the +
+namefield. ++ ++ ++
+subdomain++ ++ This rule matches when the name being updated + is a subdomain of, or identical to, the contents of + the +
+namefield. ++ ++ ++
+wildcard++ ++ The
+namefield + 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
+identityfield. + Thenamefield + is ignored, but should be + the same as theidentityfield. The +selfnametype 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. Theidentitywould be + specified as*in + this case. ++ In all cases, the
+name+ field must + specify a fully qualified domain name. ++ If no types are explicitly specified, this rule matches all + types except + SIG, NS, SOA, and NXT. Types may be specified by name, including + "ANY" (ANY matches all types except NXT, which can never be + updated). + Note that when an attempt is made to delete all records + associated with a + name, the rules are checked for each existing record type. +
++ ++ +++ 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. +
++ +++ 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 the section called “The sortlist Statement” and the section called “RRset Ordering”. +
++ The components of a Resource Record are: +
+++
+ + ++ + + ++ ++ owner name +
++ ++ the domain name where the RR is found. +
++ ++ ++ type +
++ ++ an encoded 16 bit value that specifies + the type of the resource record. +
++ ++ ++ TTL +
++ ++ the time to live of the RR. This field + is a 32 bit integer in units of seconds, and is + primarily used by + resolvers when they cache RRs. The TTL describes how + long a RR can + be cached before it should be discarded. +
++ ++ ++ class +
++ ++ an encoded 16 bit value that identifies + a protocol family or instance of a protocol. +
++ + ++ ++ RDATA +
++ ++ the resource data. The format of the + data is type (and sometimes class) specific. +
++ The following are types of valid RRs: +
+++
+ + ++ + + ++ ++ A +
++ ++ a host address. In the IN class, this is a + 32-bit IP address. Described in RFC 1035. +
++ ++ ++ AAAA +
++ ++ IPv6 address. Described in RFC 1886. +
++ ++ ++ A6 +
++ ++ IPv6 address. This can be a partial + address (a suffix) and an indirection to the name + where the rest of the + address (the prefix) can be found. Experimental. + Described in RFC 2874. +
++ ++ ++ AFSDB +
++ ++ location of AFS database servers. + Experimental. Described in RFC 1183. +
++ ++ ++ APL +
++ ++ address prefix list. Experimental. + Described in RFC 3123. +
++ ++ ++ CERT +
++ ++ holds a digital certificate. + Described in RFC 2538. +
++ ++ ++ CNAME +
++ ++ identifies the canonical name of an alias. + Described in RFC 1035. +
++ ++ ++ DNAME +
++ ++ Replaces the domain name specified with + another name to be looked up, effectively aliasing an + entire + subtree of the domain name space rather than a single + record + as in the case of the CNAME RR. + Described in RFC 2672. +
++ ++ ++ GPOS +
++ ++ Specifies the global position. Superseded by LOC. +
++ ++ ++ HINFO +
++ ++ identifies the CPU and OS used by a host. + Described in RFC 1035. +
++ ++ ++ ISDN +
++ ++ representation of ISDN addresses. + Experimental. Described in RFC 1183. +
++ ++ ++ KEY +
++ ++ stores a public key associated with a + DNS name. Described in RFC 2535. +
++ ++ ++ KX +
++ ++ identifies a key exchanger for this + DNS name. Described in RFC 2230. +
++ ++ ++ LOC +
++ ++ for storing GPS info. Described in RFC 1876. + Experimental. +
++ ++ ++ MX +
++ ++ identifies a mail exchange for the domain. + a 16 bit preference value (lower is better) + followed by the host name of the mail exchange. + Described in RFC 974, RFC 1035. +
++ ++ ++ NAPTR +
++ ++ name authority pointer. Described in RFC 2915. +
++ ++ ++ NSAP +
++ ++ a network service access point. + Described in RFC 1706. +
++ ++ ++ NS +
++ ++ the authoritative name server for the + domain. Described in RFC 1035. +
++ ++ ++ NXT +
++ ++ used in DNSSEC to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Described in RFC 2535. +
++ ++ ++ PTR +
++ ++ a pointer to another part of the domain + name space. Described in RFC 1035. +
++ ++ ++ PX +
++ ++ provides mappings between RFC 822 and X.400 + addresses. Described in RFC 2163. +
++ ++ ++ RP +
++ ++ information on persons responsible + for the domain. Experimental. Described in RFC 1183. +
++ ++ ++ RT +
++ ++ route-through binding for hosts that + do not have their own direct wide area network + addresses. + Experimental. Described in RFC 1183. +
++ ++ ++ SIG +
++ ++ ("signature") contains data authenticated + in the secure DNS. Described in RFC 2535. +
++ ++ ++ SOA +
++ ++ identifies the start of a zone of authority. + Described in RFC 1035. +
++ ++ ++ SRV +
++ ++ information about well known network + services (replaces WKS). Described in RFC 2782. +
++ ++ ++ TXT +
++ ++ text records. Described in RFC 1035. +
++ ++ ++ WKS +
++ ++ information about which well known + network services, such as SMTP, that a domain + supports. Historical. +
++ + ++ ++ X25 +
++ ++ representation of X.25 network addresses. + Experimental. Described in RFC 1183. +
++ The following classes of resource records + are currently valid in the DNS: +
+++
+ + ++ + + ++ ++ IN +
++ ++ The Internet. +
++ ++ ++ CH +
++ ++ CHAOSnet, a LAN protocol created at MIT in the + mid-1970s. + Rarely used for its historical purpose, but reused for + BIND's + built-in server information zones, e.g., +
+version.bind. ++ + ++ ++ HS +
++ ++ Hesiod, an information service + developed by MIT's Project Athena. It is used to share + information + about various systems databases, such as users, + groups, printers + and so on. +
++ The owner name is often implicit, rather than forming an + integral + part of the RR. For example, many name servers internally form + tree + or hash structures for the name space, and chain RRs off nodes. + The remaining RR parts are the fixed header (type, class, TTL) + which is consistent for all RRs, and a variable part (RDATA) + that + fits the needs of the resource being described. +
++ The meaning of the TTL field is a time limit on how long an + RR can be kept in a cache. This limit does not apply to + authoritative + data in zones; it is also timed out, but by the refreshing + policies + for the zone. The TTL is assigned by the administrator for the + zone where the data originates. While short TTLs can be used to + minimize caching, and a zero TTL prohibits caching, the + realities + of Internet performance suggest that these times should be on + the + order of days for the typical host. If a change can be + anticipated, + the TTL can be reduced prior to the change to minimize + inconsistency + during the change, and then increased back to its former value + following + the change. +
++ The data in the RDATA section of RRs is carried as a combination + of binary strings and domain names. The domain names are + frequently + used as "pointers" to other data in the DNS. +
++ +++ 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. +
++ 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.comand +mail2.example.com(in + any order), and if neither of those succeed, delivery tomail.backup.orgwill + be attempted. ++ +++ 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. ++ +++ 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.+++Note
++ 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. +
++ +++ 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. +
++ +++ 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. +++ ++ ++ Syntax: $INCLUDE +
+filename+ [ +origin] + [comment] ++ Read and process the file
+filenameas + 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. +
+++Note
++ 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. +
++ ++ 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 $.0is 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.
|
+ 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. +
+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, + + + + ++Chapter 7. BIND 9 Security Considerations + + + + + + + + ++ +\ No newline at end of file +++Table of Contents
+ ++ ++ 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. acl bogusnets { 0.0.0.0/8; 1.0.0.0/8; 2.0.0.0/8; 192.0.2.0/24; 224.0.0.0/3; 10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16; }; // Set up an ACL called our-nets. Replace this with the real IP numbers. @@ -173,330 +98,149 @@ zone "example.com" { file "m/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
7.2. chroot and setuid (for -UNIX servers)
On UNIX servers, it is possible to run BIND in a chrooted environment -(chroot()) by specifying the "
-t" -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 (
-uuser ). -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
7.2.1. The chroot Environment
In order for a chroot() environment to -work properly in a particular directory -(for example, /var/named), -you will need to set up an environment that includes everything -BIND needs to run. -From BIND's point of view, /var/named is -the root of the filesystem. You will need to adjust the values of options like -like directory and pid-file to account -for this. -
Unlike with earlier versions of BIND, you will typically -not need to compile named -statically nor install shared libraries under the new root. -However, depending on your operating system, you may need -to set up things like -/dev/zero, -/dev/random, -/dev/log, and/or -/etc/localtime. -
7.2.2. Using the setuid Function
Prior to running the named daemon, use -the touch utility (to change file access and -modification times) or the chown utility (to -set the user id and/or group id) on files -to which you want BIND -to write. Note that if the named daemon is running as an -unprivileged user, it will not be able to bind to new restricted ports if the -server is reloaded.
7.3. Dynamic Update Security
Access to the dynamic -update facility should be strictly limited. In earlier versions of -BIND the only way to do this was based on the IP -address of the host requesting the update, by listing an IP address or -network prefix in the allow-update zone option. -This method is insecure since the source address of the update UDP packet -is easily forged. Also note that if the IP addresses allowed by the -allow-update option include the address of a slave -server which performs forwarding of dynamic updates, the master can be -trivially attacked by sending the update to the slave, which will -forward it to the master with its own source IP address causing the -master to approve it without question.
For these reasons, we strongly recommend that updates be -cryptographically authenticated by means of transaction signatures -(TSIG). That is, the allow-update option should -list only TSIG key names, not IP addresses or network -prefixes. Alternatively, the new update-policy -option can be used.
Some sites choose to keep all dynamically updated DNS data -in a subdomain and delegate that subdomain to a separate zone. This -way, the top-level zone containing critical data such as the IP addresses -of public web and mail servers need not allow dynamic update at -all.
+ 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 + +
+
+ On UNIX servers, it is possible to run BIND in a chrooted environment
+ (chroot()) by specifying the "-t"
+ 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 ( -u 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.
+
+ 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. +
++ 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. +
+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.
Setting the serial number to a lower number on the master - server than the slave server means that the slave will not perform - updates to its copy of the zone.
The solution to this is to add 2147483647 (2^31-1) to the - number, reload the zone and make sure all slaves have updated to - the new zone serial number, then reset the number to what you want - it to be, and reload the zone again.
The Internet Software Consortium (ISC) offers a wide range - of support and service agreements for BIND and DHCP servers. Four - levels of premium support are available and each level includes - support for all ISC programs, significant discounts on products - and training, and a recognized priority on bug fixes and - non-funded feature requests. In addition, ISC offers a standard - support agreement package which includes services ranging from bug - fix announcements to remote support. It also includes training in - BIND and DHCP.
To discuss arrangements for support, contact - info@isc.org or visit the - ISC web page at http://www.isc.org/services/support/ - to read more.
Table of Contents
+ ++ 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. +
++ Setting the serial number to a lower number on the master + server than the slave server means that the slave will not perform + updates to its copy of the zone. +
++ The solution to this is to add 2147483647 (2^31-1) to the + number, reload the zone and make sure all slaves have updated to + the new zone serial number, then reset the number to what you want + it to be, and reload the zone again. +
++ The Internet Software Consortium + (ISC) offers a wide range + of support and service agreements for BIND and DHCP servers. Four + levels of premium support are available and each level includes + support for all ISC programs, + significant discounts on products + and training, and a recognized priority on bug fixes and + non-funded feature requests. In addition, ISC offers a standard + support agreement package which includes services ranging from bug + fix announcements to remote support. It also includes training in + BIND and DHCP. +
++ To discuss arrangements for support, contact + info@isc.org or visit the + ISC web page at + http://www.isc.org/services/support/ + + to read more. +
+| BIND 9 Administrator Reference Manual | ||
|---|---|---|
| Prev |
Although the "official" beginning of the Domain Name - System occurred in 1984 with the publication of RFC 920, the - core of the new system was described in 1983 in RFCs 882 and - 883. From 1984 to 1987, the ARPAnet (the precursor to today's - Internet) became a testbed of experimentation for developing the - new naming/addressing scheme in an rapidly expanding, - operational network environment. New RFCs were written and - published in 1987 that modified the original documents to - incorporate improvements based on the working model. RFC 1034, - "Domain Names-Concepts and Facilities", and RFC 1035, "Domain - Names-Implementation and Specification" were published and - became the standards upon which all DNS implementations are - built. -
The first working domain name server, called "Jeeves", was -written in 1983-84 by Paul Mockapetris for operation on DEC Tops-20 -machines located at the University of Southern California's Information -Sciences Institute (USC-ISI) and SRI International's Network Information -Center (SRI-NIC). A DNS server for Unix machines, the Berkeley Internet -Name Domain (BIND) package, was written soon after by a group of -graduate students at the University of California at Berkeley under -a grant from the US Defense Advanced Research Projects Administration -(DARPA). Versions of BIND through 4.8.3 were maintained by the Computer -Systems Research Group (CSRG) at UC Berkeley. Douglas Terry, Mark -Painter, David Riggle and Songnian Zhou made up the initial BIND -project team. After that, additional work on the software package -was done by Ralph Campbell. Kevin Dunlap, a Digital Equipment Corporation -employee on loan to the CSRG, worked on BIND for 2 years, from 1985 -to 1987. Many other people also contributed to BIND development -during that time: Doug Kingston, Craig Partridge, Smoot Carl-Mitchell, -Mike Muuss, Jim Bloom and Mike Schwartz. BIND maintenance was subsequently -handled by Mike Karels and O. Kure.
BIND versions 4.9 and 4.9.1 were released by Digital Equipment -Corporation (now Compaq Computer Corporation). Paul Vixie, then -a DEC employee, became BIND's primary caretaker. Paul was assisted -by Phil Almquist, Robert Elz, Alan Barrett, Paul Albitz, Bryan Beecher, Andrew -Partan, Andy Cherenson, Tom Limoncelli, Berthold Paffrath, Fuat -Baran, Anant Kumar, Art Harkin, Win Treese, Don Lewis, Christophe -Wolfhugel, and others.
BIND Version 4.9.2 was sponsored by Vixie Enterprises. Paul -Vixie became BIND's principal architect/programmer.
BIND versions from 4.9.3 onward have been developed and maintained -by the Internet Software Consortium with support being provided -by ISC's sponsors. As co-architects/programmers, Bob Halley and -Paul Vixie released the first production-ready version of BIND version -8 in May 1997.
BIND development work is made possible today by the sponsorship -of several corporations, and by the tireless work efforts of numerous -individuals.
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.
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/. -
[RFC2136] P. Vixie, S. Thomson, Y. Rekhter, and J. Bound, Dynamic Updates in the Domain Name System, April 1997.
[RFC2845] P. Vixie, O. Gudmundsson, D. Eastlake, 3rd, and B. Wellington, Secret Key Transaction Authentication for DNS (TSIG), May 2000.
[RFC1535] E. Gavron, A Security Problem and Proposed Correction With Widely Deployed DNS Software., October 1993.
[RFC1536] A. Kumar, J. Postel, C. Neuman, P. Danzig, and S. Miller, Common DNS Implementation Errors and Suggested Fixes, October 1993.
[RFC1183] C.F. Everhart, L. A. Mamakos, R. Ullmann, and P. Mockapetris, New DNS RR Definitions, October 1990.
[RFC2168] R. Daniel and M. Mealling, Resolution of Uniform Resource Identifiers using -the Domain Name System, June 1997.
[RFC1876] C. Davis, P. Vixie, T., and I. Dickinson, A Means for Expressing Location Information in the Domain -Name System, January 1996.
[RFC2052] A. Gulbrandsen and P. Vixie, A DNS RR for Specifying the Location of -Services., October 1996.
[RFC2163] A. Allocchio, Using the Internet DNS to Distribute MIXER -Conformant Global Address Mapping, January 1998.
[RFC1464] R. Rosenbaum, Using the Domain Name System To Store Arbitrary String Attributes, May 1993.
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. -
Table of Contents
+ ++ Although the "official" beginning of the Domain Name + System occurred in 1984 with the publication of RFC 920, the + core of the new system was described in 1983 in RFCs 882 and + 883. From 1984 to 1987, the ARPAnet (the precursor to today's + Internet) became a testbed of experimentation for developing the + new naming/addressing scheme in an rapidly expanding, + operational network environment. New RFCs were written and + published in 1987 that modified the original documents to + incorporate improvements based on the working model. RFC 1034, + "Domain Names-Concepts and Facilities", and RFC 1035, "Domain + Names-Implementation and Specification" were published and + became the standards upon which all DNS implementations are + built. +
++ The first working domain name server, called "Jeeves", was + written in 1983-84 by Paul Mockapetris for operation on DEC + Tops-20 + machines located at the University of Southern California's + Information + Sciences Institute (USC-ISI) and SRI International's Network + Information + Center (SRI-NIC). A DNS server for + Unix machines, the Berkeley Internet + Name Domain (BIND) package, was + written soon after by a group of + graduate students at the University of California at Berkeley + under + a grant from the US Defense Advanced Research Projects + Administration + (DARPA). Versions of BIND through + 4.8.3 were maintained by the Computer + Systems Research Group (CSRG) at UC Berkeley. Douglas Terry, Mark + Painter, David Riggle and Songnian Zhou made up the initial BIND + project team. After that, additional work on the software package + was done by Ralph Campbell. Kevin Dunlap, a Digital Equipment + Corporation + employee on loan to the CSRG, worked on BIND for 2 years, from 1985 + to 1987. Many other people also contributed to BIND development + during that time: Doug Kingston, Craig Partridge, Smoot + Carl-Mitchell, + Mike Muuss, Jim Bloom and Mike Schwartz. BIND maintenance was subsequently + handled by Mike Karels and O. Kure. +
++ BIND versions 4.9 and 4.9.1 were + released by Digital Equipment + Corporation (now Compaq Computer Corporation). Paul Vixie, then + a DEC employee, became BIND's + primary caretaker. Paul was assisted + by Phil Almquist, Robert Elz, Alan Barrett, Paul Albitz, Bryan + Beecher, Andrew + Partan, Andy Cherenson, Tom Limoncelli, Berthold Paffrath, Fuat + Baran, Anant Kumar, Art Harkin, Win Treese, Don Lewis, Christophe + Wolfhugel, and others. +
++ BIND Version 4.9.2 was sponsored by + Vixie Enterprises. Paul + Vixie became BIND's principal + architect/programmer. +
++ BIND versions from 4.9.3 onward + have been developed and maintained + by the Internet Software Consortium with support being provided + by ISC's sponsors. As co-architects/programmers, Bob Halley and + Paul Vixie released the first production-ready version of BIND version + 8 in May 1997. +
++ BIND development work is made + possible today by the sponsorship + of several corporations, and by the tireless work efforts of + numerous + individuals. +
++ 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. +
+
+ 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/.
+
[RFC974] Mail Routing and the Domain System. January 1986.
[RFC1034] Domain Names — Concepts and Facilities. November 1987.
[RFC1035] Domain Names — Implementation and + Specification. November 1987.
[RFC2181] Clarifications to the DNS + Specification. July 1997.
[RFC2308] Negative Caching of DNS + Queries. March 1998.
[RFC1995] Incremental Zone Transfer in DNS. August 1996.
[RFC1996] A Mechanism for Prompt Notification of Zone Changes. August 1996.
[RFC2136] Dynamic Updates in the Domain Name System. April 1997.
[RFC2845] Secret Key Transaction Authentication for DNS (TSIG). May 2000.
+ Note: the following list of + RFCs are undergoing major revision by the IETF. +
+[RFC1886] DNS Extensions to support IP + version 6. December 1995.
[RFC2065] Domain Name System Security Extensions. January 1997.
[RFC2137] Secure Domain Name System Dynamic Update. April 1997.
[RFC1535] A Security Problem and Proposed Correction With Widely + Deployed DNS Software.. October 1993.
[RFC1536] Common DNS Implementation + Errors and Suggested Fixes. October 1993.
[RFC1982] Serial Number Arithmetic. August 1996.
[RFC1183] New DNS RR Definitions. October 1990.
[RFC1706] DNS NSAP Resource Records. October 1994.
[RFC2168] Resolution of Uniform Resource Identifiers using + the Domain Name System. June 1997.
[RFC1876] A Means for Expressing Location Information in the + Domain + Name System. January 1996.
[RFC2052] A DNS RR for Specifying the + Location of + Services.. October 1996.
[RFC2163] Using the Internet DNS to + Distribute MIXER + Conformant Global Address Mapping. January 1998.
[RFC2230] Key Exchange Delegation Record for the DNS. October 1997.
[RFC1101] DNS Encoding of Network Names + and Other Types. April 1989.
[RFC1123] Requirements for Internet Hosts - Application and + Support. October 1989.
[RFC1591] Domain Name System Structure and Delegation. March 1994.
[RFC2317] Classless IN-ADDR.ARPA Delegation. March 1998.
[RFC1537] Common DNS Data File + Configuration Errors. October 1993.
[RFC1912] Common DNS Operational and + Configuration Errors. February 1996.
[RFC2010] Operational Criteria for Root Name Servers.. October 1996.
[RFC2219] Use of DNS Aliases for + Network Services.. October 1997.
+ Note: the following list of RFCs, although + DNS-related, are not + concerned with implementing software. +
+[RFC1464] Using the Domain Name System To Store Arbitrary String + Attributes. May 1993.
[RFC1713] Tools for DNS Debugging. November 1994.
[RFC1794] DNS Support for Load + Balancing. April 1995.
[RFC2240] A Legal Basis for Domain Name Allocation. November 1997.
[RFC2345] Domain Names and Company Name Retrieval. May 1998.
[RFC2352] A Convention For Using Legal Names as Domain Names. May 1998.
[RFC1712] DNS Encoding of Geographical + Location. November 1994.
+ 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. +
+Copyright © 2004 Internet Systems Consortium, Inc. ("ISC")
Copyright © 2000-2003 Internet Software Consortium
| Next | ||
| Introduction |
Copyright © 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
Copyright © 2000-2003 Internet Software Consortium
Table of Contents
+lwres — introduction to the lightweight resolver library
+#include <lwres/lwres.h>
+ 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. +
+
+ 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. +
++ 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. +
++ 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. +
+ +lwres_gethostent(3), - + lwres_getipnode(3), - -
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.
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.
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.
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.
lwres_gethostent(3), + lwres_getnameinfo(3), -lwres_getipnode(3), + lwres_noop(3), -lwres_getnameinfo(3), + lwres_gabn(3), -lwres_noop(3), + lwres_gnba(3), -lwres_gabn(3), + lwres_context(3), -lwres_gnba(3), + lwres_config(3), -lwres_context(3), + resolver(5), -lwres_config(3), + lwresd(8). -resolver(5), - -lwresd(8).
#include <lwres/lwbuffer.h>
void
-lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length);
void
-lwres_buffer_invalidate(lwres_buffer_t *b);
void
-lwres_buffer_add(lwres_buffer_t *b, unsigned int n);
void
-lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n);
void
-lwres_buffer_clear(lwres_buffer_t *b);
void
-lwres_buffer_first(lwres_buffer_t *b);
void
-lwres_buffer_forward(lwres_buffer_t *b, unsigned int n);
void
-lwres_buffer_back(lwres_buffer_t *b, unsigned int n);
lwres_uint8_t
-lwres_buffer_getuint8(lwres_buffer_t *b);
void
-lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val);
lwres_uint16_t
-lwres_buffer_getuint16(lwres_buffer_t *b);
void
-lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val);
lwres_uint32_t
-lwres_buffer_getuint32(lwres_buffer_t *b);
void
-lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val);
void
-lwres_buffer_putmem(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);
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.
+ + + +lwres_buffer + + ++ ++++Name
+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
+++Synopsis
++++#include <lwres/lwbuffer.h> +++
++ ++ +void +lwres_buffer_init(lwres_buffer_t * ++b, ++ ++ void * ++base, ++ ++ unsigned int ++length +);+
+ + +void +lwres_buffer_invalidate(lwres_buffer_t * ++b +);+
++ ++ +void +lwres_buffer_add(lwres_buffer_t * ++b, ++ ++ unsigned int ++n +);+
++ ++ +void +lwres_buffer_subtract(lwres_buffer_t * ++b, ++ ++ unsigned int ++n +);+
+ + +void +lwres_buffer_clear(lwres_buffer_t * ++b +);+
+ + +void +lwres_buffer_first(lwres_buffer_t * ++b +);+
++ ++ +void +lwres_buffer_forward(lwres_buffer_t * ++b, ++ ++ unsigned int ++n +);+
++ ++ +void +lwres_buffer_back(lwres_buffer_t * ++b, ++ ++ unsigned int ++n +);+
+ + +lwres_uint8_t +lwres_buffer_getuint8(lwres_buffer_t * ++b +);+
++ ++ +void +lwres_buffer_putuint8(lwres_buffer_t * ++b, ++ ++ lwres_uint8_t ++val +);+
+ + +lwres_uint16_t +lwres_buffer_getuint16(lwres_buffer_t * ++b +);+
++ ++ +void +lwres_buffer_putuint16(lwres_buffer_t * ++b, ++ ++ lwres_uint16_t ++val +);+
+ + +lwres_uint32_t +lwres_buffer_getuint32(lwres_buffer_t * ++b +);+
++ ++ +void +lwres_buffer_putuint32(lwres_buffer_t * ++b, ++ ++ lwres_uint32_t ++val +);+
++ ++ +void +lwres_buffer_putmem(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 +);++ b-c == optional active region. + +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. +
#include <lwres/lwres.h>
void
-lwres_conf_init(lwres_context_t *ctx);
void
-lwres_conf_clear(lwres_context_t *ctx);
lwres_result_t
-lwres_conf_parse(lwres_context_t *ctx, const char *filename);
lwres_result_t
-lwres_conf_print(lwres_context_t *ctx, FILE *fp);
lwres_conf_t *
-lwres_conf_get(lwres_context_t *ctx);
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.
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.
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); |
+
+void
+lwres_conf_clear( |
+lwres_context_t * | +
+ctx); |
+
+lwres_result_t
+lwres_conf_parse( |
+lwres_context_t * | ++ctx, | +
| + | const char * | +
+filename); |
+
+lwres_result_t
+lwres_conf_print( |
+lwres_context_t * | ++ctx, | +
| + | FILE * | +
+fp); |
+
+lwres_conf_t *
+lwres_conf_get( |
+lwres_context_t * | +
+ctx); |
+
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.
+
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.
+
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_result_t
+lwres_context_destroy( |
+lwres_context_t ** | +
+contextp); |
+
+void
+lwres_context_initserial( |
+lwres_context_t * | ++ctx, | +
| + | lwres_uint32_t | +
+serial); |
+
+lwres_uint32_t
+lwres_context_nextserial( |
+lwres_context_t * | +
+ctx); |
+
+void
+lwres_context_freemem( |
+lwres_context_t * | ++ctx, | +
| + | void * | ++mem, | +
| + | size_t | +
+len); |
+
+void
+lwres_context_allocmem( |
+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_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
+ malloc(3).
+ and
+ free(3).
-
+ 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.
+
+ Once memory for the structure has been allocated,
+ it is initialized using
+ lwres_conf_init(3)
+ and returned via *contextp.
+
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.
+
+ 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.
+
+ 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.
+
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_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.
+
lwres_conf_init(3), - -
#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_result_t
-lwres_context_destroy(lwres_context_t **contextp);
void
-lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial);
lwres_uint32_t
-lwres_context_nextserial(lwres_context_t *ctx);
void
-lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len);
void
-lwres_context_allocmem(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_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,
+ malloc(3),
-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
-.Xr malloc 3
-and
-free(3).
-
-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.
Once memory for the structure has been allocated,
-it is initialized using
-lwres_conf_init(3)
-
-and returned via
-*contextp.
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.
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.
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.
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_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.
#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_result_t
-lwres_gabnresponse_render(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_result_t
-lwres_gabnresponse_parse(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);
void
-lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);
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 - + + + +lwres_gabn + + ++ ++++Name
+lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free — lightweight resolver getaddrbyname message handling
+++Synopsis
+++#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_result_t +lwres_gabnresponse_render(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_result_t +lwres_gabnresponse_parse(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 +);+
++ ++ +void +lwres_gabnrequest_free(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. ++#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; @@ -175,245 +234,90 @@ typedef struct { lwres_addrlist_t addrs; void *base; 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. +} lwres_gabnresponse_t; + ++
+
lwres_gabnrequest_render()+ uses resolver contextctxto convert + getaddrbyname request structurereqto + canonical format. The packet header structure +pktis initialised and transferred to + bufferb. -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. + The contents of*reqare 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 contextctxto convert the contents + of packetpktto a + lwres_gabnrequest_t structure. Buffer +bprovides 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. +lwres_gabnresponse_parse()offers the same + semantics aslwres_gabnrequest_parse()+ except it yields a lwres_gabnresponse_t structure. +
lwres_gabnresponse_free()+ andlwres_gabnrequest_free()release the + memory in resolver contextctxthat 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.+ 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.++ +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. +
lwres_gai_strerror — print suitable error string
+#include <lwres/netdb.h>+
+char *
+gai_strerror(int ecode);
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.
+
+ address family for hostname not supported +
+ temporary failure in name resolution +
+ invalid value for
+ ai_flags
+
+ non-recoverable failure in name resolution +
ai_family not supported
+
+ memory allocation failure +
+ no address associated with hostname +
+ hostname or servname not provided, or not known +
+ servname not supported for ai_socktype
+
ai_socktype not supported
+
+ 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().
+
strerror(3), - + lwres_getaddrinfo(3), - -
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.
-
address family for hostname not supported
temporary failure in name resolution
invalid value for
-ai_flags
non-recoverable failure in name resolution
ai_family not supported
memory allocation failure
no address associated with hostname
hostname or servname not provided, or not known
servname not supported for ai_socktype
ai_socktype not supported
system error returned in errno
ecode
-is out of range.ai_flags,
-ai_family
-and
-ai_socktype
-are elements of the
-struct addrinfo
-used by
-lwres_getaddrinfo().
#include <lwres/netdb.h>
int
-lwres_getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);
void
-lwres_freeaddrinfo(struct addrinfo *ai);
If the operating system does not provide a -struct addrinfo, -the following structure is used: - -
struct addrinfo {
+
+
+
+lwres_getaddrinfo
+
+
+
+
+
+Name
+lwres_getaddrinfo, lwres_freeaddrinfo — socket address structure to host and service name
+
+
+Synopsis
+
+#include <lwres/netdb.h>
+
+
+
+int
+lwres_getaddrinfo(const char *
+
+hostname,
+
+
+
+const char *
+
+servname,
+
+
+
+const struct addrinfo *
+
+hints,
+
+
+
+struct addrinfo **
+
+res);
+
+
+
+
+void
+lwres_freeaddrinfo(struct addrinfo *
+
+ai);
+
+
+
+ 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 */
int ai_socktype; /* SOCK_xxx */
@@ -100,594 +82,240 @@ CLASS="PROGRAMLISTING"
char *ai_canonname; /* canonical name for hostname */
struct sockaddr *ai_addr; /* binary address */
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
+lwres_getaddrinfo()
+ is used to get a list of IP addresses and port numbers for host
+ hostname and service
+ servname.
-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.
+ 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.
-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.
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.
+
+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:
-
ai_familyThe 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_socktypedenotes 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_protocolindicates which transport protocol is wanted: IPPROTO_UDP or
-IPPROTO_TCP.
-If
-ai_protocol
-is zero the caller will accept any protocol.
ai_flagsFlag 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
-bind(2).
+
+
+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
+ bind(2).
-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
-connect(2)
-for a connection-oriented protocol or
-connect(2),
+ 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
+ connect(2)
+ for a connection-oriented protocol or
+ connect(2),
-sendto(2),
+ sendto(2),
-or
-sendmsg(2)
-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.
All other elements of the struct addrinfo passed
-via hints must be zero.
A hints of NULL is treated as if
-the caller provided a struct addrinfo initialized to zero
-with ai_familyset to
-PF_UNSPEC.
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
-socket(2).
-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_strerror(3)
-if an error occurs.
-If both
-hostname
-and
-servname
-are
-NULL
-lwres_getaddrinfo()
-returns
-EAI_NONAME.
SEE ALSO
lwres(3),
+ or
+ sendmsg(2)
+ 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.
+
+
+
+
+
+
+ All other elements of the struct addrinfo passed
+ via hints must be zero.
+
+
+ A hints of NULL is
+ treated as if
+ the caller provided a struct addrinfo initialized to zero
+ with ai_familyset to
+ PF_UNSPEC.
+
+
+ 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
+ socket(2).
+ 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_strerror(3)
+ if an error occurs. If both hostname and
+ servname are NULL
+ lwres_getaddrinfo() returns
+ EAI_NONAME.
+
+
+
+SEE ALSO
+lwres(3),
-lwres_getaddrinfo(3),
+ lwres_getaddrinfo(3),
-lwres_freeaddrinfo(3),
+ lwres_freeaddrinfo(3),
-lwres_gai_strerror(3),
+ lwres_gai_strerror(3),
-RFC2133,
+ RFC2133,
-getservbyname(3),
+ getservbyname(3),
-bind(2),
+ bind(2),
-connect(2),
+ connect(2),
-sendto(2),
+ sendto(2),
-sendmsg(2),
+ sendmsg(2),
-socket(2).
+ socket(2).
+
+
+#include <lwres/netdb.h>
struct hostent *
-lwres_gethostbyname(const char *name);
struct hostent *
-lwres_gethostbyname2(const char *name, int af);
struct hostent *
-lwres_gethostbyaddr(const char *addr, int len, int type);
struct hostent *
-lwres_gethostent(void);
void
-lwres_sethostent(int stayopen);
void
-lwres_endhostent(void);
struct hostent *
-lwres_gethostbyname_r(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);
struct hostent *
-lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error);
void
-lwres_sethostent_r(int stayopen);
void
-lwres_endhostent_r(void);
These functions provide hostname-to-address and -address-to-hostname lookups by means of the lightweight resolver. -They are similar to the standard -gethostent(3) -functions provided by most operating systems. -They use a -struct hostent -which is usually defined in -<namedb.h>. - -
struct hostent {
+
+
+
+lwres_gethostent
+
+
+
+
+
+Name
+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
+
+
+Synopsis
+
+#include <lwres/netdb.h>
+
+
+struct hostent *
+lwres_gethostbyname(const char *
+
+name);
+
+
+
+
+struct hostent *
+lwres_gethostbyname2(const char *
+
+name,
+
+
+
+int
+
+af);
+
+
+
+
+
+struct hostent *
+lwres_gethostbyaddr(const char *
+
+addr,
+
+
+
+int
+
+len,
+
+
+
+int
+
+type);
+
+
+
+struct hostent *
+lwres_gethostent(void);
+
+void
+lwres_sethostent(int stayopen);
+
+void
+lwres_endhostent(void);
+
+
+
+struct hostent *
+lwres_gethostbyname_r(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);
+
+
+
+
+
+struct hostent *
+lwres_gethostent_r(struct hostent *
+
+resbuf,
+
+
+
+char *
+
+buf,
+
+
+
+int
+
+buflen,
+
+
+
+int *
+
+error);
+
+
+
+void
+lwres_sethostent_r(int stayopen);
+
+void
+lwres_endhostent_r(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
+ gethostent(3)
+ 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 */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses from name server */
};
-#define h_addr h_addr_list[0] /* address, for backward compatibility */The members of this structure are:
-
h_nameThe official (canonical) name of the host.
h_aliasesA NULL-terminated array of alternate names (nicknames) for the host.
h_addrtypeThe type of address being returned —
-PF_INET
-or
-PF_INET6.
h_lengthThe length of the address in bytes.
h_addr_listA 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.
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.
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>:
+#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.
+
+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.
+
+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>:
-
HOST_NOT_FOUNDThe host or address was not found.
TRY_AGAINA recoverable error occurred, e.g., a timeout.
-Retrying the lookup may succeed.
NO_RECOVERYA non-recoverable error occurred.
NO_DATAThe 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_hstrerror(3)
-translates these error codes to suitable error messages.
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.
SEE ALSO
gethostent(3),
+
+
+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_hstrerror(3)
+ translates these error codes to suitable error messages.
+
+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.
+
+
+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.
+ lwres_hstrerror(3)
+
+
+
+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.
+
+
+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: -
struct hostent {
+
+
+
+lwres_getipnode
+
+
+
+
+
+Name
+lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent — lightweight resolver nodename / address translation API
+
+
+Synopsis
+
+#include <lwres/netdb.h>
+
+
+
+struct hostent *
+lwres_getipnodebyname(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);
+
+
+
+
+void
+lwres_freehostent(struct hostent *
+
+he);
+
+
+
+
+DESCRIPTION
+
+ 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:
+
+
+struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses from name server */
};
-#define h_addr h_addr_list[0] /* address, for backward compatibility */The members of this structure are:
-
h_nameThe official (canonical) name of the host.
h_aliasesA NULL-terminated array of alternate names (nicknames) for the host.
h_addrtypeThe type of address being returned - usually
-PF_INET
-or
-PF_INET6.
h_lengthThe length of the address in bytes.
h_addr_listA
-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
+#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.
-for the hostname
-name.
+
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
+ 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_V4MAPPEDThis is used with an
-af
-of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
-IPv6 addresses.
AI_ALLThis 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_ADDRCONFIGOnly 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_DEFAULTThis 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.
lwres_freehostent()
-releases all the memory associated with
-the
-struct hostent
-pointer
-he.
+
+
+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.
+
+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_hstrerror(3)
+ translates these error codes to suitable error messages.
+
+
+
+SEE ALSO
+RFC2553,
-Any memory allocated for the
-h_name,
+ lwres(3),
-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_FOUNDNo such host is known.
NO_ADDRESSThe 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_AGAINA temporary and possibly transient error occurred, such as a
-failure of a server to respond. The request may succeed if
-retried.
NO_RECOVERYAn unexpected failure occurred, and retrying the request
-is pointless.
lwres_hstrerror(3)
-translates these error codes to suitable error messages.
SEE ALSO
RFC2553,
+ lwres_gethostent(3),
-lwres(3),
+ lwres_getaddrinfo(3),
-lwres_gethostent(3),
+ lwres_getnameinfo(3),
-lwres_getaddrinfo(3),
-
-lwres_getnameinfo(3),
-
-lwres_hstrerror(3).
+ lwres_hstrerror(3).
+
+
+ This function is equivalent to the getnameinfo(3) 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 flags argument sets the following
-bits:
-
NI_NOFQDNA fully qualified domain name is not required for local hosts. -The local part of the fully qualified domain name is returned instead.
NI_NUMERICHOSTReturn the address in numeric form, as if calling inet_ntop(), -instead of a host name.
NI_NAMEREQDA 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_NUMERICSERVThe service name is returned as a digit string representing the port number.
NI_DGRAMSpecifies 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.
RFC2133, -getservbyport(3), -lwres(3), -lwres_getnameinfo(3), -lwres_getnamebyaddr(3). -lwres_net_ntop(3).
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); |
+
+ This function is equivalent to the
+ getnameinfo(3) 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 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. +
+
+lwres_getnameinfo()
+ returns 0 on success or a non-zero error code if an error occurs.
+
#include <lwres/netdb.h>
int
-lwres_getrrsetbyname(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);
void
-lwres_freerrset(struct rrsetinfo *rrset);
The following structures are used: -
struct rdatainfo {
+
+
+
+lwres_getrrsetbyname
+
+
+
+
+
+Name
+lwres_getrrsetbyname, lwres_freerrset — retrieve DNS records
+
+
+Synopsis
+
+#include <lwres/netdb.h>
+
+
+
+int
+lwres_getrrsetbyname(const char *
+
+hostname,
+
+
+
+unsigned int
+
+rdclass,
+
+
+
+unsigned int
+
+rdtype,
+
+
+
+unsigned int
+
+flags,
+
+
+
+struct rrsetinfo **
+
+res);
+
+
+
+
+void
+lwres_freerrset(struct rrsetinfo *
+
+rrset);
+
+
+
+ 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 */
@@ -100,261 +95,97 @@ struct rrsetinfo {
char *rri_name; /* canonical name */
struct rdatainfo *rri_rdatas; /* individual records */
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:
+
+
+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
+
ERRSET_INVAL
+ a parameter is invalid
+
ERRSET_FAIL
+ other failure
+
+
-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.
-
-Memory allocated for the dynamically allocated structures created by
-a successful call to
-lwres_getrrsetbyname()
-is released by
-lwres_freerrset().
-
-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:
-
ERRSET_NONAMEthe name does not exist
ERRSET_NODATAthe name exists, but does not have data of the desired type
ERRSET_NOMEMORYmemory could not be allocated
ERRSET_INVALa parameter is invalid
ERRSET_FAILother failure
+
+
+
+#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_result_t
-lwres_gnbaresponse_render(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_result_t
-lwres_gnbaresponse_parse(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);
void
-lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
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 - + + + +lwres_gnba + + ++ ++++Name
+lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free — lightweight resolver getnamebyaddress message handling
+++Synopsis
++++#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_result_t +lwres_gnbaresponse_render +(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_result_t +lwres_gnbaresponse_parse(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 +);+
++ ++ +void +lwres_gnbarequest_free(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. ++#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; @@ -168,242 +230,86 @@ typedef struct { lwres_uint16_t *aliaslen; void *base; 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.+} lwres_gnbaresponse_t; + +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.+
++
lwres_gnbarequest_render()+ uses resolver contextctxto convert + getnamebyaddr request structurereqto + canonical format. The packet header structure +pktis 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 contextctxto convert the contents of + packetpktto a + lwres_gnbarequest_t structure. Buffer +bprovides 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 aslwres_gnbarequest_parse()+ except it yields a lwres_gnbaresponse_t structure. ++
lwres_gnbaresponse_free()+ andlwres_gnbarequest_free()release the + memory in resolver contextctxthat 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. +
lwres_herror, lwres_hstrerror — lightweight resolver error message generation
+#include <lwres/netdb.h>+
+void
+lwres_herror(const char *s);
+const char *
+lwres_hstrerror(int err);
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:
-
+
Resolver Error 0 (no error) +
Unknown host +
Host name lookup failure +
Unknown server error +
No address associated with name +
+
+
+ The string Unknown resolver error is returned by
+ lwres_hstrerror()
+ when the value of
+ lwres_h_errno
+ is not a valid error code.
+
herror(3), - -
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:
-
-
Resolver Error 0 (no error)
Unknown host
Host name lookup failure
Unknown server error
No address associated with name
The string Unknown resolver error is returned by
-lwres_hstrerror()
-when the value of
-lwres_h_errno
-is not a valid error code.
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.
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.
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); |
+
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.
+
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_result_t
+lwres_noopresponse_render( |
+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_result_t
+lwres_noopresponse_parse( |
+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); |
+
+void
+lwres_nooprequest_free( |
+lwres_context_t * | ++ctx, | +
| + | lwres_nooprequest_t ** | +
+structp); |
+
+ 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.
-
-
-
-
#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_result_t
-lwres_noopresponse_render(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_result_t
-lwres_noopresponse_parse(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);
void
-lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp);
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. -
#define LWRES_OPCODE_NOOP 0x00000000U - + 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.
lwres_nooprequest_render()uses resolver -contextctxto convert no-op request structure -reqto canonical format. The packet header -structurepktis initialised and transferred to -bufferb. The contents of -*reqare 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 -ctxto convert the contents of packet -pktto a lwres_nooprequest_t -structure. Bufferbprovides 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 aslwres_nooprequest_parse()except it -yields a lwres_noopresponse_t structure.
lwres_noopresponse_free()and -lwres_nooprequest_free()release the memory in -resolver contextctxthat was allocated to the -lwres_noopresponse_t or lwres_nooprequest_t -structures referenced viastructp.
The no-op opcode functions
-lwres_nooprequest_render(),
+} 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. +
+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_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.
+
+ 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.
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.
+
+These functions rely on a -struct lwres_lwpacket -which is defined in -lwres/lwpacket.h. - -
typedef struct lwres_lwpacket lwres_lwpacket_t; - + + + +lwres_packet + + ++ ++ +++Name
+lwres_lwpacket_renderheader, lwres_lwpacket_parseheader — lightweight resolver packet handling functions
+++Synopsis
+++#include <lwres/lwpacket.h>++
++ ++ +lwres_result_t +lwres_lwpacket_renderheader(lwres_buffer_t * ++b, ++ ++ lwres_lwpacket_t * ++pkt +);+
++ ++ +lwres_result_t +lwres_lwpacket_parseheader(lwres_buffer_t * ++b, ++ ++ lwres_lwpacket_t * ++pkt +);++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; @@ -115,248 +88,147 @@ struct lwres_lwpacket { lwres_uint32_t recvlength; lwres_uint16_t authtype; lwres_uint16_t authlength; -};The elements of this structure are: -
lengththe overall packet length, including the entire packet header. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls.
versionthe 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.
pktflagslibrary-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.
serialis 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.
opcodeindicates 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.
resultis 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.
recvlengthis 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.
authtypedefines 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.
authlengives the length of the authentication data. -Since packet authentication is currently not used, this must be zero.
The following opcodes are currently defined: -
NOOPSuccess is always returned and the packet contents are echoed. -The lwres_noop_*() functions should be used for this type.
GETADDRSBYNAMEreturns all known addresses for a given name. -The lwres_gabn_*() functions should be used for this type.
GETNAMEBYADDRreturn 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*pktin 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*bto resolver packet -*pkt. The contents of the buffer -bshould correspond to a -lwres_lwpacket_t.+ This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + +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*band -lightweight resolver packet*pktboth functions -return LWRES_R_UNEXPECTEDEND.+ 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*pktin + 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*bto resolver + packet*pkt. The contents of the buffer +bshould correspond to a + lwres_lwpacket_t. +
#include <lwres/lwres.h>
lwres_result_t
-lwres_string_parse(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_result_t
-lwres_getaddrsbyname(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_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_getaddrsbyname()
-and
-lwres_getnamebyaddr()
-use the
-lwres_gnbaresponse_t
-structure defined below:
-
typedef struct {
+
+
+
+lwres_resutil
+
+
+
+
+
+Name
+lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr — lightweight resolver utility functions
+
+
+Synopsis
+
+#include <lwres/lwres.h>
+
+
+
+lwres_result_t
+lwres_string_parse(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_result_t
+lwres_getaddrsbyname(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);
+
+
+
+
+
+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_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:
+
+
+typedef struct {
lwres_uint32_t flags;
lwres_uint16_t naliases;
lwres_uint16_t naddrs;
@@ -191,197 +174,84 @@ CLASS="PROGRAMLISTING"
lwres_addrlist_t addrs;
void *base;
size_t baselen;
-} lwres_gabnresponse_t;
-The contents of this structure are not manipulated directly but
-they are controlled through the
-lwres_gabn(3)
-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.
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.
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().
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_buffer(3),
+} lwres_gabnresponse_t;
+
+
+ The contents of this structure are not manipulated directly but
+ they are controlled through the
+ lwres_gabn(3)
+ 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.
+
+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.
+
+
+
+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().
+
+
+ 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.
+
+
+
+ lwres_gabn(3).
+
+
+