Audit logging provides a command-line interface to manage audit
logging and view audit logs. Audit logs provide a history of changes
to objects in the system. They are stored in a full-text index.
If audit logging is used, then for the objects it tracks, its logging
replaces the messaging that otherwise would be visible in .
Important: Audit logging works only on operations that
are performed directly on a running system. It does not work on data
imported into the system. The bfimport facility updates the database
directly and does not interact with the audit logging facility.
Managing Audit Policy
An audit policy controls
how much auditing is done. It is determined by the setting of the
Audit Policy system configuration setting.
- NONE
- No auditing information is recorded.
- SECURITY
- Only security-related are recorded. Examples: access group creation
and user session activity.
- BASIC
- This is the default setting. It is also used if there is an invalid
Audit Policy value. Only minimal information is recorded, such as
user, object type, uuid, and action.
- DETAILED
- Records detailed information about what properties changed, including
the old value and the new value. Not all objects can provide this
information. For those that cannot, there is no difference between
BRIEF and DETAILED policy. The Audit Max String Length system configuration
setting can be used to limit the amount of data stored.
The Audit Max String Length system configuration
setting controls how much information can be recorded for a DETAILED
change by capping the length of string data fields. If the audit item
exceeds this number of characters, then an SHA message digest is stored
instead of the string value. For fields that contain sensitive information,
such as passwords, the message digest is used regardless of the string
length.
Displaying audit information
A command-line
interface allows you to specify what information to display and how
to format it.
The View All Audit Logs permission is required.
It is assigned by default to the Security and Build Engineer access
groups.
Usage: bfauditlog [connection-options][command-options][query]
The
literal executable is as follows:
- Windows systems: bfauditlog.bat
- UNIX and Linux systems: bfauditlog.sh
Connection options
- -H hostname | --hostname=hostname
- The remote host name for the connection. The default is localhost.
- -P port | --port=port
- Communications port for the connection. The default is 3966.
- -d domain | --domain=domain
- The domain or realm for authentication. Default: none.
- -u login | --user=login
- The user name to use for authentication. The default is root.
- -p password | --password=password
- The password for the authentication user. The default is root.
- -E encoding | --encoding=encoding
- The output character set encoding to use. If an invalid encoding
is specified, then all available encodings are listed and the program
exits. Note that the ability to display text in the requested encoding
depends on the capabilities of the terminal software used on the
client. The default depends on your operating system and JVM support.
Command options
- -h
- Display help.
- -b | --bare
- Display less information in the output (bare). The exact effect
depends on the output format (see -t). For example, in XML output,
the opening tags, ending tags, and row count are omitted. In CSV,
the row count and the column names are omitted.
- -c auditClass[,auditClass ...] | --audit.class=class-list
- Specifies a list of audit classes to use in the query. Separate
multiple class names with commas. If specified multiple times, then
the union of all audit classes specified is used. If the option is
not specified, then all audit classes that the user can specify are
used. Use the -L option to list available audit classes.
The default is all audit classes that the user is authorized to view.
- -f field[,field ...] | --field=field-list
- Specifies the fields to include in the output. Separate multiple
field names with commas. Use the -L option to list
available fields.
- -s field[+|-][,field[+|-] ...] | --field=field-list
- Lists the fields to use for sorting the output. By default the
output is sorted in descending order of the audit.stamp. The + marker
specifies ascending order. The - marker specifies descending order.
Separate multiple field names with commas. The default is -audit.stamp.
- -l [offset,]count | --limit=[offset,]count
- Used to paginate the results. The offset and count are expressed
in numbers of entries. For example, "-l 100,50" means show 50 entries,
after the 100th entry. Output formats that are not bare will include
the total number of matching entries in the output.
- -a user[,user ...] | --audit.user=user-list
- Limits output to entries associated with the specified user or
users. Separate multiple user names with commas. If you use multiple -a options,
the command uses the union of all users specified in the options.
The users may be specified by login IDs or UUIDs. If -–audit-user is
specified without a user argument, then the user that is used for
authentication is used.
- -t format | --format=format
- The format to use for output, one of CSV, XML, JSON, or TEXT.
The default is TEXT.
- -L | --list
- Lists available audit classes for the user. Audit classes that
are marked with a asterisk (*) are available for the user to access.
If used with -c (list of audit classes), then a list
of fields available for each class is displayed instead. Other command
options have no effect with when this option is specified. Users with ViewAllAudits permission
can view audit logs from any class. Other users can use the -a option
to view only their own audit logs.
Query
The query is a string that
uses the format commonly used by web search engines: a space-separated
list of specifications. Specifications are in the form 'field:value' to
search for value in the specified field. If no query
is specified but at least one option is specified, then all matching
audit logs are displayted. The audit user and audit class cannot be
specified in the query. Use the command options to specify them.
Note: Use
double quotes on Windows systems and single quotes on UNIX and Linux
systems.
Examples
- This example lists all known query fields for the Project and
Step audit classes.
- Windows
$ bfauditlog.bat -c Project,Step -L
- UNIX and Linux
$ bfauditlog.sh -c Project,Step -L
- This example shows the 10 most recent audit logs for project creations
using a comma-separated variables output format and without the column
headings or total row count. Only the project's unique identifier
and name will be given for each record.
- Windows
$ bfauditlog.bat -c Project -t CSV -f audit.target,
sxProjectName --bare -l 10 "audit.type:Create"
- UNIX and Linux
$ bfauditlog.sh -c Project -t CSV -f audit.target,
sxProjectName --bare -l 10 'audit.type:Create'
- This example retreives the 100 most recent audit logs from the
installation on the machine 'buildforge.example.com' after logging
in with the domain, username, and password provided.
- This example retrieves the audit logs that were recorded from
the beginning of May 23, 2011 to the end of May 27, 2011, according
to the time zone settings of the user that authenticated the connection.
- This example retrieves the audit logs for projects whose access
group levels were changed from the old value of 4, 5, or 6 to the
new value 3. Note that square brackets are used to indicate an inclusive
range, so '[4 TO 6]' means that the values 4 and 6 will match. Also
note that the old and new level values will only be available to search
if the auditing policy has been set to 'DETAILED'.
- This example retrieves the audit logs for projects whose access
group levels were changed from the old value of 4 or 5 to the new
value 2 or 3. Note that curly braces are used to indicate an exclusive
range, so '{3 TO 6}' means that the values 3 and 6 will not match.
Also note that the old and new level values will only be available
to search if the auditing policy has been set to 'DETAILED'.
- This example constrains the query to results for audit users root and sv and
produces output in a CSV file. It returns data for the Project and
Step classes and includes information for the class, type, target,
user, and timestamp:
- Windows
$ bfauditlog.bat -c Project,Step -f audit.class,
audit.type,audit.target,audit.user,audit.stamp
-a root,sv -l 10,5 -t CSV
- UNIX and Linux
$ bfauditlog.sh -c Project,Step -f audit.class,
audit.type,audit.target,audit.user,audit.stamp
-a root,sv -l 10,5 -t CSV
Classes
Classes are labels for audit log entries.
Use the -L option to list the classes available to you.
Fields
Fields represent information assigned
to each audit log record.
- audit.class: Project (string)
- audit.stamp: A timestamp (integer)
- audit.stamp.localized: A localized string representing the audit.stamp
integer value
- audit.type: Update (string)
- audit.target: UUID of the project (string)
- audit.user: UUID of the user who performed the update
Some fields in an audit log record will reflect their state
(o for old, n for new, x for extended) and their data type (s for
string, i for integer). Example:
soDescription: Old project description (string)
snDescription: New project description (string)
soSelectorUuid: Old selector's UUID (string)
snSelectorUuid: New selector's UUID (string)
ioRunLimit: Old run limit (integer)
inRunLimit: New run limit (integer)