"Fossies" - the Fresh Open Source Software Archive

Member "apache-log4j-2.12.4-src/src/site/markdown/index.md.vm" (28 Dec 2021, 8887 Bytes) of package /linux/misc/apache-log4j-2.12.4-src.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!-- vim: set syn=markdown : -->
    2 <!--
    3     Licensed to the Apache Software Foundation (ASF) under one or more
    4     contributor license agreements.  See the NOTICE file distributed with
    5     this work for additional information regarding copyright ownership.
    6     The ASF licenses this file to You under the Apache License, Version 2.0
    7     (the "License"); you may not use this file except in compliance with
    8     the License.  You may obtain a copy of the License at
    9 
   10          http://www.apache.org/licenses/LICENSE-2.0
   11 
   12     Unless required by applicable law or agreed to in writing, software
   13     distributed under the License is distributed on an "AS IS" BASIS,
   14     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   15     See the License for the specific language governing permissions and
   16     limitations under the License.
   17 -->
   18 #set($dollar = '$')
   19 #set($h1='#')
   20 #set($h2='##')
   21 #set($h3='###')
   22 #set($h4='####')
   23 
   24 $h1 Apache Log4j 2
   25 
   26 Apache Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j 1.x, and
   27 provides many of the improvements available in Logback while fixing some inherent problems in Logback's architecture.
   28 
   29 <a name="CVE-2021-44832"/>
   30     $h2 Important: Security Vulnerability CVE-2021-44832
   31 
   32 Summary: Apache Log4j2 vulnerable to RCE via JDBC Appender when attacker controls configuration.
   33 
   34 $h4 Details
   35 
   36 Apache Log4j2 versions 2.0-beta7 through 2.17.0 (excluding security fix releases 2.3.2 and 2.12.4) are vulnerable to
   37 a remote code execution (RCE) attack where an attacker with permission to modify the logging configuration file can
   38 construct a malicious configuration using a JDBC Appender with a data source referencing a JNDI URI which can execute
   39 remote code. This issue is fixed by limiting JNDI data source names to the java protocol in Log4j2 versions 2.17.1,
   40 2.12.4, and 2.3.2.
   41 
   42 $h4 Mitigation
   43 Upgrade to Log4j 2.3.2 (for Java 6), 2.12.4 (for Java 7), or 2.17.1 (for Java 8 and later)
   44 
   45 $h4 Reference
   46 Please refer to the [Security page](https://logging.apache.org/log4j/2.x/security.html#CVE-2021-44832) for details and
   47 mitigation measures for older versions of Log4j.
   48 
   49 $h2 Important: Security Vulnerabilities CVE-2021-45105, CVE-2021-45046 and CVE-2021-44228
   50 
   51 Please refer to the [Security page](https://logging.apache.org/log4j/2.x/security.html) for details and mitigation
   52 measures for these security issues.
   53 
   54 $h2 Features
   55 
   56 $h3 API Separation
   57 
   58 The API for Log4j is separate from the implementation making it clear for application developers which classes and
   59 methods they can use while ensuring forward compatibility. This allows the Log4j team to improve the implementation
   60 safely and in a compatible manner.
   61 
   62 The Log4j API is a logging facade that may, of course, be used with the Log4j implementation, but may also be used
   63 in front of other logging implementations such as Logback. The Log4j API has several advantages over SLF4J:
   64 1. The Log4j API supports logging [Messages](manual/messages.html) instead of just Strings.
   65 2. The Log4j API supports lambda expressions.
   66 3. The Log4j API provides many more logging methods than SLF4J.
   67 4. In addition to the "parameterized logging" format supported by SLF4J, the Log4j API also supports events using
   68    the java.text.MessageFormat syntax as well printf-style messages.
   69 5. The Log4j API provides a LogManager.shutdown() method. The underlying logging implementation must implement the
   70    Terminable interface for the method to have effect.
   71 6. Other constructs such as Markers, log Levels, and ThreadContext (aka MDC) are fully supported.
   72 
   73 $h3 Improved Performance
   74 
   75 Log4j 2 contains next-generation Asynchronous Loggers based on the LMAX Disruptor library. In multi-threaded scenarios
   76 Asynchronous Loggers have 18 times higher throughput and orders of magnitude lower latency than Log4j 1.x and Logback.
   77 See [Asynchronous Logging Performance](manual/async.html#Performance) for details. Otherwise, Log4j 2 significantly
   78 outperforms Log4j 1.x, Logback and java.util.logging, especially in multi-threaded applications.
   79 See [Performance](performance.html) for more information.
   80 
   81 $h3 Support for multiple APIs
   82 
   83 While the Log4j 2 API will provide the best performance, Log4j 2 provides support for the Log4j 1.2, SLF4J, Commons
   84 Logging and java.util.logging (JUL) APIs.
   85 
   86 $h3 Avoid lock-in
   87 
   88 Applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant library as their logger
   89 implementation with the log4j-to-slf4j adapter.
   90 
   91 $h3 Automatic Reloading of Configurations
   92 
   93 Like Logback, Log4j 2 can automatically reload its configuration upon modification. Unlike Logback, it will do so
   94 without losing log events while reconfiguration is taking place.
   95 
   96 $h3 Advanced Filtering
   97 
   98 Like Logback, Log4j 2 supports filtering based on context data, markers, regular expressions, and other components in
   99 the Log event. Filtering can be specified to apply to all events before being passed to Loggers or as they pass through
  100 Appenders. In addition, filters can also be associated with Loggers. Unlike Logback, you can use a common Filter class
  101 in any of these circumstances.
  102 
  103 $h3 Plugin Architecture
  104 
  105 Log4j uses the plugin pattern to configure components. As such, you do not need to write code to create and configure an
  106 Appender, Layout, Pattern Converter, and so on. Log4j automatically recognizes plugins and uses them when a
  107 configuration references them.
  108 
  109 $h3 Property Support
  110 
  111 You can reference properties in a configuration, Log4j will directly replace them, or Log4j will pass them to an
  112 underlying component that will dynamically resolve them. Properties come from values defined in the configuration file,
  113 system properties, environment variables, the ThreadContext Map, and data present in the event. Users can further
  114 customize the property providers by adding their own [Lookup](manual/lookups.html) Plugin.
  115 
  116 $h3 Java 8 Lambda Support
  117 
  118 Previously, if a log message was expensive to construct, you would often explicitly check if the requested log level is
  119 enabled before constructing the message. Client code running on Java 8 can benefit from Log4j's
  120 [lambda support](manual/api.html#LambdaSupport). Since Log4j will not evaluate a lambda expression if the requested log
  121 level is not enabled, the same effect can be achieved with less code.
  122 
  123 $h3 Custom Log Levels
  124 
  125 In Log4j 2, [custom log levels](manual/customloglevels.html) can easily be defined in code or in configuration. No
  126 subclassing is required.
  127 
  128 $h3 Garbage-free
  129 
  130 During steady state logging, Log4j 2 is [garbage-free](manual/garbagefree.html) in stand-alone applications, and low
  131 garbage in web applications. This reduces pressure on the garbage collector and can give better response time performance.
  132 
  133 $h3 Integrating with Application Servers
  134 
  135 Version 2.10.0 added the module log4j-appserver to improve integration with Apache Tomcat and Eclipse Jetty.
  136 
  137 $h3 Cloud Enabled
  138 
  139 Version 2.12.0 introduced support for accessing Docker container information via a Lookup and for accessing
  140 and updating the Log4j configuration through Spring Cloud Configuration. See [Logging in the Cloud](manual/cloud.html)
  141 for details.
  142 
  143 $h2 Documentation
  144 
  145 The Log4j 2 User's Guide is available on this [site](manual/index.html) or as a downloadable
  146 [PDF](log4j-users-guide.pdf).
  147 
  148 $h2 Requirements
  149 
  150 Log4j 2.4 and greater requires Java 7, versions 2.0-alpha1 to 2.3 required Java 6. Some features require optional
  151 dependencies; the documentation for these features specifies the dependencies.
  152 
  153 $h2 News
  154 
  155 Log4j 2.12.3 has been released solely to:
  156 
  157 * Address CVE-2021-45105.
  158 * Require components that use JNDI to be enabled individually via system properties.
  159 
  160 2.12.3 is a recommended upgrade to ensure that recursive lookups do not cause services to fail.
  161 
  162 Log4j $Log4jReleaseVersion is now available for production. The API for Log4j 2 is not compatible with Log4j 1.x, however an adapter is
  163 available to allow applications to continue to use the Log4j 1.x API. Adapters are also available for Apache Commons
  164 Logging, SLF4J, and java.util.logging.
  165 
  166 Log4j $Log4jReleaseVersion is the latest release of Log4j and contains several bug fixes that were found after the release of Log4j 2.6.
  167 The list of fixes can be found in the latest [changes report](changes-report.html#a$Log4jReleaseVersion).
  168 
  169 Note that subsequent to the release of Log4j 2.6 a minor source incompatibility with prior release was found due to the
  170 addition of new methods to the Logger interface. If you have code that does:
  171 
  172     logger.error(null, "This is the log message", throwable);
  173 
  174 or similar with any log level you will get a compiler error saying the reference is ambiguous. To correct this either
  175 do:
  176 
  177     logger.error("This is the log message", throwable);
  178 
  179 or
  180 
  181     logger.error((Marker) null, "This is the log message", throwable);
  182 
  183 Log4j $Log4jReleaseVersion maintains binary compatibility with previous releases.