Skip to content

Auditing Module

Jump to bottom
Nuno Oliveira edited this page Jan 14, 2016 · 37 revisions

Building

The auditing module is activated by the Maven profile auditing. To build geostore with auditing capabilities enabled enter the src/ directory and launch:

mvn clean install -Pauditing

To run the application from Maven with the auditing capabilities enabled you also need the profile:

mvn jetty:run -Pauditing

Configuring

An OS environment variable or a Java property variable of name GEOSTORE_AUDITING_CONF must exist and point to a valid configuration file.

For example as a java property variable:

-DGEOSTORE_AUDITING_CONF="/opt/geostore/conf/auditing.properties"

and as Linux environment variable:

export GEOSTORE_AUDITING_CONF="/opt/geostore/conf/auditing.properties"

If the variable above is not defined the auditing capabilities will be disabled. No exception will be throw, but an warning will appear in the application log file.

The configuration file must contain the following properties:

  • auditing.enable: allow to disable or enable the auditing capabilities
  • auditing.templates.directory: defines the directory that should contain the templates
  • auditing.output.directory: defines the directory that should contain the produced audit information files
  • auditing.templates.version: specifies the version of the current templates
  • auditing.max.requests.per.file: specifies the max number of request per file
  • auditing.output.files.extension: allow to define the file extension of the produced audit information files

All this properties are mandatory if one of this properties is missing an exception will be throw specifying which property is missing.

Follow the example of a configuration file:

auditing.enable=true
auditing.templates.directory=/opt/geostore/conf/templates
auditing.output.directory=/var/geostore/auditing
auditing.templates.version=1
auditing.max.requests.per.file=100
auditing.output.files.extension=xml

Templates

The auditing output format can be configured using Apache FreeMarker template language. Three templates are required header.ftl, body.ftl and footer.ftl and should be present on the templates directory.

Those are the variables (auditing information related to an executed request) that will be available and can be used in the templates:

  • httpMethod: the HTTP method of the request
  • path: the full path of a request, for example users/user/100
  • basePath: the base path of the request, for example users
  • queryString: the query string of the request
  • remoteAddr: the IP address of the client
  • remoteHost: the host name of the client
  • remoteUser: full client login information, for example User[id=2, name=admin, group=[UserGroup[id=1, groupName=everyone,admin]], role=ADMIN]
  • userName: the user name of the client, for example admin
  • userRole: the role name of the user, for example ADMIN
  • userGroups: the groups of the client, for example everyone,admin
  • host: the name of the host who receive the request
  • bodyAsString: the body of the request as a string
  • failed: true if the request execution produced an exception
  • errorMessage: if the request execution produced an exception this will contain the exception description
  • responseStatus: the HTTP code of the response
  • responseContentType: the content type of the response, for example text/plain
  • responseLength: the length of the response in bytes
  • startTime: the request start execution time in milliseconds
  • endTime: the request end execution time in milliseconds
  • totalTime: the request total execution time in milliseconds

Follow examples of the three templates that contain all the possible values.

Header

<?xml version="1.0" encoding="UTF-8" ?>
<Requests>

Body

<#escape x as x?xml>
<Request id="${id!""}">
   <HttpMethod>${httpMethod!""}</HttpMethod>
   <Path>${path!""}</Path>
   <BasePath>${basePath!""}</BasePath>
   <QueryString>${queryString!""}</QueryString>
   <RemoteAddr>${remoteAddr!""}</RemoteAddr>
   <RemoteHost>${remoteHost!""}</RemoteHost>
   <RemoteUser>${remoteUser!""}</RemoteUser>
   <UserName>${userName!""}</UserName>
   <UserRole>${userRole!""}</UserRole>
   <UserGroups>${userGroups!""}</UserGroups>
   <Host>${host}</Host>
   <#if bodyAsString??>
   <Body>${bodyAsString}</Body>
   </#if>
   <#if failed??>
   <Failed>true</Failed>
   <ErrorMessage>${errorMessage!""}</ErrorMessage>
   <#else>
   <Failed>false</Failed>
   </#if>
   <ResponseStatus>${responseStatus!""}</ResponseStatus>
   <ResponseContentType>${responseContentType!""}</ResponseContentType>
   <ResponseLength>${responseLength!""}</ResponseLength>
   <StartTime>${(startTime?number?number_to_datetime?iso_utc_ms)!""}</StartTime>
   <EndTime>${(endTime?number?number_to_datetime?iso_utc_ms)!""}</EndTime>
   <TotalTime>${totalTime!""}</TotalTime>
</Request>
</#escape>

Footer

</Requests>

Output files

The produced files will be wrote to the configured output directory. The current output file name will be audit-geostore.extension.The rolled output files names will follow the pattern audit-geostore-yyyymmdd-index.extension. Files will be automatically rolled at the end of each day or when the max number of requests per file is reached. When the application starts if an output file exists it will be automatically rolled.

Follow an example of the files than can exists in the output directory:

audit-geostore-20160113-1.xml
audit-geostore-20160113-2.xml
audit-geostore-20160114-1.xml
audit-geostore.xml
Clone this wiki locally