| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| 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. |
| --> |
| <!-- Generated by Apache Maven Doxia at 2018-12-02 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Log4j_Audit – Getting Started - Apache Log4j Audit</title> |
| <link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" /> |
| <link rel="stylesheet" href="./css/site.css" type="text/css" /> |
| <script type="text/javascript" src="./js/jquery.min.js"></script> |
| <script type="text/javascript" src="./js/bootstrap.min.js"></script> |
| <script type="text/javascript" src="./js/prettify.min.js"></script> |
| <script type="text/javascript" src="./js/site.js"></script> |
| <meta name="Date-Revision-yyyymmdd" content="20181202" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| </head> |
| <body class="composite"> |
| <a href="http://www.apache.org/events/current-event.html"> |
| <img class=logo-left src="http://www.apache.org/events/current-event-234x60.png"/> |
| </a> |
| <img class="logo-right" src="./images/logo.png" alt="Apache log4j logo" /> |
| <a href="https://logging.apache.org/"> |
| <img class="logo-center" src="./images/ls-logo.jpg" alt="Apache logging services logo" /> |
| </a> |
| <div class="clear"></div> |
| |
| <div class="navbar"> |
| <div class="navbar-inner"> |
| <div class="container-fluid"> |
| <a class="brand" href="http://logging.apache.org/log4j-audit">Apache Log4j Audit ™</a> |
| <ul class="nav"> |
| <li> |
| |
| |
| <a href="https://cwiki.apache.org/confluence/display/LOGGING/Home" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://logging.apache.org/" class="external" target="_blank" title="Logging Services">Logging Services</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://github.com/apache/logging-log4j-audit" class="external" target="_blank" title="GitHub">GitHub</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container-fluid"> |
| <table class="layout-table"> |
| <tr> |
| <td class="sidebar"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-home"></i>Apache Log4j Audit™</li> |
| <li class="none"> |
| <a href="index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="download.html" title="Download">Download</a> |
| </li> |
| <li class="none active"> |
| <a href="gettingStarted.html" title="Getting Started">Getting Started</a> |
| </li> |
| <li class="none"> |
| <a href="catalog.html" title="Audit Catalog">Audit Catalog</a> |
| </li> |
| <li class="none"> |
| <a href="requestContext.html" title="RequestContext">RequestContext</a> |
| </li> |
| <li class="none"> |
| <a href="sample.html" title="Sample Project">Sample Project</a> |
| </li> |
| <li class="none"> |
| <a href="changelog.html" title="Changelog">Changelog</a> |
| </li> |
| <li class="none"> |
| <a href="apidocs/index.html" title="Javadoc">Javadoc</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-pencil"></i>For Contributors</li> |
| <li class="none"> |
| <a href="build.html" title="Building Log4j Audit from Source">Building Log4j Audit from Source</a> |
| </li> |
| <li class="none"> |
| <a href="guidelines.html" title="Guidelines">Guidelines</a> |
| </li> |
| <li class="none"> |
| <a href="javastyle.html" title="Style Guide">Style Guide</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Component Reports</li> |
| <li class="none"> |
| <a href="log4j-audit/log4j-audit-api/index.html" title="Audit API">Audit API</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-audit/log4j-audit-war/index.html" title="Audit Service">Audit Service</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-audit/log4j-audit-maven-plugin/index.html" title="Maven Plugin">Maven Plugin</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-api/index.html" title="Catalog API">Catalog API</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-git/index.html" title="Git Catalog Access">Git Catalog Access</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-jpa/index.html" title="JPA Catalog Access">JPA Catalog Access</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-war/index.html" title="Catalog Editor">Catalog Editor</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-info-sign"></i>Project Information</li> |
| <li class="none"> |
| <a href="dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a> |
| </li> |
| <li class="none"> |
| <a href="dependency-management.html" title="Dependency Management">Dependency Management</a> |
| </li> |
| <li class="none"> |
| <a href="team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li class="none"> |
| <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li class="none"> |
| <a href="license.html" title="Project License">Project License</a> |
| </li> |
| <li class="none"> |
| <a href="source-repository.html" title="Source Repository">Source Repository</a> |
| </li> |
| <li class="none"> |
| <a href="project-summary.html" title="Project Summary">Project Summary</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Project Reports</li> |
| <li class="none"> |
| <a href="changes-report.html" title="Changes Report">Changes Report</a> |
| </li> |
| <li class="none"> |
| <a href="jira-report.html" title="JIRA Report">JIRA Report</a> |
| </li> |
| <li class="none"> |
| <a href="rat-report.html" title="RAT Report">RAT Report</a> |
| </li> |
| </ul> |
| </div> |
| <div id="poweredBy"> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="./images/maven-feather.png" /> |
| </a> |
| </div> |
| </td> |
| <td class="content"> |
| <!-- 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. --> |
| |
| |
| <div class="section"> |
| <h2><a name="Getting_Started_with_Log4j_Audit"></a>Getting Started with Log4j Audit</h2> |
| |
| |
| <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"></a> |
| |
| <div class="section"> |
| <h3><a name="What_you_will_build"></a>What you will build</h3> |
| |
| |
| <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> |
| </div> |
| <a name="what_you_will_need"></a> |
| |
| <div class="section"> |
| <h3><a name="What_you_will_need"></a>What you will need</h3> |
| |
| <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> |
| </div> |
| <a name="how_to_complete"></a> |
| |
| <div class="section"> |
| <h3><a name="How_to_complete_this_guide"></a>How to complete this guide</h3> |
| |
| |
| <p>Create a directory for this guide:<br /> |
| </p> |
| <div> |
| <pre><tt> |
| cd ~ |
| mkdir log4j-audit-guide |
| cd log4j-audit-guide</tt></pre></div> |
| |
| |
| <p><a class="externalLink" 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 class="externalLink" href="https://git-scm.com/downloads">Git</a>:<br /> |
| </p> |
| <div> |
| <pre><tt> |
| git clone https://github.com/apache/logging-log4j-audit-sample</tt></pre></div> |
| |
| |
| <p>Change to the root directory of the project and build it using Maven:<br /> |
| </p> |
| <div> |
| <pre><tt> |
| cd logging-log4j-audit-sample |
| mvn clean install</tt></pre></div> |
| |
| |
| <p>Three artifacts will have been created and installed into your local Maven repository: |
| </p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>org.apache.logging.log4j:audit-service-api:1.0.1:jar</li> |
| |
| <li>org.apache.logging.log4j:audit-service-war:1.0.1:war</li> |
| |
| <li>org.apache.logging.log4j:audit-service:1.0.1:jar</li> |
| </ol> |
| |
| |
| <p>The sample catalog can be found at audit-service-api/src/main/resources/catalog.json.</p> |
| </div> |
| <a name="BuildResults"></a> |
| |
| <div class="section"> |
| <h3><a name="Inspect_the_build_results"></a>Inspect the build results</h3> |
| |
| |
| <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: |
| |
| </p> |
| <div> |
| <pre><tt> |
| 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); |
| }</tt></pre></div> |
| |
| </div> |
| <a name="Run"></a> |
| |
| <div class="section"> |
| <h3><a name="Run_an_application_that_performs_auditing"></a>Run an application that performs auditing</h3> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>Change to the sample-app diretory. |
| |
| <div> |
| <pre><tt> |
| cd sample-app</tt></pre></div></li> |
| |
| <li>Run the sample app and view the logs |
| |
| <div> |
| <pre><tt> |
| ./sample-app.sh |
| vi target/logs/audit.log</tt></pre></div></li> |
| </ol> |
| |
| <p>The output from the logs should look similar to: |
| </p> |
| <div> |
| <pre><tt> |
| <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"]</tt></pre></div> |
| Note that the formatting is completely controlled by the Log4j configuration. In this case, the RFC5424Layout was used. |
| |
| |
| <p>The application that generated these logs is: |
| </p> |
| <div> |
| <pre><tt> |
| 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"; |
| }</tt></pre></div> |
| |
| </div> |
| <a name="DeployAuditService"></a> |
| |
| <div class="section"> |
| <h3><a name="Deploy_the_Audit_Service_WAR"></a>Deploy the Audit Service WAR</h3> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>Create a temporary directory and copy the audit service jar to it. |
| <div> |
| <pre><tt> |
| cd ~ |
| mkdir auditService |
| cd auditService |
| cp ~/log4j-audit-guide/logging-audit-sample/audit-service/target/audit-service-1.0.1.jar .</tt></pre></div></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. |
| |
| <div> |
| <pre><tt> |
| remoteRepoUrl=https://github.com/apache/logging-log4j-audit-sample.git |
| remoteRepoCatalogPath=audit-service-api/src/main/resources/catalog.json |
| branch=<branchname> |
| gitUserName= |
| gitPassword= |
| gitPassPhrase=</tt></pre></div></li> |
| |
| <li>Start the application. |
| |
| <div> |
| <pre><tt> |
| java -jar audit-service-1.0.1.jar</tt></pre></div></li> |
| |
| <li>Wait for the application to start.</li> |
| |
| <li>Generate an audit event. |
| <div> |
| <pre><tt> |
| 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"}}' |
| </tt></pre></div></li> |
| |
| <li>The command should respond with <tt>HTTP/1.1 200</tt></li> |
| |
| <li>View the audit log at logs/AuditService/audit.log. The audit event should be present in the file.</li> |
| </ol> |
| </div> |
| <a name="DeployAuditCatalog"></a> |
| |
| <div class="section"> |
| <h3><a name="Run_the_Audit_Catalog_Editor"></a>Run the Audit Catalog Editor</h3> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li><a class="externalLink" href="http://www.apache.org/dist/logging/apache-log4j-audit-1.0.1-bin.zip">Download</a> |
| the Log4j audit binary zip. |
| |
| <div> |
| <pre><tt> |
| wget http://www.apache.org/dist/logging/log4j-audit/1.0.1/apache-log4j-audit-1.0.1-bin.zip</tt></pre></div></li> |
| |
| <li>Unzip the contents. |
| |
| <div> |
| <pre><tt> |
| unzip apache-log4j-audit-1.0.1-bin.zip</tt></pre></div></li> |
| |
| <li>Copy the Log4j Catalog Editor jar to any directory. |
| |
| <div> |
| <pre><tt> |
| mkdir catalogEditor |
| cd catalogEditor |
| cp apache-log4j-audit-1.0.1-bin/log4j-catalog-editor-1.0.1.jar .</tt></pre></div></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. |
| |
| <div> |
| <pre><tt> |
| remoteRepoUrl=https://github.com/apache/logging-log4j-audit-sample.git |
| remoteRepoCatalogPath=audit-service-api/src/main/resources/catalog.json |
| branch=<branchname> |
| gitUserName= |
| gitPassword= |
| gitPassPhrase=</tt></pre></div></li> |
| |
| <li>Start the application. |
| |
| <div> |
| <pre><tt>java -jar log4j-catalog-editor-1.0.1.jar</tt></pre></div></li> |
| </ol> |
| </div> |
| <a name="CatalogEditor"></a> |
| |
| <div class="section"> |
| <h3><a name="Use_the_Catalog_Editor"></a>Use the Catalog Editor</h3> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>Navigate to the edit attributes screen at http://localhost:8080/attributes. The screen |
| should look like <br /><img src="images/attributes.png" alt="" /></li> |
| |
| <li>Navigate to the edit events screen at http://localhost:8080/events. The screen should |
| look like <br /><img src="images/events.png" alt="" /></li> |
| </ol> |
| </div> |
| </div> |
| |
| |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| <div class="footer"> |
| <p>Copyright © 2016-2018 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p> |
| <p>Apache Logging, Apache Log4j, Log4j, Apache Log4j Audit, Log4j Audit, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| <p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p> |
| </div> |
| </div> |
| </body> |
| </html> |
