NetBSD/usr.sbin/ifwatchd/ifwatchd.8

.\" $NetBSD: ifwatchd.8,v 1.4 2001/12/10 15:04:51 wiz Exp $
.\"
.\" Copyright (C) 2001 by Martin Husemann
.\" 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(S) ``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(S) 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 September 2, 2001
.Os
.Dt IFWATCHD 8
.Sh NAME
.Nm ifwatchd
.Nd "watch for addresses added to or deleted from interfaces and call up/down-scripts for them"
.Sh SYNOPSIS
.Nm
.Op Fl d Ar down-script
.Op Fl h
.Op Fl i
.Op Fl u Ar up-script
.Op Fl v
.Ar ifname(s)
.Sh DESCRIPTION
.Nm
is used to monitor dynamic interfaces (for example PPP interfaces) for address
changes.  Sometimes these interfaces are accompanied by a daemon program, which
can take care of running any necessary scripts (like
.Xr pppd 8
or
.Xr isdnd 8 ) ,
but sometimes the interfaces run completely autonomously (like
.Xr pppoe 8 ) .
.Pp
.Nm
provides a generic way to watch this type of changes.  It works by monitoring
the routing socket and interpreting
.Ql RTM_NEWADDR
.Pq address added
and
.Ql RTM_DELADDR
.Pq address deleted
messages.  It does not need special privileges to do this.  The scripts called
for up or down events are run with the same user id as
.Nm
is run.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl d Ar down-script
Specify the command to invoke on
.Dq interface down
events (or: deletion of an address from an interface).
.It Fl h
Show the synopsis.
.It Fl i
Inhibit a call to the up-script on startup for all watched interfaces
already marked up. If this option is not given,
.Nm
will check all watched interfaces on startup whether they are already marked
up and, if they are, call the up-script with appropriate parameters.
.Pp
Since ifwatchd typically is started late in the system boot sequence, some
of the monitored interfaces may already have come up when it finally starts,
but their up-scripts have not been called. By default
.Nm
calls them on startup to account for this (and make the scripts easier.)
.It Fl u Ar up-script
Specify the command to invoke on
.Dq interface up
events (or: addition of an address to an interface).
.It Fl v
Output verbose progress messages and flag errors ignored during normal
operation.
.It Ar ifname(s)
The name of the interface to watch.  Multiple interfaces may be specified.
Events for other interfaces are ignored.
.El
.Sh EXAMPLES
.Bd -literal -offset indent
# ifwatchd -u /etc/ppp/ip-up -d /etc/ppp/ip-down pppoe0
.Ed
.Sh PARAMETERS PASSED TO SCRIPTS
The invoked scripts get three parameters passed:
.Bl -tag -width address
.It Ar ifname
The name of the interface this change is for (this allows to share the same
script for multiple interfaces watched and dispatching on the interface name
in the script).
.It Ar up/down
Verbatim
.Em up
or
.Em down ,
which allows for the sharing of up and down scripts.
.It Ar address
The new address if this is an up event, or the no longer valid old address
if this is a down event.
.Pp
The format of the address depends on the address family, for IPv4 it is the
usual dotted quad notation, for IPv6 the colon separated standard notation.
.El
.Sh SEE ALSO
.Xr route 4 ,
.Xr ifconfig.if 5 ,
.Xr pppoe 8 ,
.Xr rc.d 8 ,
.Xr route 8
.Sh HISTORY
The
.Nm
utility appeared in
.Nx 1.6 .
.Sh AUTHORS
The program was written by
.An Martin Husemann Aq martin@netbsd.org .