Documentation and help portal

regify regigate Manual

Intro

This document aims to provide an overview, integration examples, as well as detailed configuration of the regify regigate product, here on referred to as regigate or appliance.

Intended Audience

The intended audience is a technical one. This includes administrators deploying regigate and also those in charge of integrating regigate into their existing e-mail infrastructure. It also includes regify Provider administrators who provide key services to the deployed regigate instances.

Document Structure

This document will cover various aspects pertaining to regigate.

  • General regigate Information explains the general e-mail flow as well as some behavioral details and an abstract example rule set.

  • Routing shows and explains the regigate routing capabilities including an explained example setup.

  • regify Provider covers the steps a regify Provider needs to take in order to enroll a regigate appliance.

  • Installation basics info about hardware/VM requirements, third party software and serial port installation.

  • Appliance Wizard post installation basic host configuration.

  • SSH Terminal a short PuTTY tutorial for Windows users.

  • Appliance Menu is a description of the terminal based appliance menu used to configure the regigate appliance.

Setup process (best practice)

In order to set up a new regigate, best is to follow this guide:

  1. Set up the system inside of the desired network.

  2. Configure your SSH access (Network Settings  Advanced Settings).

  3. Login to the regigate appliance using SSH (PuTTY or similar tool or SSH directly on Linux based systems).

  4. Enter regigate Settings  Routes…​  Add route…​ and create your first route (eg incoming). The correct value for “Provider Server” is given to you by your regify provider / sub-provider administrator and looks similar like this: providerdomain.com:9001.
    regigate is not able to operate without a regify provider connection!

  5. After the new route was created, enter the route settings and select Show Certificate Request.

  6. Copy the request and send it to the regify (sub)provider administrator. There the request will get signed and you will get a signature certificate back.

  7. Select Import Signed Certificate and paste the signed certificate from the provider in here. Finish by pressing ENTER, followed by CTRL+d.

This list of setup steps are not meant to ignore the later document. Please read the corresponding articles and sections to get more information about the steps.

General regigate Information

This chapter explains the general e-mail flow going through regigate as well as some behavioral details.

E-mail Flow

The usual setup has outgoing e-mails encrypted based on criteria that implements company policies. This could be based on e-mail headers such as subject or recipient address. Any internal outbound e-mail goes through regigate which decides to encrypt the message or not based on its rule engine. If it is to be encrypted, regigate will do so and forwards it to the configured next MTA/gateway or to the Internet. The flow below describes the encryption process where regigate routes the encrypted e-mail to the Internet after optional encryption.

flowOutgoing

Incoming e-mails are handled in a similar way. Inbound e-mails are checked whether they need decryption and, if so, getting decrypted regigate will then route the decrypted e-mail back to the configured MTA (mail server) for further processing and delivery.

flowIncoming

Behavioral Details

Below are some note worthy details to point out:

  • E-mails are only encrypted if the sender has a regify account. If not, regigate will reject the e-mail with a permanent 5.x SMTP Error. This is done to insure that e-mails designated for encryption do not leave the company unencrypted.

  • Encrypted e-mails are only decrypted if the recipient has a regify account. If this is not the case, the e-mail is passed on encrypted. This way it can be decrypted by the recipient locally after getting a regify account.

  • Senders and recipients are solely determined by the SMTP MAIL FROM and RCPT TO and not from the e-mail headers.

  • When multiple recipients are specified, the message is split and a message for each recipient is sent onward.

  • By default, regigate sets no special headers indicating that it processed an e-mail. You can use the rule tags to create or modify headers if needed in your regigate route rules.

  • regigate will reject e-mail with temporary 4.x SMTP errors if cannot reach its regify provider or has other local error conditions.

  • regigate will not(!) create bounce messages if a configured smarthost denies the message (eg user not found). Instead, it is simply dropped. If you need top have such bounce messages, please use some catchall mechanism on your mailserver to define and trigger your own bounce messages through your MTA.

Opportunistic MTA TLS encryption

All regify appliances support opportunistic TLS encryption of MTA traffic. This means that e-mail traffic between MTAs is encrypted. Opportunistic in this case means that the MTAs negotiate this type of encryption, and if they agree on a scheme, they will use it. If one side does not support encryption, the e-mail will be sent in the clear. TLS encryption has nothing to do with regimail encryption. TLS encryption is only between MTAs, while regimail encryption is between sender and recipient. To see whether sent e-mail was TLS encrypted, one can either look at the MIME of an e-mail where you can see the Received headers. An example of TLS having been used could look like this:

Received: from [1.2.3.4] (helo=smtprelay.isp.com)
    by mx.isp.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256)

Another place is the mail log under /var/log/maillog on the regify appliance. The following is an example of an e-mail that went out via TLS:

May  4 10:35:01 portal postfix/smtp[164]: Untrusted TLS connection established to mx.isp.com[1.2.3.4]:25: TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)

Self signed certificates

By default regify appliances use a self signed certificate valid for 10 years. Even older appliances are retrofitted with a self signed certificate during the course of the update. Self signed certificates are generally deemed acceptable for this type of use. In our implementation it is possible to use custom certificates on a global level (one for all routes), or individual certificates for each given route. Since self signed certificates are generally all that is needed for this, no GUI has been designed to manage custom certificates.

Certificate Management

To facilitate customizing the default certificates, the implementation needs to be explained, so the model is understood. Every regify appliance has an MTA instance configured under /etc/postfix. regigate appliances have additional instances under /etc/postfix-milter-n and /etc/postfix-split-n. Where n is the route id that is also displayed in the appliance menu when configuring a given route. By default all keys and certificates are searched for in a file named key_cert.pem under each instance, so the default instance looks for /etc/postfix/key_cert.pem. In the default cases, these are symbolic links to our default self signed certificate under /etc/postfix/self_signed_key_cert.pem, which should not be changed or removed as it will be auto generated when missing.

