IFALIVE

NAME
SYNOPSIS
DESCRIPTION
EXPRESSION
OPTIONS
FILES
BUGS
SEE ALSO
AUTHORS
BUG REPORTS
COPYRIGHT

---

NAME

ifalive - check network interface activity

SYNOPSIS

ifalive -i [-dnp] IFACE [PID]

ifalive [-c] [-dn] [-s SIG] PID [EXPR...]

ifalive -r [-dnp] [PID]

ifalive -h

DESCRIPTION

Given the network interface name and the PID of the program that controls it, ifalive checks if the interface is "alive", and if not, terminates the program.

It is designed as an ancillary utility for jumper(8), to help automatically shut down inactive interfaces.

The program runs in three different operation modes, selected by the options -i, -c, and -r.

Initialization
The -i option requests initialization mode. In this mode, ifalive remembers information about the network interface, and the PID of the corresponding process that controls it.

If the PID argument is not given, the program assumes the PID of its parent process. The -p option, if used, instructs the program to use PID of the parent process of the originally obtained PID. For example,

ifalive -i -p tun0 1822

means that interface tun0 is controlled by the parent of PID 1822, whereas

ifalive -i -p tun0

means that it is controlled by the grand-parent of ifalive itself. This option can be used multiple times to move up the process ancestor tree. For example,

ifalive -i -ppp tun0 1822

means use grand-grand-parent of PID 1822.

The information is stored in a disk file /var/run/ifalive/PID. This file will then be used to store intermediate information about the state of the interface.

The initialization is normally performed right after the corresponding interface is started. For example, supposing the interface is controlled by vpnc(8), the following line should appear in the /etc/vpnc/vpnc-script-post-connect-action file:

/usr/libexec/ifalive -i -pp $TUNDEV

Periodic checking
This is the main (and the default) operation mode. It is requested by the -c option, or by the absence of the mode specifying option. The PID argument is required. The tool will first look up the interface name corresponding to that PID, and will evaluate the expression EXPR to check if the interface is active. In the absence of EXPR, the default expression is evaluated. See the section EXPRESSION, for the description.

If the expression evaluates to true, the utility will update the interface statistics in its spool file, and will exit. Otherwise, it will terminate the controlling program by sending the SIGTERM signal to PID.

The check mode is normally run periodically in a HEARTBEAT event:

onevent HEARTBEAT {
command "/usr/libexec/ifalive -c $pid";
}

Cleanup
The cleanup mode is requested by the -r command line option. In this mode, ifalive removes the state file for the given PID. The actual PID is computed as described in subsection Initialization, above.

This mode should be run when the interface goes down. For example, if the interface is controlled by vpnc, the following line should appear in the file /etc/vpnc/vpnc-script-post-disconnect-action:

/usr/libexec/ifalive -r -pp

EXPRESSION

The expression operates on two variables: the previous interface state a, and its current state, b. Both variables have a number of numeric attributes, which are accessed as X.attr, where X stands for the variable and attr for the attribute name. The following attributes are defined:
rx_bytes

Number of bytes received.

rx_packets

Number of network packets received.

rx_errors

Number of errors while receiving.

rx_dropped

Number of dropped incoming (received) packets.

rx_fifo_errors

Number of FIFO errors on incoming packets.

rx_frame_errors

Number of received frame errors.

rx_compressed

Number of received compressed format packets.

rx_multicast

Number of received multicast packets.

tx_bytes

Number of bytes transmitted.

tx_packets

Number of network packets transmitted.

tx_errors

Number of transmit errors.

tx_dropped

Number of dropped transmit packets.

tx_fifo_errors

Number of FIFO errors on transmit.

collisions

Number of collisions.

tx_carrier_errors

Number of carrier errors.

tx_compressed

Number of transmitted compressed format packets.

The usual arithmetical operations (+, -, *, /) are allowed over these values and integer numeric constants. The results can be compared using the operators: == (or ==), !=, <, <=, >, >=. The comparisons can be combined using boolean operations or and and. Logical values are negated using !. The following table lists the operators in order of their precedence. Operators down the table are executed prior to those located above. Operators on the same line are executed left to right.

or

	and
	=, ==, !=
	<, <=, >, >=
	+, -
	*, /
	unary !, unary -

Braces can be used to control the precedence.

The default expression is:

a.rx_bytes != b.rx_bytes and a.tx_bytes != b.tx_bytes

It means that interface is considered alive if some bytes were transmitted or received over it since the last check.

OPTIONS

Actions

	-i		Initializes the state file.
	-c		Checks the state of the link (the default).
	-r		Removes the state file for PID
	-h		Displays a help summary.

Modifiers

	-d		Enable debug output.
	-n		Dry-run mode: print everything, do nothing.
	-p		Use parent of PID (grand-parent for -pp, etc.)
	-s SIG		Terminate idle process with signal SIG, instead of the default SIGTERM.

FILES

/proc/net/dev

Network interface statistics.

/var/run/ifalive

Directory where interface state files are stored. Files are named by the corresponding PID.

BUGS

The program is Linux-specific.

SEE ALSO

jumper(8),

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <bug-jumper@gnu.org.ua>.

COPYRIGHT

Copyright © 2017 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

---