Allow pdnsd_conf to work without pdnsd_resolv.
[openresolv] / resolvconf.conf.5.in
index bef8f41fa369918592cb02ca438342c2aa26c797..0682ca0535d8cd2154a078fabf315d3a6714a5b6 100644 (file)
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2009 Roy Marples
+.\" Copyright (c) 2009-2010 Roy Marples
 .\" All rights reserved
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd November 15, 2009
+.Dd October 29, 2010
 .Dt RESOLVCONF.CONF 5 SMM
 .Os
 .Sh NAME
 .Nm
 is the configuration file for
 .Xr resolvconf 8 .
+The
+.Nm
+file is a shell script that is sourced by
+.Xr resolvconf 8 ,
+meaning that
+.Nm
+must contain valid shell commands.
+Listed below are the standard
+.Nm
+variables that may be set.
 .Pp
 After updaing this file, you may wish to run
 .Nm resolvconf -u
@@ -46,9 +56,16 @@ 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 search_domains
+Prepend search domains to the dynamically generated list.
+.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 private_interfaces
 These interfaces name servers will only be queried for the domains listed
 in their resolv.conf.
+Useful for VPN domains.
 This is equivalent to the
 .Nm resolvconf -p
 option.
@@ -71,12 +88,6 @@ if not set.
 .It Sy resolv_conf_options
 A list of libc resolver options, as specified in
 .Xr resolv.conf 5 .
-.It Sy search_domains
-Prepend search domains to the dynamically generated list.
-.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 resolv_conf_passthrough
 When set to YES the latest resolv.conf is written to
 .Sy resolv_conf
@@ -85,31 +96,82 @@ without any alteration.
 .Sh SUBSCRIBER OPTIONS
 openresolv ships with subscribers for the name servers
 .Xr dnsmasq 8 ,
-.Xr named 8
+.Xr named 8 ,
+.Xr pdnsd 8
 and
 .Xr unbound 8 .
-These subscribers have options which instruct openresolv where
-to write the configuration files for the name server to include.
+Each subscriber can create configuration files which should be included in
+in the subscribers main configuration file.
 .Bl -tag -width indent
 .It Sy dnsmasq_conf
-Set this to the same file that the dnsmasq configuaration option
-.Sy conf-file
-points to.
 This file tells dnsmasq which nameservers to use for specific domains.
 .It Sy dnsmasq_resolv
-Set this to the same file that the dnsmasq configuaration option
-.Sy resolv-file
-points to.
 This file tells dnsmasq which nameservers to use for global lookups.
+.Pp
+Example resolvconf.conf for dnsmasq:
+.D1 nameservers=127.0.0.1
+.D1 dnsmasq_conf=/etc/dnsmasq-conf.conf
+.D1 dnsmasq_resolv=/etc/dnsmasq-resolv.conf
+.Pp
+Example dnsmasq.conf:
+.D1 listen-address=127.0.0.1
+.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.
 .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.
+.Pp
+Example resolvconf.conf for named:
+.D1 nameservers=127.0.0.1
+.D1 named_options=/etc/named-options.conf
+.D1 named_zones=/etc/named-zones.conf
+.Pp
+Example named.conf:
+.D1 options {
+.D1    listen-on { 127.0.0.1; };
+.D1    include "/etc/named-options.conf";
+.D1 };
+.D1 include "/etc/named-zones.conf";
+.It Sy pdnsd_conf
+This is the main pdnsd configuration file which we modify to add our
+forward domains to.
+If this variable is not set then we rely on the pdnsd configuration file
+setup to read
+.Pa pdnsd_resolv
+as documented below.
+.It Sy pdnsd_resolv
+This file tells pdnsd about global nameservers.
+If this variable is not set then it's written to
+.Pa pdnsd_conf .
+.Pp
+Example resolvconf.conf for pdnsd:
+.D1 nameservers=127.0.0.1
+.D1 pdnsd_conf=/etc/pdnsd.conf
+.D1 # pdnsd_resolv=/etc/pdnsd-resolv.conf
+.Pp
+Example pdnsd.conf:
+.D1 global {
+.D1    server_ip = 127.0.0.1;
+.D1    status_ctl = on;
+.D1 }
+.D1 server {
+.D1    # A server definition is required, even if emtpy.
+.D1    label="empty";
+.D1    proxy_only=on;
+.D1    # file="/etc/pdnsd-resolv.conf";
+.D1 }
 .It Sy unbound_conf
-Include this file anywhere in the unbound configuration.
 This file tells unbound about specific and global nameservers.
+.Pp
+Example resolvconf.conf for unbound:
+.D1 nameservers=127.0.0.1
+.D1 unbound_conf=/etc/unbound-resolvconf.conf
+.Pp
+Example unbound.conf:
+.D1 include: /etc/unbound-resolvconf.conf
 .El
 .Sh SEE ALSO
 .Xr resolv.conf 5