Here is what the general directory structure of /etc/postfix looks like:

key_cert.pem -> self_signed_key_cert.pem
main.cf
master.cf
self_signed_key_cert.pem

This listing reflects a general regigate route under /etc/postfix-milter-1 and /etc/postfix-split-1:

key_cert.pem -> /etc/postfix/key_cert.pem
main.cf
master.cf

To use the same custom certificate for all instances, simply place the key and certificate in PEM format into a file like /etc/postfix/my_cert.pem and point /etc/postfix/key_cert.pem to it.

To use individual certificates for a given route, simply replace its symlink to the default certificate with a file containing the key and certificate in PEM format. Do this for each /etc/postfix-milter-n/key_cert.pem, /etc/postfix-split-n/key_cert.pem instance.

These files will not be overwritten, but removed if a route is deleted, so backup your certificate somewhere. In the same course, each routes custom certificate needs to be placed into that file after a new route has been created.

When switching to HA mode, the files will be copied over to /d1/etc/postfix... and back again when leaving HA mode.

Certificate Creation

There are some commands that can be used as root to create a certificate and request on the regify appliance. Running the following command does this. Running it by itself yields some usage info:

makeCert
Generates a TLS certificate with key and certificate request. The key and cert
will only be generated if they do not already exist.

Parameters:
    -a Alternative name (may be used multiple times)
    -C Certificate directory
    -c Country code (required)
    -e Email
    -K Key directory
    -l Locality City or Town
    -n Common Name (required)
    -o Organization
    -P Filename prefix
    -s State
    -u OrgUnit

Usage:
    makeCert -c CN [-s State] [-l Locality/City] [-o Organization] \\
         [-u OrgUnit] -n domain.tld [-e email] \\
        [[-a domain1.tld] -a domain2.tld] \\
        [-P FilePrefix] [-C CertDir] [-K KeyDir]

Examples:
    # Minimal example
    makeCert -c DE -n example.com -e info@example.com

    # A more realistic example
    makeCert -c DE -l Frankfurt -o 'Example Inc' -n www.example.com \\
        -e info@example.com -a www.example.com -a example.com \\
        -K . -C . -P example
    # this creates
    ./example.key
    ./example.csr
    ./example.crt

Here we set some example values. We skip -C and -K so they default to the local directory.

makeCert -c DE -s BW -l Hüfingen -o 'regify GmbH' -u QA -n mail.tester.com -a tester.com -a mail.tester.com -e test@regify.com -P my_cert

This leaves us with 3 files:

my_cert.crt
my_cert.csr
my_cert.key

The .crt is the self signed certificate, the .key is the key and the .csr is the signing request. As it says in the usage info, the key and cert will only be created if they do not yet exist, so it is safe to create a request using existing key and cert files without overwriting them. Now we post the request to the screen so we can copy it and get it signed.

cat my_cert.csr

To import the signed certificate it is easiest to use the clip board and paste it into the cert file. So we type echo ', then <PASTE> the cert and finish by typing ' > my_cert.crt to write it into the cert file.

echo '<PASTE>
' > my_cert.crt

Postfix expects the key and certificate to be in a single file, so we prepare one here.

cp my_cert.key my_cert.pem
cat my_cert.crt >> my_cert.pem

In general it is best to save the key and certificate in my_cert.key and my_cert.crt someplace safe and remove my_cert.* from the local directory.

Examples

Below is a sample way of replacing the self signed certificate for all routes or an individual route.

After each change be sure to restart postfix to insure the new certificates are used by running:

systemctl restart postfix
All Routes

We copy our key and cert to /etc/postfix/my_cert.pem.

cp -f my_cert.pem /etc/postfix/my_cert.pem

Then we point the symlink from /etc/postfix/self_signed_key_cert.pem to /etc/postfix/my_cert.pem.

rm -f /etc/postfix/key_cert.pem
(cd /etc/postfix && ln -s my_cert.pem key_cert.pem)

Then restart postfix.

Individual Route

We simply replace key_cert.pem of example route 1. We use rsync, because it will replace the symbolic link with our file instead of overwriting the file it points to.

rsync -av my_cert.pem /etc/postfix-milter-1/key_cert.pem
rsync -av my_cert.pem /etc/postfix-split-1/key_cert.pem

Then restart postfix.

Routing

regigate allows you to setup multiple SMTP routes to offer you flexible e-mail routing. Every route applies its own rule set to decide whether to forward, reject, encrypt or decrypt a given e-mail. The routing rules are defined using a routing configuration file in JSON format. The file is copied to the regigate appliance using SSH menu access.

There is separate documentation available about the routing options and the routing configuration file (values, syntax etc).

Example configuration

To understand the principles, it is best explained using an example configuration. In order to be placed in a full e-mail flow (in and out), regigate needs at least two routes configured: One for the incoming e-mails and one for the outgoing e-mails.

regigateRouting

In the above sample drawing, the regigate system is configured with the public IP address of the company’s mail-domain mail.company.com. Therefore, it receives incoming e-mails. Its host name is set to mail.company.com and the DNS MX records are pointing to it.

Route one is listening on port 25 for incoming e-mails from the Internet. It only accepts e-mails to the company’s e-mail domain company.com. After the rules are applied, the messages are forwarded to the company’s mail-server (based on IP address). No need to define an MTA name here.

