Network Appenders
This section guides you through appenders that use simple network protocols to transmit log events to a remote host.
Common concerns
TLS Configuration
All network appenders support TLS (formerly known as SSL) connections. The TLS layer can be configured:
-
Either globally using configuration properties. See Transport Security for more details.
-
Or by providing a nested
SSL
Log4j component.
Ssl
The Ssl
component supports the following configuration options:
Attribute | Type | Default value | Description | ||
---|---|---|---|---|---|
|
|
It specifies the
|
|||
|
|
If See also
|
Type | Multiplicity | Description |
---|---|---|
zero or one |
It specifies the
|
|
zero or one |
It specifies the trust roots to use for TLS server authentication. |
KeyStore
The KeyStore
is meant to contain your private keys and certificates, and determines which authentication credentials to send to the remote host.
Attribute | Type | Default value | Description |
---|---|---|---|
The location of the private key store. See also |
|||
|
|
The password for the private key store. See also |
|
|
|
The name of the environment variable that contains the password for the private key store. |
|
|
The name of a file that contains the password for the private key store. See also |
||
The type of private key store.
See See also |
|||
Name of the |
TrustStore
The trust store is meant to contain the CA certificates you are willing to trust when a remote party presents its certificate. It determines whether the remote authentication credentials (and thus the connection) should be trusted.
Attribute | Type | Default value | Description |
---|---|---|---|
The location of the trust store. See also |
|||
|
|
The password for the trust store. See also |
|
|
|
The name of the environment variable that contains the password for the trust store. |
|
|
The name of a file that contains the password for the trust store. See also |
||
The type of trust store.
See See also |
|||
Name of the |
TLS configuration example
This is an example of TLS configuration:
-
XML
-
JSON
-
YAML
-
Properties
log4j2.xml
<Ssl>
<KeyStore location="keystore.p12"
type="PKCS12"
password="${env:KEYSTORE_PASSWORD}"/>
<TrustStore location="truststore.p12"
type="PKCS12"
passwordEnvironmentVariable="TRUSTSTORE_PASSWORD"/>
</Ssl>
log4j2.json
"Ssl": {
"KeyStore": {
"location": "keystore.p12",
"type": "PKCS12",
"password": "${env:KEYSTORE_PASSWORD}"
},
"TrustStore": {
"location": "truststore.p12",
"type": "PKCS12",
"passwordEnvironmentVariable": "TRUSTSTORE_PASSWORD"
}
}
log4j2.yaml
Ssl:
KeyStore:
location: "keystore.p12"
type: "PKCS12"
password: "${env:KEYSTORE_PASSWORD}"
TrustStore:
location: "truststore.p12"
type: "PKCS12"
passwordEnvironmentVariable: "TRUSTSTORE_PASSWORD"
log4j2.properties
appender.0.ssl.type = Ssl
appender.0.ssl.ks.type = KeyStore
appender.0.ssl.ks.password = ${env:KEYSTORE_PASSWORD}
appender.0.ssl.ts.type = TrustStore
appender.0.ssl.ts.passwordEnvironmentVariable = TRUSTSTORE_PASSWORD
HTTP Appender
The HTTP Appender sends log events over HTTP, by wrapping them in an HTTP request.
The Content-Type
HTTP header is set based on the
getContentType()
method of the
nested layout.
Additional headers can be configured using the nested
Property
elements.
If the appender receives a response with status code different from 2xx
, an exception is thrown.
See also ignoreExceptions
configuration attribute.
The implementation uses
|
Attribute | Type | Default value | Description |
---|---|---|---|
Required |
|||
|
The name of the appender. |
||
The URL of the HTTP server.
Only the |
|||
Optional |
|||
|
|
The connect timeout in milliseconds.
If |
|
|
|
The socket read timeout in milliseconds.
If |
|
|
|
If Logging exceptions are always also logged to Status Logger |
|
|
|
The HTTP method to use. |
|
|
|
If |
Type | Multiplicity | Description |
---|---|---|
zero or one |
Allows filtering log events just before they are formatted and sent. See also appender filtering stage. |
|
one |
Formats log events.
The choice of the layout is also responsible for the See Layouts for more information. |
|
zero or more |
Additional HTTP headers to use. The values support runtime property substitution and are evaluated in a global context. |
|
zero or one |
It specifies the TLS parameters to use. See TLS Configuration for more details. |
Configuration examples
Here is a sample Http Appender configuration snippet:
-
XML
-
JSON
-
YAML
-
Properties
log4j2.xml
<Http name="HTTP" url="https://localhost/logs">
<Property name="X-Java-Version" value="${java:version}"/> (1)
<Property name="X-Context-Path" value="$${web:contextPath}"/> (2)
<JsonTemplateLayout/>
<Ssl>
<KeyStore location="keystore.p12"
password="${env:KEYSTORE_PASSWORD}"/>
<TrustStore location="truststore.p12"
password="${env:TRUSTSTORE_PASSWORD}"/>
</Ssl>
</Http>
log4j2.json
"Http": {
"name": "HTTP",
"url": "https://localhost/logs",
"JsonTemplateLayout": {},
"Property": [
{ (1)
"name": "X-Java-Version",
"value": "${java:version}"
},
{ (2)
"name": "X-Context-Path",
"value": "$${web:contextPath}"
}
],
"Ssl": {
"KeyStore": {
"location": "keystore.p12",
"password": "${env:KEYSTORE_PASSWORD}"
},
"TrustStore": {
"location": "truststore.p12",
"password": "${env:TRUSTSTORE_PASSWORD}"
}
}
}
log4j2.yaml
Http:
name: "HTTP"
host: "localhost"
url: "https://localhost/logs"
Property:
(1)
- name: "X-Java-Version"
value: "${java:version}"
(2)
- name: "X-Context-Path"
value: "$${web:contextPath}"
JsonTemplateLayout: {}
Ssl:
KeyStore:
location: "keystore.p12"
password: "${env:KEYSTORE_PASSWORD}"
TrustStore:
location: "truststore.p12"
password: "${env:TRUSTSTORE_PASSWORD}"
log4j2.properties
appender.0.type = Http
appender.0.name = HTTP
appender.0.url = https://localhost/logs
(1)
appender.0.p0.type = Property
appender.0.p0.name = X-Java-Version
appender.0.p0.value = ${java:version}
(2)
appender.0.p1.type = Property
appender.0.p1.name = X-Context-Path
appender.0.p1.value = $${web:contextPath}
appender.0.layout.type = JsonTemplateLayout
appender.0.ssl.type = Ssl
appender.0.ssl.ks.type = KeyStore
appender.0.ssl.ks.password = ${env:KEYSTORE_PASSWORD}
appender.0.ssl.ts.type = TrustStore
appender.0.ssl.ts.password = ${env:TRUSTSTORE_PASSWORD}
1 | This HTTP header is evaluated once at configuration time. |
2 | This HTTP header is evaluated at each log event. |
SMTP Appender
The SMTP writes log events to an e-mail service using Jakarta Mail 1.6 or higher.
Unlike what happens with
most appenders, the SMTP does not discard log events that are denied by the
All the log events received by the appender are added to a cyclic log event buffer as context. If the filter accepts a message, an e-mail is sent. |
Attribute | Type | Default value | Description |
---|---|---|---|
Required |
|||
|
The name of the appender. |
||
Optional |
|||
|
|
The maximum number of log events to be buffered for inclusion in a single message. |
|
|
|
If Logging exceptions are always also logged to Status Logger |
|
|
|
When set to See the javadoc of
|
|
|
|
The Jakarta Mail transport protocol. Most implementations provide:
|
|
|
|
The SMTP hostname to send to. |
|
|
|
The SMTP port to send to. |
|
|
The username used to authenticate against the SMTP server. |
||
|
The password used to authenticate against the SMTP server. |
||
RFC 822 message fields |
|||
A list of sender e-mail addresses. See RFC2822 Address Specification for the format. |
|||
A list of reply-to e-mail addresses. See RFC2822 Address Specification for the format. |
|||
A list of recipient e-mail addresses. See RFC2822 Address Specification for the format. |
|||
A list of CC e-mail addresses. See RFC2822 Address Specification for the format. |
|||
A list of BCC e-mail addresses. See RFC2822 Address Specification for the format. |
|||
|
It specifies the subject field of the RFC 822 message. This field can contain pattern converters. |
Type | Multiplicity | Description |
---|---|---|
zero or one |
A filter that decides which events trigger an e-mail and which events are buffered for context. If absent, a
|
|
one |
Formats log events.
The choice of the layout is also responsible for the See Layouts for more information. |
|
zero or one |
It specifies the TLS parameters to use. See TLS Configuration for more details. |
Additional runtime dependencies are required to use the SMTP appender:
-
Maven
-
Gradle
We assume you use log4j-bom
for dependency management.
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-jakarta-smtp</artifactId>
<scope>runtime</scope>
</dependency>
We assume you use log4j-bom
for dependency management.
runtimeOnly 'org.apache.logging.log4j:log4j-jakarta-smtp'
Click here if you are you using Jakarta EE 8 or any version of Java EE?
Jakarta EE 8 and all Java EE applications servers use the legacy javax
package prefix instead of jakarta
.
If you are using those application servers, you should replace the dependencies above with:
-
Maven
-
Gradle
<dependency>
<groupId>com.sun.mail</groupId>
<artifactId>javax.mail</artifactId>
<version>1.6.2</version>
</dependency>
runtimeOnly 'com.sun.mail:javax.mail:1.6.2'
Configuration examples
Here is an example of SMTP Appender configuration:
-
XML
-
JSON
-
YAML
-
Properties
log4j2.xml
<SMTP name="SMTP"
smtpProtocol="smtps"
smtpHost="mx.example.org"
from="app@example.org"
to="root@example.org"
subject="[%markerSimpleName] Security incident on ${hostName}"> (1)
<MarkerFilter marker="AUDIT"/> (2)
<HtmlLayout/>
<Ssl>
<KeyStore location="keystore.p12"
password="${env:KEYSTORE_PASSWORD}"/>
<TrustStore location="truststore.p12"
password="${env:TRUSTSTORE_PASSWORD}"/>
</Ssl>
</SMTP>
log4j2.json
"SMTP": {
"name": "SMTP",
"smtpProtocol": "smtps",
"smtpHost": "mx.example.org",
"from": "app@example.org",
"to": "root@example.org",
"subject": "[%markerSimpleName] Security incident on ${hostName}", (1)
"MarkerFilter": { (2)
"marker": "AUDIT"
},
"HtmlLayout": {},
"Ssl": {
"KeyStore": {
"location": "keystore.p12",
"password": "${env:KEYSTORE_PASSWORD}"
},
"TrustStore": {
"location": "truststore.p12",
"password": "${env:TRUSTSTORE_PASSWORD}"
}
}
}
log4j2.yaml
SMTP:
name: "SMTP"
smtpProtocol: "smtps"
smtpHost: "mx.example.org"
from: "app@example.org"
to: "root@example.org"
subject: "[%markerSimpleName] Security incident on ${hostName}" (1)
MarkerFilter: (2)
marker: "AUDIT"
HtmlLayout: {}
Ssl:
KeyStore:
location: "keystore.p12"
password: "${env:KEYSTORE_PASSWORD}"
TrustStore:
location: "truststore.p12"
password: "${env:TRUSTSTORE_PASSWORD}"
log4j2.properties
appender.0.type = SMTP
appender.0.name = SMTP
appender.0.url = https://localhost/logs
appender.0.smtpProtocol = smtps
appender.0.smtpHost = mx.example.org
appender.0.from = app@example.org
appender.0.to = root@example.org
(1)
appender.0.subject = [%markerSimpleName] Security incident on ${hostName}
(2)
appender.0.filter.0.type = MarkerFilter
appender.0.filter.0.marker = AUDIT
appender.0.layout.type = HtmlLayout
appender.0.ssl.type = Ssl
appender.0.ssl.ks.type = KeyStore
appender.0.ssl.ks.password = ${env:KEYSTORE_PASSWORD}
appender.0.ssl.ts.type = TrustStore
appender.0.ssl.ts.password = ${env:TRUSTSTORE_PASSWORD}
1 | The subject attribute can use pattern converters. |
2 | An e-mail will be sent for each AUDIT log event.
Additional log events will be kept for context. |
Socket Appender
The Socket Appender that writes its output to a remote destination using TCP or UDP sockets. You can optionally secure communication with TLS.
The TCP and TLS variants write to the socket as a stream and do not expect a response from the target destination.
When the target server closes its connection, some log events may continue to appear as delivered until a
If guaranteed delivery is required, a protocol that requires acknowledgments must be used. |
Attribute | Type | Default value | Description |
---|---|---|---|
Required |
|||
|
The name or address of the system that is listening for log events. |
||
|
The name of the appender. |
||
Optional |
|||
|
|
If set to See Buffering for more details. |
|
|
The size of the
See Buffering for more details. |
||
|
|
If Logging exceptions are always also logged to Status Logger |
|
|
boolean |
|
When set to |
|
|
If set to See Buffering for more details. |
|
|
|
The port on the host that is listening for log events. Required |
|
enumeration |
|
The network protocol to use: |
|
|
|
The connect timeout in milliseconds.
If |
|
|
|
The socket read timeout in milliseconds.
If |
Type | Multiplicity | Description |
---|---|---|
zero or one |
Allows filtering log events just before they are formatted and sent. See also appender filtering stage. |
|
zero or one |
Formats log events. See Layouts for more information. |
|
zero or one |
It specifies the TLS parameters to use. See TLS Configuration for more details. |
Configuration examples
The following example appends log events to a Syslog server using a TLS connection and the RFC5424 log event format:
-
XML
-
JSON
-
YAML
-
Properties
log4j2.xml
<Socket name="SYSLOG"
host="syslog.local"
port="6514">
<Rfc5424Layout appName="myApp"
facility="DAEMON"
id="Log4j"
newLineEscape="\n"/>
<Ssl>
<KeyStore location="keystore.p12"
password="${env:KEYSTORE_PASSWORD}"/>
<TrustStore location="truststore.p12"
password="${env:TRUSTSTORE_PASSWORD}"/>
</Ssl>
</Socket>
log4j2.json
"Socket": {
"name": "SYSLOG",
"host": "syslog.local",
"port": 6514,
"Rfc5424Layout": {
"appName": "myApp",
"facility": "DAEMON",
"id": "Log4j",
"newLineEscape": "\\n"
},
"Ssl": {
"KeyStore": {
"location": "keystore.p12",
"password": "${env:KEYSTORE_PASSWORD}"
},
"TrustStore": {
"location": "truststore.p12",
"password": "${env:TRUSTSTORE_PASSWORD}"
}
}
}
log4j2.yaml
Socket:
name: "SYSLOG"
host: "syslog.local"
port: 6514
Rfc5424Layout:
appName: "myApp"
facility: "DAEMON"
id: "Log4j"
newLineEscape: "\\n"
Ssl:
KeyStore:
location: "keystore.p12"
password: "${env:KEYSTORE_PASSWORD}"
TrustStore:
location: "truststore.p12"
password: "${env:TRUSTSTORE_PASSWORD}"
log4j2.properties
appender.0.type = Socket
appender.0.name = SYSLOG
appender.0.host = syslog.local
appender.0.port = 6514
appender.0.layout.type = Rfc5424Layout
appender.0.layout.appName = myApp
appender.0.layout.facility = DAEMON
appender.0.layout.id = Log4j
appender.0.layout.newLineEscape = \\n
appender.0.ssl.type = Ssl
appender.0.ssl.ks.type = KeyStore
appender.0.ssl.ks.password = ${env:KEYSTORE_PASSWORD}
appender.0.ssl.ts.type = TrustStore
appender.0.ssl.ts.password = ${env:TRUSTSTORE_PASSWORD}
Syslog Appender
The Syslog Appender is a utility Log4j plugin to combine a Socket Appender with either a
Syslog Layout
or
Rfc5424 Layout
to provide a functionality similar to the
UNIX syslog
function.
It has a single configuration property to select the layout to use:
Attribute | Type | Default value | Description |
---|---|---|---|
enumeration |
|
It determines the layout to use:
|
All the remaining configuration attributes and nested elements are inherited from Socket Appender and the chosen layout.
Configuration examples
The following configuration snippet creates the same appender as the Socket Appender example above:
-
XML
-
JSON
-
YAML
-
Properties
log4j2.xml
<Syslog name="SYSLOG"
host="syslog.local"
port="6514"
format="RFC5424"
appName="myApp"
facility="DAEMON"
id="Log4j"
newLineEscape="\n"> (1)
<Ssl>
<KeyStore location="keystore.p12"
password="${env:KEYSTORE_PASSWORD}"/>
<TrustStore location="truststore.p12"
password="${env:TRUSTSTORE_PASSWORD}"/>
</Ssl>
</Syslog>
log4j2.json
"Syslog": {
"name": "SYSLOG",
"host": "syslog.local",
"port": 6514,
"format": "RFC5424", (1)
"appName": "myApp",
"facility": "DAEMON",
"id": "Log4j",
"newLineEscape": "\\n",
"Ssl": {
"KeyStore": {
"location": "keystore.p12",
"password": "${env:KEYSTORE_PASSWORD}"
},
"TrustStore": {
"location": "truststore.p12",
"password": "${env:TRUSTSTORE_PASSWORD}"
}
}
}
log4j2.yaml
Socket:
name: "SYSLOG"
host: "syslog.local"
port: 6514
format: "RFC5424" (1)
appName: "myApp"
facility: "DAEMON"
id: "Log4j"
newLineEscape: "\\n"
Ssl:
KeyStore:
location: "keystore.p12"
password: "${env:KEYSTORE_PASSWORD}"
TrustStore:
location: "truststore.p12"
password: "${env:TRUSTSTORE_PASSWORD}"
log4j2.properties
appender.0.type = Syslog
appender.0.name = SYSLOG
appender.0.host = syslog.local
appender.0.port = 6514
(1)
appender.0.format = RFC5424
appender.0.appName = myApp
appender.0.facility = DAEMON
appender.0.id = Log4j
appender.0.newLineEscape = \\n
appender.0.ssl.type = Ssl
appender.0.ssl.ks.type = KeyStore
appender.0.ssl.ks.password = ${env:KEYSTORE_PASSWORD}
appender.0.ssl.ts.type = TrustStore
appender.0.ssl.ts.password = ${env:TRUSTSTORE_PASSWORD}
1 | By setting the format attribute to RFC5424 , the Rfc5424Layout will be used.
The remaining attributes are either attributes of Socket Appender or the Rfc5424Layout . |