Document pdnsd_conf option.
[openresolv] / resolvconf.conf.5.in
index a97c9c75a6758b7cf9b1944116760d72f9fb25b7..c295e72872cb8cccbbee57ff27e97691673e0149 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 October 25, 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,12 +56,25 @@ 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.
+.It Sy state_dir
+Override the default state directory of
+.Pa @VARDIR@ .
+This should not be changed once
+.Nm resolvconf
+is in use unless the old directory is copied to the new one.
 .El
 .Sh LIBC OPTIONS
 The following variables affect
@@ -65,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
@@ -78,29 +95,80 @@ without any alteration.
 .El
 .Sh SUBSCRIBER OPTIONS
 openresolv ships with subscribers for the name servers
-.Xr dnsmasq 8
+.Xr dnsmasq 8 ,
+.Xr named 8 ,
+.Xr pdnsd 8
 and
-.Xr named 8 .
-These subscribers take two options each which instruct openresolv where
-to write the configuration files for the name server to include.
+.Xr unbound 8 .
+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.
+.It Sy pdnsd_resolv
+This file tells pdnsd about global nameservers.
+.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    label="resolvconf";
+.D1    file="/etc/pdnsd-resolv.conf";
+.D1 }
+.It Sy unbound_conf
+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 ,
-.Xr resolvconf 8 ,
-.Xr named.conf 5
+.Xr resolv.conf 5
+and
+.Xr resolvconf 8 .
 .Sh AUTHORS
 .An Roy Marples Aq roy@marples.name
 .Sh BUGS