IFWATCHD(8) BSD System Manager's Manual IFWATCHD(8)NAMEifwatchd — watch for addresses added to or deleted from interfaces and
call up/down-scripts for them
SYNOPSISifwatchd [-hiqv] [-A arrival-script] [-c carrier-script]
[-D departure-script] [-d down-script] [-u up-script]
[-n no-carrier-script] ifname(s)DESCRIPTIONifwatchd is used to monitor dynamic interfaces (for example PPP inter‐
faces) 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 pppd(8) or
isdnd(8)), but sometimes the interfaces run completely autonomously (like
pppoe(4)).
ifwatchd provides a generic way to watch these types of changes. It
works by monitoring the routing socket and interpreting ‘RTM_NEWADDR’
(address added), ‘RTM_DELADDR’ (address deleted) and ‘RTM_IFINFO’
(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 ifwatchd is run.
The following options are available:
-A arrival-script
Specify the command to invoke on arrival of new interfaces (like
PCMCIA cards).
-c carrier-script
Specify the command to invoke when the carrier status transitions
from no carrier to carrier.
-D departure-script
Specify the command to invoke when an interface departs (for
example a PCMCIA card is removed.)
-d down-script
Specify the command to invoke on “interface down” events (or:
deletion of an address from an interface).
-h Show the synopsis.
-i Inhibit a call to the up-script on startup for all watched inter‐
faces already marked up. If this option is not given, ifwatchd
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, ifwatchd will run the carrier script.
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 ifwatchd calls them on startup to account for
this (and make the scripts easier.)
-n no-carrier-script
Specify the command to invoke when the carrier status transitions
from carrier to no carrier.
-q Be quiet and don't log non-error messages to syslog.
-u up-script
Specify the command to invoke on “interface up” events (or: addi‐
tion of an address to an interface).
-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. You do not want to use this
option in /etc/rc.conf!
ifname(s)
The name of the interface to watch. Multiple interfaces may be
specified. Events for other interfaces are ignored.
EXAMPLES
# ifwatchd-u /etc/ppp/ip-up -d /etc/ppp/ip-down pppoe0
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:
#! /bin/sh
/sbin/route add default $5
/sbin/route add -inet6 default fe80::2 -iface ifp $1
As described below the fifth command line parameter will contain the peer
address of the pppoe link. The corresponding ip-down script is:
#! /bin/sh
/sbin/route delete default $5
/sbin/route delete -inet6 default fe80::2
Note that this is not a good idea if you have pppoe0 configured to con‐
nect only on demand (via the link1 flag), but works well for all perma‐
nent connected cases. Use
! /sbin/route add default -iface 0.0.0.1
in your /etc/ifconfig.pppoe0 file in the on-demand case.
The next example is for dhclient users.
# ifwatchd-i -c /etc/dhcp/carrier-detect tlp0
With the above command, the carrier-detect script will be invoked when a
carrier is detected on the interface tlp0. Note that the -i flag pre‐
vents 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 dhclient.
#! /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
PARAMETERS PASSED TO SCRIPTS
The invoked scripts get passed these parameters:
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).
tty Dummy parameter for compatibility with pppd(8) which will
always be /dev/null.
speed Dummy parameter for compatibility with pppd(8) which will
always be 9600.
address The new address if this is an up event, or the no longer
valid old address if this is a down event.
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.
destination For point to point interfaces, this is the remote address of
the interface. For other interfaces it is the broadcast
address.
ERRORS
The program logs to the syslog daemon as facility “daemon”. For detailed
debugging use the -v (verbose) option.
SEE ALSOpppoe(4), route(4), ifconfig.if(5), rc.d(8), route(8)HISTORY
The ifwatchd utility appeared in NetBSD 1.6.
AUTHORS
The program was written by Martin Husemann ⟨martin@NetBSD.org⟩.
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.
BSD April 16, 2010 BSD
