> ## 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. # SMTP Configuration This page guides you through the SMTP configuration of xorlab Security Platform. In case you are only interested in a specific configuration, use the following shortcuts: * [Email routing](#email-routing) * [Sender and recipient restrictions](#sender-and-recipient-restrictions) * [TLS configuration](#tls-configuration) Remember that **the only required action is to configure [SMTP hostname](/9.0/vm-setup-guide#ehlo-configuration) and [email routing](#email-routing)**. All other configurations are optional. xorlab Security Platform internally uses [Postfix](http://www.postfix.org/) to accept, route, and send emails. Therefore, we recommend that you make yourself familiar with the basics of email routing in Postfix. Good starting points are: * [General Postfix documentation](http://www.postfix.org/documentation.html). * [Transport maps](http://www.postfix.org/postconf.5.html#transport_maps) with [transport](http://www.postfix.org/transport.5.html) for standard recipient based routing. * [Configuration parameters](http://www.postfix.org/postconf.5.html) for looking up specific Postfix parameters. However, for all common use cases, you can still follow this guide without any Postfix knowledge. The different configuration files for email routing and SMTP, in general, are exposed in [Expert Editor](/9.0/expert-editor) under `activeguard/mta/startup_cfg/postfix_custom`: Postfix configuration files for SMTP ## Email routing The email routing configuration depends largely on the integration, i.e., where the XSP instance is located within your mail environment and how it communicates with other elements. All possible deployments are covered in *[Integrations overview](/9.0/integrations-overview)* and your routing configuration should reflect the deployment: * [Internal MTA](#internal-mta)—emails are delivered to the next hop, e.g., inbound emails to an internal Exchange server, outbound to the internal email gateway. * [Microsoft 365](#microsoft-365)—self-explanatory: XSP communicates with M365. * [Gateway](#gateway)—outbound emails are delivered directly to the external recipient, inbound ones to a static next hop, for example, to an internal Exchange server. * [Star integration](#star-integration)—all emails (inbound and outbound) are delivered to the same destination (next hop). This is typically the case when XSP is integrated into a self-hosted mail infrastructure, with all email traffic going via one mail server, or in an M365 integration when only one domain is used. * [Monitoring mode](#monitoring-mode)—self-explanatory: emails are forwarded to XSP, but no actions are taken (messages are deleted/dropped after processing). There’s also a special case, [sender-based routing](#special-case-sender-based-routing), which is usually used in addition to internal MTA or gateway setups to address very specific routing needs. **The most important settings** Here are the two most important configurations that you have to set for every integration: * **Access control** which answers the question “*what emails are accepted?*”. This is done either in the `client_access` file or using `relay_domains` in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file. * **Next hop** which answers the question “*where are emails sent to?*”. This is done either via transport maps or using `relayhost` in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file. After you have configured the email routing, the mandatory SMTP configuration is done. The remaining sections cover additional configuration for more advanced requirements. #### Next hop syntax Before we start with the routing configuration, please be aware of the following possibilities to specify a next-hop destination. This will be useful throughout all routing configuration: | Format | Example | Description | | :--------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Domain` | `gateway.xorlab.com` | Look up the destination through DNS MX records of the domain. This provides the most flexibility and automatic fallback if there are multiple MX records specified | | `[Domain]` | `[gateway.xorlab.com]` | Look up the destination through DNS A records of the domain | | `[IP]` | `[1.2.3.4]` | Use the IP address directly as the next destination | For more details information about the syntax, please refer to the [Postfix documentation](http://www.postfix.org/lmtp.8.html). ### Common scenarios You can set the email routing based on specific setups and needs. Just go to the section that reflects how XSP is integrated in your environment and you will find a proper config. #### Internal MTA In this scenario, xorlab Security Platform will: * Deliver inbound emails to the next hop (referred to as ``), for example, to an internal Exchange server. * Deliver outbound emails to the next hop (referred to as ``), for example, to the internal email gateway. First, enable the transport maps in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file: ``` transport_maps = lmdb:/etc/postfix/transport ``` If the `activeguard/mta/startup_cfg/postfix_custom/transport` file does not exist, you have to create it. Then, in [Expert Editor](/9.0/expert-editor): 1. Open the `activeguard/mta/startup_cfg/postfix_custom/client_access` file and add one line, like shown below, for every internal email server that will send emails to xorlab Security Platform (inbound and outbound): ```shell theme={null} ## Permit this IP to send emails through xorlab Security Platform ## 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 permit permit ``` 2. Open the `activeguard/mta/startup_cfg/postfix_custom/transport` file. Add a line for every guarded tenant domain with `` and one line for all outgoing emails with ` xorlab.net smtp: # Outbound emails * smtp: ``` **Subdomains** By default, subdomains do not match the parent domain in the `transport` file. For example, `test.xorlab.com` would be routed as an outbound email in the example above. Please see *[Subdomain matching](#subdomain-matching)* for more details. **Fallback** You can specify multiple next hops in the `transport` file that will serve as a fallback if the first destination is not reachable: `smtp:[1.2.3.4],[2.2.2.2]`. #### Microsoft 365 If you have only one Guarded Tenant Domain, use the [star integration](#star-integration) configuration to route all emails (incoming and outgoing) to Microsoft 365. The configuration then looks like this: ```shell theme={null} # Route all emails to M365 (incoming and outgoing emails) * smtp:xorlab-com.mail.protection.outlook.com ``` If you have multiple domains, you have to configure [internal MTA](#internal-mta) or [gateway](#gateway) setup as well as [sender based routing](#special-case-sender-based-routing) to make sure that the emails for your different domains are routed to the correct Microsoft 365 tenant. The following examples are for the `xorlab.com` and `xorlab.net` domains: * `activeguard/mta/startup_cfg/postfix_custom/transport` file ```shell theme={null} xorlab.com smtp:xorlab-com.mail.protection.outlook.com xorlab.net smtp:xorlab-net.mail.protection.outlook.com ``` * `activeguard/mta/startup_cfg/postfix_custom/sender_dependent_transport` file ```shell theme={null} @xorlab.com xorlab-com.mail.protection.outlook.com @xorlab.net xorlab-net.mail.protection.outlook.com ``` In the case of a scenario with multiple domains, you also need to set the `relayhost` parameter in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file to make sure that outgoing bounce emails are also sent to Microsoft 365: ```shell theme={null} # Fallback when none of the entries in transport and sender_dependent_transport match (i.e., for outgoing bounce emails) # Use any of your M365 tenants as domain relayhost = xorlab-com.mail.protection.outlook.com ``` In the same `activeguard/mta/startup_cfg/postfix_custom/main.cf` file, configure TLS certificates required by M365: ```shell theme={null} smtpd_tls_cert_file=/etc/ssl/my_certs/my_cert.crt smtpd_tls_key_file=/etc/ssl/my_certs/my_cert.key smtp_tls_security_level = encrypt smtpd_tls_security_level = encrypt ``` #### Gateway In this scenario, xorlab Security Platform will: * Deliver outbound emails directly to the external recipient. * Deliver inbound emails to a static next hop (referred to as ``), for example, to an internal Exchange server. First, enable the transport maps in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file: ``` transport_maps = lmdb:/etc/postfix/transport ``` If the `activeguard/mta/startup_cfg/postfix_custom/transport` file does not exist, you have to create it. Then, in [Expert Editor](/9.0/expert-editor): 1. Open the `activeguard/mta/startup_cfg/postfix_custom/client_access` file and add one line, like shown below, for every internal email server that will send outbound emails to XSP. Those are usually the same servers that XSP will send inbound emails to (``). You can also add: ```shell theme={null} ## Permit this IP to send emails through xorlab Security Platform ## 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 permit permit #You can also permit domains. The domain name is determined by means of a reverse DNS lookup and automatically extends to subdomains. example.com permit ``` This will ensure that xorlab Security Platform relays emails to the internet only from your internal servers. 2. Edit `activeguard/mta/startup_cfg/postfix_custom/transport` and, for every Guarded Tenant Domain, add a line with your internal next-hop destination: ```shell theme={null} # Inbound emails xorlab.com smtp: xorlab.net smtp: ``` As explained before, `` can be substituted with any format described in *[Next hop syntax](#next-hop-syntax)*. 3. In the last step, open the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file and add all Guarded Tenant Domains as `relay_domains`: ```shell theme={null} # Only add domains to the relay_domains, this will automatically include subdomains as well relay_domains = xorlab.com, xorlab.net ``` By setting up `relay_domains`, you ensure that xorlab will accept all emails going to those domains via SMTP. #### Star integration With a static relay host configuration, xorlab Security Platform will route all emails (inbound as well as outbound) to the same next hop (referred to as ``). 1. Specify the next-hop destination in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file: ```shell theme={null} ## Routing relayhost = ``` 2. Add the IP address or domain of the `` to the `activeguard/mta/startup_cfg/postfix_custom/client_access` file: ```shell theme={null} ## Permit this IP to send emails through xorlab Security Platform permit ``` #### Monitoring mode In monitoring mode, emails are forwarded to xorlab Security Platform, but no actions are taken, and messages are deleted/dropped after processing. 1. Specify the next-hop destination in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file: ```shell theme={null} ## Routing relayhost = relay.host.com ``` The `relayhost` entry can have either of the following values: * Your next-hop destination, that is usually your MTA specified in the MX record. * `localhost` in case xorlab Security Platform should never send any emails to you. This is rather an edge case, and only used when you don’t want to test the reporting feature (no feedback emails will be sent). 2. Open the `activeguard/mta/startup_cfg/postfix_custom/client_access` file and add one line, like shown below, for every email server that will send emails to xorlab Security Platform: ```shell theme={null} ## Permit this IP to send emails through xorlab Security Platform ## 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 permit permit #You can also permit domains. The domain name is determined by means of a reverse DNS lookup and automatically extends to subdomains. example.com permit ``` ### Special case: sender-based routing In sender-based routing, the next hop (referred to as ``) for the email is chosen based on the sender’s address (`MAIL FROM`). This configuration is usually only used in conjunction with recipient-based routing to address special cases. First, we need to enable the sender-dependent transport in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file: ```shell theme={null} sender_dependent_relayhost_maps = lmdb:/etc/postfix/sender_dependent_transport ``` If the `activeguard/mta/startup_cfg/postfix_custom/sender_dependent_transport` file does not exist, you have to create it. **Routing precedence** Please be aware that recipient-based routing has **precedence** over sender-based routing. If a recipient address matches an entry in `transport`, it will overrule any next-hop configurations from a match in `sender_dependent_transport`. Afterwards, for every sender that you would like to configure, add one line to the `activeguard/mta/startup_cfg/postfix_custom/sender_dependent_transport` file. You can specify sender email addresses as well as sender domains: ```shell theme={null} # Example for sender domain-based routing @xorlab.com # Example for sender email address-based routing test1@xorlab.com test2@xorlab.com ``` ## Subdomain matching ### Subdomains in transport maps When configuring email routing in `activeguard/mta/startup_cfg/postfix_custom/transport`, subdomains are not matched by default. This means that if you want to route emails for both a domain (e.g., xorlab.com) and its subdomains (e.g., sub.xorlab.com), you must either specify them explicitly or use the dot-prefix (.) syntax to apply a wildcard rule. ```shell theme={null} # Routing for xorlab.com xorlab.com smtp: # Routing for xorlab.com and all subdomains xorlab.com smtp: .xorlab.com smtp: ``` If you want subdomain matching to be applied automatically for all entries in your transport file, you can enable it globally. To do this, add the following line to `activeguard/mta/startup_cfg/postfix_custom/main.cf`: ```shell theme={null} # Enable subdomain matching for all transport entries parent_domain_matches_subdomains = transport_maps ``` ### Subdomains in client access In contrast, subdomain matching behaves differently for `client_access` and `relay_domains` configurations. For these settings, subdomains are automatically matched without requiring explicit entries. This is because Postfix performs a reverse DNS lookup on the EHLO IP address, which allows it to match both the domain and its subdomains seamlessly. For example: * In `activeguard/mta/startup_cfg/postfix_custom/client_access`, you only need to list the top-level domain (xorlab.com), and subdomains will be matched automatically. * Similarly, listing the main domains as `relay_domains` in `activeguard/mta/startup_cfg/postfix_custom/main.cf` is sufficient for subdomain matching. ## Sender and recipient restrictions This section explains how to impose generic restrictions on either a sending MTA or on a recipient address or domain. **SMTP restrictions** The restrictions described in this section refer to the SMTP connection only. Emails rejected during the SMTP connection will not appear in the Control Center GUI (XCC). ### Reject clients To reject emails from certain sender IPs or hostnames during the SMTP connection, list them in the `activeguard/mta/startup_cfg/postfix_custom/client_access` file with `reject`: ```shell theme={null} # Reject SMTP connection based on IP or hostname (EHLO) 1.2.3.4 reject 1.3 reject ehlo.example.com reject ``` ### Reject recipients To reject all emails to certain recipients, add these recipients to the file `activeguard/mta/startup_cfg/postfix_custom/recipient_access`: ```shell theme={null} # Reject certain recipients or recipient domains recipient@xorlab.com reject xorlab.net reject ``` ## TLS configuration TLS policies can be defined for xorlab Security Platform when acting as a client as well as when acting as a server. The policies are set in `activeguard/mta/startup_cfg/postfix_custom/main.cf`: ```shell theme={null} # TLS policy as client smtp_tls_security_level = may # TLS policy as server smtpd_tls_security_level = may ``` Supported values include: * `none`: Disable TLS. * `may` (default): Opportunistic TLS. Use TLS if the client, respectively the server, supports TLS. * `encrypt`: Enforce TLS. Do not send or receive emails without TLS. No valid certificate required. * `verify`: Enforce TLS and successful certificate verification. Only supported for `smtp_tls_security_level`. All values and additional information can be found in the Postfix documentation for the [`smtp_tls_security_level`](http://www.postfix.org/postconf.5.html#smtp_tls_security_level) as well as [`smtpd_tls_security_level`](http://www.postfix.org/postconf.5.html#smtpd_tls_security_level). ## SMTP auth for specific email addresses If you want emails sent from specific addresses to be routed through an SMTP server requiring authentication, you can follow this configuration. For example, you can authenticate xorlab Security Platform when sending reported email feedback from the `threatanalyst@example.com` address: 1. Set the desired sender address for feedback emails as described in [*Feedback emails*](/9.0/activeguard-sender-addresses#feedback-emails). We will use `threatanalyst@example.com` here. For any other email addresses, just skip this step. 2. Configure [sender-dependent transport](#special-case-sender-based-routing) in the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file by enabling (uncommenting) this line: ``` sender_dependent_relayhost_maps = lmdb:/etc/postfix/sender_dependent_transport ``` 3. If the `activeguard/mta/startup_cfg/postfix_custom/sender_dependent_transport` file does not exist, create it and add this entry: ``` threatanalyst@example.com [smtp.example.com]:2525 ``` 4. In the same folder, create two files: `sasl_passwd.lmdb` and an `sasl_passwd` file. Leave the former empty, while in the latter add this line: ``` [smtp.example.com]:2525 username:password ``` 5. Finally, go back to the `main.cf`file and add the following block under the line you enabled in step #2: ``` sender_dependent_relayhost_maps = lmdb:/etc/postfix/sender_dependent_transport # Auth for sender_dependent smtp_sasl_password_maps = lmdb:/etc/postfix/sasl_passwd smtp_sender_dependent_authentication = yes smtp_sasl_auth_enable = yes smtp_sasl_mechanism_filter = plain smtp_sasl_security_options = noanonymous ``` 6. Click **PUBLISH** to apply changes. ## Message size limit The maximum message size that xorlab Security Platform will accept during an SMTP connection can be defined in `activeguard/mta/startup_cfg/postfix_custom/main.cf` and `activeguard/mta/startup_cfg/postfix_custom/master.cf`: ```shell title="main.cf" theme={null} # Max accepted mail size in bytes, the limit can be increased if absolutely necessary message_size_limit = 52428800 ``` ```shell title="master.cf" theme={null} mta.activeguard.xor:10026 inet n - n - 20 smtpd -o message_size_limit=57671680 ``` Note that the value of the `message_size_limit` setting in `master.cf` has to be 1.1x higher than in `main.cf`. The default message size is 50 MB. This limit can be increased if necessary. However, consider the following points: * Many major email providers don’t accept message sizes over 35 MB. * The xorlab Security Platform file size limit for dynamically scanned attachments is 50 MB. * Aggressively increasing the message size limit can slow down email processing times. ## Additional configuration xorlab Security Platform exposes the internal Postfix configuration files and thereby allows you to use the entire SMTP configuration that Postfix offers. This includes, for example: * Address rewrites * Header rewrites * SMTP connection configuration (limit, rate, delay, etc.) Please refer to the [Postfix documentation](http://www.postfix.org/documentation.html) if you want to configure one of those things. Afterwards, you can configure it directly in the Postfix configuration files that are exposed in xorlab Control Center. Below you can find all built-in Postfix files. You can also add additional files in [Expert Editor](/9.0/expert-editor). **Postfix lookup tables** xorlab supports [Postmap](http://www.postfix.org/postmap.1.html) lookup tables in `lmdb:` format ([Lookup tables](http://www.postfix.org/DATABASE_README.html)). The following files are automatically postmapped: `client_access`,`client_access_tenant`,`recipient_access`,`sender_access`,`transport`,`sender_dependent_transport` and `postmap_*`. If you use a different file name, you need to either: a) Prefix your file `postmap_`. b) Create an empty file with the same name and `.lmbd` suffix. E.g., for `custom_transport`, you need to create an empty file called `custom_transport.lmdb` in the same folder. | Name | Postfix Resource | Descripton | | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | | `client_access` | [http://www.postfix.org/postconf.5.html#check\_client\_access](http://www.postfix.org/postconf.5.html#check_client_access) | Restrictions based on the client hostname or IP during SMTP connection | | `header_checks` | [http://www.postfix.org/header\_checks.5.html](http://www.postfix.org/header_checks.5.html) | Is not active by default. You have to configure it first in `main.cf` | | `main.cf` (or `main.cf.vmx.`) | [http://www.postfix.org/postconf.5.html](http://www.postfix.org/postconf.5.html) | Main configuration | | `master.cf` | [http://www.postfix.org/master.5.html](http://www.postfix.org/master.5.html) | Normally, it should not be changed. Can break email routing easily | | `recipient_access` | [http://www.postfix.org/postconf.5.html#check\_recipient\_access](http://www.postfix.org/postconf.5.html#check_recipient_access) | Restrictions based on the RCPT TO during SMTP connection | | `sender_access` | [http://www.postfix.org/postconf.5.html#check\_sender\_access](http://www.postfix.org/postconf.5.html#check_sender_access) | Restrictions during SMTP connection based on the sender | | `sender_access_add_header` | N/A | Used only internally. Adds the `envelope from` into a new header `x-xor-envelope-from` | ## Reserved configuration The following Postfix features are reserved for internal use and must not be configured: * [`mynetworks`](http://www.postfix.org/postconf.5.html#mynetworks): Use the `client_access` file instead to allow certain IPs to relay emails through xorlab Security Platform * [`content_filter`](http://www.postfix.org/postconf.5.html#content_filter)