Section 21 Distributed Components

The three LISTSERV Maestro components, the LISTSERV server(s), the SMTP server(s), and the optional external database(s) may be installed on any combination of hosts, from one single host shared by all components to six or more dedicated hosts, one for each component. If different components are installed on separate servers, it is not necessary that all of the servers have the same operating system. It is possible to install the Maestro User Interface and Administration Hub components on a Windows server and at the same time the Maestro Tracker component on a Linux server and LISTSERV on Solaris (or other combinations). For more information on host restrictions, installing LISTSERV Maestro, and starting and stopping the LISTSERV Maestro service, see the LISTSERV Maestro Installation Manual.

Distributing components has several advantages:

·         Load Distribution – Processor and disk load is shared between several servers, giving each component more “room” to operate.

·         SSL Security – If SSL secure access (that is, HTTPS) is required for HUB and/or LUI, those must be on a separate server than TRK, which must not be configured to use SSL.

·         Separate Maintenance – Not all components have to be shut down or re-started whenever a maintenance task on one of them requires it. The other components may continue running (although when a component that other components rely on is shut down, the others may have to wait for that component to come back up before they can finish performing any tasks).

Specifically, the Maestro Tracker component has very rigid uptime requirements. This component should constantly be running to be able to collect the tracking data from the messages that are sent. It can only do so while it is running and connected to the Internet. Therefore, it is not a good idea to shut down the server on which the Maestro Tracker component is running – this should only be done as a last resort. Other components do not have these strict uptime requirements. To minimize Tracker downtime in the event of maintenance on the tracker components, it is a good idea to have the Maestro Tracker component on a separate server.

For optimal performance for a high-volume installation with requirements for high availability and high performance, a component distribution on five or more servers might be necessary:

·         User-Interface and Hub Server – Contains the LISTSERV Maestro components Maestro User Interface and Administration Hub.

·         Tracker Server – Contains the Maestro Tracker component.

·         Database Server – Contains the Maestro System Database component.

·         LISTSERV Server – Contains the LISTSERV external component.

·         SMTP Server – Contains the SMTP service.

·         Depending on load and performance requirements, you may need additional LISTSERV servers to assign different LISTSERV instances to each account group and/or for bounce processing and/or to serve as “distribute workers” for the primary LISTSERV server(s). To handle high volumes of deliveries quickly, you may also need additional SMTP servers.

Tip: L-Soft Consulting Services can assist you in finding the right configuration for your needs. Contact your L-Soft sales representative for more information.

21.1 Fresh Installation with Distributed Components

A fresh installation with distributed components is a straightforward operation. To install any of the three LISTSERV Maestro components, simply run the LISTSERV Maestro setup on the server where the component(s) will be installed and then select the required components from the list, while leaving all components to be installed on other servers unchecked. The other external components (LISTSERV, external database, and SMTP server) are installed separately. Simply execute each application setup on the respective server(s).

21.2 Moving Components to another Server

If you already have a running installation and plan to move one or several of its components to other servers, you can do so too (this also applies, in slightly different form, if you need to change the host name of the server where your components are installed).

The following sections describe for each component, what you need to do to move it do a different server.

21.2.1 Moving the Maestro User Interface Component to Another Server

Follow these steps to move the Maestro User Interface Component to another server:

1.   As a preparation for moving the Maestro User Interface component, first think about which kind of system database you are using:

a.   If you are currently using an external system database, then you need to make sure that the new server will also be able to contact this external database over the network. You must also remember to add the database driver file(s) for that external database to the fresh installation of your Maestro User Interface on the new server (see step 4 below). Remember to skip steps 2, 6, and 8 below, which are only applicable when using the internal database.

b.   If you are currently using the internal system database, then you must decide whether or not you want the new server to continue using the internal system database or if you want to switch to an external system database instead.

      If you decide to stay with the internal system database, then simply continue with the procedure described here.

     If you decide to switch to an external database, then, for the time being, abandon the procedure described here and first switch to the new database, as described in Section 4.1 Configuring the External System Database . Then return to here, only that now you proceed as described in the bullet above, which deals with an external system database.

