Haraka 3.1.5 → 3.1.7

package/docs/Tutorial.md

@@ -1,270 +1,183 @@
 # Writing Haraka Plugins
 
-Part of the joy of using Haraka as your main mail server is having a strong
-plugin based system which means you control all aspects of how your mail is
-processed, accepted, and delivered.
+Part of the joy of using Haraka as your main mail server is having a strong plugin system: you control every aspect of how mail is processed, accepted, and delivered.
 
-Of course in order to control this you may at some point need to edit some
-sort of plugin file of your own to customise how things work. The good news
-is that writing plugins in Haraka is simple, even for novice coders. You
-just need a little knowledge of Javascript (and maybe some understanding of
-Node.js) and the world is your oyster.
+This tutorial walks through a small plugin that supports *disposable addresses*: an email like `user-20271231@example.com` is accepted up until 31 December 2027, after which delivery is rejected. Mail that is still within the validity window is rewritten back to `user@example.com` before it is forwarded on.
 
-This tutorial will run through a simple plugin which allows you to have
-email addresses that expire in a short period of time. This is handy if you
-want a _disposable email address_ to use to sign up for a web site that you
-don't wish to continually receive communication from.
+## What You'll Need
 
-## The Design
-
-In order to make this simple, we are going to simply let you have tagged
-email addresses such as `user-20120515@domain.com` which will expire on the
-15th May, 2012. Haraka will then check the email has yet to expire, and
-reject mails to that address after the expiry date. If the address hasn't
-expired yet it will re-write the address to `user@domain.com` before onward
-delivery.
-
-## What You Will Need
-
-- Node.js and npm
+- Node.js (an active LTS release) and npm
 - Haraka
 - A text editor
-- [swaks][1]
-- A screwdriver
-
-[1]: http://jetmore.org/john/code/swaks/
+- [swaks][swaks] for sending test mail
 
 ## Getting Started
 
-First install Haraka via npm if you haven't already:
+Install Haraka and create a project:
 
-    $ sudo npm -g install Haraka
+```sh
+sudo npm install -g Haraka
+haraka -i /path/to/new_project
+```
 
-Now we can create our project directory to get started with:
+Use a directory that does not yet exist. Now scaffold a plugin:
 
-    $ haraka -i /path/to/new_project
+```sh
+haraka -c /path/to/new_project -p rcpt_to.disposable
+```
 
-Make sure you use a directory that doesn't exist for your project.
+`haraka -p` reports the files it created:
 
-Next, let's create a new plugin:
+```
+Plugin rcpt_to.disposable created
+Now edit javascript in:    /path/to/new_project/plugins/rcpt_to.disposable.js
+Add the plugin to config:  /path/to/new_project/config/plugins
+And edit documentation in: /path/to/new_project/docs/plugins/rcpt_to.disposable.md
+```
 
-    $ haraka -c /path/to/new_project -p rcpt_to.disposable
+Edit `config/plugins` so the only enabled lines are:
 
-This should output a bunch of information about files it has created:
+```
+rcpt_to.disposable
+rcpt_to.in_host_list
+queue/test
+```
 
-    Plugin rcpt_to.disposable created
-    Now edit javascript in:    /path/to/new_project/plugins/rcpt_to.disposable.js
-    Add the plugin to config:  /path/to/new_project/config/plugins
-    And edit documentation in: /path/to/new_project/docs/plugins/rcpt_to.disposable.md
+The ordering matters — the disposable plugin must run *before* `rcpt_to.in_host_list`, which accepts mail for domains listed in `config/host_list`. `queue/test` writes accepted mail to a `.eml` file in `os.tmpdir()` so you can confirm delivery.
 
-So let's do the second part now - load up the `config/plugins` file and
-set it up to test. Comment out most of the plugins, except for
-`rcpt_to.in_host_list` and add in our new plugin, and change the queue
-plugin to `test_queue`. The final file should look like this:
+Open `plugins/rcpt_to.disposable.js` and start with:
 
-    # default list of plugins
+```js
+exports.hook_rcpt = (next, connection, params) => {
+    const rcpt = params[0]
+    connection.loginfo(`got recipient: ${rcpt}`)
+    next()
+}
+```
 
