CAST AIC Portal is unsupported. We encourage you to switch to AIP Console.


On this page:


Target audience:

CAST AI Administrators


Summary: this page explains how to enable and configure the Audit Trail feature in the CAST AIC Portal to log successful user logins, failed logins, logouts, web application startup/stop etc.

Introduction

By default, the CAST AIC Portal does not log significant user events. If you would like to see this information in a log file for security reasons, then you can enable the Audit Trail feature. The Audit Trail feature will log all of the following events:

Enabling the Audit Trail feature

To enable the Audit Trail feature, you need to modify the following file with a text editor:

%CATALINA_HOME%\webapps\CAST-AICP\WEB-INF\log4j2.xml
<Property name="auditLevel">OFF</Property>
<Property name="auditLevel">ALL</Property>

Consulting the Audit Trail log file

%CATALINA_HOME%\webapps\CAST-AICP\audit\audit.log
[ DATE YYYY-MM-DD HH:MM:SS,MS | USER_HOST | USER_NAME | LEVEL | EVENT/MESSAGE ]
2015-04-10 14:58:47,426 | 10.0.1.50 | James | INFO | Application startup
2015-04-10 14:58:59,945 | 10.0.1.52 | cast | INFO | Login successful
2015-04-10 16:52:13,335 | 10.0.1.52 | cast | INFO | Login successful
2015-04-10 16:52:29,406 | 10.0.1.52 | cast | INFO | Application created [guid: c18ca3b9-ea4d-4ade-842b-b051cb5e8e56, name: MEUDON]
2015-04-10 16:53:00,188 | 10.0.1.52 | cast | INFO | User Logout
2015-04-10 16:53:42,660 | 10.0.1.50 | James | INFO | Application shutdown
2015-04-10 16:53:46,459 | 10.0.1.50 | James | INFO | Application startup
2015-04-10 16:54:07,000 | 10.0.1.52 | cast | WARN | Login failed
2015-04-10 16:54:09,882 | 10.0.1.52 | cast | INFO | Login successful
2015-04-10 16:54:12,629 | 10.0.1.52 | cast | INFO | User Logout

Changing the log file storage location

Audit Trail log files are created and archived by default in the CAST AIC Portal application deployment folder, under the audit folder. To change this location, you need to modify the following file with a text editor:

%CATALINA_HOME%\webapps\CAST-AICP\WEB-INF\log4j2.xml

To change the location of the log folder within the limits of the web application:

<Property name="auditPath">$${web:rootDir}/audit</Property>
<Property name="logPath">$${web:rootDir}/test</Property>
%CATALINA_HOME%\webapps\CAST-AICP\test

Changing the log file rotation strategy

The Audit Trail log file has a default rotation strategy as follows:

This strategy can be modified as follows:

%CATALINA_HOME%\webapps\CAST-AICP\WEB-INF\log4j2.xml
filePattern="${auditPath}/audit-%d{yyyy-MM}.log.zip"

Letter

Date or Time Component

Examples

G

Era designator

AD

y

Year

199696

M

Month in year

JulyJul07

w

Week in year

27

W

Week in month

2

D

Day in year

189

d

Day in month

10

F

Day of week in month

2

E

Day in week

TuesdayTue

a

Am/pm marker

PM

H

Hour in day (0-23)

0

k

Hour in day (1-24)

24

K

Hour in am/pm (0-11)

0

h

Hour in am/pm (1-12)

12

m

Minute in hour

30

s

Second in minute

55

S

Millisecond

978

z

General Time zone

Pacific Standard TimePSTGMT-08:00

Z

RFC 822 Time zone

-0800


