upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-06-10 22:39:58 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Use semantic markup for :program: self-references

Browse source 
Sphinx has it's own :program: syntax for refering to program names.
Use it for self-references in manual pages. These self-references are
not clickable and not as eye-cathing as links, which is a good thing.
There is no point in attracting attention to ``dig`` several times on a
single page dedicated to dig itself.

Substituted automatically using:
    find bin  -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh

With /tmp/repl.sh being:
    BASE=$(basename "$1" .rst)
    sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"

(cherry picked from commit c7085be211)
This commit is contained in:
Petr Špaček 2022-03-03 16:00:43 +01:00
parent d13066ca5b
commit 52a20d646d
No known key found for this signature in database
GPG key ID: ABD587CDF06581AE
30 changed files with 231 additions and 231 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
bin/check/named-checkconf.rst
View file

@ -26,16 +26,16 @@ Synopsis
Description
~~~~~~~~~~~
``named-checkconf`` checks the syntax, but not the semantics, of a
:program:`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,
|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
``named-checkconf``. Configuration errors in these files may cause
``named`` to fail to run, even if ``named-checkconf`` was successful.
However, ``named-checkconf`` can be run on these files explicitly.
:program:`named-checkconf`. Configuration errors in these files may cause
``named`` to fail to run, even if :program:`named-checkconf` was successful.
However, :program:`named-checkconf` can be run on these files explicitly.
Options
~~~~~~~
@ -76,7 +76,7 @@ Options
.. option:: -v
This option prints the version of the ``named-checkconf`` program and exits.
This option prints the version of the :program:`named-checkconf` program and exits.
.. option:: -x
@ -99,7 +99,7 @@ Options
Return Values
~~~~~~~~~~~~~
``named-checkconf`` returns an exit status of 1 if errors were detected
:program:`named-checkconf` returns an exit status of 1 if errors were detected
and 0 otherwise.
See Also

10
bin/check/named-checkzone.rst
View file

@ -28,9 +28,9 @@ Synopsis
Description
~~~~~~~~~~~
``named-checkzone`` checks the syntax and integrity of a zone file. It
:program:`named-checkzone` checks the syntax and integrity of a zone file. It
performs the same checks as ``named`` does when loading a zone. This
makes ``named-checkzone`` useful for checking zone files before
makes :program:`named-checkzone` useful for checking zone files before
configuring them into a name server.
Options
@ -51,7 +51,7 @@ Options
.. option:: -v
This option prints the version of the ``named-checkzone`` program and exits.
This option prints the version of the :program:`named-checkzone` program and exits.
.. option:: -j
@ -103,7 +103,7 @@ Options
.. option:: -F format
This option specifies the format of the output file specified. For
``named-checkzone``, this does not have any effect unless it dumps
:program:`named-checkzone`, this does not have any effect unless it dumps
the zone contents.
Possible formats are ``text`` (the default), which is the standard
@ -212,7 +212,7 @@ Options
Return Values
~~~~~~~~~~~~~
``named-checkzone`` returns an exit status of 1 if errors were detected
:program:`named-checkzone` returns an exit status of 1 if errors were detected
and 0 otherwise.
See Also

8
bin/check/named-compilezone.rst
View file

@ -28,7 +28,7 @@ Synopsis
Description
~~~~~~~~~~~
``named-compilezone`` checks the syntax and integrity of a zone file,
:program:`named-compilezone` checks the syntax and integrity of a zone file,
and dumps the zone contents to a specified file in a specified format.
It applies strict check levels by default, since the
dump output is used as an actual zone file loaded by ``named``.
@ -152,7 +152,7 @@ Options
.. option:: -o filename
This option writes the zone output to ``filename``. If ``filename`` is ``-``, then
the zone output is written to standard output. This is mandatory for ``named-compilezone``.
the zone output is written to standard output. This is mandatory for :program:`named-compilezone`.
.. option:: -r mode
@ -194,7 +194,7 @@ Options
.. option:: -D
This option dumps the zone file in canonical format. This is always enabled for
``named-compilezone``.
:program:`named-compilezone`.
.. option:: -W mode
@ -214,7 +214,7 @@ Options
Return Values
~~~~~~~~~~~~~
``named-compilezone`` returns an exit status of 1 if errors were detected
:program:`named-compilezone` returns an exit status of 1 if errors were detected
and 0 otherwise.
See Also

4
bin/confgen/ddns-confgen.rst
View file

@ -27,7 +27,7 @@ Synopsis
Description
~~~~~~~~~~~
``ddns-confgen`` is an utility that generates keys for use in TSIG signing.
:program:`ddns-confgen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
to a zone, or for the ``rndc`` command channel.
@ -40,7 +40,7 @@ command-channel security.)
Note that ``named`` itself can configure a local DDNS key for use with
:option:`nsupdate -l`; it does this when a zone is configured with
``update-policy local;``. ``ddns-confgen`` is only needed when a more
``update-policy local;``. :program:`ddns-confgen` is only needed when a more
elaborate configuration is required: for instance, if ``nsupdate`` is to
be used from a remote system.

8
bin/confgen/rndc-confgen.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``rndc-confgen`` generates configuration files for ``rndc``. It can be
:program:`rndc-confgen` generates configuration files for ``rndc``. It can be
used as a convenient alternative to writing the ``rndc.conf`` file and
the corresponding ``controls`` and ``key`` statements in ``named.conf``
by hand. Alternatively, it can be run with the :option:`-a` option to set up a
@ -46,7 +46,7 @@ Options
If a more elaborate configuration than that generated by
:option:`rndc-confgen -a` is required, for example if rndc is to be used
remotely, run ``rndc-confgen`` without the :option:`-a` option
remotely, run :program:`rndc-confgen` without the :option:`-a` option
and set up ``rndc.conf`` and ``named.conf`` as directed.
.. option:: -A algorithm
@ -68,7 +68,7 @@ Options
.. option:: -h
This option prints a short summary of the options and arguments to
``rndc-confgen``.
:program:`rndc-confgen`.
.. option:: -k keyname
@ -113,7 +113,7 @@ To allow ``rndc`` to be used with no manual configuration, run:
To print a sample ``rndc.conf`` file and the corresponding ``controls`` and
``key`` statements to be manually inserted into ``named.conf``, run:
``rndc-confgen``
:program:`rndc-confgen`
See Also
~~~~~~~~

2
bin/confgen/tsig-keygen.rst
View file