Route two is listening on port 2525 to receive outgoing e-mails from the company’s mail server. It only accepts messages from the company’s mail server to avoid an open relay. The mail server must be configured to use regigate as smarthost for sending e-mails. After Route two applied the rules, the messages are sent out to the Internet using DNS (no forward to address configured).

If both routes utilize an empty routing configuration like the default, all e-mails are simply forwarded. This is perfect for an initial configuration.

To avoid any open relay, the regigate appliance does not allow you to setup a route to the Internet without specifying a source IP address (see Route two).

Firewall

We strongly recommend you to run a firewall in front of your mail-server. This is giving you more flexibility in routing and more security (eg blocking access to port 2525 from the Internet). Additional NAT features can give you the chance to run the mail-server and regigate inside a DMZ, away from the Internet.

IP addresses

Regigate allows you to use multiple network interfaces (NIC) and multiple IP addresses. Please note that regigate only supports HA (high availability) if all routes are using the same IP address. The reason is the floating IP address that must be used for HA and the system is only supporting one floating IP at a time. In such case, please use the same IP address and port numbers to setup the routing. Therefore, a NAT firewall is required to support multiple domains on regigate with HA support enabled.

regify Provider

This chapter is meant for regify (sub)providers administrators. It covers the steps a provider needs to take to enroll a regigate appliance. In this chapter we will refer to the administrator of the regigate appliance as the regigate admin and the administrator of the regify Provider as the provider admin.

Enroll a regigate

The regigate admin provides the provider admin their outgoing IP number and their certificate request. The provider admin logs into their administration console at https://provider Name/ADMINISTRATION and clicks on Gateway management.

provAdmin

This will open the following page where the IP number and a description should be added followed by pressing Save Changes.

provGwMg1

After the page reloads the gear wheel icon of the newly added entry should be pressed.

provGwMg2

That will bring up this page where the certificate request provider by the regigate admin should be pasted in and Sign Certificate should be pressed.

provGwSign1

This page will then display the signed certificate, which should then be sent to the regigate admin.

provGwSign2

The regigate admin then imports the signed certificate as described in Network Settings  Advanced Settings  Combine Interfaces.

Delete a regigate

Deleting a regigate entry inside of the regify provider merely involves clicking the red x icon in the Gateway Management page and pressing Yes to confirm.

provGwMgDel

Installation

The regify regigate appliance herein referred to as the 'appliance' or 'regigate' is a ready to install and use turnkey system. It requires no Linux knowledge, even though it runs on a specialised CentOS 7 Linux system. The following concepts must be understood by the person installing and configuring this appliance:

  • Basic knowledge of IPv4 numbers, host names and DNS

  • Basic conceptual MTA configuration knowledge.

Requirements

A dedicated hardware machine or VMware virtual machine with the following attributes:

The ISO image can be burned onto a CD and then installed by booting off the CD. If the machine is a virtual machine then the virtual CD can be pointed at the ISO itself.

Before installing the system it is helpful to provide a few basic things:

  • IP number for the system including the net mask

  • Fully qualified domain name for the host

  • Fully qualified domain name for the server. This can be the same as the host name, but must be resolvable via DNS

Third party software

Installation of driver software and programs in the context of virtualisation technologies

regify also provides support for customers who use the regify regigate software appliance or the regigate software appliance on virtual servers (e.g. on VMWare, VirtualBox or Microsoft Virtual PC) according to the maintenance agreement and in line with commercial practice. As virtualisation technologies emulate functions of physical computers, regify assumes that regify products work in virtual environments as they do in physical environments. Therefore, provisioning of the regify support is based on the assumption that apotential problem or error that is observed in a virtual environment can be replicated in a physical one.

A regify customer may install other software on a regify appliance if such software is critical for the operation of the virtual environment. The existing maintenance agreement between customer and regify also applies for such virtual setups. However, problems or errors that only occur on virtual systems or in combination with software that was installed by the customer are not covered by the maintenance agreement. In such cases, regify reserves the right to charge the customer for time and effort. Moreover, regify does not assume any liability for system failure or loss of data.

System Installation

Insert the CD into the computer and boot off of it. At the first boot: prompt simply press enter. This will automatically install the entire system and reboot into the appliance wizard. If you are installing using a serial connection type serial and press enter at the boot: prompt. To use the serial connection insure your client the BIOS to use the following settings.

Serial: Port 0
Baud: 115200
Parity: None
Databits: 8
Flowcontrol: None
Then after the reboot wait for the login prompt.
CentOS Linux release 6.0 (Final)
Kernel 2.6.32-71.29.1.el6.i686 on an i686

localhost.localdomain login:

Login to the appliance as user regify password regify.

Appliance Wizard

The first page in the appliance wizard is the end user license agreement (EULA). If it is not accepted, the system will shut itself down. Subsequent reboots will land on the same page. After reading the EULA simply press Tab to move the focus to the Accept button and press Enter.

wizEula

The second page allows you to choose the database back end. MariaDB is the better choice for the clearing appliance due to performance reasons. So simply TAB to Yes and press Enter. One thing to note is that the back end cannot be changed at a later time. In the case of multiple clearing databases participating in a replication scheme, all databases need to be of the same type.

wizChooseDb

From here on the wizard pages can be repeated at any time by choosing Appliance Settings  Run appliance wizard from the appliance menu.

Here you choose your keyboard layout. It only matters when logging in locally, but is important for getting the passwords right. You can use the Arrow keys to choose your layout and hit Tab to choose the Next button.

wizKeyboard

Next we have the basic network configuration to be entered.

wizIp

