diff options
Diffstat (limited to 'contrib/openresolv/resolvconf.conf.5.in')
-rw-r--r-- | contrib/openresolv/resolvconf.conf.5.in | 152 |
1 files changed, 139 insertions, 13 deletions
diff --git a/contrib/openresolv/resolvconf.conf.5.in b/contrib/openresolv/resolvconf.conf.5.in index 454aac5..d4f6543 100644 --- a/contrib/openresolv/resolvconf.conf.5.in +++ b/contrib/openresolv/resolvconf.conf.5.in @@ -1,4 +1,4 @@ -.\" Copyright (c) 2009-2010 Roy Marples +.\" Copyright (c) 2009-2015 Roy Marples .\" All rights reserved .\" .\" Redistribution and use in source and binary forms, with or without @@ -22,8 +22,8 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 29, 2010 -.Dt RESOLVCONF.CONF 5 SMM +.Dd March 20, 2015 +.Dt RESOLVCONF.CONF 5 .Os .Sh NAME .Nm resolvconf.conf @@ -42,12 +42,22 @@ must contain valid shell commands. Listed below are the standard .Nm variables that may be set. +If the values contain white space for special shell characters, +ensure they are quoted and escaped correctly. .Pp After updating this file, you may wish to run .Nm resolvconf -u to apply the new configuration. +.Pp +When a dynamically generated list is appended or prepended to, the whole +is made unique where left-most wins. .Sh RESOLVCONF OPTIONS .Bl -tag -width indent +.It Sy resolvconf +Set to NO to disable +.Nm resolvconf +from running any subscribers. +Defaults to YES. .It Sy interface_order These interfaces will always be processed first. If unset, defaults to the following:- @@ -56,16 +66,27 @@ If unset, defaults to the following:- These interfaces will be processed next, unless they have a metric. If unset, defaults to the following:- .D1 tap[0-9]* tun[0-9]* vpn vpn[0-9]* ppp[0-9]* ippp[0-9]* +.It Sy local_nameservers +If unset, defaults to the following:- +.D1 127.* 0.0.0.0 255.255.255.255 ::1 .It Sy search_domains Prepend search domains to the dynamically generated list. .It Sy search_domains_append Append search domains to the dynamically generated list. +.It Sy domain_blacklist +A list of domains to be removed from consideration. +To remove a domain, you can use foo.* +To remove a sub domain, you can use *.bar .It Sy name_servers Prepend name servers to the dynamically generated list. You should set this to 127.0.0.1 if you use a local name server other than libc. .It Sy name_servers_append Append name servers to the dynamically generated list. +.It Sy name_server_blacklist +A list of name servers to be removed from consideration. +The default is 0.0.0.0 as some faulty routers send it via DHCP. +To remove a block, you can use 192.168.* .It Sy private_interfaces These interfaces name servers will only be queried for the domains listed in their resolv.conf. @@ -73,6 +94,34 @@ Useful for VPN domains. This is equivalent to the .Nm resolvconf -p option. +.It Sy replace +Is a space separated list of replacement keywords. The syntax is this: +.Va $keyword Ns / Ns Va $match Ns / Ns Va $replacement +.Pp +Example, given this resolv.conf: +.D1 domain foo.org +.D1 search foo.org dead.beef +.D1 nameserver 1.2.3.4 +.D1 nameserver 2.3.4.5 +and this configuaration: +.D1 replace="search/foo*/bar.com nameserver/1.2.3.4/5.6.7.8 nameserver/2.3.4.5/" +you would get this resolv.conf instead: +.D1 domain foo.org +.D1 search bar.com +.D1 nameserver 5.6.7.8 +.It Sy replace_sub +Works the same way as +.Sy replace +except it works on each space separated value rather than the whole line, +so it's useful for the replacing a single domain within the search directive. +Using the same example resolv.conf and changing +.Sy replace +to +.Sy replace_sub , +you would get this resolv.conf instead: +.D1 domain foo.org +.D1 search bar.com dead.beef +.D1 nameserver 5.6.7.8 .It Sy state_dir Override the default state directory of .Pa @VARDIR@ . @@ -96,6 +145,32 @@ A list of libc resolver options, as specified in When set to YES the latest resolv.conf is written to .Sy resolv_conf without any alteration. +When set to /dev/null or NULL, +.Sy resolv_conf_local_only +is defaulted to NO, +.Sy local_nameservers +is unset unless overriden and only the information set in +.Nm +is written to +.Sy resolv_conf . +.It Sy resolv_conf_sortlist +A libc resolver sortlist, as specified in +.Xr resolv.conf 5 . +.It Sy resolv_conf_local_only +If a local name server is configured then the default is just to specify that +and ignore all other entries as they will be configured for the local +name server. +Set this to NO to also list non-local nameservers. +This will give you working DNS even if the local nameserver stops functioning +at the expense of duplicated server queries. +.It Sy append_nameservers +Append name servers to the dynamically generated list. +.It Sy prepend_nameservers +Prepend name servers to the dynamically generated list. +.It Sy append_search +Append search domains to the dynamically generated list. +.It Sy prepend_search +Prepend search domains to the dynamically generated list. .El .Sh SUBSCRIBER OPTIONS openresolv ships with subscribers for the name servers @@ -106,11 +181,15 @@ and .Xr unbound 8 . Each subscriber can create configuration files which should be included in in the subscribers main configuration file. +.Pp +To disable a subscriber, simply set it's name to NO. +For example, to disable the libc subscriber you would set: +.D1 libc=NO .Bl -tag -width indent .It Sy dnsmasq_conf -This file tells dnsmasq which nameservers to use for specific domains. +This file tells dnsmasq which name servers to use for specific domains. .It Sy dnsmasq_resolv -This file tells dnsmasq which nameservers to use for global lookups. +This file tells dnsmasq which name servers to use for global lookups. .Pp Example resolvconf.conf for dnsmasq: .D1 name_servers=127.0.0.1 @@ -119,14 +198,17 @@ Example resolvconf.conf for dnsmasq: .Pp Example dnsmasq.conf: .D1 listen-address=127.0.0.1 +.D1 # If dnsmasq is compiled for DBus then we can take +.D1 # advantage of not having to restart dnsmasq. +.D1 enable-dbus .D1 conf-file=/etc/dnsmasq-conf.conf .D1 resolv-file=/etc/dnsmasq-resolv.conf .It Sy named_options Include this file in the named options block. -This file tells named which nameservers to use for global lookups. +This file tells named which name servers to use for global lookups. .It Sy named_zones Include this file in the named global scope, after the options block. -This file tells named which nameservers to use for specific domains. +This file tells named which name servers to use for specific domains. .Pp Example resolvconf.conf for named: .D1 name_servers=127.0.0.1 @@ -147,7 +229,7 @@ setup to read .Pa pdnsd_resolv as documented below. .It Sy pdnsd_resolv -This file tells pdnsd about global nameservers. +This file tells pdnsd about global name servers. If this variable is not set then it's written to .Pa pdnsd_conf . .Pp @@ -168,7 +250,9 @@ Example pdnsd.conf: .D1 # file="/etc/pdnsd-resolv.conf"; .D1 } .It Sy unbound_conf -This file tells unbound about specific and global nameservers. +This file tells unbound about specific and global name servers. +.It Sy unbound_insecure +When set to YES, unbound marks the domains as insecure, thus ignoring DNSSEC. .Pp Example resolvconf.conf for unbound: .D1 name_servers=127.0.0.1 @@ -177,11 +261,53 @@ Example resolvconf.conf for unbound: Example unbound.conf: .D1 include: /etc/unbound-resolvconf.conf .El +.Sh SUBSCRIBER INTEGRATION +Not all distributions store the files the subscribers need in the same +locations. +For example, named service scripts have been called named, bind and rc.bind +and they could be located in a directory called /etc/rc.d, /etc/init.d or +similar. +Each subscriber attempts to automatically configure itself, but not every +distribution has been catered for. +Also, users could equally want to use a different version from the one +installed by default, such as bind8 and bind9. +To accomodate this, the subscribers have these files in configurable +variables, documented below. +.Pp +.Bl -tag -width indent +.It Sy dnsmasq_service +Location of the dnsmasq service. +.It Sy dnsmasq_restart +Command to restart the dnsmasq service. +.It Sy dnsmasq_pid +Location of the dnsmasq pidfile. +.It Sy libc_service +Location of the libc service. +.It Sy libc_restart +Command to restart the libc service. +.It Sy named_service +Location of the named service. +.It Sy named_restart +Command to restart the named service. +.It Sy pdnsd_restart +Command to restart the pdnsd service. +.It Sy unbound_service +Location of the unbound service. +.It Sy unbound_restart +Command to restart the unbound service. +.It Sy unbound_pid +Location of the unbound pidfile. +.El .Sh SEE ALSO -.Xr resolv.conf 5 +.Xr resolv.conf 5 , +.Xr resolvconf 8 and -.Xr resolvconf 8 . +.Xr sh 1 . .Sh AUTHORS -.An Roy Marples Aq roy@marples.name +.An Roy Marples Aq Mt roy@marples.name .Sh BUGS -Please report them to http://roy.marples.name/projects/openresolv +Each distribution is a special snowflake and likes to name the same thing +differently, namely the named service script. +.Pp +Please report them to +.Lk http://roy.marples.name/projects/openresolv |