2.   Only required if you are using the internal system database: Trigger a backup of LISTSERV Maestro. In the Administration Hub, click Global Component Settings > Administration Hub > General Administration, and then click the [Execute Backup Now] button. Wait for the backup to complete. Check the backup log in the “hub/logs” folder in the LISTSERV Maestro installation folder on the server where the Administration Hub is installed. A backup log with the current date and time must appear, and the log must state that the backup has completed successfully.

3.  Shut down the existing LISTSERV Maestro installation on all servers where components of it are installed. If the internal database is in use and Hosted LISTSERV Lists are being used, then shut down all LISTSERV instances as well.

4.  The Maestro User Interface must not already be installed on the new server. However, the Administration Hub or Maestro Tracker components may already be installed, in which case the Maestro User Interface is added to the existing installation:

a.   If there are no LISTSERV Maestro components already installed on the new server, then simply execute a fresh installation as described in the installation manual for your operating system. During the installation, when queried for which components to install, select only the Maestro User Interface component.

b.   If there are already other LISTSERV Maestro components installed on the new server, then start the installation package for your operating system in the same way as if doing a fresh installation. The installation package will then recognize the existing installation and will give you the option of adding new components to it. Select the Maestro User Interface component to be added and proceed with the installation.

      In both cases, if you are planning to use the internal database on the new server, then remember to also select the MySQL component during installation. If you are not using the internal database, then do not select the MySQL component for installation on the new server.

      After the installation, do not start LISTSERV Maestro!

5.  Transfer the following files and folders (including all files and subfolders in them) from the previous server to the new server:

   [maestro_install_folder]/lui/lui.ini

  [maestro_install_folder]/lui/luidata

  [maestro_install_folder]/lui/registry

      To transfer these files and folders, first delete them on the new server, then replace them with copies of the corresponding files and folders from the previous server (do not just copy the folders from the previous server over the same folders on the new server, since this may result in an inconsistent mix of files from the two servers).

      (Depending on your installation, these paths may be slightly different on one or both of your servers.)

6.   Only required if you are using the internal system database: Copy the backup folder into which the Maestro User Interface (LUI) backup was written during step 2 above. By default, the folder will have a path like:

[maestro_install_folder]/lui/backup

      However, this name may differ if you have configured a different backup folder for the Maestro User Interface component in the Administration Hub.

      Locate the backup folder and copy it to the new server (to a temporary folder outside of the LISTSERV Maestro installation structure).

      Then, edit the following file:

[maestro_install_folder]/lui/lui.ini

      Add an entry like the following:

RestoreBackup=PATH_TO_BACKUP_FOLDER

      where you replace “PATH_TO_BACKUP_FOLDER” with the path of the backup folder which you have just copied to this new server (see above). You can either give an absolute path or a path relative to the location of the “lui.ini” file.

7.   On the old server, you now need to remove the previous installation of the Maestro User Interface component:

a.   On Windows: Use Windows’ Add/Remove Programs panel on the old server to start the maintenance setup of LISTSERV Maestro. In the setup, choose Modify, and then deselect the Maestro User Interface component so that it is uninstalled.

b.   On Linux / Solaris: Start the installation package for your operating system in the same way as if doing a fresh installation (see installation manual). The installation package will then recognize the existing installation and will give you the option of removing components from it. Select the Maestro User Interface component to be removed and proceed with the uninstallation.

8.   Only required if you are using the internal system database: If Hosted LISTSERV Lists are being used, then the database access configuration of all connected LISTSERV instances needs to also be changed so that it points to the internal database on the new server. See the installation manual for details.

9.   Restart LISTSERV Maestro (on all servers), as well as any LISTSERV instances that have been stopped.

21.2.2 Moving the Administration Hub Component to Another Server

Follow these steps to move the Administration Hub to another server:

1.   Shut down the existing LISTSERV Maestro installation on all servers where components of it are installed. If the internal database is in use and Hosted LISTSERV Lists are being used, then shut down all LISTSERV instances as well.

2.   The Administration Hub must not already be installed on the new server. However, the Maestro User Interface or Maestro Tracker components may already be installed, in which case the Administration Hub is added to the existing installation:

a.   If there are no LISTSERV Maestro components already installed on the new server, then simply execute a fresh installation as described in the installation manual for your operating system. During the installation, when queried for which components to install, select only the Administration Hub component.

