| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| |
| <properties> |
| <title>Getting Started</title> |
| </properties> |
| |
| <body> |
| <section name="Getting Started with Log4j Audit"> |
| |
| <p>This guide provides an overview of how to define events to be audited, generate the Java interfaces for those |
| events and then use those interfaces to generate the audit events.</p> |
| |
| <a name="what_you_will_build"/> |
| <subsection name="What you will build"> |
| |
| <p>You will build a project that consist of two modules. One module generates a jar that contains the audit |
| catalog along with the Java interfaces that were created from the catalog. The second module generates a war |
| that provides the service endpoints to perform remote audit logging and manage dynamic catalogs. You will |
| install and use the catalog editor. Finally, you will also build a project that uses the audit event |
| interfaces and generates audit events.</p> |
| </subsection> |
| <a name="what_you_will_need"/> |
| <subsection name="What you will need"> |
| <ul> |
| <li>About 15 minutes</li> |
| <li>A favorite text editor or IDE</li> |
| <li>JDK 1.8 or later</li> |
| <li>Apache Maven 3.0+</li> |
| </ul> |
| </subsection> |
| <a name="how_to_complete"/> |
| <subsection name="How to complete this guide"> |
| |
| <p>Create a directory for this guide:<br /> |
| <pre><code> |
| cd ~ |
| mkdir log4j-audit-guide |
| cd log4j-audit-guide</code></pre></p> |
| |
| <p><a href="https://github.com/apache/logging-log4j-audit-sample/archive/master.zip">Download</a> and unzip the |
| sample source repository, or clone it using <a href="https://git-scm.com/downloads">Git</a>:<br /> |
| <pre><code> |
| git clone https://github.com/apache/logging-log4j-audit-sample</code></pre></p> |
| |
| <p>Change to the root directory of the project and build it using Maven:<br /> |
| <pre><code> |
| cd logging-log4j-audit-sample |
| mvn clean install</code></pre></p> |
| |
| <p>Three artifacts will have been created and installed into your local Maven repository: |
| <ol> |
| <li>org.apache.logging.log4j:audit-service-api:${Log4jAuditVersion}:jar</li> |
| <li>org.apache.logging.log4j:audit-service-war:${Log4jAuditVersion}:war</li> |
| <li>org.apache.logging.log4j:audit-service:${Log4jAuditVersion}:jar</li> |
| </ol></p> |
| |
| <p>The sample catalog can be found at audit-service-api/src/main/resources/catalog.json.</p> |
| </subsection> |
| <a name="BuildResults"/> |
| <subsection name="Inspect the build results"> |
| |
| <p>List the contents of audit-service-api/target/generated-sources/log4j-audit directory. The event interfaces |
| generated from the catalog will be located in this directory. As an example, the Class that represents |
| a transfer event looks like: |
| |
| <pre><code> |
| package org.apache.logging.log4j.audit.event; |
| |
| import java.math.BigDecimal; |
| import org.apache.logging.log4j.audit.AuditEvent; |
| import org.apache.logging.log4j.audit.annotation.Constraint; |
| import org.apache.logging.log4j.audit.annotation.MaxLength; |
| import org.apache.logging.log4j.audit.annotation.RequestContext; |
| import org.apache.logging.log4j.audit.annotation.Required; |
| |
| /** |
| * Transfer between accounts |
| * @author generated |
| */ |
| @MaxLength(32) |
| @RequestContext(key="hostName") |
| @RequestContext(key="loginId", required=true) |
| @RequestContext(key="ipAddress", constraints={@Constraint(constraintType="pattern", constraintValue="^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$")}) |
| @RequestContext(key="accountNumber", required=true) |
| @RequestContext(key="userId", required=true) |
| public interface Transfer extends AuditEvent { |
| |
| /** |
| * Amount : Amount to transfer |
| * @param amount Amount to transfer |
| */ |
| @Required |
| public void setAmount(BigDecimal amount); |
| |
| /** |
| * From Account Number : Source of funds |
| * @param fromAccount Source of funds |
| */ |
| @Required |
| public void setFromAccount(int fromAccount); |
| |
| /** |
| * To Account Number : Destination account |
| * @param toAccount Destination account |
| */ |
| @Required |
| @Constraint(constraintType="minValue", constraintValue="1") |
| public void setToAccount(int toAccount); |
| }</code></pre> |
| </p> |
| </subsection> |
| <a name="Run"/> |
| <subsection name="Run an application that performs auditing"> |
| <ol> |
| <li>Change to the sample-app diretory. |
| <pre><code> |
| cd sample-app</code></pre></li> |
| <li>Run the sample app and view the logs |
| <pre><code> |
| ./sample-app.sh |
| vi target/logs/audit.log</code></pre></li> |
| </ol> |
| <p>The output from the logs should look similar to: |
| <pre><code><![CDATA[ |
| <128>1 2018-06-09T19:54:26.018-07:00 RalphGoers-MacBook-Pro.local SampleApp 18815 Audit [RequestContext@18060 hostName="RalphGoers-MacBook-Pro.local" ipAddress="192.168.1.15" loginId="testuser"][login@18060] |
| <128>1 2018-06-09T19:54:26.021-07:00 RalphGoers-MacBook-Pro.local SampleApp 18815 Audit [RequestContext@18060 accountNumber="12345" hostName="RalphGoers-MacBook-Pro.local" ipAddress="192.168.1.15" loginId="testuser" userId="1111"][login@18060 completionStatus="Success"] |
| <128>1 2018-06-09T19:54:26.026-07:00 RalphGoers-MacBook-Pro.local SampleApp 18815 Audit [RequestContext@18060 accountNumber="12345" hostName="RalphGoers-MacBook-Pro.local" ipAddress="192.168.1.15" loginId="testuser" userId="1111"][deposit@18060 account="123456" amount="100"] |
| <128>1 2018-06-09T19:54:26.027-07:00 RalphGoers-MacBook-Pro.local SampleApp 18815 Audit [RequestContext@18060 accountNumber="12345" hostName="RalphGoers-MacBook-Pro.local" ipAddress="192.168.1.15" loginId="testuser" userId="1111"][deposit@18060 account="123456" amount="100" completionStatus="Success"]]]></code></pre> |
| Note that the formatting is completely controlled by the Log4j configuration. In this case, the RFC5424Layout was used.</p> |
| |
| <p>The application that generated these logs is: |
| <pre><code> |
| public class SampleApp { |
| |
| public static void main(String[] args) throws Exception { |
| String hostName = NetUtils.getLocalHostname(); |
| RequestContext.setHostName(hostName); |
| String inetAddress = InetAddress.getLocalHost().getHostAddress(); |
| RequestContext.setIpAddress(inetAddress); |
| RequestContext.setLoginId("testuser"); |
| Login login = LogEventFactory.getEvent(Login.class); |
| login.logEvent(); |
| String result = login("testuser"); |
| login.setCompletionStatus(result); |
| login.logEvent(); |
| Deposit deposit = LogEventFactory.getEvent(Deposit.class); |
| deposit.setAccount(123456); |
| deposit.setAmount(new BigDecimal(100.00)); |
| deposit.logEvent(); |
| result = deposit(deposit); |
| deposit.setCompletionStatus(result); |
| deposit.logEvent(); |
| RequestContext.clear(); |
| } |
| |
| private static String login(String user) { |
| RequestContext.setUserId("1111"); |
| RequestContext.setAccountNumber(12345L); |
| return "Success"; |
| } |
| |
| private static String deposit(Deposit deposit) { |
| return "Success"; |
| }</code></pre> |
| </p> |
| </subsection> |
| <a name="DeployAuditService"/> |
| <subsection name="Deploy the Audit Service WAR"> |
| <ol> |
| <li>Create a temporary directory and copy the audit service jar to it.<pre><code> |
| cd ~ |
| mkdir auditService |
| cd auditService |
| cp ~/log4j-audit-guide/logging-audit-sample/audit-service/target/audit-service-${Log4jAuditVersion}.jar .</code></pre></li> |
| <li>Use an editor to create a file named application.properties in the directory.</li> |
| <li>Copy the following lines into the file. The value for remoteRepoUrl should the Git repo where your |
| version of catalog.json should be stored. remoteRepoCatalogPath is the location within that Git repository |
| where the catalog.json file resides. gitPassPhrase is the pass phrase needed to access the repository |
| when SSH is used. gitUserName and gitPassPhrase are the credentials required to access the Git |
| repository when using HTTP or HTTPS. If the credentials or pass phrase are not provided typically you |
| will be able to view the catalog but not update it. |
| <pre><code> |
| remoteRepoUrl=https://github.com/apache/logging-log4j-audit-sample.git |
| remoteRepoCatalogPath=audit-service-api/src/main/resources/catalog.json |
| branch=<![CDATA[<branchname>]]> |
| gitUserName= |
| gitPassword= |
| gitPassPhrase=</code></pre></li> |
| <li>Start the application. |
| <pre><code> |
| java -jar audit-service-${Log4jAuditVersion}.jar</code></pre></li> |
| <li>Wait for the application to start.</li> |
| <li>Generate an audit event.<pre><code> |
| curl -i -X POST -H 'Content-Type: application/vnd.apache.logging.log4j.audit+json; version="1.0"' \ |
| http://localhost:8080/event/log -d '{ "eventName": "transfer", "requestContextMap": {"loginId": "rgoers", "corpAccountNumber": "12345", "ipAddress": "127.0.0.1"}, "properties": {"toAccount": "111111", "fromAccount": "222222", "amount": "100.00"}}' |
| </code></pre></li> |
| <li>The command should respond with <code>HTTP/1.1 200</code></li> |
| <li>View the audit log at logs/AuditService/audit.log. The audit event should be present in the file.</li> |
| </ol> |
| </subsection> |
| <a name="DeployAuditCatalog"/> |
| <subsection name="Run the Audit Catalog Editor"> |
| <ol> |
| <li><a href="http://www.apache.org/dist/logging/apache-log4j-audit-${Log4jAuditVersion}-bin.zip">Download</a> |
| the Log4j audit binary zip. |
| <pre><code> |
| wget http://www.apache.org/dist/logging/log4j-audit/${Log4jAuditVersion}/apache-log4j-audit-${Log4jAuditVersion}-bin.zip</code></pre></li> |
| <li>Unzip the contents. |
| <pre><code> |
| unzip apache-log4j-audit-${Log4jAuditVersion}-bin.zip</code></pre></li> |
| <li>Copy the Log4j Catalog Editor jar to any directory. |
| <pre><code> |
| mkdir catalogEditor |
| cd catalogEditor |
| cp apache-log4j-audit-${Log4jAuditVersion}-bin/log4j-catalog-editor-${Log4jAuditVersion}.jar .</code></pre></li> |
| <li>Use an editor to create a file named application.properties in this directory.</li> |
| <li>Copy the following lines into the file. The value for remoteRepoUrl should the Git repo where your |
| version of catalog.json should be stored. remoteRepoCatalogPath is the location within that Git repository |
| where the catalog.json file resides. gitPassPhrase is the pass phrase needed to access the repository |
| when SSH is used. gitUserName and gitPassPhrase are the credentials required to access the Git |
| repository when using HTTP or HTTPS. If the credentials or pass phrase are not provided typically you |
| will be able to view the catalog but not update it. |
| <pre><code> |
| remoteRepoUrl=https://github.com/apache/logging-log4j-audit-sample.git |
| remoteRepoCatalogPath=audit-service-api/src/main/resources/catalog.json |
| branch=<![CDATA[<branchname>]]> |
| gitUserName= |
| gitPassword= |
| gitPassPhrase=</code></pre></li> |
| <li>Start the application. |
| <pre><code>java -jar log4j-catalog-editor-${Log4jAuditVersion}.jar</code></pre></li> |
| </ol> |
| </subsection> |
| <a name="CatalogEditor"/> |
| <subsection name="Use the Catalog Editor"> |
| <ol> |
| <li>Navigate to the edit attributes screen at http://localhost:8080/attributes. The screen |
| should look like <br /><img src="images/attributes.png"/></li> |
| <li>Navigate to the edit events screen at http://localhost:8080/events. The screen should |
| look like <br /><img src="images/events.png"/></li> |
| </ol> |
| </subsection> |
| </section> |
| </body> |
| </document> |