7. Integration

MSUI offers a lot of options for integrating with Halon which in combination with the Halon Scripting Language (HSL) provides a high degree of flexibility.

The choice of which settings to offer, and using what permission levels, is configurable within the UI. The values can then be accessed with HSL to make processing decisions for each smtp transaction.

Note

The sample configuration files located under /opt/halon/msui/share/examples/hsl contains sample scripts for inbound and outbound email processing (includes routing, SPF, DMARC, anti-spam, anti-spam and more). It uses the msui-config.yaml configuration file that is created by the configuration export function in MSUI. It also use the history plugin to send transactional logs to Elasticsearch.

7.1. MSUI Client

The MSUI client should be installed on every Halon node that needs to be able to integrate with MSUI. Follow the instructions in our manual to add our package repository and then run the below command.

7.1.1. Ubuntu

$ apt-get install halon-extras-msui-client

7.1.2. RHEL

$ yum install halon-extras-msui-client

7.2. Settings in MSUI

By using the class provided by the MSUI client plugin you can fetch various settings from the exported configuration file (see configuration export for instructions on how to export the file from MSUI to Halon), for example:

// Managed Service UI
import { msui } from "extras://msui-client";
$msui = msui();

$settings = $msui->getDomainSettings("example.com");

if ($settings["dkim"]) {
    $mail->signDKIM($settings["dkim"]["selector"], "example.com", $settings["dkim"]["privatekey"]);
}

The scope for a setting can either be set to the entire domain or for individual users, depending on the use-case. This is determined by the “Availability” option in the UI.

// Managed Service UI
import { msui } from "extras://msui-client";
$msui = msui();

$settings = $msui->getUserSettings("[email protected]");

if ($settings["allowlist"]) {
    if (array_includes($connection["remoteip"], $settings["allowlist"])) {
        Accept();
    }
}

Invoking the msui.getUserSettings() method will get the domain settings by default if there are no excplicit settings set for the user-scope, in other words the settings on the user level will have priority over the domain (unless the msui.getDomainSettings() method is used instead).

Note

It is recommended to create a HSL script file that can be used to verify data from the exported configuration, such as msui/test.hsl. This way you can send queries to MSUI and fetch the values of the settings to see if they are behaving as expected (Configuration > Settings):

// Managed Service UI
import { msui } from "extras://msui-client";
$msui = msui();

$recipientdomain = "";
$recipient = "";

echo $msui->getDomainSettings($recipientdomain);
echo $msui->getUserSettings($recipient);

This file can then be run either from the command line or using the Halon debugger for VSCode.

7.2.1. msui-config.yaml

The configuration file that is exported from MSUI contains all the domains/users as well as their settings, this is what it used by Halon to dynamically make decisions for each transaction. Below is an example of what part of this file can look like:

domains: !Map
  example.com:
    id: 1
    domain: example.com
    transport:
      destination:
        - port: 25
          hostname: mx1.example.com
    settings:
      global: []
    users: !Map
      [email protected]:
        id: 1
        username: [email protected]
      [email protected]:
        id: 2
        username: [email protected]
settings: !Map
  [...]
  allowlist:
    schema:
      access_type: all
      type: list
      default_value: null
      option_values: []
      merge_default: true
    global: {}
    domains: !Map
      example.com:
        users: !Map
          [email protected]:
            user:
              value:
                - value: halon.io

Note

This file should not be altered manually, whenever changes are made to msui.yaml or any settings are changed in the UI itself the new values are exported so that the configuration in MSUI is always in sync with Halon.

These values are used by the msui() class, a lot more examples on how to use these can be found here.