| 1 | .\" Copyright (c) 2009-2023 Roy Marples |
| 2 | .\" All rights reserved |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that the following conditions |
| 6 | .\" are met: |
| 7 | .\" 1. Redistributions of source code must retain the above copyright |
| 8 | .\" notice, this list of conditions and the following disclaimer. |
| 9 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 10 | .\" notice, this list of conditions and the following disclaimer in the |
| 11 | .\" documentation and/or other materials provided with the distribution. |
| 12 | .\" |
| 13 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
| 14 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 15 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 16 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 17 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 18 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 19 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 20 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 21 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 22 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 23 | .\" SUCH DAMAGE. |
| 24 | .\" |
| 25 | .Dd May 23, 2023 |
| 26 | .Dt RESOLVCONF.CONF 5 |
| 27 | .Os |
| 28 | .Sh NAME |
| 29 | .Nm resolvconf.conf |
| 30 | .Nd resolvconf configuration file |
| 31 | .Sh DESCRIPTION |
| 32 | .Nm |
| 33 | is the configuration file for |
| 34 | .Xr resolvconf 8 . |
| 35 | The |
| 36 | .Nm |
| 37 | file is a shell script that is sourced by |
| 38 | .Xr resolvconf 8 , |
| 39 | meaning that |
| 40 | .Nm |
| 41 | must contain valid shell commands. |
| 42 | Listed below are the standard |
| 43 | .Nm |
| 44 | variables that may be set. |
| 45 | If the values contain whitespace, wildcards or other special shell characters, |
| 46 | ensure they are quoted and escaped correctly. |
| 47 | See the |
| 48 | .Sy replace |
| 49 | variable for an example on quoting. |
| 50 | .Pp |
| 51 | After updating this file, you may wish to run |
| 52 | .Nm resolvconf -u |
| 53 | to apply the new configuration. |
| 54 | .Pp |
| 55 | When a dynamically generated list is appended or prepended to, the whole |
| 56 | is made unique where left-most wins. |
| 57 | .Sh RESOLVCONF OPTIONS |
| 58 | .Bl -tag -width indent |
| 59 | .It Sy resolvconf |
| 60 | Set to NO to disable |
| 61 | .Nm resolvconf |
| 62 | from running any subscribers. |
| 63 | Defaults to YES. |
| 64 | .It Sy allow_interfaces |
| 65 | If set, only these interfaces will be processed. |
| 66 | .It Sy deny_interfaces |
| 67 | If set, these interfaces will not be processed. |
| 68 | .It Sy interface_order |
| 69 | These interfaces will always be processed first. |
| 70 | If unset, defaults to the following:- |
| 71 | .Bd -compact -literal -offset indent |
| 72 | lo lo[0-9]* |
| 73 | .Ed |
| 74 | .It Sy dynamic_order |
| 75 | These interfaces will be processed next, unless they have a metric. |
| 76 | If unset, defaults to the following:- |
| 77 | .Bd -compact -literal -offset indent |
| 78 | tap[0-9]* tun[0-9]* vpn vpn[0-9]* wg[0-9]* ppp[0-9]* ippp[0-9]* |
| 79 | .Ed |
| 80 | .It Sy inclusive_interfaces |
| 81 | Ignore any exclusive marking for these interfaces. |
| 82 | This is handy when 3rd party integrations force the |
| 83 | .Nm resolvconf -x |
| 84 | option and you want to disable it easily. |
| 85 | .It Sy local_nameservers |
| 86 | If unset, defaults to the following:- |
| 87 | .Bd -compact -literal -offset indent |
| 88 | 127.* 0.0.0.0 255.255.255.255 ::1 |
| 89 | .Ed |
| 90 | .It Sy search_domains |
| 91 | Prepend search domains to the dynamically generated list. |
| 92 | .It Sy search_domains_append |
| 93 | Append search domains to the dynamically generated list. |
| 94 | .It Sy domain_blacklist |
| 95 | A list of domains to be removed from consideration. |
| 96 | To remove a domain, you can use foo.* |
| 97 | To remove a sub domain, you can use *.bar |
| 98 | .It Sy name_servers |
| 99 | Prepend name servers to the dynamically generated list. |
| 100 | You should set this to 127.0.0.1 if you use a local name server other than |
| 101 | libc. |
| 102 | .It Sy name_servers_append |
| 103 | Append name servers to the dynamically generated list. |
| 104 | .It Sy name_server_blacklist |
| 105 | A list of name servers to be removed from consideration. |
| 106 | The default is 0.0.0.0 as some faulty routers send it via DHCP. |
| 107 | To remove a block, you can use 192.168.* |
| 108 | .It Sy private_interfaces |
| 109 | These interfaces name servers will only be queried for the domains listed |
| 110 | in their resolv.conf. |
| 111 | Useful for VPN domains. |
| 112 | Setting |
| 113 | .Sy private_interfaces Ns ="*" |
| 114 | will stop the forwarding of the root zone and allows the local resolver to |
| 115 | recursively query the root servers directly. |
| 116 | Requires a local nameserver other than libc. |
| 117 | This is equivalent to the |
| 118 | .Nm resolvconf -p |
| 119 | option. |
| 120 | .It Sy public_interfaces |
| 121 | Force these interface to be public, overriding the private marking. |
| 122 | This is handy when 3rd party integrations force the |
| 123 | .Nm resolvconf -p |
| 124 | option and you want to disable it easily. |
| 125 | .It Sy replace |
| 126 | Is a space separated list of replacement keywords. |
| 127 | The syntax is this: |
| 128 | .Va $keyword Ns / Ns Va $match Ns / Ns Va $replacement |
| 129 | .Pp |
| 130 | Example, given this resolv.conf: |
| 131 | .Bd -compact -literal -offset indent |
| 132 | domain foo.org |
| 133 | search foo.org dead.beef |
| 134 | nameserver 1.2.3.4 |
| 135 | nameserver 2.3.4.5 |
| 136 | .Ed |
| 137 | and this configuration: |
| 138 | .Bd -compact -literal -offset indent |
| 139 | replace="search/foo*/bar.com" |
| 140 | replace="$replace nameserver/1.2.3.4/5.6.7.8" |
| 141 | replace="$replace nameserver/2.3.4.5/" |
| 142 | .Ed |
| 143 | you would get this resolv.conf instead: |
| 144 | .Bd -compact -literal -offset indent |
| 145 | domain foo.org |
| 146 | search bar.com |
| 147 | nameserver 5.6.7.8 |
| 148 | .Ed |
| 149 | .It Sy replace_sub |
| 150 | Works the same way as |
| 151 | .Sy replace |
| 152 | except it works on each space separated value rather than the whole line, |
| 153 | so it's useful for the replacing a single domain within the search directive. |
| 154 | Using the same example resolv.conf and changing |
| 155 | .Sy replace |
| 156 | to |
| 157 | .Sy replace_sub , |
| 158 | you would get this resolv.conf instead: |
| 159 | .Bd -compact -literal -offset indent |
| 160 | domain foo.org |
| 161 | search bar.com dead.beef |
| 162 | nameserver 5.6.7.8 |
| 163 | .Ed |
| 164 | .It Sy state_dir |
| 165 | Override the default state directory of |
| 166 | .Pa @VARDIR@ . |
| 167 | This should not be changed once |
| 168 | .Nm resolvconf |
| 169 | is in use unless the old directory is copied to the new one. |
| 170 | .El |
| 171 | .Sh LIBC OPTIONS |
| 172 | The following variables affect |
| 173 | .Xr resolv.conf 5 |
| 174 | directly:- |
| 175 | .Bl -tag -width indent |
| 176 | .It Sy resolv_conf |
| 177 | Defaults to |
| 178 | .Pa /etc/resolv.conf |
| 179 | if not set. |
| 180 | .It Sy resolv_conf_options |
| 181 | A list of libc resolver options, as specified in |
| 182 | .Xr resolv.conf 5 . |
| 183 | .It Sy resolv_conf_passthrough |
| 184 | When set to YES the latest resolv.conf is written to |
| 185 | .Sy resolv_conf |
| 186 | without any alteration. |
| 187 | When set to /dev/null or NULL, |
| 188 | .Sy resolv_conf_local_only |
| 189 | is defaulted to NO, |
| 190 | .Sy local_nameservers |
| 191 | is unset unless overridden and only the information set in |
| 192 | .Nm |
| 193 | is written to |
| 194 | .Sy resolv_conf . |
| 195 | .It Sy resolv_conf_sortlist |
| 196 | A libc resolver sortlist, as specified in |
| 197 | .Xr resolv.conf 5 . |
| 198 | .It Sy resolv_conf_local_only |
| 199 | If a local name server is configured then the default is just to specify that |
| 200 | and ignore all other entries as they will be configured for the local |
| 201 | name server. |
| 202 | Set this to NO to also list non-local nameservers. |
| 203 | This will give you working DNS even if the local nameserver stops functioning |
| 204 | at the expense of duplicated server queries. |
| 205 | .It Sy append_nameservers |
| 206 | Append name servers to the dynamically generated list. |
| 207 | .It Sy prepend_nameservers |
| 208 | Prepend name servers to the dynamically generated list. |
| 209 | .It Sy append_search |
| 210 | Append search domains to the dynamically generated list. |
| 211 | .It Sy prepend_search |
| 212 | Prepend search domains to the dynamically generated list. |
| 213 | .It Sy resolv_conf_mv |
| 214 | Defaults to NO. |
| 215 | Defines if |
| 216 | .Pa /etc/resolv.conf |
| 217 | is updated by writing to a temporary file and then moving it |
| 218 | vs writing directly to it. |
| 219 | .El |
| 220 | .Sh SUBSCRIBER OPTIONS |
| 221 | openresolv ships with subscribers for the name servers |
| 222 | .Xr dnsmasq 8 , |
| 223 | .Xr named 8 , |
| 224 | .Xr pdnsd 8 , |
| 225 | .Xr pdns_recursor 1 , |
| 226 | and |
| 227 | .Xr unbound 8 . |
| 228 | Each subscriber can create configuration files which should be included in |
| 229 | the subscribers main configuration file. |
| 230 | .Pp |
| 231 | To disable a subscriber, simply set its name to NO. |
| 232 | For example, to disable the libc subscriber you would set: |
| 233 | .Bd -compact -literal -offset indent |
| 234 | libc=NO |
| 235 | .Ed |
| 236 | .Bl -tag -width indent |
| 237 | .It Sy dnsmasq_conf |
| 238 | This file tells dnsmasq which name servers to use for specific domains. |
| 239 | .It Sy dnsmasq_resolv |
| 240 | This file tells dnsmasq which name servers to use for global lookups. |
| 241 | .Pp |
| 242 | Example resolvconf.conf for dnsmasq: |
| 243 | .Bd -compact -literal -offset indent |
| 244 | name_servers=127.0.0.1 |
| 245 | dnsmasq_conf=/etc/dnsmasq-conf.conf |
| 246 | dnsmasq_resolv=/etc/dnsmasq-resolv.conf |
| 247 | .Ed |
| 248 | .Pp |
| 249 | Example dnsmasq.conf: |
| 250 | .Bd -compact -literal -offset indent |
| 251 | listen-address=127.0.0.1 |
| 252 | # If dnsmasq is compiled for DBus then we can take |
| 253 | # advantage of not having to restart dnsmasq. |
| 254 | enable-dbus |
| 255 | conf-file=/etc/dnsmasq-conf.conf |
| 256 | resolv-file=/etc/dnsmasq-resolv.conf |
| 257 | .Ed |
| 258 | .It Sy named_options |
| 259 | Include this file in the named options block. |
| 260 | This file tells named which name servers to use for global lookups. |
| 261 | .It Sy named_zones |
| 262 | Include this file in the named global scope, after the options block. |
| 263 | This file tells named which name servers to use for specific domains. |
| 264 | .Pp |
| 265 | Example resolvconf.conf for named: |
| 266 | .Bd -compact -literal -offset indent |
| 267 | name_servers=127.0.0.1 |
| 268 | named_options=/etc/named-options.conf |
| 269 | named_zones=/etc/named-zones.conf |
| 270 | .Ed |
| 271 | .Pp |
| 272 | Example named.conf: |
| 273 | .Bd -compact -literal -offset indent |
| 274 | options { |
| 275 | listen-on { 127.0.0.1; }; |
| 276 | include "/etc/named-options.conf"; |
| 277 | }; |
| 278 | |
| 279 | include "/etc/named-zones.conf"; |
| 280 | .Ed |
| 281 | .It Sy pdnsd_conf |
| 282 | This is the main pdnsd configuration file which we modify to add our |
| 283 | forward domains to. |
| 284 | If this variable is not set then we rely on the pdnsd configuration file |
| 285 | setup to read |
| 286 | .Pa pdnsd_resolv |
| 287 | as documented below. |
| 288 | .It Sy pdnsd_resolv |
| 289 | This file tells pdnsd about global name servers. |
| 290 | If this variable is not set then it's written to |
| 291 | .Pa pdnsd_conf . |
| 292 | .Pp |
| 293 | Example resolvconf.conf for pdnsd: |
| 294 | .Bd -compact -literal -offset indent |
| 295 | name_servers=127.0.0.1 |
| 296 | pdnsd_conf=/etc/pdnsd.conf |
| 297 | # pdnsd_resolv=/etc/pdnsd-resolv.conf |
| 298 | .Ed |
| 299 | .Pp |
| 300 | Example pdnsd.conf: |
| 301 | .Bd -compact -literal -offset indent |
| 302 | global { |
| 303 | server_ip = 127.0.0.1; |
| 304 | status_ctl = on; |
| 305 | } |
| 306 | server { |
| 307 | # A server definition is required, even if empty. |
| 308 | label="empty"; |
| 309 | proxy_only=on; |
| 310 | # file="/etc/pdnsd-resolv.conf"; |
| 311 | } |
| 312 | .Ed |
| 313 | .It Sy pdns_zones |
| 314 | This file tells pdns_recursor about specific and global name servers. |
| 315 | .Pp |
| 316 | Example resolvconf.conf for pdns_recursor: |
| 317 | .Bd -compact -literal -offset indent |
| 318 | name_servers=127.0.0.1 |
| 319 | pdns_zones=/etc/pdns/recursor-zones.conf |
| 320 | .Ed |
| 321 | .Pp |
| 322 | Example recursor.conf: |
| 323 | .Bd -compact -literal -offset indent |
| 324 | allow-from=127.0.0.0/8, ::1/128 |
| 325 | forward-zones-file=/etc/pdns/recursor-zones.conf |
| 326 | .Ed |
| 327 | .It Sy unbound_conf |
| 328 | This file tells unbound about specific and global name servers. |
| 329 | .It Sy unbound_insecure |
| 330 | When set to YES, unbound marks the domains as insecure, thus ignoring DNSSEC. |
| 331 | .It Sy unbound_forward_zone_options |
| 332 | Options appended to each forward zone. |
| 333 | Each option should be separated by an embedded new line. |
| 334 | .Pp |
| 335 | Example resolvconf.conf for unbound: |
| 336 | .Bd -compact -literal -offset indent |
| 337 | name_servers=127.0.0.1 |
| 338 | unbound_conf=/etc/unbound-resolvconf.conf |
| 339 | .Ed |
| 340 | .Pp |
| 341 | Example unbound.conf: |
| 342 | .Bd -compact -literal -offset indent |
| 343 | include: /etc/unbound-resolvconf.conf |
| 344 | .Ed |
| 345 | .El |
| 346 | .Sh SUBSCRIBER INTEGRATION |
| 347 | Not all distributions store the files the subscribers need in the same |
| 348 | locations. |
| 349 | For example, named service scripts have been called named, bind and rc.bind |
| 350 | and they could be located in a directory called /etc/rc.d, /etc/init.d or |
| 351 | similar. |
| 352 | Each subscriber attempts to automatically configure itself, but not every |
| 353 | distribution has been catered for. |
| 354 | Also, users could equally want to use a different version from the one |
| 355 | installed by default, such as bind8 and bind9. |
| 356 | To accommodate this, the subscribers have these files in configurable |
| 357 | variables, documented below. |
| 358 | .Bl -tag -width indent |
| 359 | .It Sy dnsmasq_service |
| 360 | Name of the dnsmasq service. |
| 361 | .It Sy dnsmasq_restart |
| 362 | Command to restart the dnsmasq service. |
| 363 | .It Sy dnsmasq_pid |
| 364 | Location of the dnsmasq pidfile. |
| 365 | .It Sy libc_service |
| 366 | Name of the libc service. |
| 367 | .It Sy libc_restart |
| 368 | Command to restart the libc service. |
| 369 | .It Sy named_service |
| 370 | Name of the named service. |
| 371 | .It Sy named_restart |
| 372 | Command to restart the named service. |
| 373 | .It Sy pdnsd_restart |
| 374 | Command to restart the pdnsd service. |
| 375 | .It Sy pdns_service |
| 376 | Command to restart the pdns_recursor service. |
| 377 | .It Sy pdns_restart |
| 378 | Command to restart the pdns_recursor service. |
| 379 | .It Sy unbound_service |
| 380 | Name of the unbound service. |
| 381 | .It Sy unbound_restart |
| 382 | Command to restart the unbound service. |
| 383 | .It Sy unbound_pid |
| 384 | Location of the unbound pidfile. |
| 385 | .El |
| 386 | .Sh SEE ALSO |
| 387 | .Xr sh 1 , |
| 388 | .Xr resolv.conf 5 , |
| 389 | .Xr resolvconf 8 |
| 390 | .Sh AUTHORS |
| 391 | .An Roy Marples Aq Mt roy@marples.name |
| 392 | .Sh BUGS |
| 393 | Each distribution is a special snowflake and likes to name the same thing |
| 394 | differently, namely the named service script. |
| 395 | .Pp |
| 396 | Please report them to |
| 397 | .Lk https://roy.marples.name/projects/openresolv |