MirOS Manual: ifwatchd(8)

IFWATCHD(8)              BSD System Manager's Manual               IFWATCHD(8)

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 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 (such
     as pppoe(4)).

     Attention: on current MirOS, only address additions for pppoe(4) inter-
     faces are tested.

     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 (such
             as 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 ex-
             ample 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 al-
             ready marked up and, if they are, call the up-script with ap-
             propriate 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 se-
             quence, 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 ig-
             nored 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/mksh
           /sbin/route -n add default $5

     As described below the fifth command line parameter will contain the peer
     address of the pppoe link. The corresponding ip-down script is:

           #!/bin/mksh
           /sbin/route -n delete default $5

     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 per-
     manent connected cases. Use

           ! /sbin/route -n add default -iface 0.0.0.1

     in your /etc/hostname.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/mksh
           # 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
                   kill $(</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 ad-
                  dress.

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), hostname.if(5), rc.conf(8), route(8)

HISTORY

     The ifwatchd utility appeared in NetBSD 1.6 first and was ported to
     MirOS #8.

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 pos-
     sible for a pcmcia card with the name given to be inserted later.

MirOS BSD #10-current          November 4, 2004                              2

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.