Note that:

  • Plain text can be quoted using single quotes (') to avoid interpretation, like for example: %d{yyyy-'w'w} that generates the output 2015-w11

  • The output generated by the date format pattern is dependent on the locale of the machine hosting the web application server

Size based rotation policy

A supplementary Audit Trail log rotation by size can be achieved by uncommenting the SizeBasedTriggeringPolicy available in the Policies list, as follows:

<!-- Audit log rotation policies -->
<Policies>
...
    <!-- <SizeBasedTriggeringPolicy size="10 MB"/> -->
</Policies>
...

The size based policy causes a rotation once the file has reached the specified size. The size can be specified in bytes, with the suffix KB, MB or GB, for example “10 MB”.

Log file rotation examples

The time based policy and the size based policies can be used together. The following section provides some examples of how to modify the rotation policy:

Changing the user event message output format

As described previously, messages relating to user events will be displayed in the log file in the following format:

[ DATE YYYY-MM-DD HH:MM:SS,MS | USER_HOST | USER_NAME | LEVEL | EVENT/MESSAGE ]

This output format is governed by the following line in the log4j2.xml file:

<PatternLayout pattern="%date{DEFAULT} | %mdc{audittrail.remotehost} | %mdc{audittrail.username} | %level | %message%n" charset="UTF-8"/>

Where the following is true:

It is possible to modify this output by changing the pattern layout. Please refer to the following Log4j2 documentation page: http://logging.apache.org/log4j/2.0/manual/layouts.html#PatternLayout for more information.

Changing the message output

All Audit Trail messages that are output to the log file can be customized if required. Messages are stored in an XML properties file in the following location:

%CATALINA_HOME%\webapps\CAST-AICP\WEB-INF\classes\audittrail

Two files are provided by default: one to provide messages in English, the other in French - see the section Internationalization below for more information about how these two files work.

If you wish to customise the output message, you can do so by editing the XML file with a text editor.  All output messages are configured using the <entry> tag, for example the message that is output when a user login fails is configured in the following line - the message is "Login failed":

<entry key="USER_LOGIN_FAILED">Login failed</entry>

To change this, simply update the text between the <entry> tags:

<entry key="USER_LOGIN_FAILED">A user login failed</entry>

Use of variables

Some output messages contain variables, for example:

<entry key="CREATE_DOMAIN">Created application domain %2$s [guid: %1$s]</entry>

These variables are used to display specific values. In the example above, the message would look something like the following, where the domain name is TEST and its GUID is 50037cba-12ef-43f1-8514-b16660a3b492:

Created application domain TEST [guid: 50037cba-12ef-43f1-8514-b16660a3b492]

A full run down of all the variables used in messages is provided below:

Entry KeyMessageVariable
CREATE_DOMAINCreated application domain %2$s [guid: %1$s]%1$s - application domain guid
%2$s - application domain name
UPDATE_DOMAIN_NAMEUpdated name of application domain %2$s [guid: %1$s] to %3$s%1$s - application domain guid
%2$s - old application domain name
%3$s - new application domain name
GRANT_DELIVERY_MANAGERGranted delivery manager rights to %3$s on application domain %2$s [guid: %1$s]%1$s - application domain guid
%2$s - application domain name
%3$s - delivery manager name
DENY_DELIVERY_MANAGERDenied delivery manager rights to %3$s on application domain %2$s [guid: %1$s]%1$s - application domain guid
%2$s - application domain name
%3$s - delivery manager name
DELETE_DOMAINDeleted application domain %2$s [guid: %1$s]%1$s - application domain guid
%2$s - application domain name
CREATE_APPLICATIONCreated application %2$s [guid: %1$s] in application domain %4$s [guid: %3$s]%1$s - application guid
%2$s - application name
%3$s - application domain guid
%4$s - application domain name
UPDATE_APPLICATION_NAMEUpdated name of application %2$s [guid: %1$s] to %3$s%1$s - application guid
%2$s - old application name
%3$s - new application name
MOVE_APPLICATIONMoved application %2$s [guid: %1$s] from domain %4$s [guid: %3$s] to domain %6$s [guid: %5$s]%1$s - application guid
%2$s - application name
%3$s - old application domain guid
%4$s - old application domain name
%5$s - new application domain guid
%6$s - new application domain name
DELETE_APPLICATIONDeleted application %2$s [guid: %1$s]%1$s - application guid
%2$s - application name
APPLICATION_VERSION_DELIVERYDelivered version %4$s [guid: %3$s], application %2$s [guid: %1$s]%1$s - application guid
%2$s - application name
%3$s - version guid
%4$s - version name
APPLICATION_PACKAGE_DELIVERYDelivered package %6$s [guid: %5$s], version %4$s [guid: %3$s] in application %2$s [guid: %1$s]%1$s - application guid
%2$s - application name
%3$s - version guid
%4$s - version name
%5$s - package guid
%6$s - package name
APPLICATION_VERSION_DELIVERY_CLOSEClosed version %4$s [guid: %3$s], application %2$s [guid: %1$s]%1$s - application guid
%2$s - application name
%3$s - version guid
%4$s - version name
REFRESH_APPLICATIONRefreshed application %2$s [guid: %1$s]%1$s - application guid
%2$s - application name
REFRESH_VERSIONRefreshed version %4$s [guid: %3$s], application %2$s [guid: %1$s]%1$s - application guid
%2$s - application name
%3$s - version guid
%4$s - version name
REFRESH_PACKAGERefreshed package %6$s [guid: %5$s], version %4$s [guid: %3$s], application %2$s [guid: %1$s]%1$s - application guid
%2$s - application name
%3$s - version guid
%4$s - version name
%5$s - package guid
%6$s - package name

Removing variables

If you do not want the real names of Applications, Domains, Delivery Managers, Versions and Packages to appear in the Audit Trail ouput log, then you can simply remove them. For example to remove the name of the Domain from the following message simply change it from:

<entry key="GRANT_DELIVERY_MANAGER">Granted delivery manager rights to %3$s on application domain %2$s [guid: %1$s]</entry>

to:

<entry key="GRANT_DELIVERY_MANAGER">Granted delivery manager rights to %3$s on application domain [guid: %1$s]</entry>

Internationalization

Audit trail messages are by default internationalized and come in two translations: English (default language if the machine language is not supported) and French.  The translations into French are stored in XML properties file types under:

%CATALINA_HOME%\webapps\CAST-AICP\WEB-INF\classes\audittrail

If desired, additional language translation files can be added under this path.