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:

Table 1. Ssl configuration attributes
Attribute Type Default value Description

protocol

String

TLS

It specifies the SSLContext algorithm that JSSE will use.

This setting can only be used to reduce the highest version of TLS to be used.

To disable older TLS versions, see JSSE documentation.

verifyHostName

boolean

false

If true, the host name in X509 certificate will be compared to the requested host name. In the case of a mismatch, the connection will fail.

See also log4j2.sslVerifyHostName.

Table 2. Ssl nested elements
Type Multiplicity Description

KeyStore

zero or one

It specifies the KeyStore to use for TLS client authentication.

TrustStore

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.

Table 3. KeyStore configuration attributes
Attribute Type Default value Description

location

Path or URI

The location of the private key store.

See also log4j2.keyStoreLocation.

password

String

null

The password for the private key store.

See also log4j2.keyStorePassword.

passwordEnvironmentVariable

String

null

The name of the environment variable that contains the password for the private key store.

See also log4j2.keyStorePasswordEnvironmentVariable.

passwordFile

Path

null

The name of a file that contains the password for the private key store.

See also log4j2.keyStorePasswordFile.

type

KeyStore

JVM dependent

The type of private key store. See KeyStore standard types.

See also log4j2.keyStoreType.

keyManagerFactoryAlgorithm

KeyManagerFactory

JVM dependent

Name of the KeyManagerFactory implementation to use for the private key store. See KeyManagerFactory standard names.

See also log4j2.keyStoreKeyManagerFactoryAlgorithm.

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.

Table 4. TrustStore configuration attributes
Attribute Type Default value Description

location

Path or URI

The location of the trust store.

See also log4j2.trustStoreLocation.

password

String

null

The password for the trust store.

See also log4j2.trustStorePassword.

passwordEnvironmentVariable

String

null

The name of the environment variable that contains the password for the trust store.

See also log4j2.trustStorePasswordEnvironmentVariable.

passwordFile

Path

null

The name of a file that contains the password for the trust store.

See also log4j2.trustStorePasswordFile.

type

KeyStore

JVM dependent

The type of trust store. See KeyStore standard types.

See also log4j2.trustStoreType.

keyManagerFactoryAlgorithm

KeyManagerFactory

JVM dependent

Name of the KeyManagerFactory implementation to use for the trust store. See KeyManagerFactory standard names.

See also log4j2.trustStoreKeyManagerFactoryAlgorithm.

TLS configuration example

This is an example of TLS configuration:

  • XML

  • JSON

  • YAML

  • Properties

Snippet from an example log4j2.xml
<Ssl>
  <KeyStore location="keystore.p12"
            type="PKCS12"
            password="${env:KEYSTORE_PASSWORD}"/>
  <TrustStore location="truststore.p12"
              type="PKCS12"
              passwordEnvironmentVariable="TRUSTSTORE_PASSWORD"/>
</Ssl>
Snippet from an example log4j2.json
"Ssl": {
  "KeyStore": {
    "location": "keystore.p12",
    "type": "PKCS12",
    "password": "${env:KEYSTORE_PASSWORD}"
  },
  "TrustStore": {
    "location": "truststore.p12",
    "type": "PKCS12",
    "passwordEnvironmentVariable": "TRUSTSTORE_PASSWORD"
  }
}
Snippet from an example log4j2.yaml
Ssl:
  KeyStore:
    location: "keystore.p12"
    type: "PKCS12"
    password: "${env:KEYSTORE_PASSWORD}"
  TrustStore:
    location: "truststore.p12"
    type: "PKCS12"
    passwordEnvironmentVariable: "TRUSTSTORE_PASSWORD"
Snippet from an example 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 HttpURLConnection under the hood.

Table 5. HTTP Appender configuration attributes
Attribute Type Default value Description

Required

name

String

The name of the appender.

url

URL

The URL of the HTTP server. Only the http and https schemas are supported.

Optional

connectTimeoutMillis

int

0

The connect timeout in milliseconds. If 0 the timeout is infinite.

readTimeoutMillis

int

0

The socket read timeout in milliseconds. If 0 the timeout is infinite.

ignoreExceptions

boolean

true

If false, logging exception will be forwarded to the caller of the logging statement. Otherwise, they will be ignored.

Logging exceptions are always also logged to Status Logger

method

String

POST

The HTTP method to use.

verifyHostName

boolean

true

If true, the host name in X509 certificate will be compared to the requested host name. In the case of a mismatch, the connection will fail.

Table 6. HTTP Appender nested elements
Type Multiplicity Description

Filter

zero or one

Allows filtering log events just before they are formatted and sent.

See also appender filtering stage.

Layout

one

Formats log events. The choice of the layout is also responsible for the Content-Type header of HTTP requests.

