blob: 710361c0dc41f4c8ac2263a567f0aa3118662635 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/index.md.vm at 2022-09-13
| Rendered using Apache Maven Fluido Skin 1.8
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" />
<title>Log4j &#x2013; Apache Log4j 2</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.8.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script src="./js/apache-maven-fluido-1.8.min.js"></script>
</head>
<body class="topBarDisabled">
<div class="container-fluid">
<header>
<div id="banner">
<div class="pull-left"><a href="../.." id="bannerLeft"><img src="images/ls-logo.jpg" alt=""/></a></div>
<div class="pull-right"><a href="./" id="bannerRight"><img src="images/logo.png" alt=""/></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2022-09-13<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 2.19.0</li>
<li class="pull-right"><span class="divider">|</span>
<a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li>
<li class="pull-right"><span class="divider">|</span>
<a href="../../" title="Logging Services">Logging Services</a></li>
<li class="pull-right"><span class="divider">|</span>
<a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li>
<li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li>
</ul>
</div>
</header>
<div class="row-fluid">
<header id="leftColumn" class="span2">
<nav class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><img class="imageLink" src="img/glyphicons/home.png" alt="Apache Log4j™ 2" border="0"/> Apache Log4j™ 2</li>
<li class="active"><a href="#"><span class="none"></span>About</a></li>
<li><a href="download.html" title="Download"><span class="none"></span>Download</a></li>
<li><a href="javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</a></li>
<li><a href="maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li>
<li><a href="runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li>
<li><a href="changelog.html" title="Changelog"><span class="none"></span>Changelog</a></li>
<li><a href="faq.html" title="FAQ"><span class="none"></span>FAQ</a></li>
<li><a href="performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li>
<li><a href="articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li>
<li><a href="security.html" title="Security"><span class="none"></span>Security</a></li>
<li><a href="support.html" title="Support"><span class="none"></span>Support</a></li>
<li><a href="thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li>
<li><a href="guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li>
<li><a href="javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/book.png" alt="Manual" border="0"/> Manual</li>
<li><a href="manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li>
<li><a href="manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li>
<li><a href="manual/api-separation.html" title="API Separation"><span class="none"></span>API Separation</a></li>
<li><a href="manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></span>Log4j 1.x Migration</a></li>
<li><a href="manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li>
<li><a href="manual/scala-api.html" title="Scala API"><span class="none"></span>Scala API</a></li>
<li><a href="manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li>
<li><a href="manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li>
<li><a href="manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li>
<li><a href="manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li>
<li><a href="manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li>
<li><a href="manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li>
<li><a href="manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li>
<li><a href="manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li>
<li><a href="manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li>
<li><a href="manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li>
<li><a href="manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li>
<li><a href="manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li>
<li><a href="manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li>
<li><a href="manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li>
<li><a href="manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/tag.png" alt="Related Projects" border="0"/> Related Projects</li>
<li><a href="../../chainsaw/2.x/index.html" title="Chainsaw"><span class="none"></span>Chainsaw</a></li>
<li><a href="../../log4cxx/latest_stable/index.html" title="Log4Cxx"><span class="none"></span>Log4Cxx</a></li>
<li><a href="../../log4j-audit/latest/index.html" title="Log4j Audit"><span class="none"></span>Log4j Audit</a></li>
<li><a href="../kotlin/index.html" title="Log4j Kotlin"><span class="none"></span>Log4j Kotlin</a></li>
<li><a href="../scala/index.html" title="Log4j Scala"><span class="none"></span>Log4j Scala</a></li>
<li><a href="../../log4net/index.html" title="Log4Net"><span class="none"></span>Log4Net</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li>
<li><a href="../1.2/" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li>
<li><a href="../log4j-2.3.2/" title="Log4j 2.3.2 - Java 6"><span class="none"></span>Log4j 2.3.2 - Java 6</a></li>
<li><a href="../log4j-2.12.4/" title="Log4j 2.12.4 - Java 7"><span class="none"></span>Log4j 2.12.4 - Java 7</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/cog.png" alt="Components" border="0"/> Components</li>
<li><a href="log4j-api/index.html" title="API"><span class="none"></span>API</a></li>
<li><a href="log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li>
<li><a href="log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li>
<li><a href="log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li>
<li><a href="log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li>
<li><a href="log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li>
<li><a href="log4j-jpl/index.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li>
<li><a href="log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li>
<li><a href="log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li>
<li><a href="log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li>
<li><a href="log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li>
<li><a href="log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li>
<li><a href="log4j-jakarta-web/index.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li>
<li><a href="log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li>
<li><a href="log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li>
<li><a href="log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li>
<li><a href="log4j-mongodb4/index.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li>
<li><a href="log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li>
<li><a href="log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li>
<li><a href="log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li>
<li><a href="log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li>
<li><a href="log4j-spring-boot/index.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li>
<li><a href="log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/info.png" alt="Project Information" border="0"/> Project Information</li>
<li><a href="dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li>
<li><a href="dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li>
<li><a href="team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li>
<li><a href="mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li>
<li><a href="issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li>
<li><a href="license.html" title="Project License"><span class="none"></span>Project License</a></li>
<li><a href="source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li>
<li><a href="project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li>
<li><a href="changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li>
<li><a href="jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li>
<li><a href="rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li>
</ul>
</nav>
<div class="well sidebar-nav">
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
</div>
</div>
</header>
<main id="bodyColumn" class="span10" >
<!-- vim: set syn=markdown : -->
<!--
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.
-->
<h1>Apache Log4j&trade; 2</h1>
<p>Apache Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j 1.x, and
provides many of the improvements available in Logback while fixing some inherent problems in Logback's architecture.</p>
<a name="CVE-2021-44832"></a>
<section>
<h2><a name="Important:_Security_Vulnerability_CVE-2021-44832"></a>Important: Security Vulnerability CVE-2021-44832</h2>
<p>Summary: Apache Log4j2 vulnerable to RCE via JDBC Appender when attacker controls configuration.</p><section><section>
<h4><a name="Details"></a>Details</h4>
<p>Apache Log4j2 versions 2.0-beta7 through 2.17.0 (excluding security fix releases 2.3.2 and 2.12.4) are vulnerable to
a remote code execution (RCE) attack where an attacker with permission to modify the logging configuration file can
construct a malicious configuration using a JDBC Appender with a data source referencing a JNDI URI which can execute
remote code. This issue is fixed by limiting JNDI data source names to the java protocol in Log4j2 versions 2.17.1,
2.12.4, and 2.3.2.</p></section><section>
<h4><a name="Mitigation"></a>Mitigation</h4>
<p>Upgrade to Log4j 2.3.2 (for Java 6), 2.12.4 (for Java 7), or 2.17.1 (for Java 8 and later)</p></section><section>
<h4><a name="Reference"></a>Reference</h4>
<p>Please refer to the <a href="security.html#CVE-2021-44832">Security page</a> for details and mitigation measures for older
versions of Log4j.</p></section></section></section><section>
<h2><a name="Important:_Security_Vulnerabilities_CVE-2021-45105.2C_CVE-2021-45046_and_CVE-2021-44228"></a>Important: Security Vulnerabilities CVE-2021-45105, CVE-2021-45046 and CVE-2021-44228</h2>
<p>Please refer to the <a href="security.html">Security page</a> for details and mitigation measures for these security issues.</p></section><section>
<h2><a name="Features"></a>Features</h2><section>
<h3><a name="API_Separation"></a>API Separation</h3>
<p>The API for Log4j is separate from the implementation making it clear for application developers which classes and
methods they can use while ensuring forward compatibility. This allows the Log4j team to improve the implementation
safely and in a compatible manner.</p>
<p>The Log4j API is a logging facade that may, of course, be used with the Log4j implementation, but may also be used
in front of other logging implementations such as Logback. The Log4j API has several advantages over SLF4J:</p>
<ol style="list-style-type: decimal">
<li>The Log4j API supports logging <a href="manual/messages.html">Messages</a> instead of just Strings.</li>
<li>The Log4j API supports lambda expressions.</li>
<li>The Log4j API provides many more logging methods than SLF4J.</li>
<li>In addition to the &#x201c;parameterized logging&#x201d; format supported by SLF4J, the Log4j API also supports events using
the java.text.MessageFormat syntax as well printf-style messages.</li>
<li>The Log4j API provides a LogManager.shutdown() method. The underlying logging implementation must implement the
Terminable interface for the method to have effect.</li>
<li>Other constructs such as Markers, log Levels, and ThreadContext (aka MDC) are fully supported.</li>
</ol></section><section>
<h3><a name="Improved_Performance"></a>Improved Performance</h3>
<p>Log4j 2 contains next-generation Asynchronous Loggers based on the LMAX Disruptor library. In multi-threaded scenarios
Asynchronous Loggers have 18 times higher throughput and orders of magnitude lower latency than Log4j 1.x and Logback.
See <a href="manual/async.html#Performance">Asynchronous Logging Performance</a> for details. Otherwise, Log4j 2 significantly
outperforms Log4j 1.x, Logback and java.util.logging, especially in multi-threaded applications.
See <a href="performance.html">Performance</a> for more information.</p></section><section>
<h3><a name="Support_for_multiple_APIs"></a>Support for multiple APIs</h3>
<p>While the Log4j 2 API will provide the best performance, Log4j 2 provides support for the Log4j 1.2, SLF4J, Commons
Logging and java.util.logging (JUL) APIs.</p></section><section>
<h3><a name="Avoid_lock-in"></a>Avoid lock-in</h3>
<p>Applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant library as their logger
implementation with the log4j-to-slf4j adapter.</p></section><section>
<h3><a name="Automatic_Reloading_of_Configurations"></a>Automatic Reloading of Configurations</h3>
<p>Like Logback, Log4j 2 can automatically reload its configuration upon modification. Unlike Logback, it will do so
without losing log events while reconfiguration is taking place.</p></section><section>
<h3><a name="Advanced_Filtering"></a>Advanced Filtering</h3>
<p>Like Logback, Log4j 2 supports filtering based on context data, markers, regular expressions, and other components in
the Log event. Filtering can be specified to apply to all events before being passed to Loggers or as they pass through
Appenders. In addition, filters can also be associated with Loggers. Unlike Logback, you can use a common Filter class
in any of these circumstances.</p></section><section>
<h3><a name="Plugin_Architecture"></a>Plugin Architecture</h3>
<p>Log4j uses the plugin pattern to configure components. As such, you do not need to write code to create and configure an
Appender, Layout, Pattern Converter, and so on. Log4j automatically recognizes plugins and uses them when a
configuration references them.</p></section><section>
<h3><a name="Property_Support"></a>Property Support</h3>
<p>You can reference properties in a configuration, Log4j will directly replace them, or Log4j will pass them to an
underlying component that will dynamically resolve them. Properties come from values defined in the configuration file,
system properties, environment variables, the ThreadContext Map, and data present in the event. Users can further
customize the property providers by adding their own <a href="manual/lookups.html">Lookup</a> Plugin.</p></section><section>
<h3><a name="Java_8_Lambda_Support"></a>Java 8 Lambda Support</h3>
<p>Previously, if a log message was expensive to construct, you would often explicitly check if the requested log level is
enabled before constructing the message. Client code running on Java 8 can benefit from Log4j's
<a href="manual/api.html#LambdaSupport">lambda support</a>. Since Log4j will not evaluate a lambda expression if the requested log
level is not enabled, the same effect can be achieved with less code.</p></section><section>
<h3><a name="Custom_Log_Levels"></a>Custom Log Levels</h3>
<p>In Log4j 2, <a href="manual/customloglevels.html">custom log levels</a> can easily be defined in code or in configuration. No
subclassing is required.</p></section><section>
<h3><a name="Log_Builder_API"></a>Log Builder API</h3>
<p>In addition to using one of the many log methods in the Log4j API, log events can be constructed using a builder. See
<a href="manual/logbuilder.html">Log Builder</a> for more information.</p></section><section>
<h3><a name="Garbage-free"></a>Garbage-free</h3>
<p>During steady state logging, Log4j 2 is <a href="manual/garbagefree.html">garbage-free</a> in stand-alone applications, and low
garbage in web applications. This reduces pressure on the garbage collector and can give better response time performance.</p></section><section>
<h3><a name="Integrating_with_Application_Servers"></a>Integrating with Application Servers</h3>
<p>Version 2.10.0 added the module log4j-appserver to improve integration with Apache Tomcat and Eclipse Jetty.</p></section><section>
<h3><a name="Cloud_Enabled"></a>Cloud Enabled</h3>
<p>Version 2.12.0 introduced support for accessing Docker container information via a Lookup and for accessing
and updating the Log4j configuration through Spring Cloud Configuration. This support was enhanced in
version 2.13.0 to add support for accessing Spring Boot properties as well as Kubernetes information.
See <a href="manual/cloud.html">Logging in the Cloud</a> for details.</p></section><section>
<h3><a name="Compatible_with_Log4j_1.x"></a>Compatible with Log4j 1.x</h3>
<p>The Log4j-1.2-api module of Log4j 2 provides compatibility for applications using the Log4j 1 logging methods. As
of Log4j 2.13.0 Log4j 2 also provides experimental support for Log4j 1.x configuration files. See
<a href="manual/compatibility.html">Log4j 2 Compatibility with Log4j 1</a> for more information.</p></section></section><section>
<h2><a name="Documentation"></a>Documentation</h2>
<p>The Log4j 2 User's Guide is available on this <a href="manual/index.html">site</a> or as a downloadable
<a href="log4j-users-guide.pdf">PDF</a>.</p></section><section>
<h2><a name="Requirements"></a>Requirements</h2>
<p>Log4j 2.13.0 and greater require Java 8. Version 2.4 through 2.12.1 required Java 7 (the Log4j team no longer supports
Java 7). Some features require optional dependencies; the documentation for these features will specify the required
dependencies.</p></section><section>
<h2><a name="News"></a>News</h2>
<p>Log4j 2.17.2 has been released to:</p>
<ul>
<li>Over 50 improvements and fixes to the Log4j 1.x support. Continued testing has shown it is a suitable replacement
for Log4j 1.x in most cases.</li>
<li>Scripting now requires a system property be specified naming the languages the user wishes to allow. The scripting
engine will not load if the property isn't set.</li>
<li>By default, the only remote protocol allowed for loading configuration files is HTTPS. Users can specify a system
property to allow others or prevent remote loading entirely.</li>
<li>Variable resolution has been modified so that only properties defined as properties in the configuration file can be
recursive. All other Lookups are now non-recursive. This addresses issues users were having resolving lookups specified
in property definitions for use in the RoutingAppender and RollingFileAppender due to restrictions put in place in 2.17.1.</li>
<li>Many other fixes and improvements.</li>
</ul>
<p>2.17.2 (for Java 8) is a recommended upgrade.</p>
<p>Log4j 2.19.0 is now available for production. While the normal API for Log4j 2 is not compatible with
Log4j 1.x, an adapter is available to allow applications to continue to use the Log4j 1.x API and configuration files.
Adapters are also available for Apache Commons Logging, SLF4J, and java.util.logging.</p>
<p>Log4j 2.19.0 is the latest release of Log4j. As of Log4j 2.13.0 Log4j 2 requires Java 8 or greater at
runtime. This release contains new features and fixes which can be found
in the latest <a href="changes-report.html#a2.19.0">changes report</a>.</p>
<p>Log4j 2.19.0 maintains binary compatibility with previous releases.</p></section>
</main>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p align="center">Copyright &copy; 1999-2022 <a class="external" href="https://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br>
Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
</div>
</div>
</footer>
</body>
</html>