The fwaudit utility may be used to extract audit information from
the forward-log files. The audit information may be converted into
the Eloquence binary audit file format and/or output as text.
usage: fwaudit [options] file [...]
-help - show usage (this list)
-o filename - write binary audit output to file (- for stdout)
-c comment - write clear-text comment into binary audit file
-e expr - specify filter expression
-f filename - read filter expression from file
-r - print clear-text report
-m - print MEMO records
-i number - print values of the first 'number' items
-I itemlist - print values of specified items (comma- or space-separated)
-v - print progress info / report details (-vv: more details)
-x - clear-text diagnostic output (hexdump format)
-M - use master key
-Z - compress audit file
The fwaudit utility processes one or multiple forward-log files that
are specified on the command line. In addition, it can read and process
its own binary audit file format, so it is typically used to create
Eloquence audit files as well as to later analyze them.
If multiple forward-log files are specified, fwaudit automatically
recognizes their volume generation and sequence numbers and sorts
them appropriately so that they are processed in the correct order.
This is done by reading the file headers, therefore this works even
if the file names do not indicate the generation and sequence.
The options are:
The -o option may be used to specify the name of an output file. If
present, the audit information is written to this file encoded in the
Eloquence binary audit format.
A - as the output file name specifies the standard output.
If an output file is created, the -Z option may be used to write
a compressed output file (gzip compatible). When reading audit files with
fwaudit, the compressed format is detected automatically.
If an output file is created, the -c option may be used to write an
user-defined comment to the beginning of the file, for example to
include a label that may later be helpful to associate the file's
The -e and -f options allow to specify one or more
filter expressions to qualify the information
which is output. This affects both the information written to an
audit file as well as any clear-text output.
The -r option activates the clear-text reporting to analyze the contents
of forward-log or binary audit files. It may be combined with the -i,
-I and -v options to specify the level of detail:
- If the -r option is specified alone (that is, neither -i nor -I nor
-v are specified), the DBPUT, DBUPDATE or DBDELETE actions are printed
indicating the data set, record number, timestamp and session
number they belong to. Whenever a new session number occurs,
the associated session sign-on record is printed which indicates
the session's client process information.
- The -i option specifies the number of item values which should be printed
for each action (DBPUT, DBUPDATE or DBDELETE) in addition. For example,
-i3 specifies that in addition to the -r output the first three item
values should be printed.
- The -I option allows to specify a list of item names which values
should be printed for each action in addition. For example, -I
'custno, matchcode, name' specifies that in addition to the -r output
the values of the CUSTNO, MATCHCODE and NAME items should be printed
if they are part of the particular data set.
If a single array element should be printed, specify the 1-based element
index in square brackets. For example, the first element in the TURNOVER
array is specified as TURNOVER. To specify that all elements of an
array should be printed, use the array item name, for example TURNOVER.
- For DBUPDATE, if -i or -I is specified modified item values
are always printed regardless whether they are covered by the -i or -I
specification. For example, if you specify -i1 but the value of the
third item was modified its old and new values are printed.
- If the -r option is not specified, the -i and -I options have no effect.
- If the -v option is specified alone (that is, -r is not specified)
the progress is indicated by printing the name of each
processed file. Specifying -v twice (-vv) prints additional file
header detail information.
- If both the -v and -r options are specified, the values of all
items are printed for each action unless the items to be printed
are qualified with -i or -I.
The -m option activates clear-text output of TurboIMAGE DBMEMO
and DBBEGIN/DBEND records, which may have been recorded depending
on the HP3K_API_COMPAT database property.
- TurboIMAGE DBMEMO and DBBEGIN/DBEND record data is output in
clear text by default. Any non-printable characters are printed as
octal escape sequences (the same way item values are output).
The -x option allows to switch to a hexdump output format instead.
- The -m option may be combined with the -r option (print clear
If neither -o nor -r nor -v nor -m are specified, fwaudit just silently checks
the forward-log or binary audit files for consistency and prints any error
or warning messages to the standard error output.
A filter expression qualifies the information that is processed by the
fwaudit utility. It affects both the data written to a binary audit
file and the clear-text reporting output. This may be used for various
purposes, for example:
- To extract a subset of the original information from either
forward-log or binary audit files to a new binary audit file
- To create a clear-text report about specific actions in a
database from either forward-log or binary audit files
Filter expressions follow a syntax that allows to specify different
Filter expressions may be combined with AND, OR and NOT operators.
- filter by timestamp
- filter by the type of database operation (dbput, dbupdate, dbdelete)
- filter by database and data set
- filter by record number
- filter by process specific information (e.g. user, pid, or program name)
- filter by item value
- filter by session identifier
- filter by session connection timestamp
- filter by TurboIMAGE DBMEMO and DBBEGIN/DBEND information
Find details and examples on
using filter expressions
in the Eloquence B.08.10 document on
The fwaudit -M option is used with encrypted forward logs.
When specified, the EQ_MKEYID and EQ_MKEYFILE environment variables
are used to provide master key(s) to access encrypted data.
The user is prompted to enter the pass-phrase(s).
- EQ_MKEYID specifies a colon separated list of master key id's.
Up to 6 master key id's may be present.
- EQ_MKEYFILE specifies a colon separated list of master key files.
Up to 3 key files may be specified. The default key file is eqdb.key.
$ export EQ_MKEYID=alpha:beta
$ export EQ_MKEYFILE=test.key
$ fwaudit ... -M ...
Enter passphrase for alpha:
alpha: Master key activated
Enter passphrase for beta:
beta: Master key activated
Note that using fwaudit on forward logs with encrypted data is also
possible without specifying the -M option and master keys. However, this
only grants access to the items that are not encrypted. For all encrypted
items, fwaudit will only display blank or zero values.
The first example uses the -o option to extract audit information to
a binary file for archiving or subsequent reporting. The second example
uses the -r option to create a text report, specifying item names to
display and a filter expression to select records by timestamp.
fwaudit -o 20050705.audit /data/fwlog/*
fwaudit -rvv -I'albumcode,composername' \
-e'timestamp >= 2005-07-05 14:09:06' /data/fwlog/*
processing file: 222-1.log
byte order: 4321
character set: hp-roman8 (0)
volume release: 11
volume set id: 0x395e413e
volume generation: 222
file sequence: 1
DBPUT MUSIC.SELECTIONS (#489) recno:148065 session:7
timestamp: 2005-07-05 14:09:06
ALBUMCODE : 17358
COMPOSERNAME : "Ludwig Beethoven"
DBDELETE MUSIC.SELECTIONS (#489) recno:13343 session:7
timestamp: 2005-07-05 14:09:06
ALBUMCODE : 17358
COMPOSERNAME : "Edvard Grieg"
DBUPDATE MUSIC.SELECTIONS (#489) recno:148344 session:7
timestamp: 2005-07-05 14:09:06
ALBUMCODE : 27625
COMPOSERNAME : "Amadeus Mozart"
-COMMENT : "Comments"
+COMMENT : "Comments Updated"
Audit file format