Attachment #40442 for bug #63570

View | Details | Raw Unified | Return to bug 63570
Collapse All | Expand All




      <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 which host and cache individual domain
        information.
      </para>


          <para><hostid>org.</hostid> is a zone under the root zone</para>
        </listitem>
        <listitem>
          <para><hostid>example.org.</hostid> is a zone under the
          <hostid>org.</hostid> zone</para>
        </listitem>
        <listitem>

      </itemizedlist>

      <para>As one can see, the more specific part of a hostname appears to
        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>

    <sect2>
      <title>Reasons to Run a Name Server</title>

      <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>


	<listitem>
	  <para>a domain, such as <hostid>example.org</hostid>, is
	    registered and IP addresses need to be assigned to hostnames
	    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 be available to reply to queries
	    when the primary is down or inaccessible.</para>
	  </listitem>
      </itemizedlist>

      <para>A caching name server may provide:</para>

      <itemizedlist>
	<listitem>
	  <para>Faster responses than are available from outside name
	  servers.</para>
	</listitem>
	<listitem>
	  <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.
	Additional queries will not have to go outside the local
	network, since the information is cached locally.</para>

    </sect2>


	    <row>
	      <entry><filename>/etc/namedb/named.conf</filename></entry>
	      <entry>named configuration file</entry>
	    </row>
	  </tbody>
	</tgroup>

	<secondary>starting</secondary>
      </indexterm>
      <para>
        Since BIND is installed by default, configuring it is
        relatively simple.
      </para>
      <para>
        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>

        <para>
          Note that every hostname ending in a <quote>.</quote> is an
          exact hostname, whereas everything without a trailing
          <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

        <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> seen here could have been
	  <hostid role="domainname">example.org.</hostid>
	  The <literal>@</literal> translates to the origin.
        </para>

          <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, meaning <hostid>example.org</hostid>
          would resolve to <hostid role="ipaddr">3.2.1.30</hostid>.
        </para>


        <para>
          The canonical name record is usually used for giving aliases
          to a machine.  In the example, <hostid>www</hostid> is
          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

          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 a mail server, and 10 is the priority of
          that mail server.
        </para>


        <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> and <varname>CNAME</varname>.
        </para>

        <programlisting>$TTL 3600

10      IN PTR  mail.example.org.
30      IN PTR  example.org.</programlisting>
        <para>
         This file gives the proper IP address to hostname mappings for our above
         fictitious domain.
        </para>
      </sect3>

        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 master or slave zones.
      </para>
    </sect2>


	and a group called <groupname>bind</groupname>, intended for this
	use.</para>

      <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 scenario.</para>
      </note>

      <para>Since <application>named</application> will not be able to

	  <calloutlist>
	    <callout arearefs="chown-slave">
	      <para><application>named</application> only needs write access to
		these three directories, so that is all we give it control over.</para>
	    </callout>
	  </calloutlist>
	</listitem>

	  <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's <filename>bin</filename> directory.</para>
	</listitem>

	<listitem>

	    <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 used is actually
	    <filename>/etc/namedb/etc/named.conf</filename>.</para>
	  </note>
	</listitem>

	<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 mentioned here is no
	different from the setup for a DNS server not running in a
	sandbox):</para>


      </para>

      <tip><para>If a problem arises, keeping sources up to date and having a
        fresh build of named may help.</para></tip>
    </sect2>

    <sect2>

      <itemizedlist>
	<listitem>
	  <para><ulink
	      url="http://www.isc.org/products/BIND/">Official ISC BIND
	      Page</ulink></para>
	</listitem>

Return to bug 63570

Lines 5036-5042 Link Here