@ -27,7 +27,7 @@ Synopsis
Description
~~~~~~~~~~~
``tsig-keygen`` is an utility that generates keys for use in TSIG signing.
:program:`tsig-keygen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
to a zone, or for the ``rndc`` command channel.

60
bin/delv/delv.rst
View file

@ -32,10 +32,10 @@ Synopsis
Description
~~~~~~~~~~~
``delv`` is a tool for sending DNS queries and validating the results,
:program:`delv` is a tool for sending DNS queries and validating the results,
using the same internal resolver and validator logic as ``named``.
``delv`` sends to a specified name server all queries needed to
:program:`delv` sends to a specified name server all queries needed to
fetch and validate the requested data; this includes the original
requested query, subsequent queries to follow CNAME or DNAME chains,
queries for DNSKEY, and DS records to establish a chain of trust for
@ -44,25 +44,25 @@ simulates the behavior of a name server configured for DNSSEC validating
and forwarding.
By default, responses are validated using the built-in DNSSEC trust anchor
for the root zone ("."). Records returned by ``delv`` are either fully
for the root zone ("."). Records returned by :program:`delv` are either fully
validated or were not signed. If validation fails, an explanation of the
failure is included in the output; the validation process can be traced
in detail. Because ``delv`` does not rely on an external server to carry
in detail. Because :program:`delv` does not rely on an external server to carry
out validation, it can be used to check the validity of DNS responses in
environments where local name servers may not be trustworthy.
Unless it is told to query a specific name server, ``delv`` tries
Unless it is told to query a specific name server, :program:`delv` tries
each of the servers listed in ``/etc/resolv.conf``. If no usable server
addresses are found, ``delv`` sends queries to the localhost
addresses are found, :program:`delv` sends queries to the localhost
addresses (127.0.0.1 for IPv4, ::1 for IPv6).
When no command-line arguments or options are given, ``delv``
When no command-line arguments or options are given, :program:`delv`
performs an NS query for "." (the root zone).
Simple Usage
~~~~~~~~~~~~
A typical invocation of ``delv`` looks like:
A typical invocation of :program:`delv` looks like:
::
@ -75,15 +75,15 @@ where:
is the name or IP address of the name server to query. This can be an
IPv4 address in dotted-decimal notation or an IPv6 address in
colon-delimited notation. When the supplied ``server`` argument is a
hostname, ``delv`` resolves that name before querying that name
hostname, :program:`delv` resolves that name before querying that name
server (note, however, that this initial lookup is *not* validated by
DNSSEC).
If no ``server`` argument is provided, ``delv`` consults
If no ``server`` argument is provided, :program:`delv` consults
``/etc/resolv.conf``; if an address is found there, it queries the
name server at that address. If either of the :option:`-4` or :option:`-6`
options is in use, then only addresses for the corresponding
transport are tried. If no usable addresses are found, ``delv``
transport are tried. If no usable addresses are found, :program:`delv`
sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1
for IPv6).
@ -95,7 +95,7 @@ where:
indicates what type of query is required - ANY, A, MX, etc.
``type`` can be any valid query type. If no ``type`` argument is
supplied, ``delv`` performs a lookup for an A record.
supplied, :program:`delv` performs a lookup for an A record.
Options
~~~~~~~
@ -109,13 +109,13 @@ Options
Keys that do not match the root zone name are ignored. An alternate
key name can be specified using the ``+root=NAME`` options.
Note: When reading the trust anchor file, ``delv`` treats ``trust-anchors``,
Note: When reading the trust anchor file, :program:`delv` treats ``trust-anchors``,
``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
supported. :program:`delv` does not consult the managed-keys database maintained by
``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``.
use DNSSEC validation in :program:`delv`.
.. option:: -b address
@ -127,26 +127,26 @@ Options
.. option:: -c class
This option sets the query class for the requested data. Currently, only class
"IN" is supported in ``delv`` and any other value is ignored.
"IN" is supported in :program:`delv` and any other value is ignored.
.. option:: -d level
This option sets the systemwide debug level to ``level``. The allowed range is
from 0 to 99. The default is 0 (no debugging). Debugging traces from
``delv`` become more verbose as the debug level increases. See the
:program:`delv` become more verbose as the debug level increases. See the
``+mtrace``, ``+rtrace``, and ``+vtrace`` options below for
additional debugging details.
.. option:: -h
This option displays the ``delv`` help usage output and exits.
This option displays the :program:`delv` help usage output and exits.
.. option:: -i
This option sets insecure mode, which disables internal DNSSEC validation. (Note,
however, that this does not set the CD bit on upstream queries. If the
server being queried is performing DNSSEC validation, then it does
not return invalid data; this can cause ``delv`` to time out. When it
not return invalid data; this can cause :program:`delv` to time out. When it
is necessary to examine invalid data to debug a DNSSEC problem, use
``dig +cd``.)
@ -182,30 +182,30 @@ Options
.. option:: -v
This option prints the ``delv`` version and exits.
This option prints the :program:`delv` version and exits.
.. option:: -x addr
This option performs a reverse lookup, mapping an address to a name. ``addr``
is an IPv4 address in dotted-decimal notation, or a colon-delimited
IPv6 address. When :option:`-x` is used, there is no need to provide the
``name`` or ``type`` arguments; ``delv`` automatically performs a
``name`` or ``type`` arguments; :program:`delv` automatically performs a
lookup for a name like ``11.12.13.10.in-addr.arpa`` and sets the
query type to PTR. IPv6 addresses are looked up using nibble format
under the IP6.ARPA domain.
.. option:: -4
This option forces ``delv`` to only use IPv4.
This option forces :program:`delv` to only use IPv4.
.. option:: -6
This option forces ``delv`` to only use IPv6.
This option forces :program:`delv` to only use IPv6.
Query Options
~~~~~~~~~~~~~
``delv`` provides a number of query options which affect the way results
:program:`delv` provides a number of query options which affect the way results
are displayed, and in some cases the way lookups are performed.
Each query option is identified by a keyword preceded by a plus sign
@ -217,11 +217,11 @@ assign values to options like the timeout interval. They have the form
.. option:: +[no]cdflag
This option controls whether to set the CD (checking disabled) bit in queries
sent by ``delv``. This may be useful when troubleshooting DNSSEC
sent by :program:`delv`. This may be useful when troubleshooting DNSSEC
problems from behind a validating resolver. A validating resolver
blocks invalid responses, making it difficult to retrieve them
for analysis. Setting the CD flag on queries causes the resolver
to return invalid responses, which ``delv`` can then validate
to return invalid responses, which :program:`delv` can then validate
internally and report the errors in detail.
.. option:: +[no]class
@ -237,7 +237,7 @@ assign values to options like the timeout interval. They have the form
.. option:: +[no]rtrace
This option toggles resolver fetch logging. This reports the name and type of each
query sent by ``delv`` in the process of carrying out the resolution
query sent by :program:`delv` in the process of carrying out the resolution
and validation process, including the original query
and all subsequent queries to follow CNAMEs and to establish a chain
of trust for DNSSEC validation.
@ -250,7 +250,7 @@ assign values to options like the timeout interval. They have the form
.. option:: +[no]mtrace
This option toggles message logging. This produces a detailed dump of the
responses received by ``delv`` in the process of carrying out the
responses received by :program:`delv` in the process of carrying out the
resolution and validation process.
This is equivalent to setting the debug level to 10 for the "packets"
@ -317,11 +317,11 @@ assign values to options like the timeout interval. They have the form
This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a
verbose multi-line format with human-readable comments. The default
is to print each record on a single line, to facilitate machine
parsing of the ``delv`` output.
parsing of the :program:`delv` output.
.. option:: +[no]dnssec
This option indicates whether to display RRSIG records in the ``delv`` output.
This option indicates whether to display RRSIG records in the :program:`delv` output.
The default is to do so. Note that (unlike in ``dig``) this does
*not* control whether to request DNSSEC records or to
validate them. DNSSEC records are always requested, and validation

66
bin/dig/dig.rst
View file

@ -29,28 +29,28 @@ Synopsis
Description
~~~~~~~~~~~
``dig`` is a flexible tool for interrogating DNS name servers. It
:program:`dig` is a flexible tool for interrogating DNS name servers. It
performs DNS lookups and displays the answers that are returned from the
name server(s) that were queried. Most DNS administrators use ``dig`` to
name server(s) that were queried. Most DNS administrators use :program:`dig` to
troubleshoot DNS problems because of its flexibility, ease of use, and
clarity of output. Other lookup tools tend to have less functionality
than ``dig``.
than :program:`dig`.
Although ``dig`` is normally used with command-line arguments, it also
Although :program:`dig` is normally used with command-line arguments, it also
has a batch mode of operation for reading lookup requests from a file. A
brief summary of its command-line arguments and options is printed when
the :option:`-h` option is given. The BIND 9
implementation of ``dig`` allows multiple lookups to be issued from the
implementation of :program:`dig` allows multiple lookups to be issued from the
command line.
Unless it is told to query a specific name server, ``dig`` tries each
Unless it is told to query a specific name server, :program:`dig` tries each
of the servers listed in ``/etc/resolv.conf``. If no usable server
addresses are found, ``dig`` sends the query to the local host.
addresses are found, :program:`dig` sends the query to the local host.
When no command-line arguments or options are given, ``dig``
When no command-line arguments or options are given, :program:`dig`
performs an NS query for "." (the root).
It is possible to set per-user defaults for ``dig`` via
It is possible to set per-user defaults for :program:`dig` via
``${HOME}/.digrc``. This file is read and any options in it are applied
before the command-line arguments. The :option:`-r` option disables this
feature, for scripts that need predictable behavior.
@ -63,7 +63,7 @@ class, use the :option:`-q` to specify the domain name, or use "IN." and
Simple Usage
~~~~~~~~~~~~
A typical invocation of ``dig`` looks like:
A typical invocation of :program:`dig` looks like:
::
@ -76,14 +76,14 @@ where:
is the name or IP address of the name server to query. This can be an
IPv4 address in dotted-decimal notation or an IPv6 address in
colon-delimited notation. When the supplied ``server`` argument is a
hostname, ``dig`` resolves that name before querying that name
hostname, :program:`dig` resolves that name before querying that name
server.
If no ``server`` argument is provided, ``dig`` consults
If no ``server`` argument is provided, :program:`dig` consults
``/etc/resolv.conf``; if an address is found there, it queries the
name server at that address. If either of the :option:`-4` or :option:`-6`
options are in use, then only addresses for the corresponding
transport are tried. If no usable addresses are found, ``dig``
transport are tried. If no usable addresses are found, :program:`dig`
sends the query to the local host. The reply from the name server
that responds is displayed.
@ -95,7 +95,7 @@ where:
indicates what type of query is required - ANY, A, MX, SIG, etc.
``type`` can be any valid query type. If no ``type`` argument is
supplied, ``dig`` performs a lookup for an A record.
supplied, :program:`dig` performs a lookup for an A record.
Options
~~~~~~~
@ -121,9 +121,9 @@ Options
.. option:: -f file
This option sets batch mode, in which ``dig`` reads a list of lookup requests to process from
This option sets batch mode, in which :program:`dig` reads a list of lookup requests to process from
the given ``file``. Each line in the file should be organized in the
same way it would be presented as a query to ``dig`` using the
same way it would be presented as a query to :program:`dig` using the
command-line interface.
.. option:: -h
@ -134,7 +134,7 @@ Options
This option tells ``named`` to sign queries using TSIG using a key read from the given file. Key
files can be generated using ``tsig-keygen``. When using TSIG
authentication with ``dig``, the name server that is queried needs to
authentication with :program:`dig`, the name server that is queried needs to
know the key and algorithm that is being used. In BIND, this is done
by providing appropriate ``key`` and ``server`` statements in
``named.conf``.
@ -190,7 +190,7 @@ Options
``addr`` is an IPv4 address in dotted-decimal notation, or a
colon-delimited IPv6 address. When the :option:`-x` option is used, there is no
need to provide the ``name``, ``class``, and ``type`` arguments.
``dig`` automatically performs a lookup for a name like
:program:`dig` automatically performs a lookup for a name like
``94.2.0.192.in-addr.arpa`` and sets the query type and class to PTR
and IN respectively. IPv6 addresses are looked up using nibble format
under the IP6.ARPA domain.
@ -213,7 +213,7 @@ Options
Query Options
~~~~~~~~~~~~~
``dig`` provides a number of query options which affect the way in which
:program:`dig` provides a number of query options which affect the way in which
lookups are made and the results displayed. Some of these set or reset
flag bits in the query header, some determine which sections of the
answer get printed, and others determine the timeout and retry
@ -292,7 +292,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
.. option:: +[no]cmd
This option toggles the printing of the initial comment in the output, identifying the
version of ``dig`` and the query options that have been applied. This option
version of :program:`dig` and the query options that have been applied. This option
always has a global effect; it cannot be set globally and then overridden on a
per-lookup basis. The default is to print this comment.
@ -437,7 +437,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
``IDN SUPPORT`` to have been enabled at compile time.
The default is to process IDN input when standard output is a tty.
The IDN processing on input is disabled when ``dig`` output is redirected
The IDN processing on input is disabled when :program:`dig` output is redirected
to files, pipes, and other non-tty file descriptors.
.. option:: +[no]idnout
@ -446,7 +446,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
``IDN SUPPORT`` to have been enabled at compile time.
The default is to process puny code on output when standard output is
a tty. The puny code processing on output is disabled when ``dig`` output
a tty. The puny code processing on output is disabled when :program:`dig` output
is redirected to files, pipes, and other non-tty file descriptors.
.. option:: +[no]ignore
@ -468,7 +468,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
This option prints [or does not print] records, like the SOA records, in a verbose multi-line format
with human-readable comments. The default is to print each record on
a single line to facilitate machine parsing of the ``dig`` output.
a single line to facilitate machine parsing of the :program:`dig` output.
.. option:: +ndots=D
@ -486,7 +486,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
.. option:: +[no]nssearch
When this option is set, ``dig`` attempts to find the authoritative
When this option is set, :program:`dig` attempts to find the authoritative
name servers for the zone containing the name being looked up, and
display the SOA record that each name server has for the zone.
Addresses of servers that did not respond are also printed.
@ -538,7 +538,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
.. option:: +[no]recurse
This option toggles the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means ``dig`` normally sends
This bit is set by default, which means :program:`dig` normally sends
recursive queries. Recursion is automatically disabled when the
``+nssearch`` or ``+trace`` query option is used.
@ -641,7 +641,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
This option toggles tracing of the delegation path from the root name servers for
the name being looked up. Tracing is disabled by default. When
tracing is enabled, ``dig`` makes iterative queries to resolve the
tracing is enabled, :program:`dig` makes iterative queries to resolve the
name being looked up. It follows referrals from the root servers,
showing the answer from each server that was used to resolve the
lookup.
@ -698,7 +698,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
Multiple Queries
~~~~~~~~~~~~~~~~
The BIND 9 implementation of ``dig`` supports specifying multiple
The BIND 9 implementation of :program:`dig` supports specifying multiple
queries on the command line (in addition to supporting the :option:`-f` batch
file option). Each of those queries can be supplied with its own set of
flags, options, and query options.
@ -720,19 +720,19 @@ query options. For example:
dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr
shows how ``dig`` can be used from the command line to make three
shows how :program:`dig` can be used from the command line to make three
lookups: an ANY query for ``www.isc.org``, a reverse lookup of 127.0.0.1,
and a query for the NS records of ``isc.org``. A global query option of
``+qr`` is applied, so that ``dig`` shows the initial query it made for
``+qr`` is applied, so that :program:`dig` shows the initial query it made for
each lookup. The final query has a local query option of ``+noqr`` which
means that ``dig`` does not print the initial query when it looks up the
means that :program:`dig` does not print the initial query when it looks up the
NS records for ``isc.org``.
IDN Support
~~~~~~~~~~~
If ``dig`` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. ``dig``
If :program:`dig` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. :program:`dig`
appropriately converts character encoding of a domain name before sending
a request to a DNS server or displaying a reply from the server.
To turn off IDN support, use the parameters
@ -742,7 +742,7 @@ variable.
Return Codes
~~~~~~~~~~~~
``dig`` return codes are:
:program:`dig` return codes are:
``0``
DNS response received, including NXDOMAIN status

28
bin/dig/host.rst
View file

@ -26,16 +26,16 @@ Synopsis
Description
~~~~~~~~~~~
``host`` is a simple utility for performing DNS lookups. It is normally
:program:`host` is a simple utility for performing DNS lookups. It is normally
used to convert names to IP addresses and vice versa. When no arguments
or options are given, ``host`` prints a short summary of its
or options are given, :program:`host` prints a short summary of its
command-line arguments and options.
``name`` is the domain name that is to be looked up. It can also be a
dotted-decimal IPv4 address or a colon-delimited IPv6 address, in which
case ``host`` by default performs a reverse lookup for that address.
case :program:`host` by default performs a reverse lookup for that address.
``server`` is an optional argument which is either the name or IP
address of the name server that ``host`` should query instead of the
address of the name server that :program:`host` should query instead of the
server or servers listed in ``/etc/resolv.conf``.
Options
@ -66,7 +66,7 @@ Options
.. option:: -C
This option indicates that ``named`` should check consistency, meaning that ``host`` queries the SOA records for zone
This option indicates that ``named`` should check consistency, meaning that :program:`host` queries the SOA records for zone
``name`` from all the listed authoritative name servers for that
zone. The list of name servers is defined by the NS records that are
found for the zone.
@ -77,7 +77,7 @@ Options
.. option:: -l
This option tells ``named`` to list the zone, meaning the ``host`` command performs a zone transfer of zone
This option tells ``named`` to list the zone, meaning the :program:`host` command performs a zone transfer of zone
``name`` and prints out the NS, PTR, and address records (A/AAAA).
Together, the :option:`-l` :option:`-a` options print all records in the zone.
@ -100,7 +100,7 @@ Options
This option specifies a non-recursive query; setting this option clears the RD (recursion
desired) bit in the query. This means that the name server
receiving the query does not attempt to resolve ``name``. The :option:`-r`
option enables ``host`` to mimic the behavior of a name server by
option enables :program:`host` to mimic the behavior of a name server by
making non-recursive queries, and expecting to receive answers to
those queries that can be referrals to other name servers.
@ -121,11 +121,11 @@ Options
This option specifies the query type. The ``type`` argument can be any recognized query type:
CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc.
When no query type is specified, ``host`` automatically selects an
When no query type is specified, :program:`host` automatically selects an
appropriate query type. By default, it looks for A, AAAA, and MX
records. If the :option:`-C` option is given, queries are made for SOA
records. If ``name`` is a dotted-decimal IPv4 address or
colon-delimited IPv6 address, ``host`` queries for PTR records.
colon-delimited IPv6 address, :program:`host` queries for PTR records.
If a query type of IXFR is chosen, the starting serial number can be
specified by appending an equals sign (=), followed by the starting serial
@ -133,7 +133,7 @@ Options
.. option:: -T, -U
This option specifies TCP or UDP. By default, ``host`` uses UDP when making queries; the
This option specifies TCP or UDP. By default, :program:`host` uses UDP when making queries; the
:option:`-T` option makes it use a TCP connection when querying the name
server. TCP is automatically selected for queries that require
it, such as zone transfer (AXFR) requests. Type ``ANY`` queries default
@ -165,7 +165,7 @@ Options
This options sets the length of the wait timeout, indicating that ``named`` should wait for up to ``wait`` seconds for a reply. If ``wait`` is
less than 1, the wait interval is set to 1 second.
By default, ``host`` waits for 5 seconds for UDP responses and 10
By default, :program:`host` waits for 5 seconds for UDP responses and 10
seconds for TCP connections. These defaults can be overridden by the
``timeout`` option in ``/etc/resolv.conf``.
@ -174,13 +174,13 @@ Options
IDN Support
~~~~~~~~~~~
If ``host`` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. ``host``
If :program:`host` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. :program:`host`
appropriately converts character encoding of a domain name before sending
a request to a DNS server or displaying a reply from the server.
To turn off IDN support, define the ``IDN_DISABLE``
environment variable. IDN support is disabled if the variable is set
when ``host`` runs.
when :program:`host` runs.
Files
~~~~~

14
bin/dig/nslookup.rst
View file

@ -26,8 +26,8 @@ Synopsis
Description
~~~~~~~~~~~
``nslookup`` is a program to query Internet domain name servers.
``nslookup`` has two modes: interactive and non-interactive. Interactive
:program:`nslookup` is a program to query Internet domain name servers.
:program:`nslookup` has two modes: interactive and non-interactive. Interactive
mode allows the user to query name servers for information about various
hosts and domains or to print a list of hosts in a domain.
Non-interactive mode prints just the name and requested
@ -56,7 +56,7 @@ seconds, type:
nslookup -query=hinfo -timeout=10
The ``-version`` option causes ``nslookup`` to print the version number
The ``-version`` option causes :program:`nslookup` to print the version number
and immediately exit.
Interactive Commands
@ -183,19 +183,19 @@ Interactive Commands
Return Values
~~~~~~~~~~~~~
``nslookup`` returns with an exit status of 1 if any query failed, and 0
:program:`nslookup` returns with an exit status of 1 if any query failed, and 0
otherwise.
IDN Support
~~~~~~~~~~~
If ``nslookup`` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. ``nslookup``
If :program:`nslookup` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. :program:`nslookup`
appropriately converts character encoding of a domain name before sending
a request to a DNS server or displaying a reply from the server.
To turn off IDN support, define the ``IDN_DISABLE``
environment variable. IDN support is disabled if the variable is set
when ``nslookup`` runs, or when the standard output is not a tty.
when :program:`nslookup` runs, or when the standard output is not a tty.
Files
~~~~~

28
bin/dnssec/dnssec-cds.rst
View file

@ -26,11 +26,11 @@ Synopsis
Description
~~~~~~~~~~~
The ``dnssec-cds`` command changes DS records at a delegation point
The :program:`dnssec-cds` command changes DS records at a delegation point
based on CDS or CDNSKEY records published in the child zone. If both CDS
and CDNSKEY records are present in the child zone, the CDS is preferred.
This enables a child zone to inform its parent of upcoming changes to
its key-signing keys (KSKs); by polling periodically with ``dnssec-cds``, the
its key-signing keys (KSKs); by polling periodically with :program:`dnssec-cds`, the
parent can keep the DS records up-to-date and enable automatic rolling
of KSKs.
@ -40,19 +40,19 @@ DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` opt
specifies the location of a file containing the current DS records. For
example, this could be a ``dsset-`` file generated by
``dnssec-signzone``, or the output of ``dnssec-dsfromkey``, or the
output of a previous run of ``dnssec-cds``.
output of a previous run of :program:`dnssec-cds`.
The ``dnssec-cds`` command uses special DNSSEC validation logic
The :program:`dnssec-cds` command uses special DNSSEC validation logic
specified by :rfc:`7344`. It requires that the CDS and/or CDNSKEY records
be validly signed by a key represented in the existing DS records. This
is typically the pre-existing KSK.
For protection against replay attacks, the signatures on the child
records must not be older than they were on a previous run of
``dnssec-cds``. Their age is obtained from the modification time of the
:program:`dnssec-cds`. Their age is obtained from the modification time of the
``dsset-`` file, or from the :option:`-s` option.
To protect against breaking the delegation, ``dnssec-cds`` ensures that
To protect against breaking the delegation, :program:`dnssec-cds` ensures that
the DNSKEY RRset can be verified by every key algorithm in the new DS
RRset, and that the same set of keys are covered by every DS digest
type.
@ -65,7 +65,7 @@ specify that the child zone wants to be insecure.
.. warning::
Be careful not to delete the DS records when ``dnssec-cds`` fails!
Be careful not to delete the DS records when :program:`dnssec-cds` fails!
Alternatively, :option`dnssec-cds -u` writes an ``nsupdate`` script to the
standard output. The :option:`-u` and :option:`-i` options can be used together to
@ -79,7 +79,7 @@ Options
When converting CDS records to DS records, this option specifies
the acceptable digest algorithms. This option can be repeated, so
that multiple digest types are allowed. If none of the CDS records
use an acceptable digest type, ``dnssec-cds`` will try to use CDNSKEY
use an acceptable digest type, :program:`dnssec-cds` will try to use CDNSKEY
records instead; if there are no CDNSKEY records, it reports an error.
When converting CDNSKEY records to DS records, this option specifies the
@ -103,7 +103,7 @@ Options
.. option:: -d path
This specifies the location of the parent DS records. The path can be the name of a file
containing the DS records; if it is a directory, ``dnssec-cds``
containing the DS records; if it is a directory, :program:`dnssec-cds`
looks for a ``dsset-`` file for the domain inside the directory.
To protect against replay attacks, child records are rejected if they
@ -177,7 +177,7 @@ Options
Exit Status
~~~~~~~~~~~
The ``dnssec-cds`` command exits 0 on success, or non-zero if an error
The :program:`dnssec-cds` command exits 0 on success, or non-zero if an error
occurred.
If successful, the DS records may or may not need to be
@ -187,11 +187,11 @@ Examples
~~~~~~~~
Before running ``dnssec-signzone``, ensure that the delegations
are up-to-date by running ``dnssec-cds`` on every ``dsset-`` file.
are up-to-date by running :program:`dnssec-cds` on every ``dsset-`` file.
To fetch the child records required by ``dnssec-cds``, invoke
To fetch the child records required by :program:`dnssec-cds`, invoke
``dig`` as in the script below. It is acceptable if the ``dig`` fails, since
``dnssec-cds`` performs all the necessary checking.
:program:`dnssec-cds` performs all the necessary checking.
::
@ -203,7 +203,7 @@ To fetch the child records required by ``dnssec-cds``, invoke
done
When the parent zone is automatically signed by ``named``,
``dnssec-cds`` can be used with ``nsupdate`` to maintain a delegation as follows.
:program:`dnssec-cds` can be used with ``nsupdate`` to maintain a delegation as follows.
The ``dsset-`` file allows the script to avoid having to fetch and
validate the parent DS records, and it maintains the replay attack
protection time.

