Community Knowledge Base

Configuring SmarterMail for Failover on Windows

This feature is only available in SmarterMail Enterprise.

Who Should Use This

This document is intended for administrators who want to keep SmarterMail available if their mail server fails. It covers the requirements and steps for deploying SmarterMail in a failover configuration on Windows.

Note: Failover requires activation of SmarterMail Enterprise. For licensing information for this product, contact the SmarterTools Sales Department.

Failover Overview

SmarterMail Enterprise lets you install SmarterMail on a standby server that can take over if the primary mail server has a hardware, network or service failure. Only one server runs SmarterMail at a time, so failover keeps mail available during an outage; it doesn't add capacity. If you need to spread load across multiple servers, see SmarterMail High Availability.

SmarterMail Failover Configuration

Understanding How Failover Works

A failover configuration has two servers. The primary server acts as the default SmarterMail server and manages the licensing for the pair. The secondary server is a hot standby: it's powered on and connected, but its SmarterMail service (and usually its web server) is stopped until it's needed. Both servers read their system settings and mail data from the same network share.

SmarterMail doesn't switch to the standby on its own. To fail over, you stop the Network Load Balancing (NLB) host and the SmarterMail service on the primary server, then start the NLB host and the SmarterMail service on the standby. You can do this manually, or have monitoring software run a script when it detects a failure. Sample scripts are included at the end of this document.

Minimal System Requirements

  • Two servers running a version of Windows Server listed in the System Requirements. Windows Server Core is not currently supported.
  • Three IP addresses: one for each server and one for the cluster.
  • Both servers must have their system clocks synchronized.
  • An account for the SmarterMail service to log on as. This can be a domain account, or a local account that exists with the same name and password on both servers and on the server hosting the share.
  • Note: SmarterMail can't use the Local System, Local Service or Network Service accounts in a failover configuration, because those accounts can't access the network share.
  • An SMB file share for SmarterMail's system settings and mail data. We recommend hosting the share on a NAS or SAN configured as RAID 10.

Adding Network Load Balancing to Your Servers

Note: This needs to be performed on both servers.
  1. Open Server Manager.
  2. Select Manage → Add Roles and Features.
  3. Click Next until you reach the Features page.
  4. Check the box next to Network Load Balancing, accept any additional management tools it asks to add, and click Next.
  5. Click Install.
  6. Once the installation finishes, click Close.

Configuring the Load Balanced Cluster for Use with Failover

  1. On the primary server, open Server Manager and select Tools → Network Load Balancing Manager.
  2. Click the Cluster menu item and select New.
  3. In the New Cluster: Connect window, type the IP address of your primary server in the Host text box and click Connect.
  4. When the Interface Name and Interface IP appear, select the Interface Name and click Next.
  5. In the New Cluster: Host Parameters window:
    • Set the Priority to 1, since this is the primary server.
    • Confirm the IP address and Subnet mask are correct.
    • Change the Initial host state to Stopped. This prevents connectivity problems if a server reboots unexpectedly or has a hardware failure. If both servers are set to Started, traffic is split between them.
  6. Note: Monitoring software can run scripts that start and stop the standby when a failure is detected and when the primary server recovers. Without those scripts, all failover is handled manually.
  7. Click Next.
  8. In the New Cluster: Cluster IP Addresses window, click Add and enter your cluster IP address with the same subnet mask you used for the host.
  9. Click Next.
  10. In the New Cluster: Cluster Parameters window, confirm the IP address and subnet mask. You can also enter a Full Internet Name, though this is optional.
  11. Set the Cluster operation mode to Multicast.
  12. Click Next.
  13. In the New Cluster: Port Rules window, click Edit.
    • You can restrict the cluster IP to an individual port or a port range, or allow it on all ports.
    • Set the Filtering mode to Single host.
  14. Click OK.
  15. Verify your settings and click Finish to complete the setup.

