1  # Introduction
  2  
  3  (This guide was tested with HardenedBSD 12-STABLE 1200515)
  4  
  5  Usually users with laptops connect to several wireless networks and get their
  6  settings regarding DNS nameservers. Because of this auto-setup, we may get the
  7  DNS servers that may restrict our domain queries or log them to trace profiles.
  8  
  9  Also if we do a query each time we change network and get new name-servers we
 10  need to submit new queries and that is a overhead that could be exponential in
 11  growth, so maybe there are gain in have a local DNS resolver running and
 12  benefit from the cache factor and, like previously mentioned, gain some privacy.
 13  
 14  HardenedBSD (and FreeBSD) have available local-unbound(8) that is a caching
 15  DNS resolver.
 16  
 17  ## Process of connecting to network
 18  
 19  The default process of connecting to wireless network with DHCP is:
 20  
 21  1. select network 
 22  
 23  2. dhclient(8) is called to obtain configuration where it reads
 24  /etc/dhclient.conf(5) and execute dhclient-script(8) with data from the DHCP server
 25  
 26  3. resolv.conf(5) is changed to reflect the network configuration
 27  
 28  4. pinging hardenedbsd.org works
 29  
 30  So every time we change wi-fi network, this process is repeated and we have the 
 31  configuration file /etc/resolv.conf(5) rewritten.
 32  
 33  ## Run local-unbound
 34  
 35  The normal process to connect to network with DHCP give us new DNS nameservers
 36  to query, so we can avoid this regular change by running a DNS resolver
 37  and we have `local-unbound` in base and easy available.
 38  
 39  During a fresh install of HardenedBSD 12-STABLE you can activate `local_unbound`
 40  on the setup program or if you're already running HardenedBSD, you can enable it
 41  by running the command:
 42  
 43  `sysrc local_unbound_enable=YES`
 44  
 45  or add in /etc/rc.conf:
 46  
 47  `local_unbound_enable="YES"`
 48  
 49  After enable `local-unbound(8)` we need to start it:
 50  
 51  `service local_unbound onestart`
 52  
 53  This runs `local-unbound-setup` and configures the service. Adding several
 54  changes, setting up chroot environment to run the service, and updating
 55  configuration files:
 56  
 57  - `/etc/resolv.conf`: add `nameserver 127.0.0.1` and comment out all others
 58  
 59  - `/etc/unbound/*`: add conf files with defaults and `forward.conf` with nameservers
 60  from `/etc/resolv.conf`
 61  
 62  - `/etc/resolvconf.conf(5)`: this file is written by the script, and contains
 63  `resolv_conf="/dev/null"` to prevent updating of this file by resolver
 64  
 65  #### The process of connecting to network (revised)
 66  
 67  The process now is as follows: 
 68  
 69  1. select network 
 70  
 71  2. `dhclient(8)` is called to obtain configuration where it reads
 72  `/etc/dhclient.conf(5)` and execute `dhclient-script(8)` with data from router
 73  
 74  3. `/etc/resolv.conf(5)` is changed to reflect the network configuration
 75  
 76  4. `local-unbound(8)` updates its configuration but doesn't touch `/etc/resolv.conf(5)`
 77  
 78  5. ping hardenedbsd.org doesn't works
 79  
 80  ## Solution to this problem
 81  
 82  The problem for keeping your choice of DNS and running `local-unbound(8)` is
 83  `dhclient(8)` rewriting our `/etc/resolv.conf(5)`. We should also setup the 
 84  `local-unbound-setup` to not change `local-unbound(8)` configuration files.
 85  
 86  ### Stop dhclient rewrite /etc/resolv.conf
 87  
 88  Every time `dhclient(8)` runs to get network configuration it changes 
 89  `/etc/resolv.conf(5)`, specially removing `nameserver 127.0.0.1`.
 90  
 91  To solve, create file /etc/dhclient-enter-hooks with the content:
 92  
 93  ```sh
 94  # disable dhclient(8) rewriting resolv.conf(5) when setup network
 95  
 96  add_new_resolv_conf() {
 97          return 0
 98  }
 99  ```
100  
101  This overrides the function that `dhclient-script(8)` has defined.
102  
103  ### Add unbound forward-zone config file
104  
105  Create file /etc/unbound/conf.d/01-nameserver.conf with the content:
106  
107  ```sh
108  # user choice of DNS resolvers
109  
110  forward-zone:
111          name: "."
112          forward-addr: IP
113  ```
114  
115  Where `IP` is the IP address of the DNS nameserver.
116  For more than one name-server, provide additional `forward-addr:` lines.
117  
118  Note that by default `local-unbound` runs with DNSSEC active,
119  to disable check section "Disable DNSSEC"
120  
121  Placing files in folder `conf.d` assures that every time `local-unbound-setup` is run
122  when connecting to network you don't lose your configuration.
123  
124  More information: [unbound.conf(8)](https://www.freebsd.org/cgi/man.cgi?query=unbound.conf&apropos=0&sektion=0&manpath=FreeBSD+12.0-RELEASE+and+Ports&arch=default&format=html)
125  
126  ### Check /etc/resolv.conf
127  
128  Make sure `/etc/resolv.conf(5)` as this entry `nameserver 127.0.0.1`.
129  
130  *Note: Insert only this nameserver entry. If you have more, this must be first but check CAVEAT*
131  
132  ### CAVEAT
133  
134  Forward-zone names have to be unique, so if you have `/etc/resolv.conf(5)`
135  multiple entries for nameservers, `local-unbound-setup` will fill 
136  `/etc/unbound/forward.conf` with those entries and the name of the zone
137  will be `name : "."`.
138  
139  Note that `nameserver 127.0.0.1`as to be the first entry of nameservers.
140  
141  This will result in error and may cause nondeterministic behaviour.
142  
143  ## Other options
144  
145  #### Disable DNSSEC
146  
147  Add `/etc/unbound/conf.d/99-disable-dnssec.conf`
148  
149  ```sh
150  # Disable unbound DNSSEC workings
151  
152  server:
153          harden-dnssec-stripped: no
154          disable-dnssec-lame-check: yes
155  ```
156  
157  #### Use IPv6
158  
159  For IPv6 users:
160  
161  1. add `nameserver ::1` to /etc/resolv.conf(5)
162  
163  2. add `forward-addr: Address` in IPv6 unbound config file with
164  nameservers.