Merge branch 'master' of github.com:NLnetLabs/unbound-manual

requirements.txt

@@ -1 +1,4 @@
-sphinx==4.3.2
+sphinx==4.3.2
+sphinx-version-warning==1.1.2
+sphinx-tabs==3.2.0
+sphinx-copybutton==0.4.0

source/conf.py

@@ -16,13 +16,15 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import datetime
 import sphinx_rtd_theme
 
 # -- Project information -----------------------------------------------------
 
 project = 'Unbound'
-copyright = '2007-2022, NLnet Labs'
-author = 'NLnet Labs (CC-BY 3.0)'
+year = datetime.datetime.now().year
+copyright = f'2018–{year}, NLnet Labs'
+author = 'NLnet Labs'
 
 # The short X.Y version
 version = '1.14.0'
@@ -41,9 +43,22 @@
 extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.ifconfig',
-    'sphinx.ext.autosectionlabel',
+    'sphinx_tabs.tabs',
+    'sphinx_copybutton',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel'
 ]
 
+intersphinx_mapping = {
+    'nsd': ('https://nsd.docs.nlnetlabs.nl/en/latest/', None)
+}
+
+autosectionlabel_prefix_document = True
+
+# -- Sphinx Tabs configuration -----------------------------------------------
+
+sphinx_tabs_disable_tab_closing = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../templates']
 

source/developer/libunbound-tutorial/index.rst

@@ -1,11 +1,11 @@
 Unbound Library Tutorial
 ========================
 
-This is the tutorial for the unbound library. Unbound can run as a server, as a
-daemon in the background, answering DNS queries from the network.
-Alternatively, it can link to an application as a library ``-lunbound``, and
-answer DNS queries for the application. This tutorial explains how to use the
-library API.
+This is the tutorial for the :doc:`unbound library</manpages/libunbound>`.
+Unbound can run as a server, as a daemon in the background, answering DNS
+queries from the network. Alternatively, it can link to an application as a
+library ``-lunbound``, and answer DNS queries for the application. This tutorial
+explains how to use the library API.
 
 .. toctree::
    :maxdepth: 2

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 :doc:`/manpages/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.
 
 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
 
@@ -58,52 +85,82 @@ A useful functionality to enable is the use of the :command:`unbound-control` co
         control-enable: yes
 
         # location of the files created by unbound-control-setup
-        #server-key-file: "/usr/local/etc/unbound/unbound_server.key"
-        #server-cert-file: "/usr/local/etc/unbound/unbound_server.pem"
-        #control-key-file: "/usr/local/etc/unbound/unbound_control.key"
-        #control-cert-file: "/usr/local/etc/unbound/unbound_control.pem"
+        # server-key-file: "/usr/local/etc/unbound/unbound_server.key"
+        # server-cert-file: "/usr/local/etc/unbound/unbound_server.pem"
+        # 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

@@ -19,7 +19,7 @@ Installing with a Package Manager
 Most package managers maintain a version of Unbound, although this version can
 be outdated if this package has not been updated recently. If you like to
 upgrade to the latest version, we recommend :ref:`compiling Unbound
-yourself<Building from source/Compiling>`.
+yourself<getting-started/installation:Building from source/Compiling>`.
 
 Ubuntu 20.04.1 LTS
 ^^^^^^^^^^^^^^^^^^
@@ -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=``.
@@ -128,7 +127,7 @@ for the machine.
     sudo make install
 
 We now have fully compiled and installed version of Unbound, and :ref:`continue
-to testing it<Testing>`.
+to testing it<getting-started/installation:Testing>`.
 
 Please note that the default configuration file is located at
 :file:`/usr/local/etc/unbound/unbound.conf` and created during the
@@ -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
@@ -215,7 +214,8 @@ of openssl is ``1.1.1k`` and of libexapt is ``2.3.0``).
 
 .. code-block:: bash
 
-    ./configure --with-ssl=/opt/homebrew/Cellar/openssl@1.1/1.1.1k/ --with-libexpat=/opt/homebrew/Cellar/expat/2.3.0
+    ./configure --with-ssl=/opt/homebrew/Cellar/openssl@1.1/1.1.1k/ \
+                --with-libexpat=/opt/homebrew/Cellar/expat/2.3.0
 
 When :command:`configure` gives no errors, we can continue to actually compiling
 Unbound. For this Unbound uses :command:`make`. Be warned that compiling might
@@ -233,7 +233,7 @@ for the machine.
     sudo make install
 
 We now have fully compiled and installed version of Unbound, and can
-:ref:`continue to testing it<Testing>`.
+:ref:`continue to testing it<getting-started/installation:Testing>`.
 
 Testing
 -------
@@ -252,8 +252,8 @@ Unbound instance.
 
 Another handy trick you can use during testing is to run Unbound in the
 foreground using the :option:`-d` option and increase the verbosity level using
-the :option:`-vvv` option. This allows you to see steps Unbound takes and also
-where it fails.
+the :option:`-v` option multiple times. This allows you to see steps Unbound
+takes and also where it fails.
 
 Now that Unbound is installed we can :doc:`continue to configuring
 it<configuration>`.

source/index.rst

@@ -45,26 +45,26 @@ license, with attribution to NLnet Labs.
    use-cases/local-stub
 
 .. toctree::
-      :maxdepth: 2
-      :caption: Core
-   
-      topics/performance
-      topics/monitoring
-      topics/serve-stale
+   :maxdepth: 2
+   :caption: Core
+
+   topics/performance
+   topics/monitoring
+   topics/serve-stale
 
 .. toctree::
-      :maxdepth: 2
-      :caption: Privacy
+   :maxdepth: 2
+   :caption: Privacy
 
-      topics/privacy/aggressive-nsec
-      topics/privacy/dns-over-https
+   topics/privacy/aggressive-nsec
+   topics/privacy/dns-over-https
 
 .. toctree::
-      :maxdepth: 2
-      :caption: Filtering
+   :maxdepth: 2
+   :caption: Filtering
 
-      topics/filtering/tags-views
-      topics/filtering/rpz
+   topics/filtering/tags-views
+   topics/filtering/rpz
 
 .. toctree::
    :maxdepth: 2
@@ -95,8 +95,9 @@ license, with attribution to NLnet Labs.
    reference/todo
 
 
-Indices and tables
-==================
+Index
+=====
 
 * :ref:`genindex`
-* :ref:`search`
+
+.. * :ref:`search`