b.   If there already are other LISTSERV Maestro components installed on the new server, then start the installation package for your operating system in the same way as if doing a fresh installation. The installation package will then recognize the existing installation and will give you the option of adding new components to it. Select the Administration Hub component to be added and proceed with the installation.

     After the installation, do not start LISTSERV Maestro!

3.  Transfer the following files and folders (including all files and subfolders in them) from the previous server to the new server:

[maestro_install_folder]/hub/hub.ini

[maestro_install_folder]/hub/accountreg

[maestro_install_folder]/hub/hubreg

      To transfer these files and folders, first delete them on the new server, then replace them with copies of the corresponding files and folders from the previous server (do not just copy the folders from the previous server over the same folders on the new server, since this may result in an inconsistent mix of files from the two servers).

     (Depending on your installation, these paths may be slightly different on one or both of your servers.)

4.   Edit the following file of the Maestro User Interface component, which may be installed on a different server:

[maestro_install_folder]/lui/lui.ini

      In the file, you need to edit the “RegistryHubHost” entry so that it contains the host name of the new server where the Administration Hub will be running.

      Also, if the new Administration Hub server has an external name and/or port which differs from the externally known name (i.e. the name you used for “RegistryHubHost”), then you also might need to add the entries “HubExternalHostName” and/or “HubExternalHTTPPort”. See Section 20.4 Tomcat INI-File Entries for details.

5.   Edit the following file of the Maestro Tracker component, which may also be installed on a different server:

[maestro_install_folder]/trk/tracker.ini

      In the file, you need to edit the “RegistryHubHost” entry so that it contains the host name of the new server where the Administration Hub will be running.

6.   On the old server, you now need to remove the previous installation of the Administration Hub component:

a.   On Windows: Use Windows’ Add/Remove Programs panel on the old server to start the maintenance setup of LISTSERV Maestro. In the setup, choose Modify, and then deselect the Administration Hub component so that it is uninstalled.

b.   On Linux / Solaris: Start the installation package for your operating system in the same way as if doing a fresh installation (see installation manual). The installation package will then recognize the existing installation and will give you the option of removing components from it. Select the Administration Hub component to be removed and proceed with the uninstallation.

7.   Restart LISTSERV Maestro (on all servers), as well as any LISTSERV instances that have been stopped.

21.2.3 Moving the Maestro Tracker Component to Another Server

Important: Moving the Maestro Tracker component to a different server must be thoroughly planned. The problem is that all mails that were sent while the Maestro Tracker component was still installed on the old server will include mail tracking code with the old server name. If you now shut down and uninstall the Maestro Tracker component on that old server, then all tracking events from those mails will be lost.

Even worse, click-through tracking links will not work any longer at all. This means that if a recipient clicks on a click-through tracked link that is connected to the old Maestro Tracker component’s host name, then the recipient will receive a “Host not found” or “Page not found” error (it will look like a broken link – instead of being routed to the actual link target).

Because of this, you should be very careful when moving the Maestro Tracker component to a different server. Under normal production conditions, this should never be done. Only if your last tracked mailing is already some time in the past and you don’t care about tracking events that get lost and broken links (because since already some time has passed since the mailing, there are no tracking events being generated any longer anyway, or at least only very few).

Of course, you can also solve this problem by changing the DNS registration of the host name.  If the host name for your Maestro Tracker component was previously DNS-registered to point to the IP-address of the old server, then you can change the registration and let it point to the address of the new server instead. From the outside, this will look like there was no change at all (keep in mind that the propagation of a DNS change always takes a few days so, in the interim period, the averse effects of moving the component, as described above, may still happen).

However, if you really need to or want to move your Maestro Tracker component, do so here:

1.   Shut down the existing LISTSERV Maestro installation on all servers where components of it are installed. If the internal database is in use and Hosted LISTSERV Lists are being used, then shut down all LISTSERV instances as well.

2.   Maestro Tracker must not already be installed on the new server. However, the Maestro User Interface or Administration Hub components may already be installed, in which case Maestro Tracker is added to the existing installation:

a.   If there are no LISTSERV Maestro components already installed on the new server, then simply execute a fresh installation as described in the installation manual for your operating system. During the installation, when queried for which components to install, select only the Maestro Tracker component.

