> ## 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. # Configure Tenant Domains and Routing > Configure tenant domains and SMTP routing for each supported multi-tenant topology. The configuration is different depending on the topology. Choose the one below that fits your setup best. ## Deployment Topologies The xorlab Security Platform supports several deployment options. If you're unsure which to choose, we recommend starting with the `Default Chain`. * [Default Chain](#default-chain-topology): xorlab is located between your gateway and the internal mailbox server like Exchange. * [Microsoft 365](#m365-topology): xorlab is integrated directly with M365 via connectors. * [Star](#star-topology): A central gateway integrates xorlab in a Star layout. * [Front MTA](#front-mta-topology): xorlab is the gateway (front MTA) and receives emails directly from the internet. * [Full Chain](#full-chain-topology): Same as Default Chain, but inter-tenant emails pass twice through xorlab. ### Default Chain Topology #### Guarded Tenants `name`: Define the name of the tenant. Also visible in the web interface. `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first. `tenantSelector`: Reference the `headerName` and `headerValue` of a header that will be used to identify the tenant. ```yaml /shared/guarded_tenants.yml theme={null} # Config example for Default Chain Topology ## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant. configSets: default: tenantSelector: - headerName: "x-xor-trusted-client" headerValue: "trusted" ### Begin Tenant Config tenants: - name: tenantA domains: - tenantA.com - tenantA.ch - name: tenantB domains: - tenantB.com - tenant-B.net ``` #### Transport Map The transport map is used to ensure that incoming emails are delivered to the appropriate next-hop destination (such as the front MTA) based on the recipient’s domain. * Define a rule for each guarded domain, specifying the correct next-hop destination. * Use the `smtp` command to specify the SMTP endpoint (e.g., the front MTA). * The last line should be a default route to handle outgoing email traffic. ```yaml /activeguard/mta/startup_cfg/postfix_custom/transport theme={null} # Route incoming emails to the SMTP endpoints of each tenant domains tenantA.ch smtp: tenantA.com smtp: tenantB.com smtp: tenantB.net smtp: # Define a default route for all outgoing emails * smtp: ``` #### Client Access Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems. * Specify the IP address of the SMTP client, typically the Front MTA or Exchange Server, responsible for routing emails to xorlab. * Use the `permit` command to allow these connections to access xorlab and forward emails. ```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access theme={null} ## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format: # 1.2.3.4 permit # 1.2.3 permit # 1.2 permit # 1 permit ## Add the IP address of each front MTA that receives emails and forward them to xorlab permit permit ``` #### Client Access Tenant This file defines which headers xorlab should add to incoming and outgoing emails. * Structure: ` PREPEND : ` * The `` specifies the IP range of the SMTP client responsible for routing emails to xorlab * Add `/32` to restrict to a single IP address. * The `` and `` refer to the `tenantSelector` or the `tenantSelectors`. * The file should always end with an `0.0.0.0/0` entry to prevent header spoofing. ```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access_tenant theme={null} # Allow-list specific SMTP clients for Multi-tenant deployments 198.51.100.1/32 PREPEND x-xor-trusted-client: trusted 192.0.2.1/32 PREPEND x-xor-trusted-client: trusted 203.0.113.1/32 PREPEND x-xor-trusted-client: trusted # Always include a 0.0.0.0/0 entry in the end of this file to sanitize the headerValue 0.0.0.0/0 PREPEND x-xor-trusted-client: unknown ``` When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute. ### M365 Topology #### Guarded Tenants `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first. `tenantSelectors`: Refer to the x-originatororg header of each accepted domain in your Microsoft Exchange environment. * Go to admin.cloud.microsoft/exchange#/accepteddomains * For **each domain listed**, define a separate `selector` in `guarded_tenants.yml` * Use the following format for each selector: * HeaderName: `"x-originatororg"` * Header value: The domain listed in the "Accepted Domain" column, between double quotation marks. ```yaml /shared/guarded_tenants.yml theme={null} tenants: - name: tenantA domains: - tenantA.com - tenantA.ch tenantSelectors: - selector: - headerName: "x-originatororg" headerValue: "tenanta.com" - selector: - headerName: "x-originatororg" headerValue: "tenantaaa.onmicrosoft.com" - name: tenantB domains: - tenantB.com - tenantB.net tenantSelectors: - selector: - headerName: "x-originatororg" headerValue: "tenantb.com" - selector: - headerName: "x-originatororg" headerValue: "tenantbbb.onmicrosoft.com" ``` #### Header Checks This config file contains the routing rules of your mail flow. It refers to the headers specified for each tenant in the previous step. * `x-originatororg` should correspond to the `headerName` of the `tenantSelectors` defined in `guarded_tenants`. * `tenantA.com` and `tenantB.com` should correspond to the `headerValue` of the `tenantSelectors` defined in `guarded_tenants`. * `tenant` `a/b` `-com.mail.protection.outlook.com` should correspond to the SMTP endpoint (MX server) of the `headerValue` of the `tenantSelectors` defined in `guarded_tenants`. ```yaml /activeguard/mta/startup_cfg/postfix_custom/header_checks_core theme={null} # Header-based routing # Define mail routes as specified in the shared/guarded_tenants.yml /^x-originatororg: tenantA.com/ FILTER smtp:tenanta-com.mail.protection.outlook.com /^x-originatororg: tenantaaa.onmicrosoft.com/ FILTER smtp:tenantaaa.mail.protection.outlook.com /^x-originatororg: tenantB.com/ FILTER smtp:tenantb-com.mail.protection.outlook.com /^x-originatororg: tenantbbb.onmicrosoft.com FILTER smtp:tenantbbb-com.mail.protection.outlook.com ``` When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute. ### Star Topology #### Guarded Tenants `name`: Define the name of the tenant. Also visible in the web interface. `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first. `tenantSelector`: Identifies the header that will be set when the email is coming from the trusted infrastructure. ```yaml /shared/guarded_tenants.yml theme={null} configSets: default: tenantSelector: - headerName: "x-xor-trusted-client" headerValue: "trusted" tenants: - name: tenantA domains: - tenantA.com - tenantA.ch - name: tenantB domains: - tenantB.com - tenantB.net ``` #### Transport Rules The transport rules for a multi-tenancy star integration only require one route that redirects all traffic to the central email gateway. * The `*` wildcard matches all traffic. * `` should contain the domain of the central email gateway. ```yaml /activeguard/mta/startup_cfg/postfix_custom/transport theme={null} # Make sure a default route is defined. * smtp: ``` #### Client Access Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems. * Specify the IP address of central gateway that will send emails to xorlab. * Use the `permit` command to allow these connections to access xorlab and forward emails. ```yaml activeguard/mta/startup_cfg/postfix_custom/client_access theme={null} ## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format: # 1.2.3.4 permit # 1.2.3 permit # 1.2 permit # 1 permit ## Add the IP address of each front MTA that will send emails to xorlab permit permit ``` When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute. ### Front MTA Topology #### Guarded Tenants `name`: Define the name of the tenant. Also visible in the web interface. `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first. `tenantSelector`: Reference the `headerName` and `headerValue` of a header that will be added by xorlab. > The headers referenced in `tenantSelector` need to match the entries in the `client_access_tenant` configuration. ```yaml /shared/guarded_tenants.yml theme={null} ## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant. configSets: default: tenantSelector: - headerName: "x-xor-trusted-client" headerValue: "trusted" tenants: - name: tenantA domains: - tenantA.com - tenantA.ch - name: tenantB domains: - tenantB.com - tenant-B.net ``` #### Client Access Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems. * Specify the IP address of the allowed SMTP client, typically the Exchange server. * Use the `permit` command to allow these connections to access xorlab and forward emails. ```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access theme={null} ## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format: # 1.2.3.4 permit # 1.2.3 permit # 1.2 permit # 1 permit ## Add the IP address of each server that will send emails to xorlab permit permit ``` #### Client Access Tenant This file defines which headers xorlab should add to incoming and outgoing emails. * Structure: ` PREPEND : ` * The `` specifies the IP range of each tenant's mail server * Add `/32` to restrict to a single IP address. * The `` and `` refer to the `tenantSelector` or the `tenantSelectors`. * The file should always end with an `0.0.0.0/0` entry to prevent header spoofing. ```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access_tenant theme={null} # Allow-list specific SMTP clients for Multi-tenant deployments 198.51.100.1/32 PREPEND x-xor-trusted-client: trusted 192.0.2.1/32 PREPEND x-xor-trusted-client: trusted 203.0.113.1/32 PREPEND x-xor-trusted-client: trusted # Always include a 0.0.0.0/0 entry in the end of this file to sanitize the headerValue 0.0.0.0/0 PREPEND x-xor-trusted-client: unknown ``` #### Transport Map The transport map is used to ensure that incoming emails are delivered to the appropriate next-hop destination (such as the front MTA) based on the recipient’s domain. * Define a rule for each guarded domain, specifying the correct next-hop destination. * Use the `smtp` command to specify the SMTP endpoint (e.g., the front MTA). ```yaml /activeguard/mta/startup_cfg/postfix_custom/transport theme={null} # Route incoming emails to the SMTP endpoints of each tenant domains tenantA.ch smtp: tenantA.com smtp: tenantB.com smtp: tenantB.net smtp: ``` When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute. ### Full Chain Topology In the Full Chain Topology xorlab sits between a front MTA and the Exchange server. The difference to the default chain is that inter-tenant emails are routed to the front MTA and back. Important: the front MTA needs to strip away all x-xor-trusted-client headers from all emails to ensure proper routing. #### Guarded Tenants `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first. `tenantSelector`: If needed, reference a unique trusted `headerName` and `headerValue` for specific tenants. `interTenantMessageSplitting`: Controls whether xorlab splits emails sent between tenants into separate incoming and outgoing messages. By default, this attribute is set to `true` but for the `Full Chain Topology` you are required to set it to `false`. `configSets` - `tenantSelector`: Reference the `headerName` and `headerValue` of a header that will be added by xorlab. > The headers referenced in `tenantSelector` and `tenantSelectors` need to match the entries in the `client_access_tenant` configuration. ```yaml /shared/guarded_tenants.yml theme={null} ## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant configSets: default: # This is required when inter-tenant emails are passing through xorlab twice interTenantMessageSplitting: false tenantSelector: - headerName: "x-xor-trusted-client" headerValue: "trusted" tenants: - name: tenantA domains: - tenantA.com - tenantA.de - name: tenantB domains: - tenantB.com - tenantB.net ``` #### Header Checks This config file defines how messages are routed based on the headers assigned in guarded\_tenants.yml. * Structure: `/^:/ FILTER smtp:[]` * The `` should include the domain of either the frontMta or the guarded domain's mail server. ```yaml /activeguard/mta/startup_cfg/postfix_custom/header_checks_core theme={null} # Header-based routing /^x-xor-trusted-client: unknown/ FILTER smtp: /^x-xor-trusted-client: trusted/ FILTER smtp: ``` #### Client Access Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems. * Specify the IP address of the SMTP client, typically the Front MTA or Exchange Server, responsible for routing emails to xorlab. * Use the `permit` command to allow these connections to access xorlab and forward emails. ```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access theme={null} ## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format: # 1.2.3.4 permit # 1.2.3 permit # 1.2 permit # 1 permit ## Add the IP address of each front MTA that receives emails and forward them to xorlab permit permit ``` #### Client Access Tenant This file defines which headers xorlab should add to incoming and outgoing emails. * Structure: ` PREPEND : ` * The `` specifies the IP range of the **Exchange Server**. * Add `/32` to restrict to a single IP address. * The `` and `` refer to the `tenantSelector` or the `tenantSelectors`. * The file should always end with an `0.0.0.0/0` entry to prevent header spoofing. ```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access_tenant theme={null} # Set the Exchange servers as trusted. Do not add the front MTA as trusted. 198.51.100.1/32 PREPEND x-xor-trusted-client: trusted 192.0.2.1/32 PREPEND x-xor-trusted-client: trusted # Always include a 0.0.0.0/0 entry in the end of this file to prevent spoofing of the headerValue 0.0.0.0/0 PREPEND x-xor-trusted-client: unknown ``` When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute. ## How to define tenant selectors Tenant selectors are used to assign emails to the correct tenant by evaluating specific mail headers. There are two configuration options: * `tenantSelector`: Defines a single set of headers that must all match to assign the message to a tenant (AND logic). * `tenantSelectors`: One property that enables you to define more then one `selector`. A `selector` can reference one or more header sets. If multiple header sets are referenced, all need to match (AND-logic). The message matches a tenant if at least one `Selector` matches (OR logic). Both options can be used for a specific tenant, as well as default within `configSets`. **Avoid External Header Manipulation** Only use sanitized and trusted mail headers for tenant identification. Never rely on headers that could be set or modified by external senders. ```yaml /shared/guarded_tenants.yml theme={null} ## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant. ## In this example, it applies to tenant C and D. configSets: default: tenantSelector: - headerName: "x-xor-trusted-client" headerValue: "trustedMailRoute" tenants: - name: tenantA domains: - tenantA.com # Assigned to tenantA only if both headers match (AND logic) tenantSelector: - headerName: "x-xor-trusted-client" headerValue: "specialRoute" - headerName: "another-trusted-header" headerValue: "i-know-this-is-tenantA" - name: tenantB domains: - tenantB.com # Assigned to tenantB if either of these selectors match (OR logic between selectors) tenantSelectors: - selector: - headerName: "x-xor-trusted-client" headerValue: "specialRoute2" - selector: - headerName: "x-xor-trusted-client" headerValue: "specialRoute3_part1" - headerName: "another-trusted-header" headerValue: "specialRoute3_part2" - name: tenantC domains: - tenantC.com - name: tenantD domains: - tenantD.com ``` After updating `shared/guarded_tenants.yml`, click **Publish**. The new configuration becomes active within about one minute. ### Explanation of tenant selection logic When processing an email, the system determines which Tenant it belongs to based on the following rules. **Step 1: Single Match:** If exactly one Tenant Selector matches the email, the email is assigned to that Tenant. **Step 2: No Match:** If no Tenant Selector matches the email, choose the Tenant based on the recipient addresses. If no Tenant can be identified, assign the email to the special `UNKNOWN` Tenant. **Step 3: Multiple Matches:** If multiple Tenant Selectors match, the selection is resolved using the logic below in the specified order. 1. Assign Tenant based on sender address. 1. Prefer a match on the sender’s envelope-from address. 2. If no match, check the header-from address. 2. Assign Tenant based on recipient addresses. Choose only from the matched Tenant Selectors. 3. If no Tenant can be identified, assign the email to the special `UNKNOWN` Tenant. **Recipient address matching** For step 2 and 3: If the Tenant is chosen based on the recipients, and the recipients belong to different Tenants, the email is split for each Tenant. Each split email is assigned a separate GGRID and will be shown as separate email in the web interface. After the tenant is selected, the email is processed. Because the email can have multiple different recipients, even from different tenants, xorlab applies the following logic when delivering emails: * For all recipients of the email that do not match any tenants (outgoing email) or match the tenant of the email itself (internal or incoming email), deliver the email. * For all recipients of the email that match a different tenant than the one of the email itself (inter-tenant email): * If `interTenantMessageSplitting` is active, re-process the email again with a separate `GGRID` and assigned to the recipient tenant. No email delivery at this point. * Else deliver the email. We expect the email to pass again through xorlab.