1.\" $NetBSD: ifwatchd.8,v 1.29 2019/02/17 20:50:25 gutteridge Exp $ 2.\" 3.\" Copyright (c) 2001-2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Martin Husemann <martin@NetBSD.org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 17, 2019 31.Dt IFWATCHD 8 32.Os 33.Sh NAME 34.Nm ifwatchd 35.Nd "watch for addresses added to or deleted from interfaces and call up/down-scripts for them" 36.Sh SYNOPSIS 37.Nm 38.Op Fl hiqv 39.Op Fl A Ar arrival-script 40.Op Fl c Ar carrier-script 41.Op Fl D Ar departure-script 42.Op Fl d Ar down-script 43.Op Fl u Ar up-script 44.Op Fl n Ar no-carrier-script 45.Ar ifname(s) 46.Sh DESCRIPTION 47.Nm 48is used to monitor dynamic interfaces (for example PPP interfaces) 49for address changes, and to monitor static interfaces for carrier 50changes. 51Sometimes these interfaces are accompanied by a daemon program, 52which can take care of running any necessary scripts (like 53.Xr pppd 8 ) , 54but sometimes the interfaces run completely autonomously (like 55.Xr pppoe 4 ) . 56.Pp 57.Nm 58provides a generic way to watch these types of changes. 59It works by monitoring the routing socket and interpreting 60.Ql RTM_NEWADDR 61.Pq address added , 62.Ql RTM_DELADDR 63.Pq address deleted 64and 65.Ql RTM_IFINFO 66.Pq carrier detect or loss of carrier 67messages. 68It does not need special privileges to do this. 69The scripts called for up or down events are run with the same user 70id as 71.Nm 72is run. 73.Pp 74The following options are available: 75.Bl -tag -width indent 76.It Fl A Ar arrival-script 77Specify the command to invoke on arrival of new interfaces (like 78PCMCIA cards). 79.It Fl c Ar carrier-script 80Specify the command to invoke when the carrier status transitions from 81no carrier to carrier. 82.It Fl D Ar departure-script 83Specify the command to invoke when an interface departs (for example 84a PCMCIA card is removed.) 85.It Fl d Ar down-script 86Specify the command to invoke on 87.Dq interface down 88events (or: deletion of an address from an interface). 89.It Fl h 90Show the synopsis. 91.It Fl i 92Inhibit a call to the up-script on startup for all watched interfaces 93already marked up. 94If this option is not given, 95.Nm 96will check all watched interfaces on startup whether they are 97already marked up and, if they are, call the up-script with 98appropriate parameters. 99Additionally, if the interface is up and has a link, 100.Nm 101will run the carrier script. 102.Pp 103Since ifwatchd typically is started late in the system boot sequence, 104some of the monitored interfaces may already have come up when it 105finally starts, but their up-scripts have not been called. 106By default 107.Nm 108calls them on startup to account for this (and make the scripts 109easier.) 110.It Fl n Ar no-carrier-script 111Specify the command to invoke when the carrier status transitions from 112carrier to no carrier. 113.It Fl q 114Be quiet and don't log non-error messages to syslog. 115.It Fl u Ar up-script 116Specify the command to invoke on 117.Dq interface up 118events (or: addition of an address to an interface). 119.It Fl v 120Run in verbose debug mode and do not detach from the controlling 121terminal. 122Output verbose progress messages and flag errors ignored during 123normal operation. 124.Em You do not want to use this option in 125.Pa /etc/rc.conf ! 126.It Ar ifname(s) 127The name of the interface to watch. 128Multiple interfaces may be specified. 129Events for other interfaces are ignored. 130.El 131.Sh EXAMPLES 132.Bd -literal -offset indent 133# ifwatchd -u /etc/ppp/ip-up -d /etc/ppp/ip-down pppoe0 134.Ed 135.Pp 136If your pppoe0 interface is your main connection to the internet, 137the typical use of the up/down scripts is to add and remove a 138default route. 139This is an example for an up script doing this: 140.Bd -literal -offset indent 141#! /bin/sh 142/sbin/route add default $5 143/sbin/route add -inet6 default fe80::2 -iface ifp $1 144.Ed 145.Pp 146As described below the fifth command line parameter will contain 147the peer address of the pppoe link. 148The corresponding ip-down script is: 149.Bd -literal -offset indent 150#! /bin/sh 151/sbin/route delete default $5 152/sbin/route delete -inet6 default fe80::2 153.Ed 154.Pp 155Note that this is not a good idea if you have pppoe0 configured to 156connect only on demand (via the link1 flag), but works well for 157all permanent connected cases. 158Use 159.Bd -literal -offset indent 160! /sbin/route add default -iface 0.0.0.1 161.Ed 162.Pp 163in your 164.Pa /etc/ifconfig.pppoe0 165file in the on-demand case. 166.Sh PARAMETERS PASSED TO SCRIPTS 167The invoked scripts get passed these parameters: 168.Bl -tag -width destination 169.It Ar ifname 170The name of the interface this change is for (this allows to share 171the same script for multiple interfaces watched and dispatching on 172the interface name in the script). 173.It Ar tty 174Dummy parameter for compatibility with 175.Xr pppd 8 176which will always be 177.Em /dev/null . 178.It Ar speed 179Dummy parameter for compatibility with 180.Xr pppd 8 181which will always be 182.Em 9600 . 183.It Ar address 184The new address if this is an up event, or the no longer valid old 185address if this is a down event. 186.Pp 187The format of the address depends on the address family, for IPv4 188it is the usual dotted quad notation, for IPv6 the colon separated 189standard notation. 190.It Ar destination 191For point to point interfaces, this is the remote address of the 192interface. 193For other interfaces it is the broadcast address. 194.El 195.Sh ERRORS 196The program logs to the syslog daemon as facility 197.Dq daemon . 198For detailed debugging use the 199.Fl v 200(verbose) option. 201.Sh SEE ALSO 202.Xr pppoe 4 , 203.Xr route 4 , 204.Xr ifconfig.if 5 , 205.Xr rc.d 8 , 206.Xr route 8 207.Sh HISTORY 208The 209.Nm 210utility appeared in 211.Nx 1.6 . 212.Sh AUTHORS 213The program was written by 214.An Martin Husemann 215.Aq martin@NetBSD.org . 216.Sh CAVEATS 217Due to the nature of the program a lot of stupid errors can not 218easily be caught in advance without removing the provided facility 219for advanced uses. 220For example typing errors in the interface name can not be detected 221by checking against the list of installed interfaces, because it 222is possible for a pcmcia card with the name given to be inserted 223later. 224