Skip to content

Commit

Permalink
Update manpages for 1.17.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@gthess
gthess committed Oct 21, 2022
1 parent 1efcef2 commit 354b38b
Show file tree
Hide file tree
Showing 8 changed files with 4,469 additions and 3,054 deletions.
20 changes: 10 additions & 10 deletions source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,13 @@

project = 'Unbound'
year = datetime.datetime.now().year
copyright = f'2018–{year}, NLnet Labs'
copyright = f'1999–{year}, NLnet Labs'
author = 'NLnet Labs'

# The short X.Y version
version = '1.14.0'
version = '1.17.0'
# The full version, including alpha/beta/rc tags
release = '1.14.0'
release = '1.17.0'

# -- General configuration ---------------------------------------------------

Expand Down Expand Up @@ -167,25 +167,25 @@
# (source start file, name, description, authors, manual section).
man_pages = [
('manpages/unbound', 'unbound',
'Unbound DNS validating resolver', unbound_authors, 8),
f'Unbound DNS validating resolver {version}.', unbound_authors, 8),

('manpages/unbound-checkconf', 'unbound-checkconf',
'Check unbound configuration file for errors.', unbound_authors, 8),
f'Check Unbound {version} configuration file for errors.', unbound_authors, 8),

('manpages/unbound-anchor', 'unbound-anchor',
'Unbound anchor utility.', unbound_authors, 8),
f'Unbound {version} anchor utility.', unbound_authors, 8),

('manpages/unbound.conf', 'unbound.conf',
'Unbound configuration file.', unbound_authors, 5),
f'Unbound {version} configuration file.', unbound_authors, 5),

('manpages/unbound-control', 'unbound-control',
'Unbound remote server control utility.', unbound_authors, 8),
f'Unbound {version} remote server control utility.', unbound_authors, 8),

('manpages/unbound-host', 'unbound-host',
'Unbound DNS lookup utility', unbound_authors, 1),
f'Unbound {version} DNS lookup utility.', unbound_authors, 1),

('manpages/libunbound', 'libunbound',
'Unbound DNS validating resolver functions.', unbound_authors, 3)
f'Unbound DNS validating resolver {version} functions.', unbound_authors, 3)
]

# -- Options for Texinfo output ----------------------------------------------
Expand Down
438 changes: 243 additions & 195 deletions source/manpages/libunbound.rst
View file

Large diffs are not rendered by default.

245 changes: 134 additions & 111 deletions source/manpages/unbound-anchor.rst
View file
Original file line number Diff line number Diff line change
@@ -1,178 +1,199 @@
.. program:: unbound-anchor

unbound-anchor(8)
=================

Synopsis
--------

:command:`unbound-anchor` [`opts`]
**unbound-anchor** [``opts``]

Description
-----------

:command:`Unbound-anchor` performs setup or update of the root trust anchor for
DNSSEC validation. The program fetches the trust anchor with the method from
:RFC:`7958` when regular :RFC:`5011` update fails to bring it up to date. It can
be run (as root) from the commandline, or run as part of startup scripts. Before
you start the :doc:`/manpages/unbound` DNS server.
``unbound-anchor`` performs setup or update of the root trust anchor for DNSSEC
validation.
The program fetches the trust anchor with the method from :RFC:`7958` when
regular :RFC:`5011` update fails to bring it up to date.
It can be run (as root) from the commandline, or run as part of startup
scripts.
Before you start the :doc:`unbound(8)</manpages/unbound>` DNS server.

Suggested usage:

.. code-block:: text
# in the init scripts.
# provide or update the root anchor (if necessary)
unbound-anchor -a "/usr/local/etc/unbound/root.key"
# Please note usage of this root anchor is at your own risk
# and under the terms of our LICENSE (see source).
#
# start validating resolver
# the unbound.conf contains:
# auto-trust-anchor-file: "/usr/local/etc/unbound/root.key"
unbound -c unbound.conf
# in the init scripts.
# provide or update the root anchor (if necessary)
unbound-anchor -a "/usr/local/etc/unbound/root.key"
# Please note usage of this root anchor is at your own risk
# and under the terms of our LICENSE (see source).
#
# start validating resolver
# the unbound.conf contains:
# auto-trust-anchor-file: "/usr/local/etc/unbound/root.key"
unbound -c unbound.conf
This tool provides builtin default contents for the root anchor and root update
certificate files.

It tests if the root anchor file works, and if not, and an update is possible,
attempts to update the root anchor using the root update certificate. It
performs a https fetch of :file:`root-anchors.xml` and checks the results
(:RFC:`7958`), if all checks are successful, it updates the root anchor file.
Otherwise the root anchor file is unchanged. It performs :RFC:`5011` tracking if
the DNSSEC information available via the DNS makes that possible.
attempts to update the root anchor using the root update certificate.
It performs a https fetch of
`root-anchors.xml <http://data.iana.org/root-anchors/root-anchors.xml>`__
and checks the results (:RFC:`7958`); if all checks are successful, it updates
the root anchor file.
Otherwise the root anchor file is unchanged.
It performs :RFC:`5011` tracking if the DNSSEC information available via the
DNS makes that possible.

