NAME
ifwatchd —
watch for addresses added to
or deleted from interfaces and call up/down-scripts for them
SYNOPSIS
ifwatchd |
[-hiqv]
[-A
arrival-script]
[-c
carrier-script]
[-D
departure-script]
[-d
down-script]
[-u
up-script]
[-n
no-carrier-script]
ifname(s) |
DESCRIPTION
ifwatchd 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
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
interfaces 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: addition 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 connect only
on demand (via the link1 flag), but works well for all permanent 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 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
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 ALSO
pppoe(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.