IFCHK(1)

NAME
ifchk — host based promiscuous mode detection and handling

SYNOPSIS
ifchk [-f config_file] [ -F ] [ -h ] [ -v ]

DESCRIPTION
ifchk scans host network interfaces to see if any of them are running in promiscuous mode. This is the case if a given configured network interface is receiving copies of all packets traversing the network medium as opposed to just those that are specifically addressed to it. ifchk will also display metrics describing network traffic flow across all configured interfaces. This information is provided with a view towards allowing users to recognize changes in interface traffic volume (e.g., spikes) that are inconsistent with established traffic trends.

OPTIONS

-f config_file
    Load the directives in the ifchk configuration file config_file on program startup. config_file must be an absolute pathname. Specifying a relative pathname will result in program startup failure.

-F  Run ifchk in the foreground (i.e. do not daemonize).

-h  Print a usage message summarizing the four command line arguments that are accepted by ifchk.

-v  Print the program revision, host runtime environment data and information showing the date and time that ifchk was compiled. Runtime environment data includes the name of the system on which ifchk is running, its operating system name, operating system release, and resident hardware/CPU type.

INTERFACE STATUS AND METRICS REPORTING
ifchk displays two categories of information pertaining to network interfaces - interface status and interface metrics. As of ifchk release 1.1.2, status output also enumerates upon any physical interfaces that comprise a channel bonding interface. Interface Status
    For each interface in an interface status report, a name/unit number pairing (e.g., eth0) and corresponding state is shown. An interface can be in one of four different states, each of which are enumerated as follows: PROMISC
        The interface is operating in promiscuous mode and is processing all traffic regardless of traffic target address.
    PROMISC [*]
        Identical to PROMISC above, with the addition of disabling the promiscuous interface. This has the same effect as marking the interface "down" using ifconfig(8) and requires superuser privileges. Data transfer over this interface will not be possible until it is marked "up" using ifconfig(8). The disabling of promiscuous interfaces is governed by the "disableOnPromisc" ifchk configuration file directive. Please see ifchk.conf(5) for more information.
    normal
        The interface is operating normally and is ignoring all network traffic not specifically addressed to it or the broadcast address.
    *down*
        The interface is down. The system will not attempt to transmit data over an interface in this state.
Channel Bonding
    For a channel-bonded interface, show its composite physical interfaces (slave), in addition to the currently active slave (actv).
Interface Metrics
    For each interface in an interface metrics report, show its name/ unit number paring (e.g., eth0), index, and input and output packet counts.

INTERFACE STATUS EXAMPLE OUTPUT
interfaces: 6
 bond0: normal <slave: em1 em2, actv: em1>
  em1: normal
  em2: normal
  em3: PROMISC [*]
  em4: *down*
   lo: normal Interface status output on a host with six network interfaces. em1 and em2 comprise channel bonding interface, bond0. em3 was running in promiscuous mode and was therefore disabled.

INTERFACE METRICS EXAMPLE OUTPUT
*** Network Interface Metrics ***
Name    Index   RX-OK           TX-OK
bond0   6       1720522         2356005
em1     2       1714144         2356005
em2     3       6377            0
em3     4       9183302         6703810
em4     5       0               0
lo      1       768742          768742
Interface metrics output on a host with six network interfaces.

ROUTINE OPERATION
ifchk performs its scanning and display actions during program startup and at user defined intervals thereafter. It does so by way of the following facilities:

-   Two POSIX signal handlers installed for the receipt of SIGUSR1 and SIGUSR2. Reception of the former results in the performing of an interface status scan. Reception of the latter results in the regeneration of interface metrics output. SIGUSR1 and SIGUSR2 can be sent to ifchk using the Unix/Linux kill(1) command (e.g., kill -SIGUSR1 <ifchk_pid>).

-   Two POSIX interval timers that count down a user defined number of seconds before triggering subsequent interface status scans and the regeneration of interface metrics output. "ifStatusDumpFreq" and "ifMetricDumpFreq" are, respectively, the two ifchk configuration file directives that govern this functionality. Please see ifchk.conf(5) for more information.

PROGRAM OUTPUT AND EVENT LOGGING
There exist differences in how ifchk outputs program and event logging data. These differences depend on whether ifchk was invoked as a foreground process or as a daemon process. Foreground Invocation
    Program startup via a command shell connects ifchk standard output and standard error streams to the invoking terminal device (e.g., /dev/pts/0). Starting ifchk at system boot (typically by way of a run control script) connects standard output and standard error to /dev/console, the system console device. The system operator may choose to redirect this output. Program and error output is also sent to syslogd(8). ifchk logs at facility LOG_USER and at priorities LOG_CRIT, LOG_WARNING, LOG_NOTICE, and LOG_INFO.
Daemon Invocation
    Program startup via a command shell or at system boot (typically by way of a run control script) connects ifchk standard output to /dev/null, the null device. Standard error is connected to an error log file, the pathname of which is governed by the ifchk "errLog" configuration file directive. Please see ifchk.conf(5) for more information. Program output is sent to syslogd(8). Error output is sent to the error log described above and possibly to syslogd(8), depending on syslogd(8) configuration. The ifchk daemon process logs at the same facilities and priorities as when started as a foreground process.

SEE ALSO
ifchk.conf(5), ifconfig(8), syslogd(8), kill(1), sysfs(2)

AVAILABILITY
The latest revision of the ifchk distribution can be found at http://www.noorg.org/ifchk/

AUTHOR
Joshua Birnbaum <engineer@noorg.org>

COPYRIGHT
Copyright (C) 2002-2020 Joshua Birnbaum
All Rights Reserved.