The Consent2Share application uses Logback Audit as a centralized audit repository in backend services, particularly in the Access Control Service components. Logback Audit can be configured to use relational databases for persistence.
Consent2Share currently uses a fork of the Logback Audit project. This fork is fundamentally the same as the original Logback Audit implementation. However, it has some dependency version updates and column size modifications in the database tables. It also includes an SQL script for database creation and a generated Logback Audit Server project that can be built and deployed on an application server such as Apache Tomcat.
- Oracle Java JDK 8 with Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy
- Docker Engine (for building a Docker image from the project)
This is a Maven project and requires Apache Maven 3.3.3 or greater to build it. It is recommended to use the Maven Wrapper scripts provided with this project. Maven Wrapper requires internet connection to download Maven and project dependencies for the very first build.
To build the project, navigate to the folder that contains the parent pom.xml
file using terminal/command line.
- To build a JAR:
- For Windows, run
mvnw.cmd clean install & cd audit-server-generator\logback-audit-server & ..\..\mvnw.cmd clean install & cd ..\..
- For *nix systems, run
mvnw clean install; cd audit-server-generator/logback-audit-server/; ../../mvnw clean install; cd ../..
- For Windows, run
- To build a Docker Image (this will create an image with
bhits/logback-audit-server:latest
tag):- For Windows, run
mvnw.cmd clean install & cd audit-server-generator\logback-audit-server & ..\..\mvnw.cmd clean package docker:build & cd ..\..
- For *nix systems, run
mvnw clean install; cd audit-server-generator/logback-audit-server/; ../../mvnw clean package docker:build; cd ../..
- For Windows, run
NOTE: The logback-audit-server
provided in this repository depends on the forked versions of Logback artifacts. Therefore, the entire project is required to be built as given in the commands above in order to build the deployable logback-audit-server
project.
This API uses MySQL for persistence. It requires having a database user account with Object Rights to a schema with the default name audit
. Please see Configure section for details about configuring the data source.
Currently, the Logback Audit Server does not support a database migration process, so the schema must be created manually. An SQL file is provided with this project to create the schema.
This API requires a separate application server to run it. Apache Tomcat 8 is the recommended application server to run this API. This API listens on a port that is different from the application server port to communicate with other audit clients. Please see the Configure section for details of configuring the port number to listen to.
For easy deployment:
- Find the
war
file located inaudit-server-generator/logback-audit-server/target
folder after building the project. - Copy the
war
file to Tomcat'swebapps
folder. - Configure Tomcat for Logback Audit Server properties (See Configure section).
- Start up Tomcat.
Please refer to Tomcat Web Application Deployment documentation for more details about Tomcat deployment.
This API depends on certain environment variables to be available in Tomcat. Please navigate to $TOMCAT_HOME/conf/catalina.properties
and add the following variables:
-
audit.datasource.url
: The URL for the database connection (Example:jdbc:mysql://localhost:3306/audit?autoReconnect=true
) -
audit.datasource.username
: The username for the database connection (Example:root
) -
audit.datasource.password
: The password for the database connection (Example:admin
) -
audit.listen.port
: The port number that the audit server will listen to and communicate with audit clients. This port number is NOT the same as the application server port number. (Example:9630
) -
C2S_PROPS
: This should be the location of root directory for externalized configuration. IfC2S_PROPS=/c2s-config
, the Logback Audit Server will try to load:/c2s-config/logback-audit/config-template/logback-audit-config-logback_included.xml
: External logback file that will be included into the application logback configuration. This file can be used to configure logging details including where the log files will be stored and logging level. Please see the sample included logback file.
-
AUTO_SCAN
: This variable is used to configure logback auto scan feature, so the expected value for this property istrue
orfalse
. IfAUTO_SCAN=true
, logback will scan for changes in the included external configuration file and reconfigure itself when it detects a change. -
SCAN_PERIOD
: This variable is used to configure logback auto scan period configuration. IfSCAN_PERIOD=30 seconds
, logback will scan the external file for changes for every 30 seconds.
docker run -d --link=audit-service-db.c2s.com -e "CATALINA_OPTS=-Daudit.datasource.url=jdbc:mysql://audit-service-db.c2s.com:3306/audit?autoReconnect=true -Daudit.datasource.username=root -Daudit.datasource.password=admin -Daudit.listen.port=9630 -DC2S_PROPS=/java/C2S_PROPS -DAUTO_SCAN=true -DSCAN_PERIOD='60 seconds'" -v "/path/to/config/root/on/dockerhost:/java/C2S_PROPS" bhits/logback-audit-server:latest
- In a
docker-compose.yml
, this can be provided as:
version: '2'
services:
...
logback-audit-server.c2s.com:
image: "bhits/logback-audit-server:latest"
environment:
CATALINA_OPTS: "-Daudit.datasource.url=jdbc:mysql://audit-service-db.c2s.com:3306/audit?autoReconnect=true -Daudit.datasource.username=root -Daudit.datasource.password=admin -Daudit.listen.port=9630 -DC2S_PROPS=/java/C2S_PROPS -DAUTO_SCAN=true -DSCAN_PERIOD='60 seconds'"
volumes:
- /path/to/config/root/on/dockerhost:/java/C2S_PROPS
...
If you have any questions, comments, or concerns please see Consent2Share project site.
Please use BHITS Logback Audit GitHub Issues page to report the issues related to Consent2Share modifications and Logback Audit GitHub Issues page to report the issues related to the core Logback Audit framework.
The Logback Audit license can be found at http://audit.qos.ch/license.html.
- Added Maven Enforcer Plugin configuration with a list of banned dependencies to the generated
logback-audit-server
project. - Added dependency management to the generated
logback-audit-server
project to resolve dependency convergence issues. - Upgraded
logback
version to1.2.3
- Updated this
README.md
file anddocs/docker-image-desc.md
file.
- Upgraded logback-core dependency and logback-classic dependency from
1.0.9
to1.1.7
. - Updated this
README.md
file anddocs/docker-image-desc.md
file.
- Prepared this
README.md
file as a general technical documentation. - Prepared
docs/docker-image-desc.md
file for DockerHub image description. - Released an unofficial version
0.6.1
containing Consent2Share modifications. - Updated
.gitignore
file and created a.gitattributes
file. - Modified the column sizes in hibernate mappings and adjusted the existing unit test accordingly.
- Generated a
logback-audit-server
project usingaudit-server-generator
that supports:- Externalized hibernate configuration using environment variables,
- JDBC connection and statement pooling using
c3p0
library, - Externalized logging configuration with an included
logback.xml
configuration file, - Externalized port number configuration that the audit server listens to,
- Upgraded dependency versions for
logback
andc3p0
, maven-compiler-plugin
configuration with target Java version as 1.8.
- Added additional code in
ServletContextListener.contextDestroyed
hook to wait forc3p0 Resource Destroyer
thread to finish and also stopLoggerContext
to prevent the application hanging on shutdown when there is an issue with the logger. - Added Maven Wrapper support.
- Added a SQL Script for the
audit
schema.