/* $Id: README,v 1.9 2000/09/01 16:52:00 slay Exp $ */

                           UserIPacct 0.9b Page

              UserIPacct - a program to do per user ip accounting

Primary site:		http://rsmeyers.3ti.org/useripacct
Current Maintainer:	Ramses Smeyers (rsmeyers@khk.org)


   UserIPacct introduces a new policy mechanism that provides per user
   IP statistics, that is, it just provides the user's IP usage. A user
   must be allowed to have IP, and a program is provided to control
   access to the IP level.

   This package adds per user ip accounting to the kernel and contains
   programs to control and use this accounting data.

   Fist of all it consists of a kernel patch which adds per user ip
   accounting to the kernel. The kernel patch accounts all bytes sent or
   received on the ip level, i.e. all headers get accounted including the
   ip header itself. This data is exported via the proc filesystem.
   Moreover the patch allows to control the ip access on a per user
   basis. Furthermore it is possible to specify a weight for ip
   addresses. This weight controls how much every byte costs that is
   transfered from or to this ip addresses. With this weight/cost set to
   zero you can ignore certain host or networks completely from the
   statistics which might be convenient for the local network. The cost
   can be different for different ip addresses.

   Second, there's a program for controlling and viewing the
   weights/costs and the accounting data produced by the kernel. With it
   you can modify the weight table in a manner very similar to the syntax
   of the route program.

   Please note the following, UserIPacct is unable to correctly account
   PPP users, because these use the PPP daemon as a gateway. The packets
   in a PPP connection are being accounted to the PPP daemon UID. In order
   to correctly account these packets, it would be necessary to alter the
   PPP daemon.
   If you want to account PPP, take a look at net-acct-0.4.tar.gz. This
   tool allows you to account the traffic on SLIP/PPP connections, but
   not on Ethernet connections. You won't be able to deny access, though.


   Example Output (Screenshots :) )

  (outdated) example output of ipacct

        User       Sent       Received     Flags
        root       401364     401421
        news       2143       2210
        lf         221462     348287
        joe        1036475    2793743      N
        guest      65432734   43462382     N
        nobody     34323      23791

   In this example you see how much traffic every user produced since the
   last reset of the statistics. You can also see that further net access
   is denied of joe and for guest.

  (outdated) example output of a weight table (ipacct -w)

        Addr            Mask            Weight
        192.0.2.24      255.255.255.255 1
        192.0.2.0       255.255.255.0   0
        default         *               1

   This weight table says that access to the host 192.0.2.24 is accounted
   with a costs of one per byte. Access to all other hosts of the net
   192.0.2.0 is ignored (weight/cost 0). And access to all other hosts on
   the internet is accounted with a costs of one.

   Third, a program named ipacctd creates an interface to your own
   accounting program. It reads the kernel ip statistics every specified
   interval and passes to data to a user supplied program like ipquota
   (see below). But you can also impose your own ip accounting policy by
   writing your own program or shell script for recording and analyzing
   the produced data.

   And fourth, there is ipquota which is a package of itself. If used
   with ipacctd it can impose ip quotas on certain users. These quotas
   can be easily changed and viewed. Furthermore ipquota uses the feature
   of the useripacct kernel patch to control access to the net: if a user
   exceeds his quota he is denied further net access excluding access to
   hosts and networks which are recorded with a weight/cost of zero in
   the kernel. Thanks to Erik Cumps, ipquota now handles soft quota as
   well. 

   UserIPacct 0.9 introduces a major rewrite of ipquota. Erik Cumps
   created MIDBS, the Modular IPquota Database Backend System. The purpose
   of MIDBS is to separate the database handling code in its own layer,
   allowing an opaque interface to the IPquota info in the database. One
   of the advantages of MIDBS is that it is now possible to support
   different database systems by writing a plugin library. More
   information can be found in the documentation at ipquota/midbs/doc/.

   Of course, the flatfile text database used by previous versions of
   userIPacct is supported by the "classic" MIDBS module. Additionaly, a
   MySQL database backend module has been implemented.

   There's a program included which is used to create a low-rate/high-rate 
   system (much like the phone system), using useripacct's feature of a
   weight table. Thanks to Carlos Soares for this program.

   There's also a program which generates a mrtg.cfg for generating mrtg 
   graphs of the users ip usage.

   There is also an alternative to ipquota, called ipstats which provides
   accounting capabilities, but does not impose a quota, generating only
   IP traffic statistics. MIDBS is currently not supported by IPstats.
 

   Copyright

   This package is Copyright (C) 1994, 1995, 1996 Lars Fenneberg. It is
   distributed according to the GNU General Public License. Some small
   parts are Copyright (C) 1995,1996,1999 Joao Ventura and are also under
   the GNU GPL. Some small parts are Copyright (C) 1999,2000 Ramses Smeyers
   and are also under the GNU GPL. Some parts are Copyright (C) 2000 Erik
   Cumps and are, of course, also under the GNU GPL.