-    #dns-lists
-    #data.signatures
+Verify it works. In one terminal:
 
-    # block mail from some known bad HELOs - see config/helo.checks.ini for configuration
-    #helo.checks
+```sh
+echo LOGDEBUG > config/loglevel
+echo myserver.com >> config/host_list
+sudo haraka -c /path/to/new_project
+```
 
-    # Only accept mail where the MAIL FROM domain is resolvable to an MX record
-    #mail_from.is_resolvable
+In another:
 
-    # Allow dated tagged addresses
-    rcpt_to.disposable
+```sh
+swaks -h example.com -t booya@myserver.com -f sender@example.com -s localhost -p 25
+```
 
-    # Only accept mail for your personal list of hosts
-    rcpt_to.in_host_list
+You should see something like this in the Haraka log:
 
-    # Queue mail via qmail-queue
-    #queue/qmail-queue
+```
+[INFO] [<uuid>] [rcpt_to.disposable] got recipient: <booya@myserver.com>
+```
 
-    test_queue
-
-The ordering here is important - our new plugin has to come before `rcpt_to.in_host_list`.
-
-Fire up your favourite editor and put the following into the `plugins/rcpt_to.disposable.js` file:
-
-    exports.hook_rcpt = function (next, connection, params) {
-    	const rcpt = params[0];
-    	this.loginfo("Got recipient: " + rcpt);
-    	next();
-    }
+…and a `.eml` file in your system temp directory containing the message.
 
-Here we log that we got the recipient.
+## Parsing Out the Date
 
-Check this works. You'll need two terminal windows. In window 1:
+Detect addresses of the form `user-YYYYMMDD` and parse the date:
 
-    $ echo LOGDEBUG > config/loglevel
-    $ echo myserver.com >> config/host_list
-    $ sudo haraka -c /path/to/new_project
+```js
+exports.hook_rcpt = (next, connection, params) => {
+    const rcpt = params[0]
+    connection.loginfo(`got recipient: ${rcpt}`)
 
-And in window 2:
+    const match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user)
+    if (!match) return next()
 
-    $ swaks -h domain.com -t booya@myserver.com -f somewhere@example.com \
-      -s localhost -p 25
+    // Date constructor uses zero-indexed months (Dec === 11)
+    const expiry = new Date(match[2], match[3] - 1, match[4])
+    connection.loginfo(`expires on: ${expiry.toISOString()}`)
 
-In the logs you should see:
+    next()
+}
+```
 
-    [INFO] [rcpt_to.disposable] Got recipient: <booya@myserver.com>
+Restart Haraka and send:
 
-Which indicates everything is working. You should also have a file
-`/tmp/mail.eml` containing the email that swaks sent.
+```sh
+swaks -h example.com -t booya-20271231@myserver.com \
+    -f sender@example.com -s localhost -p 25
+```
 
-## Parsing Out The Date
+Logs:
 
-Now check for emails with an expire date in them and turn them into
-`Date` objects. Edit your plugin file as follows:
+```
+[INFO] [rcpt_to.disposable] got recipient: <booya-20271231@myserver.com>
+[INFO] [rcpt_to.disposable] expires on: 2027-12-31T00:00:00.000Z
+```
 
