.\" $Copyright: $
.\" Copyright (c) 1995 - 2000 by Steve Baker (ice@mama.indstate.edu)
.\" All Rights reserved
.\"
.\" This software is provided as is without any express or implied
.\" warranties, including, without limitation, the implied warranties
.\" of merchant-ability and fitness for a particular purpose.
.\"
...
.V= $Header: sac.8 1.8 1995 - 2000 $
.TH SAC 8 "\*(V)" "UNIX Manual"
.SH NAME
sac \- system accounting.
.SH SYNOPSIS
\fBsac\fP [\fB-acdfFhilmoprtU\fP] [\fB-w\fP [\fIwtmp-list\fP|\fB-\fP]]
[\fB-b\fP \fIH\fP[\fI:M\fP[\fI:S\fP]]] [\fB-s\fP \fIstart\fP]
[\fB-e\fP \fIend\fP] [\fB-X\fP[\fB3\fP|\fB4\fP]]
[[\fB-u\fP] \fIuser-list\fP] [\fB-x\fP [\fIuser-list\fP]]
[\fB-T\fP [\fItty-list\fP]] [\fB-H\fP [\fIhost-list\fP]]
[\fB-I\fP \fIH\fP[\fI:M\fP[\fI:S\fP]]] 
[\fB-M\fP \fIhour-range\fP[,...]]
[\fB-R\fP [\fIportmaster\fP/\fIpattern-list\fP]]
[\fB--seconds\fP]
[\fB--hms\fP] [\fB--hm\fP] [\fB--hours\fP] [\fB--round\fP] [\fB--longdate\fP]
[\fB--help\fP] [\fB--version\fP]
.br
.SH DESCRIPTION
\fISac\fP is a system administration utility, based on the original BSD
\fIac\fP program, to read the wtmp log and produce more human readable system
usage information than provided by \fIlast\fP. Several features not found in
the BSD version of this program have been added.

\fISac\fP produces five different types of output:  Total usage in number of
login hours since wtmp was created (default), login usage per day
(\fI-d\fP), total usage per user (\fI-p\fP), usage per tty line (\fI-t\fP),
simultaneous usage (\fI-U\fP) and raw usage (\fI-r\fP), which prints
everything sac knows about your accounting file(s). The output of these six
are modified by supplying either the average (\fI-a\fP) option, the hourly
profile (\fI-h\fP) option, the login listing (\fI-l\fP) option, and/or the
clipping (\fI-c\fP) option.

The \fI-s\fP and \fI-e\fP options are used to select the starting date and
ending date, respectively, to report on. The format for the date is one of:
\fB+\fP\fIdays\fP (days since the beginning of the wtmp file) or
\fB-\fP\fIdays\fP (days before the end of the wtmp file) or in standard date
format: \fIMM/DD/YY\fP.

The \fI-M\fP option is used to select only specific hours in a day to perform
accounting on instead of all the hours in the day.  The \fIhour-range\fP
format is: (0-23)[-(0-23)[,\fIhour-range\fP[,...]]].  The hour given applies
to the whole hour, so a range of "5-6" is a time range from 5am to 6:59:59am.
This option is probably only useful to those ISP providers that want to
charge a different rate for specific time periods.

Selecting the average option for total usage, gives an average number of
login hours per day since the creation of the wtmp file.  For the daily
option it prints the total # of logins for the day and the average login
time per login.  For the per person display it displays the total number of
logins the user has made and the average amount of time spent on each login.
For the TTY option, it prints the total number of logins on that TTY and the
average amount of time for each login.

Selecting the hourly profile option for total usage gives a visual display
of the percentage of login time spent per hour for all the logins on the
system.  For the daily option it prints the same visual display for each
day.  For the per person display it displays the hourly breakdown of login
time the user spends on the system (this can be pretty interesting).  For
the TTY option it breaks down hourly usage for each TTY.

Selecting the login listing option shows the logins and total time for each
individual login for the time period requested on each day, tty line or
person depending on the profile requested.  Such output is ready-made for
use as a ISP billing back-end.

Selecting the \fI-c\fP option performs clipping on the amount of login time
being used.  Multiple logins during the same time period will only count
once.  As a side effect (possibly a bug) clipping will affect the output of
the average option, reporting only the number of logins that uniquely apply
to the total login time. Logins that fall totally within the time span of
other logins will be totally clipped out, as if they did not occur.

If the optional user-list is given \fIsac\fP will only consider accounting
information from those users, discarding the rest.  The \fI-u\fP option can
be used to precede the optional user-list.  This option is useful to
terminate the \fI-x\fP, \fI-T\fP and \fI-H\fP options.

The \fI-x\fP option, has the reverse effect of the \fI-u\fP option, in that
it excludes the users specified from accounting.  This is useful for
removing users that are on a lot, which skew average usage results.