This page allows setting of the host name. While it is not strictly necessary, it is usually better to have the host name resolvable via DNS, because missing or mis-configured DNS can lead to strange and hard to troubleshoot problems.

wizHostname

This dialogue is used to set the password for the regify appliance user. This is the account used to administer the regify regigate appliance. The login account is called regify and the password is set in the dialogue below.

regifyPw

Here is another password dialogue, but this one is for the appliance root account. Unlike the regify user the root user has complete control over the appliance and should therefore not be used for day to day administration.

rootPw

Here you set the administrative e-mail address. This address may receive occasional e-mail from the system.

adminEmail

Here you can choose the time zone your appliance is in. If you set the BIOS system clock to UTC instead of local time check the System clock uses UTC option.

timeZone

Configuration Completion

At the end of the wizard diagnostics are run to make you aware of potential issues that need to be remedied, before the system can function properly. Here is an example result.

wizDiag

At the end of the wizard you are informed as to where to go to configure your provider installation.

wizFinish

SSH Terminal

Most users use Windows systems. Unfortunately these systems lack terminals and SSH clients. Fortunately there are third party applications available. One such application is called PuTTY and is available for free. You can download it here http://www.putty.org/ . PuTTY does not need to be installed. It can simply be placed onto the desktop and run by double clicking it.

PuTTY Configuration

While PuTTY is free and generally works well, it can be a little quirky in the initial configuration. This is why it is covered in detail here. I will setup a configuration for the regify user. I will now go through and make the adjustments needed to connect to the appliance provider2.de.regify.com as the user regify. When initially opening PuTTY you get the following screen.

puttyConf

Adding regify as the Auto-login username under Connection  Data saves you from having to type it every time.

puttyLogin

Setting the Remote characters set under Window  Translation to UTF-8 is important.

puttyCharset

If it’s not set to UTF-8 you’ll get a screen that looks like this.

gooblygook

IMPORTANT:This step is very important and frequently forgotten.

After setting the Host Name, set Saved Sessions and press Save, not Open. This will save these settings for you to use next time.

puttySave
If you only press Open, PuTTY will forget everything and you’ll have to do this again.

After pressing Save simply double click the new provider2 entry to open the session.

puttyOpen

The first time you connect, you will get a prompt that looks something like this. Simply click Yes (Ja).

puttyAlert

Now you are prompted for the password for the regify user that you set earlier in the appliance wizard. Enter it here. It will not echo it back, not even as stars. Press Enter when done.

puttyRegifyLogin

Now you are logged in as the regify user and can administer the appliance. Hitting Tab twice followed by Enter will exit the session again.

Appliance Menu

Overview

In general an appliance entry that ends with …​ indicates that there is a sub menu structure below the given item. Pressing F8 backs out of dialogues and sub menus, but does not exit the appliance menu. This allow for quickly pressing F8 to get to the top level of the appliance menu without running risk of logging yourself out.

ClearingMenu

The appliance menu is separated into several major sections and the update functionality. The update functionality handles installing updates to the appliance in a wizard like manner.

The major sections are:

  • Network - handles IP related matters

  • Appliance - appliance configuration like time password, reboot…​

  • Database - start/stop database, configure replication

  • Provider - Web server related items

These are covered in greater detail in the following sections.

Network

Even though the appliance menu protects against this, care needs to be taken in this section when connecting remotely. When changing IP numbers remotely it is best to first add the new IP, disconnect and log back into the machine using the new IP, and then deleting the old IP.

netMain

View Settings

The Network Settings  View Settings page gives you a general overview of the network settings. It lists the host name, all configured interfaces and DNS servers.

netView

Run Diagnostics

Since there are many things that can be done incorrectly between DNS entries and server configurations, a diagnostics tool is installed that aims to point out common mis configurations and their remedies. It can be found under Network Settings  Run Diagnostics.

netDiagnostics

In this screenshot everything is correct, except for the fact that this internal machine used for making these screen shots is not accessible from the internet.

diagOk

Add IP

Network Settings  Add IP allows you to do just that. Interface lists the available network adaptors. The (on) suffix means it’s plugged in, while (off) means it is not. Simply choose the Interface, specify the IP Number and Netmask and hit Ok. If you are running an 802.1Q VLAN, add the proper VLAN ID, otherwise just leave this field blank. The network will get restarted making the change immediate. This will take a second or 2 to complete.

netAddIp

Set Gateway

Network Settings  Set Gateway allows you to set the default gateway for the system. Simply type in the IP number of the gateway Tab to Ok and press Enter.

netGw

Set Hostname & DNS

Network Settings  Set Hostname & DNS allows you to specify the Hostname and up to 2 DNS servers. The DNS servers can be safely omitted to use the built-in internal DNS server. It is good practise but not mandatory for the given host name to be resolvable by the given DNS entry.

netHostDns

Advanced Settings

Network Settings  Advanced Settings to take advantage of some of less used features of the appliance.

netAdv

SSH Settings

By default SSH root login is disabled and general access is only allowed from the local subnet. This is for security reasons. At Network Settings  Advanced Settings  SSH Settings you may specify one or more space delimited IP numbers or subnets to access the appliance. The following entries are legal and equivalent:

  • 192.168.11

  • 192.168.11.0/24

  • 192.168.11.134/24

Or:

  • 192.168.11.134

  • 192.168.11.134/32

You may check Allow root login if needed. This is only needed to setup database replication or High Availability.

netSsh

Remove IP

Network Settings  Advanced Settings  Remove IP allows you to remove an IP number. It is fine to do this over the network since it will not allow you to remove the IP number with which you are logged in as. Use the Arrow keys to select 192.168.11.137 and hit Tab twice to get to the Delete IP button and hit Enter.