12
bin/dnssec/dnssec-dsfromkey.rst
View file

@ -32,7 +32,7 @@ Synopsis
Description
~~~~~~~~~~~
The ``dnssec-dsfromkey`` command outputs DS (Delegation Signer) resource records
The :program:`dnssec-dsfromkey` command outputs DS (Delegation Signer) resource records
(RRs), or CDS (Child DS) RRs with the :option:`-C` option.
By default, only KSKs are converted (keys with flags = 257). The
@ -41,13 +41,13 @@ included.
The input keys can be specified in a number of ways:
By default, ``dnssec-dsfromkey`` reads a key file named in the format
By default, :program:`dnssec-dsfromkey` reads a key file named in the format
``Knnnn.+aaa+iiiii.key``, as generated by ``dnssec-keygen``.
With the :option:`-f file <-f>` option, ``dnssec-dsfromkey`` reads keys from a zone
With the :option:`-f file <-f>` option, :program:`dnssec-dsfromkey` reads keys from a zone
file or partial zone file (which can contain just the DNSKEY records).
With the :option:`-s` option, ``dnssec-dsfromkey`` reads a ``keyset-`` file,
With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a ``keyset-`` file,
as generated by ``dnssec-keygen`` :option:`-C`.
Options
@ -88,7 +88,7 @@ Options
.. option:: -f file
This option sets zone file mode, in which the final dnsname argument of ``dnssec-dsfromkey`` is the
This option sets zone file mode, in which the final dnsname argument of :program:`dnssec-dsfromkey` is the
DNS domain name of a zone whose master file can be read from
``file``. If the zone name is the same as ``file``, then it may be
omitted.
@ -109,7 +109,7 @@ Options
.. option:: -s
This option enables keyset mode, in which the final dnsname argument from ``dnssec-dsfromkey`` is the DNS
This option enables keyset mode, in which the final dnsname argument from :program:`dnssec-dsfromkey` is the DNS
domain name used to locate a ``keyset-`` file.
.. option:: -T TTL

