nifftmt(7)						 Miscellaneous Information Manual						nifftmt(7)

NAME

       nifftmt - 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
       determines 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.  Speci-
       fies the time period, in seconds, that the traffic monitor thread delays between reads of the interface counters when it suspects there	is
       a  connectivity	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, niffconfig sets this time period to 5 seconds.  This cor-
       responds to the niffconfig -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 t2. By default, niffconfig sets this time period  to  60  seconds.
       This corresponds to the niffconfig -o option.

       The interface continues to be monitored every dt seconds in case it comes back on-line.

       The traffic monitor thread enforces the following restriction between the timing parameters: t2 > t1 + 2dt, and dt < t1

       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
       generate traffic that the suspect interface's receiver will pick up.  Other subscribers may want to take action such as to migrate applica-
       tions 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 structure. 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 interfaces.  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 rela-
       tionship 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 interface, 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 event is posted when the traffic monitor thread declares  an  interface  to  be  dead.
       This  event 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.

   RETURN CODES
       An SIOCTMTADD was attempted on an interface that is already being monitored.  The kernel could not allocate memory to copy  in  the  user's
       buffer.	The relationship between the timing parameters is not correct, or an invalid command was given to the traffic monitor.	An SIOCTM-
       TADD, 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 functions: #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 monitor0, *av);
	   bzero(&mif, sizeof (mif));
	   bcopy(*av, &mif.name[0], MIN(strlen(*av) + 1, sizeof (mif.name - 1)));
	   mif.current_interval = mif.next_time = mif.t1 = t1;
	   mif.t2 = t2;
	   mif.dt = dt;
	   mif.time_to_dead = mif.t2 - mif.t1 + 2 * mif.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 %s0, *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,  t1:  %d,  dt:  %d, t2: %d, time to dead: %d, current_interval:%d, next time: %d0, mif.name,
       state[mif.current_state], mif.t1, mif.dt, mif.t2, mif.time_to_dead, mif.current_interval, mif.next_time);
	   ++av;
	 }
	 av = oldav;

	 /* tell the traffic monitor to stop watching */
	 while (*av) {
	   printf("deleting interface %s from the traffic monitor0, *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("couldn't remove interface");
	   }
	   ++av;
	 }
	 exit(0); }

RELATED INFORMATION

       ioctl(2), EVM(5), niffconfig(8), niffd(8) delim off

																	nifftmt(7)