netDelIp

Proxy Settings

Network Settings  Advanced Settings  Proxy Settings allows you to specify a proxy server to use when making HTTP or HTTPS calls to for example the update repository or the clearing server. This can be in the format of PROTO://HOST:PORT or simply HOST:PORT.

netProxy

Combine Interfaces

Starting with version 3.4.0, it is possible to visit Network Settings  Advanced Settings  Combine Interfaces to aggregate 2 or more network interfaces into one logically bonded network interface. This provides added high availability through redundancy, as well as scalability through link aggregation. For example, by combining 3 1Gb links a single 3Gb link is achieved. This link will continue to function as long as any of the 3 links are functional. By running each link through its own switch, switch redundancy will also be accomplished. The appliance currently supports 3 modes of link aggregation.

  • 0 - Round Robin Balanced

  • 4 - 802.3ad Link Aggregation (the switch must support it)

  • 6 - Adaptive Load Balancing

All 3 modes must be support by the other end of the link, while mode 4 must also be supported by the switch. Any recent Linux kernels will support these link aggregation schemes. Only interfaces that have not been configured with an IP number are available for bonding. Interfaces that participate in link aggregation are not available for individual configuration.

netBond

After eth1 and eth2 are combined, they may be configured as bond0.

eth1 and eth2 are no longer available for IP configuration.
netAddIpBond

Separate Interfaces

Aggregated links may be separated here.

netUnbond

When deleting a bonded interface, you will be prompt to accept that the IP numbers that were configured on the interface in question will be deleted. If an IP number held by this interface is used by a service, or the connection address of the current SSH session, it will not be deleted. In the service case assign another IP number or temporarily shut down the web server. Be sure to update the web service with the proper new address afterwards.

netUnbondConfirm

Appliance

The Appliance Settings section handles things that pertain to an individual machine.

appMain

Run appliance wizard

Appliance Settings  Run appliance wizard can be used to run through the appliance wizard again. There is no harm in running it more than once and it provides a coherent alternative to making changes in the appliance menu.

Time & Locale

Use Appliance Settings  Time & Locale to set Localisation Settings.

appTimeLocale

View Time Settings

The Appliance Settings  Time & Locale  View Settings dialogue shows the state of the NTP daemon as well as the current time and time zone. Below is a listing off its current peers:

timeView

Keyboard Layout

In Appliance Settings  Time & Locale  Keyboard Layout you can change the keyboard layout for the console. Use the Arrow keys to choose the layout and press Tab to switch to the Ok button and hit Enter.

This setting has no influence on PuTTY or other remote sessions.
appKeyboard

Select Timezone

Use Appliance Settings  Time & Locale  Select Timezone to select the time zone the system is in. Use the Arrow keys to choose the time zone and press Tab to get to the checkbox. If the systems BIOS hardware clock is set to UTC instead of local time, check the System clock uses UTC option by pressing Space. Press Tab to switch to the Ok button and hit Enter.

appTz

Set NTP Servers

The Appliance Settings  Time & Locale  Set NTP Servers setting show up when NTP is enabled only. It allows you to specify one or more NTP server host names or IP addresses. Servers may be specified one or more per line. When specifying more than one per line separate them with spaces.

appNtp

E-mail Settings

Visit Appliance Settings  E-mail Settings to set anything relating to sending e-mails.

If you’re running a regigate, these settings will not apply to the individual regigate routes. This is only for internal appliance MTA like regify provider messages and system email.
appEmail

Set Administrative E-mail

The Appliance Settings  E-mail Settings  Set Administrative E-mail allows you to set the administrative e-mail address. This address may receive occasional e-mail from the system.

appAdminEmail

Set E-mail Smarthost

In some configurations it is not possible for a given server to send e-mail by itself. To accommodate this situation, you may use Appliance Settings  E-mail Settings  Set E-mail Smarthost to tell the server to route all SMTP (e-mail) traffic through the given host.

appSmartHost

Set E-mail Hostname

Appliance Settings  E-mail Settings  Set E-mail Hostname dialogue can be used to override the default host name, the appliance MTA (Mail Transfer Agent, aka E-mail Server) claims to be. This is necessary when an appliance is located off limits to the internet.
It is important to insure that this name has the following properties:

  • A reverse DNS lookup of the outgoing IP address has to resolve to the name specified here. The outgoing IP address is the address an outside MTA sees when this machine connects to it.

  • A forward DNS lookup of this name should result in the above mentioned outgoing IP address.

When one or more of these requirements are not met, it is likely that e-mail from this machine will be marked as spam or not be delivered at all.

appMtaHostname

Other Settings

Visit Appliance Settings  Other Settings for support diagnostics and other system maintenance work.

appOther

Support Diagnostics

This menu allows you to send comprehensive but not sensitive system information to regify support. Should you feel that your system setting are sensitive, you may send this information to yourself and then forward it via regimail to regify support. If even that is insecure, then log onto the console as root and run regifyInfo. Then copy the output and send it via regimail to regify support.

appSupportDiag

Drop into shell

Appliance Settings  Drop into shell provides the regify user with a command line shell to perform advanced operations. Unlike normal administrative appliance tasks, these operations do require Linux knowledge and are not recommended, unless you know what you are doing or are directed by regify technical staff to do so. As it already says, you can type exit to return to the appliance menu. Usually pressing Ctrl+d by itself will also return you to the appliance menu.

appShell

Reboot the appliance

As you might have guessed, Appliance Settings  Reboot the appliance does just that.

Set root password

