[deployment-guide/comm-rel: 354/727] Updated the `options' statement description.
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 19 12:54:26 UTC 2010
commit 7ed2ae54304b2d719035e4669a8e7ede1f496705
Author: Jaromir Hradilek <jhradile at redhat.com>
Date: Thu Aug 12 19:12:21 2010 +0200
Updated the `options' statement description.
en-US/The_BIND_DNS_Server.xml | 495 ++++++++++++++++++-----------------------
1 files changed, 213 insertions(+), 282 deletions(-)
---
diff --git a/en-US/The_BIND_DNS_Server.xml b/en-US/The_BIND_DNS_Server.xml
index 78fd121..e49cfa2 100644
--- a/en-US/The_BIND_DNS_Server.xml
+++ b/en-US/The_BIND_DNS_Server.xml
@@ -393,14 +393,6 @@ options {
allow-query-cache { red-hats; };
};</screen>
</example>
- <!-- TODO: Move this admonition to the "options" statement description.
- <important>
- <title>Important</title>
- <para>
- It is recommended to restrict recursive DNS services for only a particular subset of clients via allow-query-cache option. Otherwise nameserver will be easy target for DDoS attack.
- </para>
- </important>
- -->
</listitem>
</varlistentry>
<varlistentry>
@@ -419,284 +411,223 @@ options {
</example>
</listitem>
</varlistentry>
- </variablelist>
- <section id="s3-bind-namedconf-state-opt">
- <title><command>options</command> Statement</title>
- <para>
- The <command>options</command> statement defines global server configuration options and sets defaults for other statements. It can be used to specify the location of the <command>named</command> working directory, the types of queries allowed, and much more.
- </para>
- <para>
- The <command>options</command> statement takes the following form:
- </para>
- <screen>options {
-<replaceable><option></replaceable>;
-[<replaceable><option></replaceable>; ...]
+ <varlistentry>
+ <term><command>options</command></term>
+ <listitem>
+ <para>
+ The <command>options</command> statement allows you to define global server configuration options as well as to set defaults for other statements. It can be used to specify the location of the <command>named</command> working directory, the types of queries allowed, and much more. It takes the following form:
+ </para>
+ <screen>options {
+ <replaceable>option</replaceable>;
+ ...
};</screen>
- <para>
- In this statement, the <replaceable><option></replaceable> directives are replaced with a valid option.
- </para>
- <para>
- The following are commonly used options:
- </para>
- <!-- RHEL5: ddomingo at redhat.com: replacement -->
- <variablelist>
- <varlistentry>
- <term><command>allow-query</command></term>
- <listitem>
- <para>
- Specifies which hosts are allowed to query this nameserver for authoritative RRs. By default, all hosts are allowed to query. An access control lists, or collection of IP addresses or networks, may be used here to allow only particular hosts to query the nameserver.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>allow-query-cache</command></term>
- <listitem>
- <para>
- Similar to <command>allow-query</command>, this option applies to non-authoritative data, like recursive queries. By default, only <command>localhost;</command> and <command>localnets;</command> are allowed to obtain non-authoritative data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>blackhole</command></term>
- <listitem>
- <para>
- Specifies which hosts are banned from the server. This option should be used when particular host or network floods the server with requests. Default is <command>none;</command>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>directory</command></term>
- <listitem>
- <para>
- Specifies the <command>named</command> working directory if different from the default value, <filename>/var/named/</filename>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>forwarders</command></term>
- <listitem>
- <para>
- Specifies a list of valid IP addresses for nameservers where requests should be forwarded for resolution.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>forward</command></term>
- <listitem>
- <para>
- Specifies the forwarding behavior of a <command>forwarders</command> directive.
- </para>
- <para>
- The following options are accepted:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <command>first</command> — Specifies that the nameservers listed in the <command>forwarders</command> directive be queried before <command>named</command> attempts to resolve the name itself.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>only</command> — Specifies that <command>named</command> does not attempt name resolution itself in the event that queries to nameservers specified in the <command>forwarders</command> directive fail.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>listen-on</command></term>
- <listitem>
- <para>
- Specifies the IPv4 network interface on which <command>named</command> listens for queries. By default, all IPv4 interfaces are used.
- </para>
- <para>
- Using this directive on a DNS server which also acts a gateway, BIND can be configured to only answer queries that originate from one of the networks.
- </para>
- <para>
- The following is an example of a <command>listen-on</command> directive:
- </para>
- <!-- RHEL5: ddomingo at redhat.com: above <para>replaces below
- <para>A <command>listen-on</command> directive looks like the following example:</para>
- -->
- <screen>options { listen-on { 10.0.1.1; }; };</screen>
- <para>
- In this example, server listens only on (<command>10.0.1.1</command>) address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>listen-on-v6</command></term>
- <listitem>
- <para>
- Same as <command>listen-on</command> except for IPv6 interfaces.
- </para>
- <para>
- The following is an example of a <command>listen-on-v6</command> directive:
- </para>
- <screen>options { listen-on-v6 { 1234:5678::9abc; }; };</screen>
- <para>
- In this example, server listens only on (<command>1234:5678::9abc</command>) address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>max-cache-size</command></term>
- <listitem>
- <para>
- Specifies the maximum amount of memory to use for server caches. When the amount of data in the cache reaches this limit, the server will cause records to expire prematurely so that the limit is not exceeded. In a server with multiple views, the limit applies separately to the cache of each view. Default is 32M.
- </para>
- <screen>options { max-cache-size 256M; };</screen>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>notify</command></term>
- <listitem>
- <para>
- Controls whether <command>named</command> notifies the slave servers when a zone is updated. It accepts the following options:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <command>yes</command> — Notifies slave servers.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>no</command> — Does not notify slave servers.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>master-only</command> - Send notify only when server is a master server for the zone.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>explicit</command> — Only notifies slave servers specified in an <command>also-notify</command> list within a zone statement.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>pid-file</command></term>
- <listitem>
- <para>
- Specifies the location of the process ID file created by <command>named</command>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>recursion</command></term>
- <listitem>
- <para>
- Specifies if <command>named</command> acts as a recursive server. The default is <command>yes</command>.
- </para>
- <screen>options { recursion no; };</screen>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>statistics-file</command></term>
- <listitem>
- <para>
- Specifies an alternate location for statistics files. By default, <command>named</command> statistics are saved to the <filename>/var/named/named.stats</filename> file.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>dnssec-enable</command></term>
- <listitem>
- <para>
- Specifies if <command>named</command> returns DNSSEC related RRs. The default is <command>yes</command>.
- </para>
- <screen>options { dnssec-enable yes; };</screen>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>dnssec-validation</command></term>
- <listitem>
+ <para>
+ For a list of frequently used <replaceable>option</replaceable> directives, see <xref linkend="table-bind-namedconf-common-options" /> below.
+ </para>
+ <table id="table-bind-namedconf-common-options">
+ <title>Commonly used options</title>
+ <tgroup cols="2">
+ <colspec colname="option" colnum="1" colwidth="20*" />
+ <colspec colname="description" colnum="2" colwidth="60*" />
+ <thead>
+ <row>
+ <entry>
+ Option
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <option>allow-query</option>
+ </entry>
+ <entry>
+ Specifies which hosts are allowed to query the nameserver for authoritative resource records. It accepts an access control lists, a collection of IP addresses, or networks in the CIDR notation. All hosts are allowed by default.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>allow-query-cache</option>
+ </entry>
+ <entry>
+ Specifies which hosts are allowed to query the nameserver for non-authoritative data such as recursive queries. Only <literal>localhost</literal> and <literal>localnets</literal> are allowed by default.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>blackhole</option>
+ </entry>
+ <entry>
+ Specifies which hosts are <emphasis>not</emphasis> allowed to query the nameserver. This option should be used when particular host or network floods the server with requests. The default option is <literal>none</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>directory</option>
+ </entry>
+ <entry>
+ Specifies a working directory for the <systemitem class="service">named</systemitem> service. The default option is <literal>/var/named/</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>dnssec-enable</option>
+ </entry>
+ <entry>
+ Specifies whether to return DNSSEC related resource records. The default option is <literal>yes</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>dnssec-validation</option>
+ </entry>
+ <entry>
+ Specifies whether to prove that resource records are authentic via DNSSEC. The default option is <command>yes</command>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>forwarders</option>
+ </entry>
+ <entry>
+ Specifies a list of valid IP addresses for nameservers to which the requests should be forwarded for resolution.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>forward</option>
+ </entry>
+ <entry>
+ <para>
+ Specifies the behavior of the <command>forwarders</command> directive. It accepts the following options:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>first</literal> — The server will query the nameservers listed in the <option>forwarders</option> directive before attempting to resolve the name on its own.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>only</literal> — When unable to query the nameservers listed in the <option>forwarders</option> directive, the server will not attempt to resolve the name on its own.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>listen-on</option>
+ </entry>
+ <entry>
+ Specifies the IPv4 network interface on which to listen for queries. On a DNS server that also acts as a gateway, you can use this option to answer queries originating from a single network only. All IPv4 interfaces are used by default.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>listen-on-v6</option>
+ </entry>
+ <entry>
+ Specifies the IPv6 network interface on which to listen for queries. On a DNS server that also acts as a gateway, you can use this option to answer queries originating from a single network only. All IPv6 interfaces are used by default.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>max-cache-size</option>
+ </entry>
+ <entry>
+ Specifies the maximum amount of memory to be used for server caches. When the limit is reached, the server causes records to expire prematurely so that the limit is not exceeded. In a server with multiple views, the limit applies separately to the cache of each view. The default option is <literal>32M</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>notify</option>
+ </entry>
+ <entry>
+ <para>
+ Specifies whether to notify the secondary nameservers when a zone is updated. It accepts the following options:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>yes</option> — The server will notify all secondary nameservers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>no</option> — The server will <emphasis>not</emphasis> notify any secondary nameserver.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>master-only</option> — The server will notify primary server for the zone only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>explicit</option> — The server will notify only the secondary servers that are specified in the <option>also-notify</option> list within a zone statement.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>pid-file</option>
+ </entry>
+ <entry>
+ Specifies the location of the process ID file created by the <systemitem class="service">named</systemitem> service.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>recursion</option>
+ </entry>
+ <entry>
+ Specifies whether to act as a recursive server. The default option is <literal>yes</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <option>statistics-file</option>
+ </entry>
+ <entry>
+ Specifies an alternate location for statistics files. The <filename>/var/named/named.stats</filename> file is used by default.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <important>
+ <title>Important: Restrict Recursive Servers to Selected Clients Only</title>
<para>
- Specifies if <command>named</command> should prove that RRs are authentic via DNSSEC. The default is <command>yes</command>.
+ To prevent distributed denial of service (DDoS) attacks, it is recommended that you use the <option>allow-query-cache</option> option to restrict recursive DNS services for a particular subset of clients only.
</para>
- <screen>options { dnssec-validation yes; };</screen>
- </listitem>
- </varlistentry>
- </variablelist>
- <!-- RHEL5: ddomingo at redhat.com: above <variablelist> replaces below <itemizedlist>:
- <itemizedlist>
- <listitem>
- <para><command>allow-query</command> — Specifies which hosts are allowed to query this nameserver. By default, all hosts are allowed to query. An access control list, or collection of IP addresses or networks may be used here to
- only allow particular hosts to query the nameserver.</para>
- </listitem>
- <listitem>
- <para><command>allow-recursion</command> — Similar to <command>allow-query</command>, this option applies to recursive queries. By default, all hosts are allowed to perform recursive queries on the nameserver.</para>
- </listitem>
- <listitem>
- <para><command>blackhole </command> — Specifies which hosts are not allowed to query the server.</para>
- </listitem>
- <listitem>
- <para><command>directory</command> — Specifies the <command>named</command> working directory if different from the default value, <filename>/var/named/</filename>.</para>
- </listitem>
- <listitem>
- <para><command>forward</command> — Specifies the forwarding behavior of a <command>forwarders</command> directive.</para>
- <para>The following options are accepted:</para>
- <itemizedlist>
- <listitem>
- <para><command>first</command> — Specifies that the nameservers listed in the <command>forwarders</command> directive be queried before <command>named</command> attempts to resolve the name itself.</para>
- </listitem>
- <listitem>
- <para><command>only</command> — Specifies that <command>named</command> does not attempt name resolution itself in the event queries to nameservers specified in the <command>forwarders</command>
- directive fail.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para><command>forwarders</command> — Specifies a list of valid IP addresses for nameservers where requests should be forwarded for resolution.</para>
- </listitem>
- <listitem>
- <para><command>listen-on</command> — Specifies the network interface on which <command>named</command> listens for queries. By default, all interfaces are used.</para>
- <para>Using this directive on a DNS server which also acts a gateway, BIND can be configured to only answer queries that originate from one of the networks.</para>
- <para>A <command>listen-on</command> directive looks like the following example:</para>
-<screen>
-<command>options { listen-on { 10.0.1.1; }; };</command>
-</screen>
- <para>In this example, only requests that arrive from the network interface serving the private network (<command>10.0.1.1</command>) are accepted.</para>
- </listitem>
- <listitem>
- <para><command>notify</command> — Controls whether <command>named</command> notifies the slave servers when a zone is updated. It accepts the following options:</para>
- <itemizedlist>
- <listitem>
- <para><command>yes</command> — Notifies slave servers.</para>
- </listitem>
- <listitem>
- <para><command>no</command> — Does not notify slave servers.</para>
- </listitem>
- <listitem>
- <para><command>explicit</command> — Only notifies slave servers specified in an <command>also-notify</command> list within a zone statement.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para><command>pid-file</command> — Specifies the location of the process ID file created by <command>named</command>.</para>
- </listitem>
- <listitem>
- <para><command>root-delegation-only</command> — Turns on the enforcement of delegation properties in top-level domains (TLDs) and root zones with an optional exclude list. <firstterm>Delegation</firstterm> is the process of
- separating a single zone into multiple subzones. In order to create a delegated zone, items known as <firstterm>NS records</firstterm> are used. NameServer records (delegation records) announce the authoritative nameservers for a particular zone.</para>
- <para>The following <command>root-delegation-only</command> example specifies an exclude list of TLDs from whom undelegated responses are expected and trusted:</para>
-<screen>
-<command>options { root-delegation-only exclude { "ad"; "ar"; "biz"; "cr"; "cu"; "de"; "dm"; "id; "lu"; "lv"; "md"; "ms"; "museum"; "name"; "no"; "pa"; "pf"; "se"; "sr"; "to"; "tw"; "us"; "uy"; }; };</command>
-</screen>
- </listitem>
- <listitem>
- <para><command>statistics-file</command> — Specifies an alternate location for statistics files. By default, <command>named</command> statistics are saved to the
- <filename>/var/named/named.stats</filename> file.</para>
+ </important>
+ <para>
+ Refer to the <citetitle>BIND 9 Administrator Reference Manual</citetitle> referenced in <xref linkend="s2-bind-installed-docs" />, and the <filename>named.conf</filename> manual page for a complete list of available options.
+ </para>
+ <example id="example-bind-namedconf-common-options">
+ <title>Using the <command>options</command> statement</title>
+ <screen>options {
+ allow-query { localhost; };
+ listen-on port 53 { 127.0.0.1; };
+ listen-on-v6 port 53 { ::1; };
+ max-cache-size 256M;
+ directory "/var/named";
+ statistics-file "/var/named/data/named_stats.txt";
+
+ recursion yes;
+ dnssec-enable yes;
+ dnssec-validation yes;
+};</screen>
+ </example>
</listitem>
- </itemizedlist>
- -->
- <para>
- <!-- RHEL5: Dozens of other options are --> There are many other options also available, many of which rely upon one another to work properly. Refer to the <citetitle>BIND 9 Administrator Reference Manual</citetitle> referenced in <xref linkend="s2-bind-installed-docs" /> and the <filename>named.conf</filename> man page for more details.
- </para>
- </section>
+ </varlistentry>
+ </variablelist>
<section id="s3-bind-namedconf-state-zone">
<title><command>zone</command> Statement</title>
<para>
More information about the docs-commits
mailing list