(-)chapter.sgml (-35 / +37 lines)
5036	<indexterm><primary>DNS</primary></indexterm>	5036	<indexterm><primary>DNS</primary></indexterm>
5037	<para>DNS is coordinated across the Internet through a somewhat	5037	<para>DNS is coordinated across the Internet through a somewhat
5038	complex system of authoritative root name servers, and other	5038	complex system of authoritative root name servers, and other
5039	smaller-scale name servers who host and cache individual domain	5039	smaller-scale name servers which host and cache individual domain
5040	information.	5040	information.
5041	</para>	5041	</para>
5042		5042
Lines 5137-5143 Link Here
5137	<para><hostid>org.</hostid> is a zone under the root zone</para>	5137	<para><hostid>org.</hostid> is a zone under the root zone</para>
5138	</listitem>	5138	</listitem>
5139	<listitem>	5139	<listitem>
5140	<para><hostid>example.org</hostid> is a zone under the	5140	<para><hostid>example.org.</hostid> is a zone under the
5141	<hostid>org.</hostid> zone</para>	5141	<hostid>org.</hostid> zone</para>
5142	</listitem>	5142	</listitem>
5143	<listitem>	5143	<listitem>
Lines 5153-5159 Link Here
5153	</itemizedlist>	5153	</itemizedlist>
5154		5154
5155	<para>As one can see, the more specific part of a hostname appears to	5155	<para>As one can see, the more specific part of a hostname appears to
5156	its left. For example, <hostid>example.org.</hostid> is more	5156	the left. For example, <hostid>example.org.</hostid> is more
5157	specific than <hostid>org.</hostid>, as <hostid>org.</hostid> is	5157	specific than <hostid>org.</hostid>, as <hostid>org.</hostid> is
5158	more specific than the root zone. The layout of each part of	5158	more specific than the root zone. The layout of each part of
5159	a hostname is much like a filesystem: the <filename>/dev</filename>	5159	a hostname is much like a filesystem: the <filename>/dev</filename>
Lines 5165-5172 Link Here
5165	<sect2>	5165	<sect2>
5166	<title>Reasons to Run a Name Server</title>	5166	<title>Reasons to Run a Name Server</title>
5167		5167
5168	<para>Name servers usually come in two forms: an authoritative	5168	<para>Name servers generally come in two forms: authoritative
5169	name server, and a caching name server.</para>	5169	name servers, and caching name servers.</para>
5170		5170
5171	<para>An authoritative name server is needed when:</para>	5171	<para>An authoritative name server is needed when:</para>
5172		5172
Lines 5178-5214 Link Here
5178	<listitem>	5178	<listitem>
5179	<para>a domain, such as <hostid>example.org</hostid>, is	5179	<para>a domain, such as <hostid>example.org</hostid>, is
5180	registered and IP addresses need to be assigned to hostnames	5180	registered and IP addresses need to be assigned to hostnames
5181	under it.</para>	5181	under it. Each domain must have at least two authoritative
		5182	servers.</para>
5182	</listitem>	5183	</listitem>
5183	<listitem>	5184	<listitem>
5184	<para>an IP address block requires reverse DNS entries (IP to	5185	<para>an IP address block requires reverse DNS entries (IP to
5185	hostname).</para>	5186	hostname).</para>
5186	</listitem>	5187	</listitem>
5187	<listitem>	5188	<listitem>
5188	<para>a backup name server, called a slave, must reply to queries	5189	<para>a backup name server, called a slave, must be available to reply to queries
5189	when the primary is down or inaccessible.</para>	5190	when the primary is down or inaccessible.</para>
5190	</listitem>	5191	</listitem>
5191	</itemizedlist>	5192	</itemizedlist>
5192		5193
5193	<para>A caching name server is needed when:</para>	5194	<para>A caching name server may provide:</para>
5194		5195
5195	<itemizedlist>	5196	<itemizedlist>
5196	<listitem>	5197	<listitem>
5197	<para>a local DNS server may cache and respond more quickly	5198	<para>Faster responses than are available from outside name
5198	than querying an outside name server.</para>	5199	servers.</para>
5199	</listitem>	5200	</listitem>
5200	<listitem>	5201	<listitem>
5201	<para>a reduction in overall network traffic is desired (DNS	5202	<para>A reduction in overall network traffic, by re-using
5202	traffic has been measured to account for 5% or more of total	5203	information rather than re-fetching it from remote name
5203	Internet traffic).</para>	5204	servers. DNS traffic has been measured to account for 5% or
		5205	more of total Internet traffic.</para>
