258 lines
8.3 KiB
Groff
258 lines
8.3 KiB
Groff
.\" $NetBSD: ifwatchd.8,v 1.23 2004/11/25 16:05:11 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001-2003 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Martin Husemann <martin@NetBSD.org>.
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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 November 4, 2004
|
|
.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 hiqv
|
|
.Op Fl A Ar arrival-script
|
|
.Op Fl c Ar carrier-script
|
|
.Op Fl D Ar departure-script
|
|
.Op Fl d Ar down-script
|
|
.Op Fl u Ar up-script
|
|
.Op Fl n Ar no-carrier-script
|
|
.Ar ifname(s)
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is used to monitor dynamic interfaces (for example PPP interfaces)
|
|
for address changes, and to monitor static interfaces for carrier
|
|
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 4 ) .
|
|
.Pp
|
|
.Nm
|
|
provides a generic way to watch these types of changes.
|
|
It works by monitoring the routing socket and interpreting
|
|
.Ql RTM_NEWADDR
|
|
.Pq address added ,
|
|
.Ql RTM_DELADDR
|
|
.Pq address deleted
|
|
and
|
|
.Ql RTM_IFINFO
|
|
.Pq carrier detect or loss of carrier
|
|
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 A Ar arrival-script
|
|
Specify the command to invoke on arrival of new interfaces (like
|
|
PCMCIA cards).
|
|
.It Fl c Ar carrier-script
|
|
Specify the command to invoke when the carrier status transitions from
|
|
no carrier to carrier.
|
|
.It Fl D Ar departure-script
|
|
Specify the command to invoke when an interface departs (for example
|
|
a PCMCIA card is removed.)
|
|
.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.
|
|
Additionally, if the interface is up and has a link,
|
|
.Nm
|
|
will run the carrier script.
|
|
.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 n Ar no-carrier-script
|
|
Specify the command to invoke when the carrier status transitions from
|
|
carrier to no carrier.
|
|
.It Fl q
|
|
Be quiet and don't log non-error messages to syslog.
|
|
.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
|
|
Run in verbose debug mode and do not detach from the controlling
|
|
terminal.
|
|
Output verbose progress messages and flag errors ignored during
|
|
normal operation.
|
|
.Em You do not want to use this option in
|
|
.Pa /etc/rc.conf !
|
|
.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
|
|
.Pp
|
|
If your pppoe0 interface is your main connection to the internet,
|
|
the typical use of the up/down scripts is to add and remove a
|
|
default route.
|
|
This is an example for an up script doing this:
|
|
.Bd -literal -offset indent
|
|
#! /bin/sh
|
|
/sbin/route add default $5
|
|
.Ed
|
|
.Pp
|
|
As described below the fifth command line parameter will contain
|
|
the peer address of the pppoe link.
|
|
The corresponding ip-down script is:
|
|
.Bd -literal -offset indent
|
|
#! /bin/sh
|
|
/sbin/route delete default $5
|
|
.Ed
|
|
.Pp
|
|
Note that this is not a good idea if you have pppoe0 configured to
|
|
connect only on demand (via the link1 flag), but works well for
|
|
all permanent connected cases.
|
|
Use
|
|
.Bd -literal -offset indent
|
|
! /sbin/route add default -iface 0.0.0.1
|
|
.Ed
|
|
.Pp
|
|
in your
|
|
.Pa /etc/ifconfig.pppoe0
|
|
file in the on-demand case.
|
|
.Pp
|
|
The next example is for dhclient users.
|
|
.Bd -literal -offset indent
|
|
# ifwatchd -i -c /etc/dhcp/carrier-detect tlp0
|
|
.Ed
|
|
.Pp
|
|
With the above command, the carrier-detect script will be invoked when
|
|
a carrier is detected on the interface
|
|
.Ar tlp0 .
|
|
Note that the
|
|
.Ar -i
|
|
flag prevents any action based on the initial state.
|
|
A script like the following should work for most users, although it
|
|
will not work for machines with multiple interfaces running
|
|
.Cm dhclient .
|
|
.Bd -literal -offset indent
|
|
#! /bin/sh
|
|
# Arguments: ifname tty speed address destination
|
|
# If there is a dhclient already running, kill it.
|
|
# (This step could be put in a distinct no-carrier script,
|
|
# if desired.)
|
|
if [ -f /var/run/dhclient.pid ]; then
|
|
/bin/kill `/bin/cat /var/run/dhclient.pid`
|
|
fi
|
|
# Start dhclient again on this interface
|
|
/sbin/dhclient $1
|
|
.Ed
|
|
.Sh PARAMETERS PASSED TO SCRIPTS
|
|
The invoked scripts get passed these parameters:
|
|
.Bl -tag -width destination
|
|
.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 tty
|
|
Dummy parameter for compatibility with
|
|
.Xr pppd 8
|
|
which will always be
|
|
.Em /dev/null .
|
|
.It Ar speed
|
|
Dummy parameter for compatibility with
|
|
.Xr pppd 8
|
|
which will always be
|
|
.Em 9600 .
|
|
.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.
|
|
.It Ar destination
|
|
For point to point interfaces, this is the remote address of the
|
|
interface.
|
|
For other interfaces it is the broadcast address.
|
|
.El
|
|
.Sh ERRORS
|
|
The program logs to the syslog daemon as facility
|
|
.Dq daemon .
|
|
For detailed debugging use the
|
|
.Fl v
|
|
(verbose) option.
|
|
.Sh SEE ALSO
|
|
.Xr pppoe 4 ,
|
|
.Xr route 4 ,
|
|
.Xr ifconfig.if 5 ,
|
|
.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 .
|
|
.Sh CAVEATS
|
|
Due to the nature of the program a lot of stupid errors can not
|
|
easily be caught in advance without removing the provided facility
|
|
for advanced uses.
|
|
For example typing errors in the interface name can not be detected
|
|
by checking against the list of installed interfaces, because it
|
|
is possible for a pcmcia card with the name given to be inserted
|
|
later.
|