It does not perform an update if the certificate is expired, if the network is
down or other errors occur.

The available options are:

.. option:: -a file
.. option:: -a <file>

The root anchor key file, that is read in and written out. Default is
:file:`/usr/local/etc/unbound/root.key`. If the file does not exist, or
is empty, a builtin root key is written to it.
The root anchor key file, that is read in and written out.
Default is :file:`/usr/local/etc/unbound/root.key`.
If the file does not exist, or is empty, a builtin root key is written
to it.

.. option:: -c file
.. option:: -c <file>

The root update certificate file, that is read in. Default is
:file:`/usr/local/etc/unbound/icannbundle.pem`. If the file does not
exist, or is empty, a builtin certificate is used.
The root update certificate file, that is read in.
Default is :file:`/usr/local/etc/unbound/icannbundle.pem`.
If the file does not exist, or is empty, a builtin certificate is used.

.. option:: -l
.. option:: -l

List the builtin root key and builtin root update certificate on stdout.

.. option:: -u name
.. option:: -u <name>

The server name, it connects to ``https://name``. Specify without
``https://`` prefix. The default is ``"data.iana.org"``. It connects to
the port specified with :option:`-P`. You can pass an IPv4 address or
IPv6 address (no brackets) if you want.
The server name, it connects to ``https://name``.
Specify without ``https://`` prefix.
The default is ``"data.iana.org"``.
It connects to the port specified with :option:`-P`.
You can pass an IPv4 address or IPv6 address (no brackets) if you want.

.. option:: -S
.. option:: -S

Do not use SNI for the HTTPS connection. Default is to use SNI.
Do not use SNI for the HTTPS connection.
Default is to use SNI.

.. option:: -b address
.. option:: -b <address>

The source address to bind to for domain resolution and contacting the
server on https. May be either an IPv4 address or IPv6 address (no
brackets).
server on https.
May be either an IPv4 address or IPv6 address (no brackets).

.. option:: -x path
.. option:: -x <path>

The pathname to the root-anchors.xml file on the server. (forms URL with
:option:`-u`). The default is :file:`/root-anchors/root-anchors.xml`.
The pathname to the root-anchors.xml file on the server.
(forms URL with :option:`-u`).
The default is :file:`/root-anchors/root-anchors.xml`.

.. option:: -s path
.. option:: -s <path>

The pathname to the root-anchors.p7s file on the server. (forms URL with
:option:`-u`). The default is :file:`/root-anchors/root-anchors.p7s`.
The pathname to the root-anchors.p7s file on the server.
(forms URL with :option:`-u`).
The default is :file:`/root-anchors/root-anchors.p7s`.
This file has to be a PKCS7 signature over the xml file, using the pem
file (:option:`-c`) as trust anchor.

.. option:: -n name
.. option:: -n <name>

The emailAddress for the Subject of the signer's certificate from the
p7s signature file.
Only signatures from this name are allowed.
The default is ``dnssec@iana.org``.
If you pass ``""`` then the emailAddress is not checked.

The emailAddress for the Subject of the signer's certificate from the p7s
signature file. Only signatures from this name are allowed. default is
``dnssec@iana.org``. If you pass ``""`` then the emailAddress is not
checked.
.. option:: -4

.. option:: -4

Use IPv4 for domain resolution and contacting the server on
https. Default is to use IPv4 and IPv6 where appropriate.
https.
Default is to use IPv4 and IPv6 where appropriate.

.. option:: -6

.. option:: -6

Use IPv6 for domain resolution and contacting the server on https.
Default is to use IPv4 and IPv6 where appropriate.

.. option:: -f resolv.conf
.. option:: -f <resolv.conf>

Use the given resolv.conf file. Not enabled by default, but you could try
to pass :file:`/etc/resolv.conf` on some systems. It contains the IP
addresses of the recursive nameservers to use. However, since this tool
could be used to bootstrap that very recursive nameserver, it would not
be useful (since that server is not up yet, since we are bootstrapping
it). It could be useful in a situation where you know an upstream cache
is deployed (and running) and in captive portal situations.
Use the given resolv.conf file.
Not enabled by default, but you could try to pass
:file:`/etc/resolv.conf` on some systems.
It contains the IP addresses of the recursive nameservers to use.
However, since this tool could be used to bootstrap that very recursive
nameserver, it would not be useful (since that server is not up yet,
since we are bootstrapping it).
It could be useful in a situation where you know an upstream cache is
deployed (and running) and in captive portal situations.

.. option:: -r root.hints
.. option:: -r <root.hints>

