ibexa

Path

ez publish / technical manual / 4.6 / features / audit trailing


Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

  • Audit trailing

    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 (user name 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

    content-hide

    Hide/unhide a content node

    • Node ID
    • Object ID
    • Object Name
    • Timestamp
    • Comment

    content_hide.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 "var/log/audit".

    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=var/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 "var/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 (user name 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:

    1. 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
      
    2. 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.
    

    Julia Shymova (14/09/2010 12:33 pm)

    Geir Arne Waaler (10/06/2011 12:02 pm)


    Comments

    • new audit function

      New audit function - You say:
      <<
      In the PHP code which defines the operation that should be logged, you can do something like this:
      [..............]
      >>

      I would like to have audit's logs concerning the view operations done by users .
      Which is the php page I should modify and where is it?
      Can you write an example audit function to reach this pourpose ?

      Thanks