openresolv-1.6
[openresolv] / resolvconf.8.in
index 061bb46d8f54a532051f0c120fe09fe11b0b48e2..9e601ab5b9c3265b52c573be9f334c3725916591 100644 (file)
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd Feb 09, 2008
+.Dd Mar 07, 2008
 .Dt RESOLVCONF 8 SMM
 .Sh NAME
 .Nm resolvconf
 .Nm
 .Fl a Ar interface No < Ns Pa file
 .Nm
+.Op Fl f
 .Fl d Ar interface
 .Nm
 .Fl il Ar pattern
 .Nm
 .Fl u
 .Sh DESCRIPTION
-.Nm manages
+.Nm
+manages
 .Xr resolv.conf 5
 files from multiple sources, such as DHCP and VPN clients.
 Traditionally, the host runs just one client and that updates
 .Pa /etc/resolv.conf .
 More modern systems frequently have wired and wireless interfaces and there is
-no guarantee both are on the same network. With the advent of VPN and other
-types of networking daemons, many things contend for
+no guarantee both are on the same network.
+With the advent of VPN and other
+types of networking daemons, many things now contend for the contents of
 .Pa /etc/resolv.conf .
 .Pp
 .Nm
@@ -67,17 +70,29 @@ or
 .Xr named 8
 then
 .Nm
-will configure
-.Pa /etc/resolv.conf
-to use that and supply files that the resolver should be configured to include.
+will supply files that the resolver should be configured to include.
 This allows
 .Nm
 to configure the local resolver such that
 .Pa resolv.conf
 files specifiying a domain only query the listed nameservers when resolving
-for that domain. Otherwise the nameservers are treated as global nameservers.
+for that domain.
+Otherwise the nameservers are treated as global nameservers.
 This in turn means, that you can trivially configure nameservers for say
 VPN domains.
+Example:-
+.Bd -literal -offset indent
+# resolv.conf from bge0
+search foo.com
+nameserver 1.2.3.4
+
+# resolv.conf from tap0
+domain bar.org
+nameserver 5.6.7.8
+.Ed
+.Pp
+In this instance, nameserver 5.6.7.8 will only handle requests for bar.org
+and nameserver 1.2.3.4 will handle everything else.
 .Pp
 When an interface goes down, it should then call
 .Nm
@@ -92,6 +107,9 @@ Here are some more options that
 .Nm
 has:-
 .Bl -tag -width indent
+.It Fl f
+Ignore non existant interfaces.
+Only really useful for deleting interfaces.
 .It Fl i Ar pattern
 List the interfaces, optionally matching
 .Ar pattern ,
@@ -101,7 +119,8 @@ files for.
 .It Fl l Ar pattern
 List the
 .Pa resolv.conf
-files we have. If
+files we have.
+If
 .Ar pattern
 is specified then we list the files for the interfaces that match it.
 .It Fl u
@@ -128,58 +147,50 @@ the resolver easily.
 .El
 .Sh FILES
 .Bl -ohang
-.It Pa @PREFIX@/etc/resolvconf/run
+.It Pa @VARBASE@/run/resolvconf
 Directory that holds the data for
 .Nm .
-Normally a symlink to
-.Pa /var/run/resolvconf .
-You could symlink
-.Pa /etc/resolv.conf
-to
-.Pa resolvconf/run/resolv.conf
-to support a read only
-.Pa /etc .
-.It Pa @PREFIX@/etc/resolvconf/update.d
+.It Pa @SYSCONFDIR@/update.d
 Directory of the helper scripts which are run every time
 .Nm
 adds, deletes or updates.
-.It Pa @PREFIX@/etc/resolvconf/update-libc.d
+.It Pa @SYSCONFDIR@/update-libc.d
 Directory of helper scripts which are run after the libc helper script is run.
-.It Pa @PREFIX@/etc/resolvconf/interface-order
+.It Pa @SYSCONFDIR@/interface-order
 Determines the order in which nameserver information records are processed
 by resolvconf -l.
-.It Pa @PREFIX@/etc/resolvconf/resolv.conf.d/base
+.It Pa @SYSCONFDIR@/resolv.conf.d/base
 Contains basic resolver information which is included in
 .Pa /etc/resolv.conf
 even when no interfaces are configured.
-.It Pa @PREFIX@/etc/resolvconf/resolv.conf.d/head
+.It Pa @SYSCONFDIR@/resolv.conf.d/head
 File to be prepended to
 .Pa /etc/resolv.conf .
 Normally this is just a comment line.
-.It Pa @PREFIX@/etc/resolvconf/resolv.conf.d/tail
+.It Pa @SYSCONFDIR@/resolv.conf.d/tail
 File to be appended to
 .Pa /etc/resolv.conf .
 .El
 .Sh HISTORY
+This implementation of
 .Nm
-is fully command line compatible with Debians resolvconf,
-as written by Thomas Hood.
-.Nm
-also shares a similar directory structure with the Debian version,
+is called openresolv and is fully command line compatible with Debians
+resolvconf, as written by Thomas Hood, on which openresolv is based.
+openresolv also shares a similar directory structure with the Debian version,
 but the included helpers are not compatible.
 .Pp
-The Debian version only works with bash and other GNU userland tools, where-as
-.Nm
-works with a POSIX shell and userland tools.
+The Debian version only works with bash and other GNU userland tools, whereas
+openresolv works with a POSIX shell and userland tools.
 .Sh BUGS
 .Nm
 does not validate any of the files given to it.
-.Sh LOCAL RESOLVERS
+.Pp
 When running a local resolver other than libc, you will need to configure it
 to include files that
 .Nm
-will generate. You should consult the comment section in the helper script
-for your resolver found in @PREFIX@/etc/resolvconf/update.d for instructions
+will generate.
+You should consult the comment section in the helper script
+for your resolver found in @SYSCONFDIR@/update.d for instructions
 on this.
 .Sh SEE ALSO
 .Xr dnsmasq 8 ,
@@ -188,6 +199,6 @@ on this.
 .Xr resolver 3 ,
 .Xr stdin 3
 .Sh AUTHORS
-.An "Roy Marples" Aq roy@marples.name
+.An Roy Marples <roy@marples.name>
 .Sh BUGS
 Please report them to http://bugs.marples.name