$Id: README,v 1.5 1998/02/14 17:40:56 hans Rel $

  README for acctsum 1.1


    Copyright

Acctsum is public domain. This means in particular that it comes without any
warranty.

    What Is It?

The acctsum package consists mainly of a shell script that evaluates
your accounting file and summarizes the information in it by days,
weekdays, months, and years. It can mail its results to the system
administrator and/or produce a HTML index page. It is intended to be run
by cron once per day.

There's a second shell script that reports your ISDN usage and truncates
the ISDN log file. It is intended to be run by cron once per month.

    Is it Y2K ready?

I believe that it is, if your OS is. It uses only 4 digit years. However,
there is no warranty.

    Features

* Keeps your accounting file small. The accounting file is truncated
  after it is evaluated.

* Summarizes processes and their CPU usage by day, day of week, month,
  and year.

* Sorts the summary by programs and by users.

* Can mail the summary to the system administrator.

* Can create a HTML index page for the summaries.

* Nice (ahem...) HTMLized output of the summaries with several sorting options.

* Very configurable.

* Calculates ISDN fees (via isdnrep).

    Deficiencies

* Nothing prevents two copies of the scripts running simultanously,
  screwing up the results. But this will never happen if you're careful.

* On Linux 2.1.x apparently the format of the accounting record has been
  extended considerably. To use it you must enable BSD accounting in the
  kernel configuration and recompile the accounting tools. By switching
  to Linux 2.1 or newer your old summaries (if you have any) become useless.
  I have no workaround for this.

* No graphical output yet. But I'm looking into xvgr and gnuplot for this.

    Sample Output

The following is a shortened sample of the mail that is sent to the
administrator (it looks the same in a WWW browser). It contains the number
of calls, the total real time (actually the real time less the CPU time,
I guess), and the total CPU time per program and per user. The format
of the columns is explained in the GNU accounting utilities documentation.
The first row is the sum of all remaining rows.

    Program Summary

   Calls Real [min]  CPU [min]   Program
----------------------------------------
   30775  140943.69     223.96
    1070       1.30     103.46   cc1
     ...        ...        ...   ...
       1       0.00       0.00   slist*
       1       0.00       0.00   pqlist*

    User summary

User    Processes Real [min]  CPU [min]
---------------------------------------
            30775  140943.69     223.96
root        29104  140934.89     220.50
news         1359       0.26       2.08
hans          267       6.78       1.33
cvsadmin       43       1.75       0.03
uucp            2       0.01       0.01

    Prerequisites

You need to have accounting in the kernel enabled. In the 2.1, 2.2 and newer
kernels this means you must select the "BSD accounting" config option.

You also need the GNU Accounting Utilities (beta release 6.3 or newer) to
enable accounting (normally done during system startup) and to produce the
reports.

If you have a very old kernel version (earlier than 2.0.0) you also need the
accounting tools (acct-1.3.73.tar.gz) and probably apply the included kernel
patch. This is untested, however.

To use account.isdn, you need the isdn4linux package and the isdnlog
package.

acct-1.3.73.tar.gz is available from metalab.unc.edu or its mirrors
in directory /pub/linux/system/Admin/accounts.

The GNU Accounting Utilities (acct_6.3) are available from prep.ai.mit.edu
or its mirrors in directory /pub/gnu. This version fixes at least one serious
bug of version 6.2.

(Apologies to users of acctsum 0.1: The Accounting utilities 6.2 were not
available from prep.ai.mit.edu at that time. But version 6.3 is.)

The ISDN stuff is available from ftp.franken.de.

    Installation

See the file INSTALL for installation instructions.

    Usage

    account.daily

usage		account.daily [-acctfile file] [-mail] [-html]
				[-htmldir dir] [-statDir dir] [-date date]
options
	-acctfile file	Use alternate accounting file
	-mail		Send mail to the admin
	-html		Generate HTML output in default directory
			/home/htdocs/acct
	-htmldir dir	Generate HTML output in directory dir
	-statDir dir	Generate stats in directory dir
	-date date	Use date as the current date (if the 'date' program
			is broken or you want to debug the script)

    account.isdn

usage		account.isdn [-logfile file] [-html] [-htmldir dir]
options
	-logfile file	Takes 'file' as the log file to summarize
	-html		After creating the summary, a HTML index page
			(index.html) is produced in the standard location
			/home/htdocs/isdn
	-htmldir dir	After creating the summary, a HTML index page
			(index.html) is produced in the given location

    Contributions

Any ideas, suggestions, bugfixes, icons and other artwork are more than
welcome.

    Things To Do

See the file TODO for possible enhancements.

    Author

Hans-Joachim Baader (baader@gmx.net)
