Audit trailing

This part of the 4.x documentation is for eZ Publish 4.0, only reference section is common for all eZ Publish 4.x versions as well as eZ Publish 5.x "LegacyStack", please select the version you are using for the most up to date documentation!

It is possible to automatically generate audit logs based on what the users are doing with the system. This feature can be useful for big sites with many administrators and editors where information about various operations should be logged and stored. For example, auditing makes it possible to find out which user that removed content, from which IP address the request came from and so on.

The system provides a set of built-in audit functions that make it possible to generate audit logs for different types of activities. At minimum, for every operation, the system logs the following information:

When it happened (time-stamp)
Where the request came from (IP address)
Which user that did it (username and ID number)

Note that most audit functions provide additional information. The following example shows how a record in one of the log files look like after a node has been moved.

[ May 23 2007 14:47:58 ] [127.0.0.1] [editor:16]
Node ID: 124
Old parent node ID: 2
New parent node ID: 59
Object ID: 114
Content Name: Folder
Comment: Moved the node to the given node: eZContentObjectTreeNode::move()

The following table shows the available built-in audit functions along with when they are triggered, what kind of information that is actually logged and the default log file where the information is stored.

Audit function	Activity	Logged information	Default log file
user-login	Successful login attempts	Timestamp IP address User (name:ID)	login.log
user-failed-login	Failed login attempts	Timestamp IP address User (name:ID)	failed_login.log
content-move	Location change of content	Timestamp IP address User (name:ID) Old parent node ID New parent node ID Object ID Object name Comment	content_move.log
content-delete	Removal of content	Timestamp IP address User (name:ID) Node ID Object ID Object name Comment	content_delete.log
role-change	Role and policy changes	Timestamp IP address User (name:ID) Role ID Role name Comment	role_change.log
role-assign	Role assignment to users and groups	Timestamp IP address User (name:ID) Role ID Role name Object name Comment	role_assign.log
section-assign	Section assignments	Timestamp IP address User (name:ID) Section ID Section name Node ID Object ID Object name Comment	section_assign.log
order-delete	Removal of webshop orders	Timestamp IP address User (name:ID) Order ID Comment	order_delete.log

Configuration

By default, the auditing feature is turned off. In order to use audit trailing on your site, enable the "Audit" setting located in the "[AuditSettings]" section of an override for the "audit.ini" configuration file. Using the "AuditFileNames" configuration array located in the same file, you can specify which types of activities that should be logged (which audit functions that should be used) and to which files they should be logged. The audit function names must be the array keys and the log file names should be the values. Note that the default configuration logs everything to a collection of files (refer to the table in the previous section for details).

The "LogDir" setting can be used to specify where the audit log files should be stored. The default directory is "log/audit". This path refers tp VarDir setting, defined in site.ini.

Example

Let's say that you wish to audit successful log-in attempts and changes to roles and policies while ignoring all other activities. Start by creating an override for "audit.ini" and making sure that it contains the following lines:

[AuditSettings]
Audit=enabled
LogDir=log/my_audit
AuditFileNames[]
AuditFileNames[user-login]=login.log
AuditFileNames[role-change]=role_change.log

Information about successful log-in attempts will end up in the "login.log" file. Information about role and policy changes will be put in the "role_change.log" file. Both files will be located in the "<VarDir>/log/my_audit" directory. Each record in these files will contain a time-stamp pointing to the exact date and time when an operation was performed, which user that is associated with it (username and ID number) and which IP address the request came from. Records related to role and policy changes will have additional information.

Creating new audit functions

This section provides tips for PHP developers who want to create their own audit functions.

Sometimes you may need to create a new audit function, i.e. to make the system log information about a specific operation to a particular audit log file. For example, if you wish to create a new audit function called "my-new-audit" and store information about operations to a file called "info.log", you can do the following:

Make sure that the "Audit" setting located in the [AuditSettings] section of an override for "audit.ini" is enabled and add a new element to the "AuditFileNames" configuration array by inserting the following line:
```
AuditFileNames[my-new-audit]=info.log
```
In the PHP code which defines the operation that should be logged, you can do something like this:
```
eZAudit::writeAudit( 'my-new-audit', array( 'User id' => $userID,
       'Comment' => 'The operation XYZ was performed.' ) );
```
Elements like 'Name of something' => <valueOfSomething> define which information that should be written to the "info.log" file when the operation is performed.

For example, a record in the log file can look like this:

[ May 23 2007 14:44:04 ] [127.0.0.1] [anonymous:10]
User id: 10
Comment: The operation XYZ was performed.