2
bin/dnssec/dnssec-importkey.rst
View file

@ -28,7 +28,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-importkey`` reads a public DNSKEY record and generates a pair
:program:`dnssec-importkey` reads a public DNSKEY record and generates a pair
of .key/.private files. The DNSKEY record may be read from an
existing .key file, in which case a corresponding .private file is
generated, or it may be read from any other file or from the standard

10
bin/dnssec/dnssec-keyfromlabel.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-keyfromlabel`` generates a pair of key files that reference a
:program:`dnssec-keyfromlabel` generates a pair of key files that reference a
key object stored in a cryptographic hardware service module (HSM). The
private key file can be used for DNSSEC signing of zone data as if it
were a conventional signing key created by ``dnssec-keygen``, but the
@ -95,7 +95,7 @@ Options
.. option:: -C
This option enables compatibility mode, which generates an old-style key, without any metadata.
By default, ``dnssec-keyfromlabel`` includes the key's creation
By default, :program:`dnssec-keyfromlabel` includes the key's creation
date in the metadata stored with the private key; other dates may
be set there as well, including publication date, activation date, etc. Keys
that include this data may be incompatible with older versions of
@ -119,7 +119,7 @@ Options
.. option:: -h
This option prints a short summary of the options and arguments to
``dnssec-keyfromlabel``.
:program:`dnssec-keyfromlabel`.
.. option:: -K directory
@ -250,7 +250,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
Generated Key Files
~~~~~~~~~~~~~~~~~~~
When ``dnssec-keyfromlabel`` completes successfully, it prints a string
When :program:`dnssec-keyfromlabel` completes successfully, it prints a string
of the form ``Knnnn.+aaa+iiiii`` to the standard output. This is an
identification string for the key files it has generated.
@ -260,7 +260,7 @@ identification string for the key files it has generated.
- ``iiiii`` is the key identifier (or footprint).
``dnssec-keyfromlabel`` creates two files, with names based on the
:program:`dnssec-keyfromlabel` creates two files, with names based on the
printed string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
``Knnnn.+aaa+iiiii.private`` contains the private key.

