> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.

# Appenders

Appenders determine where and how log events are recorded in the xorlab Security Platform (XSP). They route log data to destinations like files, consoles, remote servers, or databases and specify the format for storing this information.

## Important Tips

* **Be sure to configure the appender before having it referenced from the `logger`**. The `name` attribute of the `appender` should match the  `appender-ref` attribute of the `logger`.

* When multiple appenders are referenced by a single logger, the event is logged to all specified destinations, ensuring redundancy and flexibility in log storage.

* A single appender can be used to log events with any event id.

* XSP logging is built with the Logback framework. For details on each appender, refer to the [Logback Documentation](http://logback.qos.ch/manual/appenders.html)

## Appenders

### Syslog

The syslog appender sends log events to remote destinations and is commonly used to centralize XSP logs in a SIEM.  The following example demonstrates how to configure the syslog appender to send all audit events, formatted as JSON, to the host `syslog.xorlab.com`:

```xml theme={null}
<appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
  <syslogHost>syslog.example.com</syslogHost>
  <port>514</port>
  <hostName>xorlab</hostName>
  <protocol>UDP</protocol>
  <facility>LOCAL0</facility>
  <encoder>
    <pattern>%jsonMsg%n</pattern>
  </encoder>
</appender>

<!-- This will log all audit events through syslog to syslog.xorlab.com -->
<logger name="audit">
  <appender-ref ref="syslogAppender"/>
</logger>
```

The following configuration parameters are supported by the syslog appender:

| Parameter              | Description                                                                                                                                                                                                                                                                                                             |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `syslogHost`           | Mandatory syslog daemon host                                                                                                                                                                                                                                                                                            |
| `port`                 | Configure port of the rsyslog daemon (default: 514)                                                                                                                                                                                                                                                                     |
| `protocol`             | `UDP`, `SSL`, or `TCP` (default: `UDP`)<br />**Note**: Use `AsyncAppender` for SSL and TCP as described in the [TLS Syslog Appender](#syslog-with-tls) section                                                                                                                                                          |
| `hostName`             | Specify a host name to be included in the log. This is important for log source identifiers in SIEM systems.                                                                                                                                                                                                            |
| `facility`             | [Syslog facility](https://en.wikipedia.org/wiki/Syslog#Facility)<br />Pick one of these: `KERN`, `USER`, `MAIL`, `DAEMON`, `AUTH`, `SYSLOG`, `LPR`, `NEWS`, `UUCP`, `CRON`, `AUTHPRIV`, `FTP`, `NTP`, `LOG_AUDIT`, `LOG_ALERT`, `CLOCK`, `LOCAL0`, `LOCAL1`, `LOCAL2`, `LOCAL3`, `LOCAL4`, `LOCAL5`, `LOCAL6`, `LOCAL7` |
| `format`               | Syslog message format: `RFC3164` (default) or `RFC5424`                                                                                                                                                                                                                                                                 |
| `pattern`              | Syslog message payload structure and format (e.g., JSON or CEF). For more information, please see [*Formats*](/9.0/logging-formats)                                                                                                                                                                                     |
| `trustAll`             | Allow the use of unsigned TLS certificates                                                                                                                                                                                                                                                                              |
| `reconnectDelayMillis` | Duration between reconnect attempts in milliseconds (default: 30000)                                                                                                                                                                                                                                                    |
| `immediateFail`        | `true`, `false` (default: `true`). If set to `false`, log messages will be blocked until (re)-connected.<br />**Important**: Only set to `false` while using `AsyncAppender`                                                                                                                                            |
| `messageSizeLimit`     | Optionally constrain message size by truncating it. While using UDP transport, this config's default value is set to 1500 bytes (as this is a common network MTU size). Example: `<messageSizeLimit>1500</messageSizeLimit>`                                                                                            |
| `socketOptions`        | Supports the following two child parameters: `keepAlive` (`true` or `false`, default: `true`) and `tcpNoDelay` (`true` or `false`, default: `false`). Example: `<socketOptions><keepAlive>true</keepAlive></socketOptions>`                                                                                             |

### Syslog with TCP

To send the syslog messages via TCP, you can set the syslog appender's protocol to `TCP`.

<Note>
  **AsyncAppender**

  When using TCP as the protocol for `SyslogAppender`, it’s required to use `AsyncAppender`. This prevents system impairment if the external destination becomes unreachable.
</Note>

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
      <appender name="syslogAppenderTCP" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
        <syslogHost>syslog.example.com</syslogHost>
        <port>514</port>
        <facility>LOCAL0</facility>
        <protocol>TCP</protocol>
        <encoder>
          <pattern>%jsonMsg%n</pattern>
        </encoder>
    </appender> 
    
    <appender name="asyncSyslogAppenderTCP" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="syslogAppenderTCP" />
    </appender>

    <!-- xcc user audit events -->
    <logger name="audit" level="debug" additivity="false">
        <appender-ref ref="asyncSyslogAppenderTCP"/>
    </logger>
</included>
```

### Syslog with TLS

To securely transmit logs to other servers, you can use the TLS protocol by setting the syslog appender’s protocol to `SSL`.

<Note>
  **AsyncAppender**

  When using SSL as the protocol for `SyslogAppender`, it’s required to use `AsyncAppender`. This prevents system impairment if the external destination becomes unreachable.
</Note>

See the example below:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
      <appender name="syslogAppenderTLS" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
        <syslogHost>syslog.example.com</syslogHost>
        <port>514</port>
        <facility>LOCAL0</facility>
        <!-- USE SSL HERE -->
        <protocol>SSL</protocol>
        <encoder>
          <pattern>%jsonMsg%n</pattern>
        </encoder>
    </appender> 
    
    <appender name="asyncSyslogAppenderTLS" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="syslogAppenderTLS" />
    </appender>

    <!-- xcc user audit events -->
    <logger name="audit" level="debug" additivity="false">
        <appender-ref ref="asyncSyslogAppenderTLS"/>
    </logger>

    <!-- Additional logging of failed login attempts -->
    <!-- Enabling additivity will still make the audit logger receive the log events -->
    <!--
    <logger name="audit.access.denied" additivity="true">
        <appender-ref ref="asyncSyslogAppenderTLS"/>
    </logger>
    -->

    <!-- message tracing -->
    <logger name="trace">
        <appender-ref ref="asyncSyslogAppenderTLS"/>
    </logger>

    <!-- threat intelligence events -->
    <logger name="ti">
        <appender-ref ref="asyncSyslogAppenderTLS"/>
    </logger>

    <!-- system events -->
    <logger name="sys">
        <appender-ref ref="asyncSyslogAppenderTLS"/>
    </logger>

</included>
```

### File

The File appender writes log events to a specified file. It’s a straightforward method for persistent log storage. This appender is ideal for keeping long-term logs or when logs need to be archived.

```xml theme={null}
<appender name="fileAppender" class="ch.qos.logback.core.FileAppender">
  <file>${log_dir}/mylogfile.log</file>
  <append>true</append>
  <encoder>
    <pattern>%d{yyyy-MM-dd HH:mm:ss} - %jsonMsg%n</pattern>
  </encoder>
</appender>
```

<Note>
  **Not supported for XSP SaaS**

  The file appender is only available for on-premise deployments of XSP. It is not supported for customers using xorlab's cloud services.
</Note>

### Rolling File

The Rolling File appender extends the File appender, automatically handling file rollovers based on size or time. This is useful for managing log files without manual intervention, preventing them from becoming too large.

```xml theme={null}
<appender name="rollingFileAppender" class="ch.qos.logback.core.rolling.RollingFileAppender">
  <file>${log_dir}/mylogfile.log</file>
  <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
    <fileNamePattern>${log_dir}/mylogfile-%d{yyyy-MM-dd}.%i.log.zip</fileNamePattern>
    <maxFileSize>10MB</maxFileSize>
    <maxHistory>30</maxHistory>
  </rollingPolicy>
  <encoder>
    <pattern>%d{yyyy-MM-dd HH:mm:ss} - %jsonMsg%n</pattern>
  </encoder>
</appender>
```

<Note>
  **Not supported for XSP SaaS**

  The rolling file appender is only available for on-premise deployments of XSP. It is not supported for customers using xorlab's cloud services.
</Note>

### Email

The Email appender sends log events via email. This is particularly useful for critical alerts that require immediate attention. It’s configured to send emails when certain log events are triggered. In the example below, an email containing a summary of the analysis is sent to `example@xorlab` whenever someone reports an email.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>

<included>
  
    <!-- TODO: update property.value with your xorlab url -->
  <property name="host.name" value="example.activeguard.ch"/>
  
  <appender name="smtpMailAppender" class="ch.qos.logback.classic.net.SMTPAppender">
      <!-- TODO: update <to> attribute with the email address of the receiver-->
    <to>example@xorlab.com</to>
          
        <from>no-reply@${host.name}</from>
        <subject>Email reported via ${host.name}</subject>

        <layout class="ch.qos.logback.classic.PatternLayout">
            <!-- feel free to fiddle around here --> 
        <pattern>An email was reported\nDate: %d{yyyy-MM-dd HH:mm}\nLink https://${host.name}/messages/all/message/%X{gr.id} \nSoftware Version: %versionGitDescription\n%jsonMsg\n</pattern>
        </layout>
          
        <smtpHost>mta.activeguard.xor</smtpHost>
        <smtpPort>10026</smtpPort>
        <evaluator class="com.xorlab.sgappliance.shared.logback.evaluator.LevelEvaluator"/>
    </appender>

      <logger name="trace.msg_analysis.complete.reported">
        <appender-ref ref="smtpMailAppender"/>
    </logger>
    
</included>
```