diff options
| author | peter <peter@FreeBSD.org> | 1999-11-30 02:43:11 +0000 |
|---|---|---|
| committer | peter <peter@FreeBSD.org> | 1999-11-30 02:43:11 +0000 |
| commit | 4ef23ce6957fc75fc005885496d605fed48213e1 (patch) | |
| tree | 7828b08c74ef918938b1b853c98f0cb41edac52c /contrib/bind/doc | |
| parent | 67e0f3ce71726dc4058c2f80a813341a59244dbd (diff) | |
| download | FreeBSD-src-4ef23ce6957fc75fc005885496d605fed48213e1.zip FreeBSD-src-4ef23ce6957fc75fc005885496d605fed48213e1.tar.gz | |
Import bind v8.2.2.p5, minus the crypto for the time being. The bind
package does have BXA export approval, but the licensing strings on the
dnssafe code are a bit unpleasant. The crypto is easy to restore and bind
will run without it - just without full dnssec support.
Obtained from: The Internet Software Consortium (www.isc.org)
Diffstat (limited to 'contrib/bind/doc')
41 files changed, 6202 insertions, 477 deletions
diff --git a/contrib/bind/doc/bog/00title.me b/contrib/bind/doc/bog/00title.me index be95d8b..5048969 100644 --- a/contrib/bind/doc/bog/00title.me +++ b/contrib/bind/doc/bog/00title.me @@ -1,5 +1,3 @@ -.\" ++Copyright++ 1986, 1988 -.\" - .\" Copyright (c) 1986, 1988 .\" The Regents of the University of California. All rights reserved. .\" @@ -30,7 +28,7 @@ .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. -.\" - +.\" .\" Portions Copyright (c) 1993 by Digital Equipment Corporation. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -48,9 +46,6 @@ .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS .\" SOFTWARE. -.\" - -.\" --Copyright-- -.\" .+c .(l C .sz 14 diff --git a/contrib/bind/doc/bog/ack.me b/contrib/bind/doc/bog/ack.me index 5c02c14..c9d7d85 100644 --- a/contrib/bind/doc/bog/ack.me +++ b/contrib/bind/doc/bog/ack.me @@ -1,5 +1,3 @@ -.\" ++Copyright++ 1986, 1988 -.\" - .\" Copyright (c) 1986, 1988 .\" The Regents of the University of California. All rights reserved. .\" @@ -30,7 +28,7 @@ .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. -.\" - +.\" .\" Portions Copyright (c) 1993 by Digital Equipment Corporation. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -48,8 +46,6 @@ .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS .\" SOFTWARE. -.\" - -.\" --Copyright-- .\" .\" @(#)ack.me .\" diff --git a/contrib/bind/doc/html/acl.html b/contrib/bind/doc/html/acl.html index cf684b4..57cf869 100644 --- a/contrib/bind/doc/html/acl.html +++ b/contrib/bind/doc/html/acl.html @@ -52,12 +52,12 @@ Allows any host on a network for which the system has an interface. <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: acl.html,v 1.4 1998/03/21 01:03:10 halley Exp $ +Last Updated: $Id: acl.html,v 1.5 1999/09/15 20:28:00 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/address_list.html b/contrib/bind/doc/html/address_list.html index 894ef04..ec39138 100644 --- a/contrib/bind/doc/html/address_list.html +++ b/contrib/bind/doc/html/address_list.html @@ -14,14 +14,18 @@ <PRE> <VAR>address_match_list</VAR> = 1*<VAR>address_match_element</VAR> -<VAR>address_match_element</VAR> = [ "!" ] (<VAR><A HREF="docdef.html">ip_address</A></VAR> / <VAR><A HREF="docdef.html">ip_prefix</A></VAR> / <VAR><A HREF="acl.html">acl_name</A></VAR> / <VAR>address_match_list</VAR>) ";" +<VAR>address_match_element</VAR> = [ "!" ] (<VAR><A HREF="docdef.html">address_match_list</A></VAR> / <VAR><A HREF="docdef.html">ip_address</A></VAR> / <VAR><A HREF="docdef.html">ip_prefix</A></VAR> / <VAR><A HREF="acl.html">acl_name</A></VAR> / <VAR><A HREF="docdef.html">"key" key_id</A></VAR>) ";" </PRE> <HR> <A NAME="Usage"><H3>Definition and Usage</H3></A> -<P>Address match lists are lists of elements. The elements can be any +<P>Address match lists are primarily used to determine access control for +various server operations. They are also used to define priorities +for querying other nameservers and to set the addresses on which +<CODE>named</CODE> will listen for queries. +The elements which constitute an address match list can be any of the following:</P> <UL> @@ -29,34 +33,43 @@ of the following:</P> <LI>an IP prefix (in the '/'-notation),</LI> +<LI>a key ID, as defined by the +<A HREF="key.html"><CODE>key</CODE></A> statement, or + <LI>the name of an address match list previously defined with -the <A HREF="acl.html"><CODE>acl</CODE></A> statment.</LI> +the <A HREF="acl.html"><CODE>acl</CODE></A> statment, or</LI> -<LI>an IP address match list</LI> +<LI>another <VAR>address_match_list</VAR></LI> </UL> -<P>The ACLs "any", "none", "localhost" and "localnets" are -predefined. More information can be found in the description of the -<A HREF="acl.html"><CODE>acl</CODE></A> statement. +<P>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 <A HREF="acl.html"><CODE>acl</CODE></A> statement. -<P>Elements can be negated with a leading "!". +<P>The addition of the <CODE>key</CODE> +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.</P> <P>When a given IP address or prefix is compared to an address match -list, the list is traversed in order and the first match (regardless -of negation) is used. The interpretation of a match depends on -whether the list is being used for access control or as a -topology.</P> +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 <CODE>listen-on</CODE> ports, or as a +topology, and whether the element was negated.</P> <P>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 <CODE>allow-query</CODE>, -<CODE>allow-transfer</CODE> and <CODE>allow-update</CODE> all use -address match lists like this. Similarly, the <CODE>listen-on</CODE> -clause can use negation to define local addresses which should not be -used to accept nameserver connections.</P> +<CODE>allow-transfer</CODE>, <CODE>allow-update</CODE> and +<CODE>blackhole</CODE> all use address match lists like this. +Similarly, the <CODE>listen-on</CODE> +option will cause the server to not accept queries on any of the +machine's addresses which do not match the list. <P>When used with the <CODE>topology</CODE> clause, a non-negated -match returns a distance based on its postion on the list (the closer +match returns a distance based on its position on the list (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 @@ -76,12 +89,12 @@ fall through. <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: address_list.html,v 1.5 1998/03/21 01:03:10 halley Exp $ +Last Updated: $Id: address_list.html,v 1.8 1999/09/15 20:28:00 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/comments.html b/contrib/bind/doc/html/comments.html index 8ada6b0..a064c1c 100644 --- a/contrib/bind/doc/html/comments.html +++ b/contrib/bind/doc/html/comments.html @@ -73,12 +73,12 @@ statement.</P> <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: comments.html,v 1.4 1998/03/21 01:03:11 halley Exp $ +Last Updated: $Id: comments.html,v 1.5 1999/09/15 20:28:00 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/config.html b/contrib/bind/doc/html/config.html index dd8e0b4..97f3a1b 100644 --- a/contrib/bind/doc/html/config.html +++ b/contrib/bind/doc/html/config.html @@ -47,13 +47,22 @@ specifies what the server logs, and where the log messages are sent <DT><CODE><A HREF="options.html">options</A></CODE> <DD> -controls global server configuation options and sets defaults for other +controls global server configuration options and sets defaults for other statements +<DT><CODE><A HREF="controls.html">controls</A></CODE> +<DD> +declares control channels to be used by the <VAR>ndc</VAR> utility + <DT><CODE><A HREF="server.html">server</A></CODE> <DD> sets certain configuration options on a per-server basis +<DT><CODE><A HREF="trusted-keys.html">trusted-keys</A></CODE> +<DD> +defines DNSSEC keys that are preconfigured into the server and implicitly +trusted + <DT><CODE><A HREF="zone.html">zone</A></CODE> <DD> defines a zone @@ -62,22 +71,27 @@ defines a zone <P>The <CODE>logging</CODE> and <CODE>options</CODE> statements may only occur once per configuration. -<H4><A HREF="comments.html">Comments</A></H4> +<H4>Comments</H4> + +The BIND 8 <A HREF="comments.html">comment syntax</A> allows for +comments to appear anywhere that whitespace may appear in a BIND +configuration file. To appeal to programmers of all kinds, they can +be written in C, C++, or shell/perl constructs. <H3>Converting from BIND 4.9.x</H3> -<P>BIND 4.9.x configuration files can be converted to the new format -by using <CODE>src/bin/named/named-bootconf.pl</CODE>, a perl script that -is part of the BIND 8.1 source kit. +<p>BIND 4.9.x configuration files can be converted to the new format by +using <code>src/bin/named/named-bootconf</code>, a shell script that is part of +the BIND 8.2.x source kits. <HR> -<CENTER><P>[ <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +<CENTER><P>[ <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: config.html,v 1.4 1998/03/21 01:03:11 halley Exp $ +Last Updated: $Id: config.html,v 1.10 1999/09/15 20:28:01 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/controls.html b/contrib/bind/doc/html/controls.html new file mode 100644 index 0000000..9261926 --- /dev/null +++ b/contrib/bind/doc/html/controls.html @@ -0,0 +1,70 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> + <TITLE>BIND controls Statement</TITLE> +</HEAD> + +<BODY> +<H2>BIND Configuration File Guide--<CODE>controls</CODE> Statement</H2> + +<HR> + +<A NAME="Syntax"><H3>Syntax</H3></A> + +<PRE> +controls { + [ inet <VAR><A HREF="docdef.html">ip_addr</A></VAR> + port <VAR><A HREF="docdef.html">ip_port</A></VAR> + allow { <VAR><A HREF="address_list.html">address_match_list</A></VAR>; }; ] + [ unix <VAR><A HREF="docdef.html">path_name</A></VAR> + perm <VAR><A HREF="docdef.html">number</A></VAR> + owner <VAR><A HREF="docdef.html">number</A></VAR> + group <VAR><A HREF="docdef.html">number</A></VAR>; ] +}; +</PRE> + +<HR> + +<A NAME="Usage"><H3>Definition and Usage</H3></A> + +<P>The <CODE>controls</CODE> statement declares control channels +to be used by system +administrators to affect the operation of the local name server. These +control channels are used by the <CODE>ndc</CODE> utility to send commands +to and retrieve non-DNS results from a name server.</P> + +<P>A <CODE>unix</CODE> control channel is a FIFO in the file system, +and access to it is +controlled by normal file system permissions. +It is created by <CODE>named</CODE> with the specified file mode bits (see +the <CODE>chmod</CODE>(1) manual page), user and group owner. +Note that, unlike <CODE>chmod</CODE>, the mode bits specified for +<CODE>perm</CODE> will normally have a leading 0 so the number +is interpreted as octal. Also note that the user and group +ownership specified as <CODE>owner</CODE> and <CODE>group</CODE> +must be given as numbers, not names. +It is recommended that the +permissions be restricted to administrative personnel only, or else any +user on the system might be able to manage the local name server.</P> + +<P>An <CODE>inet</CODE> control channel is a TCP/IP socket accessible +to the Internet, created at the specified <VAR>ip_port</VAR> on the +specified <VAR>ip_addr</VAR>. +Modern <VAR>telnet</VAR> clients are capable of speaking directly to these +sockets, and the control protocol is ARPAnet-style text. It is recommended +that 127.0.0.1 be the only <VAR>ip_addr</VAR> used, and this only if you +trust all non-privileged users on the local host to manage your name +server.</P> + +<HR> + +<CENTER><P>[ <A HREF="config.html">BIND Config. File</A> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> + +<HR> +<ADDRESS> +Last Updated: $Id: controls.html,v 1.4 1999/09/15 20:28:01 cyarnell Exp $ +</ADDRESS> +</BODY> +</HTML> diff --git a/contrib/bind/doc/html/docdef.html b/contrib/bind/doc/html/docdef.html index da0c9d5..0885c1f 100644 --- a/contrib/bind/doc/html/docdef.html +++ b/contrib/bind/doc/html/docdef.html @@ -23,8 +23,8 @@ as defined by the <A HREF="acl.html">acl</A> statement. <DT><VAR>address_match_list</VAR> <DD> -A list of one or more <VAR>ip_address</VAR>, <VAR>ip_prefix</VAR> or -<VAR>acl_name</VAR> elements, as described in the +A list of one or more <VAR>ip_address</VAR>, <VAR>ip_prefix</VAR> +<VAR>key_id</VAR> or <VAR>acl_name</VAR> elements, as described in the <A HREF="address_list.html">Address Match Lists</A> section. <DT><VAR>dotted-decimal</VAR> @@ -52,7 +52,8 @@ An IP address in with exactly four elements in <DD> An IP port <VAR>number</VAR>. <VAR>number</VAR> is limited to 0 through 65535, with values below 1024 typically restricted to -root-owned processes. +root-owned processes. In some cases an asterisk (``*'') character +can be used as a placeholder to select a random high-numbered port. <DT><VAR>ip_prefix</VAR> <DD> @@ -62,6 +63,11 @@ the network <CODE>127.0.0.0</CODE> with netmask <CODE>255.0.0.0</CODE>. <CODE>1.2.3.0/24</CODE> is network <CODE>1.2.3.0</CODE> with netmask <CODE>255.255.255.0</CODE>. +<DT><VAR>key_id</VAR> +<DD> +A string representing the name of a shared key, to be used for transaction +security. + <DT><VAR>number</VAR> <DD> A non-negative integer with an entire range limited by the range of a @@ -101,12 +107,12 @@ numbers <CODE>1</CODE> and <CODE>0</CODE>. <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: docdef.html,v 1.4 1998/03/21 01:03:12 halley Exp $ +Last Updated: $Id: docdef.html,v 1.8 1999/09/15 20:28:01 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/example.html b/contrib/bind/doc/html/example.html index 729b980..a147828 100644 --- a/contrib/bind/doc/html/example.html +++ b/contrib/bind/doc/html/example.html @@ -15,13 +15,18 @@ * A simple BIND 8 configuration */ +logging { + category lame-servers { null; }; + category cname { null; }; +}; + options { directory "/var/named"; }; -logging { - category lame-servers { null; }; - category cname { null; }; +controls { + inet * port 52 allow { localnets; }; // a BAD idea + unix "/var/run/ndc" perm 0600 owner 0 group 0; // the default }; zone "isc.org" in { @@ -42,18 +47,19 @@ zone "." in { zone "0.0.127.in-addr.arpa" in { type master; + notify no; file "master/127.0.0"; }; </PRE> <HR> -<CENTER><P>[ <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +<CENTER><P>[ <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: example.html,v 1.1 1997/05/06 22:11:31 vixie Exp $ +Last Updated: $Id: example.html,v 1.5 1999/09/15 20:28:01 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/include.html b/contrib/bind/doc/html/include.html index 4184210..421d97b 100644 --- a/contrib/bind/doc/html/include.html +++ b/contrib/bind/doc/html/include.html @@ -11,7 +11,9 @@ <A NAME="Syntax"><H3>Syntax</H3></A> -<P><CODE>include <VAR><A HREF="docdef.html">path_name</A></VAR>;</CODE></P> +<PRE> +include <VAR><A HREF="docdef.html">path_name</A></VAR>; +</PRE> <HR> @@ -20,16 +22,18 @@ <P>The <CODE>include</CODE> statement inserts the specified file at the point that the <CODE>include</CODE> statement is encountered. It cannot be used within another statement, though, so a line such as -<CODE>acl internal_hosts { "include internal_hosts.acl" }</CODE> is -not allowed.</P> +<PRE> +acl internal_hosts { include "internal_hosts.acl"; }; +</PRE> +is not allowed.</P> <P>Use <CODE>include</CODE> to break the configuration up into -easily-managed chunks. For example:</P> +easily-managed chunks. For example: -<UL COMPACT> -<LI><CODE>include "/etc/security/keys.bind";</CODE></LI> -<LI><CODE>include "/etc/acls.bind";</CODE></LI> -</UL> +<PRE> +include "/etc/security/keys.bind"; +include "/etc/acls.bind"; +</PRE> <P>could be used at the top of a BIND configuration file in order to include any ACL or key information.</P> @@ -42,12 +46,12 @@ comment.</P> <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: include.html,v 1.5 1998/03/21 01:03:12 halley Exp $ +Last Updated: $Id: include.html,v 1.7 1999/09/15 20:28:01 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/index.html b/contrib/bind/doc/html/index.html index ca8c73c..f19464b 100644 --- a/contrib/bind/doc/html/index.html +++ b/contrib/bind/doc/html/index.html @@ -26,6 +26,8 @@ updates that may be specified on a zone-by-zone basis</LI> <H3><A HREF="config.html">Configuration File Guide</A></H3> +<H3><A HREF="master.html">Master File Format</A></H3> + <H3>Kits</H3> <UL> <LI><A HREF="ftp://ftp.isc.org/isc/bind/src/cur"> @@ -56,7 +58,7 @@ and generally kind hearted folk such as yourself. <HR> <ADDRESS> -Last Updated: $Id: index.html,v 1.4 1998/03/21 01:03:12 halley Exp $ +Last Updated: $Id: index.html,v 1.5 1998/11/24 01:44:43 marka Exp $ </ADDRESS> </BODY> diff --git a/contrib/bind/doc/html/key.html b/contrib/bind/doc/html/key.html index bac6a96..bf2e3d1 100644 --- a/contrib/bind/doc/html/key.html +++ b/contrib/bind/doc/html/key.html @@ -23,28 +23,35 @@ key <VAR>key_id</VAR> { <A NAME="Usage"><H3>Definition and Usage</H3></A> <P>The <CODE>key</CODE> statement defines a key ID which can be used -in a <A HREF="server.html"><CODE>server</CODE> statement</A> to +in a <A HREF="server.html"><CODE>server</CODE></A> statement to associate an authentication method with a particular name server. <P>A key ID must be created with the <CODE>key</CODE> statement before it can be used in a <CODE>server</CODE> -definition.</P> +definition or an address match list.</P> <P>The <VAR>algorithm_id</VAR> is a string that specifies a -security/authentication algorithm. -<VAR>secret_string</VAR> is the secret to be used by the algorithm. - -<P>The <CODE>key</CODE> statement is intended for future use by the -server. It is checked for syntax but is otherwise ignored. +security/authentication algorithm. The only supported +algorithm is "hmac-md5". + +<P><VAR>secret_string</VAR> is the secret to be used by the algorithm, +and is treated as a base-64 encoded string. This may be generated +using dnskeygen or another utility or created manually. + +<P>The <CODE>key</CODE> statement is intended for use in transaction +security. Unless included in a <A HREF="server.html"><CODE>server</CODE></A> +statement, it is not used to sign any requests. It is used to verify +requests matching the <VAR>key_id</VAR> and <VAR>algorithm_id</VAR>, +and sign replies to those requests. <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: key.html,v 1.5 1998/03/21 01:03:13 halley Exp $ +Last Updated: $Id: key.html,v 1.10 1999/09/15 20:28:02 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/logging.html b/contrib/bind/doc/html/logging.html index 4d00219..10e2168 100644 --- a/contrib/bind/doc/html/logging.html +++ b/contrib/bind/doc/html/logging.html @@ -60,6 +60,15 @@ the logging configuration will be:</P> }; </PRE> +The logging configuration is established as soon as the +<CODE>logging</CODE> statement is parsed. If you want to redirect +messages about processing of the entire configuration file, the +<CODE>logging</CODE>statement must appear first. Even if you do not +redirect configuration file parsing messages, we recommend +always putting the <CODE>logging</CODE> statement first so that this +rule need not be consciously recalled if you ever do need want the +parser's messages relocated. + <H4>The <CODE>channel</CODE> phrase</H4> <P>All log output goes to one or more "channels"; you can make as many @@ -82,26 +91,37 @@ large the file is allowed to become, and how many versions of the file will be saved each time the file is opened. <P>The <CODE>size</CODE> option for files is simply a hard ceiling on -log growth. If the file ever exceeds the size, then +log growth. If the file ever exceeds the size, <CODE>named</CODE> will just not write anything more to it until the file is reopened; exceeding the size does not automatically trigger a reopen. The default behavior is to not limit the size of the file.</P> -<P>If you use the <CODE>version</CODE> logfile option, then +<P>If you use the <CODE>version</CODE> logfile option, <CODE>named</CODE> 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 lames.log.2, lamers.log.0 is renamed to lamers.log.1, and lamers.log is renamed to lamers.log.0. No rolled -versions are kept by default. The <CODE>unlimited</CODE> keyword is -synonymous with <CODE>99</CODE> in current BIND releases.</P> +versions are kept by default; any existing log file is simply +appended. The <CODE>unlimited</CODE> keyword is synonymous with +<CODE>99</CODE> in current BIND releases.</P> + +<P>Example usage of the size and versions options: + +<PRE> + channel an_example_level { + file "lamers.log" versions 3 size 20m; + print-time yes; + print-category yes; + }; +</PRE> <P>The argument for the <CODE>syslog</CODE> clause is a syslog facility as described in the <CODE>syslog</CODE> manual page. How <CODE>syslogd</CODE> will handle messages sent to this facility is described in the <CODE>syslog.conf</CODE> manual page. If you have a system which uses a very old version of <CODE>syslog</CODE> that only -uses two arguments to the <CODE>openlog()</CODE> function, then this +uses two arguments to the <CODE>openlog()</CODE> function, this clause is silently ignored.</P> <P>The <CODE>severity</CODE> clause works like <CODE>syslog</CODE>'s @@ -111,7 +131,7 @@ 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.</P> -<P>If you are using <CODE>syslog</CODE>, then the +<P>If you are using <CODE>syslog</CODE>, the <CODE>syslog.conf</CODE> priorities will also determine what eventually passes through. For example, defining a channel facility and severity as <CODE>daemon</CODE> and <CODE>debug</CODE> but only @@ -119,18 +139,19 @@ logging <CODE>daemon.warning</CODE> via <CODE>syslog.conf</CODE> will cause messages of severity <CODE>info</CODE> and <CODE>notice</CODE> to be dropped. If the situation were reversed, with <CODE>named</CODE> writing messages of only <CODE>warning</CODE> or -higher, then <CODE>syslogd</CODE> would print all messages it received +higher, <CODE>syslogd</CODE> would print all messages it received from the channel.</P> <P>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 server with the "-d" flag followed by a -positive integer, or by sending the server the SIGUSR1 signal (for -example, by using "ndc trace"). The global debug level can be set to -zero, and debugging mode turned off, by sending the server the SIGUSR2 -signal ("ndc notrace". All debugging messages in the server have a -debug level, and higher debug levels give more more detailed output. +zero, debugging mode will be active. The global debug level is +set either by starting the <CODE>named</CODE> server with the "-d" +flag followed by a positive integer, or by sending the running server the +SIGUSR1 signal (for example, by using "ndc trace"). The global debug +level can be set to zero, and debugging mode turned off, by sending +the server the SIGUSR2 signal ("ndc notrace"). All debugging messages +in the server have a debug level, and higher debug levels give more +more detailed output. Channels that specify a specific debug severity, e.g. <PRE> @@ -145,12 +166,12 @@ server is in debugging mode, regardless of the global debugging level. Channels with <code>dynamic</code> severity use the server's global level to determine what messages to print. -<P>If <CODE>print-time</CODE> has been turned on, then the date and +<P>If <CODE>print-time</CODE> has been turned on, the date and time will be logged. <CODE>print-time</CODE> may be specified for a syslog channel, but is usually pointless since syslog also prints the date and time. If <CODE>print-category</CODE> is requested, then the category of the message will be logged as well. Finally, if -<CODE>print-severity</CODE> is on, then the severity level of the +<CODE>print-severity</CODE> is on, the severity level of the message will be logged. The <CODE>print-</CODE> 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 @@ -197,7 +218,7 @@ logging by pointing categories at channels you have defined.</P> <P>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 +a list of channels for a category, log messages in that category will be sent to the <CODE>default</CODE> category instead. If you don't specify a default category, the following "default default" is used: @@ -337,12 +358,12 @@ Messages arising from response checking, such as <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: logging.html,v 1.7 1998/04/23 19:58:35 halley Exp $ +Last Updated: $Id: logging.html,v 1.12 1999/09/30 17:58:35 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/master.html b/contrib/bind/doc/html/master.html new file mode 100644 index 0000000..ff4ba0a --- /dev/null +++ b/contrib/bind/doc/html/master.html @@ -0,0 +1,166 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> + <TITLE>Master File Format</TITLE> +</HEAD> + +<BODY> +<H2>BIND Configuration Guide -- Master File Format</H2> + +<HR> + +<P> +The Master File Format was initially defined in +<A HREF=http://ds.internic.net/rfc/rfc1035.txt>RFC 1035</A> +and has subsequently been extended. +<P> +While the Master File Format is class independent all records in a +Master File must be of the same class. + +<H3>Master File Directives</H3> +<H4>$ORIGIN</H4> +Syntax: <CODE>$ORIGIN <domain-name> [<comment>]</CODE> +<P> +<CODE>$ORIGIN</CODE> set the domain name that will be appended to any +unqualified records. +When a zone is first read in there is an implict <CODE>$ORIGIN</CODE> +<zone-name>. +The current <CODE>$ORIGIN</CODE> is appended to the domain specified in the +<CODE>$ORIGIN</CODE> argument if it is not absolute. + +<PRE> +$ORIGIN EXAMPLE. +$ORIGIN MYZONE +WWW CNAME MAIN-SERVER +</PRE> +is equivlent to +<PRE> +WWW.MYZONE.EXAMPLE. CNAME MAIN-SERVER.MYZONE.EXAMPLE. +</PRE> + +<H4>$INCLUDE</H4> +Syntax: <CODE>$INCLUDE <filename> [<origin>] [<comment>]</CODE> +<P> +Read and process the file filename as if it was included into the file at this +point. If origin is specified the file is processed with <CODE>$ORIGIN</CODE> +set to that value otherwise the current <CODE>$ORIGIN</CODE> is used. +<I>NOTE: The behaviour when <origin> is specified differs from that +described in +<A HREF=http://ds.internic.net/rfc/rfc1035.txt>RFC 1035</A>.</I> +<P> +The origin and current domain revert to the values they were prior to the +<CODE>$INCLUDE</CODE> once the file has been read. +<H4>$TTL</H4> +Syntax: <CODE>$TTL <default-ttl> [<comment>]</CODE> +<P> +Set the default Time To Live (TTL) for subsequent records with undefined +TTL's. Valid TTL's are of the range 0-2147483647. +<P> +<CODE>$TTL</CODE> is defined in +<A HREF=http://ds.internic.net/rfc/rfc2308.txt>RFC 2308</A>. +<H3>BIND Master File Extentions</H3> +<H4>$GENERATE</H4> +Syntax: <CODE>$GENERATE <range> <lhs> <type> <rhs> +[<comment>]</CODE> +<P> +<CODE>$GENERATE</CODE> is used to create a series of resource records +that only differ from each other by an iterator. <CODE>$GENERATE</CODE> +can be used to easily generate the sets of records required to support +sub /24 reverse delegations described in +<A HREF=http://ds.internic.net/rfc/rfc2317.txt>RFC 2317: Classless IN-ADDR.ARPA delegation</A>. + +<PRE> +$ORIGIN 0.0.192.IN-ADDR.ARPA. +$GENERATE 1-2 0 NS SERVER$.EXAMPLE. +$GENERATE 1-127 $ CNAME $.0 +</PRE> +is equivalent to +<PRE> +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. +</PRE> +<DL> +<DT>range</DT> +<DD> +This can be one of two forms: +<I>start</I>-<I>stop</I> +or +<I>start</I>-<I>stop</I>/<I>step</I>. If the first form is +used then step is set to 1. All of start, stop and step must be positive. +<DT>lhs</DT> +<DD> +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 use \$. If the lhs is not absolute +the current $ORIGIN is appended to the name, when appropriate. +You can also apply an offset to the iterator by using ${offset} where +offset is a decimal value to add to the iterator. +And you can also change the format of the iterator by using a printf +like string. The format is ${offset,width,radix} where offset is as before +(use 0 for no change), width is the minimum field width (always zero padded) +radix is one of d, o, x, or X to change the radix to decimal, octal, hex, or hex +with capital letters. +The default is ${0,1,d}. +For example: ${16,3} will add 16 to the iterator and be replaced by +a 3 digit decimal representation. ${0,2,x} will be replaced by a 2 digit +hex representation. To get a { character inserted into the text +immediately after the iterator, use $\{. +<DT>type</DT> +<DD> +At present the only supported types are A, AAAA, PTR, CNAME and NS. +<DT>rhs</DT> +<DD> +Rhs is the data. It is processed similarly to the lhs. +<DD> +</DL> +<H2>Resource Records</H2> +Syntax: <CODE>{<domain>|@|<blank>} +[<ttl>] [<class>] <type> <rdata> +[<comment>]</CODE> +<P> +All resource records have the same basic syntax. +<DL> +<DT><CODE>domain</CODE></DT> +<DD> +Specify the domain name for this record. If it is not absolute the +current <CODE>$ORIGIN</CODE> is appended. +<DT><CODE>@</CODE></DT> +<DD> +Use the current <CODE>$ORIGIN</CODE> for the domain name for this record. +<DT><CODE>blank</CODE></DT> +<DD> +Use the last specified domainname. +<DT><CODE>ttl</CODE></DT> +<DD> +This specifies how long this record will be cached by caching servers. +The valid range is 0-2147483647. +<DT><CODE>class</CODE></DT> +<DD> +Specify the class of this record. This is usually redundent as the +class of a zone is specfied in the configuration file prior to reading +the zone file. +<DT><CODE>type</CODE></DT> +<DD> +Specify the type of this record. This describes the contents of the rdata +section. +<DT><CODE>rdata</CODE></DT> +<DD> +This is the value of the resource record. +</DL> +<H2>Time Values: Alternate Specification format (BIND Enhancement)</H2> +<P> +Many time values within the MASTER file may be specified in multiples +of weeks, days, hours, minutes and seconds rather than just seconds. +<P> +The format for this is <CODE>#w#d#h#m#s</CODE>. To specify 1 week you would +use <CODE>1w</CODE> or two weeks and 1 hour <CODE>2w1h</CODE>. +<P> +This format applies to TTL values, and SOA REFRESH, RETRY, EXPIRE and MINIMUM +values. +</P> +</BODY> +</HTML> diff --git a/contrib/bind/doc/html/options.html b/contrib/bind/doc/html/options.html index 515ee96..e3e09ef 100644 --- a/contrib/bind/doc/html/options.html +++ b/contrib/bind/doc/html/options.html @@ -13,6 +13,7 @@ <PRE> options { + [ version <VAR>version_string</VAR>; ] [ directory <VAR>path_name</VAR>; ] [ named-xfer <VAR>path_name</VAR>; ] [ dump-file <VAR>path_name</VAR>; ] @@ -21,37 +22,55 @@ options { [ statistics-file <VAR>path_name</VAR>; ] [ auth-nxdomain <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ deallocate-on-exit <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ dialup <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ fake-iquery <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ fetch-glue <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ has-old-clients <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ host-statistics <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ multiple-cnames <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ notify <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ recursion <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ rfc2308-type1 <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ use-id-pool <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ treat-cr-as-space <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ also-notify { <VAR><A HREF="docdef.html">ip_addr</A></VAR>; [ <VAR><A HREF="docdef.html">ip_addr</A></VAR>; ... ] }; [ forward ( only | first ); ] [ forwarders { [ <VAR><A HREF="docdef.html">in_addr</A></VAR> ; [ <VAR><A HREF="docdef.html">in_addr</A></VAR> ; ... ] ] }; ] [ check-names ( master | slave | response ) ( warn | fail | ignore); ] [ allow-query { <VAR>address_match_list</VAR> }; ] [ allow-transfer { <VAR>address_match_list</VAR> }; ] + [ allow-recursion { <VAR>address_match_list</VAR> }; ] + [ blackhole { <VAR>address_match_list</VAR> }; ] [ listen-on [ port <VAR><A HREF="docdef.html">ip_port</A></VAR> ] { <VAR>address_match_list</VAR> }; ] [ query-source [ address ( <VAR><A HREF="docdef.html">ip_addr</A></VAR> | * ) ] [ port ( <VAR><A HREF="docdef.html">ip_port</A></VAR> | * ) ] ; ] + [ lame-ttl <VAR>number</VAR>; ] [ max-transfer-time-in <VAR>number</VAR>; ] + [ max-ncache-ttl <VAR>number</VAR>; ] + [ min-roots <VAR>number</VAR>; ] + [ serial-queries <VAR>number</VAR>; ] [ transfer-format ( one-answer | many-answers ); ] [ transfers-in <VAR>number</VAR>; ] [ transfers-out <VAR>number</VAR>; ] [ transfers-per-ns <VAR>number</VAR>; ] + [ transfer-source <VAR><A HREF="docdef.html">ip_addr</A></VAR>; ] + [ maintain-ixfr-base <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ max-ixfr-log-size <VAR>number</VAR>; ] [ coresize <VAR><A HREF="docdef.html">size_spec</A></VAR> ; ] [ datasize <VAR><A HREF="docdef.html">size_spec</A></VAR> ; ] [ files <VAR><A HREF="docdef.html">size_spec</A></VAR> ; ] [ stacksize <VAR><A HREF="docdef.html">size_spec</A></VAR> ; ] [ cleaning-interval <VAR>number</VAR>; ] + [ heartbeat-interval <VAR>number</VAR>; ] [ interface-interval <VAR>number</VAR>; ] [ statistics-interval <VAR>number</VAR>; ] - [ topology { <VAR>address_match_list</VAR> }; ] + [ <A HREF="#topology">topology</A> { <VAR>address_match_list</VAR> }; ] + [ <A HREF="#sortlist">sortlist</A> { <VAR>address_match_list</VAR> }; ] + [ rrset-order { <VAR>order_spec</VAR> ; [ <VAR>order_spec</VAR> ; ... ] ] }; }; </PRE> <HR> -<A NAME="Usage"><H3>Definition and Use</H3></A> +<A NAME="Usage"><H3>Definition and Usage</H3></A> <P>The options statement sets up global options to be used by BIND. This statement may appear at only once in a @@ -63,6 +82,13 @@ an options block with each option set to its default will be used.</P> <H4>Pathnames</H4> <DL> +<DT><CODE>version</CODE> +<DD> +The version the server should report via the <VAR>ndc</VAR> command +or via a query of name <CODE>version.bind</CODE> in class <I>chaos</I>. +The default is the real version number of the server, but some server +operators prefer the string <CODE>"surely you must be joking"</CODE>. + <DT><CODE>directory</CODE> <DD> The working directory of the server. Any non-absolute @@ -86,7 +112,7 @@ specified, the default is "named_dump.db". <DT><CODE>memstatistics-file</CODE> <DD> -The pathname of the file the server writes memory usage statistics to on exit, +The pathname of the file the server writes memory usage statistics to, on exit, if <CODE>deallocate-on-exit</CODE> is <CODE>yes</CODE>. If not specified, the default is "named.memstats". @@ -110,7 +136,7 @@ specified, the default is "named.stats". <DL> <DT><CODE>auth-nxdomain</CODE> <DD> -If <CODE>yes</CODE>, then the <CODE>AA</CODE> bit is always set on +If <CODE>yes</CODE>, the <CODE>AA</CODE> bit is always set on NXDOMAIN responses, even if the server is not actually authoritative. The default is <CODE>yes</CODE>. Do not turn off <CODE>auth-nxdomain</CODE> unless you are sure you know what you are @@ -118,12 +144,36 @@ doing, as some older software won't like it. <DT><CODE>deallocate-on-exit</CODE> <DD> -If <CODE>yes</CODE>, then when the server exits it will painstakingly -deallocate every object it allocated, and then write a memory usage report to +If <CODE>yes</CODE>, the server will painstakingly deallocate every object it +it allocated, when it exits, and then write a memory usage report to the <CODE>memstatistics-file</CODE>. The default is <CODE>no</CODE>, because it is faster to let the operating system clean up. <CODE>deallocate-on-exit</CODE> is handy for detecting memory leaks. +<DT><CODE>dialup</CODE> +<DD> +If <CODE>yes</CODE>, 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 +<CODE>heartbeat-interval</CODE> and hopefully during the one call. +It also suppresses some of the normal zone maintainance traffic. +The default is <CODE>no</CODE>. The <CODE>dialup</CODE> +option may also be specified in the <CODE>zone</CODE> statement, in which +case it overrides the <CODE>options dialup</CODE> statement. + +<P> +If the zone is a <CODE>master</CODE> zone, the server will send out +NOTIFY request to all the slaves. This will trigger the "zone up to +date checking" in the slave (providing it supports NOTIFY), allowing +the <CODE>slave</CODE> to verify the zone while the call us up. + +<P> +If the zone is a <CODE>slave</CODE> or <CODE>stub</CODE> zone, the server +will suppress the regular "zone up to date" queries and only perform +them when the <CODE>heartbeat-interval</CODE> expires. + <DT><CODE>fake-iquery</CODE> <DD> If <CODE>yes</CODE>, the server will simulate the obsolete DNS query type @@ -137,15 +187,29 @@ a response. <CODE>fetch-glue no</CODE> can be used in conjunction with <CODE>recursion no</CODE> to prevent the server's cache from growing or becoming corrupted (at the cost of requiring more work from the client). +<DT><CODE>has-old-clients</CODE> +<DD> +Setting the option to <CODE>yes</CODE> is equivalent to setting the follow +three options <CODE>auth-nxdomain yes;</CODE>, <CODE>maintain-ixfr-base +yes;</CODE> and <CODE>rfc2308-type1 no;</CODE>. +The use of <CODE>has-old-clients</CODE> with <CODE>auth-nxdomain</CODE>, +<CODE>maintain-ixfr-base</CODE> and <CODE>rfc2308-type1</CODE> is order +dependant. + <DT><CODE>host-statistics</CODE> <DD> -If <CODE>yes</CODE>, then statistics are kept for every host that the +If <CODE>yes</CODE>, statistics are kept for every host that the the nameserver interacts with. The default is <CODE>no</CODE>. <I>Note:</I> turning on <CODE>host-statistics</CODE> can consume huge amounts of memory. +<DT><CODE>maintain-ixfr-base</CODE> +<DD> +If <CODE>yes</CODE>, a transaction log is kept for +Incremental Zone Transfer. The default is <CODE>no</CODE>. + <DT><CODE>multiple-cnames</CODE> <DD> -If <CODE>yes</CODE>, then multiple CNAME resource records will be +If <CODE>yes</CODE>, multiple CNAME resource records will be allowed for a domain name. The default is <CODE>no</CODE>. Allowing multiple CNAME records is against standards and is not recommended. Multiple CNAME support is available because previous versions of BIND @@ -157,24 +221,62 @@ balancing by a number of sites. If <CODE>yes</CODE> (the default), DNS NOTIFY messages are sent when a zone the server is authoritative for changes. The use of NOTIFY speeds convergence between the master and its slaves. Slave servers -that receive a NOTIFY message and understand it will contact the -master server for the zone and see if they need to do a zone transfer, and -if they do, they will initiate it immediately. The <CODE>notify</CODE> +that receive a NOTIFY message, and understand it, will contact the +master server for the zone to see if they need to do a zone transfer. If +they do, they will initiate it immediately. The <CODE>notify</CODE> option may also be specified in the <CODE>zone</CODE> statement, in which case it overrides the <CODE>options notify</CODE> statement. <DT><CODE>recursion</CODE> <DD> -If <CODE>yes</CODE>, and a DNS query requests recursion, then the +If <CODE>yes</CODE>, and a DNS query requests recursion, the server will attempt to do all the work required to answer the query. If recursion is not on, the server will return a referral to the client if it doesn't know the answer. The default is <CODE>yes</CODE>. See also <CODE>fetch-glue</CODE> above. + +<DT><CODE>rfc2308-type1</CODE> +<DD> +If <CODE>yes</CODE>, the server will send NS records along with the SOA +record for negative answers. +You need to set this to <CODE>no</CODE> if you have an old BIND +server using you as a forwarder that does not understand negative answers +which contain both SOA and NS records or you have an old version of sendmail. +The correct fix is to upgrade the broken server or sendmail. +The default is <CODE>no</CODE>. + +<DT><CODE>use-id-pool</CODE> +<DD> +If <CODE>yes</CODE>, the server will keep track of its own outstanding +query ID's to avoid duplication and increase randomness. This will result +in 128KB more memory being consumed by the server. +The default is <CODE>no</CODE>. + +<DT><CODE>treat-cr-as-space</CODE> +<DD> +If <CODE>yes</CODE>, the server will treat '\r' characters the same way it +treats a ' ' or '\t'. This may be necessary when loading zone files on a +UNIX system that were generated on an NT or DOS machine. The default is <CODE>no</CODE>. + </DL> -<H4>Forwarding</H4> +<A NAME="Also-notify"><H4>Also-Notify</H4></A> + +<DT><CODE>also-notify</CODE> +<P> +Defines a global list of IP addresses that also get sent NOTIFY messages +whenever a fresh copy of the zone is loaded. This helps to ensure that +copies of the zones will quickly converge on ``stealth'' servers. +If an <CODE>also-notify</CODE> list is given in a <CODE>zone</CODE> +statement, it will override the <CODE>options also-notify</CODE> statement. +When a <CODE>zone notify</CODE> statement is set to <CODE>no</CODE>, +the IP addresses in the global <CODE>also-notify</CODE> list will not get +sent NOTIFY messages for that zone. +The default is the empty list (no global notification list). + +<A NAME="Forwarding"><H4>Forwarding</H4></A> -<P>The forwarding facility can be used to create a large sitewide +<P>The forwarding facility can be used to create a large site-wide cache on a few servers, reducing traffic over links to external nameservers. 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 @@ -197,6 +299,13 @@ Specifies the IP addresses to be used for forwarding. The default is the empty list (no forwarding). </DL> +<P>Forwarding can also be configured on a per-zone basis, allowing for +the global forwarding options to be overridden in a variety of ways. +You can set particular zones to use different forwarders, or have +different <CODE>forward only/first</CODE> behavior, or to not forward +at all. See the <A HREF="zone.html"><CODE>zone</CODE></A> statement +for more information. + <P>Future versions of BIND 8 will provide a more powerful forwarding system. The syntax described above will continue to be supported. @@ -239,7 +348,8 @@ client. check-names response ignore; </PRE> -<P><CODE>check-names</CODE> may also be specified in the <CODE>zone</CODE> +<P><CODE>check-names</CODE> may also be specified in the +<A HREF="zone.html"><CODE>zone</CODE></A> statement, in which case it overrides the <CODE>options check-names</CODE> statement. When used in a <CODE>zone</CODE> statement, the area is not specified (because it can be deduced from the zone type). @@ -267,6 +377,18 @@ server. <CODE>allow-transfer</CODE> may also be specified in the <CODE>zone</CODE> statement, in which case it overrides the <CODE>options allow-transfer</CODE> statement. If not specified, the default is to allow transfers from all hosts. + +<DT><CODE>allow-recursion</CODE> +<DD> +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. + +<DT><CODE>blackhole</CODE> +<DD> +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. </DL> <H4>Interfaces</H4> @@ -285,6 +407,10 @@ not specified, port 53 will be used. listen-on port 1234 { !1.2.3.4; 1.2/16; }; </PRE> +will enable the nameserver 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. + <P>If no <CODE>listen-on</CODE> is specified, the server will listen on port 53 on all interfaces. @@ -321,7 +447,7 @@ The server supports two zone transfer methods. <CODE>one-answer</CODE> uses one DNS message per resource record transferred. <CODE>many-answers</CODE> packs as many resource records as possible into a message. <CODE>many-answers</CODE> is more -efficient, but is only known to be understood by BIND 8.1 and patched +efficient, but is only known to be understood by BIND 8.1+ and patched versions of BIND 4.9.5. The default is <CODE>one-answer</CODE>. <CODE>transfer-format</CODE> may be overridden on a per-server basis by using the <CODE>server</CODE> statement. @@ -349,6 +475,36 @@ zones, but it also may increase the load on the remote nameserver. <CODE>transfers-per-ns</CODE> may be overridden on a per-server basis by using the <CODE>transfers</CODE> phrase of the <CODE>server</CODE> statement. + +<DT><CODE>transfer-source</CODE> +<DD> +<CODE>transfer-source</CODE> determines which local address will be bound +to the TCP connection used to fetch all zones transferred inbound by the +server. 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 <CODE>allow-transfer</CODE> +option for the zone being transferred, if one is specified. This statement +sets the <CODE>transfer-source</CODE> for all zones, but can be overridden +on a per-zone basis by including a <CODE>transfer-source</CODE> statement +within the zone block in the configuration file. + +<DT><CODE>serial-queries</CODE> +<DD> +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, but more importantly each query uses a +small amount of <I>memory</I> in the slave server while waiting for the +master server to respond. The <CODE>serial-queries</CODE> option sets the +maximum number of concurrent serial-number queries allowed to be outstanding +at any given time. The default is four (4). +<B>Note:</B> +If a server loads a large (tens or hundreds of thousands) number of slave +zones, this limit should be raised to the high hundreds or low +thousands -- otherwise the slave server may never actually become aware of +zone changes in the master servers. Beware, though, that setting this limit +arbitrarily high can spend a considerable amount of your slave server's +network, CPU, and memory resources. As with all tunable limits, this one +should be changed gently and monitored for its effects. </DL> <H4>Resource Limits</H4> @@ -366,7 +522,7 @@ example, <CODE>1G</CODE> can be used instead of <CODE>unlimited</CODE> requests unlimited use, or the maximum available amount. <CODE>default</CODE> uses the limit that was in force when the server was started. See -<VAR><AHREF="docdef.html">size_spec</A></VAR> for more details. +<VAR><A HREF="docdef.html">size_spec</A></VAR> for more details. <DL> <DT><CODE>coresize</CODE> @@ -380,7 +536,7 @@ The maximum amount of data memory the server may use. The default is <DT><CODE>files</CODE> <DD> -The maximum number of files ther server may have open concurrently. +The maximum number of files the server may have open concurrently. The default is <CODE>unlimited</CODE>. <I>Note:</I> on some operating systems the server cannot set an unlimited value and cannot determine the maximum number of open files the kernel can support. On such @@ -390,6 +546,12 @@ and the value returned by <CODE>sysconf(_SC_OPEN_MAX)</CODE>. If the actual kernel limit is larger than this value, use <CODE>limit files</CODE> to specify the limit explicitly. +<DT><CODE>max-ixfr-log-size</CODE> +<DD> +The <CODE>max-ixfr-log-size</CODE> will be used in a future release of +the server to limit the size of the +transaction log kept for Incremental Zone Transfer. + <DT><CODE>stacksize</CODE> <DD> The maximum amount of stack memory the server may use. The default is @@ -405,6 +567,12 @@ The server will remove expired resource records from the cache every <CODE>cleaning-interval</CODE> minutes. The default is 60 minutes. If set to 0, no periodic cleaning will occur. +<DT><CODE>heartbeat-interval</CODE> +<DD> +The server will perform zone maintenance tasks for all zones marked +<CODE>dialup yes</CODE> whenever this interval expires. +The default is 60 minutes. Reasonable values are up to 1 day (1440 minutes). +If set to 0, no zone maintenance for these zones will occur. <DT><CODE>interface-interval</CODE> <DD> The server will scan the network interface list every @@ -417,11 +585,11 @@ cleaned up. <DT><CODE>statistics-interval</CODE> <DD> -Nameserver statisitics will be logged every <CODE>statistics-interval</CODE> +Nameserver statistics will be logged every <CODE>statistics-interval</CODE> minutes. The default is 60. If set to 0, no statistics will be logged. </DL> -<H4>Topology</H4> +<H4><A NAME="topology">Topology</A></H4> <P>All other things being equal, when the server chooses a nameserver to query from a list of nameservers, it prefers the one that is @@ -455,15 +623,192 @@ of all. topology { localhost; localnets; }; </PRE> +<H4><A NAME="sortlist">Resource Record sorting</A></H4> + +<P> +When returning multiple RRs, +the nameserver will normally return them in +<B>Round Robin</B>, +i.e. after each request, the first RR is put to the end of the list. +As the order of RRs is not defined, this should not cause any problems. +</P> +<P> +The client resolver code should re-arrange the RRs as appropriate, +i.e. using any addresses on the local net in preference to other addresses. +However, not all resolvers can do this, or are not correctly configured. +</P> +<P> +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 nameservers, not all the clients. +</P> +<P> +The sortlist statement takes an address match list and interprets it even +more specially than the <A HREF="#topology">topology</A> statement does. +</P> +<P> +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 nested +address match list) of each top level list is checked against the +source address of the query until a match is found. +</P> +<P> +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, the second element is treated like 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. +</P> +<P> +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. +<PRE> +sortlist { + { localhost; // IF the local host + { localnets; // THEN first fit on the + 192.168.1/24; // following nets + { 192,168.2/24; 192.168.3/24; }; }; }; + { 192.168.1/24; // IF on class C 192.168.1 + { 192.168.1/24; // THEN use .1, or .2 or .3 + { 192.168.2/24; 192.168.3/24; }; }; }; + { 192.168.2/24; // IF on class C 192.168.2 + { 192.168.2/24; // THEN use .2, or .1 or .3 + { 192.168.1/24; 192.168.3/24; }; }; }; + { 192.168.3/24; // IF on class C 192.168.3 + { 192.168.3/24; // THEN use .3, or .1 or .2 + { 192.168.1/24; 192.168.2/24; }; }; }; + { { 192.168.4/24; 192.168.5/24; }; // if .4 or .5, prefer that net + }; +}; +</PRE> +The following example will give reasonable behaviour 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. +<PRE> +sortlist { + { localhost; localnets; }; + { localnets; }; +}; +</PRE> +<!-- + * XXX - it would be nice to have an ACL called "source" that matched the + * source address of a query so that a host could be configured to + * automatically prefer itself, and an ACL called "sourcenet", that + * would return the primitive IP match element that matched the source + * address so that you could do: + * { localnets; { sourcenet; { other stuff ...}; }; + * and automatically get similar behaviour to what you get with: + * { localnets; }; +--> +</P> + +<a name="RrsetOrder"> +<H4>RRset Ordering</H4> + +<P>When multiple records are returned in an answer it may be useful to +configure the order the records are placed into the response. For example the +records for a zone might be configured to always be returned in the order they +are defined in the zone file. Or perhaps a <i>random</i> shuffle of the +records as they are returned is wanted. The <var>rrset-order</var> statement +permits configuration of the ordering made of the records in a multiple record +response. The default, if no ordering is defined, is a cyclic ordering (round +robin). + +<P>An <var>order_spec</var> is defined as follows: + +<PRE> + [ <var>class</var> class_name ][ <var>type</var> type_name ][ <var>name</var> "FQDN" ] <var>order</var> ordering +</PRE> + +<P>If no <var>class</var> is specified, the default is <code>ANY</code>. If no +<var>type</var> is specified, the default is <code>ANY</code>. If no +<var>name</var> is specified, the default is <code>"*"</code>. + +<P>The legal values for <code>ordering</code> are: + +<DL> +<DT><code>fixed</code> +<DD>Records are returned in the order they are defined in the zone file. + +<DT><code>random</code> +<DD>Records are returned in some random order. + +<DT><code>cyclic</code> +<DD>Records are returned in a round-robin order. + +</DL> + + +<P>For example: + +<PRE> + rrset-order { + class IN type A name "rc.vix.com" order random; + order cyclic; + }; +</PRE> + +<P>will cause any responses for type <VAR>A</VAR> records in class +<VAR>IN</VAR> that have "rc.vix.com" as a suffix, to always be returned in +random order. All other records are returned in cyclic order. + +<P>If multiple <code>rrset-order</code> statements appear, they are not +combined--the last one applies. + +<P>If no <code>rrset-order</code> statement is specified, a default one +of: + +<pre> + rrset-order { class ANY type ANY name "*" order cyclic ; }; +</pre> + +<P>is used. + +<H4>Tuning</H4> + +<DL> +<DT><CODE>lame-ttl</CODE> +<DD> +Sets the number of seconds to cache a lame server indication. +0 disables caching. Default is 600 (10 minutes). Maximum value is 1800 (30 minutes). +<DT><CODE>max-ncache-ttl</CODE> +<DD> +To reduce network traffic and increase performance the server stores negative +answers. <CODE>max-ncache-ttl</CODE> is used to set a maximum retention time +for these answers in the server is seconds. The default <CODE>max-ncache-ttl</CODE> is +10800 seconds (3 hours). <CODE>max-ncache-ttl</CODE> cannot exceed the +maximum retention time for ordinary (positive) answers (7 days) and will be +silently truncated to 7 days if set to a value which is greater that 7 days. +<DT><CODE>min-roots</CODE> +<DD> +The minimum number of root servers that is required for a +request for the root servers to be accepted. Default 2. +</DL> <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: options.html,v 1.10 1998/05/05 19:50:28 halley Exp $ +Last Updated: $Id: options.html,v 1.36 1999/10/13 20:57:05 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/server.html b/contrib/bind/doc/html/server.html index 0eb4dca..eba350b 100644 --- a/contrib/bind/doc/html/server.html +++ b/contrib/bind/doc/html/server.html @@ -14,6 +14,7 @@ <PRE> server <VAR><A HREF="docdef.html">ip_addr</A></VAR> { [ bogus <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] + [ support-ixfr <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ transfers <VAR><A HREF="docdef.html">number</A></VAR>; ] [ transfer-format ( one-answer | many-answers ); ] [ keys { <VAR><A HREF="key.html">key_id</A></VAR> [<VAR>key_id</VAR> ... ] }; ] @@ -45,18 +46,24 @@ specified by the <CODE>options</CODE> statement will be used. to limit the number of concurrent in-bound zone transfers from the specified server. It is checked for syntax but is otherwise ignored. -<P>The <CODE>keys</CODE> statement is intended for future use by the -server. It is checked for syntax but is otherwise ignored. +<P>The <CODE>keys</CODE> clause is used to identify a +<VAR>key_id</VAR> defined by the <CODE>key</CODE> statement, to be +used for transaction security when talking to the remote server. +The <CODE>key</CODE> statememnt must come before the <CODE>server</CODE> +statement that references it. 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. <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: server.html,v 1.6 1998/03/21 01:03:13 halley Exp $ +Last Updated: $Id: server.html,v 1.10 1999/09/15 20:28:02 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/html/trusted-keys.html b/contrib/bind/doc/html/trusted-keys.html new file mode 100644 index 0000000..acf2bed --- /dev/null +++ b/contrib/bind/doc/html/trusted-keys.html @@ -0,0 +1,58 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> + <TITLE>BIND trusted-keys Statement</TITLE> +</HEAD> + +<BODY> +<H2>BIND Configuration File Guide--<CODE>trusted-keys</CODE> Statement</H2> + +<HR> + +<A NAME="Syntax"><H3>Syntax</H3></A> + +<PRE> +trusted-keys { + [ <VAR><A HREF="docdef.html">domain_name</A></VAR> <VAR><A HREF="docdef.html">number</A></VAR> <VAR><A HREF="docdef.html">number</A></VAR> <VAR><A HREF="docdef.html">number</A></VAR> <VAR>string</VAR>; ] +}; + +</PRE> + +<HR> + +<A NAME="Usage"><H3>Definition and Usage</H3></A> + +The <CODE>trusted-keys</CODE> +statement is for use with DNSSEC-style security, originally specified +in RFC 2065. DNSSEC is meant to +provide three distinct services: key distribution, data origin +authentication, and transaction and request authentication. A +complete description of DNSSEC and its use is beyond the scope of this +document, and readers interested in more information should start with +<A HREF="http://info.internet.isi.edu/in-notes/rfc/files/rfc2065.txt"> +RFC 2065</A> and then continue with the +<A HREF="http://www.ietf.org/ids.by.wg/dnssec.html"> +Internet Drafts</A>.</P> + +<P>Each trusted key is associated with a domain name. Its attributes are +the non-negative integral <VAR>flags</VAR>, <VAR>protocol</VAR>, and +<VAR>algorithm</VAR>, as well as a base-64 encoded string representing +the key.</P> + +A trusted key is added when a public key for a non-authoritative zone is +known, but cannot be securely obtained through DNS. This occurs when +a signed zone is a child of an unsigned zone. Adding the trusted +key here allows data signed by that zone to be considered secure.</P> + +<HR> + +<CENTER><P>[ <A HREF="config.html">BIND Config. File</A> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> + +<HR> +<ADDRESS> +Last Updated: $Id: trusted-keys.html,v 1.4 1999/09/15 20:28:02 cyarnell Exp $ +</ADDRESS> +</BODY> +</HTML> diff --git a/contrib/bind/doc/html/zone.html b/contrib/bind/doc/html/zone.html index b6edb38..8d90a45 100644 --- a/contrib/bind/doc/html/zone.html +++ b/contrib/bind/doc/html/zone.html @@ -15,25 +15,43 @@ zone <VAR><A HREF="docdef.html">domain_name</A></VAR> [ ( in | hs | hesiod | chaos ) ] { type master; file <VAR><A HREF="docdef.html">path_name</A></VAR>; + [ forward ( only | first ); ] + [ forwarders { [ <VAR><A HREF="docdef.html">ip_addr</A></VAR> ; [ <VAR>ip_addr</VAR> ; ... ] ] }; ] [ check-names ( warn | fail | ignore ); ] - [ allow-update { <VAR><A NAME="address_list.html">address_match_list</A></VAR> }; ] - [ allow-query { <VAR><A NAME="address_list.html">address_match_list</A></VAR> }; ] - [ allow-transfer { <VAR><A NAME="address_list.html">address_match_list</A></VAR> }; ] + [ allow-update { <VAR><A HREF="address_list.html">address_match_list</A></VAR> }; ] + [ allow-query { <VAR><A HREF="address_list.html">address_match_list</A></VAR> }; ] + [ allow-transfer { <VAR><A HREF="address_list.html">address_match_list</A></VAR> }; ] + [ dialup <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ notify <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ also-notify { <VAR><A HREF="docdef.html">ip_addr</A></VAR>; [ <VAR>ip_addr</VAR>; ... ] }; + [ ixfr-base <VAR><A HREF="docdef.html">path_name</A></VAR>; ] + [ pubkey <VAR><A HREF="docdef.html">number</A></VAR> <VAR><A HREF="docdef.html">number</A></VAR> <VAR><A HREF="docdef.html">number</A></VAR> <VAR>string</VAR>; ] }; zone <VAR><A HREF="docdef.html">domain_name</A></VAR> [ ( in | hs | hesiod | chaos ) ] { type ( slave | stub ); [ file <VAR><A HREF="docdef.html">path_name</A></VAR>; ] - masters { <VAR><A HREF="docdef.html">ip_addr</A></VAR>; [ <VAR>ip_addr</VAR>; ... ] }; + [ ixfr-base <VAR><A HREF="docdef.html">path_name</A></VAR>; ] + masters [ port <VAR><A HREF="docdef.html">ip_port</A></VAR> ] { <VAR><A HREF="docdef.html">ip_addr</A></VAR>; [ <VAR>ip_addr</VAR>; ... ] }; + [ forward ( only | first ); ] + [ forwarders { [ <VAR><A HREF="docdef.html">ip_addr</A></VAR> ; [ <VAR>ip_addr</VAR> ; ... ] ] }; ] [ check-names ( warn | fail | ignore ); ] - [ allow-update { <VAR><A NAME="address_list.html">address_match_list</A></VAR> }; ] - [ allow-query { <VAR><A NAME="address_list.html">address_match_list</A></VAR> }; ] - [ allow-transfer { <VAR><A NAME="address_list.html">address_match_list</A></VAR> }; ] + [ allow-update { <VAR><A HREF="address_list.html">address_match_list</A></VAR> }; ] + [ allow-query { <VAR><A HREF="address_list.html">address_match_list</A></VAR> }; ] + [ allow-transfer { <VAR><A HREF="address_list.html">address_match_list</A></VAR> }; ] + [ transfer-source <VAR><A HREF="docdef.html">ip_addr</A></VAR>; ] + [ dialup <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ max-transfer-time-in <VAR>number</VAR>; ] [ notify <VAR><A HREF="docdef.html">yes_or_no</A></VAR>; ] [ also-notify { <VAR><A HREF="docdef.html">ip_addr</A></VAR>; [ <VAR>ip_addr</VAR>; ... ] }; + [ pubkey <VAR><A HREF="docdef.html">number</A></VAR> <VAR><A HREF="docdef.html">number</A></VAR> <VAR><A HREF="docdef.html">number</A></VAR> <VAR>string</VAR>; ] +}; + +zone <VAR><A HREF="docdef.html">domain_name</A></VAR> [ ( in | hs | hesiod | chaos ) ] { + type forward; + [ forward ( only | first ); ] + [ forwarders { [ <VAR><A HREF="docdef.html">ip_addr</A></VAR> ; [ <VAR>ip_addr</VAR> ; ... ] ] }; ] + [ check-names ( warn | fail | ignore ); ] }; zone "." [ ( in | hs | hesiod | chaos ) ] { @@ -52,22 +70,50 @@ zone "." [ ( in | hs | hesiod | chaos ) ] { <DL> <DT><CODE>master</CODE> <DD> -The master copy of the data in a zone. +The server has a master copy of the data for the zone and will be able +to provide authoritative answers for it. + <DT><CODE>slave</CODE> <DD> A <CODE>slave</CODE> zone is a replica of a master zone. The <CODE>masters</CODE> list specifies one or more IP addresses that the -slave contacts to update its copy of the zone. If <CODE>file</CODE> -is specified, then the replica will be written to the file. Use of +slave contacts to update its copy of the zone. If a <CODE>port</CODE> +is specified then checks to see if the zone is current and zone transfers +will be done to the port given. If <CODE>file</CODE> +is specified, the replica will be written to this file whenever +the zone is changed, and reloaded from this file on a server restart. +Use of <CODE>file</CODE> is recommended, since it often speeds server startup -and eliminates a needless waste of bandwidth. +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 <CODE>vix.com</CODE> might place the zone contents into +a file called <CODE>"vi/vix.com"</CODE> where <CODE>vi/</CODE> is just the +first two letters of the zone name. (Most operating systems behave very +slowly if you put 100K files into a single directory.) <DT><CODE>stub</CODE> <DD> A <CODE>stub</CODE> zone is like a slave zone, except that it replicates only the NS records of a master zone instead of the entire zone. +<DT><CODE>forward</CODE> +<DD> +A <CODE>forward</CODE> zone is used to <A HREF="options.html#Forwarding"> +direct all queries</A> in it to other servers. The specification of +options in such a zone will override any global options +declared in the <A HREF="options.html#Forwarding">options</A> statement. + +<P>If either no <CODE>forwarders</CODE> statement is present in the +zone or an empty list for <CODE>forwarders</CODE> is given, no +forwarding will be done for the zone, cancelling the effects of any +<CODE>forwarders</CODE> in the <CODE>options</CODE> statement. +Thus if you want to use this +type of zone to change the behavior of the global <CODE>forward</CODE> +option, and not the servers used, you also need to respecify the +global forwarders. + <DT><CODE>hint</CODE> <DD> The initial set of root nameservers is specified using a @@ -81,8 +127,22 @@ a hint zone.</P> <H4>Class</H4> -<P>The zone's name may optionally be followed by a class. If a class is not -specified, class <CODE>in</CODE> is used. +<P>The zone's name may optionally be followed by a class. If a class +is not specified, class <CODE>in</CODE> (for "internet"), is assumed. +This is correct for the vast majority of cases. + +<P>The <CODE>hesiod</CODE> class is 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. More +information can be found at +<A HREF="ftp://athena-dist.mit.edu/pub/ATHENA/usenix/athena_changes.PS">MIT</A>. +The keyword <CODE>hs</CODE> is a synonym for <CODE>hesiod</CODE>.</P> + +<P>Another MIT development was CHAOSnet, a LAN protocol created in the +mid-1970s. It is still sometimes seen on LISP stations and other +hardware in the AI community, and zone data for it can be specified +with the +<CODE>chaos</CODE> class.</P> <H4>Options</H4> @@ -94,7 +154,10 @@ See <A HREF="options.html#NameChecking">Name Checking</A>. <DT><CODE>allow-query</CODE> <DD> See the description of <CODE>allow-query</CODE> in the -<A HREF="options.html#AccessControl">Access Control</A> section. +<A HREF="options.html#AccessControl">Access Control</A> section. Note that +this should in general be <I>more restrictive</I> than the similar global +option of the same name; otherwise, confusing and nonworthwhile delegations +will be returned. <DT><CODE>allow-update</CODE> <DD> @@ -106,11 +169,29 @@ server. The default is to deny updates from all hosts. See the description of <CODE>allow-transfer</CODE> in the <A HREF="options.html#AccessControl">Access Control</A> section. +<DT><CODE>transfer-source</CODE> +<DD> +<CODE>transfer-source</CODE> determines which local address will be bound to +the TCP connection used to fetch this zone. 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 +<CODE>allow-transfer</CODE> option for this zone if one is specified. + +<DT><CODE>ixfr-base</CODE> +<DD> +<CODE>ixfr-base</CODE> +specifies the file name used for IXFR transaction log file. + <DT><CODE>max-transfer-time-in</CODE> <DD> See the description of <CODE>max-transfer-time-in</CODE> in the <A HREF="options.html#ZoneTransfers">Zone Transfers</A> section. +<DT><CODE>dialup</CODE> +<DD> +See the description of <CODE>dialup</CODE> in +the <A HREF="options.html#BooleanOptions">Boolean Options</A> section. + <DT><CODE>notify</CODE> <DD> See the description of <CODE>notify</CODE> in @@ -124,17 +205,40 @@ NOTIFY message for this zone is made up of all the listed nameservers for the zone (other than the primary master) plus any IP addresses specified with <CODE>also-notify</CODE>. <CODE>also-notify</CODE> is not meaningful for <CODE>stub</CODE> zones. The default is the empty list. -</DL> +<DT><CODE>forward</CODE> +<DD> +<CODE>forward</CODE> is only meaningful if the zone has a +<CODE>forwarders</CODE> list. The <CODE>only</CODE> value causes the +lookup to fail after trying the <CODE>forwarders</CODE> and getting no +answer, while <CODE>first</CODE> would allow a normal lookup to be tried. + +<DT><CODE>forwarders</CODE> +<DD> +The <CODE>forwarders</CODE> option in a zone is used to override the +list of global forwarders. If it is not specified in a zone of type +<CODE>forward</CODE>, <STRONG>no</STRONG> forwarding is done for the +zone; the global options are not used. + +<DT><CODE>pubkey</CODE> +<DD> +A pubkey represents a public key for this zone. It is needed when this is the +top level authoritative zone served by this server and there is no chain of +trust to a <A HREF="trusted-keys.html">trusted key</A>. It is considered +secure, so that data that it signs will be considered secure. The DNSSEC +flags, protocol, and algorithm are specified, as well as a base-64 encoded +string representing the key. + +</DL> <HR> <CENTER><P>[ <A HREF="config.html">BIND Config. File</A> -| <A HREF="http://www.vix.com/isc/bind.html">BIND Home</A> -| <A HREF="http://www.isc.org">ISC</A> ]</P></CENTER> +| <A HREF="http://www.isc.org/products/BIND/">BIND Home</A> +| <A HREF="http://www.isc.org/">ISC</A> ]</P></CENTER> <HR> <ADDRESS> -Last Updated: $Id: zone.html,v 1.6 1998/03/21 01:03:14 halley Exp $ +Last Updated: $Id: zone.html,v 1.23 1999/09/30 17:58:41 cyarnell Exp $ </ADDRESS> </BODY> </HTML> diff --git a/contrib/bind/doc/man/Makefile b/contrib/bind/doc/man/Makefile index 4ac138f..b792ef9 100644 --- a/contrib/bind/doc/man/Makefile +++ b/contrib/bind/doc/man/Makefile @@ -16,7 +16,7 @@ ## ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS ## SOFTWARE. -## Portions Copyright (c) 1996 by Internet Software Consortium +## Portions Copyright (c) 1996,1999 by Internet Software Consortium ## ## Permission to use, copy, modify, and distribute this software for any ## purpose with or without fee is hereby granted, provided that the above @@ -32,7 +32,7 @@ ## SOFTWARE. # -# Makefile to install the BIND 4.9 manual entries. +# Makefile to install the BIND manual entries. # # Default Configuration: # There are a set of default assignments immediately following this @@ -228,18 +228,16 @@ SYS_OPS_OUT_EXT = ${OUT_EXT}${SYS_OPS_EXT} # # User command manual entries # -CMD_BASE = dig host dnsquery +CMD_BASE = dig host dnsquery dnskeygen CMD_SRC_EXT = 1 CMD_SRC = dig.${CMD_SRC_EXT} \ host.${CMD_SRC_EXT} \ dnsquery.${CMD_SRC_EXT} \ - dnskeygen.${CMD_SRC_EXT} \ - dnssigner.${CMD_SRC_EXT} + dnskeygen.${CMD_SRC_EXT} CMD_OUT = dig.${CMD_OUT_EXT} \ host.${CMD_OUT_EXT} \ dnsquery.${CMD_OUT_EXT} \ - dnskeygen.${CMD_OUT_EXT} \ - dnssigner.${CMD_OUT_EXT} + dnskeygen.${CMD_OUT_EXT} # # named manual entries @@ -257,6 +255,13 @@ NAMED_XFER_SRC = named-xfer.${SYS_OPS_SRC_EXT} NAMED_XFER_OUT = named-xfer.${SYS_OPS_OUT_EXT} # +# named-bootconf manual entry +# +NAMED_BOOTCONF_BASE = named-bootconf +NAMED_BOOTCONF_SRC = named-bootconf.${SYS_OPS_SRC_EXT} +NAMED_BOOTCONF_OUT = named-bootconf.${SYS_OPS_OUT_EXT} + +# # nslookup manual entry # NSLOOKUP_BASE = nslookup @@ -264,26 +269,48 @@ NSLOOKUP_SRC = nslookup.${SYS_OPS_SRC_EXT} NSLOOKUP_OUT = nslookup.${SYS_OPS_OUT_EXT} # +# nsupdate manual entry +# +NSUPDATE_BASE = nsupdate +NSUPDATE_SRC = nsupdate.${SYS_OPS_SRC_EXT} +NSUPDATE_OUT = nsupdate.${SYS_OPS_OUT_EXT} + +# # Network library routines manual entries # -LIB_NETWORK_BASE = gethostbyname resolver getnetent +LIB_NETWORK_BASE = gethostbyname inet_cidr resolver hesiod getnetent \ + tsig getaddrinfo inet_cidr getipnodebyname LIB_NETWORK_SRC_EXT = 3 LIB_NETWORK_SRC = gethostbyname.${LIB_NETWORK_SRC_EXT} \ + inet_cidr.${LIB_NETWORK_SRC_EXT} \ resolver.${LIB_NETWORK_SRC_EXT} \ - getnetent.${LIB_NETWORK_SRC_EXT} + hesiod.${LIB_NETWORK_SRC_EXT} \ + getnetent.${LIB_NETWORK_SRC_EXT} \ + tsig.${LIB_NETWORK_SRC_EXT} \ + getaddrinfo.${LIB_NETWORK_SRC_EXT} \ + getnameinfo.${LIB_NETWORK_SRC_EXT} \ + getipnodebyname.${LIB_NETWORK_SRC_EXT} LIB_NETWORK_OUT = gethostbyname.${LIB_NETWORK_OUT_EXT} \ + inet_cidr.${LIB_NETWORK_OUT_EXT} \ resolver.${LIB_NETWORK_OUT_EXT} \ - getnetent.${LIB_NETWORK_OUT_EXT} + hesiod.${LIB_NETWORK_OUT_EXT} \ + getnetent.${LIB_NETWORK_OUT_EXT} \ + tsig.${LIB_NETWORK_OUT_EXT} \ + getaddrinfo.${LIB_NETWORK_OUT_EXT} \ + getnameinfo.${LIB_NETWORK_OUT_EXT} \ + getipnodebyname.${LIB_NETWORK_OUT_EXT} # # File format manual entries # -FORMAT_BASE = resolver irs.conf +FORMAT_BASE = resolver irs.conf named.conf FORMAT_SRC_EXT = 5 FORMAT_SRC = resolver.${FORMAT_SRC_EXT} \ - irs.conf.${FORMAT_SRC_EXT} + irs.conf.${FORMAT_SRC_EXT} \ + named.conf.${FORMAT_SRC_EXT} FORMAT_OUT = resolver.${FORMAT_OUT_EXT} \ - irs.conf.${FORMAT_OUT_EXT} + irs.conf.${FORMAT_OUT_EXT} \ + named.conf.${FORMAT_OUT_EXT} # # Feature Description manual entries @@ -320,7 +347,8 @@ DESC_OUT = hostname.${DESC_OUT_EXT} mailaddr.${DESC_OUT_EXT} @${MK_MANFILE} <$*.${DESC_SRC_EXT} >$*.${DESC_OUT_EXT} OUTFILES = ${CMD_OUT} ${NAMED_OUT} ${NAMED_XFER_OUT} ${NSLOOKUP_OUT} \ - ${LIB_NETWORK_OUT} ${FORMAT_OUT} ${DESC_OUT} + ${NSUPDATE_OUT} ${LIB_NETWORK_OUT} ${FORMAT_OUT} ${DESC_OUT} \ + ${NAMED_BOOTCONF_OUT} all: ${OUTFILES} @@ -345,11 +373,21 @@ install: ${OUTFILES} \ $${f}.${SYS_OPS_OUT_EXT} \ ${DESTDIR}${DESTMAN}/${MANDIR}${SYS_OPS_EXT_DIR}/${XFER_INDOT}$${f}.${CATEXT}; \ done + @set -x; N=${SYS_OPS_EXT}; for f in ${NAMED_BOOTCONF_BASE}; do \ + ${INSTALL} -c -m 444 ${MAN_OWNER} ${MAN_GROUP} \ + $${f}.${SYS_OPS_OUT_EXT} \ + ${DESTDIR}${DESTMAN}/${MANDIR}${SYS_OPS_EXT_DIR}/${XFER_INDOT}$${f}.${CATEXT}; \ + done @set -x; N=${SYS_OPS_EXT}; for f in ${NSLOOKUP_BASE}; do \ ${INSTALL} -c -m 444 ${MAN_OWNER} ${MAN_GROUP} \ $${f}.${SYS_OPS_OUT_EXT} \ ${DESTDIR}${DESTMAN}/${MANDIR}${SYS_OPS_EXT_DIR}/$${f}.${CATEXT}; \ done + @set -x; N=${SYS_OPS_EXT}; for f in ${NSUPDATE_BASE}; do \ + ${INSTALL} -c -m 444 ${MAN_OWNER} ${MAN_GROUP} \ + $${f}.${SYS_OPS_OUT_EXT} \ + ${DESTDIR}${DESTMAN}/${MANDIR}${SYS_OPS_EXT_DIR}/$${f}.${CATEXT}; \ + done @set -x; N=${LIB_NETWORK_EXT}; for f in ${LIB_NETWORK_BASE}; do \ ${INSTALL} -c -m 444 ${MAN_OWNER} ${MAN_GROUP} \ $${f}.${LIB_NETWORK_OUT_EXT} \ diff --git a/contrib/bind/doc/man/dig.1 b/contrib/bind/doc/man/dig.1 index 72de71f..47284c2 100644 --- a/contrib/bind/doc/man/dig.1 +++ b/contrib/bind/doc/man/dig.1 @@ -1,4 +1,4 @@ -.\" $Id: dig.1,v 8.3 1998/03/21 01:01:23 halley Exp $ +.\" $Id: dig.1,v 8.4 1999/10/15 21:29:58 vixie Exp $ .\" .\" ++Copyright++ 1993 .\" - @@ -297,6 +297,9 @@ Specify class of query. May specify either an integer value to be included in the class field or use the abbreviated mnemonic as discussed above (i.e., in = C_IN). +.It Fl k Ar keydir:keyname +Sign the query with the TSIG key named keyname +that is in the directory keydir. .It Fl envsav This flag specifies that the .Ic dig diff --git a/contrib/bind/doc/man/dnskeygen.1 b/contrib/bind/doc/man/dnskeygen.1 index bdc2df9..4b3c406 100644 --- a/contrib/bind/doc/man/dnskeygen.1 +++ b/contrib/bind/doc/man/dnskeygen.1 @@ -1,4 +1,4 @@ -.\" Copyright (c) 1996 by Internet Software Consortium +.\" Copyright (c) 1996,1999 by Internet Software Consortium .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -13,163 +13,120 @@ .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS .\" SOFTWARE. .\" -.\" $Id: dnskeygen.1,v 8.2 1997/03/14 02:29:41 vixie Exp $ +.\" $Id: dnskeygen.1,v 8.5 1999/02/23 05:20:18 vixie Exp $ .\" -.Dd October 25, 1996 +.Dd December 2, 1998 .Dt DNSKEYGEN @CMD_EXT_U@ .Os BSD 4 .Sh NAME .Nm dnskeygen -.Nd generate and display public and private RSA keys for DNS +.Nd generate public, private, and shared secret keys for DNS Security .Sh SYNOPSIS .Nm dnskeygen -.Bo Fl g Ns Op Ar size -.Op Fl f -.Bc -.Bo Fl z -| -.Fl e -| -.Fl u -.Bc -.Op Fl i -.Op Fl m -.Op Fl p Ns Ar # -.Op Fl s Ns Ar # -.Op Fl x -.Ar name +.Oo Fl +.Op Cm DHR +.Ar size +.Oc +.Op Fl F +.Fl Op Cm zhu +.Op Cm Fl a +.Op Cm Fl c +.Op Cm Fl p Ar num +.Op Cm Fl s Ar num +.Fl n Ar name .Sh DESCRIPTION .Ic Dnskeygen -(DNS Key Generator) is a tool to generate and maintain RSA keys -for DNS (Domain Name System). +(DNS Key Generator) is a tool to generate and maintain keys for DNS Security +within the DNS (Domain Name System). +.Nm Dnskeygen +can generate public and private keys to authenticate zone data, and shared +secret keys to be used for Request/Transaction signatures. .Bl -tag -width Fl -.It Fl g Ns Op Ar size -.Ic Dnskeygen -will generate a new key when -the -.Dq Fl g -flag is specified. If the -.Dq Fl g -flag is not specified, then it -will attempt to display an existing key that is stored in the current -directory. If no -.Ar size -is specified after the -.Dq Fl g -flag, a key of 512 bits -will be generated; otherwise, -.Ar size -is the size of the modulus in the newly-generated key. -.It Fl f -flag can only be specified with the -.Dq Fl g -flag; this changes the -exponent used on the key. If -.Dq Fl f -is specified, the exponent is 65537, -which is suitable for encryption keys. If -.Dq Fl f -is not specified, -the exponent is 3, which is suitable for signatures and -verification of public data such as DNS records. Signing and -verifying with exponent of 65537 takes significantly more CPU time than -with exponent of 3. -.It Fl z Fl e Fl u -These flags define the type of key being generated: Zone (DNS -validation) key, End Entity (host or service) key or User (e.g. email) key, -respectively. -Each key is only allowed to be one of these. When -keys are displayed, the type of key can be changed. -.It Fl i -Indicates that the key can be used for IPSEC (Internet Protocol Security -services). -.It Fl m -Indicates that the key can be used for secure email. -.It Fl p Ns Ar # -Indicates that the key can be used for protocol number -.Ar # . -A value of -.Ar 0 -denies the use of the key for -.Em any -protocol (other than those specified by other option flags like -.Fl m ) . -A value of -.Ar 255 -allows it to be used with -.Em all -protocols. -These protocol numbers will be assigned in the latest Assigned Numbers -RFC from the Internet Assigned Numbers Authority (IANA). -.It Fl s Ns Ar # -Strength value; this value is only used when key is signing. -Interpretation of this field is to be specified later. Default value is 7. -.It Fl x -Experimental key. This indicates that software should not assume -that it should use secure protocols when talking to this zone, host, or user. -Instead, the key is being published experimentally, to debug the software -to be used to run the secure protocols, for example. -Data signed by Experimental keys will not be treated as trusted by DNS servers. -.It Ar name -The DNS name the key is for. This can be any valid DNS name. +.It Fl D +Dnskeygen will generate a +.Ic DSA/DSS +key. +.Dq size +must be one of [512, 576, 640, 704, 768, 832, 896, 960, 1024]. +.It Fl H +Dnskeygen will generate an +.Ic HMAC-MD5 +key. +.Dq size +must be between 128 and 504. +.It Fl R +Dnskeygen will generate an +.Ic RSA +key. +.Dq size +must be between 512 and 4096. +.It Fl F +.Ic (RSA only) +Use a large exponent for key generation. +.It Fl z Fl h Fl u +These flags define the type of key being generated: Zone (DNS validation) key, +Host (host or service) key or User (e.g. email) key, respectively. +Each key is only allowed to be one of these. +.It Fl a +Indicates that the key +.Ic CANNOT +be used for authentication. +.It Fl c +Indicates that the key +.Ic CANNOT +be used for encryption. +.It Fl p Ar num +Sets the key's protocol field to +.Ar num +; the default is +.Ic 3 +(DNSSEC) if +.Dq Fl z +or +.Dq Fl h +is specified and +.Ic 2 +(EMAIL) otherwise. Other accepted values are +.Ic 1 +(TLS), +.Ic 4 +(IPSEC), and +.Ic 255 +(ANY). +.It Fl s Ar num +Sets the key's strength field to +.Ar num; +the default is +.Sy 0. +.It Fl n Ar name +Sets the key's name to +.Ar name. .El .Ss DETAILS .Ic Dnskeygen -uses two files for each key: -.Pa <name>.priv +stores each key in two files: +.Pa K<name>+<alg>+<footprint>.private and -.Pa <name>.public . -File -.Pa <name>.public -contains the public key in the pubkey format: +.Pa K<name>+<alg>+<footprint>.key +The file +.Pa K<name>+<alg>+<footprint>.private +contains the private key in a portable format. The file +.Pa K<name>+<alg>+<footprint>.key +contains the public key in the DNS zone file format: .Pp -.D1 Ar <flags> <algorithm> <protocol> <exponent|modulus> +.D1 Ar <name> IN KEY <flags> <algorithm> <protocol> <exponent|modulus> .Pp -.Ic Dnskeygen -.Ar name -displays the public key in both DNS RR format and pubkey format. -.Ic Dnskeygen -can display the key with different flags on subsequent runs. -The contents of the public key file will not be changed. -.Pa <name>.priv -stores the private key, in either a password-protected -format file or in a open file. The advantage of -a password-protected file is that it is harder to use the key if the file is -stolen. The disadvantage is that the password has to be given each time -the key is read. If the key is to be stored in a safe off-line place, -and only used for signing zones, then local policy may allow storing the -key in an unencrypted format. .Sh ENVIRONMENT No environmental variables are used. .Sh SEE ALSO -RSAREF documentation, .Em RFC 2065 -on secure DNS. +on secure DNS and the +.Em TSIG +Internet Draft. .Sh AUTHOR Olafur Gudmundsson (ogud@tis.com). .Sh ACKNOWLEDGMENTS -The underlying cryptographic math is done by the RSAREF or BSAFE libraries. +The underlying cryptographic math is done by the DNSSAFE and/or Foundation +Toolkit libraries. .Sh BUGS -.Ic Dnskeygen -renames old keys in such a way that only one -.Dq previous -key for a given name is kept; older keys are overwritten. (For example, -the third time a key is generated for a given name, the second key is kept -as the -.Dq previous -key, while the first key is lost. If a key is generated -.Em again -for this name--i.e., if the fourth key is generated--then the third key -will become the -.Dq previous -key and the second key will be lost.) -.Ic Dnskeygen -will not overwrite existing keys. -Only one key for each name can be stored in the current directory. If you -want to keep your old keys, rename the files before running -.Ic dnskeygen . -Otherwise you must delete them before running -.Ic dnskeygen . -.Pp -Portability of Private key file must be better tested between -different implementations of RSA. +None are known at this time diff --git a/contrib/bind/doc/man/dnsquery.1 b/contrib/bind/doc/man/dnsquery.1 index 048d29e..2662ab4 100644 --- a/contrib/bind/doc/man/dnsquery.1 +++ b/contrib/bind/doc/man/dnsquery.1 @@ -1,6 +1,6 @@ -.\" $Id: dnsquery.1,v 8.2 1997/03/14 02:29:41 vixie Exp $ +.\" $Id: dnsquery.1,v 8.3 1999/01/08 18:54:21 vixie Exp $ .\" -.\"Copyright (c) 1995, 1996 by Internet Software Consortium +.\"Copyright (c) 1995,1996,1999 by Internet Software Consortium .\" .\"Permission to use, copy, modify, and distribute this software for any .\"purpose with or without fee is hereby granted, provided that the above diff --git a/contrib/bind/doc/man/getaddrinfo.3 b/contrib/bind/doc/man/getaddrinfo.3 new file mode 100644 index 0000000..a906c5d --- /dev/null +++ b/contrib/bind/doc/man/getaddrinfo.3 @@ -0,0 +1,361 @@ +.\" Copyright (c) 1983, 1987, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 +.\" $Id: getaddrinfo.3,v 8.1 1999/01/11 21:30:51 vixie Exp $ +.\" +.Dd May 25, 1995 +.Dt GETADDRINFO @LIB_NETWORK_EXT@ +.Os KAME +.Sh NAME +.Nm getaddrinfo +.Nm freeaddrinfo , +.Nm gai_strerror +.Nd nodename-to-address translation in protocol-independent manner +.Sh SYNOPSIS +.Fd #include <sys/socket.h> +.Fd #include <netdb.h> +.Ft int +.Fn getaddrinfo "const char *nodename" "const char *servname" \ +"const struct addrinfo *hints" "struct addrinfo **res" +.Ft void +.Fn freeaddrinfo "struct addrinfo *ai" +.Ft "char *" +.Fn gai_strerror "int ecode" +.Sh DESCRIPTION +The +.Fn getaddrinfo +function is defined for protocol-independent nodename-to-address translation. +It performs functionality of +.Xr gethostbyname @LIB_NETWORK_EXT@ +and +.Xr getservbyname @LIB_NETWORK_EXT@ , +in more sophisticated manner. +.Pp +The addrinfo structure is defined as a result of including the +.Li <netdb.h> +header: +.Bd -literal -offset +struct addrinfo { * + int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ + int ai_family; /* PF_xxx */ + int ai_socktype; /* SOCK_xxx */ + int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ + size_t ai_addrlen; /* length of ai_addr */ + char *ai_canonname; /* canonical name for nodename */ + struct sockaddr *ai_addr; /* binary address */ + struct addrinfo *ai_next; /* next structure in linked list */ +}; +.Ed +.Pp +The +.Fa nodename +and +.Fa servname +arguments are pointers to null-terminated strings or +.Dv NULL . +One or both of these two arguments must be a +.Pf non Dv -NULL +pointer. +In the normal client scenario, both the +.Fa nodename +and +.Fa servname +are specified. +In the normal server scenario, only the +.Fa servname +is specified. +A +.Pf non Dv -NULL +.Fa nodename +string can be either a node name or a numeric host address string +.Po +i.e., a dotted-decimal IPv4 address or an IPv6 hex address +.Pc . +A +.Pf non Dv -NULL +.Fa servname +string can be either a service name or a decimal port number. +.Pp +The caller can optionally pass an +.Li addrinfo +structure, pointed to by the third argument, +to provide hints concerning the type of socket that the caller supports. +In this +.Fa hints +structure all members other than +.Fa ai_flags , +.Fa ai_family , +.Fa ai_socktype , +and +.Fa ai_protocol +must be zero or a +.Dv NULL +pointer. +A value of +.Dv PF_UNSPEC +for +.Fa ai_family +means the caller will accept any protocol family. +A value of 0 for +.Fa ai_socktype +means the caller will accept any socket type. +A value of 0 for +.Fa ai_protocol +means the caller will accept any protocol. +For example, if the caller handles only TCP and not UDP, then the +.Fa ai_socktype +member of the hints structure should be set to +.Dv SOCK_STREAM +when +.Fn getaddrinfo +is called. +If the caller handles only IPv4 and not IPv6, then the +.Fa ai_family +member of the +.Fa hints +structure should be set to +.Dv PF_INET +when +.Fn getaddrinfo +is called. +If the third argument to +.Fn getaddrinfo +is a +.Dv NULL +pointer, this is the same as if the caller had filled in an +.Li addrinfo +structure initialized to zero with +.Fa ai_family +set to PF_UNSPEC. +.Pp +Upon successful return a pointer to a linked list of one or more +.Li addrinfo +structures is returned through the final argument. +The caller can process each +.Li addrinfo +structure in this list by following the +.Fa ai_next +pointer, until a +.Dv NULL +pointer is encountered. +In each returned +.Li addrinfo +structure the three members +.Fa ai_family , +.Fa ai_socktype , +and +.Fa ai_protocol +are the corresponding arguments for a call to the +.Fn socket +function. +In each +.Li addrinfo +structure the +.Fa ai_addr +member points to a filled-in socket address structure whose length is +specified by the +.Fa ai_addrlen +member. +.Pp +If the +.Dv AI_PASSIVE +bit is set in the +.Fa ai_flags +member of the +.Fa hints +structure, then the caller plans to use the returned socket address +structure in a call to +.Fn bind . +In this case, if the +.Fa nodename +argument is a +.Dv NULL +pointer, then the IP address portion of the socket +address structure will be set to +.Dv INADDR_ANY +for an IPv4 address or +.Dv IN6ADDR_ANY_INIT +for an IPv6 address. +.Pp +If the +.Dv AI_PASSIVE +bit is not set in the +.Fa ai_flags +member of the +.Fa hints +structure, then the returned socket address structure will be ready for a +call to +.Fn connect +.Pq for a connection-oriented protocol +or either +.Fn connect , +.Fn sendto , or +.Fn sendmsg +.Pq for a connectionless protocol . +In this case, if the +.Fa nodename +argument is a +.Dv NULL +pointer, then the IP address portion of the +socket address structure will be set to the loopback address. +.Pp +If the +.Dv AI_CANONNAME +bit is set in the +.Fa ai_flags +member of the +.Fa hints +structure, then upon successful return the +.Fa ai_canonname +member of the first +.Li addrinfo +structure in the linked list will point to a null-terminated string +containing the canonical name of the specified +.Fa nodename . +.Pp +If the +.Dv AI_NUMERICHOST +bit is set in the +.Fa ai_flags +member of the +.Fa hints +structure, then a +.Pf non Dv -NULL +.Fa nodename +string must be a numeric host address string. +Otherwise an error of +.Dv EAI_NONAME +is returned. +This flag prevents any type of name resolution service (e.g., the DNS) +from being called. +.Pp +All of the information returned by +.Fn getaddrinfo +is dynamically allocated: +the +.Li addrinfo +structures, and the socket address structures and canonical node name +strings pointed to by the addrinfo structures. +To return this information to the system the function +Fn freeaddrinfo +is called. +The +.Fa addrinfo +structure pointed to by the +.Fa ai argument +is freed, along with any dynamic storage pointed to by the structure. +This operation is repeated until a +.Dv NULL +.Fa ai_next +pointer is encountered. +.Pp +To aid applications in printing error messages based on the +.Dv EAI_xxx +codes returned by +.Fn getaddrinfo , +.Fn gai_strerror +is defined. +The argument is one of the +.Dv EAI_xxx +values defined earlier and the return value points to a string describing +the error. +If the argument is not one of the +.Dv EAI_xxx +values, the function still returns a pointer to a string whose contents +indicate an unknown error. +.Sh FILES +.Bl -tag -width /etc/resolv.conf -compact +.It Pa /etc/hosts +.It Pa /etc/host.conf +.It Pa /etc/resolv.conf +.El +.Sh DIAGNOSTICS +Error return status from +.Fn getaddrinfo +is zero on success and non-zero on errors. +Non-zero error codes are defined in +.Li <netdb.h> , +and as follows: +.Pp +.Bl -tag -width EAI_ADDRFAMILY -compact +.It Dv EAI_ADDRFAMILY +address family for nodename not supported +.It Dv EAI_AGAIN +temporary failure in name resolution +.It Dv EAI_BADFLAGS +invalid value for ai_flags +.It Dv EAI_FAIL +non-recoverable failure in name resolution +.It Dv EAI_FAMILY +ai_family not supported +.It Dv EAI_MEMORY +memory allocation failure +.It Dv EAI_NODATA +no address associated with nodename +.It Dv EAI_NONAME +nodename nor servname provided, or not known +.It Dv EAI_SERVICE +servname not supported for ai_socktype +.It Dv EAI_SOCKTYPE +ai_socktype not supported +.It Dv EAI_SYSTEM +system error returned in errno +.El +.Pp +If called with proper argument, +.Fn gai_strerror +returns a pointer to a string describing the given error code. +If the argument is not one of the +.Dv EAI_xxx +values, the function still returns a pointer to a string whose contents +indicate an unknown error. +.Sh SEE ALSO +.Xr getnameinfo @LIB_NETWORK_EXT@ , +.Xr gethostbyname @LIB_NETWORK_EXT@ , +.Xr getservbyname @LIB_NETWORK_EXT@ , +.Xr hosts @FORMAT_EXT@ , +.Xr services @FORMAT_EXT@ , +.Xr hostname @DESC_EXT@ , +.Xr named @SYS_OPS_EXT@ +.Pp +R. Gilligan, S. Thomson, J. Bound, and W. Stevens, +``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997. +.Sh HISTORY +The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. +.Sh STANDARDS +The +.Fn getaddrinfo +function is defined IEEE POSIX 1003.1g draft specification, +and documented in ``Basic Socket Interface Extensions for IPv6'' +.Pq RFC2133 . +.Sh BUGS +The text was shamelessly copied from RFC2133. diff --git a/contrib/bind/doc/man/getipnodebyname.3 b/contrib/bind/doc/man/getipnodebyname.3 new file mode 100644 index 0000000..3396c3a --- /dev/null +++ b/contrib/bind/doc/man/getipnodebyname.3 @@ -0,0 +1,231 @@ +.\" Copyright (c) 1996,1999 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\" CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" +.\" Copyright (c) 1983, 1987 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms are permitted provided +.\" that: (1) source distributions retain this entire copyright notice and +.\" comment, and (2) distributions including binaries display the following +.\" acknowledgement: ``This product includes software developed by the +.\" University of California, Berkeley and its contributors'' in the +.\" documentation or other materials provided with the distribution and in +.\" all advertising materials mentioning features or use of this software. +.\" Neither the name of the University nor the names of its contributors may +.\" be used to endorse or promote products derived from this software without +.\" specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.Dd September 17, 1999 +.Dt GETIPNODEBYNAME @LIB_NETWORK_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm getipnodebyname , +.Nm getipnodebyaddr +.Nd get network host entry +.br +.Nm freehostent +.Nd free network host entry +.Sh SYNOPSIS +.Fd #include <netdb.h> +.Pp +.Ft struct hostent * +.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error"; +.Ft struct hostent * +.Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error"; +.Ft void +.Fn freehostent "struct hostent *he"; +.Sh DESCRIPTION +.Fn Getipnodebyname , +and +.Fn getipnodebyaddr +each return a pointer to a +.Ft hostent +structure (see below) describing an internet host +referenced by name or by address, as the function names indicate. +This structure contains either the information obtained from the name server, +.Xr @INDOT@named @SYS_OPS_EXT@ , +or broken-out fields from a line in +.Pa /etc/hosts . +If the local name server is not running, these routines do a lookup in +.Pa /etc/hosts . +.Bd -literal -offset indent +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 */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width "h_addr_list" +.It h_name +Official name of the host. +.It h_aliases +A zero-terminated array of alternate names for the host. +.It h_addrtype +The type of address being returned. +.It h_length +The length, in bytes, of the address. +.It h_addr_list +A zero-terminated array of network addresses for the host. +Host addresses are returned in network byte order. +.It h_addr +The first address in +.Li h_addr_list ; +this is for backward compatibility. +.El +.Pp +This structure should be freed after use by calling +.Fn freehostent . +.Pp +When using the nameserver, +.Fn getiphostbyaddr +will search for the named host in each parent domain given in the +.Dq Li search +directive of +.Xr resolv.conf @FORMAT_EXT@ +unless the name contains a dot +.Pq Dq \&. . +If the name contains no dot, and if the environment variable +.Ev HOSTALIASES +contains the name of an alias file, the alias file will first be searched +for an alias matching the input name. +See +.Xr hostname @DESC_EXT@ +for the domain search procedure and the alias file format. +.Pp +.Fn Getiphostbyaddr +can be told to look for IPv4 addresses, IPv6 addresses or both IPv4 and IPv6. +If IPv4 addresses only are to be looked up then +.Fa af +should be set to +.Dv AF_INET , +otherwise it should be set to +.Dv AF_INET6 . +.Pp +There are three flags that can be set +.Bl -tag -width "AI_ADDRCONFIG" +.It Dv AI_V4MAPPED +Return IPv4 addresses if no IPv6 addresses are found. +This flag is ignored unless +.Fa af +is +.Dv AF_INET6 . +.It Dv AI_ALL +Return IPv4 addresses as well IPv6 addresses if +.Dv AI_V4MAPPED +is set. +This flag is ignored unless +.Fa af +is +.Dv AF_INET6 . +.It Dv AI_ADDRCONFIG +Only return addresses of a given type if the system has an active interface +with that type. +.El +.Pp +Also +.Dv AI_DEFAULT +is defined to be +.Dv (AI_V4MAPPED|AI_ADDRCONFIG) . +.Pp +.Fn Getipnodebyaddr +will lookup IPv4 mapped and compatible addresses in the IPv4 name +space and IPv6 name space +.Pp +.Fn Freehostent +frees the hostent structure allocated be +.Fn getipnodebyname +and +.Fn getipnodebyaddr . +The structures returned by +.Fn gethostbyname , +.Fn gethostbyname2 , +.Fn gethostbyaddr +and +.Fn gethostent +should not be passed to +.Fn freehostent +as they are pointers to static areas. +.Sh ENVIRONMENT +.Bl -tag -width "HOSTALIASES " -compress +.It Ev HOSTALIASES +Name of file containing +.Pq Ar host alias , full hostname +pairs. +.El +.Sh FILES +.Bl -tag -width "HOSTALIASES " -compress +.It Pa /etc/hosts +See +.Xr hosts @FORMAT_EXT@ . +.It Ev HOSTALIASES +Name of file containing +.Pq Ar host alias , full hostname +pairs. +.El +.Sh DIAGNOSTICS +.Pp +Error return status from +.Fn getipnodebyname +and +.Fn getipnodebyaddr +is indicated by return of a null pointer. +In this case +.Ft error +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +.Ft errno +can have the following values: +.Bl -tag -width "HOST_NOT_FOUND " -offset indent +.It Dv NETDB_INTERNAL +This indicates an internal error in the library, unrelated to the network +or name service. +.Ft errno +will be valid in this case; see +.Xr perror @SYSCALL_EXT@ . +.It Dv HOST_NOT_FOUND +No such host is known. +.It Dv TRY_AGAIN +This is usually a temporary error +and means that the local server did not receive +a response from an authoritative server. +A retry at some later time may succeed. +.It Dv NO_RECOVERY +Some unexpected server failure was encountered. +This is a non-recoverable error, as one might expect. +.It Dv NO_ADDRESS +The requested name is valid but does not have an IP address; +this is not a temporary error. +This means that the name is known to the name server but there is no address +associated with this name. +Another type of request to the name server using this domain name +will result in an answer; +for example, a mail-forwarder may be registered for this domain. +.El +.Sh SEE ALSO +.Xr hosts @FORMAT_EXT@ , +.Xr hostname @DESC_EXT@ , +.Xr @INDOT@named @SYS_OPS_EXT@ , +.Xr resolver @LIB_NETWORK_EXT@ , +.Xr resolver @FORMAT_EXT@ , +.Xr gethostbyname @LIB_NETWORK_EXT@ , +.Xr RFC2553 . diff --git a/contrib/bind/doc/man/getnameinfo.3 b/contrib/bind/doc/man/getnameinfo.3 new file mode 100644 index 0000000..02548c0 --- /dev/null +++ b/contrib/bind/doc/man/getnameinfo.3 @@ -0,0 +1,103 @@ +.\" $Id: getnameinfo.3,v 8.1 1999/01/11 21:30:51 vixie Exp $ +.\" +.\"Copyright (c) 1998,1999 by Internet Software Consortium +.\" +.\"Permission to use, copy, modify, and distribute this software for any +.\"purpose with or without fee is hereby granted, provided that the above +.\"copyright notice and this permission notice appear in all copies. +.\" +.\"THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\"CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\"DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\"PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\"ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\"SOFTWARE. +.\" +.Dd January 11, 1999 +.Dt GETRNAMEINFO @LIB_NETWORK_EXT@ +.Sh NAME +.Nm getnameinfo +.Nd address-to-name translation in protocol-independent manner +.Sh SYNOPSIS +.Fd #include <sys/socket.h> +.Fd #include <netdb.h> +.Ft int +.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \ +"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" +.Sh DESCRIPTION +The +.Fn getnameinfo +function is defined for protocol-independent address-to-nodename translation. +It performs functionality of +.Xr gethostbyaddr @LIB_NETWORK_EXT@ +and +.Xr getservbyport @LIB_NETWORK_EXT@ +in more sophisticated manner. +.Pp +The +.Fa sa +arguement is a pointer to a generic socket address structure of size +.Fa salen . +The arguements +.Fa host +and +.Fa serv +are pointers to buffers to hold the return values. +Their sizes are specified by +.Fa hostlen +and +.Fa servlen +repectively. +Either +.Fa host +or +.Fa serv +may be +.Dv NULL +if the hostname or service name is not required. +.Pp +The +.Fa flags +arguement modifies the behaviour of +.Fn getnameinfo +as follows: +.Pp +If +.Dv NI_NOFQDN +is set only the unqualified hostname is returned for local fully +qualified names. +.Pp +If +.Dv NI_NUMERICHOST +is set then the numeric form of the hostname is returned. +.Pp +If +.Dv NI_NAMEREQD +is set, then a error is returned if the hostname cannot be looked up. +.Pp +If +.Dv NI_NUMERICSERV +is set then the service is returned in numeric form. +.Pp +If +.Dv NI_DGRAM +is set then the service is UDP based rather than TCP based. +.Sh SEE ALSO +.Xr getaddrinfo @LIB_NETWORK_EXT@ , +.Xr gethostbyaddr @LIB_NETWORK_EXT@ , +.Xr getservbyport @LIB_NETWORK_EXT@ , +.Xr hosts @FORMAT_EXT@ , +.Xr services @FORMAT_EXT@ , +.Xr hostname @DESC_EXT@ , +.Xr named @SYS_OPS_EXT@ +.Pp +R. Gilligan, S. Thomson, J. Bound, and W. Stevens, +``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997. +.Sh STANDARDS +The +.Fn getaddrinfo +function is defined IEEE POSIX 1003.1g draft specification, +and documented in ``Basic Socket Interface Extensions for IPv6'' +.Pq RFC2133 . diff --git a/contrib/bind/doc/man/getnetent.3 b/contrib/bind/doc/man/getnetent.3 index 3b941e2..4f600e0 100644 --- a/contrib/bind/doc/man/getnetent.3 +++ b/contrib/bind/doc/man/getnetent.3 @@ -1,6 +1,6 @@ -.\" $Id: getnetent.3,v 8.3 1997/03/14 02:29:43 vixie Exp $ +.\" $Id: getnetent.3,v 8.4 1999/01/08 18:54:23 vixie Exp $ .\" -.\"Copyright (c) 1995, 1996 by Internet Software Consortium +.\"Copyright (c) 1995,1996,1999 by Internet Software Consortium .\" .\"Permission to use, copy, modify, and distribute this software for any .\"purpose with or without fee is hereby granted, provided that the above diff --git a/contrib/bind/doc/man/hesiod.3 b/contrib/bind/doc/man/hesiod.3 new file mode 100644 index 0000000..284b8f4 --- /dev/null +++ b/contrib/bind/doc/man/hesiod.3 @@ -0,0 +1,129 @@ +.\" $Id: hesiod.3,v 8.1 1999/04/12 02:47:00 vixie Exp $ +.\" +.\" Copyright 1988, 1996 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH HESIOD 3 "30 November 1996" +.SH NAME +hesiod, hesiod_init, hesiod_resolve, hesiod_free_list, hesiod_to_bind, hesiod_end \- Hesiod name server interface library +.SH SYNOPSIS +.nf +.B #include <hesiod.h> +.PP +.B int hesiod_init(void **\fIcontext\fP) +.B char **hesiod_resolve(void *\fIcontext\fP, const char *\fIname\fP, +.B const char *\fItype\fP) +.B void hesiod_free_list(void *\fIcontext\fP, char **\fIlist\fP); +.B char *hesiod_to_bind(void *\fIcontext\fP, const char *\fIname\fP, +.B const char *\fItype\fP) +.B void hesiod_end(void *\fIcontext\fP) +.fi +.SH DESCRIPTION +This family of functions allows you to perform lookups of Hesiod +information, which is stored as text records in the Domain Name +Service. To perform lookups, you must first initialize a +.IR context , +an opaque object which stores information used internally by the +library between calls. +.I hesiod_init +initializes a context, storing a pointer to the context in the +location pointed to by the +.I context +argument. +.I hesiod_end +frees the resources used by a context. +.PP +.I hesiod_resolve +is the primary interface to the library. If successful, it returns a +list of one or more strings giving the records matching +.I name +and +.IR type . +The last element of the list is followed by a NULL pointer. It is the +caller's responsibility to call +.I hesiod_free_list +to free the resources used by the returned list. +.PP +.I hesiod_to_bind +converts +.I name +and +.I type +into the DNS name used by +.IR hesiod_resolve . +It is the caller's responsibility to free the returned string using +.IR free . +.SH RETURN VALUES +If successful, +.I hesiod_init +returns 0; otherwise it returns \-1 and sets +.I errno +to indicate the error. On failure, +.I hesiod_resolve +and +.I hesiod_to_bind +return NULL and set the global variable +.I errno +to indicate the error. +.SH ENVIRONMENT +If the environment variable +.B HES_DOMAIN +is set, it will override the domain in the Hesiod configuration file. +If the environment variable +.B HESIOD_CONFIG +is set, it specifies the location of the Hesiod configuration file. +.SH SEE ALSO +`Hesiod - Project Athena Technical Plan -- Name Service', named(8), +hesiod.conf(5) +.SH ERRORS +Hesiod calls may fail because of: +.IP ENOMEM +Insufficient memory was available to carry out the requested +operation. +.IP ENOEXEC +.I hesiod_init +failed because the Hesiod configuration file was invalid. +.IP ECONNREFUSED +.I hesiod_resolve +failed because no name server could be contacted to answer the query. +.IP EMSGSIZE +.I hesiod_resolve +failed because the query or response was too big to fit into the +packet buffers. +.IP ENOENT +.I hesiod_resolve +failed because the name server had no text records matching +.I name +and +.IR type , +or +.I hesiod_to_bind +failed because the +.I name +argument had a domain extension which could not be resolved with type +``rhs-extension'' in the local Hesiod domain. +.SH AUTHOR +Steve Dyer, IBM/Project Athena +.br +Greg Hudson, MIT Team Athena +.br +Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology. +.SH BUGS +The strings corresponding to the +.I errno +values set by the Hesiod functions are not particularly indicative of +what went wrong, especially for +.I ENOEXEC +and +.IR ENOENT . diff --git a/contrib/bind/doc/man/inet_cidr.3 b/contrib/bind/doc/man/inet_cidr.3 new file mode 100644 index 0000000..9aeb102 --- /dev/null +++ b/contrib/bind/doc/man/inet_cidr.3 @@ -0,0 +1,94 @@ +.\" $Id: inet_cidr.3,v 8.2 1999/01/08 18:54:24 vixie Exp $ +.\" +.\"Copyright (c) 1998,1999 by Internet Software Consortium +.\" +.\"Permission to use, copy, modify, and distribute this software for any +.\"purpose with or without fee is hereby granted, provided that the above +.\"copyright notice and this permission notice appear in all copies. +.\" +.\"THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\"CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\"DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\"PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\"ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\"SOFTWARE. +.\" +.Dd October 19, 1998 +.Dt INET_CIDR @LIB_NETWORK_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm inet_cidr_ntop , +.Nm inet_cidr_pton +.Nd network translation routines +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <netinet/in.h> +.Fd #include <arpa/inet.h> +.Fn inet_cidr_ntop "int af" "const void *src" "int bits" "char *dst" "size_t size" +.Fn inet_cidr_pton "int af" "const char *src" "void *dst" "int *bits" +.Sh DESCRIPTION +These routines are used for converting addresses to and from network and +presentation forms with CIDR (Classless Inter-Domain Routing) representation, +embedded net mask. +.Pp +.Bd -literal + 130.155.16.1/20 +.Ed +.\" ::ffff:130.155.16.1/116 +.Pp +.Fn inet_cidr_ntop +converts an address from network to presentation format. +.Pp +.Ft af +describes the type of address that is being passed in +.Ft src. +.\"Currently defined types are AF_INET and AF_INET6. +Currently only AF_INET is supported. +.Pp +.Ft src +is an address in network byte order, its length is determined from +.Ft af. +.Pp +.Ft bits +specifies the number of bits in the netmask unless it is -1 in which case +the CIDR representation is omitted. +.Pp +.Ft dst +is a caller supplied buffer of at least +.Ft size +bytes. +.Pp +.Fn inet_cidr_ntop +returns +.Ft dst +on success or NULL. +Check errno for reason. +.Pp +.Fn inet_cidr_pton +converts and address from presentation format, with optional CIDR +reperesentation, to network format. +The resulting address is zero filled if there were insufficint bits in +.Ft src. +.Pp +.Ft af +describes the type of address that is being passed in via +.Ft src +and determines the size of +.Ft dst. +.Pp +.Ft src +is an address in presentation format. +.Pp +.Ft bits +returns the number of bits in the netmask or -1 if a CIDR representation was +not supplied. +.Pp +.Fn inet_cidr_pton +returns 0 on succces or -1 on error. +Check errno for reason. +ENOENT indicates an invalid netmask. +.Sh SEE ALSO +.Xr intro 2 diff --git a/contrib/bind/doc/man/irs.conf.5 b/contrib/bind/doc/man/irs.conf.5 index 50216e3..9ee5882 100644 --- a/contrib/bind/doc/man/irs.conf.5 +++ b/contrib/bind/doc/man/irs.conf.5 @@ -1,4 +1,4 @@ -.\" Copyright (c) 1996 by Internet Software Consortium +.\" Copyright (c) 1996,1999 by Internet Software Consortium .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -44,7 +44,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: irs.conf.5,v 8.2 1997/11/17 06:46:27 vixie Exp $ +.\" $Id: irs.conf.5,v 8.4 1999/01/18 07:46:45 vixie Exp $ .\" .Dd November 16, 1997 .Dt IRS.CONF 5 @@ -96,6 +96,7 @@ Access method Description local Use a local file, usually in /etc dns Use the domain name service (includes hesiod) nis Use the Sun-compatible Network Information Service +irp Use the IRP daemon on the localhost. .Ed .Pp Available options: @@ -138,7 +139,10 @@ protocols local hosts dns continue hosts local -networks local +# Networks comes first from the local file, and failing +# that the, irp daemon +networks local continue +networks irp netgroup local .Ed diff --git a/contrib/bind/doc/man/named-bootconf.8 b/contrib/bind/doc/man/named-bootconf.8 new file mode 100644 index 0000000..2a0d39d --- /dev/null +++ b/contrib/bind/doc/man/named-bootconf.8 @@ -0,0 +1,70 @@ +.\" $NetBSD: named-bootconf.8,v 1.1 1998/11/19 21:11:45 tron Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from software contributed to The NetBSD +.\" Foundation by Matthias Scheler. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1999 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\" CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. + +.Dd November 19, 1998 +.Dt NAMED-BOOTCONF 8 +.Os NetBSD +.Sh NAME +.Nm named-bootconf +.Nd convert name server configuration files +.Sh SYNOPSIS +.Nm +.Sh DESCRIPTION +.Nm +converts named configuration files from BIND 4 format to BIND 8 format. +.Sh EXAMPLES +named-bootconf < named.boot > named.conf +.Sh BUGS +Comments from the source file will not always appear at the appropriate place +in the target file. +.Sh SEE ALSO +.Xr named 8 , +.Xr named.conf 5 diff --git a/contrib/bind/doc/man/named-xfer.8 b/contrib/bind/doc/man/named-xfer.8 index 766d583..e7b2cf3 100644 --- a/contrib/bind/doc/man/named-xfer.8 +++ b/contrib/bind/doc/man/named-xfer.8 @@ -49,6 +49,24 @@ .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS .\" SOFTWARE. .\" - +.\" Portions Copyright (c) 1999 by Check Point Software Technologies, Inc. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies, and that +.\" the name of Check Point Software Technologies Incorporated not be used +.\" in advertising or publicity pertaining to distribution of the document +.\" or software without specific, written prior permission. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND CHECK POINT SOFTWARE TECHNOLOGIES +.\" INCORPORATED DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. +.\" IN NO EVENT SHALL CHECK POINT SOFTWARE TECHNOLOGIES INCORPRATED +.\" BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER +.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" .\" --Copyright-- .\" .\" from named.8 6.6 (Berkeley) 2/14/89 @@ -66,10 +84,14 @@ .Fl s Ar serial_no .Op Fl d Ar debuglevel .Op Fl l Ar debug_log_file +.Op Fl i Ar ixfr_file .Op Fl t Ar trace_file .Op Fl p Ar port# .Op Fl S -.Ar nameserver ... +.Ar nameserver +.Op Ar [ Sy axfr +| +.Op Sy ixfr ] .Sh DESCRIPTION .Ic Named-xfer is an ancillary program executed by @@ -107,6 +129,11 @@ or Note that this only applies if .Dq Fl d is also specified. +.It Fl i Ar ixfr_file +Specifies the name of the +.Ar ixfr_file +into which the zone changes from Incremental Zone Transfer (IXFR) +should be dumped when it is received from the primary server. .It Fl t Ar trace_file Specifies a .Ar trace_file @@ -138,10 +165,21 @@ syntax no host name are allowed here. At least one address must be specified. Any additional addresses will be tried, in order, if the first one fails to transfer to us successfully. +The +.Sy axfr +or +.Sy ixfr +after name server address designates the type of zone transfer to perform. +Use +.Sy axfr +for a full zone transfer or +.Sy ixfr +for an incremental zone transfer. .Sh SEE ALSO .Xr hostname @DESC_EXT@ , .Xr @INDOT@named @SYS_OPS_EXT@ , .Xr resolver @LIB_NETWORK_EXT@ , .Xr resolver @FORMAT_EXT@ , -RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123, +RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, +RFC 1123, RFC 1995 .Dq Name Server Operations Guide for Sy BIND . diff --git a/contrib/bind/doc/man/named.8 b/contrib/bind/doc/man/named.8 index b07dc7a..c0e73df 100644 --- a/contrib/bind/doc/man/named.8 +++ b/contrib/bind/doc/man/named.8 @@ -68,7 +68,7 @@ .Pc .Ar config_file .Oc -.Op Fl f q r +.Op Fl f q r v .Op Fl u Ar user_name .Op Fl g Ar group_name .Op Fl t Ar directory @@ -189,6 +189,8 @@ This option can be overridden by and is deprecated in favor of the clause of the configuration file's .Dq Li options statement. +.It Fl v +Report the version and exit. .It Fl u Ar user_name Specifies the user the server should run as after it initializes. The value specified may be either a username or a numeric user id. If the @@ -232,6 +234,7 @@ records for objects in the zone of the forms: .Bd -literal -offset indent $INCLUDE <filename> <opt_domain> $ORIGIN <domain> +$TTL <ttl> <domain> <opt_ttl> <opt_class> <type> <resource_record_data> .Ed .Pp @@ -261,10 +264,14 @@ Neither the field nor .Li $ORIGIN statements in the included file modify the current origin for this file. +.It Ar ttl +A integer number that sets the default time-to-live for future records without +an explicit ttl. .It Ar opt_ttl An optional integer number for the time-to-live field. -It defaults to zero, meaning the minimum value specified in the SOA -record for the zone. +If not set the ttl is taken from the last $TTL statement. +If no $TTL statement has occured then the SOA minimum value is used and a +warning is generated. .It Ar opt_class The object address type; currently only one type is supported, .Dv IN , @@ -286,7 +293,8 @@ the canonical name for an alias (domain) .It Dv SOA marks the start of a zone of authority (domain of originating host, domain address of maintainer, a serial number and the following -parameters in seconds: refresh, retry, expire and minimum TTL (see RFC 883)). +parameters in seconds: refresh, retry, expire and minimum TTL (see RFC 883 +and RFC 2308)). .It Dv NULL a null resource record (no format or data) .It Dv RP @@ -342,9 +350,7 @@ the new data. If a master server cannot be contacted when a refresh is due, the retry time specifies the interval at which refreshes should be attempted. If a master server cannot be contacted within the interval given by the expire time, all data from the zone is discarded by secondary servers. The -minimum value is the time-to-live -.Pq Dq TTL -used by records in the file with no explicit time-to-live value. +minimum value is the cache time-to-live for negative answers (RFC 2308). .Sh NOTES The boot file directives .Dq Li domain @@ -389,9 +395,7 @@ Dumps the profiling data in .Pa /var/tmp if the server is compiled with profiling (server forks, chdirs and exits). .It Dv SIGTERM -Dumps the primary and secondary database files. -Used to save modified data on shutdown if the -server is compiled with dynamic updating enabled. +Saves any modified dynamic zones to the file system, and shuts down the server. .It Dv SIGUSR1 Turns on debugging; each .Dv SIGUSR1 @@ -433,4 +437,5 @@ nameserver statistics data .Xr resolver @FORMAT_EXT@ , .Xr signal @SYSCALL_EXT@ , RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123, +RFC 2308 .Dq Name Server Operations Guide for Sy BIND diff --git a/contrib/bind/doc/man/named.conf.5 b/contrib/bind/doc/man/named.conf.5 new file mode 100644 index 0000000..44f1ec9 --- /dev/null +++ b/contrib/bind/doc/man/named.conf.5 @@ -0,0 +1,2355 @@ +.\" Copyright (c) 1999 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\" CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. + +.Dd January 7, 1999 +.Dt NAMED.CONF 5 +.Os BSD 4 + +.Sh NAME +.Nm named.conf +.Nd configuration file for +.Xr named 8 + +.Sh OVERVIEW + +BIND 8 is much more configurable than previous release of BIND. There +are entirely new areas of configuration, such as access control lists +and categorized logging. Many options that previously applied to all +zones can now be used selectively. These features, plus a +consideration of future configuration needs led to the creation of a +new configuration file format. + +.Ss General Syntax + +A BIND 8 configuration consists of two general features, statements +and comments. All statements end with a semicolon. Many statements +can contain substatements, which are each also terminated with a +semicolon. + +.Pp +The following statements are supported: +.Bl -tag -width 1 +.It Ic logging +specifies what the server logs, and where the log messages are sent + +.It Ic options +controls global server configuration options and sets defaults for other +statements + +.It Ic zone +defines a zone + +.It Ic acl +defines a named IP address matching list, for access control and other uses + +.It Ic key +specifies key information for use in authentication and authorization + +.It Ic trusted-keys +defines DNSSEC keys that are preconfigured into the server and implicitly +trusted + +.It Ic server +sets certain configuration options for individual remote servers + +.It Ic controls +declares control channels to be used by the +.Nm ndc +utility + +.It Ic include +includes another file + +.El + +The +.Ic logging +and +.Ic options +statements may only occur once per configuration, while the rest may +appear numerous times. Further detail on each statement is provided +in individual sections below. + +Comments may appear anywhere that whitespace may appear in a BIND +configuration file. To appeal to programmers of all kinds, they can +be written in C, C++, or shell/perl constructs. + +C-style comments start with the two characters +.Li /* +(slash, star) and end with +.Li */ +(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 +.Li */ : + +.Bd -literal -offset indent +/* 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. */ +.Ed + +C++-style comments start with the two characters +.Li // +(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 +.Li // +pair. For example: + +.Bd -literal -offset indent +// This is the start of a comment. The next line +// is a new comment, even though it is logically +// part of the previous comment. +.Ed + +Shell-style (or perl-style, if you prefer) comments start with the +character +.Li # +(hash or pound or number or octothorpe or whatever) and continue to +the end of the physical line, like C++ comments. For example: + +.Bd -literal -offset indent +# This is the start of a comment. The next line +# is a new comment, even though it is logically +# part of the previous comment. +.Ed + +.Em WARNING: +you cannot use the +.Li ; +(semicolon) character to start a comment such as you would in a zone +file. The semicolon indicates the end of a configuration statement, +so whatever follows it will be interpreted as the start of the next +statement. + +.Ss Converting from BIND 4.9.x + +.Pp +BIND 4.9.x configuration files can be converted to the new format +by using +.Pa src/bin/named/named-bootconf , +a shell script that is part of the BIND 8.2.x source kit. + +.Sh DOCUMENTATION DEFINITIONS + +Described below are elements used throughout the BIND configuration +file documentation. Elements which are only associated with one +statement are described only in the section describing that statement. + +.Bl -tag -width 1 +.It Va acl_name +The name of an +.Va address_match_list +as defined by the +.Ic acl +statement. + +.It Va address_match_list +A list of one or more +.Va ip_addr , +.Va ip_prefix , +.Va key_id , +or +.Va acl_name +elements, as described in the +.Sx ADDRESS MATCH LISTS +section. + +.It Va dotted-decimal +One or more integers valued 0 through 255 separated only by dots +(``.''), such as +.Li 123 , +.Li 45.67 +or +.Li 89.123.45.67 . + +.It Va domain_name +A quoted string which will be used as a DNS name, for example +.Qq Li my.test.domain . + +.It Va path_name +A quoted string which will be used as a pathname, such as +.Qq Li zones/master/my.test.domain . + +.It Va ip_addr +An IP address in with exactly four elements in +.Va dotted-decimal +notation. + +.It Va ip_port +An IP port +.Va number . +.Va number is limited to +.Li 0 +through +.Li 65535 , +with values below 1024 typically restricted to +root-owned processes. In some cases an asterisk (``*'') character +can be used as a placeholder to select a random high-numbered port. + +.It Va ip_prefix +An IP network specified in +.Va dotted-decimal +form, followed by ``/'' +and then the number of bits in the netmask. E.g. +.Li 127/8 +is +the network +.Li 127.0.0.0 +with netmask +.Li 255.0.0.0 . +.Li 1.2.3.0/28 +is network +.Li 1.2.3.0 +with netmask +.Li 255.255.255.240. + +.It Va key_name +A string representing the name of a shared key, to be used for transaction +security. + +.It Va number +A non-negative integer with an entire range limited by the range of a +C language signed integer (2,147,483,647 on a machine with 32 bit +integers). Its acceptable value might further be limited by the +context in which it is used. + +.It Va size_spec +A +.Va number , +the word +.Li unlimited , +or the word +.Li default . + +.Pp +The maximum value of +.Va size_spec +is that of unsigned long integers on the machine. +.Li unlimited +requests unlimited use, or the maximum available amount. +.Li default +uses the limit that was in force when the server was started. + +.Pp +A +.Va number +can optionally be followed by a scaling factor: +.Li K +or +.Li k +for kilobytes, +.Li M +or +.Li m +for megabytes, and +.Li G +or +.Li g +for gigabytes, which scale by 1024, 1024*1024, and 1024*1024*1024 +respectively. + +.Pp +Integer storage overflow is currently silently ignored during +conversion of scaled values, resulting in values less than intended, +possibly even negative. Using +.Li unlimited +is the best way to safely set a really large number. + +.It Va yes_or_no +Either +.Li yes +or +.Li no . +The words +.Li true +and +.Li false +are also accepted, as are the numbers +.Li 1 and +.Li 0 . + +.El + +.Sh ADDRESS MATCH LISTS +.Ss Syntax + +.Bd -literal +\fIaddress_match_list\fR = 1\&*\fIaddress_match_element\fR + +\fIaddress_match_element\fR = [ \&"!\&" ] ( \fIaddress_match_list\fR / + \fIip_address\fR / \fIip_prefix\fR / + \fIacl_name\fR / \&"key \&" \fIkey_id\fR ) \&";\&" +.Ed + +.Ss Definition and Usage + +Address match lists are primarily used to determine access control for +various server operations. They are also used to define priorities +for querying other nameservers and to set the addresses on which +.Nm named +will listen for queries. +The elements which constitute an address match list can be any +of the following: + +.Bl -bullet +.It +an +.Va ip-address +(in +.Va dotted-decimal +notation, +.It +an +.Va ip-prefix +(in the '/'-notation), +.It +A +.Va key_id , +as defined by the +.Ic key +statement, +.It +the name of an address match list previously defined with +the +.Ic acl +statement, or +.It +another +.Va address_match_list . +.El + +.Pp +Elements can be negated with a leading exclamation mark (``!''), and +the match list names +.Li any , +.Li none , +.Li localhost +and +.Li localnets +are predefined. More information on those names can be found in the +description of the +.Ic acl +statement. + +.Pp +The addition of the +.Ic 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. + +.Pp +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 +.Ic listen-on +ports, or as a topology, and whether the element was +negated. + +.Pp +When used as an access control list, a non-negated match allows access +and a negated match denies access. If there is no match at all in the +list, access is denied. The clauses +.Ic allow-query , +.Ic allow-transfer , +.Ic allow-update , +.Ic allow-recursion , +and +.Ic blackhole +all use address match lists like this. Similarly, the +.Ic listen-on +option will cause the server to not accept queries on any of the +machine's addresses which do not match the list. + +.Pp +When used with the +.Ic topology +option, a non-negated match returns a distance based on its position on +the list (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. + +.Pp +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 +.Dl 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 +.Dl !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. + +.Sh THE LOGGING STATEMENT +.Ss Syntax + +.Bd -literal +logging { + [ channel \fIchannel_name\fR { + ( file \fIpath_name\fR + [ versions ( \fInumber\fR | unlimited ) ] + [ size \fIsize_spec\fR ] + | syslog ( kern | user | mail | daemon | auth | syslog | lpr | + news | uucp | cron | authpriv | ftp | + local0 | local1 | local2 | local3 | + local4 | local5 | local6 | local7 ) + | null ); + + [ severity ( critical | error | warning | notice | + info | debug [ \fIlevel\fR ] | dynamic ); ] + [ print-category \fIyes_or_no\fR; ] + [ print-severity \fIyes_or_no\fR; ] + [ print-time \fIyes_or_no\fR; ] + }; ] + + [ category \fIcategory_name\fR { + \fIchannel_name\fR; [ \fIchannel_name\fR; ... ] + }; ] + ... +}; +.Ed + +.Ss Definition and Usage + +The +.Ic logging +statement configures a wide variety of logging options for the nameserver. +Its +.Ic channel +phrase associates output methods, format options and +severity levels with a name that can then be used with the +.Ic category +phrase to select how various classes of messages are logged. + +.Pp +Only one +.Ic logging +statement is used to define as many channels and categories as are wanted. +If there are multiple logging statements in a configuration, the first +defined determines the logging, and warnings are issued for the +others. If there is no logging statement, the logging configuration +will be: + +.Bd -literal + logging { + category default { default_syslog; default_debug; }; + category panic { default_syslog; default_stderr; }; + category packet { default_debug; }; + category eventlib { default_debug; }; + }; +.Ed + +The logging configuration is established as soon as the +.Ic logging +statement is parsed. If you want to redirect +messages about processing of the entire configuration file, the +.Ic logging +statement must appear first. Even if you do not +redirect configuration file parsing messages, we recommend +always putting the +.Ic logging +statement first so that this rule need not be consciously recalled if +you ever do need want the parser's messages relocated. + +.Ss The channel phrase + +All log output goes to one or more ``channels''; you can make as many +of them as you want. + +.Pp +Every channel definition must include a clause that says whether +messages selected for the channel go to a file, to a particular syslog +facility, or are discarded. It can optionally also limit the message +severity level that will be accepted by the channel (default is +.Li info ) , +and whether to include a time stamp generated by +.Nm named , +the category name, or severity level. The default is not to include +any of those three. + +.Pp +The word +.Li null +as the destination option for the +channel will cause all messages sent to it to be discarded; other +options for the channel are meaningless. + +.Pp +The +.Ic file +clause 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. + +.Pp +The +.Ic size +option for files is simply a hard ceiling on +log growth. If the file ever exceeds the size, then +.Nm named +will just not write anything more to it until the file is reopened; +exceeding the size does not automatically trigger a reopen. The +default behavior is to not limit the size of the file. + +.Pp +If you use the +.Ic version +logfile option, then +.Nm 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 lames.log.2, lamers.log.0 is renamed to +lamers.log.1, and lamers.log is renamed to lamers.log.0. No rolled +versions are kept by default; any existing log file is simply appended. +The +.Li unlimited +keyword is synonymous with +.Li 99 +in current BIND releases. Example usage of size and versions options: + +.Bd -literal + channel an_example_level { + file "lamers.log" versions 3 size 20m; + print-time yes; + print-category yes; + }; +.Ed + +.Pp +The argument for the +.Ic syslog +clause is a syslog facility as described in the +.Xr syslog 3 +manual page. How +.Nm syslogd +will handle messages sent to this facility is described in the +.Xr syslog.conf 5 +manual page. If you have a system which uses a very old version of +syslog that only uses two arguments to the +.Fn openlog() +function, then this clause is silently ignored. + +.Pp +The +.Ic 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. + +.Pp +If you are using syslog, then the +.Pa syslog.conf +priorities will also determine what eventually passes through. +For example, defining a channel facility and severity as +.Li daemon +and +.Li debug +but only logging +.Li daemon.warning +via +.Pa syslog.conf +will cause messages of severity +.Li info +and +.Li notice +to be dropped. If the situation were reversed, with +.Nm named +writing messages of only +.Li warning +or higher, then +.Nm syslogd +would print all messages it received from the channel. + +.Pp +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 +.Nm named +server with the +.Fl d +flag followed by a positive integer, or by sending the running server the +.Dv SIGUSR1 +signal (for example, by using +.Ic ndc trace ) . +The global debug level can be set to +zero, and debugging mode turned off, by sending the server the +.Dv SIGUSR2 +signal (as with +.Ic ndc notrace ) . +All debugging messages in the server have a +debug level, and higher debug levels give more more detailed output. +Channels that specify a specific debug severity, e.g. + +.Bd -literal + channel specific_debug_level { + file \&"foo\&"; + severity debug 3; + }; +.Ed + +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 +.Li dynamic +severity use the server's global level to determine what messages to +print. + +.Pp +If +.Ic print-time +has been turned on, then the date and time will be logged. +.Ic print-time +may be specified for a syslog channel, but is usually pointless since +syslog also prints the date and time. +If +.Ic print-category +is requested, then the category of the message will be logged as well. +Finally, if +.Ic print-severity +is on, then the severity level of the message will be logged. The +.Ic 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 +.Ic print- +options are on: + +.Bd -literal + 28-Apr-1997 15:05:32.863 default: notice: Ready to answer queries. +.Ed + +.Pp +There are four predefined channels that are used for +.Nm named 's +default logging as follows. How they are used +used is described in the next section, +.Sx The category phrase. + +.Bd -literal + channel default_syslog { + syslog daemon; # send to syslog's daemon facility + severity info; # only send priority info and higher + }; + + channel default_debug { + file \&"named.run\&"; # write to named.run in the working directory + # Note: stderr is used instead of \&"named.run\&" + # if the server is started with the -f option. + severity dynamic; # log at the server's current debug level + }; + + channel default_stderr { # writes to stderr + file \&"<stderr>\&"; # this is illustrative only; there's currently + # no way of specifying an internal file + # descriptor in the configuration language. + severity info; # only send priority info and higher + }; + + channel null { + null; # toss anything sent to this channel + }; +.Ed + +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. + +.Ss 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 +.Li default +category instead. +If you don't specify a default category, the following ``default +default'' is used: + +.Bd -literal + category default { default_syslog; default_debug; }; +.Ed + +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: + +.Bd -literal + channel my_security_channel { + file \&"my_security_file\&"; + severity info; + }; + category security { my_security_channel; + default_syslog; default_debug; }; +.Ed + +To discard all messages in a category, specify the +.Li null +channel: + +.Bd -literal + category lame-servers { null; }; + category cname { null; }; +.Ed + +The following categories are available: + +.Bl -tag -width 1 +.It Ic default +The catch-all. Many things still aren't classified into categories, +and they all end up here. Also, if you don't specify any channels for +a category, the default category is used instead. If you do not +define the default category, the following definition is used: +.Dl category default { default_syslog; default_debug; }; + +.It Ic config +High-level configuration file processing. + +.It Ic parser +Low-level configuration file processing. + +.It Ic queries +A short log message is generated for every query the server receives. + +.It Ic lame-servers +Messages like ``Lame server on ...'' + +.It Ic statistics +Statistics. + +.It Ic panic +If the server has to shut itself down due to an internal problem, it +will log the problem in this category as well as in the problem's native +category. If you do not define the panic category, the following definition +is used: +.Dl category panic { default_syslog; default_stderr; }; + +.It Ic update +Dynamic updates. + +.It Ic ncache +Negative caching. + +.It Ic xfer-in +Zone transfers the server is receiving. + +.It Ic xfer-out +Zone transfers the server is sending. + +.It Ic db +All database operations. + +.It Ic eventlib +Debugging info from the event system. Only one channel may be specified for +this category, and it must be a file channel. If you do not define the +eventlib category, the following definition is used: +.Dl category eventlib { default_debug; }; + +.It Ic packet +Dumps of packets received and sent. Only one channel may be specified for +this category, and it must be a file channel. If you do not define the +packet category, the following definition is used: +.Dl category packet { default_debug; }; + +.It Ic notify +The NOTIFY protocol. + +.It Ic cname +Messages like ``... points to a CNAME''. + +.It Ic security +Approved/unapproved requests. + +.It Ic os +Operating system problems. + +.It Ic insist +Internal consistency check failures. + +.It Ic maintenance +Periodic maintenance events. + +.It Ic load +Zone loading messages. + +.It Ic response-checks +Messages arising from response checking, such as +``Malformed response ...'', ``wrong ans. name ...'', +``unrelated additional info ...'', ``invalid RR type ...'', +and ``bad referral ...''. + +.El + +.Sh THE OPTIONS STATEMENT +.Ss Syntax + +.Bd -literal +options { + [ version \fIversion_string\fR; ] + [ directory \fIpath_name\fR; ] + [ named-xfer \fIpath_name\fR; ] + [ dump-file \fIpath_name\fR; ] + [ memstatistics-file \fIpath_name\fR; ] + [ pid-file \fIpath_name\fR; ] + [ statistics-file \fIpath_name\fR; ] + [ auth-nxdomain \fIyes_or_no\fR; ] + [ deallocate-on-exit \fIyes_or_no\fR; ] + [ dialup \fIyes_or_no\fR; ] + [ fake-iquery \fIyes_or_no\fR; ] + [ fetch-glue \fIyes_or_no\fR; ] + [ has-old-clients \fIyes_or_no\fR; ] + [ host-statistics \fIyes_or_no\fR; ] + [ multiple-cnames \fIyes_or_no\fR; ] + [ notify \fIyes_or_no\fR; ] + [ recursion \fIyes_or_no\fR; ] + [ rfc2308-type1 \fIyes_or_no\fR; ] + [ use-id-pool \fIyes_or_no\fR; ] + [ treat-cr-as-space \fIyes_or_no\fR; ] + [ also-notify \fIyes_or_no\fR; ] + [ forward ( only | first ); ] + [ forwarders { [ \fIin_addr\fR ; [ \fIin_addr\fR ; ... ] ] }; ] + [ check-names ( master | slave | response ) ( warn | fail | ignore); ] + [ allow-query { \fIaddress_match_list\fR }; ] + [ allow-recursion { \fIaddress_match_list\fR }; ] + [ allow-transfer { \fIaddress_match_list\fR }; ] + [ blackhole { \fIaddress_match_list\fR }; ] + [ listen-on [ port \fIip_port\fR ] { \fIaddress_match_list\fR }; ] + [ query-source [ address ( \fIip_addr\fR | * ) ] + [ port ( \fIip_port\fR | * ) ] ; ] + [ lame-ttl \fInumber\fR; ] + [ max-transfer-time-in \fInumber\fR; ] + [ max-ncache-ttl \fInumber\fR; ] + [ min-roots \fInumber\fR; ] + [ serial-queries \fInumber\fR; ] + [ transfer-format ( one-answer | many-answers ); ] + [ transfers-in \fInumber\fR; ] + [ transfers-out \fInumber\fR; ] + [ transfers-per-ns \fInumber\fR; ] + [ transfer-source \fIip_addr\fR; ] + [ maintain-ixfr-base \fIyes_or_no\fR; ] + [ max-ixfr-log-size \fInumber\fR; ] + [ coresize \fIsize_spec\fR ; ] + [ datasize \fIsize_spec\fR ; ] + [ files \fIsize_spec\fR ; ] + [ stacksize \fIsize_spec\fR ; ] + [ cleaning-interval \fInumber\fR; ] + [ heartbeat-interval \fInumber\fR; ] + [ interface-interval \fInumber\fR; ] + [ statistics-interval \fInumber\fR; ] + [ topology { \fIaddress_match_list\fR }; ] + [ sortlist { \fIaddress_match_list|fR }; ] + [ rrset-order { \fIorder_spec\fR ; [ \fIorder_spec\fR ; ... [ [ }; +}; +.Ed + +.Ss Definition and Usage + +The options statement sets up global options to be used by +BIND. This statement may appear at only once in a +configuration file; if more than one occurrence is found, the +first occurrence determines the actual options used, +and a warning will be generated. If there is no options statement, +an options block with each option set to its default will be used. + +.Ss Pathnames + +.Bl -tag -width 1 + +.It Ic version +The version the server should report via the ndc command or via a query of +name +.Pa version.bind +in class chaos. The default is the real version number of ths server, +but some server operators prefer the string ( +.Ic surely you must be joking +). + +.It Ic 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. +.Pa named.run ) +is this directory. If a directory is not +specified, the working directory defaults to +.Pa . , +the directory from which the +server was started. The directory specified should be an absolute path. + +.It Ic named-xfer +The pathname to the named-xfer program that the server uses for +inbound zone transfers. If not specified, the default is +system dependent (e.g. +.Pa /usr/sbin/named-xfer +). + +.It Ic dump-file +The pathname of the file the server dumps the database to when it +receives +.Dv SIGINT +signal (as sent by +.Ic ndc dumpdb +). If not specified, the default is +.Pa named_dump.db . + +.It Ic memstatistics-file +The pathname of the file the server writes memory usage statistics to +on exit, if +.Ic deallocate-on-exit +is +.Li yes . +If not specified, the default is +.Pa named.memstats . + +.It Ic pid-file +The pathname of the file the server writes its process ID in. If not +specified, the default is operating system dependent, but is usually +.Pa /var/run/named.pid +or +.Pa /etc/named.pid . +The pid-file is used by programs like +.Nm ndc +that want to send signals to the running nameserver. + +.It Ic statistics-file +The pathname of the file the server appends statistics to when it +receives +.Dv SIGILL +signal (from +.Ic ndc stats ) . +If not specified, the default is +.Pa named.stats . +.El + +.Ss Boolean Options + +.Bl -tag -width 1 +.It Ic auth-nxdomain +If +.Li yes , +then the +.Li AA +bit is always set on +.Dv NXDOMAIN +responses, even if the server is not actually authoritative. +The default is +.Li yes . +Do not turn off +.Ic auth-nxdomain +unless you are sure you know what you are +doing, as some older software won't like it. + +.It Ic deallocate-on-exit +If +.Li yes , +then when the server exits it will painstakingly deallocate every +object it allocated, and then write a memory usage report to the +.Ic memstatistics-file . +The default is +.Li no , +because it is faster to let the operating system clean up. +.Ic deallocate-on-exit +is handy for detecting memory leaks. + +.It Ic dialup +If +.Li 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 +.Ic heartbeat-interval +and hopefully during the one call. +It also suppresses some of the normal zone maintenance traffic. +The default is +.Li no . +The +.Ic dialup +option may also be specified in the +.Ic zone +statement, in which +case it overrides the +.Ic options dialup +statement. + +.Pp +If the zone is a +.Ic master +then the server will send out +.Dv NOTIFY +request to all the slaves. +This will trigger the zone up to date checking in the slave (providing +it supports +.Dv NOTIFY ) +allowing the slave +to verify the zone while the call us up. + +.Pp +If the zone is a +.Ic slave +or +.Ic stub +then the server will suppress the zone regular zone up to date queries +and only perform the when the +.Ic heartbeat-interval +expires. + +.It Ic fake-iquery +If +.Li yes , +the server will simulate the obsolete DNS query type +.Dv IQUERY . +The default is +.Li no . + +.It Ic fetch-glue +If +.Li yes +(the default), the server will fetch ``glue'' resource +records it doesn't have when constructing the additional data section of +a response. +.Ic fetch-glue no +can be used in conjunction with +.Ic recursion no +to prevent the server's cache from growing or +becoming corrupted (at the cost of requiring more work from the client). + +.It Ic has-old-clients +Setting the option to +.Li yes , +is equivalent to setting the following three options: +.Ic auth-nxdomain yes ;, +.Ic maintain-ixfr-base yes ;, +and +.Ic rfc2308-type1 no ; +. The use of +.Ic has-old-clients +with +.Ic auth-nxdomain , +.Ic maintain-ixfr-base , +and +.Ic rfc2308-type1 +is order dependant. + +.It Ic host-statistics +If +.Li yes , +then statistics are kept for every host that the the nameserver +interacts with. The default is +.Li no . +.Em Note: +turning on +.Ic host-statistics +can consume huge amounts of memory. + +.It Ic maintain-ixfr-base +If +.Li yes , +statistics are kept for every host that the nameserver interacts with. The default is +.Li no . +.Em Note: +turning on +.Li host-statistics +can consume huge amounts of memory. + +.It Ic multiple-cnames +If +.Li yes , +then multiple CNAME resource records will be +allowed for a domain name. The default is +.Li no . +Allowing multiple CNAME records is against standards and is not recommended. +Multiple CNAME support is available because previous versions of BIND +allowed multiple CNAME records, and these records have been used for load +balancing by a number of sites. + +.It Ic notify +If +.Li yes +(the default), DNS NOTIFY messages are sent when a +zone the server is authoritative for changes. The use of NOTIFY +speeds convergence between the master and its slaves. Slave servers +that receive a NOTIFY message and understand it will contact the +master server for the zone and see if they need to do a zone transfer, and +if they do, they will initiate it immediately. The +.Ic notify +option may also be specified in the +.Ic zone +statement, in which case it overrides the +.Ic options notify +statement. + +.It Ic recursion +If +.Li 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 not on, the server will return a referral to the +client if it doesn't know the answer. The default is +.Li yes . +See also +.Ic fetch-glue +above. + +.It Ic rfc2308-type1 +If +.Li yes, +the server will send NS records along with the SOA record for negative +answers. You need to set this to no if you have an old BIND server using +you as a forwarder that does not understand negative answers which contain +both SOA and NS records or you have an old version of sendmail. The correct +fix is to upgrade the broken server or sendmail. The default is +.Li no . + +.It Ic use-id-pool +If +.Li yes, +the server will keep track of its own outstanding query ID's to avoid duplication +and increase randomness. This will result in 128KB more memory being consumed +by the server. The default is +.Li no . + +.It Ic treat-cr-as-space +If +.Li yes, +the server will treat CR characters the same way it treats a space +or tab. This may be necessary when loading zone files on a UNIX system +that were generated on an NT or DOS machine. The default is +.Li no . + + +.El + +.Ss Also-Notify + +.Ic also-notify + +Defines a global list of IP addresses that also get sent NOTIFY messages +whenever a fresh copy of the zone is loaded. This helps to ensure that copies of +the zones will quickly converge on ``stealth'' servers. If an +.Ic also-notify +list is given in a +.Ic zone +statement, it will override the +.Ic options also-notify +statement. When a +.Ic zone notify +statement is set to +.Ic no , +the IP addresses in +the global +.Ic also-notify +list will not get sent NOTIFY messages for that zone. +The default is the empty list (no global notification list). + +.Ss Forwarding + +.Pp +The forwarding facility can be used to create a large site-wide +cache on a few servers, reducing traffic over links to external +nameservers. 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. + +.Bl -tag -width 1 +.It Ic forward +This option is only meaningful if the +.Ic forwarders +list is +not empty. A value of +.Li first , +the default, causes the +server to query the forwarders first, and if that doesn't answer the +question the server will then look for the answer itself. If +.Li only +is specified, the server will only query the forwarders. + +.It Ic forwarders +Specifies the IP addresses to be used for forwarding. The default is the +empty list (no forwarding). +.El + +.Pp +Forwarding can also be configured on a per-zone basis, allowing for +the global forwarding options to be overridden in a variety of ways. +You can set particular zones to use different forwarders, or have +different +.Ic forward only/first +behavior, or to not forward +at all. See +.Sx THE ZONE STATEMENT +section for more information. + +.Pp +Future versions of BIND 8 will provide a more powerful forwarding +system. The syntax described above will continue to be supported. + +.Ss Name Checking + +The server can check domain names based upon their expected client contexts. +For example, a domain name used as a hostname can be checked for compliance +with the RFCs defining valid hostnames. + +.Pp +Three checking methods are available: + +.Bl -tag -width 1 +.It Ic ignore +No checking is done. + +.It Ic warn +Names are checked against their expected client contexts. Invalid names are +logged, but processing continues normally. + +.It Ic fail +Names are checked against their expected client contexts. Invalid names are +logged, and the offending data is rejected. +.El + +.Pp +The server can check names three areas: master zone files, slave +zone files, and in responses to queries the server has initiated. If +.Ic check-names response fail +has been specified, and +answering the client's question would require sending an invalid name +to the client, the server will send a +.Dv REFUSED +response code to the client. + +.Pp +The defaults are: + +.Bd -literal + check-names master fail; + check-names slave warn; + check-names response ignore; +.Ed + +.Pp +.Ic check-names +may also be specified in the +.Ic zone +statement, in which case it overrides the +.Ic options check-names +statement. When used in a +.Ic zone +statement, the area is not specified (because it can be deduced from +the zone type). + +.Ss Access Control + +.Pp +Access to the server can be restricted based on the IP address of the +requesting system or via shared secret keys. See +.Sx ADDRESS MATCH LISTS +for details on how to specify access criteria. + +.Bl -tag -width 1 +.It Ic allow-query +Specifies which hosts are allowed to ask ordinary questions. +.Ic allow-query +may also be specified in the +.Ic zone +statement, in which case it overrides the +.Ic options allow-query +statement. If not specified, the default is + +.Bl -tag -width 1 +.It Ic allow-recursion +Specifies which hosts are allowed to ask recursive questions. +.Ic allow-recursion +may also be specified in the +.Ic zone +statement, in which case it overrides the +.Ic options allow-recursion +statement. If not specified, the default is to allow recursive queries +from all hosts. + +.It Ic allow-transfer +Specifies which hosts are allowed to receive zone transfers from the +server. +.Ic allow-transfer +may also be specified in the +.Ic zone +statement, in which case it overrides the +.Ic options allow-transfer +statement. If not specified, the default +is to allow transfers from all hosts. + +.It Ic 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. +.El + +.Ss Interfaces + +.Pp +The interfaces and ports that the server will answer queries from may +be specified using the +.Ic listen-on +option. +.Ic 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. + +.Pp +Multiple +.Ic listen-on +statements are allowed. For example, + +.Bd -literal + listen-on { 5.6.7.8; }; + listen-on port 1234 { !1.2.3.4; 1.2/16; }; +.Ed + +will enable the nameserver 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. + +.Pp +If no +.Ic listen-on +is specified, the server will listen on port +53 on all interfaces. + +.Ss Query Address + +.Pp +If the server doesn't know the answer to a question, it will query +other nameservers. +.Ic query-source +specifies the address and port used for such queries. If +.Ic address +is +.Li * +or is omitted, a wildcard IP address +( +.Dv INADDR_ANY ) +will be used. If +.Va port +is +.Li * +or is omitted, a random unprivileged port will be used. +The default is +.Dl query-source address * port *; + +.Pp +Note: +.Ic query-source +currently applies only to UDP queries; +TCP queries always use a wildcard IP address and a random unprivileged +port. + +.Ss Zone Transfers + +.Bl -tag -width 1 +.It Ic max-transfer-time-in +Inbound zone transfers ( +.Nm named-xfer +processes) running +longer than this many minutes will be terminated. +The default is 120 minutes (2 hours). + +.It Ic transfer-format +The server supports two zone transfer methods. +.Li one-answer +uses one DNS message per resource record +transferred. +.Li many-answers +packs as many resource records +as possible into a message. +.Li many-answers +is more efficient, but is only known to be understood by BIND 8.1 and +patched versions of BIND 4.9.5. The default is +.Li one-answer . +.Ic transfer-format +may be overridden on a per-server basis by using the +.Ic server +statement. + +.It Ic transfers-in +The maximum number of inbound zone transfers that can be running +concurrently. The default value is 10. Increasing +.Ic transfers-in +may speed up the convergence of slave zones, +but it also may increase the load on the local system. + +.It Ic transfers-out +This option will be used in the future to limit the number of +concurrent outbound zone transfers. It is checked for syntax, but is +otherwise ignored. + +.It Ic transfers-per-ns +The maximum number of inbound zone transfers ( +.Nm named-xfer +processes) that can be concurrently transferring from a given remote +nameserver. The default value is 2. Increasing +.Ic transfers-per-ns +may speed up the convergence of slave zones, but it also may increase +the load on the remote nameserver. +.Ic transfers-per-ns +may be overridden on a per-server basis by using the +.Ic transfers +phrase of the +.Ic server +statement. + +.It Ic transfer-source +.Nm transfer-source +determines which local address will be bound to the TCP connection used to fetch all zones +transferred inbound by the server. 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 +.Nm allow-transfer +option for the zones being transferred, if one is specified. This statement sets the +.Nm transfer-source +for all zones, but can be overriden on a per-zone basis by includinga +.Nm transfer-source +statement within the zone block in the configuration file. +.El + +.Ss Resource Limits + +.Pp +The server's usage of many system resources can be limited. Some +operating systems don't support some of the limits. On such systems, +a warning will be issued if the unsupported limit is used. Some +operating systems don't support limiting resources, and on these systems +a +.D1 cannot set resource limits on this system +message will +be logged. + +.Pp +Scaled values are allowed when specifying resource limits. For +example, +.Li 1G +can be used instead of +.Li 1073741824 +to specify a limit of one gigabyte. +.Li unlimited +requests unlimited use, or the maximum +available amount. +.Li default +uses the limit that was in +force when the server was started. +See the definition of +.Va size_spec +in the +.Sx DOCUMENTATION DEFINITIONS +section for more details. + +.Bl -tag -width 1 +.It Ic coresize +The maximum size of a core dump. The default value is +.Li default . + +.It Ic datasize +The maximum amount of data memory the server may use. The default +value is +.Li default . + +.It Ic files +The maximum number of files the server may have open concurrently. +The default value is +.Li unlimited . +Note that on some operating systems the server cannot set an unlimited +value and cannot determine the maximum number of open files the kernel +can support. On such systems, choosing +.Li unlimited +will cause the server to use +the larger of the +.Va rlim_max +from +.Fn getrlimit RLIMIT_NOFILE +and the value returned by +.Fn sysconf _SC_OPEN_MAX . +If the +actual kernel limit is larger than this value, use +.Ic limit files +to specify the limit explicitly. + +.It Ic max-ixfr-log-size +The +.Li max-ixfr-log-size +will be used in a future release of the server to limit the size of the transaction +log kept for Incremental Zone Transfer. + +.It Ic stacksize +The maximum amount of stack memory the server may use. The default value is +.Li default . +.El + +.Ss Periodic Task Intervals + +.Bl -tag -width 1 +.It Ic cleaning-interval +The server will remove expired resource records from the cache every + +.Ic cleaning-interval +minutes. The default is 60 minutes. If set +to 0, no periodic cleaning will occur. + +.It Ic heartbeat-interval +The server will perform zone maintenance tasks for all zones marked +.Ic dialup yes +whenever this interval expires. +The default is 60 minutes. Reasonable values are up to 1 day (1440 minutes). +If set to 0, no zone maintenance for these zones will occur. + +.It Ic interface-interval +The server will scan the network interface list every +.Ic interface-interval +minutes. The default is 60 minutes. +If set to 0, interface scanning will only occur when the configuration +file is loaded. After the scan, listeners will be started on any new +interfaces (provided they are allowed by the +.Ic listen-on +configuration). Listeners on interfaces that have gone away will be +cleaned up. + +.It Ic statistics-interval +Nameserver statistics will be logged every +.Ic statistics-interval +minutes. The default is 60. If set to 0, no statistics will be logged. +.El + +.Ss Topology + +.Pp +All other things being equal, when the server chooses a nameserver +to query from a list of nameservers, it prefers the one that is +topologically closest to itself. The +.Ic 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, + +.Bd -literal + topology { + 10/8; + !1.2.3/24; + { 1.2/16; 3/8; }; + }; +.Ed + +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. + +.Pp +The default topology is +.Dl topology { localhost; localnets; }; + +.Ss Resource Record sorting + +.Pp +When returning multiple RRs, the nameserver will normally return them in +.Ic Round Robin , +i.e. after each request, the first RR is put to the end of the list. +As the order of RRs is not defined, this should not cause any problems. + +The client resolver code should re-arrange the RRs as appropriate, i.e. using +any addresses on the local net in preference to other addresses. However, not all +resolvers can do this, or are not 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 nameservers, +not all the clients. + +The +.Ic sortlist +statement takes an address match list and interprets it even more +specially than the +.Ictopology +statement does. + +Each top level statement in the sortlist must itself be an explicit address match +list with one or two elements. The first element (which may be an IP address, +an IP prefix, an ACL name or 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, +the second element is treated like 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. + +.Bd -literal +sortlist { + { localhost; // IF the local host + { localnets; // THEN first fit on the + 192.168.1/24; // following nets + { 192,168.2/24; 192.168.3/24; }; }; }; + { 192.168.1/24; // IF on class C 192.168.1 + { 192.168.1/24; // THEN use .1, or .2 or .3 + { 192.168.2/24; 192.168.3/24; }; }; }; + { 192.168.2/24; // IF on class C 192.168.2 + { 192.168.2/24; // THEN use .2, or .1 or .3 + { 192.168.1/24; 192.168.3/24; }; }; }; + { 192.168.3/24; // IF on class C 192.168.3 + { 192.168.3/24; // THEN use .3, or .1 or .2 + { 192.168.1/24; 192.168.2/24; }; }; }; + { { 192.168.4/24; 192.168.5/24; }; // if .4 or .5, prefer that net + }; +}; +.Ed + +The following example will give reasonable behaviour 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. + +.Bd -literal +sortlist { + { localhost; localnets; }; + { localnets; }; +}; +.Ed + +.Ss RRset Ordering + +.Pp +When multiple records are returned in an answer it may be useful to configure +the order the records are placed into the response. For example the records for +a zone might be configured to always be returned in the order they are defined +in the zone file. Or perhaps a random shuffle of the records as they are +returned is wanted. The rrset-order statement permits configuration of the +ordering made of the records in a multiple record response. The default, if no +ordering is defined, is a cyclic ordering (round robin). + +An +.Ic order_spec +is defined as follows: + +.Bd -literal + [ \fIclass class_name\fR ][ \fItype type_name\fR ][ \fIname\fR "FQDN" ] \fIorder\fR ordering +.Ed + +If no class is specified, the default is +.Ic ANY . +If no +.Li Ictype +is specified, the default is +.Ic ANY . +If no name is specified, the default is "*". + +The legal values for +.Ic ordering +are: + +.Bd -literal +.Ic fixed + Records are returned in the order they are defined in the zone file. +.Ic random + Records are returned in some random order. +.Ic cyclic + Records are returned in a round-robin order. + +For example: + + rrset-order { + class IN type A name "rc.vix.com" order random; + order cyclic; + }; +.Ed + +will cause any responses for type A records in class IN that have "rc.vix.com" as +a suffix, to always be returned in random order. All other records are returned +in cyclic order. + +If multiple +.Ic rrset-order +statements appear, they are not combined--the last one applies. + +If no +.Ic rrset-order +statement is specified, a default one of: + +.Bd -literal + rrset-order { class ANY type ANY name "*" order cyclic ; }; +.Ed + +is used. + +.Ss Tuning + +.Bl -tag -width 1 +.It Ic lame-ttl +Sets the number of seconds to cache a lame server indication. 0 disables +caching. Default is 600 (10 minutes). Maximum value is 1800 (30 minutes) +.It Ic max-ncache-ttl +To reduce network traffic and increase performance the server store negative +answers. +.Ic max-ncache-ttl +is used to set a maximum retention time +for these answers in the server is seconds. The default +.Ic max-ncache-ttl +is 10800 seconds (3 hours). +.Ic max-ncache-ttl +cannot exceed the maximum retention time for ordinary (positive) +answers (7 days) and will be silently truncated to 7 days if set to a +value which is greater that 7 days. +.It Ic min-roots +The minimum number of root servers that is required for a request for the root +servers to be accepted. Default is 2. +.El + +.Sh THE ZONE STATEMENT +.Ss Syntax + +.Bd -literal +zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { + type master; + file \fIpath_name\fR; + [ check-names ( warn | fail | ignore ); ] + [ allow-update { \fIaddress_match_list\fR }; ] + [ allow-query { \fIaddress_match_list\fR }; ] + [ allow-transfer { \fIaddress_match_list\fR }; ] + [ dialup \fIyes_or_no\fR; ] + [ notify \fIyes_or_no\fR; ] + [ also-notify { \fIip_addr\fR; [ \fIip_addr\fR; ... ] }; + [ pubkey \fInumber\fR \fInumber\fR \fInumber\fR \fIstring\fR; ] +}; + +zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { + type ( slave | stub ); + [ file \fIpath_name\fR; ] + masters [ port \fIip_port\fR ] { \fIip_addr\fR; [ \fIip_addr\fR; ... ] }; + [ check-names ( warn | fail | ignore ); ] + [ allow-update { \fIaddress_match_list\fR }; ] + [ allow-query { \fIaddress_match_list\fR }; ] + [ allow-transfer { \fIaddress_match_list\fR }; ] + [ transfer-source \fIip_addr\fR; ] + [ max-transfer-time-in \fInumber\fR; ] + [ notify \fIyes_or_no\fR; ] + [ also-notify { \fIip_addr\fR; [ \fIip_addr\fR; ... ] }; + [ pubkey \fInumber\fR \fInumber\fR \fInumber\fR \fIstring\fR; ] +}; + +zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { + type forward; + [ forward ( only | first ); ] + [ forwarders { [ \fIip_addr\fR ; [ \fIip_addr\fR ; ... ] ] }; ] + [ check-names ( warn | fail | ignore ); ] +}; + +zone \&".\&" [ ( in | hs | hesiod | chaos ) ] { + type hint; + file \fIpath_name\fR; + [ check-names ( warn | fail | ignore ); ] +}; +.Ed + +.Ss Definition and Usage + +The +.Ic zone +statement is used to define how information about particular DNS zones +is managed by the server. There are five different zone types. + +.Bl -tag -width 1 +.It Ic master +The server has a master copy of the data for the zone and will be able +to provide authoritative answers for it. + +.It Ic slave +A +.Ic slave +zone is a replica of a master zone. The +.Ic masters +list specifies one or more IP addresses that the slave contacts to +update its copy of the zone. If a +.Ic port +is specified then checks to see if the zone is current and zone transfers +will be done to the port given. If +.Ic file +is specified, then the replica will be written to the named file. +Use of the +.Ic file +clause is highly recommended, since it often speeds server startup +and eliminates a needless waste of bandwidth. + +.It Ic stub +A +.Ic stub +zone is like a slave zone, except that it replicates +only the NS records of a master zone instead of the entire zone. + +.It Ic forward +A +.Ic forward +zone is used to direct all queries in it to other servers, as described in +.Sx THE OPTIONS STATEMENT +section. The specification of options in such a zone will override +any global options declared in the +.Ic options +statement. + +.Pp +If either no +.Ic forwarders +clause is present in the zone or an empty list for +.Ic forwarders +is given, then no forwarding will be done for the zone, cancelling the +effects of any +.Ic forwarders +in the +.Ic options +statement. +Thus if you want to use this type of zone to change only the behavior of +the global +.Ic forward +option, and not the servers used, then you also need to respecify the +global forwarders. + +.It Ic hint +The initial set of root nameservers is specified using a +.Ic hint +zone. When the server starts up, it uses the root hints +to find a root nameserver and get the most recent list of root nameservers. +.El + +.Pp +Note: previous releases of BIND used the term +.Ic primary +for a master zone, +.Ic secondary +for a slave zone, and +.Ic cache +for a hint zone. + +.Ss Classes + +The zone's name may optionally be followed by a class. If a class is not +specified, class +.Ic in +(for "internet"), is assumed. This is correct for the vast majority +of cases. + +.Pp +The +.Ic hesiod +class is 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. More information can be found at +ftp://athena-dist.mit.edu/pub/ATHENA/usenix/athena_changes.PS. +The keyword +.Ic hs +is a synonym for +.Ic hesiod . + +.Pp +Another MIT development was CHAOSnet, a LAN protocol created in the +mid-1970s. It is still sometimes seen on LISP stations and other +hardware in the AI community, and zone data for it can be specified +with the +.Ic chaos +class. + +.Ss Options + +.Bl -tag -width 1 +.It Ic check-names +See the subsection on +.Sx Name Checking +in +.Sx THE OPTIONS STATEMENT . + +.It Ic allow-query +See the description of +.Ic allow-query +in the +.Sx Access Control +subsection of +.Sx THE OPTIONS STATEMENT . + +.It Ic allow-update +Specifies which hosts are allowed to submit Dynamic DNS updates to the +server. The default is to deny updates from all hosts. + +.It Ic allow-transfer +See the description of +.Ic allow-transfer +in the +.Sx Access Control +subsection of +.Sx THE OPTIONS STATEMENT . + +.It Ic transfer-source +.Ic transfer-source +determines which local address will be bound to the TCP connection +used to fetch this zone. 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 +.Ic allow-transfer +option for this zone if one is specified. + +.It Ic max-transfer-time-in +See the description of +.Ic max-transfer-time-in +in the +.Sx Zone Transfers +subsection of +.Sx THE OPTIONS STATEMENT . + +.It Ic dialup +See the description of +.Ic dialup +in the +.Sx Boolean Options +subsection of +.Sx THE OPTIONS STATEMENT . + +.It Ic notify +See the description of +.Sx notify +in the +.Sx Boolean Options +subsection of the +.Sx THE OPTIONS STATEMENT . + +.It Ic also-notify +.Ic also-notify +is only meaningful if +.Ic 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 nameservers for the zone (other than +the primary master) plus any IP addresses specified with +.Ic also-notify . +.Ic also-notify +is not meaningful for +.Ic stub +zones. The default is the empty list. + +.It Ic forward +.Ic forward +is only meaningful if the zone has a +.Ic forwarders +list. The +.Ic only +value causes the lookup to fail after trying the +.Ic forwarders +and getting no answer, while +.Ic first +would allow a normal lookup to be tried. + +.It Ic forwarders +The +.Ic forwarders +option in a zone is used to override the list of global forwarders. +If it is not specified in a zone of type +.Ic forward , +.Em no +forwarding is done for the zone; the global options are not used. + +.It Ic pubkey +The DNSSEC flags, protocol, and algorithm are specified, as well as a base-64 +encoded string representing the key. +.El + +.Sh THE ACL STATEMENT +.Ss Syntax + +.Bd -literal +acl \fIname\fR { + \fIaddress_match_list\fR +}; +.Ed + +.Ss Definition and Usage + +The +.Ic acl +statement creates a named address match list. +It gets its name from a primary use of address match lists: Access +Control Lists (ACLs). + +.Pp +Note that an address match list's name must be defined with +.Ic acl +before it can be used elsewhere; no forward +references are allowed. + +.Pp +The following ACLs are built-in: + +.Bl -tag -width 1 +.It Ic any +Allows all hosts. +.It Ic none +Denies all hosts. +.It Ic localhost +Allows the IP addresses of all interfaces on the system. +.It Ic localnets +Allows any host on a network for which the system has an interface. +.El + +.Sh THE KEY STATEMENT +.Ss Syntax + +.Bd -literal +key \fIkey_id\fR { + algorithm \fIalgorithm_id\fR; + secret \fIsecret_string\fR; +}; +.Ed + +.Ss Definition and Usage + +The +.Ic key +statement defines a key ID which can be used in a +.Ic server +statement to associate a method of authentication with a particular +name server that is more rigorous than simple IP address matching. +A key ID must be created with the +.Ic key +statement before it can be used in a +.Ic server +definition or an address match list. + +.Pp +The +.Va algorithm_id +is a string that specifies a +security/authentication algorithm. +.Va secret_string +is the secret to be used by the algorithm, +and is treated as a base-64 encoded string. +It should go without saying, but probably can't, +that if you have +.Va secret_string 's +in your +.Pa named.conf , +then it should not be readable by anyone but the superuser. + +.Sh THE TRUSTED-KEYS STATEMENT +.Ss Syntax + +.Bd -literal +trusted-keys { + [ \fIdomain_name\fR \fIflags\fR \fIprotocol\fR \fIalgorithm\fR \fIkey\fR; ] +}; +.Ed + +.Ss Definition and Usage + +The +.Ic trusted-keys +statement is for use with DNSSEC-style security, originally specified +in RFC 2065. DNSSEC is meant to +provide three distinct services: key distribution, data origin +authentication, and transaction and request authentication. A +complete description of DNSSEC and its use is beyond the scope of this +document, and readers interested in more information should start with +RFC 2065 and then continue with the Internet Drafts available at +http://www.ietf.org/ids.by.wg/dnssec.html. + +.Pp +Each trusted key is associated with a domain name. Its attributes are +the non-negative integral +.Va flags , +.Va protocol , +and +.Va algorithm , +as well as a base-64 encoded string representing the +.Va key . + +.Pp +Any number of trusted keys can be specified. + +.Sh THE SERVER STATEMENT +.Ss Syntax + +.Bd -literal +server \fIip_addr\fR { + [ bogus \fIyes_or_no\fR; ] + [ transfers \fInumber\fR; ] + [ transfer-format ( one-answer | many-answers ); ] + [ keys { \fIkey_id\fR [ \fIkey_id\fR ... ] }; ] +}; +.Ed + +.Ss Definition and Usage + +The server statement defines the characteristics to be +associated with a remote name server. + +.Pp +If you discover that a server is giving out bad data, marking it as +.Ic bogus +will prevent further queries to it. The default value of +.Ic bogus +is +.Li no . + +.Pp +The server supports two zone transfer methods. The first, +.Ic one-answer , +uses one DNS message per resource record transferred. +.Ic many-answers +packs as many resource records as possible into a message. +.Ic many-answers +is more efficient, but is only known to be understood by BIND 8.1 and +patched versions of BIND 4.9.5. You can specify which method to use +for a server with the +.Ic transfer-format +option. If +.Ic transfer-format +is not specified, the +.Ic transfer-format +specified by the +.Ic options +statement will be used. + +.Pp +The +.Ic transfers +will be used in a future release of the server to limit the number of +concurrent in-bound zone transfers from the specified server. It is +checked for syntax but is otherwise ignored. + +.Pp +The +.Ic keys +clause is used to identify a +.Va key_id +defined by the +.Ic key +statement, to be used for transaction security when talking to the +remote server. +The +.Ic key +statememnt must come before the +.Ic server +statement that references it. + +.Pp +The +.Ic keys +statement is intended for future use by the +server. It is checked for syntax but is otherwise ignored. + +.Sh THE CONTROLS STATEMENT +.Ss Syntax + +.Bd -literal +controls { + [ inet \fIip_addr\fR + port \fIip_port\fR + allow { \fIaddress_match_list\fR; }; ] + [ unix \fIpath_name\fR + perm \fInumber\fR + owner \fInumber\fR + group \fInumber\fR; ] +}; +.Ed + +.Ss Definition and Usage + +The +.Ic controls +statement declares control channels to be used by system +administrators to affect the operation of the local name server. +These control channels are used by the +.Nm ndc +utility to send commands +to and retrieve non-DNS results from a name server. + +.Pp +A +.Ic unix +control channel is a FIFO in the file system, and access to it is +controlled by normal file system permissions. It is created by +.Nm named +with the specified file mode bits (see +.Xr chmod 1 ) , +user and group owner. Note that, unlike +.Nm chmod , +the mode bits specified for +.Ic perm +will normally have a leading +.Li 0 +so the number is interpreted as octal. Also note that the user and +group ownership specified as +.Ic owner +and +.Ic group +must be given as numbers, not names. +It is recommended that the +permissions be restricted to administrative personnel only, or else any +user on the system might be able to manage the local name server. + +.Pp +An +.Ic inet +control channel is a TCP/IP socket accessible to the Internet, created +at the specified +.Va ip_port +on the specified +.Va ip_addr . +Modern +.Nm telnet +clients are capable of speaking directly to these +sockets, and the control protocol is ARPAnet-style text. +It is recommended that 127.0.0.1 be the only +.Va ip_addr +used, and this only if you trust all non-privileged users on the local +host to manage your name server. + +.Sh THE INCLUDE STATEMENT +.Ss Syntax + +.Bd -literal +include \fIpath_name\fR; +.Ed + +.Ss Definition and Usage + +The +.Ic include +statement inserts the specified file at the point that the +.Ic include +statement is encountered. It cannot be used within another statement, +though, so a line such as +.Dl acl internal_hosts { include "internal_hosts.acl"; }; +is not allowed. + +.Pp +Use +.Ic include +to break the configuration up into easily-managed chunks. +For example: + +.Bd -literal +include "/etc/security/keys.bind"; +include "/etc/acls.bind"; +.Ed + +could be used at the top of a BIND configuration file in order to +include any ACL or key information. + +.Pp +Be careful not to type +``#include'', like you would in a C program, because +``#'' is used to start a comment. + +.Sh EXAMPLES + +The simplest configuration file that is still realistically useful is +one which simply defines a hint zone that has a full path to the root +servers file. +.Bd -literal +zone \&".\&" in { + type hint; + file \&"/var/named/root.cache\&"; +}; +.Ed + +Here's a more typical real-world example. + +.Bd -literal +/* + * A simple BIND 8 configuration + */ + +logging { + category lame-servers { null; }; + category cname { null; }; +}; + +options { + directory \&"/var/named\&"; +}; + +controls { + inet * port 52 allow { any; }; // a bad idea + unix \&"/var/run/ndc\&" perm 0600 owner 0 group 0; // the default +}; + +zone \&"isc.org\&" in { + type master; + file \&"master/isc.org\&"; +}; + +zone \&"vix.com\&" in { + type slave; + file \&"slave/vix.com\&"; + masters { 10.0.0.53; }; +}; + +zone \&"0.0.127.in-addr.arpa\&" in { + type master; + file \&"master/127.0.0\&"; +}; + +zone \&".\&" in { + type hint; + file \&"root.cache\&"; +}; +.Ed + +.Sh FILES +.Bl -tag -width 1 -compact +.It Pa /etc/named.conf +The BIND 8 +.Nm named +configuration file. +.El + +.Sh SEE ALSO +.Xr named 8 , +.Xr ndc 8 diff --git a/contrib/bind/doc/man/ndc.8 b/contrib/bind/doc/man/ndc.8 index 247ef96..a4645e6 100644 --- a/contrib/bind/doc/man/ndc.8 +++ b/contrib/bind/doc/man/ndc.8 @@ -1,142 +1,133 @@ -.\" Copyright (c) 1994 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. +.\" Copyright (c) 1998,1999 by Internet Software Consortium .\" -.Dd November 27, 1994 +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\" CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" +.Dd December 31, 1998 .Dt @INDOT_U@NDC @SYS_OPS_EXT_U@ .Os BSD 4 .Sh NAME -.Nm @INDOT@ndc -.Nd name daemon control interface +.Nm ndc +.Nd name daemon control program .Sh SYNOPSIS -.Nm @INDOT@ndc -.Ar directive -.Op Ar ... +.Nm ndc +.Op Fl c Ar channel +.Op Fl l Ar localsock +.Op Fl p Ar pidfile +.Op Fl d +.Op Fl q +.Op Fl s +.Op Fl t +.Op Ar command .Sh DESCRIPTION -This command allows the name server administrator to send various signals -to the name server, or to restart it. Zero or more directives may be given, -from the following list: -.Bl -tag -width "querylog" -.It Ic status -Displays the current status of -.Xr @INDOT@named @SYS_OPS_EXT@ -as shown by -.Xr ps @CMD_EXT@ . -.It Ic dumpdb -Causes -.Ic @INDOT@named -to dump its database and cache to -.Pa /var/tmp/named_dump.db -(uses the -.Dv INT -signal.) -.It Ic reload -Causes -.Ic @INDOT@named -to check the serial numbers of all primary and secondary zones -and to reload those that have changed (uses the -.Dv HUP -signal.) -.It Ic stats -Causes -.Ic @INDOT@named -to dump its statistics to -.Pa /var/tmp/named.stats -(uses the -.Dv IOT -or -.Dv ABRT -signal.) -.It Ic trace -Causes -.Ic @INDOT@named -to increment its -.Dq tracing level -by one. Whenever the tracing level -is nonzero, trace information will be written to -.Pa /var/tmp/named.run . -Higher tracing levels result in more detailed information. -(Uses the -.Dv USR1 -signal.) -.It Ic notrace -Causes -.Ic @INDOT@named -to set its -.Dq tracing level -to zero, closing -.Pa /var/tmp/named.run , -if it is open (uses the -.Dv USR2 -signal.) -.It Ic querylog -Causes -.Ic @INDOT@named -to toggle the -.Dq query logging -feature, which while on will result in a -.Xr syslog @SYSCALL_EXT@ -of each incoming query (uses the -.Dv WINCH -signal.) Note that query logging -consumes quite a lot of log file space. This directive may also be given as -.Ic qrylog . -.It Ic start -Causes -.Ic @INDOT@named -to be started, as long as it isn't already running. -.It Ic stop -Causes -.Ic @INDOT@named -to be stopped, if it is running. -.It Ic restart -Causes -.Ic @INDOT@named -to be killed and restarted. +This command allows the system administrator to control the operation +of a name server. If no +.Ar command +is given, +.Ic ndc +will prompt for commands until it reads EOF. +.Pp +Options are: +.Bl -tag -width Fl +.It Fl c Ar channel +Specifies the rendezvous point for the control channel. The default is +.Pa /var/run/ndc +(a UNIX domain socket which is also the server's default control channel). +If the desired control channel is a TCP/IP socket, then the format of the +.Ar channel +argument is +.Sy ipaddr/port +(for example, +.Sy 127.0.0.1/54 +would be TCP port 54 on the local host.) +.It Fl l Ar localsock +This option will +.Xr bind 2 +the client side of the control channel to a specific address. Servers can +be configured to reject connections which do not come from specific addresses. +The format is the same as for +.Ar channel +(see above). +.It Fl p Ar pidfile +For backward compatibility with older name servers, +.Ic ndc +is able to use UNIX signals for control communications. This capability is +optional in modern name servers and will disappear altogether at some future +time. Note that the available +.Ar command +set is narrower when the signal interface is used. A likely +.Ar pidfile +argument would be something like +.Pa /var/run/named.pid . +.It Fl d +Turns on debugging output, which is of interest mainly to developers. +.It Fl q +Suppresses prompts and result text. +.It Fl s +Suppresses nonfatal error announcements. +.It Fl t +Turns on protocol and system tracing, useful in installation debugging. .El -.Sh BUGS -Arguments to +.Sh COMMANDS +Several commands are built into +.Ic ndc , +but the full set of commands supported by the name server is dynamic and +should be discovered using the +.Ar help +command (see below). Builtin commands are: +.Bl -tag -width Fl +.It Ar /help +Provides help for builtin commands. +.It Ar /exit +Exit from +.Ic ndc +command interpreter. +.It Ar /trace +Toggle tracing (see +.Fl -t +description above). +.It Ar /debug +Toggle debugging (see +.Fl d +description above). +.It Ar /quiet +Toggle quietude (see +.Fl q +description above). +.It Ar /silent +Toggle silence (see +.Fl s +description above). +.El +.Sh NOTES +If running in +.Ar pidfile +mode, any arguments to +.Ar start +and +.Ar restart +commands are passed to the new .Ic @INDOT@named -are not preserved by -.Ic restart , -or known by -.Ic start . -.Pp -Some mechanism for controlling the parameters and environment should exist. -.Pp -Implemented as a -.Xr sh @CMD_EXT@ -script. +on its command line. If running in +.Ar channel +mode, there is no +.Ar start +command and the +.Ar restart +command just tells the name server to +.Xr execvp 2 +itself. .Sh AUTHOR Paul Vixie (Internet Software Consortium) .Sh SEE ALSO .Xr @INDOT@named @SYS_OPS_EXT@ , -.Xr @INDOT@named.reload @SYS_OPS_EXT@ , -.Xr @INDOT@named.restart @SYS_OPS_EXT@ . diff --git a/contrib/bind/doc/man/nsupdate.8 b/contrib/bind/doc/man/nsupdate.8 new file mode 100644 index 0000000..feaa64c --- /dev/null +++ b/contrib/bind/doc/man/nsupdate.8 @@ -0,0 +1,214 @@ +.\" $Id: nsupdate.8,v 8.4 1999/10/17 06:26:18 cyarnell Exp $ +.\" +.\"Copyright (c) 1999 by Internet Software Consortium +.\" +.\"Permission to use, copy, modify, and distribute this software for any +.\"purpose with or without fee is hereby granted, provided that the above +.\"copyright notice and this permission notice appear in all copies. +.\" +.\"THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\"CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\"DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\"PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\"ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\"SOFTWARE. +.Dd March 5, 1999 +.Dt NSUPDATE @SYS_OPS_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm nsupdate +.Nd update Internet name servers interactively +.Sh SYNOPSIS +.Nm nsupdate +.Op Fl Ar k keydir:keyname +.Op Fl Ar d +.Op Fl Ar v +.Op Ar filename +.Sh DESCRIPTION +.Ic Nsupdate +is a program to update Internet domain name servers +supporting dynamic update. +.Ic Nsupdate +uses the DNS resolver library to pass messages +to a DNS server requesting the additional or deletion of +DNS resource records (RRs). +.Ic Nsupdate +reads input from +.Ar filename +or standard input. +.Sh ARGUMENTS +.Bl -tag -width Fl +.It Fl k +Sign updates with TSIG. +.It Fl d +Debug mode. +.It Fl v +Virtual circuit - use TCP to communication with server. +Default is UDP. +.Sh INPUT FORMAT +.Ic Nsupdate +reads input records, one per line, +each line contributing a resource record to an +update request. +All domain names used in a single update request +must belong to the same DNS zone. +A blank line causes the accumulated +records to be formated into a single update request +and transmitted to the zone's authoritative name servers. +Additional records may follow, +which are formed into additional, +completely independent update requests. +For the last request to be transmitted, a blank line +must end the input. +.Pp +Records take one of two general forms. +.Em Prerequisite +records specify conditions that must be satisfied before +the request will be processed. +.Em Update +records specify changes to be made to the DNS database. +A update request consists of zero or more prerequisites +and one or more updates. +Each update request is processed atomically - +all prerequisites must be satisfied, then all updates +will be performed. +.Pp +.Ic Nsupdate +understands the following input record formats: +.Pp + +.Bl -ohang + +.It Ic prereq nxdomain Va domain-name +Requires that no RR of any type exists with name +.Va domain-name . + +.It Ic prereq yxdomain Va domain-name +Requires that at least one RR named +.Va domain-name +must exist. + +.It Xo +.Ic prereq nxrrset Va domain-name Op class +.Va type +.Xc +Requires that no RR exists of the specified +.Va type +and +.Va domain-name . + +.It Xo +.Ic prereq yxrrset +.Va domain-name Op class +.Va type Op data... +.Xc +Requires that a RR exists of the specified +.Va type +and +.Va domain-name . +If +.Va data +is specified, it must match exactly. + +.It Xo +.Ic update delete +.Va domain-name Op class +.Va Op type Op data... +.Xc +Deletes RRs named +.Va domain-name . +If +.Va type +(and possibly +.Va data ) +is specified, +only matching records will be deleted. + +.It Xo +.Ic update add +.Va domain-name ttl Op class +.Va type data... +.Xc +Adds a new RR with specified +.Va ttl , type , +and +.Va data . + +.El + +.Sh EXAMPLES +The following example illustrates the interactive use of +.Ic nsupdate +to change an IP address by deleting any existing A records +for a domain name and then inserting a new one. +Since no prerequisites are specified, +the new record will be added even if +there were no existing records to delete. +Note the +trailing blank line, required to process the request. +.Bd -literal -offset indent +$ nsupdate +> update delete test.example.com A +> update add test.example.com 3600 A 10.1.1.1 +> + +.Ed +.Pp +In this example, a CNAME alias is added to the database +only if there are no existing A or CNAME records for +the domain name. +.Bd -literal -offset indent +$ nsupdate +> prereq nxrrset www.example.com A +> prereq nxrrset www.example.com CNAME +> update add www.example.com 3600 CNAME test.example.com +> + +.Ed +.Pp +In this example, the nsupdate will be signed with the key "mykey", which +is in the directory "/var/named/keys". +.Bd -literal -offset indent +$ nsupdate -k /var/named/keys:mykey +> update add ftp.example.com 60 A 192.168.5.1 +> + +.Ed + +.Sh DIAGNOSTICS +.Bl -ohang + +.It Qq send error +Typically indicates that the authoritative nameservers could not be reached + +.It Qq failed update packet +Typically indicates that the nameserver has rejected the update, +either because the nameserver doesn't support dynamic update, +or due to an authentication failure + +.It Qq res_mkupdate: packet size = Va size +(and no other messages) +The update was successfully received and authenticated by the nameserver. +The prerequisites, however, may have prevented the update from actually +being performed. The only way to determine if the update was performed +is to use debug mode +.Fl ( d ) +and examine the status field in the nameserver's reply. + +.Sh FILES +.It Pa /etc/resolv.conf +initial domain name and name server addresses +.Sh SEE ALSO +.Xr @INDOT@named @SYS_OPS_EXT@ , +.Xr resolver @LIB_NETWORK_EXT@ , +.Xr resolver @FORMAT_EXT@ ; +RFC-1034, +.Dq Domain Names - Concepts and Facilities ; +RFC-1035, +.Dq Domain Names - Implementation and Specification ; +RFC-2136, +Dynamic Updates in the Domain Name System. +.Sh AUTHOR +Brent Baccala diff --git a/contrib/bind/doc/man/resolver.3 b/contrib/bind/doc/man/resolver.3 index fe0c3f7..6ddfe11 100644 --- a/contrib/bind/doc/man/resolver.3 +++ b/contrib/bind/doc/man/resolver.3 @@ -16,44 +16,134 @@ .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" @(#)resolver.3 6.5 (Berkeley) 6/23/90 -.\" $Id: resolver.3,v 8.5 1997/03/14 02:29:48 vixie Exp $ +.\" $Id: resolver.3,v 8.11 1999/09/13 23:33:24 vixie Exp $ .\" -.Dd December 11, 1995 +.Dd October 19, 1998 .Dt RESOLVER @LIB_NETWORK_EXT_U@ .Os BSD 4 .Sh NAME +.Nm res_ninit , +.Nm res_nisourserver , +.Nm fp_resstat , +.Nm res_npquery , +.Nm res_hostalias , +.Nm res_nquery , +.Nm res_nsearch , +.Nm res_nquerydomain , +.Nm res_nmkquery , +.Nm res_nsend , +.Nm res_nupdate , +.Nm res_nmkupdate , +.Nm res_nclose , +.Nm res_nsendsigned , +.Nm res_nsendupdate , +.Nm res_findzonecut , +.Nm dn_comp , +.Nm dn_expand , +.Nm hstrerror , +.Nm res_init , +.Nm res_isourserver , +.Nm p_nquery , +.Mm p_query , +.Mm hostalias , .Nm res_query , .Nm res_search , +.Nm res_querydomain , .Nm res_mkquery , .Nm res_send , -.Nm res_init , -.Nm dn_comp , -.Nm dn_expand +.Nm res_update , +.Nm res_close , +.Nm herror .Nd resolver routines .Sh SYNOPSIS .Fd #include <sys/types.h> .Fd #include <netinet/in.h> .Fd #include <arpa/nameser.h> .Fd #include <resolv.h> +.Fn res_ninit "res_state statp" +.Fn res_nisourserver "const res_state statp" "const struct sockaddr_in *addr" +.Fn fp_resstat "const res_state statp" "FILE *fp" +.Fn res_npquery "const res_state statp" "const u_char *msg" "int msglen" "FILE *fp" +.Fn res_hostalias "const res_state statp" "const char *name" "char *buf" "size_t buflen" +.Fn res_nquery "res_state statp" "const char *dname" "int class" "int type" "u_char *answer" "int anslen" +.Fn res_nsearch "res_state statp" "const char *dname" "int class" "int type" "u_char * answer" "int anslen" +.Fn res_nquerydomain "res_state statp" "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen" +.Fn res_nmkquery "res_state statp, int op, const char *dname" "int class" "int type" "const u_char *data" "int datalen" "const u_char *newrr" "u_char *buf" "int buflen" +.Fn res_nsend "res_state statp" "const u_char *msg" "int msglen" "u_char *answer" "int anslen" +.Fn res_nupdate "res_state statp" "ns_updrec *rrecp_in" +.Fn res_nmkupdate "res_state statp" "ns_updrec *rrecp_in" "u_char *buf" "int buflen" +.Fn res_nclose "res_state statp" +.Fn res_nsendsigned "res_state statp" "const u_char *msg" "int msglen" "ns_tsig_key *key" "u_char *answer" "int anslen" +.Fn res_findzonecut "res_state statp" "const char *dname" "ns_class class" "int options" "char *zname" "size_t zsize" "struct in_addr *addrs" "int naddrs" +.Fn res_nsendupdate "res_state statp" "ns_updrec *rrecp_in" "ns_tsig_key *key" "char *zname" "struct in_addr addr" +.Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs, **lastdnptr" +.Fn dn_expand "const u_char *msg, *eomorig, *comp_dn" "char *exp_dn" "int length" +.Fn hstrerror "int err" +.Sh DEPRECATED +.nr nS 1 +.Fd #include <sys/types.h> +.Fd #include <netinet/in.h> +.Fd #include <arpa/nameser.h> +.Fd #include <resolv.h> +.Fn res_init "void" +.Fn res_isourserver "const struct sockaddr_in *addr" +.Fn p_nquery "const u_char *msg" "int msglen" "FILE *fp" +.Fn p_query "const u_char *msg" "FILE *fp" +.Fn hostalias "const char *name" .Fn res_query "const char *dname" "int class, type" "u_char *answer" "int anslen" .Fn res_search "const char *dname" "int class, type" "u_char *answer" "int anslen" -.Fn res_mkquery "int op" "const char *dname" "int class, type" "const char *data" "int datalen" "struct rrec *newrr" "u_char *buf" "int buflen" +.Fn res_querydomain "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen" +.Fn res_mkquery "int op" "const char *dname, int class, type" "const char *data" "int datalen" "struct rrec *newrr" "u_char *buf" "int buflen" .Fn res_send "const u_char *msg" "int msglen" "u_char *answer" "int anslen" -.Fn res_init -.Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs, **lastdnptr" -.Fn dn_expand "const u_char *msg, *eomorig, *comp_dn" "char *exp_dn" "int length" +.Fn res_update "ns_updrec *rrecp_in" +.Fn res_close "void" .Fn herror "const char *s" -.Fn hstrerror "int err" .Sh DESCRIPTION These routines are used for making, sending and interpreting query and reply messages with Internet domain name servers. .Pp -Global configuration and state information that is used by the -resolver routines is kept in the structure -.Ft _res . -Most of the values have reasonable defaults and can be ignored. +State information is kept in +.Fa statp +and is used to control the behavior of these functions. +.Fa statp +should be set to all zeros prior to the first call to any of these functions. +.Pp +The functions +.Fn res_init , +.Fn res_isourserver , +.Fn p_nquery , +.Fn p_query , +.Fn hostalias , +.Fn res_query , +.Fn res_search , +.Fn res_querydomain , +.Fn res_mkquery , +.Fn res_send , +.Fn res_update , +.Fn res_close +and +.Fn herror +are deprecated and are supplied for compatability with old source +code. +They use global configuration and state information that is +kept in the structure +.Ft _res +rather than that referenced through +.Ft statp . +.Pp +Most of the values in +.Ft statp +and +.Ft _res +are initialized on the first call to +.Fn res_ninit +/ +.Fn res_init +to reasonable defaults and can be ignored. Options stored in +.Ft statp->options +/ .Ft _res.options are defined in .Pa resolv.h @@ -65,14 +155,14 @@ of the options enabled. .It Dv RES_INIT True if the initial name server address and default domain name are initialized (i.e., +.Fn res_ninit +/ .Fn res_init has been called). .It Dv RES_DEBUG Print debugging messages. .It Dv RES_AAONLY Accept authoritative answers only. -With this option, -.Fn res_send should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .It Dv RES_USEVC @@ -84,22 +174,28 @@ to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .It Dv RES_IGNTC -Unused currently (ignore truncation errors, i.e., don't retry with TCP). +Ignore truncation errors, i.e., don't retry with TCP. .It Dv RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c +.Fn res_nsend +/ .Fn res_send does not do iterative queries and expects the name server to handle recursion.) .It Dv RES_DEFNAMES If set, +.Fn res_nsearch +/ .Fn res_search will append the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .It Dv RES_DNSRCH If this option is set, +.Fn res_nsearch +/ .Fn res_search will search for host names in the current domain and in parent domains; see .Xr hostname @DESC_EXT@ . @@ -110,10 +206,31 @@ This option is enabled by default. This option turns off the user level aliasing feature controlled by the .Ev HOSTALIASES -environment variable. Network daemons should set this option. +environment variable. +Network daemons should set this option. +.It Dv RES_USE_INET6 +This option causes +.Xr gethostbyname @LIB_NETWORK_EXT@ +to look for AAAA records before looking for A records if none are found. +.It Dv RES_ROTATE +This options causes the +.Fn res_nsend +/ +.Fn res_send +to rotate the list of nameservers in +.Fa statp->nsaddr_list +/ +.Fa _res.nsaddr_list . +.It Dv RES_KEEPTSIG +This option causes +.Fn res_nsendsigned +to leave the message unchanged after TSIG verification; otherwise the TSIG +record would be removed and the header updated. .El .Pp The +.Fn res_ninit +/ .Fn res_init routine reads the configuration file (if any; see @@ -135,6 +252,8 @@ Another environment variable .Pq Dq Ev RES_OPTIONS can be set to override certain internal resolver options which are otherwise set by changing fields in the +.Ft statp +/ .Ft _res structure or are inherited from the configuration file's .Ic options @@ -146,9 +265,11 @@ Initialization normally occurs on the first call to one of the other resolver routines. .Pp The +.Fn res_nquery +/ .Fn res_query -function provides an interface to the server query mechanism. -It constructs a query, sends it to the local server, +functions provides interfaces to the server query mechanism. +They constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .Fa type @@ -161,10 +282,18 @@ The reply message is left in the buffer with length .Fa anslen supplied by the caller. +.Fn res_nquery +/ +.Fn res_query +return -1 on error or the length of the answer. .Pp The +.Fn res_nsearch +/ .Fn res_search -routine makes a query and awaits a response like +routines make a query and awaits a response like +.Fn res_nquery +/ .Fn res_query , but in addition, it implements the default and search rules controlled by the @@ -172,13 +301,19 @@ controlled by the and .Dv RES_DNSRCH options. -It returns the first successful reply. +It returns the length of the first successful reply which is stored in +.Ft answer +or -1 on error. .Pp The remaining routines are lower-level routines used by +.Fn res_nquery +/ .Fn res_query . The +.Fn res_nmkquery +/ .Fn res_mkquery -function +functions constructs a standard query message and places it in .Fa buf . It returns the size of the query, or \-1 if the query is @@ -196,17 +331,159 @@ The domain name for the query is given by is currently unused but is intended for making update messages. .Pp The +.Fn res_nsend +/ .Fn res_send -routine +/ +.Fn res_nsendsigned +routines sends a pre-formatted query and returns an answer. It will call +.Fn res_ninit +/ .Fn res_init if .Dv RES_INIT is not set, send the query to the local name server, and -handle timeouts and retries. +handle timeouts and retries. Additionally, +.Fn res_nsendsigned +will use TSIG signatures to add authentication to the query and verify the +response. In this case, only one nameserver will be contacted. The length of the reply message is returned, or \-1 if there were errors. .Pp +.Fn res_nquery +/ +.Fn res_query , +.Fn res_nsearch +/ +.Fn res_search +and +.Fn res_nsend +/ +.Fn res_send +return a length that may be bigger than +.Fa anslen . +In that case the query should be retried with a bigger buffer. +NOTE the answer to the second query may be larger still so supplying +a buffer that bigger that the answer returned by the previous +query is recommended. +.Pp +.Fa answer +MUST be big enough to receive a maximum UDP response from the server or +parts of the answer will be silently discarded. +The default maximum UDP response size is 512 bytes. +.Pp +The functions +.Fn res_nisourserver +/ +.Fn res_isourserver +return true when +.Fa inp +is one of the servers in +.Fa statp->nsaddr_list +/ +.Fa _res.nsaddr_list . +.Pp +The functions +.Fn res_npquery +/ +.Fn p_nquery +/ +.Fn p_query +print out the query and any answer in +.Fa msg +on +.Fa fp . +.Fn p_query +is equivalent to +.Fn p_nquery +with +.Fa msglen +set to 512. +.Pp +The function +.Fn fp_resstat +prints out the active flag bits in +.Fa statp->options +preceeded by the text ";; res options:" on +.Fa file . +.Pp +The functions +.Fn res_hostalias +/ +.Fn hostalias +lookup up name in the file referred to by the +.Ev HOSTALIASES files return a fully qualified hostname if found or NULL if +not found or an error occurred. +.Fn res_hostalias +uses +.Fa buf +to store the result in, +.Fn hostalias +uses a static buffer. +.Pp +The functions +.Fn res_nupdate +/ +.Fn res_update +take a list of ns_updrec +.Fa rrecp_in . +Identifies the containing zone for each record and groups the records +according to containing zone maintaining in zone order then sends and +update request to the servers for these zones. +The number of zones updated is returned or -1 on error. +.Pp +The function +.Fn res_findzonecut +discovers the closest enclosing zone cut for a specified domain name, +and finds the IP addresses of the zone's master servers. +.Pp +The function +.Fn res_nsendupdate +is used to perform TSIG authenticated dynamic update operations. +.Fn res_nsendupdate +sends a dynamic update to the specified IP address, authenticating the update +if the key is not NULL. +.Pp +The functions +.Fn res_nmkupdate +/ +.Fn res_mkupdate +take a linked list of ns_updrec +.Fa rrecp_in +and construct a UPDATE message in +.Fa buf . +.Fn res_nmkupdate +/ +.Fn res_mkupdate +return the length of the constructed message on no error or one of the +following error values. +.Bl -inset -width "-5" +.It -1 +An error occurred parsing +.Fa rrecp_in . +.It -2 +The buffer +.Fa buf +was too small. +.It -3 +The first record was not a zone section or there was a section order problem. +The section order is S_ZONE, S_PREREQ and S_UPDATE. +.It -4 +A number overflow occurred. +.It -5 +Unknown operation or no records. +.El +.Pp +The functions +.Fn res_nclose +/ +.Fn res_close +close any open files referenced through +.Fa statp +/ +.Fa _res . +.Pp The .Fn dn_comp function @@ -256,7 +533,11 @@ which is of size .Fa length . The size of compressed name is returned or \-1 if there was an error. .Pp -The external variable +The variables +.Ft statp->res_h_errno +/ +.Ft _res.res_h_errno +and external variable .Ft h_errno is set whenever an error occurs during resolver operation. The following definitions are given in @@ -265,8 +546,8 @@ definitions are given in #define NETDB_INTERNAL -1 /* see errno */ #define NETDB_SUCCESS 0 /* no problem */ #define HOST_NOT_FOUND 1 /* Authoritative Answer Host not found */ -#define TRY_AGAIN 2 /* Non-Authoritive not found, or SERVFAIL */ -#define NO_RECOVERY 3 /* Nonrecoverable: FORMERR, REFUSED, NOTIMP */ +#define TRY_AGAIN 2 /* Non-Authoritative not found, or SERVFAIL */ +#define NO_RECOVERY 3 /* Non-Recoverable: FORMERR, REFUSED, NOTIMP */ #define NO_DATA 4 /* Valid name, no data for requested type */ .Ed .Pp diff --git a/contrib/bind/doc/man/resolver.5 b/contrib/bind/doc/man/resolver.5 index 044bf60..2129893 100644 --- a/contrib/bind/doc/man/resolver.5 +++ b/contrib/bind/doc/man/resolver.5 @@ -14,7 +14,7 @@ .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" @(#)resolver.5 5.9 (Berkeley) 12/14/89 -.\" $Id: resolver.5,v 8.4 1997/03/14 02:29:49 vixie Exp $ +.\" $Id: resolver.5,v 8.6 1999/05/21 00:01:02 vixie Exp $ .\" .Dd November 11, 1993 .Dt RESOLVER @FORMAT_EXT_U@ @@ -46,14 +46,16 @@ The only name server to be queried will be on the local machine, the domain name is determined from the host name, and the domain search path is constructed from the domain name. .Pp -The different configuration options are: +The different configuration directives are: .Bl -tag -width "nameser" .It Li nameserver Internet address (in dot notation) of a name server that the .Nm resolver should query. Up to .Dv MAXNS -(currently 3) name servers may be listed, one per keyword. +(see +.Pa <resolv.h> ) +name servers may be listed, one per keyword. If there are multiple servers, the .Nm resolver library queries them in the order listed. @@ -138,6 +140,44 @@ meaning that if there are dots in a name, the name will be tried first as an absolute name before any .Em search list elements are appended to it. +.It Li timeout: Ns Ar n +sets the amount of time the resolver will wait for a response from a remote +name server before retrying the query via a different name server. Measured in +seconds, the default is +.Dv RES_TIMEOUT +(see +.Pa <resolv.h> ). +.It Li attempts: Ns Ar n +sets the number of times the resolver will send a query to its name servers +before giving up and returning an error to the calling application. The +default is +.Dv RES_DFLRETRY +(see +.Pa <resolv.h> ). +.It Li rotate +sets +.Dv RES_ROTATE +in +.Ft _res.options , +which causes round robin selection of nameservers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every time. +.It Li no-check-names +sets +.Dv RES_NOCHECKNAME +in +.Ft _res.options , +which disables the modern BIND checking of incoming host names and mail names +for invalid characters such as underscore (_), non-ASCII, or control characters. +.It Li inet6 +sets +.Dv RES_USE_INET6 +in +.Ft _res.options . +This has the effect of trying a AAAA query before an A query inside the +.Ft gethostbyname +function, and of mapping IPv4 responses in IPv6 ``tunnelled form'' if no +AAAA records are found but an A record set exists. .El .El .Pp @@ -174,6 +214,7 @@ The keyword and value must appear on a single line, and the keyword must start the line. The value follows the keyword, separated by white space. .Sh FILES .Pa /etc/resolv.conf +.Pa <resolv.h> .Sh SEE ALSO .Xr gethostbyname @LIB_NETWORK_EXT@ , .Xr hostname @DESC_EXT@ , diff --git a/contrib/bind/doc/man/tsig.3 b/contrib/bind/doc/man/tsig.3 new file mode 100644 index 0000000..fa852ee --- /dev/null +++ b/contrib/bind/doc/man/tsig.3 @@ -0,0 +1,240 @@ +.\" $Id: tsig.3,v 8.2 1999/01/08 18:54:28 vixie Exp $ +.\" +.\"Copyright (c) 1995-1999 by Internet Software Consortium +.\" +.\"Permission to use, copy, modify, and distribute this software for any +.\"purpose with or without fee is hereby granted, provided that the above +.\"copyright notice and this permission notice appear in all copies. +.\" +.\"THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\"CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\"DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\"PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\"ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\"SOFTWARE. +.\" +.Dd January 1, 1996 +.Os BSD 4 +.Dt TSIG @SYSCALL_EXT@ +.Sh NAME +.Nm ns_sign , +.Nm ns_sign_tcp , +.Nm ns_sign_tcp_init , +.Nm ns_verify , +.Nm ns_verify_tcp , +.Nm ns_verify_tcp_init , +.Nm ns_find_tsig +.Nd TSIG system +.Sh SYNOPSIS +.Ft int +.Fo ns_sign +.Fa "u_char *msg" +.Fa "int *msglen" +.Fa "int msgsize" +.Fa "int error" +.Fa "void *k" +.Fa "const u_char *querysig" +.Fa "int querysiglen" +.Fa "u_char *sig" +.Fa "int *siglen" +.Fa "time_t in_timesigned" +.Fc +.Ft int +.Fn ns_sign_tcp "u_char *msg" "int *msglen" "int msgsize" "int error" \ + "ns_tcp_tsig_state *state" "int done" +.Ft int +.Fn ns_sign_tcp_init "void *k" "const u_char *querysig" "int querysiglen" \ + "ns_tcp_tsig_state *state" +.Ft int +.Fo ns_verify +.Fa "u_char *msg" +.Fa "int *msglen" +.Fa "void *k" +.Fa "const u_char *querysig" +.Fa "int querysiglen" +.Fa "u_char *sig" +.Fa "int *siglen" +.Fa "time_t in_timesigned" +.Fa "int nostrip" +.Fc +.Ft int +.Fn ns_verify_tcp "u_char *msg" "int *msglen" "ns_tcp_tsig_state *state" \ + "int required" +.Ft int +.Fn ns_verify_tcp_init "void *k" "const u_char *querysig" "int querysiglen" \ + "ns_tcp_tsig_state *state" +.Ft u_char * +.Fn ns_find_tsig "u_char *msg" "u_char *eom" +.Sh DESCRIPTION +The TSIG routines are used to implement transaction/request security of +DNS messages. +.Pp +.Fn ns_sign +and +.Fn ns_verify +are the basic routines. +.Fn ns_sign_tcp +and +.Fn ns_verify_tcp +are used to sign/verify TCP messages that may be split into multiple packets, +such as zone transfers, and +.Fn ns_sign_tcp_init, +.Fn ns_verify_tcp_init +initialize the state structure necessary for TCP operations. +.Fn ns_find_tsig +locates the TSIG record in a message, if one is present. +.Pp +.Fn ns_sign +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv msgsize +the size of the buffer containing the DNS message on input +.It Dv error +the value to be placed in the TSIG error field +.It Dv key +the (DST_KEY *) to sign the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv sig +a buffer to be filled with the generated signature +.It Dv siglen +the length of the signature buffer on input, the signature length on output +.El +.Pp +.Fn ns_sign_tcp +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv msgsize +the size of the buffer containing the DNS message on input +.It Dv error +the value to be placed in the TSIG error field +.It Dv state +the state of the operation +.It Dv done +non-zero value signifies that this is the last packet +.El +.Pp +.Fn ns_sign_tcp_init +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv k +the (DST_KEY *) to sign the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv state +the state of the operation, which this initializes +.El +.Pp +.Fn ns_verify +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv key +the (DST_KEY *) to sign the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv sig +a buffer to be filled with the signature contained +.It Dv siglen +the length of the signature buffer on input, the signature length on output +.It Dv nostrip +non-zero value means that the TSIG is left intact +.El +.Pp +.Fn ns_verify_tcp +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv state +the state of the operation +.It Dv required +non-zero value signifies that a TSIG record must be present at this step +.El +.Pp +.Fn ns_verify_tcp_init +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv k +the (DST_KEY *) to verify the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv state +the state of the operation, which this initializes +.El +.Pp +.Fn ns_find_tsig +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message +.It Dv msglen +the length of the DNS message +.El +.Sh RETURN VALUES +.Fn ns_find_tsig +returns a pointer to the TSIG record if one is found, and NULL otherwise. +.Pp +All other routines return 0 on success, modifying arguments when necessary. +.Pp +.Fn ns_sign +and +.Fn ns_sign_tcp +return the following errors: +.Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent +.It Dv (-1) +bad input data +.It Dv (-ns_r_badkey) +The key was invalid, or the signing failed +.It Dv NS_TSIG_ERROR_NO_SPACE +the message buffer is too small. +.El +.Pp +.Fn ns_verify +and +.Fn ns_verify_tcp +return the following errors: +.Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent +.It Dv (-1) +bad input data +.It Dv NS_TSIG_ERROR_FORMERR +The message is malformed +.It Dv NS_TSIG_ERROR_NO_TSIG +The message does not contain a TSIG record +.It Dv NS_TSIG_ERROR_ID_MISMATCH +The TSIG original ID field does not match the message ID +.It Dv (-ns_r_badkey) +Verification failed due to an invalid key +.It Dv (-ns_r_badsig) +Verification failed due to an invalid signature +.It Dv (-ns_r_badtime) +Verification failed due to an invalid timestamp +.It Dv ns_r_badkey +Verification succeeded but the message had an error of BADKEY +.It Dv ns_r_badsig +Verification succeeded but the message had an error of BADSIG +.It Dv ns_r_badtime +Verification succeeded but the message had an error of BADTIME +.El +.Pp +.Sh SEE ALSO +.Xr resolver 3 . +.Sh AUTHORS +Brian Wellington, TISLabs at Network Associates +.\" .Sh BUGS diff --git a/contrib/bind/doc/notes/data b/contrib/bind/doc/notes/data new file mode 100644 index 0000000..e522392 --- /dev/null +++ b/contrib/bind/doc/notes/data @@ -0,0 +1,51 @@ +/* + * We need a registy of name server addresses. For each, we retain an RTT + * and a list of name server names which have used this address. + */ +tree_t *by_nsaddr; +struct by_nsaddr { + u_int32_t rtt; /* measured. */ + char **names; /* NULL terminated array; strdup'd. */ +}; + +/* + * "struct server" is a name server, which can have many addresses. There + * is no central registry of servers, since each creator can have a different + * idea of what the addresses are. + */ +struct server { + char *name; /* made with strdup. */ + struct sockaddr_in *addrs; /* counted array. */ + int n_addrs; /* array size. */ +}; + +/* + * "struct zone" is a zone cut. + */ +tree_t *by_class; /* zone[class]. */ +struct zone { + enum {master, slave, cache, boot} + type; + + /* Servers learned from boot cache, a parent zone, or !auth answer. */ + struct server *servers_notauth; + + /* Servers learned from authoritative answer or local zone. */ + struct server *servers_auth; + + /* Root node of zone. */ + struct node *root; +}; + +struct node { + char *label; /* made with strdup. */ + tree_t *subs; /* subdomains (node[label]). */ + /* really this is "data" since for the zone cut tree we have no sets.*/ + tree_t *rrsets; /* rr sets (rrset[type]). */ +}; + +struct rrset { + rrtype type; + u_int32_t ttl; + u_char data[1]; /* struct size constrains this. */ +}; diff --git a/contrib/bind/doc/notes/db_names.c b/contrib/bind/doc/notes/db_names.c new file mode 100644 index 0000000..0b4e62c --- /dev/null +++ b/contrib/bind/doc/notes/db_names.c @@ -0,0 +1,184 @@ +/* + * Copyright (c) 1996,1999 by Internet Software Consortium. + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS + * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE + * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL + * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR + * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS + * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + * SOFTWARE. + */ + +#include <sys/types.h> +#include <sys/param.h> +#include <netinet/in.h> +#include <arpa/nameser.h> + +#include <ctype.h> +#include <errno.h> +#include <resolv.h> +#include <stdio.h> + +#include "named.h" +#include "tree.h" + +struct node { + struct node *parent; /* NULL for "."'s node. */ + tree *children; /* Nodes using us as parent. */ + /*void *userdata;*/ /* For future use. */ + char name[sizeof(void*)]; /* Open array. */ +}; + +static struct node rootNode; + +static int +nodeCompare(t1, t2) + const tree_t t1, t2; +{ + const char *n1 = ((struct node *)t1)->name + sizeof(u_char), + *n2 = ((struct node *)t2)->name + sizeof(u_char); + + return (strcasecmp(n1, n2)); +} + +/* void * + * db_findname(const char *name, int storeflag) + * find or store a presentation format domain name. + * returns: + * NULL if an error occurred (check errno) + * else, node's unique, opaque address. + */ +void * +db_findname(name, storeflag) + const char *name; + int storeflag; +{ + struct node *node, *tnode; + const char *tname; + size_t len; + int ch; + + /* The root domain has its own static node. */ + if (name[0] == '\0') + return (&rootNode); + + /* Locate the end of the first label. */ + for (tname = name; (ch = *tname) != '\0'; tname++) { + /* Is this the end of the first label? */ + if (ch == '.') + break; + /* Is it an escaped character? */ + if (ch == '\\') { + ch = *++tname; + if (ch == '\0') + break; + } + } + + /* Make sure the label's length will fit in our length byte. */ + len = tname - name; + if (len > 255) { + errno = ENAMETOOLONG; + return (NULL); + } + + /* If nothing but unescaped dots after this, elide them. */ + while (ch == '.') + ch = *tname++; + + /* + * Make a new node since the comparison function needs it + * and we may yet end up adding it to our parent's tree. + * + * Note that by recursing for tnode->parent, we might be + * creating our parents and grandparents and so on. + */ + tnode = (struct node *)malloc(sizeof(struct node) - sizeof(void *) + + sizeof(u_char) + len + sizeof(char)); + tnode->parent = db_findname(tname); + tnode->children = NULL; + *((u_char *)tnode->name) = (u_char)len; + memcpy(tnode->name + sizeof(u_char), name, len); + tnode->name[sizeof(u_char) + len] = '\0'; + + /* If our first label isn't in our parent's tree, put it there. */ + node = tree_srch(&tnode->parent->children, nodeCompare, (tree_t)tnode); + if (node == NULL) + if (storeflag) + if (tree_add(&tnode->parent->children, nodeCompare, + (tree_t)tnode, NULL)) + node = tnode, tnode = NULL; + else + errno = ENOMEM; + else + errno = ENOENT; + + /* Get rid of tnode if we didn't consume it. */ + if (tnode != NULL) + free(tnode); + + /* Return the (possibly new) node, or NULL, as appropriate. */ + return (node); +} + +/* int + * db_getname(void *node, char *name, size_t size) + * given a node's unique, opaque address, format its name. + * returns: + * -1 = error occurred, check errno + * 0 = success + */ +int +db_getname(vnode, name, size) + const void *vnode; + char *name; + size_t size; +{ + const struct node *node = vnode; + + while (node != NULL) { + size_t len = (size_t)node->name[0]; + + if (size < len + 1) + goto too_long; + memcpy(name, node->name + sizeof(u_char), len); + name += len; + *name++ = '.'; + size -= len + sizeof(char); + node = node->parent; + } + + if (size < sizeof(char)) { + too_long: + errno = ENAMETOOLONG; + return (-1); + } + *name = '\0'; + return (0); +} + +/* + * char * + * db_makename(void *node) + * given a node's unique, opaque address, format and return its name. + * returns: + * pointer to the name or NULL on errors (check errno). + * notes: + * returns pointer to a static buffer, be careful how you call it. + */ +char * +db_makename(vnode) + void *vnode; +{ + static char name[MAXDNAME*2]; + + if (db_getname(vnode, name, sizeof name) < 0) + return (NULL); + return (name); +} diff --git a/contrib/bind/doc/notes/irp.txt b/contrib/bind/doc/notes/irp.txt new file mode 100644 index 0000000..f2b59e2 --- /dev/null +++ b/contrib/bind/doc/notes/irp.txt @@ -0,0 +1,521 @@ +IRP Commands + +This document describes version 1 of IRP. + +IRP is a text-based command/response protocol like NNTP or SMTP. + +1.0 Response types: textual and status. + +1.1 Textual responses + +Textual responses are sent after a status response which indicates the text +will follow. The text is a series of CR-LF terminated lines. On the last line a +single period ``.'' will appear. If a normal text line starts with a period +then this will be doubled before sending. + +There is no maximum line length for responses. Commands have a maximum line +length of 1024 characters. + +The lines that make up the transmitted data are divided into fields. The fields +are spearated by the colon character ``:'', except in one case (for host data) +where the at-sign ``@'' is used instead. Some fields, such as alias names for +hosts, can have multiple values, and these values are separated by commas. + +Most transmission of data requires no special character changes. The field +separators and subfield separators don't normally appear in the data. However +in one case they can (network names). So to avoid trouble, all ``special'' +characters found in any data fields are encoded in URL-encoding form. That is +they are replaced with the 3-character sequence ``%xx'', where xx is the +hexidecimal value of the ascii-code for the chatacter. i,e, ``:'' becomes +``%58'', ``,'' becomes ``%44'' and ``%'' becomes ``%37''. + +For version 1 of IRP the set of special characters for purposes of encoding, +is: + + `,', '%', ':', '@' + +In a couple cases (password structure and group structure), there may be +encrypted passwords as part of the data. If the client is a privileged user +that the server can verify (e.g. through the use of SunOS doors(2)), then the +encrypted password will be sent back to the client. If the client is not +privileged the password will be replaced with the string ``*''. + + +1.2 Status responses. + +Status responses follow a numbering pattern similar to NNTP. + + 1xx - Informative message + 2xx - Command ok + 3xx - Command ok so far, send the rest of it. + 4xx - Command was correct, but couldn't be performed for + some reason. + 5xx - Command unimplemented, or incorrect, or a serious + program error occurred. + + The next digit in the code indicates the function response category. + + x0x - Connection, setup, and miscellaneous messages + x1x - Host lookup + x2x - Network lookup + x3x - User lookup + x4x - Group lookup + x5x - Service lookup + x6x - Protocol lookup + x7x - Netgroup lookup + x8x - Misc. Information Lookup + x9x - Debugging output + + The final digit in the code indicates whether textual data follows + + xx0 - No textual data follows. + xx1 - Textual data follows. + +2.0 Connection Establishment + + When the client connects to the server, the server will issue a welcome + banner. If the server will accetp commands, then the banner will start with + a status code indicating this, followed by a version number of the protocol + it accepts. Other words may come on the line afterwards to indicate to + humans the state of the server, + + If the server wont accept commands then it will issue a banner indicating + that and will then drop the connection. + +2.1 Responses + + 200 1 Ready to go. ; note: The server handles version 1 of the protocol + 200 2 Ready ; note: The server handles version 2 of the protocol + 400 Sorry. Down to due to nightly backups. + +3.0 Commands + +3.1 The HOST commands + +3.1.1 GETHOSTBYNAME hostname +3.1.2 GETHOSTBYNAME2 hostname address-family +3.1.2 GETHOSTBYADDR address address-family +3.1.3 GETHOSTENT + + Returns a textual response containing the information for the given host(s) + (a struct hostent) encoded in an ascii format. gethostbyaddr and + gethostbyname look up a specific host. GETHOSTENT returns the contents + of the /etc/hosts file. The GETHOSTENT command is optional may not be + supported by the server. The address-family paramater is the value + "AF_INET" or "AF_INET6" + +{ XXX GETHOSTENT is optional as the gethostent(3) call isn't always available } + +3.1.4 Responses + + 210 No such host + 211 Host found + + If the hostname given as the command argument doesn't exist, then the 210 + response will be returned. If the host is successfully looked up, then the + 211 response is sent and a textual message is sent after. The textual + message contains the host information encoded in an ascii form. The fields + of the host data are separated by at-signs. Fields that have multiple values + (like the aliases field) have their sub values separated by commas. + + hostname@aliases@address-type@address-length@address-list@ + + - hostname is the FQDN of the host. + + - aliases is a comma separated list of FQDNs for the host aliases. + + - address-type is either the strings "AF_INET" or "AF_INET6" + + - address-length is the length of each address in bytes (after conversion + back to binary form). + + - address-list is a comma separated list of dotted IPv4 if IPv6 addresses. + +{ XXX if we're going to include TTLs where should they go? Perhaps the +address-list field should be "addr/ttl,addr/ttl,..." } + + For example: + + C: GETHOSTBYNAME gw.downtown.vix.com + + S: 210 No such host. + + C: GETHOSTBYNAME gw.home.vix.com + + S: 211 OK + gw.home.vix.com@ftp.vix.com,www.vix.com@AF_INET@4@192.5.5.1,192.5.5.1@ + . + + C: GETHOSTBYNAME2 gw.home.vix.com AF_INET6 + gw.home.vix.com@@AF_INET6@ffff:ffff:ffff:ffff:ffff:ffff:255.255.255.255@ + . + + C: GETHOSTBYADDR 192.5.5.1 + + S: 211 OK + gw.home.vix.com@ftp.vix.com,www.vix.com@AF_INET@4@192.5.5.1,192.5.5.1@ + . + + C: GETHOSTENT + + S: 211 OK + gw.home.vix.com@ftp.vix.com,www.vix.com@AF_INET@4@192.5.5.1,192.5.5.1@ + data.pa.vix.com@@AF_INET@4@204.152.184.37@ + . + + +3.2 The USER commands. + +3.2.1 GETPWNAM username +3.2.2 GETPWUID uid +3.2.3 GETPWENT + + Returns a textual response with the user information (a struct passwd) + enocoded in an ascii format. The optional GETPWENT command transmits the + entire /etc/password file + +{ XXX It's optional only cause it doesn't seem right to spit the password out +to whoever wants it, even with encrypted passwords not being sent } + +3.2.4 Reponses + + 230 No such user + 231 User found + + If the username or uid given as the command argument doesn't exist, then + the 230 response will be returned. If the user is successfully looked up, + then the 231 response is sent and a textual message is sent after. The + textual message contains the user information encoded in an ascii form. The + fields of the user data are separated by colons. The format is very similar + to the /etc/password format (see passwd(5)) + + username:password:uid:gid:class:change:expire:gecos:home_dir:shell: + + - username is the user's login name + + - password User's encrypted password (or the string "*" if the client is + unprivileged) + + - uid User's numeric id. + + - gid User's numeric login group id. + + - class User's general classification (a string) + + - change Password change time (integer seconds from epoch) + + - expire Account expiration time (integer seconds from epoch) + + - gecos General information about the user. + + - home_dir User's home directory. + + - shell User's login shell. + + For example. Client being a non-privileged user: + + C: GETPWNAM brister + + S: 231 User found + brister:*:1364:100:James Brister:/udir/brister:/bin/csh: + . + + C: GETPWUID 6 + games:*:7:13:Games Pseudo-user:/usr/games:nologin + . + + S: GETPWENT + root:*:0:0:System Administrator:/root:/bin/csh + postmast:*:4:4:Postmaster:/:/nologin + daemon:*:1:1:System Daemon:/:nologin + sys:*:2:2:Operating System:/tmp:nologin + bin:*:3:7:BSDI Software:/usr/bsdi:nologin + operator:*:5:5:System Operator:/usr/opr:/bin/csh + uucp:*:6:6:UNIX-to-UNIX Copy:/var/spool/uucppublic:/usr/libexec/uucico + . + + If a priviled user looks up a username: + + C: GETPWNAM www + + S: 231 User found + www:WZajcgFCaAd8s:51:84::0:0:WWW-server:/var/www:/bin/sh + . + +3.3 The NETWORK commands + +3.3.1 GETNETBYNAME network +3.3.2 GETNETBYADDR dotted-ip-address address-family +3.3.4 GETNETENT + + Returns a textual response with the network information (an IRS struct + nwent, *not* a struct netent) enocoded in an ascii format. The optionally + supported GETNETENT command transmits the entire /etc/networks file + +{ XXX should it be optional? } + +3.2.4 Reponses + + 220 No such network + 221 Netork found + + If the network given as the command argument doesn't exist, then the 220 + response will be returned. If the network is successfully looked up, then + the 221 response is sent and a textual message is sent after. The textual + message contains the network information encoded in an ascii form. The fields + of the network data are separated by colons. + + network-name:aliases:address-type:address-length:network-address: + + - network-name is the name of the network + + - aliases is a comma separated list of aliases for the network + + - address-type is ``AF_INET'' or ``AF_INET6''. + + - address-length is the number of bits the following network address uses. + + - address is the network address in a dotted ascii format. AF_INET address + are padded with 0 bits to the full 32 bits before conversion to ascii for + transmission. AF_INET6 addresses are padded to the full 128 bits with 0 + bits before conversion. + + For example: + + C: GETNETBYNAME vixie-net + + S: 221 Network found + vixie-net::AF_INET:24:192.5.5.0: + . + + C: GETNETBYADDR 10.0.0.1 + + S: 221 Network found + private-net:home-net,upstairs-net:AF_INET:8:10.0.0.0: + . + + C: GETNETENT + + S: 221 OK + vixie-net::AF_INET:24:192.5.5.0: + private-net:home-net,upstairs-net:AF_INET:8:10.0.0.0: + lookback-net::AF_INET:8:127.0.0.0 + . + +3.4 The GROUP commands + +3.4.1 GETGRNAM group +3.4.2 GETGRGID gid +3.4.3 GETGRENT + + Returns a textual response with the group information (a struct group) + enocoded in an ascii format. The optionally supported GETGRENT command + transmits the entire /etc/group file. + +3.4.4 Reponses + + 240 No such group + 241 Group found + + If the group given as the command argument doesn't exist, then the 240 + response will be returned. If the group is successfully looked up, then + the 241 response is sent and a textual message is sent after. The textual + message contains the group information encoded in an ascii form. The fields + of the group data are separated by colons. + + group-name:group-password:group-gid:group-members: + + - group-name is the name of the group. + + - group-password is the group's password. This will be correct if the + client has appropriate privileges (see discussion above on the USER + commands). Otherwise it will be the string ``*'' + + - group-gid is the numeric id for the group + + - group-members is a comma separated list of usernames for all the members + of the group. + + For example: + + C: GETGRNAM wheel + + S: 241 Group found + wheel:*:0:root,brister,nathalie,tester: + + C: GETGRGID 20 + + S: 241 Group found + staff:*:20:root,brister: + + C: GETGRENT + + S: 241 OK + wheel:*:0:root,brister,nathalie,tester: + daemon:*:1:daemon: + kmem:*:2:root: + sys:*:3:root: + tty:*:4:root: + operator:*:5:root: + uucp:*:6:brister: + bin:*:7:: + news:*:8:brister: + utmp:*:12:: + games:*:13:: + mail:*:14:: + staff:*:20:root,brister: + . + +3.5 The SERVICE commands + +3.5.1 GETSERVBYNAME name protocol +3.5.2 GETSERVBYPORT port protocol +3.5.3 GETSERVENT + + Returns a textual response with the service information (a struct servent) + enocoded in an ascii format. The optionally supported GETSERVENT command + transmits the entire /etc/services file. + +3.5.4 Reponses + + 250 No such service + 251 Group found + + If the group given as the command argument doesn't exist, then the 250 + response will be returned. If the service is successfully looked up, then + the 251 response is sent and a textual message is sent after. The textual + message contains the service information encoded in an ascii form. The fields + of the service data are separated by colons. + + service-name:aliases:port-number:protocol: + + - The service name is the offical name of the services. + + - aliases is a comma separated list of aliases for the service. + + - port-number is the decimal number of the port used for the service. + + - protocol is the name of the protocol the service operates under. Usually + either ``TCP'' or ``UCP'' + + For example: + + C: GETSERVBYNAME nntp tcp + + S: 251 Service found + nntp:readnews,untp:119:tcp: + . + + C: GETSERVBYPORT 514 udp + syslog::514:ucp: + . + + C: GETSERVENT + 251 OK + tcpmux::1:tcp: + echo::7:tcp: + echo::7:udp: + discard:sink,null:9:tcp: + discard:sink,null:9:udp: + systat:users:11:tcp: + systat:users:11:udp: + daytime::13:tcp: + daytime::13:udp: + netstat::15:tcp: + qotd:quote:17:tcp: + qotd:quote:17:udp: + . + +3.6 The PROTOCOL commands + +3.6.1 GETPROTOBYNAME protocol-name +3.6.2 GETPROTOBYNUMBER protocol-number +3.6.3 GETPROTOENT + + Returns a textual response with the protocol information (a struct protoent) + enocoded in an ascii format. The optionally supported GETPROTOENT command + transmits the entire /etc/protocols file. + +3.6.4 Reponses + + 260 No such protocol + 261 Protocol found + + If the protocol given as the command argument doesn't exist, then the 260 + response will be returned. If the service is successfully looked up, then + the 261 response is sent and a textual message is sent after. The textual + message contains the protocol information encoded in an ascii form. The fields + of the protocol data are separated by colons. + + protocol-name:aliases:protocol-number: + + - protocol-name is the offical name of the protocol + + - aliases is a comma separated list of aliases for the protocol + + - protocol-nunber is the number of the protocol in decimal. + + + For example: + + C: GETPROTOBYNAME ip + + S: 261 Protocol found + ip:IP:0: + . + + C: GETPROTOBYNUMBER 17 + + S: 261 Protocol found + udp:UDP:17: + . + + C: GETPROTOENT + + S: 261 OK + ip:IP:0: + icmp:ICMP:1: + igmp:IGMP:2: + ggp:GGP:3: + tcp:TCP:6: + egp:EGP:8: + pup:PUP:12: + udp:UDP:17: + hmp:HMP:20: + xns-idp:XNS-IDP:22: + rdp:RDP:27: + iso-tp4:ISO-TP4:29: + iso-ip:ISO-IP:80: + encap:ENCAP:98: + . + +3.7 The NETGROUP commands + +3.7.1 GETNETGRENT netgrouup + + Returns a textual response with the netgroup information enocoded in an + ascii format. + +3.6.4 Reponses + + 270 No such netgroup + 271 Netgroups found + + For the given netgroup a list of the netgroup entries will be + returned. Each netgroup entry is three fields separated by colons. A field + may be empty to indicate wildcarding. + + :hostname:username:domainname: + + For example: + + C: GETNETGRENT devlopers + + S: 271 OK + :gw.home.vix.com:brister:vix.com: + :bb.rc.vix.com:vixie:: + . + + + + |