18
bin/dnssec/dnssec-keygen.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-keygen`` generates keys for DNSSEC (Secure DNS), as defined in
:program:`dnssec-keygen` generates keys for DNSSEC (Secure DNS), as defined in
:rfc:`2535` and :rfc:`4034`. It can also generate keys for use with TSIG
(Transaction Signatures) as defined in :rfc:`2845`, or TKEY (Transaction
Key) as defined in :rfc:`2930`.
@ -80,7 +80,7 @@ Options
.. option:: -C
This option enables compatibility mode, which generates an old-style key, without any timing
metadata. By default, ``dnssec-keygen`` includes the key's
metadata. By default, :program:`dnssec-keygen` includes the key's
creation date in the metadata stored with the private key; other
dates may be set there as well, including publication date, activation date,
etc. Keys that include this data may be incompatible with older
@ -125,7 +125,7 @@ Options
.. option:: -h
This option prints a short summary of the options and arguments to
``dnssec-keygen``.
:program:`dnssec-keygen`.
.. option:: -K directory
@ -134,12 +134,12 @@ Options
.. option:: -k policy
This option creates keys for a specific ``dnssec-policy``. If a policy uses multiple keys,
``dnssec-keygen`` generates multiple keys. This also
:program:`dnssec-keygen` generates multiple keys. This also
creates a ".state" file to keep track of the key state.
This option creates keys according to the ``dnssec-policy`` configuration, hence
it cannot be used at the same time as many of the other options that
``dnssec-keygen`` provides.
:program:`dnssec-keygen` provides.
.. option:: -L ttl
@ -174,7 +174,7 @@ Options
.. option:: -q
This option sets quiet mode, which suppresses unnecessary output, including progress
indication. Without this option, when ``dnssec-keygen`` is run
indication. Without this option, when :program:`dnssec-keygen` is run
interactively to generate an RSA or DSA key pair, it prints a
string of symbols to ``stderr`` indicating the progress of the key
generation. A ``.`` indicates that a random number has been found which
@ -295,7 +295,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
Generated Keys
~~~~~~~~~~~~~~
When ``dnssec-keygen`` completes successfully, it prints a string of the
When :program:`dnssec-keygen` completes successfully, it prints a string of the
form ``Knnnn.+aaa+iiiii`` to the standard output. This is an
identification string for the key it has generated.
@ -305,7 +305,7 @@ identification string for the key it has generated.
- ``iiiii`` is the key identifier (or footprint).
``dnssec-keygen`` creates two files, with names based on the printed
:program:`dnssec-keygen` creates two files, with names based on the printed
string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
``Knnnn.+aaa+iiiii.private`` contains the private key.
@ -329,7 +329,7 @@ The command prints a string of the form:
``Kexample.com.+013+26160``
In this example, ``dnssec-keygen`` creates the files
In this example, :program:`dnssec-keygen` creates the files
``Kexample.com.+013+26160.key`` and ``Kexample.com.+013+26160.private``.
To generate a matching key-signing key, issue the command:

4
bin/dnssec/dnssec-revoke.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-revoke`` reads a DNSSEC key file, sets the REVOKED bit on the
:program:`dnssec-revoke` reads a DNSSEC key file, sets the REVOKED bit on the
key as defined in :rfc:`5011`, and creates a new pair of key files
containing the now-revoked key.
@ -63,7 +63,7 @@ Options
.. option:: -f
This option indicates a forced overwrite and causes ``dnssec-revoke`` to write the new key pair,
This option indicates a forced overwrite and causes :program:`dnssec-revoke` to write the new key pair,
even if a file already exists matching the algorithm and key ID of
the revoked key.

8
bin/dnssec/dnssec-settime.rst
View file

@ -26,14 +26,14 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-settime`` reads a DNSSEC private key file and sets the key
:program:`dnssec-settime` reads a DNSSEC private key file and sets the key
timing metadata as specified by the :option:`-P`, :option:`-A`, :option:`-R`,
:option:`-I`, and :option:`-D` options. The metadata can then be used by
``dnssec-signzone`` or other signing software to determine when a key is
to be published, whether it should be used for signing a zone, etc.
If none of these options is set on the command line,
``dnssec-settime`` simply prints the key timing metadata already stored
:program:`dnssec-settime` simply prints the key timing metadata already stored
in the key.
When key metadata fields are changed, both files of a key pair
@ -64,7 +64,7 @@ Options
.. option:: -f
This option forces an update of an old-format key with no metadata fields. Without
this option, ``dnssec-settime`` fails when attempting to update a
this option, :program:`dnssec-settime` fails when attempting to update a
legacy key. With this option, the key is recreated in the new
format, but with the original key data retained. The key's creation
date is set to the present time. If no other values are
@ -230,7 +230,7 @@ Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE.
Printing Options
~~~~~~~~~~~~~~~~
``dnssec-settime`` can also be used to print the timing metadata
:program:`dnssec-settime` can also be used to print the timing metadata
associated with a key.
.. option:: -u

