Merge pull request #6 from jpmens/patch-1

Some rephrasing and a few suggestions. :-)

source/use-cases/home-resolver.rst

@@ -6,21 +6,21 @@ Resolver for Home Networks
 ==========================
 
 To start off, let's ask the all-important question "Why would you want Unbound as a resolver for your home network?" |br|
-Firstly, Unbound supports DNSSEC which, through an authentication chain, verifies that the DNS query responses you receive are unaltered, as opposed to query responses which do not have a DNSSEC record and could be changed by anyone who has access to the query.
-Secondly, by using your own resolver you stop sharing your DNS traffic with third parties (your ISP, Google, Cloudflare, Quad9, etc.) and increase your DNS privacy. While you still send out (parts of) your query unencrypted, you could configure Unbound to take it a step further, which we'll talk about in an upcoming guide.
-Lastly, when you run your own resolver your DNS cache will be locally in your network. Even though the first time you resolve a domain name may be slightly slower than using your ISP’s resolver, all subsequent queries will likely be much faster.
+Firstly, Unbound supports DNSSEC which, through an authentication chain, verifies that the DNS query responses you receive are unaltered, as opposed to query responses which are not DNSSEC-signed and could be changed by anyone who has access to the query.
+Secondly, by using your own resolver you stop sharing your DNS traffic with third parties (your ISP, Google, Cloudflare, Quad9, etc.) and increase your DNS privacy. While you still send out (parts of) your queries unencrypted, you could configure Unbound to take it a step further, which we'll talk about in an upcoming guide.
+Lastly, when you run your own resolver your DNS cache will be local to your network. Even though the first time you resolve a domain name may be slightly slower than using your ISP’s resolver, all subsequent queries for the name will likely be much faster.
 
 In this tutorial we'll look at setting up Unbound as a DNS resolver; Firstly for your own machine, and then for your entire network.
 
 
 Setting up Unbound
 ------------------
 
-Unbound is a powerful validating, recursive, caching DNS resolver. It’s used by some of the biggest tech companies in the world as well as home users, who use it together with ad blockers and firewalls, or self-hosted resolvers. Setting it up for your home network can be quite simple as we’ll showcase below.
+Unbound is a powerful validating, recursive, caching DNS resolver. It’s used by some of the biggest tech companies in the world as well as small-office / home-office users, who use it together with ad blockers and firewalls, or self-hosted resolvers. Setting it up for your home network can be quite simple as we’ll showcase below.
 
-Setting up your own DNS resolver for your entire home network requires a couple of things. Namely, a recursive DNS resolver (who knew!), and a dedicated machine where the resolver runs, which is always on and accessible to the entire network. This can be as simple as a Raspberry Pi, or any other machine that is always online, connected to your home router.
+Setting up a caching DNS server for your entire home network requires a recursive DNS resolver, and a dedicated machine on which the resolver runs; this (small) system is always on and accessible to the entire network. It can be as small as a Raspberry Pi or any other available Linux/Unix machine that is always online and has Internet connectivity via your router.
 
-Because of the variety of machines that Unbound can run on we cannot create a comprehensive tutorial for all possible options. For this tutorial we will use :command:`Ubuntu 20.04.1 LTS` as a stepping stone which you could use and adapt for other machines.
+Because of the variety of machines that Unbound can run on we cannot create a comprehensive tutorial for all possible options. For this tutorial we will use :command:`Ubuntu 20.04.1 LTS` as a stepping stone you can adapt and apply to other systems.
 
 While you could download the code from GitHub and build it yourself, getting a copy can be as simple as running:
 
@@ -29,9 +29,9 @@ While you could download the code from GitHub and build it yourself, getting a c
 	sudo apt update
 	sudo apt install unbound -y
 
