Date: Sun, 29 Feb 2004 23:20:59 -0500 (EST) From: Chris Pepper <pepper@reppep.com> To: FreeBSD-gnats-submit@FreeBSD.org Cc: chern@FreeBSD.org Subject: docs/63570: Language cleanup for the Handbook's DNS section Message-ID: <20040301042059.9813C100C5@www.reppep.com> Resent-Message-ID: <200403010430.i214UGZt070751@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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.
<para>a backup name server, called a slave, must reply to queries
when the primary is down or inaccessible.</para>
<para>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.</para>
</sect3>
>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 @@
<indexterm><primary>DNS</primary></indexterm>
<para>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.
</para>
@@ -5137,7 +5137,7 @@
<para><hostid>org.</hostid> is a zone under the root zone</para>
</listitem>
<listitem>
- <para><hostid>example.org</hostid> is a zone under the
+ <para><hostid>example.org.</hostid> is a zone under the
<hostid>org.</hostid> zone</para>
</listitem>
<listitem>
@@ -5153,7 +5153,7 @@
</itemizedlist>
<para>As one can see, the more specific part of a hostname appears to
- its left. For example, <hostid>example.org.</hostid> is more
+ the left. For example, <hostid>example.org.</hostid> is more
specific than <hostid>org.</hostid>, as <hostid>org.</hostid> is
more specific than the root zone. The layout of each part of
a hostname is much like a filesystem: the <filename>/dev</filename>
@@ -5165,8 +5165,8 @@
<sect2>
<title>Reasons to Run a Name Server</title>
- <para>Name servers usually come in two forms: an authoritative
- name server, and a caching name server.</para>
+ <para>Name servers generally come in two forms: authoritative
+ name servers, and caching name servers.</para>
<para>An authoritative name server is needed when:</para>
@@ -5178,37 +5178,39 @@
<listitem>
<para>a domain, such as <hostid>example.org</hostid>, is
registered and IP addresses need to be assigned to hostnames
- under it.</para>
+ under it. Each domain must have at least two authoritative
+ servers.</para>
</listitem>
<listitem>
<para>an IP address block requires reverse DNS entries (IP to
hostname).</para>
</listitem>
<listitem>
- <para>a backup name server, called a slave, must reply to queries
+ <para>a backup name server, called a slave, must be available to reply to queries
when the primary is down or inaccessible.</para>
</listitem>
</itemizedlist>
- <para>A caching name server is needed when:</para>
+ <para>A caching name server may provide:</para>
<itemizedlist>
<listitem>
- <para>a local DNS server may cache and respond more quickly
- than querying an outside name server.</para>
+ <para>Faster responses than are available from outside name
+ servers.</para>
</listitem>
<listitem>
- <para>a reduction in overall network traffic is desired (DNS
- traffic has been measured to account for 5% or more of total
- Internet traffic).</para>
+ <para>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.</para>
</listitem>
</itemizedlist>
<para>When one queries for <hostid>www.FreeBSD.org</hostid>, 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.</para>
</sect2>
@@ -5245,7 +5247,7 @@
<row>
<entry><filename>/etc/namedb/named.conf</filename></entry>
- <entry>daemon configuration file</entry>
+ <entry>named configuration file</entry>
</row>
</tbody>
</tgroup>
@@ -5266,12 +5268,12 @@
<secondary>starting</secondary>
</indexterm>
<para>
- Since BIND is installed by default, configuring it all is
+ Since BIND is installed by default, configuring it is
relatively simple.
</para>
<para>
- To ensure the named daemon is started at boot, put the following
- modifications in <filename>/etc/rc.conf</filename>:
+ To ensure named is started at boot, put the following
+ in <filename>/etc/rc.conf</filename>:
</para>
<programlisting>named_enable="YES"</programlisting>
<para>To start the daemon manually (after configuring it)</para>
@@ -5505,7 +5507,7 @@
<para>
Note that every hostname ending in a <quote>.</quote> is an
exact hostname, whereas everything without a trailing
- <quote>.</quote> is referenced to the origin. For example,
+ <quote>.</quote> is a reference to the origin. For example,
<literal>www</literal> is translated into <literal>www +
origin</literal>. In our fictitious zone file, our origin
is <hostid>example.org.</hostid>, so
@@ -5622,7 +5624,7 @@
<para>
This is an <varname>NS</varname> entry. Every name server that is going to reply
authoritatively for the zone must have one of these entries.
- The <literal>@</literal> as seen here could have been
+ The <literal>@</literal> seen here could have been
<hostid role="domainname">example.org.</hostid>
The <literal>@</literal> translates to the origin.
</para>
@@ -5639,7 +5641,7 @@
<hostid>ns1.example.org</hostid> would resolve to
<hostid role="ipaddr">3.2.1.2</hostid>. Again,
the origin symbol, <literal>@</literal>, is
- used here, thus meaning <hostid>example.org</hostid>
+ used here, meaning <hostid>example.org</hostid>
would resolve to <hostid role="ipaddr">3.2.1.30</hostid>.
</para>
@@ -5649,7 +5651,7 @@
<para>
The canonical name record is usually used for giving aliases
to a machine. In the example, <hostid>www</hostid> is
- aliased to the machine addressed to the origin, or
+ aliased to the origin, or
<hostid>example.org</hostid>
(<hostid role="ipaddr">3.2.1.30</hostid>).
<varname>CNAME</varname>s can be used to provide alias
@@ -5664,7 +5666,7 @@
The <varname>MX</varname> record indicates which mail
servers are responsible for handling incoming mail for the
zone. <hostid role="fqdn">mail.example.org</hostid> 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.
</para>
@@ -5679,7 +5681,7 @@
<para>
For in-addr.arpa zone files (reverse DNS), the same format is
used, except with <varname>PTR</varname> entries instead of
- <varname>A</varname> or <varname>CNAME</varname>.
+ <varname>A</varname> and <varname>CNAME</varname>.
</para>
<programlisting>$TTL 3600
@@ -5699,7 +5701,7 @@
10 IN PTR mail.example.org.
30 IN PTR example.org.</programlisting>
<para>
- 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.
</para>
</sect3>
@@ -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.
</para>
</sect2>
@@ -5738,10 +5740,10 @@
and a group called <groupname>bind</groupname>, intended for this
use.</para>
- <note><para>Various people would recommend that instead of configuring
+ <note><para>Various people recommend that instead of configuring
<application>named</application> to <command>chroot</command>, you
should run <application>named</application> inside a &man.jail.8;.
- This section does not attempt to cover this situation.</para>
+ This section does not attempt to cover this scenario.</para>
</note>
<para>Since <application>named</application> will not be able to
@@ -5768,7 +5770,7 @@
<calloutlist>
<callout arearefs="chown-slave">
<para><application>named</application> only needs write access to
- these directories, so that is all we give it.</para>
+ these three directories, so that is all we give it control over.</para>
</callout>
</calloutlist>
</listitem>
@@ -5844,7 +5846,7 @@
<para>If you are running &os; version 4.9-RELEASE or later, then
the copy of <command>named-xfer</command> in
<filename>/usr/libexec</filename> is statically linked by default,
- and you can simply use &man.cp.1; to copy it into your sandbox.</para>
+ and you can simply use &man.cp.1; to copy it into your sandbox's <filename>bin</filename> directory.</para>
</listitem>
<listitem>
@@ -5896,7 +5898,7 @@
<para>Note that the configuration file
<replaceable>/etc/named.conf</replaceable> is denoted by a full
pathname <emphasis>relative to the sandbox</emphasis>, i.e. in
- the line above, the file referred to is actually
+ the line above, the file used is actually
<filename>/etc/namedb/etc/named.conf</filename>.</para>
</note>
</listitem>
@@ -5906,7 +5908,7 @@
<filename>/etc/namedb/etc/named.conf</filename> so that
<application>named</application> 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):</para>
@@ -6014,7 +6016,7 @@
</para>
<tip><para>If a problem arises, keeping sources up to date and having a
- fresh build of named would not hurt.</para></tip>
+ fresh build of named may help.</para></tip>
</sect2>
<sect2>
@@ -6026,7 +6028,7 @@
<itemizedlist>
<listitem>
<para><ulink
- url="http://www.isc.org/products/BIND/">Official ISC Bind
+ url="http://www.isc.org/products/BIND/">Official ISC BIND
Page</ulink></para>
</listitem>
--- chapter.sgml.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040301042059.9813C100C5>