SmarterMail Help
Community Knowledge Base

Installation and Upgrade (Windows)

SmarterMail High Availability, or SmarterMail HA for short, allows businesses to build a fault-tolerant SmarterMail cluster on the exact same code base as previous versions of SmarterMail. It has 2 different installation files, one for hubs and another for nodes.

Jump to:

Why SmarterMail HA Requires CLI

In a High Availability deployment, the hub and every node read and write to a centralized shared data directory (a Windows file share, SAN, or NAS). The SmarterMail service must therefore run as an account — typically a domain account or a shared local account — that has been granted full read/write permissions to that share.

When you run the installer wizard using the .EXE files, the SmarterMail service is configured to run under a default account that will not have those share permissions. Therefore, in order to set the service account at install time, the installer needs to run "silently" from an elevated command prompt and pass the "SERVICE_USER_*" arguments described below. This applies to both the hub and node installers, and must be repeated on every upgrade.

Installer Arguments

All SmarterMail Windows installers (hub and node) accept the following properties. The three "SERVICE_USER_*" properties are what bind the SmarterMail service to your share-authorized account.

  • SERVICE_USER_TYPE (Required) - Tells the installer to run the SmarterMail service under a specific user account. For example: "user".
  • SERVICE_USER_ACCOUNT (Required) - The account the service runs as. This must have full read/write access to the shared hub/node data directories/shares. Use "DOMAIN\User" for a domain account or ".\User" for a local account. For example, ".\SmarterMail-HA".
  • SERVICE_USER_PWD (Required) - The password for the service account. For example: "Your5tr0ngP@5s"
  • /exenoui (Required) - Runs the bundled EXE installer without its UI. (I.e., "silently").
  • /qn (Required) - Passes quiet/no-UI mode through to the underlying MSI.
  • /L*V <path> (Strongly recommended) - Writes a verbose installation log. This allows you to confirm the service account was applied and diagnose failures. For example, use c:\install-log.txt.
Note: Hub installers include "_hub" in the file name. For example, "SmarterMail_HUB_9686". Node installers do not. Always confirm you are running the correct installer for the role you are configuring.

Share Setup

As SmarterMail HA is a clustering solution, emphasizing redundancy and fault tolerance, centralized storage is really a requirement. This can be handled us NFS or Samba shares on Linux, folder shares on Windows, or even using a SAN or NAS. Regardless of what is used, the following will be required so that SmarterMail HA hubs and nodes have access to this shared storage.

  1. Create a network shared directory on your Windows or Linux server, SAN or NAS. NFS or Samba shares work for Linux.
  2. Inside this shared directory, you will want to create a folder for your hub(s) and well as folders for each of your nodes. For example, your folder setup can look like this, where “data” is the shared directory:
    • /data/hub - folder that will be used by each of your hubs
    • /data/node1 - folder for your first node
    • /data/node2 - folder for your second node
    • /data/nodeN - additional folders for any additional nodes
  3. Mount the share created for your hub (e.g., /data/hub/) on the hub server or VM. (NOTE: You do not need to mount shares on your nodes, though you can. If you choose not to, you can add mount/unmount commands for your shares when you walk through Node Configuration.)

Hub Installation

Install the hub from an elevated command prompt (i.e., as Administrator), passing the service-account arguments so the hub can reach the shared \data\hub directory. Be sure to replace the example information for SERVICE_USER_TYPE, SERVICE_USER_ACCOUNT, AND SERVICE_USER_PWD in the template, below, with your own values.

Command Template

<path-to-hub-installer>.exe /exenoui /qn /L*V  SERVICE_USER_TYPE="user" 
        SERVICE_USER_ACCOUNT="\" SERVICE_USER_PWD=""

Example with data

S:\Staging\SmarterMail_Hub_9686.exe /exenoui /qn /L*V C:\Logs\sm-hub-install.txt SERVICE_USER_TYPE="user" SERVICE_USER_ACCOUNT=".\SmarterMail-HA" SERVICE_USER_PWD="Your5tr0ngP@5s"

Note the "_hub_" in the file name of the installer. This ensures you're installing a SmarterMail HA hub!

After the hub installs, continue with the standard hub steps: select or create the IIS site, provide the site name, hostname, IP, and port, review the summary, and let the installer configure the IIS application pools, website, and permissions.