Adding the Standby Server to the Cluster

  1. On the standby server, open Server Manager and select Tools → Network Load Balancing Manager.
  2. Click the Cluster menu item and select Connect to Existing.
  3. Note: The cluster needs to be running before you can add the standby server to it.
  4. In the Connect to Existing: Connect window, enter the cluster IP address as the Host and click Connect.
  5. Select the cluster that appears in the Clusters section and click Finish.
  6. In Network Load Balancing Manager, expand Network Load Balancing Clusters, right-click your cluster (it may be listed by its IP address) and select Add Host to Cluster.
  7. In the Add Host to Cluster: Connect window, enter the IP address of the standby server in the Host text box and click Connect.
  8. When the Interface Name and Interface IP appear, select the Interface Name and click Next.
  9. In the Add Host to Cluster: Host Parameters window, set the Priority to 2, confirm the IP address and subnet mask, and set the Initial host state to Stopped.
  10. Click Next.
  11. In the Add Host to Cluster: Port Rules window, you can set the same kind of port rules you set for the primary server. To change them, click Edit. Otherwise, click Finish to complete the setup.
  12. Wait for the servers to converge. If the standby server's host is running, stop it by right-clicking the standby server's name and selecting Control Host → Stop.

Configure a Shared Service Directory

  1. Create an SMB file share named SmarterMail, preferably on a NAS or SAN.
  2. Note: We recommend hosting this share on storage configured as RAID 10.
  3. Inside the SmarterMail share, create a Settings folder. In the examples below, this folder is \\serverName\SmarterMail\Settings.
  4. Give the SmarterMail service account full read/write access to the share. Then, on both servers, open Services, right-click the SmarterMail service, select Properties and set the account on the Log On tab.
  5. Note: Upgrading SmarterMail resets the service to the Local System account, so you'll need to set the account again after each upgrade. See Upgrading Failover Servers.

About the failover.json File

Failover is turned on with a file named failover.json in the Service\Settings folder of each server's SmarterMail installation. By default, that's C:\Program Files\SmarterTools\SmarterMail\Service\Settings. This file doesn't exist on a new installation, so create it if it isn't there. It needs these settings:

  • FailoverIPAddress: the cluster IP address.
  • IsEnabled: set this to true.
  • SharedSystemFilesPath: the Settings folder on the share.

A sample failover.json looks like this:

{
    "FailoverIPAddress": "122.32.55.241",
    "IsEnabled": true,
    "SharedSystemFilesPath": "\\\\serverName\\SmarterMail\\Settings"
}

Match the casing shown above, and use two backslashes for each backslash in the path so the JSON is read correctly. SmarterMail adds a NodeId value to the file the first time the service starts.

Configuring a Fresh Installation of SmarterMail for Failover

  1. Install SmarterMail Enterprise on the primary server using the installer available from the SmarterMail Downloads page, then stop the SmarterMail service.
  2. Install SmarterMail Enterprise on the standby server. Keep the default settings, and make sure the SmarterMail site is configured in IIS.
  3. Stop the SmarterMail service on the standby server.
  4. On the primary server, create the failover.json file in the Service\Settings folder.
  5. Copy the failover.json file to the same folder on the standby server.
  6. Copy all folders and files from the primary server's Service\Settings folder to the Settings folder on the share.
  7. Start the SmarterMail service on the standby server and verify that it's using the paths on the share.
  8. Activate your Enterprise license key on the standby server by logging in to SmarterMail as the system administrator. Then stop the SmarterMail service on the standby server.
  9. Start the SmarterMail service on the primary server, then reactivate your Enterprise license key.
  10. Go to IP Addresses and bind all ports to the cluster IP address. Make sure no other IP addresses have ports bound to them.
  11. To verify the setup, log in to the primary server as the system administrator and go to Gateways / Failover. Both servers are listed on the Failover Servers tab.

Adding Failover to an Existing Installation of SmarterMail

