Provided by: wipl-daemon_20020601-11.3_i386 bug

NAME

       wipld - Daemon program to collect statistics.

SYNOPSIS

       wipld [ -b ] [ -c configfile ]

DESCRIPTION

       This  program  creates  a  shared  memory  area  which contains a table
       indexed by MAC or IP addresses. Each index  in  the  table  contains  a
       number of counters.

OPTIONS

       -b --debug
              Do  not  fork  into  the background and print output both to the
              logfile and to stdout.

       -c file --config file
              Use the specified configuration file instead of the default.

THE CONFIGURATION FILE

       The configuration file should  contain  different  sections  which  are
       described below.

COUNTERS SECTION

       In the [counters] section of the configuration file you simply list the
       names of the counters you want to maintain for each IP or MAC  address,
       one pr. line. For example:

              [counters]
              Send
              Recv

       This  will  declare  the  two  counters  Send and Recv an give them the
       counter numbers 0 and 1 respectively.

OPTIONS SECTION

       In the [options] section of the configuration  file  several  different
       options can be stated in the format:

       option: value

       The valid options are:

       addrmode
              The  value  for  this  option  should  either be mac or ip.  The
              option indicates if the daemon should run in  MAC  or  IP  based
              addressing  mode. That is, if the table maintained by the daemon
              should be indexed by MAC or IP address.

       user
              Tells the wipld daemon to drop superuser privileges  and  become
              the specified user as soon as the interface is opened. value can
              be both a username or a numerical uid.

       group
              Tells the wipld daemon to drop superuser privileges  and  become
              part  of the specified group as soon as the interface is opened.
              value can be both a group name or a numerical gid.

       logfile
              This sets the name of the logfile. The file is reopened when the
              daemon  receives a HUP signal. If the file does not exists it is
              created with the permission of the daemon as  specified  by  the
              user and group options.

       logaddrchange
              If  this  is  set to a non-zero value an entry is written to the
              logfile every time an IP/MAC address is changed for an entry  in
              the table.

       logbadpackets
              If  this is set to a non-zero value it is logged when an invalid
              IP packet is seen.

       logtablefull
              If this is set to a non-zero value it is logged when  the  least
              recently  lookuped entry is deleted from the table maintained by
              the daemon as described in the maxentries option.

       promiscmode
              If this is set to 0  the  network  interface  is  not  put  into
              promiscuous mode.

       maxentries
              The  maximal  number  of  entries in the table maintained by the
              daemon.  If more entries are tried created  the  least  recently
              lookuped entry will be erased. This number is needed because the
              shared memory area maintained by the daemon has a fixed size.

       netdev
              The network device to get packages from. If this option  is  not
              present the daemon will try to find an appropriate device.

       filter
              This  is  an  expression  that  will determine which packets the
              daemon will see. The expression should have a format as given to
              the  popular  tcpdump(8)  program.  The filter has two purposes:
              First, you can use it to prevent the program  in  the  [program]
              section  from  seeing  some  packages.  Second,  you might get a
              significant performance increase if you filter away the  packets
              you are ignoring.

       pidfile
              To this the process id of the daemon will be written.

       proxymaxcon
              If  this  value  is  non-zero  then  proxy  remapping support is
              enabled.  Proxy remapping support makes it possible for a  proxy
              server  to  inform  wipld  by  on  behalf  of  which machines it
              transfers  packages.  And  wipld  will  then  account   packages
              transferred   by  the  proxy  server  to  the  machine  actually
              requesting the information.

              The value should be set to  the  maximal  number  of  concurrent
              connections  the proxy server can make. A typical value is 2048.

       daemonfile
              This file is used as the communication point between the  daemon
              and  it’s  clients.  It  is  possible  to  have multiple daemons
              running at the same time if they use different daemon files. The
              specified file must exists.

PROGRAM SECTION

       In  the  [program]  section  you  must  specify  a  program in the wipl
       programming  language.   For  a  description  of  this   language   see
       wipllang(5).   The  program  you  specify  will be executed for each IP
       packet seen by the daemon.

       Some examples on programs will be given now. These examples all  assume
       that  you  run  the  daemon  in  MAC  based addressing mode. If you are
       running it in IP based addressing mode change srcmac[0] to srcip[0] and
       dstmac[1] to dstip[1].

       If  you  want  to collect simple statistics about the IP traffic on the
       LAN segment you are connected to, you can  use  the  following  program
       together with the counter definitions from the top of this manual page:

              [program]
              srcmac[0]+=size;
              dstmac[1]+=size;

       This means that for each packet the Send counter (counter 0) associated
       with the source MAC address of the packet is incremented by the size of
       the packet. Similarly the Recv counter (counter 1) associated with  the
       destination MAC address is incremented.

       For a more advanced situation suppose you want to make statistics about
       what is transfered through a router. Also suppose that the  router  has
       the MAC address 11:22:33:44:55:66 and the IP address 1.2.3.4.  Then you
       can use the following program:

              [program]
              if(dstmac==11:22:33:44:55:66 && dstip!=1.2.3.4)
                srcmac[0]+=size;
              else if(srcmac==11:22:33:44:55:66 && srcip!=1.2.3.4)
                dstmac[1]+=size;

       The following program will only account traffic that goes from internal
       to  external hosts and from external to internal hosts (traffic between
       internal hosts is ignored).  It will also account the traffic for whole
       network  (it should be easy to extend this example to account different
       internal networks):

              [program]
              bool s = (srcip/24 == 192.168.1.0);
              bool d = (dstip/24 == 192.168.1.0);
              if (s && !d) {
                srcip[0]+=size;
                (srcip/24)[0]+=size;
              } else if (d && !s) {
                dstip[1]+=size;
                (dstip/24)[1]+=size;
              }

       This code assumes your network has no  host  with  the  192.168.1.0  IP
       address,  in  that  case the program will account the traffic two times
       for that host.

       Final note: If you declare a variable without assigning a value to  it,
       like in:

              int a;

       The variable is initialized to 0 AND it will preserve its value between
       each execution of the program.

PERMISSIONS

       The shared memory area is created with the user and group of the daemon
       process  as  specifed  by  the  user  and group options. Read and write
       permission of the area is always given to the user  to  allow  the  the
       daemon to access the area. Read and write permissions for the group and
       for others are set to the same permissions as the persmissions  of  the
       daemonfile. A user which has read but not write permission cannot write
       to the shared memory area but can lock it  infinitly  prevening  others
       from accessing it.

DEBUGGING

       The tcpdump and the wipld program both use the pcap library to read the
       raw packets from the network card and to interpret the  filter  string.
       So  when you don’t get the statistics you think you should it is a good
       idea to try to run tcpdump to  check  if  the  wipld  daemon  sees  the
       packets  you  think it does. Also you probably want to run tcpdump with
       the -n option to prevent DNS lookups from blocking the program.

FILES

       /etc/rc.d/init.d/wipld
              Usually the daemon is started and stopped by this script.

       /etc/wipld.conf
              Default configuration- and daemonfile.

       /var/log/wipld
              Default logfile

       /var/run/wipld.pid
              Default pidfile

SEE ALSO

       wipl(1), wipllang(5), tcpdump(8), pcap(3)

                                  August 2000                         wipld(8)