nifftmt(7)nifftmt(7)NAMEnifftmt - Traffic monitoring for the Network Interface Failure Finder
(NIFF)
SYNOPSIS
#include <net/if.h> #include <sys/ioctl.h>
DESCRIPTION
The NIFF traffic monitor thread checks the connectivity of network
interfaces and issues events when it detects a change in an interface's
connectivity. It does this by monitoring the interface's data counters
and using the event management (EVM) framework to inform interested
subscribers of connectivity-related events.
Typically, the traffic monitor looks at a network interface's counters
once every several seconds and issues an event based on what it deter‐
mines from their value.
There are two basic types of events. The first type occurs when an
interface is added to the list of events already being monitored. In
this case, the traffic monitor sends an event to indicate the interface
is up and running. The other type of event occurs when the traffic
monitor does not see any traffic coming into the interface for a period
of time. The traffic monitor thread uses timing parameters to determine
when to issue an event.
Timing Parameters
The timing parameters for the traffic monitor are passed to the NIFF
traffic monitor thread using the ioctl(2) system call and the moni‐
tored_interface structure defined in the <net/if.h> file. See ioctl(2)
for further information.
The following lists the NIFF traffic monitor thread timing parameters:
The name of an interface that is to be monitored. For example, tu0 and
fta0. Specifies the time period, in seconds, that the traffic monitor
thread delays between reads of the interface counters when the network
is running normally. The traffic monitor thread issues a yellow alert
when there is no change in the received byte count for a period of t1
seconds. By default, niffconfig sets this time period to 20 seconds.
This corresponds to the niffconfig -t option. Specifies the time
period, in seconds, that the traffic monitor thread delays between
reads of the interface counters when it suspects there is a connectiv‐
ity problem. This number must be smaller than the number given for the
t1 option. The traffic monitor thread issues an orange alert when
there is no change in the received byte count for t1 plus dt seconds.
If another dt seconds goes by with no change in the received byte
count, the traffic monitor thread issues a red alert. By default, niff‐
config sets this time period to 5 seconds. This corresponds to the nif‐
fconfig -d option. The total number of traffic-free seconds that must
pass before the traffic monitor thread declares the interface to be
dead. After t2 seconds with no change in the interface's received byte
count, the traffic monitor thread issues a dead event. This number must
be equal to at least the sum of t1 and two times dt. By default, niff‐
config sets this time period to 60 seconds. This corresponds to the
niffconfig -o option.
The time_to_dead field (shown in the EXAMPLES section and in niffconfig
-v) is the amount of time that expires between the red alert being
raised and the interface being declared dead. It is calculated by the
traffic monitor thread as t2 - t1 - (2 * dt).
The interface continues to be monitored every dt seconds in case it
comes back on-line.
You can specify the values for t1, dt, and t2 in seconds (if the
MIF_MILLISECONDS bit is clear in the flags field), or in milliseconds
(if the MIF_MILLISECONDS bit is set). See the EXAMPLES section to see
how this is used.
The traffic monitor thread enforces the following restriction between
the timing parameters: t2 > t1 + 2dt dt < t1
t1 >= 0.5 t2 >= 1.1 dt >= 0.2
In the preceding restrictions, the minimum values for t1, dt, and t2
are in seconds.
It is up to the subscribers to take action based on the events that the
traffic monitor reports. For example, the niffd daemon attempts to gen‐
erate traffic that the suspect interface's receiver will pick up. Other
subscribers may want to take action such as to migrate applications to
another node or to activate another network interface to replace the
suspect interface.
The traffic monitor responds to the following ioctl(2) commands:
#include <net/if.h>
mif_t arg; ioctl(fd, command, arg);
As shown in the previous example, mif_t is a monitored interface struc‐
ture. Most commands require the name field of the mif_t structure to be
filled in. The applicable commands are: Adds the named interface to
the list of interfaces being monitored. The timing parameters must be
filled in as noted in the TIMING PARAMETERS section. If this is the
first interface to be added, the SIOCTMTADD command also starts the
thread. Removes the named interface from the list of monitored inter‐
faces. If the last interface in the list of those being monitored is
removed, the thread is stopped. Modifies the timing parameters for the
named interface. The relationship between the timing parameters must be
as noted in the TIMING PARAMETERS section. Returns the number of bytes
required to store a complete status dump of the interfaces currently
being monitored. See SIOCTMTDUMP. This command does not require a third
argument to ioctl. Fills in the mif_t structure for the named inter‐
face, thereby sending its status back to the caller. Fills in the
user-supplied buffer with the status of each interface being monitored.
Used for debugging. Causes the kernel to print the status of each
interface that is currently being monitored.
Events
The traffic monitor posts the following events: This is a notice event.
It is posted when the traffic monitor thread has not seen traffic on an
interface for t1 seconds. This event is also posted every dt seconds
until either traffic is detected or the traffic monitor determines that
the interface is dead. This is an alert event. It is posted when the
traffic monitor thread cannot detect connectivity through a network
interface. The interface is considered dead. This is a notice event.
It is posted when the traffic monitor thread has detected connectivity
through a network interface.
Return Codes
An SIOCTMTADD was attempted on an interface that is already being moni‐
tored. The kernel could not allocate memory to copy in the user's buf‐
fer. The relationship between the timing parameters is not correct, or
an invalid command was given to the traffic monitor. An SIOCTMTADD,
SIOCTMTSTATUS, or SIOCTMTMODIFY command was attempted on an interface
that is not currently being monitored.
EXAMPLES
The following example illustrates the use of a few NIFF ioctl func‐
tions: #include <stdio.h> #include <string.h> #include <sys/types.h>
#include <sys/socket.h> #include <sys/ioctl.h> #include <sys/param.h>
#include <net/if.h> #include <errno.h>
/* these strings map to the "state" enum */ char *state[] = {"INIT",
"GREEN", "YELLOW", "ORANGE", "RED", "DEAD"};
/* usage: niff_example tu0 tu1 tu2...
* must supply the name of at least one
* network interface
*/ main(int ac, char **av) {
int t1 = 20, t2 = 60, dt = 5;
char **oldav;
mif_t mif;
int s;
oldav = ++av;
s = socket(AF_INET, SOCK_DGRAM, 0);
/* tell the traffic monitor to start watching these interfaces */
while (*av) {
printf("Adding interface %s to the traffic monitor\n", *av);
bzero(&mif, sizeof (mif));
bcopy(*av, &mif.name[0], MIN(strlen(*av) + 1, sizeof (mif.name) -
1));
mif.t1 = t1;
mif.t2 = t2;
mif.dt = dt;
mif.flags = 0;
if (ioctl(s, SIOCTMTADD, &mif) < 0) {
perror("couldn't add interface");
break;
}
++av;
}
av = oldav;
/* get the status of the interfaces - NB will probably always
* be in the "init" state
*/
while (*av) {
printf("checking the status of interface %s\n", *av);
bzero(&mif, sizeof (mif));
bcopy(*av, &mif.name[0], MIN(strlen(*av) + 1, sizeof (mif.name) -
1));
if (ioctl(s, SIOCTMTSTATUS, &mif) < 0) {
perror("couldn't get status for interface");
break;
} else {
printf("Interface: %05s, state: %s ", mif.name,
state[miff.current_state]);
if (mif.flags & MIF_MILLISECONDS)
printf("Timer values in milliseconds...\n");
else
printf("Timer values in seconds...\n");
printf("t1: %d, dt: %d, t2: %d, time to dead: %d,
current_interval:%d, next time: %d\n",
mif.t1, mif.dt, mif.t2, mif.time_to_dead, mif.cur‐
rent_interval,
mif.next_time);
}
++av;
}
av = oldav;
/* tell the traffic monitor to stop watching */
while (*av) {
printf("deleting interface %s from the traffic monitor\n", *av);
bzero(&mif, sizeof (mif));
bcopy(*av, &mif.name[0], MIN(strlen(*av) + 1, sizeof (mif.name) -
1));
if (ioctl(s, SIOCTMTREMOVE, &mif) < 0) {
perror("could not remove interface");
}
++av;
}
exit(0); }
SEE ALSO
Routines: ioctl(2)
Files: EVM(5)
Commands: niffconfig(8), niffd(8)nifftmt(7)