Appliance Settings  Set root password to change the password for the root account. For security reasons, the old password must be supplied to create the new one. The password must be at least 8 characters long and contain letters and numbers, but no special characters.

appRootPw

Set regify password

Use Appliance Settings  Set regify password to change the password for the regify account. For security reasons, the old password must be supplied to create the new one. The password must be at least 8 characters long and contain letters and numbers, but no special characters.

appRegifyPw

regigate

Overview

regigate is the regify MTA gateway that handles encryption and decryption of regify e-mails in an automated fashion. It is designed to work in conjunction with an organisation’s existing e-mail infrastructure in order to handle regify cryptographic operations. It works by connecting to a regify provider for registering transactions or requesting keys on user’s behalves. It is generally designed to be placed into an organisation’s e-mail flow, but can be flexibly arranged otherwise as well.

regigate Routes

A regigate route consists of an MTA instance connected to a regigate instance. Each instance has its own provider and network settings and listens on its own unique network address. On an initial installation the menu only presents regigate Settings  Add Route…​ as routes must all have been created before high availability can be enabled. These dialogues should be used from an SSH session because many require the use of the clip board to copy or paste contents.

gwMenuNoRoutes

We’ll first go through setting up a route. The first dialog merely states that an SSL cert has been created and that it needs to be signed by the provider for this route to be able to connect to that provider.

routeSelfSigned

Here we are setting up an example inbound route. It listens to port forwarded connections from the Internet on port 25 and forwards all e-mail to smtp.de.regify.com our internal MTA. It also only accepts e-mails to regify.com and de.regify.com to prevent the creation of a potential open relay. IP:port addresses must be unique and only available IP numbers may be chosen for Incoming IP. Have a look into the following MTA Milter Settings chapter for a detailed description of each field.

routeInbound

Then the postfix instances and the milter instance for this route are created.

routeProgress

After that the new route shows up in the route menu in the form of route id - route name, in this case 1 - inbound. Route ids are how the instances are referenced internally and count upward from 1 assigning the first available id.

routeMenu1

When entering a given route, its route settings are displayed. Here list, rules and initially certificates are managed. In this case the certificate still needs to be signed denoted as (Needed). After it has been signed it will be denoted as (Done). The initial rules is empty, meaning all e-mail will be passed unmodified.

routeSettings

MTA Milter Settings

This screen is used to configure postfix instances and the milter. It is the same dialogue as presented after adding a route.

  • Process Rules specifies whether rules are applied per message or per recipient. When Recipient Based is used, all messages to multiple recipients will be split into individual messages before being passed to the rule engine

  • Incoming IP lists all available IP addresses. In High Availability mode this will only be the shared IP chosen during the High Availability setup. Choose which IP the MTA will listen on.

  • Incoming Port is the port where the MTA will listen on. All IP:Port must be unique across all routes.

  • Route Name is optional, but recommended for documentation purposes. The name also shows up in the list.

  • Provider Server is mandatory. It is used to set the provider address where regigate will register and request keys. It is of the form hostname:port. This information is provided by the administrator of your provider. Note that this will not be validated at this point, but only after an initial encryption or decryption request takes place. So care must be taken to validate tis before going live.

  • IP/Subnets to accept e-mail from is used to restrict the IP addresses which are allowed to connect. It is a space separated list of addresses. Its input can be of the following forms:

    • 192.168.1.4 - Will only accept connections from 192.168.1.4.

    • 192.168.1 or 192.168.1.0/24 - Will accept connection from 192.168.1.0 through 192.168.1.255.

  • Domains to accept e-mail for is generally used when regigate listen to the Internet and IP/Subnet…​ is not used. In our inbound example, we accept connections from anywhere but only to e-mails to the listed domains. It is a space separated list of domains.

Domains to accept e-mail for is OR combined with above IP/Subnets to accept e-mail from restriction. A message does not need to match both conditions to go through. One is sufficient! Therefore, you should use either the one or the other option to specify the limitation. Best to not use both options together.
  • Max Message Size…​ allows you to specify how big of an e-mail is acceptable.

  • Forward e-mail to …​ is optional and is used to forward all e-mail to a given MTA for further processing.

  • MTA Hostname is also optional and is usually used when regigate sends its own e-mails, i.e. with the Forward e-mail to option blank, but is behind an address translating gateway. The reverse DNS host name of this gateway should then be set here.

routeInbound

Show Rules

Use Show Rules to display the currently used rule set. This option is used in an emergency when the elsewhere stored copy has been lost, or as a quick way to look at the rule set. The canonical place for a rule set should not be on regigate, but ideally in a backed up source repository. It is designed so that the rule set can be copied out using the clipboard, via SSH only. Here it displays the default empty rule set {}.

routeShowRules

Import Rules

In this dialogue a previously prepared and lint checked rule set maybe pasted in. The new rule set will be validated and if valid, will be applied. Any referenced lists must have been added before.

There is a separate documentation about creation and parameters of rule files!
routeImportRules

Manage Lists

This dialogue is structured similarly to regigate Settings  Add Route…​ in that it lists all current lists followed by an option to add one.

routeEmptyLists

Add List

When pressing List Settings  Add List…​ the first thing it asks is what the name of the new list will be. List names can only contain ASCII letters, numbers, hyphens and underscores.

routeNewListName

After that, the content of the list may be pasted in.

The contents are not validated in any way, whatever is pasted in will be matched line by line in a case sensitive manner.

E-mail addresses must be all lowercase or they will not be matched!

routeImportList

After that the updated menu with the new list will be shown.

routeOneList

Edit List Entry