22
bin/dnssec/dnssec-signzone.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-signzone`` signs a zone; it generates NSEC and RRSIG records
:program:`dnssec-signzone` signs a zone; it generates NSEC and RRSIG records
and produces a signed version of the zone. The security status of
delegations from the signed zone (that is, whether the child zones are
secure) is determined by the presence or absence of a ``keyset``
@ -47,7 +47,7 @@ Options
This option sets compatibility mode, in which a ``keyset-zonename`` file is generated in addition
to ``dsset-zonename`` when signing a zone, for use by older versions
of ``dnssec-signzone``.
of :program:`dnssec-signzone`.
.. option:: -d directory
@ -56,7 +56,7 @@ Options
.. option:: -D
This option indicates that only those record types automatically managed by
``dnssec-signzone``, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output.
:program:`dnssec-signzone`, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output.
If smart signing (:option:`-S`) is used, DNSKEY records are also included.
The resulting file can be included in the original zone file with
``$INCLUDE``. This option cannot be combined with :option:`-O raw <-O>`
@ -144,7 +144,7 @@ Options
.. option:: -h
This option prints a short summary of the options and arguments to
``dnssec-signzone``.
:program:`dnssec-signzone`.
.. option:: -V
@ -160,7 +160,7 @@ Options
The default cycle interval is one quarter of the difference between
the signature end and start times. So if neither ``end-time`` nor
``start-time`` is specified, ``dnssec-signzone`` generates
``start-time`` is specified, :program:`dnssec-signzone` generates
signatures that are valid for 30 days, with a cycle interval of 7.5
days. Therefore, if any existing RRSIG records are due to expire in
less than 7.5 days, they are replaced.
@ -258,14 +258,14 @@ Options
one, signatures from the old key that are still within their validity
period are retained. This allows the zone to continue to validate
with cached copies of the old DNSKEY RRset. The :option:`-Q` option forces
``dnssec-signzone`` to remove signatures from keys that are no longer
:program:`dnssec-signzone` to remove signatures from keys that are no longer
active. This enables ZSK rollover using the procedure described in
:rfc:`4641#4.2.1.1` ("Pre-Publish Key Rollover").
.. option:: -q
This option enables quiet mode, which suppresses unnecessary output. Without this option, when
``dnssec-signzone`` is run it prints three pieces of information to standard output: the number of
:program:`dnssec-signzone` is run it prints three pieces of information to standard output: the number of
keys in use; the algorithms used to verify the zone was signed correctly and
other status information; and the filename containing the signed
zone. With the option that output is suppressed, leaving only the filename.
@ -275,14 +275,14 @@ Options
This option removes signatures from keys that are no longer published.
This option is similar to :option:`-Q`, except it forces
``dnssec-signzone`` to remove signatures from keys that are no longer
:program:`dnssec-signzone` to remove signatures from keys that are no longer
published. This enables ZSK rollover using the procedure described in
:rfc:`4641#4.2.1.2` ("Double Signature Zone Signing Key
Rollover").
.. option:: -S
This option enables smart signing, which instructs ``dnssec-signzone`` to search the key
This option enables smart signing, which instructs :program:`dnssec-signzone` to search the key
repository for keys that match the zone being signed, and to include
them in the zone if appropriate.
@ -336,7 +336,7 @@ Options
This option updates the NSEC/NSEC3 chain when re-signing a previously signed zone.
With this option, a zone signed with NSEC can be switched to NSEC3,
or a zone signed with NSEC3 can be switched to NSEC or to NSEC3 with
different parameters. Without this option, ``dnssec-signzone``
different parameters. Without this option, :program:`dnssec-signzone`
retains the existing chain when re-signing.
.. option:: -v level
@ -406,7 +406,7 @@ DS records can be imported from them (:option:`-g`).
db.example.com.signed
%
In the above example, ``dnssec-signzone`` creates the file
In the above example, :program:`dnssec-signzone` creates the file
``db.example.com.signed``. This file should be referenced in a zone
statement in the ``named.conf`` file.

4
bin/dnssec/dnssec-verify.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-verify`` verifies that a zone is fully signed for each
:program:`dnssec-verify` verifies that a zone is fully signed for each
algorithm found in the DNSKEY RRset for the zone, and that the
NSEC/NSEC3 chains are complete.
@ -68,7 +68,7 @@ Options
.. option:: -q
This option sets quiet mode, which suppresses output. Without this option, when ``dnssec-verify``
This option sets quiet mode, which suppresses output. Without this option, when :program:`dnssec-verify`
is run it prints to standard output the number of keys in use, the
algorithms used to verify the zone was signed correctly, and other status
information. With this option, all non-error output is suppressed, and only the exit

40
bin/named/named.rst
View file

@ -26,11 +26,11 @@ Synopsis
Description
~~~~~~~~~~~
``named`` is a Domain Name System (DNS) server, part of the BIND 9
:program:`named` is a Domain Name System (DNS) server, part of the BIND 9
distribution from ISC. For more information on the DNS, see :rfc:`1033`,
:rfc:`1034`, and :rfc:`1035`.
When invoked without arguments, ``named`` reads the default
When invoked without arguments, :program:`named` reads the default
configuration file |named_conf|, reads any initial data, and
listens for queries.
@ -39,17 +39,17 @@ Options
.. option:: -4
This option tells ``named`` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and
This option tells :program:`named` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and
:option:`-6` are mutually exclusive.
.. option:: -6
This option tells ``named`` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and
This option tells :program:`named` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and
:option:`-6` are mutually exclusive.
.. option:: -c config-file
This option tells ``named`` to use ``config-file`` as its configuration file instead of the default,
This option tells :program:`named` to use ``config-file`` as its configuration file instead of the default,
|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,
@ -58,11 +58,11 @@ Options
.. option:: -d debug-level
This option sets the daemon's debug level to ``debug-level``. Debugging traces from
``named`` become more verbose as the debug level increases.
:program:`named` become more verbose as the debug level increases.
.. option:: -D string
This option specifies a string that is used to identify a instance of ``named``
This option specifies a string that is used to identify a instance of :program:`named`
in a process listing. The contents of ``string`` are not examined.
.. option:: -E engine-name
@ -93,7 +93,7 @@ Options
system-provided memory allocation functions. If set to ``fill``, blocks
of memory are filled with tag values when allocated or freed, to
assist debugging of memory problems. ``nofill`` disables this behavior,
and is the default unless ``named`` has been compiled with developer
and is the default unless :program:`named` has been compiled with developer
options.
.. option:: -m flag
@ -105,7 +105,7 @@ Options
.. option:: -n #cpus
This option creates ``#cpus`` worker threads to take advantage of multiple CPUs. If
not specified, ``named`` tries to determine the number of CPUs
not specified, :program:`named` tries to determine the number of CPUs
present and creates one thread per CPU. If it is unable to determine
the number of CPUs, a single worker thread is created.
@ -144,12 +144,12 @@ Options
exhaustion of file descriptors and the operational environment is
known to support the specified number of sockets. Note also that
the actual maximum number is normally slightly fewer than the
specified value, because ``named`` reserves some file descriptors
specified value, because :program:`named` reserves some file descriptors
for its internal use.
.. option:: -t directory
This option tells ``named`` to chroot to ``directory`` after processing the command-line arguments, but
This option tells :program:`named` to chroot to ``directory`` after processing the command-line arguments, but
before reading the configuration file.
.. warning::
@ -161,8 +161,8 @@ Options
.. option:: -U #listeners
This option tells ``named`` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on
each address. If not specified, ``named`` calculates a default
This option tells :program:`named` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on
each address. If not specified, :program:`named` calculates a default
value based on the number of detected CPUs: 1 for 1 CPU, and the
number of detected CPUs minus one for machines with more than 1 CPU.
This cannot be increased to a value higher than the number of CPUs.
@ -177,10 +177,10 @@ Options
.. note::
On Linux, ``named`` uses the kernel's capability mechanism to drop
On Linux, :program:`named` uses the kernel's capability mechanism to drop
all root privileges except the ability to ``bind`` to a
privileged port and set process resource limits. Unfortunately,
this means that the :option:`-u` option only works when ``named`` is run
this means that the :option:`-u` option only works when :program:`named` is run
on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since
previous kernels did not allow privileges to be retained after
``setuid``.
@ -196,7 +196,7 @@ Options
.. option:: -X lock-file
This option acquires a lock on the specified file at runtime; this helps to
prevent duplicate ``named`` instances from running simultaneously.
prevent duplicate :program:`named` instances from running simultaneously.
Use of this option overrides the ``lock-file`` option in
``named.conf``. If set to ``none``, the lock file check is disabled.
@ -217,14 +217,14 @@ The result of sending any other signals to the server is undefined.
Configuration
~~~~~~~~~~~~~
The ``named`` configuration file is too complex to describe in detail
The :program:`named` configuration file is too complex to describe in detail
here. A complete description is provided in the BIND 9 Administrator
Reference Manual.
``named`` inherits the ``umask`` (file creation mode mask) from the
parent process. If files created by ``named``, such as journal files,
:program:`named` inherits the ``umask`` (file creation mode mask) from the
parent process. If files created by :program:`named`, such as journal files,
need to have custom permissions, the ``umask`` should be set explicitly
in the script used to start the ``named`` process.
in the script used to start the :program:`named` process.
Files
~~~~~

28
bin/nsupdate/nsupdate.rst
View file

@ -24,18 +24,18 @@ Synopsis
Description
~~~~~~~~~~~
``nsupdate`` is used to submit Dynamic DNS Update requests, as defined in
:program:`nsupdate` is used to submit Dynamic DNS Update requests, as defined in
:rfc:`2136`, to a name server. This allows resource records to be added or
removed from a zone without manually editing the zone file. A single
update request can contain requests to add or remove more than one
resource record.
Zones that are under dynamic control via ``nsupdate`` or a DHCP server
Zones that are under dynamic control via :program:`nsupdate` or a DHCP server
should not be edited by hand. Manual edits could conflict with dynamic
updates and cause data to be lost.
The resource records that are dynamically added or removed with
``nsupdate`` must be in the same zone. Requests are sent to the
:program:`nsupdate` must be in the same zone. Requests are sent to the
zone's primary server, which is identified by the MNAME field of the
zone's SOA record.
@ -44,13 +44,13 @@ updates. These use the TSIG resource record type described in :rfc:`2845`,
the SIG(0) record described in :rfc:`2535` and :rfc:`2931`, or GSS-TSIG as
described in :rfc:`3645`.
TSIG relies on a shared secret that should only be known to ``nsupdate``
TSIG relies on a shared secret that should only be known to :program:`nsupdate`
and the name server. For instance, suitable ``key`` and ``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
configuration fragments. ``nsupdate`` uses the :option:`-y` or :option:`-k` options
configuration fragments. :program:`nsupdate` uses the :option:`-y` or :option:`-k` options
to provide the TSIG shared secret; these options are mutually exclusive.
SIG(0) uses public key cryptography. To use a SIG(0) key, the public key
@ -131,7 +131,7 @@ Options
.. option:: -P
This option prints the list of private BIND-specific resource record types whose
format is understood by ``nsupdate``. See also the :option:`-T` option.
format is understood by :program:`nsupdate`. See also the :option:`-T` option.
.. option:: -r udpretries
@ -146,7 +146,7 @@ Options
.. option:: -T
This option prints the list of IANA standard resource record types whose format is
understood by ``nsupdate``. ``nsupdate`` exits after the lists
understood by :program:`nsupdate`. :program:`nsupdate` exits after the lists
are printed. The :option:`-T` option can be combined with the :option:`-P`
option.
@ -163,7 +163,7 @@ Options
.. option:: -v
This option specifies that TCP should be used even for small update requests. By default, ``nsupdate`` uses
This option specifies that TCP should be used even for small update requests. By default, :program:`nsupdate` uses
UDP to send update requests to the name server unless they are too
large to fit in a UDP request, in which case TCP is used. TCP may
be preferable when a batch of update requests is made.
@ -189,7 +189,7 @@ Options
Input Format
~~~~~~~~~~~~
``nsupdate`` reads input from ``filename`` or standard input. Each
:program:`nsupdate` reads input from ``filename`` or standard input. Each
command is supplied on exactly one line of input. Some commands are for
administrative purposes; others are either update instructions or
prerequisite checks on the contents of the zone. These checks set
@ -209,7 +209,7 @@ The command formats and their meanings are as follows:
``server servername port``
This command sends all dynamic update requests to the name server ``servername``.
When no server statement is provided, ``nsupdate`` sends updates
When no server statement is provided, :program:`nsupdate` sends updates
to the primary server of the correct zone. The MNAME field of that
zone's SOA record identify the primary server for that zone.
``port`` is the port number on ``servername`` where the dynamic
@ -218,14 +218,14 @@ The command formats and their meanings are as follows:
``local address port``
This command sends all dynamic update requests using the local ``address``. When
no local statement is provided, ``nsupdate`` sends updates using
no local statement is provided, :program:`nsupdate` sends updates using
an address and port chosen by the system. ``port`` can also
be used to force requests to come from a specific port. If no port number
is specified, the system assigns one.
``zone zonename``
This command specifies that all updates are to be made to the zone ``zonename``.
If no ``zone`` statement is provided, ``nsupdate`` attempts to
If no ``zone`` statement is provided, :program:`nsupdate` attempts to
determine the correct zone to update based on the rest of the input.
``class classname``
@ -323,7 +323,7 @@ Lines beginning with a semicolon (;) are comments and are ignored.
Examples
~~~~~~~~
The examples below show how ``nsupdate`` can be used to insert and
The examples below show how :program:`nsupdate` can be used to insert and
delete resource records from the ``example.com`` zone. Notice that the
input in each example contains a trailing blank line, so that a group of
commands is sent as one dynamic update request to the primary name
@ -381,5 +381,5 @@ Bugs
~~~~
The TSIG key is redundantly stored in two separate files. This is a
consequence of ``nsupdate`` using the DST library for its cryptographic
consequence of :program:`nsupdate` using the DST library for its cryptographic
operations, and may change in future releases.

8
bin/rndc/rndc.conf.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``rndc.conf`` is the configuration file for ``rndc``, the BIND 9 name
:program:`rndc.conf` is the configuration file for ``rndc``, the BIND 9 name
server control utility. This file has a similar structure and syntax to
``named.conf``. Statements are enclosed in braces and terminated with a
semi-colon. Clauses in the statements are also semi-colon terminated.
@ -38,7 +38,7 @@ C++ style: // to end of line
Unix style: # to end of line
``rndc.conf`` is much simpler than ``named.conf``. The file uses three
:program:`rndc.conf` is much simpler than ``named.conf``. The file uses three
statements: an options statement, a server statement, and a key
statement.
@ -135,7 +135,7 @@ To generate a random secret with ``rndc-confgen``:
``rndc-confgen``
A complete ``rndc.conf`` file, including the randomly generated key,
A complete :program:`rndc.conf` file, including the randomly generated key,
is written to the standard output. Commented-out ``key`` and
``controls`` statements for ``named.conf`` are also printed.
@ -147,7 +147,7 @@ Name Server Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
The name server must be configured to accept rndc connections and to
recognize the key specified in the ``rndc.conf`` file, using the
recognize the key specified in the :program:`rndc.conf` file, using the
controls statement in ``named.conf``. See the sections on the
``controls`` statement in the BIND 9 Administrator Reference Manual for
details.

24
bin/rndc/rndc.rst
View file

@ -26,15 +26,15 @@ Synopsis
Description
~~~~~~~~~~~
``rndc`` controls the operation of a name server; it supersedes the
``ndc`` utility. If ``rndc`` is
:program:`rndc` controls the operation of a name server; it supersedes the
``ndc`` utility. If :program:`rndc` is
invoked with no command line options or arguments, it prints a short
summary of the supported commands and the available options and their
arguments.
``rndc`` communicates with the name server over a TCP connection,
:program:`rndc` communicates with the name server over a TCP connection,
sending commands authenticated with digital signatures. In the current
versions of ``rndc`` and ``named``, the only supported authentication
versions of :program:`rndc` and ``named``, the only supported authentication
algorithms are HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224,
HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512. They use a shared
secret on each end of the connection, which provides TSIG-style
@ -42,7 +42,7 @@ authentication for the command request and the name server's response.
All commands sent over the channel must be signed by a key_id known to
the server.
``rndc`` reads a configuration file to determine how to contact the name
:program:`rndc` reads a configuration file to determine how to contact the name
server and decide what algorithm and key it should use.
Options
@ -77,9 +77,9 @@ Options
.. option:: -s server
``server`` is the name or address of the server which matches a server
statement in the configuration file for ``rndc``. If no server is
statement in the configuration file for :program:`rndc`. If no server is
supplied on the command line, the host named by the default-server
clause in the options statement of the ``rndc`` configuration file
clause in the options statement of the :program:`rndc` configuration file
is used.
.. option:: -p port
@ -94,7 +94,7 @@ Options
.. option:: -r
This option instructs ``rndc`` to print the result code returned by ``named``
This option instructs :program:`rndc` to print the result code returned by ``named``
after executing the requested command (e.g., ISC_R_SUCCESS,
ISC_R_FAILURE, etc.).
@ -106,7 +106,7 @@ Options
This option indicates use of the key ``key_id`` from the configuration file. For control message validation to succeed, ``key_id`` must be known
by ``named`` with the same algorithm and secret string. If no ``key_id`` is specified,
``rndc`` first looks for a key clause in the server statement of
:program:`rndc` first looks for a key clause in the server statement of
the server being used, or if no server statement is present for that
host, then in the default-key clause of the options statement. Note that
the configuration file contains shared secrets which are used to send
@ -116,7 +116,7 @@ Options
Commands
~~~~~~~~
A list of commands supported by ``rndc`` can be seen by running ``rndc``
A list of commands supported by :program:`rndc` can be seen by running :program:`rndc`
without arguments.
Currently supported commands are:
@ -449,7 +449,7 @@ Currently supported commands are:
yet been updated by a successful key refresh query).
If the first argument is ``-``, then the output is returned via the
``rndc`` response channel and printed to the standard output.
:program:`rndc` response channel and printed to the standard output.
Otherwise, it is written to the secroots dump file, which defaults to
``named.secroots``, but can be overridden via the ``secroots-file``
option in ``named.conf``.
@ -628,7 +628,7 @@ Currently supported commands are:
See also :option:`rndc showzone`.
``rndc`` commands that specify zone names, such as :option:`reload`
:program:`rndc` commands that specify zone names, such as :option:`reload`
:option:`retransfer`, or :option:`zonestatus`, can be ambiguous when applied to zones
of type ``redirect``. Redirect zones are always called ``.``, and can be
confused with zones of type ``hint`` or with secondary copies of the root

