------------------------------- Page    i -------------------------------

                        The UTS Accounting System

------------------------------- Page   ii -------------------------------

                            TABLE OF CONTENTS


1.    Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .   1

2.    Gathering the Data  . . . . . . . . . . . . . . . . . . . . . .   1

2.1      Starting Up Accounting . . . . . . . . . . . . . . . . . . .   1
2.2      Switching Files  . . . . . . . . . . . . . . . . . . . . . .   3
2.3      Kernel Accounting  . . . . . . . . . . . . . . . . . . . . .   3
2.4      Unit Record Accounting . . . . . . . . . . . . . . . . . . .   3
2.5      Connect Time Accounting  . . . . . . . . . . . . . . . . . .   4

3.    Summarizing the Data  . . . . . . . . . . . . . . . . . . . . .   5

3.1      General Function Description . . . . . . . . . . . . . . . .   5
3.2      Error Detection  . . . . . . . . . . . . . . . . . . . . . .   5
3.3      Daily File Format  . . . . . . . . . . . . . . . . . . . . .   6

4.    Getting Reports . . . . . . . . . . . . . . . . . . . . . . . .   7

5.    General Maintenance . . . . . . . . . . . . . . . . . . . . . .   8

6.    Reference Material  . . . . . . . . . . . . . . . . . . . . . .   8


                                                            Last Page   8

-------------------------------- Page  1 --------------------------------

1.    INTRODUCTION

This document describes the  implementation of an  Accounting System  for
the UTS operating system.  With this system it is possible to account for
individual and  department usage  of  UTS on  a percentage  basis.   This
information can  be  obtained  both  interactively and  in  the  form  of
reports.

The usage of commands  is also  continually tracked.  It  is thus  fairly
simple to obtain information such as "what are the most heavily used com-
mands?" and "which commands use the most  cpu?".  It is also possible  to
determine if these commands are i/o or cpu bound.

The actual accounting process is  quite simple (see  Figure 1).  The  UTS
Kernel and  several user  programs write  accounting records  to a  file.
Several times each  day the  acctpk process runs  which summarizes  these
records into another  file containing  all the information  for a  single
day.  The ac and au programs can be used to interrogate these daily files
to obtain usage information.




2.    GATHERING THE DATA

The file to receive the accounting records is named:

        /usr/spool/adm/acctx
or      /usr/spool/adm/accty

The file /etc/acctfile contains one of these names, depending on which is
the current accounting file.


2.1      STARTING UP ACCOUNTING

The accounting process is started up each time UTS is IPL-ed by the  com-
mand /etc/accton which is in the /etc/rc file.  The accton  program looks
in /etc/acctfile to see what the  current accounting file name is,  veri-
fies that it is a valid name, and issues the  acct system call to startup
accounting.

If an error is detected in the accounting file name, an appropriate  mes-
sage is written  to the operator console,  and mail is  sent to user  adm
stating the problem.  The program attempts to figure out which of the two
accounting files was  most recently  updated, and that  file is used  for
accounting.  Thus the  accounting process  should always  start, even  if
/etc/acctfile gets stomped on.

-------------------------------- Page  2 --------------------------------

           IPL the                                     UTS
           system                                      user




           /etc/rc       crontab              "au"              "ac"
                                             program          program




           "accton"    /etc/cron     per-user    daily file     command
           program                   reports      (YYDDD)        usage
                                                                reports




            "acct"           "acctsw"                "acctpk"
            system           program                 program
             call



                             acctfile



      UTS        login        opr                  acctx           accty
      Kernel     init       vmpunch
                            vmread




                "acctwrt"
                 system
                  call



                   Figure 1.    The Accounting Process

-------------------------------- Page  3 --------------------------------

2.2      SWITCHING FILES

Whenever it is  time to  summarize the  accounting records,  it is  first
necessary to  switch the  accounting  files.  Thus  the old  file can  be
operated upon without fear of losing  information (since it is now  being
collected in the new file).

The acctsw program switches the  files by getting the current  accounting
file name from /etc/acctfile, writing the other name into  /etc/acctfile,
and making the system call acct to switch to the new file.  The switch is
immediate.