Each list entry may be edited in the following way. List Settings  Show List displays the list for inspecting or copying to the clip board, List Settings  Import List facilitates pasting new list content from the clip board and List Settings  Remove List removes a given list provided it is not being referenced in the rule set.

routeEditList

Rename a List

In the rare case where a list needs renaming, follow these instructions:

  1. Navigate to Show List of the list to be renamed.

  2. Copy the list content into the clip board.

  3. Navigate to Add List and enter the new name of the list.

  4. Paste the clipboard contents into the following window.

  5. Update your rules to use the new name and paste them into Import Rules.

  6. Navigate to, and exercise Remove List of your old list to remove the old list. This will also insure that the old list is no longer referenced by the rule set.

Show Certificate Request

This request needs to be given to the provider, who in turn returns a signed certificate to be imported. The provider also needs to know the IP address that will be connecting to the provider in order to white list it. This address can be obtained from the Network Settings  Run Diagnostics command’s INTERNET CONNECTIVITY - Public outgoing IP output.

provCertReq

Import Signed Certificate

This dialogue is used to paste the certificate that the provider signed. This step must be taken before the regigate installation can function with this provider.

gwImportCert

Remove Route

Any route may be removed provided HA is disabled. Doing so removes all associated lists, rules, certificates and other configuration.

routeRemovePrompt

Enable High Availability (HA)

The regigate appliance is High Availability enabled. This means a second regigate system can act as a standby machine which becomes active in case the main system has a failure or is taken offline. When HA is enabled, the regigate service no longer listens on it’s standard IP (here in blue), but rather on the shared IP (here in green). The shared IP is set when HA is enabled and must not be used anywhere else on the network. Any E-mail gateways or rule engines must be configured to forward e-mail to the shared IP instead. The provider still requires the standard IP numbers for white listing. While only the certificate of the main regigate service must be signed, the provider must have both regigate system’s IP numbers white listed.

The regigate appliance provides High Availability using the Red Hat cluster stack and http://www.drbd.org/ Linbit’s distributed redundant block device (DRBD) to make configurations and e-mail queues available on multiple systems. Before enabling HA, it is important to read the next 2 sections for the necessary context.

Example: Implementing a Sample Configuration

Do not clone the first regigate syatem! It leads to strange errors that are time consuming to troubleshoot. It is NOT a supported configuration.
regigate shared ip

In order to implement the HA configuration shown in the above diagram follow these steps:

  • Install and configure regigate on the Main regigate with IP 192.168.1.10/24.

  • Visit regigate Settings  Add Route…​ and setup as many routes as needed all listening to the same IP address.

  • Install regigate on the Second regigate with IP 192.168.1.20/24. This regigate system needs to be configured but no routes need to be enabled, because it only acts as a standby for the Main regigate.

  • Visit Network Settings  Advanced Settings  SSH Settings and do the following:

    • Set Allowed IP/Subnet to 192.168.1.

    • Check the Allow root login option.

  • Add the Main regigate to your provider with IP 192.168.1.10 and have the regigate certificate signed by the provider.

  • Add the Second regigate to your provider with IP 192.168.1.20. The certificate need not be signed because the Second regigate system only acts as a standby for the Main regigate system.

  • Visit regigate Settings  Enable High Availability on the Main regigate system.

  • Enter 192.168.1.11 as the Shared IP.

  • Enter 192.168.1.20 as the 2nd regigate IP.

  • Enter the root password of the Second regigate system as the Root Password.

  • Direct your e-mails to 192.168.1.11 for encryption and decryption.

  • Optionally disable SSH root login on the Second regigate system again.

  • Your E-mail gateway should expect incoming e-mail from the regigate system from 192.168.1.10 and 192.168.1.20.

Requirements & Limitations

Before setting up a high availability solution, the following aspects should be given:

  • Both machines should have the same disk size and other characteristics such as CPU and RAM.

  • Both machines should be well connected to each other and on the same LAN. A direct connection via cross over LAN cables, or a dedicated set of bonded NICS (Network Settings  Advanced Settings  Combine Interfaces) would be beneficial, but are not required.

  • Each machine requires its own standard IP number and an extra shared IP is required to allow the regigate service to migrate between the regigate systems during a fail over.

  • Routes may not be added or removed when HA is enabled, but they may be modified.

  • The Shared IP is currently restricted to 1 IP and may not be changed while HA is enabled.

regify High Availability Implementation

It is important to understand the concept of how regigate appliance HA works. Not having grasped that concept can lead to confusion, lost time and misconfiguration. So here are the basic rules that apply:

  • The configuration of HA requires root SSH access to the 2nd regigate system. After HA is configured, SSH connectivity is no longer required.

  • HA always works by having an active main host and a 2nd fail over regigate system that takes over when the main host is unavailable.

  • The 2nd fail over regigate system cannot change the configuration of the service of the normally active main host. This means the HA regigate service can only be modified on the main system. The same goes for any HA configuration of that service.

  • After a failure, the HA regigate service will migrate back to the main host as soon as it is available.

  • Each regigate system can concurrently serve as a 2nd regigate system and run its own regigate services, either local, or in HA mode with the other regigate system. This means 2 regigate systems can both run in HA mode, while each acts as the 2nd regigate system of the other. Each active system runs on its own shared or standard IP in case of non HA mode.

  • Only 2 regigate systems can participate in a HA configuration of any kind.

  • No regigate routes can be added or removed when it is running in HA mode. HA mode must first be disabled.

  • HA currently only works with one floating IP. If more than 1 IP address is used by the routes, HA will be disabled, meaning "Enable High Availability" will not be shown. It will also not be shown if no routes have been configured.

  • In HA mode the regigate no longer listens to its original IP, but only to the shared IP

  • The provider still needs to white list the original IP of each regigate, not the shared IP.

  • The regigate service IP can only be set when enabling HA mode. This means changing the service IP requires disabling followed by enabling HA mode with the new IP.

  • No regigate system in an HA cluster may change its hostname.

  • Enabling HA is a time consuming process that can take several minutes. Delays occur in random places and can therefore not be announced ahead of time. The process is cut up in as many steps as possible to provide progress feedback.

  • In case of a network or timeout induced failure during configuration, it is best to first disable HA in order to come back to a known state, and then re-enabling it again.

