aboutsummaryrefslogtreecommitdiffstats
path: root/resolvconf.conf.5.in
diff options
context:
space:
mode:
Diffstat (limited to 'resolvconf.conf.5.in')
-rw-r--r--resolvconf.conf.5.in187
1 files changed, 187 insertions, 0 deletions
diff --git a/resolvconf.conf.5.in b/resolvconf.conf.5.in
new file mode 100644
index 000000000000..9a47a1caed6f
--- /dev/null
+++ b/resolvconf.conf.5.in
@@ -0,0 +1,187 @@
+.\" Copyright (c) 2009-2010 Roy Marples
+.\" All rights reserved
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" 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
+.Os
+.Sh NAME
+.Nm resolvconf.conf
+.Nd resolvconf configuration file
+.Sh DESCRIPTION
+.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
+to apply the new configuration.
+.Sh RESOLVCONF OPTIONS
+.Bl -tag -width indent
+.It Sy interface_order
+These interfaces will always be processed first.
+If unset, defaults to the following:-
+.D1 lo lo[0-9]*
+.It Sy dynamic_order
+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 search_domains_append
+Append 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 name_servers_append
+Append name servers to the dynamically generated list.
+.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
+.Xr resolv.conf 5
+directly:-
+.Bl -tag -width indent
+.It Sy resolv_conf
+Defaults to
+.Pa /etc/resolv.conf
+if not set.
+.It Sy resolv_conf_options
+A list of libc resolver options, as specified in
+.Xr resolv.conf 5 .
+.It Sy resolv_conf_passthrough
+When set to YES the latest resolv.conf is written to
+.Sy resolv_conf
+without any alteration.
+.El
+.Sh SUBSCRIBER OPTIONS
+openresolv ships with subscribers for the name servers
+.Xr dnsmasq 8 ,
+.Xr named 8 ,
+.Xr pdnsd 8
+and
+.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
+This file tells dnsmasq which nameservers to use for specific domains.
+.It Sy dnsmasq_resolv
+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
+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
+and
+.Xr resolvconf 8 .
+.Sh AUTHORS
+.An Roy Marples Aq roy@marples.name
+.Sh BUGS
+Please report them to http://roy.marples.name/projects/openresolv