regify regigate Manual

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.

This document will cover various aspects pertaining to regigate.

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

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.

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.

Below are some note worthy details to point out:

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.

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:

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

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.

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:

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

This leaves us with 3 files:

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.

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.

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

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.

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.

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).

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.

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.

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.

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

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

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.

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

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

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.

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:

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.

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.

Login to the appliance as user regify password regify.

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.

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

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.

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

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

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

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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:

Or:

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

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.

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.

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.

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.

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

Aggregated links may be separated here.

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.

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.

Use Appliance Settings  Time & Locale to set Localisation 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:

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.

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.

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.

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

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.

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.

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:

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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 {}.

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.

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

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.

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

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

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

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.

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

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.

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.

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

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.

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

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

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:

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

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

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.

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.

After this process completes the menu looks like this.

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.

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.

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.

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.

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

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

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

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:

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.

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