5204	</listitem>	5206	</listitem>
5205	</itemizedlist>	5207	</itemizedlist>
5206		5208
5207	<para>When one queries for <hostid>www.FreeBSD.org</hostid>, the	5209	<para>When one queries for <hostid>www.FreeBSD.org</hostid>, the
5208	resolver usually queries the uplink ISP's name server, and retrieves	5210	resolver usually queries the uplink ISP's name server, and retrieves
5209	the reply. With a local, caching DNS server, the query only has to	5211	the reply. With a local, caching DNS server, the query only has to
5210	be made once to the outside world by the caching DNS server. Every	5212	be made once to the outside world by the caching DNS server.
5211	additional query will not have to look to the outside of the local	5213	Additional queries will not have to go outside the local
5212	network, since the information is cached locally.</para>	5214	network, since the information is cached locally.</para>
5213		5215
5214	</sect2>	5216	</sect2>
Lines 5245-5251 Link Here
5245		5247
5246	<row>	5248	<row>
5247	<entry><filename>/etc/namedb/named.conf</filename></entry>	5249	<entry><filename>/etc/namedb/named.conf</filename></entry>
5248	<entry>daemon configuration file</entry>	5250	<entry>named configuration file</entry>
5249	</row>	5251	</row>
5250	</tbody>	5252	</tbody>
5251	</tgroup>	5253	</tgroup>
Lines 5266-5277 Link Here
5266	<secondary>starting</secondary>	5268	<secondary>starting</secondary>
5267	</indexterm>	5269	</indexterm>
5268	<para>	5270	<para>
5269	Since BIND is installed by default, configuring it all is	5271	Since BIND is installed by default, configuring it is
5270	relatively simple.	5272	relatively simple.
5271	</para>	5273	</para>
5272	<para>	5274	<para>
5273	To ensure the named daemon is started at boot, put the following	5275	To ensure named is started at boot, put the following
5274	modifications in <filename>/etc/rc.conf</filename>:	5276	in <filename>/etc/rc.conf</filename>:
5275	</para>	5277	</para>
5276	<programlisting>named_enable="YES"</programlisting>	5278	<programlisting>named_enable="YES"</programlisting>
5277	<para>To start the daemon manually (after configuring it)</para>	5279	<para>To start the daemon manually (after configuring it)</para>
Lines 5505-5511 Link Here
5505	<para>	5507	<para>
5506	Note that every hostname ending in a <quote>.</quote> is an	5508	Note that every hostname ending in a <quote>.</quote> is an
5507	exact hostname, whereas everything without a trailing	5509	exact hostname, whereas everything without a trailing
5508	<quote>.</quote> is referenced to the origin. For example,	5510	<quote>.</quote> is a reference to the origin. For example,
5509	<literal>www</literal> is translated into <literal>www +	5511	<literal>www</literal> is translated into <literal>www +
5510	origin</literal>. In our fictitious zone file, our origin	5512	origin</literal>. In our fictitious zone file, our origin
5511	is <hostid>example.org.</hostid>, so	5513	is <hostid>example.org.</hostid>, so
Lines 5622-5628 Link Here
5622	<para>	5624	<para>
5623	This is an <varname>NS</varname> entry. Every name server that is going to reply	5625	This is an <varname>NS</varname> entry. Every name server that is going to reply
5624	authoritatively for the zone must have one of these entries.	5626	authoritatively for the zone must have one of these entries.
5625	The <literal>@</literal> as seen here could have been	5627	The <literal>@</literal> seen here could have been
5626	<hostid role="domainname">example.org.</hostid>	5628	<hostid role="domainname">example.org.</hostid>
5627	The <literal>@</literal> translates to the origin.	5629	The <literal>@</literal> translates to the origin.
5628	</para>	5630	</para>
Lines 5639-5645 Link Here
5639	<hostid>ns1.example.org</hostid> would resolve to	5641	<hostid>ns1.example.org</hostid> would resolve to
5640	<hostid role="ipaddr">3.2.1.2</hostid>. Again,	5642	<hostid role="ipaddr">3.2.1.2</hostid>. Again,
5641	the origin symbol, <literal>@</literal>, is	5643	the origin symbol, <literal>@</literal>, is
5642	used here, thus meaning <hostid>example.org</hostid>	5644	used here, meaning <hostid>example.org</hostid>
5643	would resolve to <hostid role="ipaddr">3.2.1.30</hostid>.	5645	would resolve to <hostid role="ipaddr">3.2.1.30</hostid>.
5644	</para>	5646	</para>
5645		5647
Lines 5649-5655 Link Here
5649	<para>	5651	<para>
5650	The canonical name record is usually used for giving aliases	5652	The canonical name record is usually used for giving aliases
5651	to a machine. In the example, <hostid>www</hostid> is	5653	to a machine. In the example, <hostid>www</hostid> is
5652	aliased to the machine addressed to the origin, or	5654	aliased to the origin, or
5653	<hostid>example.org</hostid>	5655	<hostid>example.org</hostid>
5654	(<hostid role="ipaddr">3.2.1.30</hostid>).	5656	(<hostid role="ipaddr">3.2.1.30</hostid>).
5655	<varname>CNAME</varname>s can be used to provide alias	5657	<varname>CNAME</varname>s can be used to provide alias
Lines 5664-5670 Link Here
5664	The <varname>MX</varname> record indicates which mail	5666	The <varname>MX</varname> record indicates which mail
5665	servers are responsible for handling incoming mail for the	5667	servers are responsible for handling incoming mail for the
5666	zone. <hostid role="fqdn">mail.example.org</hostid> is the	5668	zone. <hostid role="fqdn">mail.example.org</hostid> is the
5667	hostname of the mail server, and 10 being the priority of	5669	hostname of a mail server, and 10 is the priority of
5668	that mail server.	5670	that mail server.
5669	</para>	5671	</para>
5670		5672
Lines 5679-5685 Link Here
5679	<para>	5681	<para>
5680	For in-addr.arpa zone files (reverse DNS), the same format is	5682	For in-addr.arpa zone files (reverse DNS), the same format is
5681	used, except with <varname>PTR</varname> entries instead of	5683	used, except with <varname>PTR</varname> entries instead of
5682	<varname>A</varname> or <varname>CNAME</varname>.	5684	<varname>A</varname> and <varname>CNAME</varname>.
5683	</para>	5685	</para>
5684		5686
5685	<programlisting>$TTL 3600	5687	<programlisting>$TTL 3600
Lines 5699-5705 Link Here
5699	10 IN PTR mail.example.org.	5701	10 IN PTR mail.example.org.
5700	30 IN PTR example.org.</programlisting>	5702	30 IN PTR example.org.</programlisting>
5701	<para>	5703	<para>
5702	This file gives the proper IP address to hostname mappings of our above	5704	This file gives the proper IP address to hostname mappings for our above
5703	fictitious domain.	5705	fictitious domain.
5704	</para>	5706	</para>
5705	</sect3>	5707	</sect3>
Lines 5715-5721 Link Here
5715	A caching name server is a name server that is not	5717	A caching name server is a name server that is not
5716	authoritative for any zones. It simply asks queries of its own,	5718	authoritative for any zones. It simply asks queries of its own,
5717	and remembers them for later use. To set one up, just configure	5719	and remembers them for later use. To set one up, just configure
5718	the name server as usual, omitting any inclusions of zones.	5720	the name server as usual, omitting any master or slave zones.
5719	</para>	5721	</para>
5720	</sect2>	5722	</sect2>
5721		5723
Lines 5738-5747 Link Here
5738	and a group called <groupname>bind</groupname>, intended for this	5740	and a group called <groupname>bind</groupname>, intended for this
5739	use.</para>	5741	use.</para>
5740		5742
5741	<note><para>Various people would recommend that instead of configuring	5743	<note><para>Various people recommend that instead of configuring
5742	<application>named</application> to <command>chroot</command>, you	5744	<application>named</application> to <command>chroot</command>, you
5743	should run <application>named</application> inside a &man.jail.8;.	5745	should run <application>named</application> inside a &man.jail.8;.
5744	This section does not attempt to cover this situation.</para>	5746	This section does not attempt to cover this scenario.</para>
5745	</note>	5747	</note>
5746		5748
5747	<para>Since <application>named</application> will not be able to	5749	<para>Since <application>named</application> will not be able to
Lines 5768-5774 Link Here
5768	<calloutlist>	5770	<calloutlist>
5769	<callout arearefs="chown-slave">	5771	<callout arearefs="chown-slave">
5770	<para><application>named</application> only needs write access to	5772	<para><application>named</application> only needs write access to
5771	these directories, so that is all we give it.</para>	5773	these three directories, so that is all we give it control over.</para>
5772	</callout>	5774	</callout>
5773	</calloutlist>	5775	</calloutlist>
5774	</listitem>	5776	</listitem>
Lines 5844-5850 Link Here
5844	<para>If you are running &os; version 4.9-RELEASE or later, then	5846	<para>If you are running &os; version 4.9-RELEASE or later, then
5845	the copy of <command>named-xfer</command> in	5847	the copy of <command>named-xfer</command> in
5846	<filename>/usr/libexec</filename> is statically linked by default,	5848	<filename>/usr/libexec</filename> is statically linked by default,
5847	and you can simply use &man.cp.1; to copy it into your sandbox.</para>	5849	and you can simply use &man.cp.1; to copy it into your sandbox's <filename>bin</filename> directory.</para>
5848	</listitem>	5850	</listitem>
5849		5851
5850	<listitem>	5852	<listitem>
Lines 5896-5902 Link Here
5896	<para>Note that the configuration file	5898	<para>Note that the configuration file
5897	<replaceable>/etc/named.conf</replaceable> is denoted by a full	5899	<replaceable>/etc/named.conf</replaceable> is denoted by a full
5898	pathname <emphasis>relative to the sandbox</emphasis>, i.e. in	5900	pathname <emphasis>relative to the sandbox</emphasis>, i.e. in
5899	the line above, the file referred to is actually	5901	the line above, the file used is actually
5900	<filename>/etc/namedb/etc/named.conf</filename>.</para>	5902	<filename>/etc/namedb/etc/named.conf</filename>.</para>
5901	</note>	5903	</note>
5902	</listitem>	5904	</listitem>
Lines 5906-5912 Link Here
5906	<filename>/etc/namedb/etc/named.conf</filename> so that	5908	<filename>/etc/namedb/etc/named.conf</filename> so that
5907	<application>named</application> knows which zones to load and	5909	<application>named</application> knows which zones to load and
5908	where to find them on the disk. There follows a commented	5910	where to find them on the disk. There follows a commented
5909	example (anything not specifically commented here is no	5911	example (anything not specifically mentioned here is no
5910	different from the setup for a DNS server not running in a	5912	different from the setup for a DNS server not running in a
5911	sandbox):</para>	5913	sandbox):</para>
5912		5914
Lines 6014-6020 Link Here
6014	</para>	6016	</para>
6015		6017
6016	<tip><para>If a problem arises, keeping sources up to date and having a	6018	<tip><para>If a problem arises, keeping sources up to date and having a
6017	fresh build of named would not hurt.</para></tip>	6019	fresh build of named may help.</para></tip>
6018	</sect2>	6020	</sect2>
6019		6021
6020	<sect2>	6022	<sect2>
Lines 6026-6032 Link Here
6026	<itemizedlist>	6028	<itemizedlist>
6027	<listitem>	6029	<listitem>
6028	<para><ulink	6030	<para><ulink
6029	url="http://www.isc.org/products/BIND/">Official ISC Bind	6031	url="http://www.isc.org/products/BIND/">Official ISC BIND
6030	Page</ulink></para>	6032	Page</ulink></para>
6031	</listitem>	6033	</listitem>