b.   If there are already other LISTSERV Maestro components installed on the new server, then start the installation package for your operating system in the same way as if doing a fresh installation. The installation package will then recognize the existing installation and will give you the option of adding new components to it. Select the Maestro Tracker component to be added and proceed with the installation.

     After the installation, do not start LISTSERV Maestro!

3.   Transfer the following files and folders (including all files and subfolders in them) from the previous server to the new server:

[maestro_install_folder]/trk/tracker.ini

[maestro_install_folder]/trk/data

      To transfer these files and folders, first delete them on the new server, then replace them with copies of the corresponding files and folders from the previous server (do not just copy the folders from the previous server over the same folders on the new server, since this may result in an inconsistent mix of files from the two servers).

      (Depending on your installation, these paths may be slightly different on one or both of your servers.)

4.   Edit the following file of your Maestro User Interface component (which may be installed on an entirely different server):

[maestro_install_folder]/lui/lui.ini

      In the file, you need to edit the “TrackerHost” entry so that it contains the host name of the new server where Maestro Tracker will be running (of course, if you also changed the DNS-registration of the old host name to now point to the new server, then you do not have to do this change, since the actual host name is not changed – it only points to a different server).

5.   On the old server, you now need to remove the previous installation of the Maestro Tracker component:

a.   On Windows: Use Windows’ Add/Remove Programs panel on the old server to start the maintenance setup of LISTSERV Maestro. In the setup, choose Modify and deselect the Maestro Tracker component, so that it is uninstalled.

b.   On Linux / Solaris: Start the installation package for your operating system in the same way as if doing a fresh installation (see installation manual). The installation package will then recognize the existing installation and will give you the option of removing components from it. Select the Maestro Tracker component to be removed and proceed with the uninstallation.

6.   Restart LISTSERV Maestro (on all servers), as well as any LISTSERV instances that have been stopped.

7.   If the new server of the Maestro Tracker component is now known with a different name than the previous server was, you also might need to adjust the Tracking Host setting in the Administration Hub. For this, log into the Administration Hub and set the correct tracking host either on global default level, group level or user level, whichever is applicable.

21.2.4 Moving the Database External Component to Another Server

1. Install the database software on the new server and start it.

2. Follow the instructions in Section 4.1 Configuring the External System Database; however, instead of moving from one type of database to a different one, you move between two database which are on different servers, but may actually be the same type of database (e.g. database vendor, version, etc.).

3. If you have done any special configurations or optimizations to your original database (with configuration tools or by editing configuration or INI files), then remember to apply the same adjustments to the new database installation too.

21.3 Server Name Aliases and Proxies

With any given installation of LISTSERV Maestro, the components of LISTSERV Maestro are installed on one or more servers, where each server has its own host name. Components on separate servers use the other server or servers’ name(s) to access the component(s) there. Similarly, the “outside” world (users and email messages that are being tracked) accesses the components with their server names as well.

In the simplest setup, each server hosting a LISTSERV Maestro component will have a DNS name that can be used both for the inter-component communication as well as for “outside” world access. In this case, setup is straightforward and no extra measures have to be taken.

However, there are configurations in which the host names of the LISTSERV Maestro component servers are names known only in the local network, with no DNS names assigned. Or the hosts are, for security reasons, not accessible directly from the outside. Instead, there is a proxy (or other kind of “forwarder”) that sits between the local network and the outside world so that the outside only ever knows the host name (and IP address) of the proxy, but never the names and addresses of the servers behind it (which also may be addresses from a local range, like the 192.168.0.0 subnet).

Figure 67 shows such a setup, where only the proxy has a valid non-local IP address and a registered DNS name (or several names, see examples following the figure), while the LISTSERV Maestro servers have only local names and addresses.

Figure 67 Sample Proxy Setup

Example 1

Assume that the proxy shown in Figure 67 has a single DNS name “maestro.sample.com”. It could be configured to:

·         Forward access on
maestro.sample.com:9001

to local host LUI (192.168.1.1), port 80

·         Forward access on
maestro.sample.com:9002

to local host HUB (192.168.1.2), port 8080

·         Forward access on
maestro.sample.com:9003

to local host TRK (192.168.1.3), port 8888

This example shows how a single DNS name can be “split” to proxy for three different servers, by employing different ports (9001-9003), which are mapped to different hosts (LUI, HUB, TRK) and their corresponding ports (80, 8080, 8888). Users wanting to access the Maestro User Interface would have to use a URL similar to: http://maestro.sample.com:9001/lui.

