authorSergey Poznyakoff <>2017-04-07 09:26:57 (GMT)
committer Sergey Poznyakoff <>2017-04-07 09:26:57 (GMT)
commit9c05a5d36ed327460f579e0981a0d8725ffb3e84 (patch) (side-by-side diff)
parent718815e81c186a8f3084ef2d1dd7064212844bfa (diff)
Document ifalive.
* [JMP_PROCNET_COND]: Build extra program only if the condition is true. * (JMP_PROCNET_COND): New condition. * extra/ Distribute and install ifalive.8 * extra/ifalive.8: New manpage.
Diffstat (more/less context) (ignore whitespace changes)
4 files changed, 298 insertions, 3 deletions
diff --git a/ b/
index 9a12017..ec4ebcb 100644
--- a/
+++ b/
@@ -16,7 +16,11 @@
-SUBDIRS=grecs src extra doc
+SUBDIRS=grecs src $(EXTRA_DIR) doc
+ EXTRA_DIR = extra
.PHONY: ChangeLog
diff --git a/ b/
index 1b81d84..409c15e 100644
--- a/
+++ b/
@@ -31,6 +31,7 @@ AC_PROG_CC
# Checks for libraries.
AC_CHECK_LIB(socket, main)
@@ -69,6 +70,8 @@ AC_MSG_RESULT($LOG_FACILITY)
+AM_CONDITIONAL([JMP_PROCNET_COND], [test -f /proc/net/dev])
# Grecs subsystem
GRECS_SETUP([grecs],[tree-api git2chg getopt])
diff --git a/extra/ b/extra/
index f129387..835ed08 100644
--- a/extra/
+++ b/extra/
@@ -6,5 +6,5 @@ ifalive_SOURCES=\
noinst_HEADERS=ifalive.h expr.h
-AM_YFLAGS = -dv
+AM_YFLAGS = -d -v
diff --git a/extra/ifalive.8 b/extra/ifalive.8
new file mode 100644
index 0000000..9563732
--- a/dev/null
+++ b/extra/ifalive.8
@@ -0,0 +1,288 @@
+.\" This file is part of jumper -*- nroff -*-
+.\" Copyright (C) 2017 Sergey Poznyakoff
+.\" Jumper is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\" Jumper is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" GNU General Public License for more details.
+.\" You should have received a copy of the GNU General Public License
+.\" along with jumper. If not, see <>.
+.TH IFALIVE 1 "April 7, 2017" "JUMPER" "Jumper User Reference"
+ifalive \- check network interface activity
+\fBifalive\fR \fB\-i\fR [\fB\-dnp\fR] \fIIFACE\fR [\fIPID\fR]
+\fBifalive\fR [\fB\-c\fR] [\fB\-dn\fR] [\fB\-s\fR \fISIG\fR] \fIPID\fR
+\fBifalive \-r\fR [\fB\-dnp\fR] [\fIPID\fR]
+.B ifalive \-h
+Given the network interface name and the PID of the program that
+controls it, \fBifalive\fR checks if the interface is "\fIalive\fR",
+and if not, terminates the program.
+It is designed as an ancillary utility for
+.BR jumper (8),
+to help automatically shut down inactive interfaces.
+The program runs in three different operation modes, selected by the
+.BR \-i,
+.BR \-c,
+.BR \-r .
+.SS Initialization
+The \fB\-i\fR option requests \fIinitialization mode\fR. In this
+mode, \fIifalive\fR remembers information about the network interface,
+and the PID of the corresponding process that controls it.
+If the \fIPID\fR argument is not given, the program assumes the PID of its
+parent process. The \fB\-p\fR option, if used, instructs the program
+to use PID of the parent process of the originally obtained PID. For
+.B ifalive -i -p tun0 1822
+means that interface \fBtun0\fR is controlled by the parent of PID
+1822, whereas
+.B ifalive -i -p tun0
+means that it is controlled by the grand-parent of \fBifalive\fR
+itself. This option can be used multiple times to move up the process
+ancestor tree. For example,
+.B ifalive -i -ppp tun0 1822
+means use grand-grand-parent of PID 1822.
+The information is stored in a disk file
+\fB/var/run/ifalive/\fIPID\fR. 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
+.BR vpnc (8),
+the following line should appear in the
+.B /etc/vpnc/vpnc-script-post-connect-action
+.B /usr/libexec/ifalive -i -pp $TUNDEV
+.SS Periodic checking
+This is the main (and the default) operation mode. It is requested by
+the \fB\-c\fR option, or by the absence of the mode specifying
+option. The \fIPID\fR argument is required. The tool will first look
+up the interface name corresponding to that \fIPID\fR, and will
+evaluate the expression \fIEXPR\fR to check if the interface is
+active. In the absence of \fIEXPR\fR, the default expression is
+evaluated. See the section
+for the description.
+If the expression evaluates to \fBtrue\fR, the utility will update the
+interface statistics in its spool file, and will exit. Otherwise, it
+will terminate the controlling program by sending the \fBSIGTERM\fR
+signal to \fIPID\fR.
+The check mode is normally run periodically in a \fBHEARTBEAT\fR
+onevent HEARTBEAT {
+ command "/usr/libexec/ifalive -c $pid";
+.SS Cleanup
+The cleanup mode is requested by the \fB\-r\fR command line option.
+In this mode, \fBifalive\fR removes the state file for the given
+\fIPID\fR. The actual PID is computed as described in subsection
+.BR Initialization ,
+This mode should be run when the interface goes down. For example, if
+the interface is controlled by \fBvpnc\fR, the following line should
+appear in the file
+.BR /etc/vpnc/vpnc-script-post-disconnect-action :
+.B /usr/libexec/ifalive -r -pp
+The expression operates on two variables: the previous interface state
+\fBa\fR, and its current state, \fBb\fR. Both variables have a number
+of numeric attributes, which are accessed as \fB\fIX\fB.\fIattr\fR,
+where \fIX\fR stands for the variable and \fIattr\fR for the attribute
+name. The following attributes are defined:
+.B rx_bytes
+Number of bytes received.
+.B rx_packets
+Number of network packets received.
+.B rx_errors
+Number of errors while receiving.
+.B rx_dropped
+Number of dropped incoming (received) packets.
+.B rx_fifo_errors
+Number of FIFO errors on incoming packets.
+.B rx_frame_errors
+Number of received frame errors.
+.B rx_compressed
+Number of received compressed format packets.
+.B rx_multicast
+Number of received multicast packets.
+.B tx_bytes
+Number of bytes transmitted.
+.B tx_packets
+Number of network packets transmitted.
+.B tx_errors
+Number of transmit errors.
+.B tx_dropped
+Number of dropped transmit packets.
+.B tx_fifo_errors
+Number of FIFO errors on transmit.
+.B collisions
+Number of collisions.
+.B tx_carrier_errors
+Number of carrier errors.
+.B tx_compressed
+Number of transmitted compressed format packets.
+The usual arithmetical operations (\fB+\fR, \fB\-\fR,
+\fB*\fR, \fB/\fR) are allowed over these values and integer numeric
+constants. The results can be compared using the operators:
+\fB==\fR (or \fB==\fR), \fB!=\fR, \fB<\fR, \fB<=\fR, \fB>\fR,
+\fB>=\fR. The comparisons can be combined using boolean operations
+\fBor\fR and \fBand\fR. Logical values are negated using \fB!\fR.
+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.
+.ta 8n
+ \fBor\fR
+ \fBand\fR
+ \fB=\fR, \fB==\fR, \fB!=\fR
+ \fB<\fR, \fB<=\fR, \fB>\fR, \fB>=\fR
+ \fB+\fR, \fB\-\fR
+ \fB*\fR, \fB/\fR
+ unary \fB!\fR, unary \fB\-\fR
+Braces can be used to control the precedence.
+The default expression is:
+.B 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.
+.SS Actions
+.B \-i
+Initializes the state file.
+.B \-c
+Checks the state of the link (the default).
+.B \-r
+Removes the state file for \fIPID\fR
+.B \-h
+Displays a help summary.
+.SS Modifiers
+.B \-d
+Enable debug output.
+.B \-n
+Dry-run mode: print everything, do nothing.
+.B \-p
+Use parent of \fIPID\fR (grand-parent for \fB\-pp\fR, etc.)
+\fB\-s\fR \fISIG\fR
+Terminate idle process with signal \fISIG\fR, instead of the default
+.B /proc/net/dev
+Network interface statistics.
+.B /var/run/ifalive
+Directory where interface state files are stored. Files are named by
+the corresponding PID.
+The program is Linux-specific.
+.BR jumper (8),
+Sergey Poznyakoff
+Report bugs to <bug\>.
+Copyright \(co 2017 Sergey Poznyakoff
+License GPLv3+: GNU GPL version 3 or later <>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:

Return to:

Send suggestions and report system problems to the System administrator.