If an  error is  detected, mail  is sent  to adm  and the  most  recently
updated file is assumed to  be current.  The switching process will  fail
totally if the new accounting file has not been previously truncated to 0
length by the previous run of acctpk.


2.3      KERNEL ACCOUNTING

The UTS Kernel writes a record to  the accounting file for each  process.
The record is as follows:

        struct acct {
                int    ac_rid;       /* record id (0)  */
                char   ac_comm[14];  /* command name   */
                long   ac_utime;     /* user time      */
                long   ac_stime;     /* system time    */
                time_t ac_etime;     /* elapsed time   */
                time_t ac_btime;     /* beginning time */
                short  ac_uid;       /* user ID        */
                short  ac_gid;       /* group ID       */
                int    ac_rdwr;      /* number of I/Os */
                dev_t  ac_tty;       /* tty name       */
                char   ac_flag;      /* flag           */
        };


2.4      UNIT RECORD ACCOUNTING

In order to track Unit Record I/O, the routines vmread, vmpunch, and  opr
were modified.  Each of  these routines uses  the system call acctwrt  to
write their accounting records.  The record format is as follows:

-------------------------------- Page  4 --------------------------------

        struct acct_io {
                int    ai_rid;       /* record id              */
                time_t ai_ctime;     /* time records produced  */
                int    ai_recs;      /* number of i/o records  */
                int    ai_uid;       /* user number            */
                int    ai_gid;       /* group number           */
        };

The record ids are:

        2 for VMREAD records
        3 for VMPUNCH records
        4 for OPR records


2.5      CONNECT TIME ACCOUNTING

Connect Time Accounting was already being done by the init and login rou-
tines.  These routines have been  modified to write their records to  the
new accounting  file (using  acctwrt) instead  of the  old  /usr/adm/wtmp
file.

The meaning of this record is non-trivial.  One of these records is writ-
ten each time a user logs in or logs out.  For a login, a record is writ-
ten with the users name and tty name.  For a logout, a record is  written
with a null user  name (the system only  knows which tty is logging  out,
not who it is).

The tty name '~' indicates that the system was rebooted at the  indicated
time.  An adjacent pair  of entries with  tty names '|' and '}'  indicate
the system-maintained time just before and just after a date command  has
changed the system's idea of  the time (this is not applicable under  VM,
but may be someday).

For each user that is logged on  when the accounting files are  switched,
acctpk acts as if  the user had logged  off when the files were  switched
and does an acctwrt  to simulate the login  of the user  at the time  the
files were switched.

The format of the record is as follows:

        struct acctlog {
                int al_rid;           /* record id   */
                struct utmp al_utmp;  /* login info  */
        };

The record id is 1 and utmp is defined as:

-------------------------------- Page  5 --------------------------------

        struct utmp {
                char ut_line[8];      /* ttyname */
                char ut_name[8];      /* user id */
                int  ut_time;         /* time on */
        };




3.    SUMMARIZING THE DATA

The program cron is used to cause the  following command line to be  exe-
cuted several times each day:

(date; /etc/acctsw; /etc/acctpk -s) >>/usr/spool/adm/track

Thus the file  /usr/spool/adm/track can  be examined to  verify that  the
accounting pack process ran successfully.


3.1      GENERAL FUNCTION DESCRIPTION

The acctpk program reads  from the  file not named  in /etc/acctfile  and
summarizes the data into "daily" files named:

/usr/spool/adm/sum/YYDDD
Where:
      YYDDD is the Julian date that the data applies to.

A -s argument  says that once  the end  of the accounting  file has  been
reached, it is to be truncated to 0 length.

A -t argument says that the acctpk process is to be traced, but no  files
are to be actually updated.  Each record in the accounting file is listed
with this option.  A -s flag is ignored if -t is given.

Each record in the accounting file contains the time the record was writ-
ten, and this  information is  used to determine  which "daily" file  the
data should be placed in.


3.2      ERROR DETECTION

Each record read in the accounting file is checked for validity by seeing
if the time it  was written is less than  7-days apart from the time  the
previous record  was  written.  This  should  eliminate  garbage  records
created by system hiccups.

-------------------------------- Page  6 --------------------------------

