apache / apache/logging-log4j2
Document XML parser features used for configuration files and clarify Log4j 1 bridge properties
- 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