Use the given root.hints file (same syntax as the BIND and Unbound root
hints file) to bootstrap domain resolution. By default a list of builtin
root hints is used. Unbound-anchor goes to the network itself for these
roots, to resolve the server (:option:`-u` option) and to check the root
DNSKEY records. It does so, because the tool when used for bootstrapping
the recursive reolver, cannot use that recursive resolver itself because
it is bootstrapping that server.

.. option:: -R

Allow fallback from :option:`-f` ``resolv.conf`` file to direct root
servers query. It allows you to prefer local resolvers, but fallback
automatically to direct root query if they do not respond or do not
support DNSSEC.

.. option:: -v

More verbose. Once prints informational messages, multiple times may
enable large debug amounts (such as full certificates or byte-dumps of
downloaded files). By default it prints almost nothing. It also prints
nothing on errors by default; in that case the original root anchor file
is simply left undisturbed, so that a recursive server can start right
after it.

.. option:: -C unbound.conf

Debug option to read :file:`unbound.conf` into the resolver process
hints file) to bootstrap domain resolution.
By default a list of builtin root hints is used.
unbound-anchor goes to the network itself for these roots, to resolve
the server (:option:`-u` option) and to check the root DNSKEY records.
It does so, because the tool when used for bootstrapping the recursive
reolver, cannot use that recursive resolver itself because it is
bootstrapping that server.

.. option:: -R

Allow fallback from :option:`-f` ``<resolv.conf>`` file to direct root
servers query.
It allows you to prefer local resolvers, but fallback automatically to
direct root query if they do not respond or do not support DNSSEC.

.. option:: -v

More verbose.
Once prints informational messages, multiple times may enable large
debug amounts (such as full certificates or byte-dumps of downloaded
files).
By default it prints almost nothing.
It also prints nothing on errors by default; in that case the original
root anchor file is simply left undisturbed, so that a recursive server
can start right after it.

.. option:: -C <unbound.conf>

Debug option to read :file:`<unbound.conf>` into the resolver process
used.

.. option:: -P port

Set the port number to use for the https connection. The default is 443.
Set the port number to use for the https connection.
The default is 443.

.. option:: -F
.. option:: -F

Debug option to force update of the root anchor through downloading the
xml file and verifying it with the certificate. By default it first tries
to update by contacting the DNS, which uses much less bandwidth, is much
faster (200 msec not 2 sec), and is nicer to the deployed infrastructure.
xml file and verifying it with the certificate.
By default it first tries to update by contacting the DNS, which uses
much less bandwidth, is much faster (200 msec not 2 sec), and is nicer
to the deployed infrastructure.
With this option, it still attempts to do so (and may verbosely tell
you), but then ignores the result and goes on to use the xml fallback
method.

.. option:: -h
.. option:: -h

Show the version and commandline option help.

Exit Code
---------

This tool exits with value 1 if the root anchor was updated using the
certificate or if the builtin root-anchor was used. It exits with code 0 if no
update was necessary, if the update was possible with :RFC:`5011` tracking, or
if an error occurred.
certificate or if the builtin root-anchor was used.
It exits with code 0 if no update was necessary, if the update was possible
with :RFC:`5011` tracking, or if an error occurred.

You can check the exit value in this manner:

Expand All @@ -190,25 +211,26 @@ convenience and under the terms of our license (see the LICENSE file in the
source distribution or https://github.com/NLnetLabs/unbound/blob/master/LICENSE
and might be stale or not suitable to your purpose.

By running ``unbound-anchor -l`` the keys and certificate that are configured in
the code are printed for your convenience.
By running :option:`unbound-anchor -l` the keys and certificate that are
configured in the code are printed for your convenience.

The built-in configuration can be overridden by providing a root-cert file and a
rootkey file.
The built-in configuration can be overridden by providing a root-cert file and
a rootkey file.

Files
-----

/usr/local/etc/unbound/root.key
The root anchor file, updated with 5011 tracking, and read and written
to. The file is created if it does not exist.
to.
The file is created if it does not exist.

/usr/local/etc/unbound/icannbundle.pem
The trusted self-signed certificate that is used to verify the
downloaded DNSSEC root trust anchor. You can update it by fetching it
from https://data.iana.org/root-anchors/icannbundle.pem (and validate
it). If the file does not exist or is empty, a builtin version is
used.
downloaded DNSSEC root trust anchor.
You can update it by fetching it from
https://data.iana.org/root-anchors/icannbundle.pem (and validate it).
If the file does not exist or is empty, a builtin version is used.

https://data.iana.org/root-anchors/root-anchors.xml
Source for the root key information.
Expand All @@ -219,4 +241,5 @@ https://data.iana.org/root-anchors/root-anchors.p7s
See Also
--------

:doc:`/manpages/unbound.conf`, :doc:`/manpages/unbound`.
:doc:`unbound.conf(5)</manpages/unbound.conf>`,
:doc:`unbound(8)</manpages/unbound>`.

0 comments on commit 354b38b

Please sign in to comment.