> ## 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.

# Troubleshooting

> Solutions to the most common problems, including editing configuration files when the web interface is unreachable.

## How to change config files in case the web interface is not reachable

When you made changes to config files in XCC [Expert Editor](/latest/expert-editor) and XCC no longer starts due to some errors in the files, you need to access those files from the command line, fix errors, save the files and restart XCC.

The procedure is as follows:

1. Make an SSH connection to your XCC instance.

2. Stop the XCC backend container:

   `cd /etc/xorlab/xcc && docker compose down`

3. Enter the commands listed below:

   `sudo su -s /bin/bash xcc_backend`

   then

   `cd /var/lib/xorlab/xcc/config/work/ag_local/`

4. You are now in the folder containing config files presented in Expert Editor. Find and adjust (with vim) the required file.

5. Enter the commands listed below:

   `git add <changed file>`

   then

   `git commit -m "<comment the change>"`

6. Press **Ctrl+D** to close the current shell (exit).

7. Start the container again:

   `docker compose up -d`

## How to find MTA logs using the command line

If you want to check the MTA logs, you can do this using SSH connection and the following commands in terminal:

1. Go to the right location: `cd /var/log/xorlab/activeguard/core/` for the email processing logs or `cd /var/log/xorlab/activeguard/mta/` for SMTP logs.
2. Make all files visible: `ll`
3. Select the log file of the date relevant to your investigation and open it with `less` (for `.log` files) or `zless` (for `.zip` files).

For a summary of all log file locations in xorlab, please have a look at [Operation Guide](/latest/operation-reference#log-files).

## How to connect to MTA GUI

You can connect with your MTA GUI using the following URL: `your.domain.name:8443`. Keep in mind that the URL might differ if you change the setup.

## How to find a GGRID of an email

You can use a unique identifier (GGRID) of an email used by xorlab to make your search easier in the core logs:

1. Go to XCC in your browser.

2. Select the email you are looking for so that it opens on the **Message Detail** page.

3. In the address bar of your browser you will see the GGRID of this email. It can be used to find the specific email in the core logs, for example using the `grep <ggrid> activeguard.log` command.

   <img src="https://mintcdn.com/xorlab/O_O2TUa6eRBR54aI/latest/assets/mail-grrid.png?fit=max&auto=format&n=O_O2TUa6eRBR54aI&q=85&s=8b34c7758a5d49f1dc92b0f7349e7ff4" alt="Mail GGRID" width="1001" height="416" data-path="latest/assets/mail-grrid.png" />

   *Mail GGRID*

## An email didn’t appear in a user’s inbox

If a message got lost on the way to a user’s inbox, you can search for some information:

1. We recommend to start checking the main XCC web interface if the email can be retrieved. You could search for the sender or even refine your query to find the exact email—please see [Search](/latest/search).

   <img src="https://mintcdn.com/xorlab/O_O2TUa6eRBR54aI/latest/assets/lost-email-search.png?fit=max&auto=format&n=O_O2TUa6eRBR54aI&q=85&s=5e05bc9a7f7e2e95124b892f39679165" alt="Searching for a lost email" width="1383" height="561" data-path="latest/assets/lost-email-search.png" />

2. If you find the email and it's status is `DELIVERED`, it means that xorlab could send the email successfully to the next hop. In all other cases, proceed below.

3. Start [checking the SMTP logs](#how-to-find-mta-logs-using-the-command-line) to see if the email arrived at xorlab and whether postfix could forward it to the core or not. SMTP logs are available on MTA: `/var/log/xorlab/activeguard/mta/mail.info`.

4. Check SMTP logs if the core sent the email back to postfix after processing and whether postfix could forward the email to the external system: use `grep` for `message-id` in `mail.info`. There should be two entries: one when the email arrives at postfix, and one when it is coming from the core. Verify that the email has been forwarded to the external destination.

5. If the email got stuck on the core, then [check the Processing log](#how-to-find-mta-logs-using-the-command-line) (`activeguard.log`). Processing logs on MTA are located here: `/var/log/xorlab/activeguard/core/activeguard.log`. We recommend to `grep` for the [email GGRID](#how-to-find-a-ggrid-of-an-email) to find all logs for a specific email (`zgrep <ggrid> <logfile.zip>`, e.g., `zgrep 7ce1d657-3a0b-48d3-9bbe-cea302d535db activeguard_2022-05-11.0.log.zip`).

## SSQ no mailbox configured error

If you open the SSQ and see the following error

<img src="https://mintcdn.com/xorlab/O_O2TUa6eRBR54aI/latest/assets/error-no-mailbox-config.png?fit=max&auto=format&n=O_O2TUa6eRBR54aI&q=85&s=6f896df98e260a91e843d4b57f46331b" alt="No mailbox configured error message" width="1171" height="692" data-path="latest/assets/error-no-mailbox-config.png" />

This means that your user has an empty `emails` attribute. This attribute is populated as part of the login mechanism. Follow the guide below to see how to configure it for your login mechanism:

* [SAML login](/latest/authentication-saml#attribute-mapping)
* [LDAP login](/latest/authentication-ldap#attribute-mapping)
* [Local user](/latest/authentication-with-a-password-file#quickstart)

## What to do with external blacklist false positives

When an external service such as Spamhaus flags some messages as spam, but their senders are legitimate, you can use a special whitelist called [Spam blacklist exclusion](/latest/whitelists#spam-blacklist-exclusion)—simply add domains that should be excluded from the spam blacklist.

## How to view the current permissions of a user

To check what permissions a particular user has:

1. Log in to xorlab as the said user.

2. Go to the `/api/v2/user/v1/getInfo` endpoint on your xorlab instance, e.g., `xyz.activeguard.cloud/api/v2/user/v1/getInfo`.

3. You will see a list of permissions:

   <img src="https://mintcdn.com/xorlab/O_O2TUa6eRBR54aI/latest/assets/checking-user-permissions.png?fit=max&auto=format&n=O_O2TUa6eRBR54aI&q=85&s=ca745028f8561deb8092b98290c2293b" alt="Checking the permissions of a user" width="584" height="478" data-path="latest/assets/checking-user-permissions.png" />

To learn more about them, please refer to [List of Built-in Permissions](/latest/create-custom-user-role#permissions-role-matrix).

## SAML ADFS troubleshooting

1. Use the URL claims from the authentication success log for the `attributeMapping`.

2. Make sure the user is allowed to authenticate: check the logs on the AD side to ensure that the user has the required permissions.

3. Install a SAML Tracer browser add-on. A SAML Tracer is a tool designed for debugging and analyzing Security Assertion Markup Language (SAML) communications between a service provider (SP) and an identity provider (IdP). This tool is especially useful in Single Sign-On (SSO) and federation services, where SAML is often used to convey authentication and authorization data.

   As you authenticate or complete the SAML exchange, the extension will capture and display the SAML messages. You can click any captured message to view the detailed contents of the SAML assertions, requests, and responses.

4. Enable extensive debug logs for SAML authentication. Contact [support@xorlab.com](mailto:support@xorlab.com) for the required configuration.

5. Check the ADFS configuration: xorlab requires `nameID`. Make sure `nameID` is sent in the response; it might be necessary to create a new property for it if xorlab says the subject is missing. For more information, please refer to [Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/saml-claims-customization).