> ## 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 Stuck in an issue you can’t solve? Here you will find solutions for the most common problems with the following distinction: * issues marked as `OP` are related to on-prem instances only, * issues marked as `C` are related to cloud (SaaS) instances only. If no mark is present, then the solution can be applied to both types of XSP instances. ## How to change config files in the command line in case GUI is not reachable When you made changes to config files in XCC [Expert Editor](/9.0/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` then `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 ` then `git commit -m «»` 6. Press **Ctrl+D** to close the current shell (exit). 7. Start the container again: `docker compose up -d` 8. Restart XCC (see *[Operation Guide](/9.0/operation-guide)* for information on how to do it). ## Solving the campaign “filter not supported” error When you want to add a campaign but you get an error that reads `The query contains a filter that is not supported for a campaign`, please have a look at *[Query Based Classifiers (Campaigns)](/9.0/query-based-classifiers)*. If no solution can be found, please contact [support@xorlab.com](mailto:support@xorlab.com). ## No emails received in the organization When email flow isn’t working and no emails are received throughout your organization, please follow these steps: 1. In the Grafana dashboard, check if the email flows are running correctly. 2. Follow the instructions from the *[An email didn’t appear in a user’s inbox](#an-email-didnt-appear-in-a-users-inbox)* section. 3. Log in to the MTA GUI. On the button configuration and system test page you got the possibility to do a health check of the email flow. 4. Observe in the command line if all servers are running properly via the `docker ps` command. For further reset commands please see *[Operation Guide](/9.0/operation-guide#mta_1)*. ## Solving problems using log files (`OP`) For an overview of our architecture and for the exact commands, please see *[Operation Guide](/9.0/operation-guide#mta_1)*. ### 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 Security Platform, please have a look at *[Operation Guide](/9.0/operation-guide#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 defer 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 Security Platform 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 activeguard.log` command.

*Mail GRRID* ### 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](/9.0/search)*.

*Searching for a lost email* 2. If nothing can be found, get the message ID in the interface to simplify your search in the SMTP logs. Open the email in XSP and select the **Headers** tab:

*Headers tab* 3. Scroll down until you see the message ID:

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

*SMTP logs* 5. 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.

*Mail transport history* 6. 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 `, e.g., `zgrep 7ce1d657-3a0b-48d3-9bbe-cea302d535db activeguard_2022-05-11.0.log.zip`). Once you discovered the email, please look at its status. We highly recommend to check the xorlab Security Platform error logs, logs for that specific day or use the `grep` command to make your troubleshooting easier. ### Functionality doesn’t work in the GUI If some feature such as establishing a campaign doesn’t work in the graphical interface, please check the XCC backend logs for any errors: * `/var/log/xorlab/xcc/backend/xcc.log` * `/var/log/xorlab/xcc/backend/xcc_err.log` You could try to reproduce the error and monitor it in the logs. ### Sandbox doesn’t scan documents Please see *[xorlab Sandbox](/9.0/dynamic-analysis)*. ### Users can’t log in with SAML or LDAP If users can’t login to SSQ or XCC GUI: 1. Depending on your SSQ setup, please verify if users are set up correctly in your AD, LDAP, and SAML settings as well as in the `auth.yml` and `passwordFile.yml` files in the XCC [Expert Editor](/9.0/expert-editor). 2. Check the log files for errors: * auth log on XCC: `/var/log/xorlab/auth/auth/auth.log` * backend log on XCC: `/var/log/xorlab/backend/xcc.log` and `xcc_err.log` ## SSQ login error Customers trying to set up our self-service portal or adding new users sometimes have experienced an error that no mailbox is configured. This happens when the user authentication has not been set up to provide the list of mailboxes that a user can see in the self-service portal. Please see the error below: No mailbox configured error message

This can be solved by making sure to populate the emails attribute as described in these articles: * *[SAML Authentication Using AAD Services](/9.0/saml-aad-authentication)* in the case of Azure. * *[SAML-based Authentication](/9.0/saml-based-authentication)* for other auth providers. ## How to disable the WAL directory cleanup (`OP`) On MTA instances, we delete the WAL directory at every startup by default to prevent Prometheus from consuming too much memory. We don’t recommend deactivating this feature, but in case it’s absolutely necessary, set the `DELETE_WAL_AT_STARTUP` env variables to `never` for the Prometheus service in the Monitored MTA `docker-compose.yml` file, i.e.: ```yml theme={null} services: ... prometheus:: ... environment: - DELETE_WAL_AT_STARTUP=never ``` On XCC instances, loading the head block from the WAL at startup might require up to \~5 GB of RAM. If this amount of memory is not available, Prometheus process would be killed. To avoid this, run the following command as the `admin` user: ```shell theme={null} docker exec monitoring_prometheus rm -rvf /prometheus/wal ``` ## List of supported browsers If you want to know which browsers are supported by xorlab Security Platform, type this URL in a tab where you are already logged in to XSP and replace `xyz` with your customer ID: `https://xyz.activeguard.cloud/supported-browsers.txt` If you are not signed in, you will be redirected to the login page. ## 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*](/9.0/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 AG as the said user. 2. Go to the `/api/v2/user/v1/getInfo` endpoint on your AG instance, e.g., `xyz.activeguard.cloud/api/v2/user/v1/getInfo`. 3. You will see a list of permissions: Checking the permissions of a user

