SPHINXBUILDDIR = $(builddir)/_build
+LF = \n
+RNDC_CONF = .. |rndc_conf| replace:: ``$(sysconfdir)/rndc.conf``
+RNDC_KEY = .. |rndc_key| replace:: ``$(sysconfdir)/rndc.key``
+NAMED_CONF = .. |named_conf| replace:: ``$(sysconfdir)/named.conf``
+BIND_KEYS = .. |bind_keys| replace:: ``$(sysconfdir)/bind.keys``
+NAMED_PID = .. |named_pid| replace:: ``$(runstatedir)/named.pid``
+SESSION_KEY = .. |session_key| replace:: ``$(runstatedir)/session.key``
+
+export RST_EPILOG = $(RNDC_CONF)$(LF)$(RNDC_KEY)$(LF)$(NAMED_CONF)$(LF)$(BIND_KEYS)$(LF)$(NAMED_PID)$(LF)$(SESSION_KEY)
+
common_SPHINXOPTS = \
-W \
-c $(srcdir) \
# The "today" variable set below is not directly used in the ARM, but its value
# is implicitly inserted on the title page of the PDF file produced by Sphinx.
-ALLSPHINXOPTS = \
- $(common_SPHINXOPTS) \
- -D today="$(RELEASE_DATE)" \
- $(SPHINXOPTS) \
+ALLSPHINXOPTS = \
+ $(common_SPHINXOPTS) \
+ -D today="$(RELEASE_DATE)" \
+ -D rst_epilog="$$(printf "$${RST_EPILOG}")" \
+ $(SPHINXOPTS) \
$(srcdir)
-man_SPHINXOPTS = \
- $(common_SPHINXOPTS) \
- -D version="@""PACKAGE_VERSION@"\
- -D today="@""RELEASE_DATE@" \
- -D release="@""PACKAGE_VERSION@"\
- $(SPHINXOPTS) \
+_ = @
+man_RNDC_CONF = .. |rndc_conf| replace:: ``$(_)sysconfdir$(_)/rndc.conf``
+man_RNDC_KEY = .. |rndc_key| replace:: ``$(_)sysconfdir$(_)/rndc.key``
+man_NAMED_CONF = .. |named_conf| replace:: ``$(_)sysconfdir$(_)/named.conf``
+man_BIND_KEYS = .. |bind_keys| replace:: ``$(_)sysconfdir$(_)/bind.keys``
+man_NAMED_PID = .. |named_pid| replace:: ``$(_)runstatedir$(_)/named.pid``
+man_SESSION_KEY = .. |session_key| replace:: ``$(_)runstatedir$(_)/session.key``
+
+export man_RST_EPILOG = $(man_RNDC_CONF)$(LF)$(man_RNDC_KEY)$(LF)$(man_NAMED_CONF)$(LF)$(man_BIND_KEYS)$(LF)$(man_NAMED_PID)$(LF)$(man_SESSION_KEY)
+
+man_SPHINXOPTS = \
+ $(common_SPHINXOPTS) \
+ -D version="@""PACKAGE_VERSION@" \
+ -D today="@""RELEASE_DATE@" \
+ -D release="@""PACKAGE_VERSION@" \
+ -D rst_epilog="$$(printf "$${man_RST_EPILOG}")" \
+ $(SPHINXOPTS) \
$(srcdir)
AM_V_SED = $(AM_V_SED_@AM_V@)
``named-checkconf`` checks the syntax, but not the semantics, of a
``named`` configuration file. The file, along with all files included by it, is parsed and checked for syntax
errors. If no file is specified,
-``/etc/named.conf`` is read by default.
+|named_conf| is read by default.
Note: files that ``named`` reads in separate parser contexts, such as
``rndc.key`` and ``bind.keys``, are not automatically read by
``filename``
This indicates the name of the configuration file to be checked. If not specified,
- it defaults to ``/etc/named.conf``.
+ it defaults to |named_conf|.
Return Values
~~~~~~~~~~~~~
~~~~~~~
``-a``
- This option sets automatic ``rndc`` configuration, which creates a file ``rndc.key``
- in ``/etc`` (or a different ``sysconfdir`` specified when BIND
- was built) that is read by both ``rndc`` and ``named`` on startup.
+ This option sets automatic ``rndc`` configuration, which creates a file
+ |rndc_key| that is read by both ``rndc`` and ``named`` on startup.
The ``rndc.key`` file defines a default command channel and
authentication key allowing ``rndc`` to communicate with ``named`` on
the local host with no further configuration.
``-a anchor-file``
This option specifies a file from which to read DNSSEC trust anchors. The default
- is ``/etc/bind.keys``, which is included with BIND 9 and contains one
+ is |bind_keys|, which is included with BIND 9 and contains one
or more trust anchors for the root zone (".").
Keys that do not match the root zone name are ignored. An alternate
``initial-key``, and ``static-key`` identically. That is, for a managed key,
it is the *initial* key that is trusted; :rfc:`5011` key management is not
supported. ``delv`` does not consult the managed-keys database maintained by
- ``named``, which means that if either of the keys in ``/etc/bind.keys`` is
- revoked and rolled over, ``/etc/bind.keys`` must be updated to
+ ``named``, which means that if either of the keys in |bind_keys| is
+ revoked and rolled over, |bind_keys| must be updated to
use DNSSEC validation in ``delv``.
``-b address``
Files
~~~~~
-``/etc/bind.keys``
+|bind_keys|
``/etc/resolv.conf``
Files
~~~~~
-``/etc/named.conf``
+|named_conf|
See Also
~~~~~~~~
:rfc:`1034`, and :rfc:`1035`.
When invoked without arguments, ``named`` reads the default
-configuration file ``/etc/named.conf``, reads any initial data, and
+configuration file |named_conf|, reads any initial data, and
listens for queries.
Options
``-c config-file``
This option tells ``named`` to use ``config-file`` as its configuration file instead of the default,
- ``/etc/named.conf``. To ensure that the configuration file
+ |named_conf|. To ensure that the configuration file
can be reloaded after the server has changed its working directory
due to to a possible ``directory`` option in the configuration file,
``config-file`` should be an absolute pathname.
Files
~~~~~
-``/etc/named.conf``
+|named_conf|
The default configuration file.
-``/var/run/named/named.pid``
+|named_pid|
The default process-id file.
See Also
TSIG relies on a shared secret that should only be known to ``nsupdate``
and the name server. For instance, suitable ``key`` and ``server``
-statements are added to ``/etc/named.conf`` so that the name server
+statements are added to |named_conf| so that the name server
can associate the appropriate secret key and algorithm with the IP
address of the client application that is using TSIG
authentication. ``ddns-confgen`` can generate suitable
This option sets local-host only mode, which sets the server address to localhost
(disabling the ``server`` so that the server address cannot be
overridden). Connections to the local server use a TSIG key
- found in ``/var/run/named/session.key``, which is automatically
+ found in |session_key|, which is automatically
generated by ``named`` if any local ``primary`` zone has set
``update-policy`` to ``local``. The location of this key file can be
overridden with the ``-k`` option.
``/etc/resolv.conf``
Used to identify the default name server
-``/var/run/named/session.key``
+|session_key|
Sets the default TSIG key for use in local-only mode
``K{name}.+157.+{random}.key``
::
- plugin query "/usr/local/lib/filter-a.so" {
+ plugin query "filter-a.so" {
filter-a-on-v6 yes;
filter-a-on-v4 yes;
filter-a { 192.0.2.1; 2001:db8:2::1; };
::
- plugin query "/usr/local/lib/filter-aaaa.so" {
+ plugin query "filter-aaaa.so" {
filter-aaaa-on-v4 yes;
filter-aaaa-on-v6 yes;
filter-aaaa { 192.0.2.1; 2001:db8:2::1; };
``-c config-file``
This option indicates ``config-file`` as the configuration file instead of the default,
- ``/etc/rndc.conf``.
+ |rndc_conf|.
``-k key-file``
This option indicates ``key-file`` as the key file instead of the default,
- ``/etc/rndc.key``. The key in ``/etc/rndc.key`` is used to
+ |rndc_key|. The key in |rndc_key| is used to
authenticate commands sent to the server if the config-file does not
exist.
]
latex_logo = "isc-logo.pdf"
+
+#
+# The rst_epilog will be completely overwritten from the Makefile,
+# the definition here is provided purely for situations when
+# sphinx-build is run by hand.
+#
+rst_epilog = """
+.. |rndc_conf| replace: ``/etc/rndc.conf``
+.. |rndc_key| replace: ``/etc/rndc.key``
+.. |named_conf| replace: ``/etc/named.conf``
+.. |bind_keys| replace: ``/etc/bind.keys``
+.. |named_pid| replace: ``/run/named.pid``
+.. |session_key| replace: ``/run/session.key``
+"""
// Two corporate subnets we wish to allow queries from.
acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
options {
- // Working directory
- directory "/etc/namedb";
-
allow-query { corpnets; };
};
// Provide a reverse mapping for the loopback
::
options {
- // Working directory
- directory "/etc/namedb";
// Do not allow access to cache
allow-query-cache { none; };
// This is the default
the server is authenticated with digital signatures that rely on a
shared secret, and there is no way to provide that secret other than
with a configuration file. The default location for the ``rndc``
- configuration file is ``/etc/rndc.conf``, but an alternate location
+ configuration file is |rndc_conf|, but an alternate location
can be specified with the ``-c`` option. If the configuration file is
- not found, ``rndc`` also looks in ``/etc/rndc.key`` (or whatever
+ not found, ``rndc`` also looks in |rndc_key| (or whatever
``sysconfdir`` was defined when the BIND build was configured). The
``rndc.key`` file is generated by running ``rndc-confgen -a`` as
described in :ref:`controls_statement_definition_and_usage`.
default-key rndc_key;
};
- This file, if installed as ``/etc/rndc.conf``, allows the
+ This file, if installed as |rndc_conf|, allows the
command:
``$ rndc reload``
control channel listening on the loopback address 127.0.0.1 and its IPv6
counterpart, ::1. In this case, and also when the ``controls`` statement
is present but does not have a ``keys`` clause, ``named`` attempts
-to load the command channel key from the file ``rndc.key`` in ``/etc``
-(or whatever ``sysconfdir`` was specified when BIND was built). To
-create an ``rndc.key`` file, run ``rndc-confgen -a``.
+to load the command channel key from the file |rndc_key|.
+To create an ``rndc.key`` file, run ``rndc-confgen -a``.
To disable the command channel, use an empty ``controls`` statement:
``controls { };``.
``pid-file``
This is the pathname of the file the server writes its process ID in. If not
- specified, the default is ``/var/run/named/named.pid``. The PID file
+ specified, the default is |named_pid|. The PID file
is used by programs that send signals to the running name
server. Specifying ``pid-file none`` disables the use of a PID file;
no file is written and any existing one is removed. Note
``bindkeys-file``
This is the pathname of a file to override the built-in trusted keys provided
by ``named``. See the discussion of ``dnssec-validation`` for
- details. If not specified, the default is ``/etc/bind.keys``.
+ details. If not specified, the default is |bind_keys|.
``secroots-file``
This is the pathname of the file the server dumps security roots to, when
``session-keyfile``
This is the pathname of the file into which to write a TSIG session key
generated by ``named`` for use by ``nsupdate -l``. If not specified,
- the default is ``/var/run/named/session.key``. (See :ref:`dynamic_update_policies`,
+ the default is |session_key|. (See :ref:`dynamic_update_policies`,
and in particular the discussion of the ``update-policy`` statement's
``local`` option, for more information about this feature.)
generates a TSIG session key when starting and stores it in a file;
this key can then be used by local clients to update the zone while
``named`` is running. By default, the session key is stored in the file
-``/var/run/named/session.key``, the key name is "local-ddns", and the
+|session_key|, the key name is "local-ddns", and the
key algorithm is HMAC-SHA256. These values are configurable with the
``session-keyfile``, ``session-keyname``, and ``session-keyalg`` options,
respectively. A client running on the local system, if run with
$(AM_V_SED)$(SED) \
-e 's,[@]PACKAGE_VERSION@,$(PACKAGE_VERSION),' \
-e 's,[@]RELEASE_DATE@,$(RELEASE_DATE),' \
+ -e 's,[@]libdir[@],$(libdir),g' \
+ -e 's,[@]runstatedir[@],$(runstatedir),g' \
+ -e 's,[@]sysconfdir[@],$(sysconfdir),g' \
$(srcdir)/$@in >$@
.1in.1:
manpages.stamp: $(MANPAGES_RST)
@rm -f manpages.tmp
@touch manpages.tmp
+ echo "${man_RST_EPILOG}"
$(AM_V_SPHINX)$(SPHINX_BUILD) -b man -d $(SPHINXBUILDDIR)/.doctrees/man $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man
for f in $(SPHINXBUILDDIR)/man/*; do \
cp -a "$$f" "$(srcdir)/$$(basename $$f)in"; \
('rndc', 'rndc', 'name server control utility', author, 8),
('tsig-keygen', 'tsig-keygen', 'TSIG key generation tool', author, 8),
]
+
+#
+# The rst_epilog will be completely overwritten from the Makefile,
+# the definition here is provided purely for situations when
+# sphinx-build is run by hand.
+#
+rst_epilog = """
+.. |rndc_conf| replace: ``@sysconfdir@/rndc.conf``
+.. |rndc_key| replace: ``@sysconfdir@/rndc.key``
+.. |named_conf| replace: ``@sysconfdir@/named.conf``
+.. |bind_keys| replace: ``@sysconfdir@/bind.keys``
+.. |named_pid| replace: ``@runstatedir@/named.pid``
+.. |session_key| replace: ``@runstatedir@/session.key``
+"""
.TP
.B \fB\-a anchor\-file\fP
This option specifies a file from which to read DNSSEC trust anchors. The default
-is \fB/etc/bind.keys\fP, which is included with BIND 9 and contains one
+is \fB@sysconfdir@/bind.keys\fP, which is included with BIND 9 and contains one
or more trust anchors for the root zone (".").
.sp
Keys that do not match the root zone name are ignored. An alternate
\fBinitial\-key\fP, and \fBstatic\-key\fP identically. That is, for a managed key,
it is the \fIinitial\fP key that is trusted; \fI\%RFC 5011\fP key management is not
supported. \fBdelv\fP does not consult the managed\-keys database maintained by
-\fBnamed\fP, which means that if either of the keys in \fB/etc/bind.keys\fP is
-revoked and rolled over, \fB/etc/bind.keys\fP must be updated to
+\fBnamed\fP, which means that if either of the keys in \fB@sysconfdir@/bind.keys\fP is
+revoked and rolled over, \fB@sysconfdir@/bind.keys\fP must be updated to
use DNSSEC validation in \fBdelv\fP\&.
.TP
.B \fB\-b address\fP
.UNINDENT
.SH FILES
.sp
-\fB/etc/bind.keys\fP
+\fB@sysconfdir@/bind.keys\fP
.sp
\fB/etc/resolv.conf\fP
.SH SEE ALSO
.sp
.nf
.ft C
-plugin query "/usr/local/lib/filter\-a.so" {
+plugin query "filter\-a.so" {
filter\-a\-on\-v6 yes;
filter\-a\-on\-v4 yes;
filter\-a { 192.0.2.1; 2001:db8:2::1; };
.sp
.nf
.ft C
-plugin query "/usr/local/lib/filter\-aaaa.so" {
+plugin query "filter\-aaaa.so" {
filter\-aaaa\-on\-v4 yes;
filter\-aaaa\-on\-v6 yes;
filter\-aaaa { 192.0.2.1; 2001:db8:2::1; };
\fBnamed\-checkconf\fP checks the syntax, but not the semantics, of a
\fBnamed\fP configuration file. The file, along with all files included by it, is parsed and checked for syntax
errors. If no file is specified,
-\fB/etc/named.conf\fP is read by default.
+\fB@sysconfdir@/named.conf\fP is read by default.
.sp
Note: files that \fBnamed\fP reads in separate parser contexts, such as
\fBrndc.key\fP and \fBbind.keys\fP, are not automatically read by
.TP
.B \fBfilename\fP
This indicates the name of the configuration file to be checked. If not specified,
-it defaults to \fB/etc/named.conf\fP\&.
+it defaults to \fB@sysconfdir@/named.conf\fP\&.
.UNINDENT
.SH RETURN VALUES
.sp
\fI\%RFC 1034\fP, and \fI\%RFC 1035\fP\&.
.sp
When invoked without arguments, \fBnamed\fP reads the default
-configuration file \fB/etc/named.conf\fP, reads any initial data, and
+configuration file \fB@sysconfdir@/named.conf\fP, reads any initial data, and
listens for queries.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-c config\-file\fP
This option tells \fBnamed\fP to use \fBconfig\-file\fP as its configuration file instead of the default,
-\fB/etc/named.conf\fP\&. To ensure that the configuration file
+\fB@sysconfdir@/named.conf\fP\&. To ensure that the configuration file
can be reloaded after the server has changed its working directory
due to to a possible \fBdirectory\fP option in the configuration file,
\fBconfig\-file\fP should be an absolute pathname.
.SH FILES
.INDENT 0.0
.TP
-.B \fB/etc/named.conf\fP
+.B \fB@sysconfdir@/named.conf\fP
The default configuration file.
.TP
-.B \fB/var/run/named/named.pid\fP
+.B \fB@runstatedir@/named.pid\fP
The default process\-id file.
.UNINDENT
.SH SEE ALSO
.UNINDENT
.SH FILES
.sp
-\fB/etc/named.conf\fP
+\fB@sysconfdir@/named.conf\fP
.SH SEE ALSO
.sp
\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBrndc(8)\fP, \fBrndc\-confgen(8)\fP, \fBtsig\-keygen(8)\fP, BIND 9 Administrator Reference Manual.
.sp
TSIG relies on a shared secret that should only be known to \fBnsupdate\fP
and the name server. For instance, suitable \fBkey\fP and \fBserver\fP
-statements are added to \fB/etc/named.conf\fP so that the name server
+statements are added to \fB@sysconfdir@/named.conf\fP so that the name server
can associate the appropriate secret key and algorithm with the IP
address of the client application that is using TSIG
authentication. \fBddns\-confgen\fP can generate suitable
This option sets local\-host only mode, which sets the server address to localhost
(disabling the \fBserver\fP so that the server address cannot be
overridden). Connections to the local server use a TSIG key
-found in \fB/var/run/named/session.key\fP, which is automatically
+found in \fB@runstatedir@/session.key\fP, which is automatically
generated by \fBnamed\fP if any local \fBprimary\fP zone has set
\fBupdate\-policy\fP to \fBlocal\fP\&. The location of this key file can be
overridden with the \fB\-k\fP option.
.B \fB/etc/resolv.conf\fP
Used to identify the default name server
.TP
-.B \fB/var/run/named/session.key\fP
+.B \fB@runstatedir@/session.key\fP
Sets the default TSIG key for use in local\-only mode
.TP
.B \fBK{name}.+157.+{random}.key\fP
.INDENT 0.0
.TP
.B \fB\-a\fP
-This option sets automatic \fBrndc\fP configuration, which creates a file \fBrndc.key\fP
-in \fB/etc\fP (or a different \fBsysconfdir\fP specified when BIND
-was built) that is read by both \fBrndc\fP and \fBnamed\fP on startup.
+This option sets automatic \fBrndc\fP configuration, which creates a file
+\fB@sysconfdir@/rndc.key\fP that is read by both \fBrndc\fP and \fBnamed\fP on startup.
The \fBrndc.key\fP file defines a default command channel and
authentication key allowing \fBrndc\fP to communicate with \fBnamed\fP on
the local host with no further configuration.
.TP
.B \fB\-c config\-file\fP
This option indicates \fBconfig\-file\fP as the configuration file instead of the default,
-\fB/etc/rndc.conf\fP\&.
+\fB@sysconfdir@/rndc.conf\fP\&.
.TP
.B \fB\-k key\-file\fP
This option indicates \fBkey\-file\fP as the key file instead of the default,
-\fB/etc/rndc.key\fP\&. The key in \fB/etc/rndc.key\fP is used to
+\fB@sysconfdir@/rndc.key\fP\&. The key in \fB@sysconfdir@/rndc.key\fP is used to
authenticate commands sent to the server if the config\-file does not
exist.
.TP
Files
~~~~~
-``/etc/named.conf``
+|named_conf|
See Also
~~~~~~~~
projects / thirdparty / bind9.git / commitdiff