2
bin/tools/arpaname.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``arpaname`` translates IP addresses (IPv4 and IPv6) to the
:program:`arpaname` translates IP addresses (IPv4 and IPv6) to the
corresponding IN-ADDR.ARPA or IP6.ARPA names.
See Also

2
bin/tools/dnstap-read.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnstap-read`` reads ``dnstap`` data from a specified file and prints
:program:`dnstap-read` reads ``dnstap`` data from a specified file and prints
it in a human-readable format. By default, ``dnstap`` data is printed in
a short summary format, but if the :option:`-y` option is specified, a
longer and more detailed YAML format is used.

28
bin/tools/mdig.rst
View file

@ -30,12 +30,12 @@ Synopsis
Description
~~~~~~~~~~~
``mdig`` is a multiple/pipelined query version of ``dig``: instead of
:program:`mdig` is a multiple/pipelined query version of ``dig``: instead of
waiting for a response after sending each query, it begins by sending
all queries. Responses are displayed in the order in which they are
received, not in the order the corresponding queries were sent.
``mdig`` options are a subset of the ``dig`` options, and are divided
:program:`mdig` options are a subset of the ``dig`` options, and are divided
into "anywhere options," which can occur anywhere, "global options," which
must occur before the query name (or they are ignored with a warning),
and "local options," which apply to the next query on the command line.
@ -45,9 +45,9 @@ address of the name server to query. (Unlike ``dig``, this value is not
retrieved from ``/etc/resolv.conf``.) It can be an IPv4 address in
dotted-decimal notation, an IPv6 address in colon-delimited notation, or
a hostname. When the supplied ``server`` argument is a hostname,
``mdig`` resolves that name before querying the name server.
:program:`mdig` resolves that name before querying the name server.
``mdig`` provides a number of query options which affect the way in
:program:`mdig` provides a number of query options which affect the way in
which lookups are made and the results displayed. Some of these set or
reset flag bits in the query header, some determine which sections of
the answer get printed, and others determine the timeout and retry
@ -64,31 +64,31 @@ Anywhere Options
.. option:: -f
This option makes ``mdig`` operate in batch mode by reading a list
This option makes :program:`mdig` operate in batch mode by reading a list
of lookup requests to process from the file ``filename``. The file
contains a number of queries, one per line. Each entry in the file
should be organized in the same way they would be presented as queries
to ``mdig`` using the command-line interface.
to :program:`mdig` using the command-line interface.
.. option:: -h
This option causes ``mdig`` to print detailed help information, with the full list
This option causes :program:`mdig` to print detailed help information, with the full list
of options, and exit.
.. option:: -v
This option causes ``mdig`` to print the version number and exit.
This option causes :program:`mdig` to print the version number and exit.
Global Options
~~~~~~~~~~~~~~
.. option:: -4
This option forces ``mdig`` to only use IPv4 query transport.
This option forces :program:`mdig` to only use IPv4 query transport.
.. option:: -6
This option forces ``mdig`` to only use IPv6 query transport.
This option forces :program:`mdig` to only use IPv6 query transport.
.. option:: -b address
@ -104,7 +104,7 @@ Global Options
.. option:: -p port#
This option is used when a non-standard port number is to be
queried. ``port#`` is the port number that ``mdig`` sends its
queried. ``port#`` is the port number that :program:`mdig` sends its
queries to, instead of the standard DNS port number 53. This option is
used to test a name server that has been configured to listen for
queries on a non-standard port number.
@ -171,7 +171,7 @@ The global query options are:
This option toggles printing of records, like the SOA records, in a verbose multi-line format
with human-readable comments. The default is to print each record on
a single line, to facilitate machine parsing of the ``mdig`` output.
a single line, to facilitate machine parsing of the :program:`mdig` output.
.. option:: +[no]question
@ -239,7 +239,7 @@ Local Options
Reverse lookups - mapping addresses to names - are simplified by
this option. ``addr`` is an IPv4 address in dotted-decimal
notation, or a colon-delimited IPv6 address. ``mdig`` automatically
notation, or a colon-delimited IPv6 address. :program:`mdig` automatically
performs a lookup for a query name like ``11.12.13.10.in-addr.arpa`` and
sets the query type and class to PTR and IN respectively. By default,
IPv6 addresses are looked up using nibble format under the IP6.ARPA
@ -319,7 +319,7 @@ The local query options are:
.. option:: +[no]recurse
This toggles the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means ``mdig`` normally sends
This bit is set by default, which means :program:`mdig` normally sends
recursive queries.
.. option:: +retry=T

