More linting

source/conf.py

@@ -165,7 +165,7 @@
     "Unbound developers are mentioned in the CREDITS file in the distribution.", 3)
 ]
 
-manpages_url = '{page}.html'
+manpages_url = '/manpages/{page}.html'
 
 # -- Options for Texinfo output ----------------------------------------------
 

source/getting-started/configuration.rst

@@ -1,13 +1,21 @@
 Configuration
 =============
 
-Unbound has a vast array of configuration options for advanced use cases, which can seem a little overwhelming at first. Luckily, all of the defaults are sensible and secure, so in a lot of environments you can run Unbound without changing any options. Below we will go through a basic, recommended config, but feel free to add and experiment with options as you need them.
+Unbound has a vast array of configuration options for advanced use cases, which
+can seem a little overwhelming at first. Luckily, all of the defaults are
+sensible and secure, so in a lot of environments you can run Unbound without
+changing any options. Below we will go through a basic, recommended config, but
+feel free to add and experiment with options as you need them.
 
-.. @TODO in the future we can put a forward link to the configuration options + explanations for advanced users.
+.. @TODO in the future we can put a forward link to the configuration options +
+         explanations for advanced users.
 
 .. Note:: The instructions in this page assume that Unbound is already installed.
 
-The basic configuration which you can use out of the box is shown below. To use it, you need to create a file with this config as its content (or copy the config to the default config file which can be found during the installation process).
+The basic configuration which you can use out of the box is shown below. To use
+it, you need to create a file with this config as its content (or copy the
+config to the default config file which can be found during the installation
+process).
 
 .. code-block:: bash
 
@@ -34,22 +42,41 @@ The basic configuration which you can use out of the box is shown below. To use
         access-control: 192.168.0.0/16 allow
         # access-control: 2001:DB8/64 allow
 
-By default the Unbound config uses `chroot <https://wiki.archlinux.org/title/chroot>`_ to provide an extra layer of defence against remote exploits. If Unbound is not starting because it cannot access files due to permission errors caused by :command:`chroot`, a solution can be to enter file paths as full pathnames starting at the root of the filesystem (``/``). Otherwise, if :command:`chroot` is not required you can disable it in the config.
+By default the Unbound config uses `chroot
+<https://wiki.archlinux.org/title/chroot>`_ to provide an extra layer of defence
+against remote exploits. If Unbound is not starting because it cannot access
+files due to permission errors caused by :command:`chroot`, a solution can be to
+enter file paths as full pathnames starting at the root of the filesystem
+(``/``). Otherwise, if :command:`chroot` is not required you can disable it in
+the config.
 
 .. code-block:: bash
 
 	# disable chroot
 	chroot: ""
 
