Welcome to Tigase AuditLog component guide

1. Overview

Tigase Audit Log component is an implementation of Audit Log pattern functionality to log important events in a system such as:

  • login events (success and failure)

  • message exchanges

  • retrieval of VCards

  • calls (Jingle)

By default log entries are stored in auditlog file in form of a JSON objects.

It is possible to enable searchable storage which will use MySQL table to store auditlog entries and will make them accessible for administrators via AdminUI. For more information about searchable storage please check Configuration of searchable repository

Following informations will be stored for logged event (if data was available for particular event):

Name of property Additional info

from

packet source

to

packet destination

type

event type - possible values are:

  • auth.success

  • auth.failure

  • auth.disconnected

  • presence

  • subscribe

  • message

  • vcard

  • jingle

when

timestamp of an event

allowed

true/false value which informs if this log entry was expected

serverName

name of cluster node which generated this event

errorCode

error code

errorMessage

error message

callId

sid of a Jingle call or a thread of a message

internalError

true if error was caused by internal error

errorCondition

added additionally which contains also info about policyName

stanzaId

id of logged stanza

connection

id of user connection if available - points to particular connection from particular device

2. Configuration

2.1. Enabling feature

To enable AuditLog feature you need to enable AuditLogComponent component in etc/config.tdsl file and set used auditlog repository implementations. To do this you need to set name of component and class implementing this component, ie.

'audit-log' () {
    memoryRepository () {}
    slf4jRepository () {}
}

It is also required to enable AuditLogProcessor. To do so you need to enable audit-log processor in sess-man section:

'sess-man' () {
    'audit-log' () {}
}

2.2. Configuration of auditlog file

AuditLog file is created and filled with events by Logback logging framework. To configure log file location, size you need to modify file etc/logback.xml which contains following data:

<configuration scan="true">
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
                <file>logs/auditlogs/auditlog.log</file>
                <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <!-- rollover hourly -->
                        <fileNamePattern>logs/auditlogs/auditlog-%d{yyyy-MM-dd_HH}.%i.log.gz</fileNamePattern>
                        <timeBasedFileNamingAndTriggeringPolicy
                        class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                        <!-- or whenever the file size reaches 50MB -->
                                <maxFileSize>50MB</maxFileSize>
                        </timeBasedFileNamingAndTriggeringPolicy>
                        <!-- No Limit -->
                        <maxHistory>0</maxHistory>
                </rollingPolicy>
                <encoder>
                        <charset>UTF-8</charset>
                        <pattern>%msg%n</pattern>
                </encoder>
        </appender>

        <logger name="tigase.auditlog" level="trace"/>

        <root level="warn">
                <appender-ref ref="FILE"/>
        </root>
</configuration>

In this sample config it is set:

  • a template for a auditlog file name logs/auditlogs/auditlog-%d{yyyy-MM-dd_HH}.%i.log.gz

  • rolling logs to new files every 50MB and every day

2.3. Configuration of searchable repository

It is possible to configure AuditLog component to store events in MySQL database. To do that you need to enable AuditLog feature as described above and you need to enable searchableRepository in AuditLog component configuration.

'audit-log' () {
    searchableRepository () {}
}

This will use database configured as a default data source of Tigase XMPP Server. If want to use different data source, you need to configure this new data source (ie. auditlogDataSource) and configure searchableRepository to use it:

dataSource {
    ...
    auditlogDataSource () {
        uri = 'jdbc:mysql://..'
    }
    ...
}

'audit-log' () {
    searchableRepository () {
        'data-source' = 'auditlogDataSource'
    }
}

After that you will be able to browse AuditLog entries in Admin UI of Tigase XMPP Server within Auditlog section.

Warning
 Remember that after enabling searchableRepository you need to load database schema for AuditLog component. To do that just execute upgrade-schema task of Tigase XMPP Server after configuration of AuditLog is done.

2.4. Using AuditLog component under different component name than audit-log

To do that you need to define AuditLog component with a different name, ie. auditLog.

'auditLog' (class: tigase.auditlog.AuditLogComponent) {}

Then inform AuditLog processor of name of AuditLog component. Entry similar to one below will need to be added to etc/config.tdsl file:

'sess-man' () {
    'audit-log' () {
        'component-jid' = 'auditLog@example.com'
    }
}
Note
 In above example it is assumed that your server hostname is example.com. You will need to replace example.com with the real hostname of your server.

2.5. Logging packets not exchanged between client and server

By default this feature is enabled. To disable it you need to add following line to etc/config.tdsl file:

'sess-man' () {
    'audit-log' () {
        'only-user-packets' = false
    }
}

2.6. Logging only packets received by user

To enable this feature you need to add following line to etc/config.tdsl file:

'sess-man' () {
    'audit-log' () {
        'only-from-user-connection' = true
    }
}

3. Protocol