Users accessing the Administration Hub would use: http://maestro.sample.com:9002/hub

The tracking URLs would contain the URL http://maestro.sample.com:9003/trk

Example 2

As a second example, assume that the proxy has three assigned DNS names lui.sample.com, hub.sample.com and trk.sample.com, which are used to decide which local host to access, so the proxy could be configured to do the following:

·         Forward access on
lui.sample.com:80

to local host LUI (192.168.1.1), port 80

·         Forward access on
hub.sample.com:80

to local host HUB (192.168.1.2), port 8080

·         Forward access on
trk.sample.com:80

to local host TRK (192.168.1.3), port 8888

In this example the “splitting” is realized by using three different host names, all assigned to the same server, where access on the standard HTTP-port 80 is mapped to the different local hosts (LUI, HUB, TRK) and their corresponding ports (80, 8080, 8888) depending on the DNS name used to access the proxy. Users wanting to access the Maestro User Interface would have to use a URL like http://lui.sample.com/lui. Users accessing the Administration Hub would use http://hub.sample.com/hub and the tracking URLs would contain the URL http://trk.sample.com/trk.

This example demonstrates that the host names of the servers hosting the LISTSERV Maestro components may differ when viewed locally or from the “outside” world. Internally, the LISTSERV Maestro components always use the local names to communicate. When setting host names in INI files (or during the setup), use the names that are locally valid (which can also be externally valid names, provided the names work for local access, too). Whenever the local names are different from the external names (usually because some sort of proxying or forwarding is involved), the administrator needs to perform some additional configuration steps to make LISTSERV Maestro aware of the differences.

21.3.1 Configuring LISTSERV Maestro Components with Server Name Aliases or Proxies

If the local name or HTTP port of a host differs from the externally known name or port the following files must be edited:

·         If the Maestro User Interface component’s server has an external host name that is different from the local name, edit the file:

   [maestro_install_folder]/lui/lui.ini

      Add or edit the entry “ExternalHostName” to read:

   ExternalHostName=HOST

where “HOST” is replaced with the external name of the server running the Maestro User Interface component. Do not include port information in the ExternalHostName” parameter.

[maestro_install_folder]/lui/lui.ini

Add or edit the entry “ExternalHTTPPort” to read:

ExternalHTTPPort=PORT

where “PORT” is replaced with the external HTTP (or HTTPS) port number of the server running the Maestro User Interface component.

·         If the Administration Hub component’s server has an external host name that is different from the internal name, edit the file:

[maestro_install_folder]/lui/lui.ini

Add or edit the entry “HubExternalHostName” to read:

HubExternalHostName=HOST

where “HOST” is replaced with the external host name of the server running the Administration Hub component. Do not include port information in the “HubExternalHostName” parameter.

[maestro_install_folder]/lui/lui.ini

Add or edit the entry “HubExternalHTTPPort” to read:

HubExternalHTTPPort=PORT

where “PORT” is replaced with the external HTTP (or HTTPS) port number of the server running the Administration Hub component.

Important: The entries above must go into the lui.ini, not into the hub.ini.

·  If the Maestro Tracker component’s server has an external host name or HTTP port that is different from the internal name/port, set the external host name and/or port in the Tracking URL settings in the Administration Hub. Please see Section 7.3 Setting the Default Tracking URL for more details.

To carry out the examples above, the following changes to the administration settings would have to be made:

·         For Example 1, four lui.ini entries are required:

ExternalHostName=maestro.sample.com

ExternalHTTPPort=9001

HubExternalHostName=maestro.sample.com

HubExternalHTTPPort=9002

In addition, the Administration Hub would be used to configure the tracking URL to use a Tracker Host of maestro.sample.com and a HTTP Port of 9003.

·         For Example 2, two lui.ini entries are required:

ExternalHostName=lui.sample.com

HubExternalHostName=hub.sample.com

In addition, the Administration Hub would be used to configure the tracking URL to use a Tracker Host of trk.sample.com and a HTTP Port of 80. Next, it would be necessary to configure the proxy accordingly, so that it transparently forwards the requests as described above – but this depends on the proxy software used and is not part of the LISTSERV Maestro setup.