4
bin/tools/named-journalprint.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``named-journalprint`` scans the contents of a zone journal file,
:program:`named-journalprint` scans the contents of a zone journal file,
printing it in a human-readable form, or, optionally, converting it
to a different journal file format.
@ -38,7 +38,7 @@ shutdown or crash. By default, the name of the journal file is formed by
appending the extension ``.jnl`` to the name of the corresponding zone
file.
``named-journalprint`` converts the contents of a given journal file
:program:`named-journalprint` converts the contents of a given journal file
into a human-readable text format. Each line begins with ``add`` or ``del``,
to indicate whether the record was added or deleted, and continues with
the resource record in master-file format.

2
bin/tools/named-nzd2nzf.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``named-nzd2nzf`` converts an NZD database to NZF format and prints it
:program:`named-nzd2nzf` converts an NZD database to NZF format and prints it
to standard output. This can be used to review the configuration of
zones that were added to ``named`` via :option:`rndc addzone`. It can also be
used to restore the old file format when rolling back from a newer

2
bin/tools/named-rrchecker.rst
View file

@ -26,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``named-rrchecker`` reads a individual DNS resource record from standard
:program:`named-rrchecker` reads a individual DNS resource record from standard
input and checks whether it is syntactically correct.
Options

2
bin/tools/nsec3hash.rst
View file

@ -28,7 +28,7 @@ Synopsis
Description
~~~~~~~~~~~
``nsec3hash`` generates an NSEC3 hash based on a set of NSEC3
:program:`nsec3hash` generates an NSEC3 hash based on a set of NSEC3
parameters. This can be used to check the validity of NSEC3 records in a
signed zone.