-    exports.hook_rcpt = function (next, connection, params) {
-    	var rcpt = params[0];
-    	this.loginfo("Got recipient: " + rcpt);
+## Rejecting Expired Addresses
 
-    	// Check user matches regex 'user-YYYYMMDD':
-    	var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
-    	if (!match) {
-    		return next();
-    	}
+Compare the parsed date to today and reject if it has already passed:
 
-    	// get date - note Date constructor takes month-1 (i.e. Dec == 11).
-    	var expiry_date = new Date(match[2], match[3]-1, match[4]);
+```js
+exports.hook_rcpt = (next, connection, params) => {
+    const rcpt = params[0]
 
-    	this.loginfo("Email expires on: " + expiry_date);
+    const match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user)
+    if (!match) return next()
 
-    	next();
+    const expiry = new Date(match[2], match[3] - 1, match[4])
+    if (expiry < new Date()) {
+        return next(DENY, 'Expired email address')
     }
 
-Start haraka again and pass it the following email via swaks:
+    next()
+}
+```
 
-    $ swaks -h domain.com -t booya-20120101@myserver.com \
-      -f somewhere@example.com -s localhost -p 25
+Send mail to an expired address:
 
-And you should see now in the logs:
+```sh
+swaks -h example.com -t booya-20200101@myserver.com \
+    -f sender@example.com -s localhost -p 25
+```
 
-    [INFO] [rcpt_to.disposable] Got recipient: <booya-20120101@myserver.com>
-    [INFO] [rcpt_to.disposable] Email expires on: Sun, 01 Jan 2012 05:00:00 GMT
+The remote end sees:
 
-The exact time may vary depending on your timezone, but it should be obvious
-we now have a date object, which we can now compare to the current date.
+```
+<** 550 Expired email address
+```
 
-## Rejecting Expired Emails
+## Rewriting Live Addresses
 
-The next edit we have to do is to add in code to compare to the current date
-and reject expired emails. Again, this is very simple:
+When the address is still valid, strip the date tag so the downstream mail store receives plain `user@domain`:
 
-    exports.hook_rcpt = function (next, connection, params) {
-    	var rcpt = params[0];
-    	this.loginfo("Got recipient: " + rcpt);
+```js
+exports.hook_rcpt = (next, connection, params) => {
+    const rcpt = params[0]
 
-    	// Check user matches regex 'user-YYYYMMDD':
-    	var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
-    	if (!match) {
-    		return next();
-    	}
+    const match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user)
+    if (!match) return next()
 
-    	// get date - note Date constructor takes month-1 (i.e. Dec == 11).
-    	var expiry_date = new Date(match[2], match[3]-1, match[4]);
-
-    	this.loginfo("Email expires on: " + expiry_date);
-
-    	var today = new Date();
-
-    	if (expiry_date < today) {
-    		// If we get here, the email address has expired
-    		return next(DENY, "Expired email address");
-    	}
-
-    	next();
+    const expiry = new Date(match[2], match[3] - 1, match[4])
+    if (expiry < new Date()) {
+        return next(DENY, 'Expired email address')
     }
 
-And we can easily check that with swaks (remember to restart Haraka):
-
-    $ swaks -h foo.com -t booya-20110101@haraka.local -f somewhere@example.com \
-      -s localhost -p 25
-    === Trying localhost:25...
-    === Connected to localhost.
-    <-  220 sergeant.org ESMTP Haraka 0.3 ready
-     -> EHLO foo.com
-    <-  250-Haraka says hi Unknown [127.0.0.1]
-    <-  250-PIPELINING
-    <-  250-8BITMIME
-    <-  250 SIZE 500000
-     -> MAIL FROM:<somewhere@example.com>
-    <-  250 From address is OK
-     -> RCPT TO:<booya-20110101@haraka.local>
-    <** 550 Expired email address
-     -> QUIT
-    <-  221 closing connection. Have a jolly good day.
-    === Connection closed with remote host.
-
-Now we need to do one more thing...
-
-## Fixing Up Unexpired Emails
-
-The last thing we need to do, is if we have an email that isn't expired, we
-need to normalise it back to the real email address, because wherever we
-deliver this to is unlikely to recognise these new email addresses.
-
-Here's how our final plugin will look:
-
-    exports.hook_rcpt = function (next, connection, params) {
-    	var rcpt = params[0];
-    	this.loginfo("Got recipient: " + rcpt);
-
-    	// Check user matches regex 'user-YYYYMMDD':
-    	var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
-    	if (!match) {
-    		return next();
-    	}
-
-    	// get date - note Date constructor takes month-1 (i.e. Dec == 11).
-    	var expiry_date = new Date(match[2], match[3]-1, match[4]);
-
-    	this.loginfo("Email expires on: " + expiry_date);
-
-    	var today = new Date();
-
-    	if (expiry_date < today) {
-    		// If we get here, the email address has expired
-    		return next(DENY, "Expired email address");
-    	}
-
-    	// now get rid of the extension:
-    	rcpt.user = match[1];
-    	this.loginfo("Email address now: " + rcpt);
-
-    	next();
-    }
-
-And when we test this with an unexpired address via swaks:
-
-    $ swaks -h foo.com -t booya-20120101@haraka.local \
-      -f somewhere@example.com -s localhost -p 25
-
-We get in the logs:
+    rcpt.user = match[1]
+    connection.loginfo(`rewrote recipient to: ${rcpt}`)
+    next()
+}
+```
 
-    [INFO] [rcpt_to.disposable] Got recipient: <booya-20120101@haraka.local>
-    [INFO] [rcpt_to.disposable] Email expires on: Sun Jan 01 2012 00:00:00 GMT-0500 (EST)
-    [INFO] [rcpt_to.disposable] Email address now: <booya@haraka.local>
+Send to a live tagged address and watch the log:
 
-Which indicates that we have successfully modified the email address.
+```
+[INFO] [rcpt_to.disposable] rewrote recipient to: <booya@myserver.com>
+```
 
-# Further Reading
+## Further Reading
 
-There are many more features of the Haraka API to explore, including access
-to the body of the email and the headers, access to the HELO string, and
-implementing ESMTP extensions, among many others.
+The Haraka API offers much more — body and header access, ESMTP extension hooks, the outbound delivery hooks, structured results, attachments, and so on. Two good starting points:
 
-There are two good places to read up on these. Firstly is the documentation
-in the Haraka "docs" directory. Start with the `Plugins.md` file, and work
-your way through the API from there.
+- The [Plugins guide](Plugins.md) and the rest of the `docs/` directory.
+- The [Plugin registry](https://github.com/haraka/Haraka/blob/master/PLUGINS.md) for an inventory of real-world plugins.
+- The plugins shipped in the [`plugins/`](../plugins/) directory. Even the most elaborate are under 200 lines; many are under 20.
 
-The second place is simply reading the source code for the plugins themselves.
-The plugins that Haraka ships with use almost all parts of the API and so
-should give you a good starting point if you want to implement a particular
-piece of functionality. Even the most complicated plugins are under 200 lines
-of code, so don't be intimidated by them! The simplest one is a mere 5 lines
-of code.
+[swaks]: https://www.jetmore.org/john/code/swaks/

package/docs/plugins/aliases.md

@@ -1,143 +1,3 @@
 # aliases
 
-This plugin allows one to configure aliases that may perform an action or
-change the RCPT address in a number of ways. All aliases are specified in
-a JSON formatted configuration file, and must have at very least an action.
-Any syntax error found in the JSON format config file will stop the server
-from running.
-
-IMPORTANT: this plugin must appear in `config/plugins` before other plugins
-that run on hook_rcpt
-
-WARNING: DO NOT USE THIS PLUGIN WITH queue/smtp_proxy.
-
-## Configuration
-
-- aliases
-
-  JSON formatted configuration file that must contain, at very least, a key
-  to match against RCPT address, and a value that is an associative array
-  with an "action" : "<action>" key, value pair. An example:
-
-        { "test1" : { "action" : "drop" } }
-
-  In the above example the "test1" alias will drop any message that matches
-  test1, or test1-_ or test1+_ (wildcard '-' or '+', see below). Actions
-  may in turn have 0 or more options listed with them like so:
-
-        { "test3" : { "action" : "alias", "to" : "test3-works" } }
-
-  In the above example the "test3" alias has an action of "alias", and
-  a required "to" field. If this "to" field were missing the alias would
-  fail to run, and an error would be printed in the logs.
-
-  Now aliases of 'user', '@host' and 'user@host' possible:
-
-        { "demo" : { "action" : "drop" } }
-        or
-        { "@example.com" : { "action" : "drop" } }
-        or
-        { "demo@example.com" : { "action" : "drop" } }
-
-  Aliases may also be exploded to multiple recipients:
-
-        { "sales@example.com": { "action: "alias", "to": ["alice@example.com", "bob@example.com"] } }
-
-  - wildcard notation
-
-    In an effort to match some of the functionality of other alias parsers
-    we've allowed wildcard matching of the alias against the right most
-    string of a RCPT address. The characters '-' and '+' are commonly used
-    for subaddressing and this plugin has built-in support to alias the
-    "user" part of the email address.
-
-    That is, if our address were test2-testing@example.com (or
-    test2+testing@example.com), the below alias would match:
-
-          { "test2" : { "action" : "drop" } }
-
-    The larger, and more specific alias, should always match first when
-    using wildcard '-' notation. So if the above RCPT were put up against
-    this alias config, it would not drop, but rather map to another
-    address:
-
-          {
-              "test2" : { "action" : "drop" },
-              "test2-testing" : { "action" : "alias", "to" : "test@foo.com" }
-          }
-
-  - chaining and circuits
-
-    In short, we do not allow chaining of aliases at this time. As a
-    side-effect, we enjoy protections against alias circuits.
-
-  - optional one line formatting
-
-    Any valid JSON will due, however, please consider keeping each alias
-    on its own line so that others that wish to grep the aliases file
-    have an easier time finding the full configuration for an alias.
-
-  - nondeterministic duplicate matches
-
-    This plugin was written with speed in mind. That means every lookup
-    hashes into the alias file for its match. While the act of doing so
-    is fast, it does mean that any duplicate alias entries will match
-    nondeterministically. That is, we cannot predict what will happen
-    here:
-
-          {
-              "coinflip" : { "action" : "alias", "to" : "heads@coin.com" },
-              "coinflip" : { "action" : "alias", "to" : "tails@coin.com" }
-          }
-
-    Truth be told, one result will likely always be chosen over the other,
-    so this is not exactly a coinflip. We simply cannot say what the
-    language implementation will do here, it could change tomorrow.
-
-- action (required)
-
-  The following is a list of supported actions, and the options they require.
-  - drop
-
-    This action simply drops a message, while pretending everything was
-    okay to the sender. This acts much like an alias to /dev/null in
-    other servers.
-
-  - alias
-
-    This action will map the alias key to the address specified in the
-    "to" option. A note about matching in addition to the note
-    about wildcard '-' above. When we match an alias, we store the
-    hostname of the match for a shortcut substitution syntax later.
-    - to (required)
-
-      This option is the full address, or local part at matched hostname
-      that the RCPT address will be re-written to. For an example of
-      an alias to a full address consider the following:
-
-            { "test5" : { "action" : "alias", "to" : "test5@foo.com" } }
-
-      This will map RCPT matches for "test5" to "test5-works@foo.com".
-      This would map "test5@somedomain.com" to "test5-works@foo.com"
-      every time. Now compare this notation with its shortcut
-      counterpart, best used when the "to" address is at the same
-      domain as the match:
-
-            { "test4" : { "action" : "alias", "to" : "test4" } }
-
-      Clearly, this notation is more compact, but what does it do. Well,
-      mail to "test4-foo@anydomain.com" will map to "test4@anydomain.com".
-      One can see the clear benefit of using this notation with lots of
-      aliases on a single domain that map to other local parts at the
-      same domain.
-
-### Example Configuration
-
-{
-"test1" : { "action" : "drop" },
-"test2" : { "action" : "drop" },
-"test3" : { "action" : "alias", "to" : "test3-works" },
-"test4" : { "action" : "alias", "to" : "test4" },
-"test5" : { "action" : "alias", "to" : "test5-works@success.com" },
-"test6" : { "action" : "alias", "to" : "test6-works@success.com" }
-}
+Repackaged as [haraka-plugin-aliases](https://github.com/haraka/haraka-plugin-aliases).

package/docs/plugins/auth/auth_ldap.md

@@ -1,41 +1,4 @@
 # auth/auth_ldap
 
-The `auth/auth_ldap` plugin uses an LDAP bind to authenticate a user. Currently
-only one server and multiple DNs can be configured. If any of the DN binds succeed,
-the user is authenticated.
-
-## Configuration
-
-Configuration is stored in `config/auth_ldap.ini` and uses the INI
-style formatting.
-
-Only the `LOGIN` authentication method is supported assuming that passwords in the
-LDAP database are not stored in cleartext (which would allow for CRAM-MD5). Note
-that this means passwords will be sent in the clear to the LDAP server unless
-an `ldaps://` conection is used.
-
-Current configuration options in `[core]` are:
-
-    server - the url of the LDAP server (ldap:// or ldaps://)
-    timeout - time in miliseconds to wait for the server resonse before giving up
-    rejectUnauthorized - boolean (true or false) as to whether to reject connections
-        not verified against a CA. Meaning, a "false" allows non-verified.
-
-Example:
-
-    [core]
-    server=ldaps://ldap.opoet.com
-    timeout=5000
-    rejectUnauthorized=false
-
-The `[dns]` section (that is plural DN and not domain name system), is a list of DNs to use
-to bind. The `%u` in the strings is substituted with the user name used in the SMTP
-authentication. Note that the keys have no meaning and the DNs are tried in series until
-the first successful bind. The LDAP RFC does not allow for parallel binds on a connection,
-so it is suggested that the most commonly used DN be placed earlier in the list.
-
-Example:
-
-    [dns]
-    dn1=uid=%u,ou=Users,dc=opoet,dc=com
-    dn2=uid=%u,ou=people,dc=opoet,dc=com
+Repackaged as [haraka-plugin-auth-ldap](https://github.com/haraka/haraka-plugin-auth-ldap).
+Loading `auth/auth_ldap` in `config/plugins` is auto-redirected to `auth-ldap`.

package/docs/plugins/max_unrecognized_commands.md

@@ -1,20 +1,6 @@
 # max_unrecognized_commands
 
-This plugin places a maximum limit on the number of unrecognized commands
-allowed before recognising that the connection is bad.
-
-If the limit is reached the connecting client is sent an error message and
-immediately (and rudely - technically an RFC violation) disconnected.
-
-**IMPORTANT**:
-This plugin should be listed near the bottom of `config/plugins` so that it
-runs after any plugins that use the unrecognized_command hook to implement
-other SMTP verbs and extensions (such as the auth/\* plugins), otherwise
-commands valid for these plugins will be counted as unknown by this plugin.
-
-## Configuration
-
-- max_unrecognized_commands
-
-  Specifies the number of unrecognized commands to allow before disconnecting.
-  Default: 10.
+The functionality of this plugin was folded into
+[haraka-plugin-limit](https://github.com/haraka/haraka-plugin-limit).
+Loading `max_unrecognized_commands` in `config/plugins` is auto-redirected
+to `limit`.

package/docs/plugins/process_title.md

@@ -37,6 +37,6 @@ across all workers, with the exception of outbound stats.
 All of the counts shown are since the process started, so if a
 worker has been re-started then the counts may not add up.
 
-Note: this plugin will only work on node >= 0.8 and should be
-added at the top of config/plugins to ensure that it functions
-correctly.
+Note: this plugin should be added at the top of `config/plugins` so
+that its `connect_init`, `rcpt`, `data`, and `disconnect` hooks run
+before any plugin that might short-circuit those hooks.

package/docs/plugins/queue/smtp_forward.md

@@ -38,9 +38,7 @@ Configuration is stored in smtp_forward.ini in the following keys:
 
 - enable_tls=[true]
 
-  Enable TLS with the forward host (if supported). TLS uses options from the tls plugin. If key and cert are provided in the the outbound section of the tls plugin, that certificate will be used as a TLS Client Certificate.
-
-  This option controls the use of TLS via `STARTTLS`. This plugin does not work with SMTP over TLS.
+  Enable opportunistic TLS with the forward host via `STARTTLS` (if the host advertises it). This plugin does not work with implicit SMTP over TLS.
 
 - auth_type=[plain\|login]
 
@@ -69,6 +67,24 @@ Configuration is stored in smtp_forward.ini in the following keys:
   [example.com]
   [example.net]
 
+- [tls]
+
+Client STARTTLS options are assembled by merging:
+
+1. `tls.ini` `[main]` — the global Haraka TLS config
+2. `smtp_forward.ini` `[tls]` — overrides. Anything set here wins.
+
+Example `smtp_forward.ini` `[tls]` section:
+
+    [tls]
+    rejectUnauthorized=true
+    minVersion=TLSv1.2
+    no_tls_hosts[]=10.0.0.5
+
+Per-domain `enable_tls=false` still disables STARTTLS for that backend. Per-domain TLS cipher/cert overrides are not currently supported.
+
+Changes to `tls.ini` require a Haraka restart to apply to the forward path; changes to `smtp_forward.ini` are picked up by the existing reload hook.
+
 # Per-Domain Configuration
 
 More specific forward routes for domains can be defined. The domain is chosen based on the value of the `domain_selector` config variable.