The \fI-T\fP option performs accounting for only the optionally specified
tty lines listed.  This is useful for determining modem usage, and who's
been using them the most.  The tty line may be given as a wildcard pattern,
using `*', `?', `[...]' and `[^...]' to easily select a given set of tty
lines (such as ttyC* to produce accounting on cyclades tty lines).  Wildcard
patterns should escaped or quoted to avoid having the shell process them.

The \fI-H\fP option performs accounting for only the optionally specified
hosts listed.  Since a host-name can only be up to 16 characters long in the
wtmp file, only the first 16 characters of a given host-name will be
considered for purposes of matches.  If a host-name given on the command line
does not contain any dots (\fB.\fP) or ends with a dot, it is taken to be a
substring and will match if the first part of the wtmp host-name matches the
substring.  Like with tty lines, the hostname may be given as a wildcard,
using `*', `?', `[...]' and `[^...]' to easily select a large number of
hosts at once (such as *.indstate.*).

If an option word used in a \fI-u\fP, \fI-x\fP, \fI-T\fP or \fI-H\fP list
begins with an '@' (at) sign, it denotes that the option word specifies a
file which contains a list of usernames, ttys or hostnames to be applied to
the specific option.  The "include file" may contain comments which are
denoted by a '#' (pound) character at the beginning of a line, ala shell
scripts.  If a word in an include file begins with an '@' as well, it
denotes another file is to be included.

The \fI-f\fP option makes sac perform accounting on both normal logins and
ftp logins. The \fI-F\fP option makes sac perform accounting on ftp logins,
normal logins are not considered.  Sac is only guaranteed to work with
wu-ftpd (wu-archive FTP daemon) style of utmp entry for ftp logins, denoted
by a line of "ftp#####" where "#####" is the process ID of the ftp process.

The time format for sac defaults to fractions of hours.  Thus 1.5 hours is 1
hour and 30 minutes.  The output time format may be changed using the
command line options \fI--seconds\fP (seconds only), \fI--hms\fP
(hour:minute:second format), \fI--hm\fP (hour:minute format), \fI--hours\fP
(hours only format), and \fI--round\fP which rounds the time to the nearest
minute or hour instead of always rounding down.
.br
.SH OPTIONS
\fISac\fP understands the following command line switches:
.TP
\fB--help\fP
Outputs a verbose usage listing.
.PP
.TP
\fB--verbose\fP
Prints alerts when sac encounters errors or other strange phenomenon. In the
case of a null wtmp entry (sometimes caused by crackers covering their
tracks) sac will print an approximate time stamp with the alert.
.PP
.TP
\fB--version\fP
Outputs the version of sac.
.PP
.TP
\fB-w\fP [\fIwtmp-list\fP|\fB-\fP]
Select a different input file(s) instead of the default (\fI/var/log/wtmp\fP).
The accounting file type is determined by the options used before -w is reached.
.PP
.TP
\fB-d\fP
List login time per day instead of the default total time.
.PP
.TP
\fB-p\fP
List login time per user instead of the default total time.
.PP
.TP
\fB-t\fP
List login time per tty line instead of the default total time.
.PP
.TP
\fB-U\fP
List simultaneous usage levels.  Lists amount of time at each usage level
(number of ttys used simultaneously) and the number of accountable hours
(time * usage level) at each usage level.
.PP
.TP
\fB-r\fP
Print almost everything that sac knows about your wtmp file. Time is
displayed in seconds.  The Hourmask is a 24 bit field representing which
hours accounting was performed on (zero for no mask used). The format is
fairly obvious.  Useful for use as a back-end to some accounting package or
for graphing usage. Quite verbose.
.PP
.TP
\fB-a\fP
Print average information.
.PP
.TP
\fB-h\fP
Print hourly profile information.
.PP
.TP
\fB-l\fP
Print login listing information.
.TP
\fB-c\fP
Perform login "clipping".  Multiple logins during the same time period will
only count once.
.PP
.TP
\fB-I\fP \fIH\fP[\fI:M\fP[\fI:S\fP]]
Ignore specific amount of login time for each user before performing
accounting.  Only works with -p option.
.PP
.TP
\fB--seconds\fP
Display time in seconds.
.PP
.TP
\fB--hms\fP
Display time in Hours:Minutes:Seconds format.
.PP
.TP
\fB--hm\fP
Display time in Hours:Minutes format.  Seconds are rounded off.
.PP
.TP
\fB--hours\fP
Display time in hours only format. Minutes and seconds are rounded off.
.PP
.TP
\fB--round\fP
Round time displayed with "--hm" to the nearest minute, or to the nearest
hour with "--hours".
.PP
.TP
\fB--longdate\fP
Displays dates in long notation (weekday, month, day and four digit year).
.PP
.TP
\fB-o\fP
Read the wtmp file as if it were an old style BSD wtmp file (old utmp format
which does not use ut_type field).  Programs such as tacacs maintain a
wtmp file which does not use all the fields.
.PP
.TP
\fB-S\fP
Attempts to seek into wtmp to the day specified by the -s option (-s
MM/DD/YY). Not guaranteed to work.  If the seek fails it will attempt to
rewind input to the beginning and continue normally.  Useful for seeing
last days usage from a large wtmp file.
.PP
.TP
\fB-X\fP[\fB3\fP]
Read a wtmp file maintained by xtacacs, terminal server access control software,
versions 3.4 and 3.5.
.PP
.TP
\fB-X4\fP
Read a wtmp file maintained by xtacacs version 4.0.
.PP
.TP
\fB-i\fP
Include hostname information when trying to determine logins and logouts.
This is useful for accurately parsing tacacs accounting logs which merge
accounting for multiple terminal servers into the same log.
.PP
.TP
\fB-R\fP \fIportmaster\fP/\fIpattern-list
Read and process the detail files maintained by the Radius access control
software for terminal servers.  Sac will process each detail file in
/usr/adm/radacct/<portmaster-name>/detail each in turn until all the detail
files have been processed.  If no portmaster name is given, a detail file
must be specified with the `\fB-w\fP' option. If a wildcard pattern is
given, sac will attempt to find all portmaster directories that match the
pattern located in the radacct directory. A detail file may be specified
with the `\fB-w\fP' option in addition to the `\fB-R\fP' option.
.PP
.TP
\fB-D\fP
When processing radius logs, this option specifies that sac should use the
@hostname part of user@hostname for the hostname field instead of
portmasters hostname.  Useful for -H filtering when using radius logs.
.PP
.TP
\fB-P\fP
Perform packet and octet accounting when reading from a detail file that
logs packet and octet information (i.e. Ascend terminal servers).
.PP
.TP
\fB-b\fP \fIhours\fP[\fI:minutes\fP[\fI:seconds\fP]]
Consider only those utmp entries that fall within the last few
hours/minutes/seconds from the current time, disregarding the rest.  This
option is useful for determining if someone has been on in the last few
hours.
.PP
.TP
\fB-s\fP \fIstart\fP
Selects the starting date of the report.
.PP
.TP
\fB-e\fP \fIend\fP
Selects the ending date of the report.
.PP
.TP
\fB-M\fP \fIhour-range\fP[,...]]
Select only specific hours in a day to perform accounting on instead of all
the hours in the day.  The \fIhour-range\fP format is:
(0-23)[-(0-23)[,\fIhour-range\fP[,...]]].  The hour given applies to the
whole hour, so a range of "5-6" is a time range from 5am to 6:59:59am.
.PP
.TP
\fB-f\fP
Perform ftp login accounting in addition to normal shell accounting.
.PP
.TP
\fB-F\fP
Perform ftp login accounting only.
.PP
.TP
\fB-m\fP
Show minimum and maximum number of concurrent logins over the total time
span or per day/per user when used with the -d/-p option.
.PP
.TP
\fB-u\fP \fIuser-list\fP
Selects only those users to perform accounting on.
.PP
.TP
\fB-x\fP \fIuser-list\fP
Selects those users to not perform accounting on.
.PP
.TP
\fB-T\fP \fItty-list\fP
Selects those ttys to perform accounting on.  Each tty specifier may be a
wildcard.
.PP
.TP
\fB-H\fP \fIhost-list\fP
Selects those hosts to perform accounting on.  Each host specifier may be
a wildcard.
.PP
.SH FILES
/var/log/wtmp                  login database
.br
/usr/adm/radacct/.../detail    Radius accounting logs
.SH AUTHOR
Steve Baker (ice@mama.indstate.edu)
.SH BUGS
The documentation for wtmp is lacking. It's not clear at all what all gets
put in wtmp or the significance of any of it.