-By default Unbound assumes that a user named "unbound" exists, which you can add this user with an account management tool available on your system. You can also disable this feature by adding ``username: ""`` in the config. If it is enabled, after the setup, any other user privileges are dropped and the configured username is assumed. If this user  needs access to files (such as the 'trust anchor' mentioned below) these can be created by executing with ``sudo -u unbound`` in front of it.
-
-.. Important:: Unbound comes with the :command:`unbound-checkconf` tool. This tool allows you to check the config file for errors before starting Unbound. It is very convenient because if any errors are found it tells you where they are, which is particularly useful when Unbound is already running to avoid failure to restart due to a configuration error.
-
+By default Unbound assumes that a user named "unbound" exists, which you can add
+this user with an account management tool available on your system. You can also
+disable this feature by adding ``username: ""`` in the config. If it is enabled,
+after the setup, any other user privileges are dropped and the configured
+username is assumed. If this user  needs access to files (such as the 'trust
+anchor' mentioned below) these can be created by executing with ``sudo -u
+unbound`` in front of it.
+
+.. Important:: Unbound comes with the :manpage:`unbound-checkconf(8)` tool. This
+               tool allows you to check the config file for errors before
+               starting Unbound. It is very convenient because if any errors are
+               found it tells you where they are, which is particularly useful
+               when Unbound is already running to avoid failure to restart due
+               to a configuration error.
 
 Set up Remote Control
 ---------------------
 
-A useful functionality to enable is the use of the :command:`unbound-control` command. This allows command makes starting, stopping, and reloading Unbound easier. To enable this functionality we need to add :option:`remote-control` to the config and enable it.
+A useful functionality to enable is the use of the :command:`unbound-control`
+command. This allows command makes starting, stopping, and reloading Unbound
+easier. To enable this functionality we need to add ``remote-control`` to the
+config and enable it.
 
 .. code-block:: bash
 
@@ -63,47 +90,77 @@ A useful functionality to enable is the use of the :command:`unbound-control` co
         #control-key-file: "/usr/local/etc/unbound/unbound_control.key"
         #control-cert-file: "/usr/local/etc/unbound/unbound_control.pem"
 
-To use the :command:`unbound-control` command, we need to invoke the :command:`unbound-control-setup` command. This creates a number of files in the default install directory. The default install directory is ``/usr/local/etc/unbound/`` on most systems, but some distributions may put it in ``/etc/unbound/`` or ``/var/lib/unbound``.
+To use the :command:`unbound-control` command, we need to invoke the
+:command:`unbound-control-setup` command. This creates a number of files in the
+default install directory. The default install directory is
+``/usr/local/etc/unbound/`` on most systems, but some distributions may put it
+in ``/etc/unbound/`` or ``/var/lib/unbound``.
 
-Apart from an extensive config file, with just about all the possible configuration options, :command:`unbound-control-setup` creates the cryptographic keys necessary for the control option. 
+Apart from an extensive config file, with just about all the possible
+configuration options, :command:`unbound-control-setup` creates the
+cryptographic keys necessary for the control option. 
 
 .. code-block:: bash
 
     unbound-control-setup
 
-If you use a username like ``unbound`` in the config to run the daemon (which is the default setting), you can use :command:`sudo` to create the files in that user's name, so that the user running Unbound is allowed to read the keys. 
-This is also a solution if the ``/usr/local/etc/unbound/`` (or any other default direcotry) directory is write-protected, which is the case for some distributions.
+If you use a username like ``unbound`` in the config to run the daemon (which is
+the default setting), you can use :command:`sudo` to create the files in that
+user's name, so that the user running Unbound is allowed to read the keys. This
+is also a solution if the ``/usr/local/etc/unbound/`` (or any other default
+direcotry) directory is write-protected, which is the case for some
+distributions.
 
 .. code-block:: bash
 
 	sudo -u unbound unbound-control-setup
 
-You can now control Unbound using the :command:`unbound-control` command. Note that if your configuration file is not in the default location or not named ``unbound.conf``, the name (and possibly path) need to be provided when using the command using the :option:`-c` flag.
+You can now control Unbound using the :command:`unbound-control` command. Note
+that if your configuration file is not in the default location or not named
+``unbound.conf``, the name (and possibly path) need to be provided when using
+the command using the :option:`-c` flag.
 
 
 Set up Trust Anchor (Enable DNSSEC)
 -----------------------------------
 
-To enable `DNSSEC <https://www.sidn.nl/en/cybersecurity/dnssec-explained>`_, which we strongly recommend, we need to set up a trust anchor as it allows the verification of the integrity of the responses to the queries you send.
+To enable `DNSSEC <https://www.sidn.nl/en/cybersecurity/dnssec-explained>`_,
+which we strongly recommend, we need to set up a trust anchor as it allows the
+verification of the integrity of the responses to the queries you send.
 
-To help, we can use the :command:`unbound-anchor` command. :command:`unbound-anchor` performs the setup by configuring a trust anchor. This trust anchor will only serve as the initial anchor from builtin values. To keep this anchor up to date, Unbound must be able to read and write to this file.
-The default location that :command:`unbound-anchor` creates this in is determined by your installation method. Usually the default directory is ``/usr/local/etc/unbound/``.
+To help, we can use the :command:`unbound-anchor` command.
+:command:`unbound-anchor` performs the setup by configuring a trust anchor. This
+trust anchor will only serve as the initial anchor from builtin values. To keep
+this anchor up to date, Unbound must be able to read and write to this file. The
+default location that :command:`unbound-anchor` creates this in is determined by
+your installation method. Usually the default directory is
+``/usr/local/etc/unbound/``.
 
 .. code-block::bash
 
 	unbound-anchor
 
-Note that using a package manager to install Unbound, on some distributions, creates the root key during installation. On Ubuntu 20.04.1 LTS for example, this location is ``/var/lib/unbound/root.key``. On macOS Big Sur this location is ``/opt/homebrew/etc/unbound/root.key`` If you create the root key yourself (by using the :command:`unbound-anchor` command), then the path to the anchor file in the configuration file should be changed to the correct location. To find out the default location you can use the :command:`unbound-anchor` command again with the ``-vvv`` option enabled.
-To enable DNSSEC, we add ``auto-trust-anchor-file`` under the ``server`` options in the config.
+Note that using a package manager to install Unbound, on some distributions,
+creates the root key during installation. On Ubuntu 20.04.1 LTS for example,
+this location is ``/var/lib/unbound/root.key``. On macOS Big Sur this location
+is ``/opt/homebrew/etc/unbound/root.key`` If you create the root key yourself
+(by using the :command:`unbound-anchor` command), then the path to the anchor
+file in the configuration file should be changed to the correct location. To
+find out the default location you can use the :command:`unbound-anchor` command
+again with the ``-vvv`` option enabled. To enable DNSSEC, we add
+``auto-trust-anchor-file`` under the ``server`` options in the config.
 
 .. code-block:: bash
 
 	# enable DNSSEC
 	auto-trust-anchor-file: "/var/lib/unbound/root.key"
 
-Note that on some systems the ``/usr/local/etc/unbound/`` directory might be write-protected. 
+Note that on some systems the ``/usr/local/etc/unbound/`` directory might be
+write-protected. 
 
-If the :command:`unbound-control-setup` command fails due to the insufficient permissions, run the command as the correct user, here we use the user ``unbound`` as this is the default user.
+If the :command:`unbound-control-setup` command fails due to the insufficient
+permissions, run the command as the correct user, here we use the user
+``unbound`` as this is the default user.
 
 .. code-block:: bash
 

source/getting-started/installation.rst

@@ -99,11 +99,10 @@ download as well.
     sudo apt-get install -y bison
     sudo apt-get install -y flex
 
-
 With all the requirements met, we can now start the compilation process in the
-Unbound directory. The first step here is configuring. With :option:`./configure
--h` you can look at the extensive list of configurables for Unbound. A nice
-feature is that :command:`configure` will tell you what it's missing during
+Unbound directory. The first step here is configuring. With ``./configure
+-h`` you can look at the extensive list of configurables for Unbound. A nice
+feature is that ``configure`` will tell you what it's missing during
 configuration. A common error is for the paths to the two libraries we just
 installed, which can be manually specified with ``--with-ssl=`` and
 ``--with-libexpat=``.
@@ -197,8 +196,8 @@ which can become important in the :command:`configure` step.
     brew install expat
 
 With all the requirements met, we can now start the compilation process in the
-Unbound directory. The first step here is configuring. With :option:`./configure
--h` you can look at the extensive list of configurables for Unbound. A nice
+Unbound directory. The first step here is configuring. With ``./configure
+-h`` you can look at the extensive list of configurables for Unbound. A nice
 feature is that :command:`configure` will tell you what it's missing during
 configuration. A common error is for the paths to the two libraries we just
 installed, which can be manually specified with ``--with-ssl=`` and

source/manpages/unbound-anchor.rst

@@ -129,8 +129,8 @@ The available options are:
 
 .. option:: -R 
 
-       Allow fallback from :option:`-f resolv.conf` file to direct root servers
-       query. It allows you to prefer local resolvers, but fallback
+       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.
 

source/manpages/unbound-control.rst

@@ -228,24 +228,24 @@ insecure_add *zone*
 insecure_remove *zone*
     Removes domain-insecure for the given zone.
 
-forward_add [:option:`+i`] *zone addr ...*
-    Add a new forward zone to running unbound. With :option:`+i` option also
+forward_add [``+i``] *zone addr ...*
+    Add a new forward zone to running unbound. With ``+i`` option also
     adds a domain-insecure for the zone (so it can resolve insecurely if you
     have a DNSSEC root trust anchor configured for other names). The addr can be
     IP4, IP6 or nameserver names, like forward-zone config in unbound.conf.
 
-forward_remove [:option:`+i`] *zone*
-    Remove a forward zone from running unbound. The :option:`+i` also removes a
+forward_remove [``+i``] *zone*
+    Remove a forward zone from running unbound. The ``+i`` also removes a
     domain-insecure for the zone.
 
-stub_add [:option:`+i`] *zone addr ...*
-    Add a new stub zone to running unbound. With :option:`+i` option also adds a
-    domain-insecure for the zone. With :option:`+p` the stub zone is set to
+stub_add [``+i``] *zone addr ...*
+    Add a new stub zone to running unbound. With ``+i`` option also adds a
+    domain-insecure for the zone. With ``p`` the stub zone is set to
     prime, without it it is set to notprime. The addr can be IP4, IP6 or
     nameserver names, like the *stub-zone* config in un- bound.conf.
 
-stub_remove [:option:`+i`] *zone*
-Remove a stub zone from running unbound. The :option:`+i` also removes a
+stub_remove [``+i``] *zone*
+Remove a stub zone from running unbound. The ``+i`` also removes a
 domain-insecure for the zone.
 
 forward [*off* | *addr ...* ]
@@ -272,16 +272,16 @@ forward [*off* | *addr ...* ]
     changes are gone. Other forward zones from the config file are not affected
     by this command.
 
-ratelimit_list [:option:`+a`]
+ratelimit_list [``a``]
     List the domains that are ratelimited. Printed one per line with current
-    estimated qps and qps limit from config. With :option:`+a` it prints all
+    estimated qps and qps limit from config. With ``a`` it prints all
     domains, not just the ratelimited domains, with their estimated qps. The
     ratelimited domains return an error for uncached (new) queries, but cached
     queries work as normal.
 
-ip_ratelimit_list [:option:`+a`]
+ip_ratelimit_list [``a``]
     List the ip addresses that are ratelimited. Printed one per line with
-    current estimated qps and qps limit from config. With :option:`+a` it prints
+    current estimated qps and qps limit from config. With ``a`` it prints
     all ips, not just the ratelimited ips, with their estimated qps. The
     ratelimited ips are dropped before checking the cache.
 

source/topics/serve-stale.rst

@@ -126,7 +126,7 @@ If more client-side performance is required, the default original serve-expired
 behavior can keep the cache-hit ratio higher. Using it together with the
 prefetch option is highly recommended in order to try and keep an updated cache.
 
-In all cases make sure to consult the :ref:`man page<doc_unbound_conf_manpage>`
-of your installed Unbound for defaults and suggested values. And always remember
-that serving expired records should be approached with caution; you may be
-directing your clients to places long gone.
+In all cases make sure to consult the :manpage:`unbound.conf(5)` manpage of your
+installed Unbound for defaults and suggested values. And always remember that
+serving expired records should be approached with caution; you may be directing
+your clients to places long gone.