////
    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.
////
[id=system-properties]
= Configuration properties

Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
See <<property-sources>> for a complete list of supported sources.

Configuration properties are used by Log4j in the following situations:

* to finely tune Log4j API and Log4j Core services that are independent of the configuration file,
* to change the default values of attributes used in a configuration file.

Log4j 3 introduces significant changes in the configuration properties subsystem by adding support for logger context specific properties.
Two kinds of configuration properties can be used:

Logger context scoped properties::
+
These properties apply only to a single logger context.
If `<contextName>` is the name of a logger context, it can be tuned using properties of the form:
+
----
log4j.contexts.<contextName>.propertyName
----
+
If the configuration property is specified using environment variables, the naming convention used is:
+
----
LOG4J_CONTEXTS_<contextName>_PROPERTY_NAME
----
+
[WARNING]
====
Not all configuration properties can be used this way.
Properties that specify global Log4j services, such as the logging provider used, can not be restricted to a single logger context.
====

Global configuration properties::
+
Global configuration properties can be used to provide a **default** value for context scoped properties described above.
Their generic syntax is:
+
----
log4j.propertyName
----
+
where `propertyName` is a sequence of camelcase words separated by dots.
As usual, the environment variable property source adopts a different convention:
+
----
LOG4J_PROPERTY_NAME
----

[TIP]
====
You can specify configuration properties using a `log4j2.component.properties` resource at the root of your classpath.
The configuration properties sub-system will take care of merging the content of all these resources.
====

[IMPORTANT]
====
The names of **all** configuration properties changed between Log4j 2 and Log4j 3.

To help users with the migration process the properties described in
link:/log4j/2.x/manual/systemproperties.html[Log4j 2 configuration properties]
are still supported through a backward-compatibility mechanism.
This mechanism is based on `META-INF/log4j/propertyMapping.json` classpath resources.

Users that use shading in their applications should take care of removing all `META-INF/log4j/propertyMapping.json`
resources and use only Log4j 3 property names.
====

[WARNING]
====
Since Log4j Core 3 uses Log4j API 2 to support **global** configuration properties, these properties are looked up using a fuzzy matching algorithm.

In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:

* `asyncLogger`,
* `disableThreadContext`,
* `isThreadContext`,
* `org.apache.logging.log4j`

and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
====

[id=properties-meta]
== Meta configuration properties

In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:

include::partial$manual/systemproperties/properties-meta.adoc[leveloffset=+1]

[id=properties-log4j-api]
== Log4j API properties

In order to configure Log4j API, see the
link:/log4j/2.x/manual/systemproperties.html#properties-log4j-api[Log4j 2 site].

[id=properties-log4j-core]
== Log4j Core properties

While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration.adoc[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.

[id=properties-async]
=== Async components

The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:

include::partial$manual/systemproperties/properties-async.adoc[leveloffset=+2]

[id=properties-properties-context-selector]
=== Logger context

The
link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector.html[`ContextSelector`]
component specifies the strategy used by Log4j to create new logger contexts.
The choice of `ContextSelector` determines in particular:

It can be customized using these properties:

include::partial$manual/systemproperties/properties-logger-context.adoc[leveloffset=+2]

[id=properties-configuration-factory]
=== Configuration factory

Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.

[WARNING]
====
Log4j Core supports both local and remote configuration files.
If a remote configuration file is used, its transport must be secured.
See <<properties-transport-security>> for details.
====

include::partial$manual/systemproperties/properties-configuration-factory.adoc[leveloffset=+2]

[id=properties-message]
=== Log messages

The way Log4j builds
{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[`Message`]s can be customized using these properties:

include::partial$manual/systemproperties/properties-message.adoc[leveloffset=+2]

[id=properties-log-event]
=== Log events

The way Log4j builds
link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`]s can be customized using these properties:

include::partial$manual/systemproperties/properties-log-event.adoc[leveloffset=+2]

[id=properties-garbage-collection]
=== Garbage Collection

include::partial$manual/systemproperties/properties-garbage-collection.adoc[leveloffset=+2]

[id=properties-log4j-core-thread-context]
=== Thread context

To configure the thread context used by Log4j Core, you can use the following properties:

[WARNING]
====
These configuration properties are only used by Log4j Core and {log4j2-url}/manual/simple-logger.html[Simple Logger] of Log4j API.

The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to {slf4j-url}/api/org/slf4j/MDC.html[the SLF4J `MDC` class].

The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
====

include::partial$manual/systemproperties/properties-thread-context-core.adoc[leveloffset=+2]

[id=properties-transport-security]
=== Transport security

Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).

In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:

include::partial$manual/systemproperties/properties-auth.adoc[leveloffset=+2]

include::partial$manual/systemproperties/properties-transport-security.adoc[leveloffset=+2]

[id=properties-log4j-core-misc]
=== Miscellaneous properties

include::partial$manual/systemproperties/properties-log4j-core-misc.adoc[leveloffset=+2]

[id=properties-other-components]
== Other components

[id=properties-log4j-async-logger]
=== Asynchronous Logger properties

Asynchronous loggers support the following additional properties:

include::partial$manual/systemproperties/properties-async-logger.adoc[leveloffset=+2]

[id=properties-jndi-support]
=== JNDI support

Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.

Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.

include::partial$manual/systemproperties/properties-log4j-jndi.adoc[leveloffset=+2]

[id=properties-log4j-jul]
=== JUL-to-Log4j API bridge properties

The JUL-to-Log4j API bridge provides the following configuration properties:

include::partial$manual/systemproperties/properties-log4j-jul.adoc[leveloffset=+2]

[id=properties-log4j-script]
=== Script support

Script support can be configured using the following properties:

include::partial$manual/systemproperties/properties-log4j-script.adoc[leveloffset=+2]

[id=property-sources]
== Property sources

The Log4j configuration properties sub-system is based on the
{log4j2-url}/javadoc/log4j-kit/org/apache/logging/log4j/kit/env/PropertyEnvironment.html[`PropertyEnvironment`]
interface, which provides a type-safe access to configuration properties.

Two kinds of property environments are used by Log4j 3:

* a single global environment resolves configuration properties that apply to the entire Log4j system.
* logger context specific environments resolve configuration properties that apply to a single logger context only.
If a property is not defined in a logger context specific environment, the corresponding value from the global environment is used.

[#global-environment]
=== Global environment

The global environment delegates property resolution to the Log4j 2 API
{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/util/PropertiesUtil.html[`PropertiesUtil`]
service (see
link:../../2.x/manual/systemproperties.adoc#property-sources[Log4j 2 API documentation]).

Configuration properties can be declared in any of the property sources below, which use the standard naming convention:

----
log4j.propertyName
----

When resolving a configuration property, the first property source that contains a value is used.

.Global environment property sources
[%header,cols="2m,1,1m,5"]
|===
| Name
| Naming Convention
| Module
| Description

| SystemPropertiesPropertySource
| standard
| log4j-api
| Resolves properties using Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties].

| EnvironmentPropertySource
| **custom**
| log4j-api
a| Resolves properties using environment variables.

**Warning**: The naming convention of this property source differs from the standard one.
The property name is prefixed with LOG4J_, is in all caps and words are all separated by underscores.

| PropertyFilePropertySource
| standard
| log4j-api
| Resolves properties using all the resources named `log4j2.component.properties` found on the classpath.
This property source should be used to change the default values of an application.
|===

Additional property source classes can be added through:

* the standard Java SE https://docs.oracle.com/en/java/javase/{java-target-version}/docs/api/java.base/java/util/ServiceLoader.html[`ServiceLoader`] mechanism,
* programmatically using `addPropertySource()` and `removePropertySource()` static methods of `PropertiesUtil` class.

[#logger-context-property-environment]
=== Logger context specific environment

The logger context specific environment resolve configuration properties that apply to a single logger context.

Configuration properties can be declared in any of the property sources below:

.Logger context specific property sources
[%header,cols="2m,1m,5"]
|===
| Name
| Module
| Description

| ContextualJavaPropsPropertySource
| log4j-kit
| Resolves properties using Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties].

| ContextualEnvironmentPropertySource
| log4j-kit
| Resolves properties using environment variables.
|===

The `ContextualJavaPropsPropertySource` looks for Java system properties of the form:

----
log4j.contexts.<contextName>.propertyName
----

and its values take precedence over those from the `ContextualEnvironmentPropertySource`.

The `ContextualEnvironmentPropertySource` looks for environment variables named:

----
LOG4J_CONTEXTS_<contextName>_PROPERTY_NAME
----