See Layouts for more information.

Property

zero or more

Additional HTTP headers to use.

The values support runtime property substitution and are evaluated in a global context.

SSL

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

Snippet from an example 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>
Snippet from an example 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}"
    }
  }
}
Snippet from an example 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}"
Snippet from an example 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 Filter element.

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.

Table 7. SMTP Appender configuration attributes
Attribute Type Default value Description

Required

name

String

The name of the appender.

Optional

bufferSize

int

512

The maximum number of log events to be buffered for inclusion in a single message.

ignoreExceptions

boolean

true

If false, logging exception will be forwarded to the caller of the logging statement. Otherwise, they will be ignored.

Logging exceptions are always also logged to Status Logger

smtpDebug

boolean

false

When set to true turns on the session debugging. In the reference implementation of Jakarta Mail (Eclipse Angus) this will cause log messages to be printed on System.out.

See the javadoc of Session.setDebug() for more details.

smtpProtocol

String

smtp

The Jakarta Mail transport protocol. Most implementations provide:

smtp

SMTP

smtps

SMTP over TLS

smtpHost

String

localhost

The SMTP hostname to send to.

smtpPort

int

25

for smtp

465

for smtps

The SMTP port to send to.

smtpUsername

String

The username used to authenticate against the SMTP server.

smtpPassword

String

The password used to authenticate against the SMTP server.

RFC 822 message fields

from

InternetAddress[]

A list of sender e-mail addresses.

See RFC2822 Address Specification for the format.

replyTo

InternetAddress[]

A list of reply-to e-mail addresses.

See RFC2822 Address Specification for the format.

to

InternetAddress[]

A list of recipient e-mail addresses.

See RFC2822 Address Specification for the format.

Required, if cc and bcc are empty.

cc

InternetAddress[]

A list of CC e-mail addresses.

See RFC2822 Address Specification for the format.

Required, if to and bcc are empty.

bcc

InternetAddress[]

A list of BCC e-mail addresses.

See RFC2822 Address Specification for the format.

Required, if to and cc are empty.

subject

String

It specifies the subject field of the RFC 822 message.

This field can contain pattern converters.

Table 8. HTTP Appender nested elements
Type Multiplicity Description

Filter

zero or one

A filter that decides which events trigger an e-mail and which events are buffered for context.

If absent, a ThresholdFilter with default parameters will be used.

Layout

one

Formats log events. The choice of the layout is also responsible for the Content-Type header of e-mail message.

See Layouts for more information.

SSL

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

Snippet from an example 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>
Snippet from an example 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}"
    }
  }
}
Snippet from an example 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}"
Snippet from an example 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 SocketException is raised, causing those events to be lost.

If guaranteed delivery is required, a protocol that requires acknowledgments must be used.

Table 9. Socket Appender configuration attributes
Attribute Type Default value Description

Required

host

String

The name or address of the system that is listening for log events.

name

String

The name of the appender.

Optional

bufferedIo

boolean

true

If set to true, Log4j Core will format each log event in an internal buffer, before sending it to the underlying resource.

See Buffering for more details.

bufferSize

int

8192

The size of the ByteBuffer internally used by the appender.

See Buffering for more details.

ignoreExceptions

boolean

true

If false, logging exception will be forwarded to the caller of the logging statement. Otherwise, they will be ignored.

Logging exceptions are always also logged to Status Logger

immediateFail

boolean

true

When set to true, log events will not wait to try to reconnect and will fail immediately if the socket is not available.

immediateFlush

boolean

true

If set to true, the appender will flush its internal buffer after each event.

See Buffering for more details.

port

int

4560

for TCP

6514

for SSL

no default

for UDP

The port on the host that is listening for log events.

Required

protocol

enumeration

TCP

The network protocol to use: UDP, TCP or SSL.

connectTimeoutMillis

int

0

The connect timeout in milliseconds. If 0 the timeout is infinite.

readTimeoutMillis

int

0

The socket read timeout in milliseconds. If 0 the timeout is infinite.

Table 10. Socket Appender nested elements
Type Multiplicity Description

Filter

zero or one

Allows filtering log events just before they are formatted and sent.

See also appender filtering stage.

Layout

zero or one

Formats log events.

See Layouts for more information.

SSL

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

Snippet from an example 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>
Snippet from an example 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}"
    }
  }
}
Snippet from an example 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}"
Snippet from an example 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:

Table 11. Configuration attributes specific to Syslog Appender
Attribute Type Default value Description

format

enumeration

BSD

It determines the layout to use:

BSD

Uses the legacy Syslog Layout.

RFC5242

Uses the Rfc5424 Layout.

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

Snippet from an example 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>
Snippet from an example 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}"
    }
  }
}
Snippet from an example 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}"
Snippet from an example 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.