Note: Before you start, configure both servers for Network Load Balancing and set up the shared service directory, as described in the Adding Network Load Balancing to Your Servers, Configuring the Load Balanced Cluster for Use with Failover, Adding the Standby Server to the Cluster and Configure a Shared Service Directory sections above.
  1. Make sure the primary server is running the latest version of SmarterMail and is configured as an IIS site with its binding pointing to the cluster IP address.
  2. Install the same version of SmarterMail on the standby server and configure it as an IIS site with its binding pointing to the cluster IP address. Make sure the standby server's NLB host is stopped.
  3. Stop the SmarterMail service on the standby server.
  4. Copy all of your mail data (located in C:\SmarterMail by default) to the share. Use robocopy if possible, since the primary server can keep running while it copies.
  5. Once robocopy finishes, run it again. The second pass copies only new and changed files.
  6. Stop the SmarterMail service on the primary server.
  7. On the primary server, create the failover.json file in the Service\Settings folder.
  8. Copy the failover.json file to the same folder on the standby server, replacing the existing file if there is one.
  9. Run robocopy one more time to copy any remaining changed files and spool messages.
  10. Copy all folders and files from the primary server's Service\Settings folder to the Settings folder on the share.
  11. Edit the domains.json file in the Settings folder on the share and change the path of each domain to its new location on the share (for example, \\serverName\SmarterMail\Domains\mydomain.com).
  12. Edit the settings.json file in the same folder and replace each instance of the old local path with the share path. For example, if your data was stored in E:\SmarterMail, replace every instance of it with \\serverName\SmarterMail.
  13. In Network Load Balancing Manager, stop the primary server's NLB host, then start the standby server's NLB host.
  14. Start the SmarterMail service on the standby server.
  15. Browse to SmarterMail at the cluster IP address and log in as the system administrator.
  16. Activate your Enterprise license key on the standby server.
  17. Verify that data and settings are being read from the share.
  18. Stop the SmarterMail service and the NLB host on the standby server.
  19. Start the NLB host and the SmarterMail service on the primary server.
  20. Log in to SmarterMail on the primary server and reactivate the Enterprise license key on the Licensing page.
  21. Verify that mail data and settings are being read from the share.

Scripting Failover

Below are sample PowerShell scripts for switching between the primary and standby servers. You can have monitoring software, such as PRTG or SolarWinds, run them when it detects a failure or a recovery.

Preparing PowerShell on the Servers

Both servers need to allow remote scripts and remote PowerShell sessions. On each server, run the following commands in an elevated PowerShell console:

Set-ExecutionPolicy RemoteSigned
Enable-PSRemoting -Force

In the scripts below, replace WAN in the -InterfaceName parameter with the name of your network interface. You can find it by running Get-NlbClusterNodeNetworkInterface in PowerShell on the server. Also replace Server01 (the primary server) and Server02 (the standby server) with the NetBIOS names of your servers, and SmarterMail with the name of your Application Pool if it's different.

Sample Script: Stop the Primary Server and Start the Standby

$StopPrimary = New-PSSession -ComputerName Server01
Invoke-Command -Session $StopPrimary -ScriptBlock {
    Import-Module NetworkLoadBalancingClusters
    Stop-NlbClusterNode -HostName Server01 -InterfaceName "WAN"
    Import-Module WebAdministration
    Stop-WebAppPool SmarterMail
    Stop-Service MailService
}
Remove-PSSession $StopPrimary
$StartSecondary = New-PSSession -ComputerName Server02
Invoke-Command -Session $StartSecondary -ScriptBlock {
    Import-Module NetworkLoadBalancingClusters
    Start-NlbClusterNode -HostName Server02 -InterfaceName "WAN"
    Start-Service MailService
    Import-Module WebAdministration
    Start-WebAppPool SmarterMail
}
Remove-PSSession $StartSecondary

Sample Script: Stop the Standby and Restart the Primary Server

Use these scripts to bring the primary server back online and stop the standby once your monitoring software reports that the primary server has recovered.

$StopSecondary = New-PSSession -ComputerName Server02
Invoke-Command -Session $StopSecondary -ScriptBlock {
    Import-Module NetworkLoadBalancingClusters
    Stop-NlbClusterNode -HostName Server02 -InterfaceName "WAN"
    Import-Module WebAdministration
    Stop-WebAppPool SmarterMail
    Stop-Service MailService
}
Remove-PSSession $StopSecondary
$StartPrimary = New-PSSession -ComputerName Server01
Invoke-Command -Session $StartPrimary -ScriptBlock {
    Import-Module NetworkLoadBalancingClusters
    Start-NlbClusterNode -HostName Server01 -InterfaceName "WAN"
    Start-Service MailService
    Import-Module WebAdministration
    Start-WebAppPool SmarterMail
}
Remove-PSSession $StartPrimary