With the details out of the way enabling HA presents us with this initial notice.

gwHaConfirm

After answering with Yes, you are prompted to supply the shared IP.

gwHaIp

Then you are prompted for the IP and root password of the 2nd regigate system. As noted below, root SSH access must be provided for this to succeed. After pressing Next, the configuration will commence.

gwHaSsh

Now the lengthy process of configuring HA begins. Depending on the size of your hard disc it can take some time, because the shared DRBD partition must be synchronized over the network.

gwHaProgDrbd

After this process completes the menu looks like this.

gwHaMain

High Availability Status

The regigate Settings  High Availability Status menu item is not only visible if HA is enabled for this system, but also if this system acts as a 2nd regigate system for another. This screen shot shows a basic healthy cluster status.

At this point a basic explanation of what is displayed seems in order. The first row shows the node names of the hosts participating in this cluster. Items like resFs1 stands for resource file system 1, where 1 indicates that this is the first cluster on these two hosts. If one were to Enable another HA from the slave to the master the number would be 2 and the resource consequently resFs2. resVip1 is the virtual IP. resMlt1-1 refers to the milter resource of route 1. The -n notations on resMlt, resPfs (postfix splitter instance) and resPf (postfix instance) refer to the route id of the constituent route.

gwHaStatus

In case there are failures this dialogue allows for cleaning them up. Often errors are only cleaned up on the local system, so this should be done on both systems.

gwHaStatusErr

Put Host on Standby

Use regigate Settings  Put Host on Standby for testing fail over or other maintenance work. After putting the host on standby most options are removed.

gwHaStandby

Put Host Online

The regigate Settings  Put Host Online entry only appears if the system is in standby mode. Since it takes a while for all resources to move back, a progress is displayed to insure the appliance menu is in proper state afterwards.

gwHaUnStandbyProg

Disable High Availability

The regigate Settings  Disable High Availability is available when HA is enabled and the host is not in standby mode.

gwDisable

Exercising it requires root SSH access to the other system, just as regigate Settings  Enabling High Availability did.

gwHaDisable

Since this process also takes considerable amount of time, a progress bar is shown.

gwHaDisProgMta

Disaster Recovery

In the event that one of the two regigate systems experiences catastrophic failure, the second system will continue the service of the failed system. In order to avoid downtime and re-enable HA after a fresh installation of the failed system, proceed as follows:

  1. Install and configure the regigate service of the new system insuring that it is functional.

  2. Redirect e-mail traffic from the standby regigate system to the new system.

  3. Visit regigate Settings  Reset High Availability on the standby regigate system.

This option is always visible when the peer system is offline. It should only be exercised when the peer system has been replaced by a new installation or is otherwise incapable of working within this cluster.

If there are e-mails remaining in the queue of the failed system, you will be prompted to either wait for them to be sent or you can delete them. The latter is merely a last resource option and should not be employed since these e-mails will then be lost.

If the standby system also used the failed system as a 2nd regigate system, its HA configuration will also be reset. Any e-mails in that queue will be handled by the remaining stand alone regigate system after HA has been reset.

gwHaReset
  • Redirect e-mail traffic to the just reset stand alone regigate system

  • Re-enable HA on the new regigate system

  • Redirect e-mail traffic to the new HA regigate cluster

  • Optionally (re-)enable HA on the 2nd regigate system and redirect e-mail traffic to it as needed.

Updates

The top entry of the appliance menu is Check for updates. When that option is exercised the system will consult updates.regify.com to see if there are new patches for your current version and whether there is a new major version available. You will be prompted to confirm each after which the system will install what you have confirmed. If you choose No to all upgrades, the system will remain unchanged.

updatesPatch

If you have upgrades that you want to install, you will get to follow the installation progress and are prompted to press enter at the end, to return to the appliance menu.

updatesProgress

If the appliance menu has been updated, you will be prompted to reload it by simply pressing Enter.

The appliance can only upgrade one major version at a time.

This means that after you have upgraded to a new version, it will automatically check for the next version. If you reboot due to a new kernel, you should again Check for updates, as there may be another major version available. Major version change in this context means 3.1.0 to 3.2.0 or 3.1.0 to 4.0.0. Patch updates mean 3.1.0 to 3.1.1. You will always be updated to the latest patch version when upgrading to a new version. If you are on version 3.1.0 and the following versions are available:

  • 3.1.0

  • 3.1.1

  • 3.2.0

  • 3.2.1

  • 3.2.2

  • 4.0.0

You will first be prompted that the 3.1.1 patch updates are available. Then you will be informed that a new version 3.2.2 is available. If you upgrade to the latest and run Check for updates again, you will be informed that a new version 4.0.0 is available. You may at that point confirm the upgrade to proceed to that version. If you run Check for updates again, you will be informed that there are no new updates available. At this point you know you have the most up to date system.

Updating the regigate Configuration

After an update you need to visit the administrative section of your regigate installation, to apply any missing or changed configurations.