.\" $NetBSD: ifwatchd.8,v 1.15 2003/04/16 09:06:55 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 . .\" .\" 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 March 5, 2003 .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 hiv .Op Fl A Ar arrival-script .Op Fl D Ar departure-script .Op Fl d Ar down-script .Op Fl u Ar up-script .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 4 ) . .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 A Ar arrival-script Specify the command to invoke on arrival of new interfaces (like PCMCIA cards). .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 D Ar departure-script Specify the command to invoke when an interface departs (for example a PCMCIA card is removed.) .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 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 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 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 in your .Pa /etc/ifconfig.pppoe0 file in the on-demand case. .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 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 .