Note: It is possible a first attempt at a silent install will fail with an error (e.g., MSI error 1602/1708). This is not uncommon. If it DOES fail do the following:
  1. Launch the standalone Hub installation .EXE.
  2. When you reach the SmarterMail License/Agreement stage, cancel the installation.
  3. Re-run the command-line installation. It should not complete successfully. Be sure to confirm the success in the verbose installation log.

Node Installation

Note: After installing your first node, and presented with the Getting Started page, you won't be able to go any further until you've actually configured the node in your hub. For more information, see Hub and Node Configuration.

Node installation uses the same command-line approach. Run the node installer from an elevated command prompt with the same service account so the node can reach its shared "\data\node" directory. Be sure to replace the example information for SERVICE_USER_TYPE, SERVICE_USER_ACCOUNT, AND SERVICE_USER_PWD in the template, below, with your own values.

Command Template

<path-to-node-installer>.exe /exenoui /qn /L*V  SERVICE_USER_TYPE="user" 
        SERVICE_USER_ACCOUNT="\" SERVICE_USER_PWD="""

Example with data

S:\Staging\SmarterMail_9686.exe /exenoui /qn /L*V C:\Logs\sm-node1-install.txt SERVICE_USER_TYPE="user" SERVICE_USER_ACCOUNT=".\SmarterMail-HA" SERVICE_USER_PWD="YourStr0ngP@ss"

Note there is no "_hub_" in the file name of the installer. This ensures you're installing a SmarterMail HA node!

Note: Use a service account that has read/write permission to every shared directory the node must reach. If the hub and nodes share one centralized storage location, use the same service account on all of them so permissions stay consistent.

Just as with the silent installation of a hub, the initial silent install of a node may also fail with an MSI error 1602/1708. If so, follow the same remediation steps you did for the hub, noted above.

  1. Launch the standalone SmarterMail installation .EXE.
  2. When you reach the SmarterMail License/Agreement stage, cancel the installation.
  3. Re-run the command-line installation. It should not complete successfully. Be sure to confirm the success in the verbose installation log.

As noted, you cannot cannot proceed setting up the node until it is associated with the hub.

Upgrading SmarterMail HA

To upgrade SmarterMail, first, backup your SmarterMail installation or take a snapshot of your VM.

Upgrading hubs and nodes follow the same silent installation steps noted above. However, it’s important to note that all hubs and nodes should be upgraded to the same version, and that there is an order of operations when it comes to upgrading. This ensures that the upgrade process is smooth and that impact for users is kept to a minimum, and that the hubs are up and running before the nodes attempt to connect.

The order is as follows:

  1. Stop all nodes.
  2. Stop all hubs.
  3. Upgrade both hubs and nodes using the command templates available above.
  4. Start the hubs.
  5. Start the nodes.
Verify after each upgrade: Open the verbose log and confirm the install succeeded, then check that the SmarterMail Windows service is still set to log on as your service account and that mail data is being read from the shared directory.

Things to Know

  • Release Notes for all current Builds of SmarterMail are available on the SmarterMail Release Notes page of our website. Any SmarterMail HA notes are noted using [HA] [Hub] for hub-related updates, or [HA] for general HA updates. It's a great idea to familiarize yourself with all the changes that have been made to SmarterMail between the version you're on and the version you'll BE on once you've upgraded as all updates pertain to a SmarterMail HA.
  • As SmarterMail HA has a monthly License Agreement, all hub and node licenses work like lease licenses: that is, they will always be valid for any new version of SmarterMail that's been released. In addition, HA licenses are retroactive to previous versions of SmarterMail.

Set Up and Configuration of Hubs and Nodes

After SmarterMail is installed, it's time to set up and configure your hubs, and then setting up nodes and associating them to the hub. For more information, see Hub and Node Configuration.

SmarterMail HA DNS Notes

Each node, each hub, any load balancer, and any gateways should have a unique A record configured in DNS. Additionally, each server in your cluster should have a valid PTR record configured that points back to that A record.

If your nodes exist on internal IPs only, the externally facing IP (that traffic will come from when sent from those servers) should have proper A record and PTR records set so that mail servers will not block the traffic as invalid.

Copyright © SmarterTools Inc. All rights reserved.