To learn more about them, please refer to [Users, Roles, and Permissions](/9.0/users-roles-and-permissions). ## How to use group names for XCC roles This method is not recommended due to issues it may cause. If you want to use existing groups in AAD for [SAML authentication and role assignment](/9.0/saml-aad-authentication), you can simply include the information about the group(s) a user belongs to in the SAML token, then map these groups to XCC roles in the xorlab Security Platform configuration file as if their names were role aliases. Let’s start with adding the information about groups to the SAML auth token: 1. Similarly to [SSQ integration](/9.0/saml-aad-authentication#ssq-integration), after completing the last step in the [basic SAML configuration](/9.0/saml-aad-authentication#creating-a-saml-app-in-ad), move down to the next section of the **SAML-based Sign-on** page called **Attributes & Claims** and click **Edit**:

*Attributes & Claims section* 2. On the **Attributes & Claims** page, click **Add a group claim**:

*Add a group claim* 3. In the input fields of the **Group claims** page that appears, set the following options: * **For hybrid/on-prem environments:** click to select **All groups** or **Security groups** depending on your setup, then select **sAMAccountName** from the **Source attribute** drop-down list. Managing claims

*Adding a group claim* * **For cloud environments:** click to select **Groups assigned to the application**, then select **sAMAccountName** from the **Source attribute** drop-down list, and click to check the **Emit group name for cloud-only groups** option. Managing claims

*Adding a group claim* Click **Save**. 4. If you have a cloud environment and selected **Groups assigned to the application** in the previous step, you must assign groups to this application by clicking **Users and groups** in the left pane and then adding the desired groups. 5. Now, follow the steps outlined in [*Configuring XSP to use the AD SAML app*](/9.0/saml-aad-authentication#configuring-xorlab-to-use-the-ad-saml-app) to use the group claim as the source of roles and then map the group names to XCC roles. Make sure to: * Change the `attributeMapping.roles` value in the `auth.yml` file to: ```yaml theme={null} roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/groups) ``` This way, your group names will be read as roles. * Also, look at the example below to see how you might assign role aliases when you are using existing group names such as `IT_monitoring`, `sec_analysts`, or `org_admins`: ```yaml theme={null} roleMapping: xcc_admin: - org_admins xcc_analyst: - sec_analysts xcc_monitor: - IT_monitoring - org_admins xcc_insights: - sec_analysts - org_admins xcc_quarantine_user: - org_users ``` Your `auth.yml` should look like the one below: ```yaml theme={null} tokenSigningKey: ****************************** tokenTtl: 60 enabledAuthBackends: - azureSaml saml2AuthBackends: azureSaml: idp: #Enter the App Federation Metadata Url from M365 metadataUrl: https://login.microsoftonline.com/***************************** attributeMapping: displayName: attr('http://schemas.microsoft.com/identity/claims/displayname') emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name') roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/groups') roleMapping: xcc_admin: - org_admins xcc_analyst: - sec_analysts xcc_monitor: - IT_monitoring - org_admins xcc_insights: - sec_analysts - org_admins xcc_quarantine_user: - org_users ```