------------------------------------------------------------------------------
IPAcct - a program to do per user ip accounting
------------------------------------------------------------------------------

WHAT IS IT?

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 accouting
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 accouting 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.

	- 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. 

	- 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
intervall 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
ipacct 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 a recorded with a weight/cost of zero in the kernel. There's a program
included which is used to create a low-rate/high-rate system (much like the
phone system), using ipacct's feature of a weight table. Thanks to Carlos
Soares <cs@uninova.pt> for this program.

INSTALLATION

	1. Take a look at the file MCONFIG in the source directory
	   where you unpacked ipacct. Normally you shouldn't have to
	   change anything. If you don't have a directory /var/log change
	   the reference in MCONFIG to something else, e.g. /var/adm, but
	   please consider reading the FSSTND v1.2 document where a
	   standard Linux filesystem is described. Maybe you have to change
	   the value of NOBODY, but only if the binaries are to be used in
	   a system with different UID for user nobody.
	
		more MCONFIG
		(vi/joe/emacs MCONFIG)
	
	2. Do a make patches under the ipacct source directory. This
	   creates the kernel patches with the changes you made in
	   MCONFIG.
	
		make patches
	
	3. Go into the patches directory and choose a suitable patch for
	   your kernel. There are some old patches under patches/OLD which
	   should work with older kernels, but I don't recommend using them.
	   Instead upgrade to a 2.0.x version of the kernel. If Linus really
	   means that 2.0 is a stable version, this patch should work with 
	   very minor changes to all the 2.0 series.
	
	4. Now change your directory to the Linux kernel source tree you
	   want to patch for the use with ipacct and apply the patch. Read
	   the patch man page, if you don't know what the options mean.
	
		cd /usr/src/linux
		patch -p0 -s <patch.linux-2.0.21
	
	5. You can recompile your kernel, now. But don't forget to activate
           the ipacct kernel extensions by answering yes to the "Per user IP
           accouting" question while doing the make config.  Make sure that
           your links under /usr/include are right and that they point to
           the kernel tree you patched for the use with ipacct. Normally
           this is a link from /usr/include/linux and /usr/include/asm to
           /usr/src/linux/include/linux and /usr/src/linux/include/asm
           respectively.
	
		make config
		make dep
		make clean
		make zImage (or make zlilo, or whatever you use usually)

	   If you use modules you will also:

		make modules
		make modules_install
	
	6. Do a make under the ipacct source directory. 
	
		make
	
	7. Do a make install and a make install.man, too. This will
	   install the programs and man pages in the places you specified
	   in MCONFIG.
	
		make install
		make install.man
	
	8. If you want to run ipquota on your system you have to
	   install a line in your rc.local or any other suitable
	   rc file, that starts ipacctd and ipquota at boot time.
	
		---8<----------------------------------------------------
		  echo Starting ipacctd with ipquota...
		  /usr/sbin/ipacctd /usr/sbin/ipquota
		---8<----------------------------------------------------
	
	9. Now you can add user to the accounting file with the ipadd
	   command.
	
		/usr/sbin/ipadd username 1024000
	
	   Or display the ip quota of a user.
	
		/usr/bin/sayip username
	
	   See the man pages for more information.
	
	10. You should have a running ipacct system, now. If you encountered
	    any problems please report them to me and I'll try to solve them
	    and answer your questions. I may be reached under 
	    lf@elemental.net. But please be patient as my time is very
	    limited.

THANKS

	Special thanks go to.. (yeah, it's a little bit short, I know :)

		Joao Ventura <jcv@students.si.fct.unl.pt>

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 Joao Ventura and
	are also under the GNU GPL.
	See file COPYING for details.