-This gives you a full, compiled, and running version of Unbound which behaves as a caching recursive DNS resolver out of the box for the local machine. You can check which version of Unbound you have installed with :option:`unbound -V`. The version installed will vary depending on the operating system. If the version is installed is quite old (at the time of writing it isn't) or you'd simply like to run the latest and greatest version you can download the latest release tarball from our `website <https://nlnetlabs.nl/projects/unbound/about/>`_ and build it yourself.
+This gives you a complete and running version of Unbound which behaves as a caching recursive DNS resolver out of the box for the system on which you install it. You can check which version of Unbound you have installed with :option:`unbound -V`. The version installed will vary depending on the operating system. If the version is installed is quite old (at the time of writing it isn't) or you'd simply like to run the latest and greatest version you can download the latest release tarball from our `website <https://nlnetlabs.nl/projects/unbound/about/>`_ and build it yourself.
 
-Do note that the current setup is only reachable on this machine.
+Do note that by default the DNS server will be queryable only from the local host, i.e. the system on which you installed Unbound. We will change that later.
 
 Testing the resolver locally
 ----------------------------
@@ -45,7 +45,7 @@ The command for testing locally on the Unbound machine is:
 	dig example.com @127.0.0.1
 
 Here we tell the :command:`dig` tool to look up the IP address for example.com, and to ask for this information from the server running at the IP address ``127.0.0.1``, which is where our Unbound machine is running by default.
-We can verify that Unbound has indeed answered our query instead of the default resolver that is present on Ubuntu by default. In the output of every :command:`dig` command there is an ``ANSWER SECTION`` which specifies the server which has answered the query under the ``SERVER`` entry. The entry should be:
+We can verify that Unbound has indeed answered our query instead of the default resolver that is present on Ubuntu by default. In the output of every :command:`dig` command there is an ``ANSWER SECTION`` which gives the response to the query. In the footer section of the output, the server which has answered the query under the ``SERVER`` entry. The entry will look like:
 
 .. code-block:: bash
 
@@ -75,15 +75,15 @@ While just changing this file will work as long as the machine doesn't reboot, t
 
 	rm /etc/resolv.conf
 
-With your favourite text editor (e.g. :command:`nano`), create a new file with the same name and specify the IP address that our Unbound instance is running at in the file. We also include the :option:`edns0` option as this enables header extensions used in DNSSEC and is an overall standard used in DNS nowadays. |br|
+With your favourite text editor (e.g. :command:`nano`), create a new file by that name and specify the IP address that our Unbound instance is running at in the file. We also include the :option:`edns0` option as this enables header extensions used in DNSSEC and is an overall standard used in DNS nowadays. |br|
 So with :file:`nano /etc/resolv.conf` we create the new file and enter:
 
 .. code-block:: bash
 
 	nameserver 127.0.0.1
 	options edns0
 
-We then need to stop and disable the currently running pre-installed resolver. Note that you cannot visit new websites until the next step after this, as you have no DNS resolver assigned for the system.
+We then need to stop and disable the currently running pre-installed resolver. Note DNS resolution will not function until the next step is complete, as you'll have no DNS resolver assigned for the system until then.
 
 .. code-block:: bash
 
@@ -96,7 +96,7 @@ Now the operating system should use our Unbound instance as default. A quick tes
 
 	dig example.com
 
-Note that the "SERVER" section in the output from :command:`dig` should also contain the local IP address of our server.
+Note that the "SERVER" section in the footer of  :command:`dig` should also contain the local IP address of our server.
 
 .. code-block:: bash
 
@@ -119,9 +119,9 @@ To find the IP address of the machine that is running Unbound, we use:
 
 	hostname --all-ip-addresses
 
-If you just have one IP address as output from the :command:`hostname` command that will be the correct one. If you have multiple IP addresses, the easiest way to determine which IP address to use, is to find out which connection goes to your home router. Keep in mind that finding the wrong IP address here can be a source of connectivity errors further on. For the purpose of this tutorial we assume that our home router has the IP address ``10.0.0.1``, and our resolver machine (the machine that is running our Unbound instance) has IP address ``10.0.0.2``, which we will get into in the next section.
+If you just have one IP address as output from the :command:`hostname` command that will be the correct one. If you have multiple IP addresses, the easiest way to determine which IP address to use, is to find out which connection goes to your home router. Keep in mind that using the wrong IP address here can be a source of connectivity errors further on. For the purpose of this tutorial we assume that our home router has the IP address ``192.168.0.1``, as this is typical for home routers, and our resolver machine (the machine that is running our Unbound instance) has IP address ``192.168.0.2``, which we will get into in the next section.
 
-As a prerequisite for the next step, we need to configure our Unbound instance to be reachable from devices other than only the machine on which the Unbound is running. The full example config is almost 1200 lines long, as the capabilities of Unbound are considerable, but we won’t need nearly as much. (If you are interested, any and all configurables can be found in the extensive manual page of :manpage:`unbound.conf`).
+As a prerequisite for the next step, we need to configure our Unbound instance to be reachable from devices other than only the machine on which the Unbound is running. Unbound is a highly capable resolver, and as such has many options which can be set; the full example config is almost 1200 lines long, but we'll need but a fraction of these settings. (If you are interested, all configurables are documented in the extensive manual page of :manpage:`unbound.conf`).
 
 The default config is found at:
 
@@ -138,23 +138,25 @@ The options that we add to the current config file to make it a "minimal usable
 	server:
 			# location of the trust anchor file that enables DNSSEC
 			auto-trust-anchor-file: "/var/lib/unbound/root.key"
-			# the interface that is used to connect to the network, this means on this machine
+			# send minimal amount of information to upstream servers to enhance privacy
+			qname-minimisation: yes
+			# the interface that is used to connect to the network (this will listen to all interfaces)
 			interface: 0.0.0.0
 			# interface: ::0
 			# addresses from the IP range that are allowed to connect to the resolver
-			access-control: 10.0.0.0/8 allow
-			# access-control: 2001:DB8.. code-block:: bash/64 allow
+			access-control: 192.168.0.0/16 allow
+			# access-control: 2001:DB8/64 allow
+
 	remote-control:
 			# allows controling unbound using "unbound-control"
 			control-enable: yes
 
-The interface is currently configured to listen to any address on the machine, and the access-control only allows queries from the ``10.0.0.0/8`` `IP subnet <https://www.ripe.net/about-us/press-centre/understanding-ip-addressing>`_ range. Note that the IP address we chose above (``10.0.0.1`` and ``10.0.0.2``) fall within the ``10.0.0.0/8`` range.
+The interface is currently configured to listen to any address on the machine, and the access-control only allows queries from the ``192.168.0.0/16`` `IP subnet <https://www.ripe.net/about-us/press-centre/understanding-ip-addressing>`_ range. Note that the IP address we chose above (``192.168.0.1`` and ``192.168.0.2``) fall within the ``192.168.0.0/16`` range.
 
 To prepare our config we are going to modify the existing config in :file:`/etc/unbound/unbound.conf`.
-If you open the file we see that there is already an “include” in there. This include enables us to do `DNSSEC <https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions>`_, which allows Unbound to verify the source of the answers that it receives, which we want to keep in. If you don't have the file that the include links to (:file:`root.key`), it can be created using the :command:`unbound-anchor` command. |br|
-If you don't have the :file:`unbound_control.key` and :file:`unbound_control.pem` files, when you're building Unbound from source for example, the command to create these is: :command:`unbound-control-setup`.
+If you open the file for the first time, you see that there is already an “include” in there. The include enables us to do `DNSSEC <https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions>`_, which allows Unbound to verify the source of the answers that it receives, as well as QNAME minimisation. For convienience these configuration options have already been added in the minimal config. The config also includes the :command:`remote-control` in the config to enable controlling Unbound using :command:`unbound-control` command which is useful if you want to modify the config later on. 
 
-Using the text editor again, we can then add the minimal config as shown above, making any changes to the access control where needed. Do note that we strongly recommend keeping the :command:`include` that is already in the file (such as in the above config). We also add the :command:`remote-control` in the config to enable controlling Unbound using :command:`unbound-control` command which is useful if you want to modify the config later on. When you are happy with your config, we can check it for mistakes with the :command:`unbound-checkconf` command:
+Using the text editor again, we can then add the minimal config shown above, making any changes to the access control where needed.When we've modified the configuration we check it for mistakes with the :command:`unbound-checkconf` command:
 
 .. code-block:: bash
 
@@ -177,28 +179,29 @@ From this point on, we can :command:`stop`, :command:`start`, and :command:`relo
 Testing the resolver from a remote machine
 ------------------------------------------
 
-So now we have a DNS resolver which should be reachable from within the network. To verify this we need to find the IP address of the resolver machine which can be found on the machine itself. For this tutorial we will use the address ``10.0.0.2`` (not ``127.0.0.1`` as we saw earlier) as an example. Armed with the IP address we can send a query to our DNS resolver from another machine which is within our home network. To do this we use the same dig command, only we change the IP address where the query is asked.
+So now we have a DNS resolver which should be reachable from within the network. To be able to verify that our resolver is working correctly, we want to test it from anoither machine in the network. As mentioned above, this tutorial uses the address ``192.168.0.2`` (not ``127.0.0.1`` as we saw earlier) as an example for the machine running Unbound. Armed with the IP address we can send a query to our DNS resolver from another machine which is within our home network. To do this we use the same dig command, only we change the IP address where the query is asked.
 
 .. code-block:: bash
 
-	dig example.com @10.0.0.2
+	dig example.com @192.168.0.2
 
-This should give the same result, including the ``SERVER`` entry, as the query from the local test above.
+This should give the same result as above. The ``SERVER`` entry in the footer reflects from which server the response was received.
 
 Where it all comes together
 ---------------------------
 
-We should now have a functioning DNS resolver that is accessible to all machines in our network (make sure you do before you continue). 
+We should now have a functioning DNS resolver that is accessible to all machines in our network (**make sure you do before you continue**).
 
-The next step then becomes a little tricky as there are many options and variations possible. We have a choice of which machines in our network will be using our configured DNS resolver. This can range from a single machine to all the machines that are connected. Since this tutorial cannot (and does not try to) be comprehensive for the range of choices, we will look at some of the basic examples which you can implement and expand on.
+The next step then is a little tricky as there are many options and variations possible. We have a choice of which machines in our network will be using our configured DNS resolver. This can range from a single machine to all the machines that are connected. Since this tutorial cannot (and does not try to) be comprehensive for the range of choices, we will look at some of the basic examples which you can implement and expand on.
 
-Most machines when they first connect to a network get a “recommended resolver” from your router using :abbr:`DHCP (Dynamic Host Configuration Protocol)`. To change this, we need to log into the router. To find the IP address of our home router which is likely be under :option:`default gateway`:
+Most machines when they first connect to a network get a “recommended resolver” from your router using :abbr:`DHCP (Dynamic Host Configuration Protocol)`. To change this, we need to log into the router. Earlier in this tutorial we assume the home router was using ``192.168.0.1``, though in reality this can differ. if this does differ, the unbound config needs to be changed as well. |br|
+To find the IP address of our home router, which is likely be under the :option:`default gateway` entry from:
 
 .. code-block:: bash
 
 	ip route
 
-When you've found the IP address of your home router, you can copy the address to a web browser, which should give you access to the router configuration portal. If you can't find the portal using this method, consult the manual or the manufacturer's website. When you have access, you should change the DHCP configuration to advertise the IP address of the machine running Unbound as the default gateway. In the case of our example, that would be 10.0.0.2.
+When you've found the IP address of your home router, you can copy the address to a web browser, which should give you access to the router configuration portal. If you can't find the portal using this method, consult the manual or the manufacturer's website. When you have access, you should change the DHCP configuration to advertise the IP address of the machine running Unbound as the default gateway. In the case of our example, that would be ``192.168.0.2``.
 
 Another possibility is a machine that does not use a resolver that is “recommended” by your router. This machine can be running its own resolver or be connected to a different one altogether. If you want these machines to use the Unbound resolver you set up, you need to change the configuration of the machine.