Digital

NAME

x25accounting − Generate accounting reports

SYNOPSIS

/usr/sbin/x25accounting [-bcdisv] [-e ’directives’] [-f script] [-r rejectfile] [logfile ...]

FLAGS

-bThe brief format presents one line for each record in the accounting logfile(s) being processed.  By default, records are displayed in this format.  The output includes start time, finish time, username, process ID, and terminal information. 

-cThe custom format presents one field per line and one record per page.  This format allows a customized report to be produced.  Commands must be specified with either the -e or -f option to determine which components of the accounting records are included in the report. 

-dThe discard format presents details of periods of time during which accounting records have been discarded.  Each period is listed with the number of records discarded during that period. 

-iThe image format generates binary records for subsequent use with other report formats.  This option is typically used to break up an existing log file into separate files before generating reports from each file. 

-sThe summary option produces a summary of the selected records, grouped according to the list of summary fields specified.  The report and summary directives are used in combination to indicate what information is to be summarized.  Commands must be specified with either the -e or -f option to determine which components of the accounting records are included in the report. 

-vThe verbose listing format presents all data contained in the selected records. 

-eAllows directives to be specified on the command line, each directive separated from the next by a semi-colon (;).  The entire list of directives specified should be enclosed in single quotes (’). 

-fAllows directives to be read from the file script.  If many directives are required to generate the desired report, it may be more convenient to place them in a file. 

-rBy default, any records not selected are ignored.  Alternatively, they can be copied to a rejectfile for subsequent processing.  This file has the same format as the log files and can be used as subsequent input to x25accounting. 

Where appropriate, data for each record is generated on a separate page.  Output can be manually redirected to any screen pager.  By default, records are displayed using the brief report format. 

Only one of the -b, -c, -d, -i, -s or -v command line options should be specified when using x25accounting. 

If no logfile is specified on the command line, accounting records are read from standard input. 

DESCRIPTION

The x25accounting utility allows reports to be generated that contain data on X.25 calls made to or from an X.25 for Digital UNIX system.  It provides access to the accounting records collected by the accounting daemon, x25accoutingd(8X25). 

Accounting records are generated at the termination of each X.25 call made to or from the X.25 for Digital UNIX system.  Calls cleared before being accepted also generate accounting records.  When accounting records are being collected for PVCs, the records are generated when the PVC is closed.  Thus, an accounting record for a PVC starts when the PVC is opened and finishes when it is closed. 

An accounting record contains information about the duration of the call, the data transferred, the call characteristics, and the local and remote DTEs if an SVC is being traced.  If a PVC is being traced, local and remote DTEs have no significance, but the name of the PVC will be recorded.  This information can be used for charging purposes or for monitoring performance. 

It is not guaranteed that all calls will be logged.  Calls are logged only while the accounting daemon is running.  When the system is under extreme load, records of calls may be discarded before being collected by the daemon. 

Once a record is collected, the system counts the number of records it discards until another record can be collected.  The system stores this count of discarded records in the later record.  An accounting record, therefore, specifies the number of records discarded between the termination time of that record and the termination time of the previous record. 

The accounting utility uses temporary files to generate reports.  The TMPDIR environment variable is examined to determine the directory in which temporary files are created.  If the TMPDIR environment variable is not set, the /tmp directory is used. 

REPORT GENERATION

The reports generated by x25accounting are controlled by a set of options and directives.  The directives can either be specified on the command line as arguments to the -e option or in a file specified as an argument to the -f option. 

The records used to generate the report, the order in which the records appear, and the format of the report are determined by the directives specified. 

Directives must be separated either by semi-colons (;) or be placed on separate lines. 

Both the summary and custom report formats require directives to be defined to construct reports. 

Directives specific to the summary and custom report formats can be included in a command file with the directives for reports of other types.  These directives are verified for correct syntax, but will only affect the report generated if the appropriate option (-c for show, -s for summary and report) is specified on the command line. 

select / reject
 
The select directive allows you to select sets of records from accounting log files; any records not selected are rejected.  By default, all accounting records are selected for inclusion in the specified report and rejected records are ignored.  If a rejectfile is specified on the command line with the -r option, rejected records are stored in the specified file. 

The format of the select directive is:

select field1=value1[,field2=value2 ...]

All records that satisfy the criteria specified are selected.  More than one select directive may be used to select different sets of records for inclusion in the report. 

The reject directive has the same format as the select directive but has the opposite effect, identifying particular sets of records that are to be excluded from the report. 

Any reject directives are performed before select directives, regardless of the order in which the directives are specified. 

The following table shows the fields on which records can be selected or rejected and the format of the values associated with them:

Field	Format
before	UTC time specification
gid	decimal number
group	alphanumeric string
local	DTE address
pid	decimal number
ppid	decimal number
priority	decimal number
pvc	alphanumeric string
remote	DTE address
since	UTC time specification
terminal	(major device number, minor device number)
uid	decimal number
user	alphanumeric string

Times should be specified in the format:

YYYY-MM-DD-hh:mm:ss.xxTDF

