From owner-freebsd-doc@FreeBSD.ORG Sun Feb 29 20:30:16 2004 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id C556C16A4CE for ; Sun, 29 Feb 2004 20:30:16 -0800 (PST) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id BB47843D45 for ; Sun, 29 Feb 2004 20:30:16 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) i214UGbv070752 for ; Sun, 29 Feb 2004 20:30:16 -0800 (PST) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.10/8.12.10/Submit) id i214UGZt070751; Sun, 29 Feb 2004 20:30:16 -0800 (PST) (envelope-from gnats) Resent-Date: Sun, 29 Feb 2004 20:30:16 -0800 (PST) Resent-Message-Id: <200403010430.i214UGZt070751@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Chris Pepper Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id E730E16A4CE; Sun, 29 Feb 2004 20:20:50 -0800 (PST) Received: from www.reppep.com (www.reppep.com [66.92.104.200]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3A2FA43D1D; Sun, 29 Feb 2004 20:20:50 -0800 (PST) (envelope-from pepper@reppep.com) Received: by www.reppep.com (Postfix, from userid 501) id 9813C100C5; Sun, 29 Feb 2004 23:20:59 -0500 (EST) Message-Id: <20040301042059.9813C100C5@www.reppep.com> Date: Sun, 29 Feb 2004 23:20:59 -0500 (EST) From: Chris Pepper To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 cc: chern@FreeBSD.org Subject: docs/63570: Language cleanup for the Handbook's DNS section X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: Chris Pepper List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 01 Mar 2004 04:30:17 -0000 >Number: 63570 >Category: docs >Synopsis: Language cleanup for the Handbook's DNS section >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Sun Feb 29 20:30:16 PST 2004 >Closed-Date: >Last-Modified: >Originator: Chris Pepper >Release: FreeBSD 4.9-STABLE i386 >Organization: >Environment: System: FreeBSD www.reppep.com 4.9-STABLE FreeBSD 4.9-STABLE #13: Thu Nov 13 23:50:39 EST 2003 root@www.reppep.com:/usr/obj/usr/src/sys/REPPEP i386 >Description: Picked a bunch of language and consistency nits in the DNS networking section. As written, slaves only reply when the primary is down; this is not the case. Added a mention that there must be two authoritative servers. Revised caching terminology; among other things, caching is rarely *necessary*, but often valuable. At some point, cached records expire, so external lookups are required again. In addition, there's a deeper problem I didn't change. The two paragraphs below imply that slaves and masters are mutually exclusive. For all domains I've deal with, ns2 is a slave from ns1, but listed with an NS record in the zone, and thus authoritative as well. The terminolgy should probably be either clarified or changed, but I don't have a solution to propose at this point. a backup name server, called a slave, must reply to queries when the primary is down or inaccessible. In the slave case, the zone information is transferred from the master name server for the particular zone, and saved in the file specified. If and when the master server dies or is unreachable, the slave name server will have the transferred zone information and will be able to serve it. >How-To-Repeat: Visit http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-dns.html >Fix: Apply this patch. --- chapter.sgml.diff begins here --- Index: chapter.sgml =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v retrieving revision 1.276 diff -u -u -r1.276 chapter.sgml --- chapter.sgml 29 Feb 2004 17:24:51 -0000 1.276 +++ chapter.sgml 1 Mar 2004 04:15:44 -0000 @@ -5036,7 +5036,7 @@ DNS DNS is coordinated across the Internet through a somewhat complex system of authoritative root name servers, and other - smaller-scale name servers who host and cache individual domain + smaller-scale name servers which host and cache individual domain information. @@ -5137,7 +5137,7 @@ org. is a zone under the root zone - example.org is a zone under the + example.org. is a zone under the org. zone @@ -5153,7 +5153,7 @@ As one can see, the more specific part of a hostname appears to - its left. For example, example.org. is more + the left. For example, example.org. is more specific than org., as org. is more specific than the root zone. The layout of each part of a hostname is much like a filesystem: the /dev @@ -5165,8 +5165,8 @@ Reasons to Run a Name Server - Name servers usually come in two forms: an authoritative - name server, and a caching name server. + Name servers generally come in two forms: authoritative + name servers, and caching name servers. An authoritative name server is needed when: @@ -5178,37 +5178,39 @@ a domain, such as example.org, is registered and IP addresses need to be assigned to hostnames - under it. + under it. Each domain must have at least two authoritative + servers. an IP address block requires reverse DNS entries (IP to hostname). - a backup name server, called a slave, must reply to queries + a backup name server, called a slave, must be available to reply to queries when the primary is down or inaccessible. - A caching name server is needed when: + A caching name server may provide: - a local DNS server may cache and respond more quickly - than querying an outside name server. + Faster responses than are available from outside name + servers. - a reduction in overall network traffic is desired (DNS - traffic has been measured to account for 5% or more of total - Internet traffic). + A reduction in overall network traffic, by re-using + information rather than re-fetching it from remote name + servers. DNS traffic has been measured to account for 5% or + more of total Internet traffic. When one queries for www.FreeBSD.org, the resolver usually queries the uplink ISP's name server, and retrieves the reply. With a local, caching DNS server, the query only has to - be made once to the outside world by the caching DNS server. Every - additional query will not have to look to the outside of the local + be made once to the outside world by the caching DNS server. + Additional queries will not have to go outside the local network, since the information is cached locally. @@ -5245,7 +5247,7 @@ /etc/namedb/named.conf - daemon configuration file + named configuration file @@ -5266,12 +5268,12 @@ starting - Since BIND is installed by default, configuring it all is + Since BIND is installed by default, configuring it is relatively simple. - To ensure the named daemon is started at boot, put the following - modifications in /etc/rc.conf: + To ensure named is started at boot, put the following + in /etc/rc.conf: named_enable="YES" To start the daemon manually (after configuring it) @@ -5505,7 +5507,7 @@ Note that every hostname ending in a . is an exact hostname, whereas everything without a trailing - . is referenced to the origin. For example, + . is a reference to the origin. For example, www is translated into www + origin. In our fictitious zone file, our origin is example.org., so @@ -5622,7 +5624,7 @@ This is an NS entry. Every name server that is going to reply authoritatively for the zone must have one of these entries. - The @ as seen here could have been + The @ seen here could have been example.org. The @ translates to the origin. @@ -5639,7 +5641,7 @@ ns1.example.org would resolve to 3.2.1.2. Again, the origin symbol, @, is - used here, thus meaning example.org + used here, meaning example.org would resolve to 3.2.1.30. @@ -5649,7 +5651,7 @@ The canonical name record is usually used for giving aliases to a machine. In the example, www is - aliased to the machine addressed to the origin, or + aliased to the origin, or example.org (3.2.1.30). CNAMEs can be used to provide alias @@ -5664,7 +5666,7 @@ The MX record indicates which mail servers are responsible for handling incoming mail for the zone. mail.example.org is the - hostname of the mail server, and 10 being the priority of + hostname of a mail server, and 10 is the priority of that mail server. @@ -5679,7 +5681,7 @@ For in-addr.arpa zone files (reverse DNS), the same format is used, except with PTR entries instead of - A or CNAME. + A and CNAME. $TTL 3600 @@ -5699,7 +5701,7 @@ 10 IN PTR mail.example.org. 30 IN PTR example.org. - This file gives the proper IP address to hostname mappings of our above + This file gives the proper IP address to hostname mappings for our above fictitious domain. @@ -5715,7 +5717,7 @@ A caching name server is a name server that is not authoritative for any zones. It simply asks queries of its own, and remembers them for later use. To set one up, just configure - the name server as usual, omitting any inclusions of zones. + the name server as usual, omitting any master or slave zones. @@ -5738,10 +5740,10 @@ and a group called bind, intended for this use. - Various people would recommend that instead of configuring + Various people recommend that instead of configuring named to chroot, you should run named inside a &man.jail.8;. - This section does not attempt to cover this situation. + This section does not attempt to cover this scenario. Since named will not be able to @@ -5768,7 +5770,7 @@ named only needs write access to - these directories, so that is all we give it. + these three directories, so that is all we give it control over. @@ -5844,7 +5846,7 @@ If you are running &os; version 4.9-RELEASE or later, then the copy of named-xfer in /usr/libexec is statically linked by default, - and you can simply use &man.cp.1; to copy it into your sandbox. + and you can simply use &man.cp.1; to copy it into your sandbox's bin directory. @@ -5896,7 +5898,7 @@ Note that the configuration file /etc/named.conf is denoted by a full pathname relative to the sandbox, i.e. in - the line above, the file referred to is actually + the line above, the file used is actually /etc/namedb/etc/named.conf. @@ -5906,7 +5908,7 @@ /etc/namedb/etc/named.conf so that named knows which zones to load and where to find them on the disk. There follows a commented - example (anything not specifically commented here is no + example (anything not specifically mentioned here is no different from the setup for a DNS server not running in a sandbox): @@ -6014,7 +6016,7 @@ If a problem arises, keeping sources up to date and having a - fresh build of named would not hurt. + fresh build of named may help. @@ -6026,7 +6028,7 @@ Official ISC Bind + url="http://www.isc.org/products/BIND/">Official ISC BIND Page --- chapter.sgml.diff ends here --- >Release-Note: >Audit-Trail: >Unformatted: