apache / apache/logging-log4j2

Document XML parser features used for configuration files and clarify Log4j 1 bridge properties

Open Beginner friendly
#4,263 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Java
Stars
3.6k
Forks
1.7k
Avg merge
21h 30m
Merged PRs (30d)
27

Description

## Context

While triaging a report received on our security mailing list (tracking reference: `https://lists.apache.org/thread/k38tg3hsbo7kl17psybp02nzl28lwloq`), we noticed that the features enabled on the XML parsers used to read configuration files are not documented, and that the relationship between the two Log4j 1 bridge configuration properties can be misread when their documentation entries are consulted out of context (e.g., through a deep link to a single anchor).

No behavior change is requested here; this issue only asks for documentation improvements.

## Document the XML parser features enabled for each configuration format

The documentation should state explicitly which XML features are enabled when parsing configuration files:

- **Log4j 1 XML configuration files** (handled by the `log4j-1.2-api` bridge, see the [Migrating from Log4j 1](https://logging.apache.org/log4j/2.x/migrate-from-log4j1.html) page): the files are parsed with **external entities enabled** for backward compatibility with the original Log4j 1 parser. **DTD validation is enabled** and parsing errors are printed as warnings to the status logger.
- **Log4j 2 XML configuration files** (see the [XML format](https://logging.apache.org/log4j/2.x/manual/configuration.html#xml-features) section of the Configuration page): **XInclude is enabled when available**, i.e., when the JAXP implementation supports it. The existing XInclude section describes how to use the feature, but the format description should state up front that the feature is active by default, since it affects which files a configuration file may pull in.

## Clarify the independence of the two Log4j 1 bridge properties

The [Migrating from Log4j 1](https://logging.apache.org/log4j/2.x/migrate-from-log4j1.html) page documents `log4j1.compatibility` and `log4j.configuration` under the sentence "set **one of the following** configuration properties", which correctly presents them as two independent, alternative ways to enable runtime conversion of Log4j 1 configuration files. However, each property's entry does not restate this, so a reader landing directly on the `log4j1.compatibility` anchor (for example via the link printed by the `DOMConfigurator`/`PropertyConfigurator` warning message) can incorrectly conclude that `log4j1.compatibility` is the sole opt-in gate for the Log4j 1 configuration file support.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the Migrating from Log4j 1 page and the Configuration page's XML format section, including the existing XInclude section. Update the documentation to state the enabled XML parser features for each format and clarify that log4j1.compatibility and log4j.configuration are independent alternatives; done when both behaviors are clear from the relevant entries and deep links.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
82/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.