If a bad record is found, the acctpk routine keeps reading in an  attempt
to find a good  record.  It is  possible that a  few good records may  be
lost in  this process.   A  thrown out  record  will be  printed  in  the
../adm/track file.  If  more than  50 bad records  are found, the  acctpk
routine gives up and exits.

Each "daily" file  contains information  telling the  highest and  lowest
dated record used to create the file.  In the event that the "daily" file
is created but the accounting file is not truncated to 0 length, a  rerun
of the acctpk program will  not re-add all the information for that  day.
All records  younger than  the high  date  in the  "daily" file  will  be
ignored.


3.3      DAILY FILE FORMAT

Two types of information are kept in the "daily" files: the user data and
the command data.  The first three 4-byte words are as follows:

WORD     CONTENTS
  1      The low-time  (oldest record used to update the file)
  2      The high-time (newest record used to update the file)
  3      The number of user records following

Then comes the user records  in order of userid.   Thus the first  record
represents data for  userid 0,  the next for  userid 1,  and so on.   The
records are as follows:

        struct aday {
                int nocmd;  /* number of commands given */
                int scpu;   /* system cpu - millisecs   */
                int ucpu;   /* user cpu   - millisecs   */
                int uio;    /* user read/write calls    */
                int uconn;  /* user connect time - secs */
                int rread;  /* virtual records read     */
                int rpun;   /* virtual records punched  */
                int rprt;   /* virtual records printed  */
                int ublk;   /* file blocks in use       */
        };

Following the  user records  are the  command usage  records.  A  hashing
function based on the command  name is used to calculate the position  of
the command record.  The following structure is written for each command:

-------------------------------- Page  7 --------------------------------

        struct cmds {
                char name[14];  /* command name          */
                int  count;     /* number of times given */
                int  realt;     /* total elapsed time    */
                int  cput;      /* user cpu time         */
                int  syst;      /* system cpu time       */
                int  io;        /* total read-writes     */
        };




4.    GETTING REPORTS

Two types of reports can be output from the packed information.  The com-
mand ac provides command usage reporting with all sorts of fancy options.
The command au provides individual  user reports.  See Reference [1]  for
information on how to use these commands.

The following glossary should help explain the categories of usage on the
reports.

Connect Time:  The number  of hours  the user  was logged  on during  the
               given accounting period.  Note that if a user is logged in
               on two  or  more different  terminals  simultaneously  the
               resulting connect time is the sum of each of the sessions.

#Commands:     The number of commands issued explicitly or implicitly  by
               the user.

Elapsed Time:  The amount of time between  issuing a command and  comple-
               tion of the command measured in seconds.

Cpu Time:      The number of seconds of cpu time used in the execution of
               a command or commands.

System Cpu Time:   The portion of cpu time  spent in execution of  system
               calls measured in seconds.

User Cpu Time: The cpu time of a command  exclusive of the time spent  in
               system calls (measured in seconds).

Read/Writes:   The number of reads and writes performed.

Unit Record IO:   The number of records read, punched or printed.

Disk Blocks:   The number of disk blocks  in use.  Divide this number  by
               57 to find the number of cylinders used.

-------------------------------- Page  8 --------------------------------

%Usage or Overall%:   The percentage of total system resources used.  The
               various resources are weighted according to the weights in
               the Accounting Weight Table.

Accounting Weight Table:   Gives the relative weighting for each type  of
               UTS resource.   Used to determine  the overall  percentage
               use of each user.




5.    GENERAL MAINTENANCE

The UTS Accounting System is designed to be self running as much as  pos-
sible.  However, occasionally system glitches or bugs may occur.  If  the
accounting system  detects an  error, it  should send  mail to  user  adm
(which stands for "administrator") describing the problem.

Also, all messages from the  acctsw and acctpk  programs are appended  to
the file /usr/spool/adm/track.

It is recommended that some person be assigned the task of logging in  as
user 'adm' once a day  to check for mail, and to check that the  informa-
tion in the ../adm/track file looks reasonable.




6.    REFERENCE MATERIAL

The following items may be of further interest to the reader:

 [1]  ac(1) and au(1) in the UTS Programmer's Manual, Volume 1,

 [2]  acct(2) and acctwrt(2) in the UTS Programmer's Manual, Volume 2

 [3]  accton(3) in the UTS Programmer's Manual, Volume 3
