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

README for acctsum 1.0
======================


Copyright
=========

Acctsum is public domain.

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.

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.

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

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

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

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

acct-1.3.73.tar.gz is available from sunsite.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
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 a 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

Things To Do
============

See the file TODO for possible enhancements.

Author
======

Hans-Joachim Baader (hans@grumbeer.inka.de)