For communication between processor detecting events and component responsible for logging events special extension of XMPP protocol is used with namespace http://tigase.org/protocol/auditlog which will be passed added as xmlns attribute to action elements of stanza requests. All stanzas will be iq stanzas.

3.1. Entry

Entry is an xml element which contains other elements as properties with values. It is basic element logged by component to audit log.

<entry>
  <whenOccurred>2015-01-15T14:54:04Z</whenOccurred>
  <srcAddress>user1@example.com</srcAddress>
  <dstAddress>user2@example.com</dstAddress>
  ...
</entry>

In above example we have passed:

whenOccurred

property which contains timestamp of this even,

srcAddress

containing source jid of stanza which triggered event,

dstAddress

containing destination jid of stanza which triggered event.

3.2. Appending entries to log

To append entry to log component which would append entry processor is sending following stanza with proper values set:

<iq type="set" id="auditlog-1">
  <append xmlns="http://tigase.org/protocol/auditlog">
    <entry>
      <whenOccurred>2015-01-15T14:54:04Z</whenOccurred>
      <srcAddress>user1@example.com</srcAddress>
      <dstAddress>user2@example.com</dstAddress>
      ...
    </entry>
    ...
  </append>
</iq>

This would notify receiver to append (as append is name of action element) entry or entries which are described by inner elements of action element.

3.3. Retrieval of entries

In some cases it will be possible to retrieve entries sent to AuditLog component using XMPP. To retrieve 2 oldest entries (oldest entries from cache) following iq stanza of get type should be sent to AuditLog component:

<iq type="get" id="auditlog-2" from="admin@example.com/res-1" to="auditlog@example.com">
  <retrieve xmlns="http://tigase.org/protocol/auditlog" offset="0" limit="2"/>
</iq>

AuditLog component will respond with stanza in following format:

<iq type="result" id="auditlog-2" from="auditlog@example.com" to="admin@example.com/res-1">
  <entries xmlns="http://tigase.org/protocol/auditlog" offset="0" limit="2">
    <entry>
      <whenOccurred>2015-01-15T14:54:04Z</whenOccurred>
      <srcAddress>user1@example.com</srcAddress>
      <dstAddress>user2@example.com</dstAddress>
      ...
    </entry>
    ...
  </entries>
</iq>

in which entries element contains requested entries as subelements in entry XML format.

If there was an error and entries could not be returned due to component not containing cached entries following result will be sent:

<iq type="error" id="auditlog-2" from="auditlog@example.com" to="admin@example.com/res-1">
  <error type="cancel">
    <item-not-found xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
  </error>
</iq>

Other types of errors specified by XMPP protocol might also be returned by server if during processing of request error occurred.

4. Web-based user interface

Tigase AuditLog component provides and easy to use web-based user interface which is accessible as a part of Tigase XMPP AdminUI. This UI is by default available at port 8080 on the server on which Tigase XMPP Server is running at path /admin/. If your are running Tigase XMPP Server on localhost it should be available at http://localhost:8080/admin/.

Note
 Despite the fact that AdminUI has the admin part in its name, any Tigase XMPP Server user can access this service, however UI will be limited only to features available for particular user.
Warning
 This AdminUI is only available if Tigase AuditLog component uses MySQL backend for storage of audit log entries.

4.1. Overview

When you open AdminUI and click on the AuditLog button located at the top left side of the web page, it will expand and present you with actions available in this section.

ListOfActions

4.2. Listing connected users

If you wishes to display list of connected users for a domain (with additional filtering), you should click on Get Connected Users. It will present you with a following form, allowing you to select domain. In the Filter field, you may a text which should be part of the displayed users jid. There is no pattern matching - you only enter part of the jid which you are looking for. This will narrow your search and reduce number of displayed entries.

GetConnectedUsersForm

When you submit this form, you will be presented with a results in the form similar to the one visible on this screenshot.

GetConnectedUsersResult

4.3. Listing disconnected users

If you wishes to display list of disconnected users for a domain (with additional filtering), you should click on Get Disconnected Users. It will present you with a following form, allowing you to select domain. In the Filter field, you may a text which should be part of the displayed users jid. There is no pattern matching - you only enter part of the jid which you are looking for. This will narrow your search and reduce number of displayed entries.

GetDisconnectedUsersForm

When you submit this form, you will be presented with a results in the form similar to the one visible on this screenshot.

GetDisconnectedUsersResult

4.4. Displaying connections history of a user

If you wishes to display a connections history for a particular user, you should click on Get Connections History. It will present you with a following form, allowing you to enter jid of a user which you want to retrieve connections history for. From and To fields will allow you to specify period for which entries should be displayed. Each of those fields consists of 3 input fields for setting date, time and selecting time zone.

GetConnectionsHistoryForm

When you submit a form and user is connected you will get result similar to the following one:

GetConnectionsHistoryResultConnected

And if user is not connected then result will be similar to the following screenshot:

GetConnectionsHistoryResultDisconnected