where YYYY is the year, MM is the month, DD is the day, hh is the hour, mm is the minute, ss.xx is the second and fraction of a second and TDF is the Time Difference Factor relative to Greenwich Mean Time expressed as shh:mm form, where s is ’+’ for places east of GMT and ’-’ for places west of GMT. 

Any meaningful subset of this format may be used to specify a time.  If the TDF is omitted then local time is assumed.  For example:

15:40:00	Corresponds to 1992-10-14-15:40:00.00+10 if used on the 14th of October, 1992 in Australia (TDF +10).
1992-10-14	Corresponds to midnight, local time, on October 14, 1992 wherever it is used.
1992-10-14+0	Corresponds to midnight, GMT, on October 14, 1992.

sort

The sort directive produces a report in which records are sorted by record field in the order you specify.  In addition to specifying the fields on which to perform the sort, you can also specify the the sequence (ascending or descending) in which each field is sorted.  The format of the sort directive is:

sort [-]field1[, [-]field2 ...]

You can specify any of the following fields as sort fields: elapsed, finished, gid, group, pid, ppid, priority, started, terminal, uid and user. 

Multiple sort fields may be specified either in the same or separate sort directives.  If more than one sort field is specified, the records are initially sorted using the first specified sort field.  Any records which have the same value for the first field are then sorted using the second sort field, and so on with subsequent fields. 

By default, records are sorted in ascending order.  To sort records in descending order on a particular field, precede the sort field with a minus (-) sign. 

summary / report
 
The summary and report directives are used in combination to produce a summary of the number of records or the total duration of X.25 calls that match specified criteria.  These directives also allow you to determine whether the accounting records of any calls have been discarded. 

These directives have the format:

summary summaryfield1[, summaryfield2 ...]
report reportfield1[, reportfield2 ...]

You can specify any of the following summary fields: date, day, gid, group, hour, month, terminal, uid, user, weekday, and year.  If no summary directive is used, the default summary field, user, is used. 

You can specify any of the following report fields: records, elapsed, and discarded.  If no report directive is used, the default report field, records, is used. 

All selected records that have the same value for each summary field specified are grouped together.  Each such group generates a line in the summary report.  The report fields specified control what statistics are collected for each group of records:

records	The number of records in each group.
elapsed	The total duration of the calls in each group.
discarded	The total number of discarded records is printed at the bottom of the report.

To generate a summary report the -s option must be specified on the command line. 

show
 
The show directive allows you to customize a report.  To use the show directive the -c option must be specified on the command line.  The report contains only those fields specified with show directives.  The report consists of one field per line and one record per page. 

The format of the show directive is:

show field1[,field2 ...]

You can specify any of the following show fields: elapsed, finished, gid, group, local (local DTE address), pid, ppid, priority, pvc, remote (remote DTE address), terminal, uid, and user. 

Discarded Record Reports

A discarded record report is generated if the -d command line option is specified when x25accounting is invoked.  The lines of the report identify periods of time during which accounting records have or have not been discarded. Meaningful reports are generated if the before and since directives are the only selection directives used. 

Verbose Reports

A verbose report is generated if the -v command line option is specified when x25accounting is invoked.  In addition to the details available through the other report types, details about the call statistics are also displayed. 

EXAMPLES

The following examples give the directives required to generate some simple reports. 

Selecting and Rejecting Records

To select all records with user name smith:

select user=smith

To select all records with user name "smith" and group name "staff" created since the beginning of August, 1992:

select user=smith, group=staff, since=1992-08

To select all records with user name "smith" or "jones":

select user=smith
select user=jones

To select all records with any user name other than "smith":

reject user=smith

Note: If the name of a rejectfile was specified on the command line (using the -r option) then all records with user name "smith" will be stored in the specified file. 

To select all records with user name "smith" that were generated after the beginning of August, 1992: smith:

select user=smith, since=1992-08

or

select user=smith
reject before=1992-08

Sorting Records

To sort selected records by user name:

sort user

To sort selected records by user name and then by start time:

sort user, started

To sort selected records by user name in ascending order then by start time in descending order:

sort user, -started

Summary Reports

To produce summary reports, x25accounting must be invoked with the -s command line option. 

To produce a report of the number of calls made by each user on a user-by-user basis:

summary user
report records

To produce a report that gives a day-by-day breakdown of the calls made and the total time spent communicating by each user, and a count of any calls discarded:

summary user, date
report records, elapsed, discarded

Customized Reports

To produce a customized report, x25accounting must be invoked with the -c command line option. 

To produce a report showing the elapsed time, user name, user ID, process ID, and terminal:

show elapsed, user, uid, pid, terminal

RESTRICTIONS

All timestamps are displayed with the seconds field rounded to three decimal places. 

DIAGNOSTICS

Any error conditions that arise are reported by x25accounting in the format:

component: error message

Where component specifies the part of the x25accounting utility which detected the error and error message describes the error that occurred. 

The component may be one of x25brief, x25custom, x25discrd, x25image, x25select, x25sort, x25summary, or x25verbose. 

FILES

/var/adm/x25log.∗Accounting log files

RELATED INFORMATION

Commands: x25accountingd(8X25). 

Functions: X25ReadAccountingLog(3X25), X25WriteAccountingLog(3X25), intro(3dts). 

X.25 for Digital UNIX − Management Guide.