The -o and -X options handle what is a login and a logout differently than
normally (because there is no ut_type field), making sac incorrectly
identify \fIxterm\fP log-outs as a login (\fIxterm\fP does not write a
"login" entry, only a "logout" entry that looks just like a login in all
respects save the contents of the ut_type field).  It should also be noted
that \fIlast\fP incorrectly handles xterm log-outs as well.

The -f or -F options should not be used with -o -X[3|4] or -R options, as
sac will default back to a normal utmp format, or ignore the -f or -F
directives depending on where they occur on the command line.

Using the -S option will cause sac to skip over accounting information which
may well apply to the days you are inspecting.  The only sure way to get all
the accounting information is to start at the beginning or at least a day
before the start you are interested in.

The -m option does not accurately report true min/max usage when inspecting
more than one logfile if those logfiles overlap the same time range.

The -U option may report incorrect amounts of time when compared to
the -t option. As yet I have no idea why.

Sac (probably) only handles changes in time logged in the wtmp file
made by \fInetdate\fP. \fIRdate\fP does not log time changes.

Clipping can affect the output of the average option, as described above.
Radius accounting uses Acct-Session-Time to determine usage when a stop
record has no start record.  Clipping will not function correctly when there
are missing start records.

The ut_addr field doesn't seem to be consistently used by all programs, so
it cannot be used for exact host-name filtering.  Even if it were, it would
be too much work for this lazy programmer anyway.

Radius detail logs suck.  There is not one standard radius detail file
format.  Sac is not guaranteed to work with your detail file.  If you
suspect sacs' output is not correct, please contact the author at the e-mail
address above.

Null usernames in radius detail logs are represented as "UNKNOWN" by sac,
which may be a valid username.

Too much accounting results in big brother... citizen.
.SH SEE ALSO
.BR ac (1),
.BR last (1),
.BR rawtmp (1),
.BR wtmp (5),
.BR netdate (8L)