/*******************************************************************
 * INSTALL file for ifchk.                                         *
 *                                                                 *
 * Copyright (C) 2002 - 2004 Joshua Birnbaum <engineer@noorg.org>. *
 * All Rights Reserved.                                            *
 *******************************************************************/


Please read the NOTES section below prior to compilation.


Building ifchk.
--------------

Building ifchk should be straightforward on most systems.

% cd <ifchk dist directory>
% make ifchk
% mv ifchk /to/somewhere/suitable/in/your/$PATH
% mv docs/ifchk.1 /to/somewhere/suitable/in/your/$MANPATH

To clean out the ifchk build directory.

% cd <ifchk dist directory>
% make clean


NOTES.
-----

* ifchk compilation requires an ANSI C compiler.
  Makefile assumes the use of gcc. If you are building with another
  C compiler implementation (e.g., pgcc), reset CC in Makefile to
  the name used to invoke it and check that it supports the -g flag.
  Manual compilation is also an option.

* IOVBUFSZ in linux.h (line 68) sets the size of the buffer that holds
  the list of configured interfaces present on the system as returned
  by the kernel.
  If IOVBUFSZ is too small, ifchk will fail to complete and will exit
  with status 1. Program failure is indicated by the output of the
  following message:

  ifchk: ERROR: constant IOVBUFSZ (linux.h:68:) too small

  If this occurs, reset the IOVBUFSZ value using the following formula:

  (256 * num_interfaces) + 1

  where num_interfaces is the total number of interfaces present on
  the system as reported under the 'Name' column by netstat -in.
  However, the default size of 8192 bytes should suffice for most
  systems.

* ifchk makes extensive use of netlink(7) sockets and the rtnetlink(7)
  routing socket subsystem to perform interface specific tasks.
  It is therefore required that the host kernel under which ifchk is
  running be compiled to support these two facilities. Their absence
  will result in program failure.

  To support ifchk operation, older kernels (e.g., 2.2.x) must be
  built with the following netlink options enabled:

  CONFIG_NETLINK
  CONFIG_RTNETLINK
  CONFIG_NETLINK_DEV

  Assuming the use of `make menuconfig`, you may access these options
  prior to kernel compilation via the following command sequence:

  LINUX 1# cd <linux kernel source dist directory>
  LINUX 2# make mrproper
  LINUX 3# make menuconfig
  
  Select "Networking options  --->" within the menuconfig environment.

  Enable the following networking options:

  x x [*] Kernel/User netlink socket				x x
  x x [*] Routing messages (NEW)				x x
  x x <*> Netlink device emulation (NEW)			x x

  (These options correspond to the three CONFIG_* options above.)

  The kernel .config file generated via the above menuconfig session
  should show that these options were enabled:

  CONFIG_NETLINK=y
  CONFIG_RTNETLINK=y
  CONFIG_NETLINK_DEV=y

  Continue with the kernel compilation procedure.

  A good guide to building custom Linux kernels may be found at:

  http://www.tldp.org/LDP/lame/LAME/linux-admin-made-easy/kernel-custom.html

  Newer kernels (e.g., 2.4.27) only provide the CONFIG_NETLINK_DEV
  option. CONFIG_NETLINK and CONFIG_RTNETLINK are absent as their
  functionality is now compiled into the kernel by default.

* ifchk was written, debugged and tested under several kernel revisions.
  They include linux-2.2.20, linux-2.4.23, linux-2.4.24, linux-2.4.25,
  linux-2.4.26 and linux-2.4.27. Except for 2.2.20, all other kernels
  were built from sources retrieved from www.kernel.org.
  Testing under Linux 2.3, 2.5 and 2.6 is still outstanding.
  
  Please mail me at engineer@noorg.org if you have access to a system
  running a Linux 2.3, 2.5 or 2.6 kernel and would like to participate
  in testing or if you can confirm building and running ifchk under
  Linux 2.3, 2.5 or 2.6


REPORTING BUGS.
--------------

* When reporting bugs or problems related to ifchk, please include
  uname -a, dmesg and C compiler revision output. Please also include
  the version of ifchk in question. This information can be sent to
  me at engineer@noorg.org as can comments and suggestions.


Enjoy.

-Josh Birnbaum <engineer@noorg.org>.
