.\" =======================================================
.TH IFCHK 1 "Apr 27th, 2019" "ifchk 1.1.1"
.\" =======================================================
.SH NAME
ifchk \(em host based promiscuous mode detection and handling 
.\" =======================================================
.SH SYNOPSIS
.B ifchk [-f config_file] [ -F ] [ -h ] [ -v ]
.\" =======================================================
.SH DESCRIPTION
.B 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.

.B 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.
.\" =======================================================
.SH OPTIONS
.\" -------------------------------------------------------
.TP
.BI \-f " config\_file"
Load the directives in the
.B ifchk
configuration file
.I config_file
on program startup.
.I config_file
must be an absolute pathname. Specifying a relative pathname will
result in program startup failure.
.\" -------------------------------------------------------
.TP
.B \-F
Run
.B ifchk
in the foreground (i.e. do not daemonize).
.\" -------------------------------------------------------
.TP
.B \-h
Print a usage message summarizing the four command line arguments
that are accepted by
.B ifchk.
.\" -------------------------------------------------------
.TP
.B \-v
Print the program revision, host runtime environment data and
information showing the date and time that
.B ifchk
was compiled. Runtime environment data includes the name of the
system on which
.B ifchk
is running, its operating system name, operating system release,
and resident hardware/CPU type.
.\" =======================================================
.SH INTERFACE STATUS AND METRICS REPORTING 
.B ifchk
displays two categories of information pertaining to network
interfaces - interface status and interface metrics.

.\" -------------------------------------------------------
Interface Status
.RS 7
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
.RS
The interface is operating in promiscuous mode and is processing
all traffic regardless of traffic target address.
.RE

.\" -------------------------------------------------------
PROMISC [*]
.RS
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"
.B ifchk
configuration file directive. Please see ifchk.conf(5) for
more information.
.RE

.\" -------------------------------------------------------
normal
.RS
The interface is operating normally and is ignoring all network
traffic not specifically addressed to it or the broadcast
address.
.RE

.\" -------------------------------------------------------
*down*
.RS
The interface is down. The system will not attempt to transmit
data over an interface in this state.
.RE
.RE

.\" -------------------------------------------------------
Interface Metrics
.RS 7
For each interface in an interface metrics report, show its name/
unit number paring (e.g., eth0), index, and input and output packet
counts.
.\" =======================================================
.SH INTERFACE STATUS EXAMPLE OUTPUT
interfaces: 6
 bond0: normal
  em1: normal
  em2: normal
  em3: PROMISC [*]
  em4: *down*
   lo: normal

Interface status output on a host with six network interfaces. Interface 
em3 was running in promiscuous mode and was therefore disabled.
.\" =======================================================
.SH INTERFACE METRICS EXAMPLE OUTPUT
***   Network Interface Metrics   ***
.nf
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
.fi

Interface metrics output on a host with six network interfaces.
.\" =======================================================
.SH ROUTINE OPERATION
.B 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:
.\" -------------------------------------------------------
.TP
\-
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
.B ifchk
using the Unix/Linux kill(1) command (e.g., kill -SIGUSR1 <ifchk_pid>).
.\" -------------------------------------------------------
.TP
\-
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
.B ifchk
configuration file directives that govern this functionality.
Please see ifchk.conf(5) for more information.
.\" =======================================================
.SH PROGRAM OUTPUT AND EVENT LOGGING
There exist differences in how
.B ifchk
outputs program and event logging data. These differences depend on whether
.B ifchk
was invoked as a foreground process or as a daemon process.

.\" -------------------------------------------------------
Foreground Invocation
.RS 7
Program startup via a command shell connects
.B ifchk
standard output and standard error streams to the invoking terminal
device (e.g., /dev/pts/0).

Starting
.B 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).
.B ifchk
logs at facility LOG_USER and at priorities LOG_CRIT, LOG_WARNING,
LOG_NOTICE, and LOG_INFO.
.RE

.\" -------------------------------------------------------
Daemon Invocation
.RS 7
Program startup via a command shell or at system boot (typically by way
of a run control script) connects
.B 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
.B 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
.B ifchk
daemon process logs at the same facilities and priorities as when
started as a foreground process.
.RE
.\" =======================================================
.SH NOTES
.\" -------------------------------------------------------
Under Linux kernel version 2.6, it is required that the host kernel be
compiled with support for the sysfs(2) subsystem. Please consult the
.B ifchk
INSTALL file for more information.
.\" =======================================================
.SH SEE ALSO
ifchk.conf(5), ifconfig(8), syslogd(8), kill(1), sysfs(2)
.\" =======================================================
.SH AVAILABILITY
The latest revision of the
.B ifchk
distribution can be found at http://www.noorg.org/ifchk/
.\" =======================================================
.SH AUTHOR
Joshua Birnbaum <engineer@noorg.org>
.\" =======================================================
.SH COPYRIGHT
.nf
Copyright (C) 2002-2019 Joshua Birnbaum
All Rights Reserved.
.fi
.\" =======================================================
