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

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.

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.

📖 Plugin reference for SSL

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 `l.t.keyStore.location`.
`password`	`String`	`null`	The password for the private key store. See also `l.t.keyStore.password`.
`passwordEnvironmentVariable`	`String`	`null`	The name of the environment variable that contains the password for the private key store. See also `l.t.keyStore.passwordEnvVar`.
`passwordFile`	`Path`	`null`	The name of a file that contains the password for the private key store. See also `l.t.keyStore.passwordFile`.
`type`	`KeyStore`	JVM dependent	The type of private key store. See `KeyStore` standard types. See also `l.t.keyStore.type`.
`keyManagerFactoryAlgorithm`	`KeyManagerFactory`	JVM dependent	Name of the `KeyManagerFactory` implementation to use for the private key store. See `KeyManagerFactory` standard names. See also `l.t.keyStore.keyManagerFactory.algorithm`.

📖 Plugin reference for KeyStore

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 `l.t.trustStore.location`.
`password`	`String`	`null`	The password for the trust store. See also `l.t.trustStore.password`.
`passwordEnvironmentVariable`	`String`	`null`	The name of the environment variable that contains the password for the trust store. See also `l.t.trustStore.passwordEnvVar`.
`passwordFile`	`Path`	`null`	The name of a file that contains the password for the trust store. See also `l.t.trustStore.passwordFile`.
`type`	`KeyStore`	JVM dependent	The type of trust store. See `KeyStore` standard types. See also `l.t.trustStore.type`.
`keyManagerFactoryAlgorithm`	`KeyManagerFactory`	JVM dependent	Name of the `KeyManagerFactory` implementation to use for the trust store. See `KeyManagerFactory` standard names. See also `l.t.trustStore.keyManagerFactory.algorithm`.

📖 Plugin reference for TrustStore

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

Appenders.0.Ssl.KeyStore.location = keystore.p12
Appenders.0.Ssl.KeyStore.password = ${env:KEYSTORE_PASSWORD}

Appenders.0.Ssl.TrustStore.location = truststore.p12
Appenders.0.Ssl.TrustStore.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 the 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.

📖 Plugin reference for HTTP

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

Appenders.Http.name = HTTP
Appenders.Http.url = https://localhost/logs

(1)
Appenders.Http.Property[1].name = X-Java-Version
Appenders.Http.Property[1].value = ${java:version}
(2)
Appenders.Http.Property[2].name = X-Context-Path
Appenders.Http.Property[2].value = $${web:contextPath}

Appenders.Http.layout.type = JsonTemplateLayout

Appenders.Http.Ssl.KeyStore.location = keystore.p12
Appenders.Http.Ssl.KeyStore.password = ${env:KEYSTORE_PASSWORD}

Appenders.Http.Ssl.TrustStore.location = truststore.p12
Appenders.Http.Ssl.TrustStore.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 the 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

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-jakarta-smtp</artifactId>
  <version>3.0.0-alpha1</version>
  <scope>runtime</scope>
</dependency>

runtimeOnly 'org.apache.logging.log4j:log4j-jakarta-smtp:3.0.0-alpha1'

📖 Plugin reference for SMTP

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

Appenders.SMTP.name = SMTP
Appenders.SMTP.url = https://localhost/logs

Appenders.SMTP.smtpProtocol = smtps
Appenders.SMTP.smtpHost = mx.example.org
Appenders.SMTP.from = app@example.org
Appenders.SMTP.to = root@example.org
(1)
Appenders.SMTP.subject = [%markerSimpleName] Security incident on ${hostName}

(2)
Appenders.SMTP.MarkerFilter.marker = AUDIT

Appenders.SMTP.layout.type = HtmlLayout

Appenders.SMTP.Ssl.KeyStore.location = keystore.p12
Appenders.SMTP.Ssl.KeyStore.password = ${env:KEYSTORE_PASSWORD}

Appenders.SMTP.Ssl.TrustStore.location = truststore.p12
Appenders.SMTP.Ssl.TrustStore.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 the 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

Appenders.Socket.name = SYSLOG
Appenders.Socket.host = syslog.local
Appenders.Socket.port = 6514

Appenders.Socket.Rfc5424Layout.type = Rfc5424Layout
Appenders.Socket.Rfc5424Layout.appName = myApp
Appenders.Socket.Rfc5424Layout.facility = DAEMON
Appenders.Socket.Rfc5424Layout.id = Log4j
Appenders.Socket.Rfc5424Layout.newLineEscape = \\n

Appenders.Socket.Ssl.KeyStore.location = keystore.p12
Appenders.Socket.Ssl.KeyStore.password = ${env:KEYSTORE_PASSWORD}

Appenders.Socket.Ssl.TrustStore.location = truststore.p12
Appenders.Socket.Ssl.TrustStore.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.

📖 Plugin reference for Syslog

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

Appenders.Syslog.type = Syslog
Appenders.Syslog.name = SYSLOG
Appenders.Syslog.host = syslog.local
Appenders.Syslog.port = 6514
(1)
Appenders.Syslog.format = RFC5424
Appenders.Syslog.appName = myApp
Appenders.Syslog.facility = DAEMON
Appenders.Syslog.id = Log4j
Appenders.Syslog.newLineEscape = \\n

Appenders.Syslog.Ssl.KeyStore.location = keystore.p12
Appenders.Syslog.Ssl.KeyStore.password = ${env:KEYSTORE_PASSWORD}

Appenders.Syslog.Ssl.TrustStore.location = truststore.p12
Appenders.Syslog.Ssl.TrustStore.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`.