Section 1
Introduction

Section 2
Configuring for First Use

Section 3
Changing Admin Password

Section 4
Creating Accounts

Section 5
Global Component Settings

Section 6
Backups

Section 7
Log Files

Section 8
User Interface Settings

Section 9
Database Connections

Section 10
Non-Standard Ports

Section 11
Firewalls

Section 12
SSL

Section 13
Tracking and Recipient Profiles

Section 14
Editing INI Files

Section 15
Distributed Components

Section 16
User Interface Branding

Section 17
International Character Sets

Appendix A
Standard Default Ports

Section 9
Database Connection

The Maestro User Interface component of LISTSERV® Maestro comes ready to use with its own internal database, which is mainly used to store recipient profiles and tracking information. The database installed with the Maestro User Interface is not intended for high-end production use. It is only intended for low-end use and evaluation purposes. Most notably, the internal database (based on MySQL) comes with a storage size (table space) of only 300 MB, and it has not been optimized for large data volumes.

If LISTSERV® Maestro is to be used in a mid- to high-end production environment, (generating a significant number of e-mail jobs), seriously consider configuring the Maestro User Interface component to use a production grade database. The Maestro User Interface has been tested together with the following databases:

  • Microsoft® SQL Server 7.0 and 2000
  • Oracle® 8i Enterprise/Standard Edition Release 3 (8.1.7)
  • DB2® Universal Database V7.2
  • MySQLTM 3.23.42

Figure 14 Database Connection

Database connection screen shot

Install any of these databases (or a compatible version) on the server where the Maestro User Interface component is installed, or on any other server that is reachable over the network. Next, configure the Maestro User Interface to use this database instead of the internal database. Using an external database is highly recommended in a production environment. Please refer to the documentation of the selected database for details on how to install and configure it.

9.1 Preparing the Database

Before the Maestro User Interface can be used together with a freshly installed database, the database must be prepared in certain ways. Outlined below are explanations of the required preparation steps for each of the supported databases.

9.1.1 Preparing SQL Server

In the SQL Server management console, create either a new database for use with the Maestro User Interface or configure one of the existing databases so that the Maestro User Interface can share it. L-Soft recommends that a new database for sole use by the Maestro User Interface be created. Please see the SQL Server documentation for details about how to create, configure and optimize a database.

Once a new database has been created, or an existing one is selected, create a user account that the Maestro User Interface can use to connect to the database. Create a new user with any desired name and give it the "db_public" role for the created or selected database. Next, in the "Permissions" of the database’s "Properties", grant the "Create Table" privilege to this user.

9.1.2 Preparing Oracle

A new Oracle database for sole use by the Maestro User Interface must be created so that it uses UTF-8 as its database character set. The database character set UTF-8 is required and the Maestro User Interface will not work with a database that has a different character set. (See the Oracle documentation for details).

The Maestro User Interface can only use an existing Oracle database if the database uses the UTF-8 character set. To configure an existing database for use with the Maestro User Interface, use an Oracle administration tool (such as SQL*Plus), to create a new user. This new user must have the CREATE SESSION and the CREATE TABLE privilege and a sufficiently large table space quota in the user's default table space.

The Maestro User Interface does not require unusually large rollback segments. If duplicate elimination is performed for large e-mail jobs, larger temporary segments are needed as duplicate elimination is performed with a database sorting operation. See the Oracle documentation for more details on how to configure and optimize databases.

9.1.3 Preparing DB2

To use a DB2 database for the Maestro User Interface, verify that the selected database supports the code set UTF-8. If this code set is not supported by the chosen database, use the DB2 Control Center application to create a new database and define UTF-8 as the database code set.

To configure an existing database that already has the code set UTF-8, verify that at least one user table space and one system temporary table space with a page size of 32K each exist. It may also be necessary to create a buffer pool with a page size of 32K before the table spaces with 32K page size can be created. Next, create a new database user for sole use by the Maestro User Interface. This user must be configured to use a table space with 32K page size; otherwise the Maestro User Interface will not work. The new user needs the Create Table privilege.

Having prepared the DB2 database, the next step is to create a database alias on the server that is running the Maestro User Interface component (this is very probably not the server where the database itself is installed). Do this by starting the IBM DB2 Client Configuration Assistant on the server where the Maestro User Interface component is running. This is a runtime client database tool that comes with the IBM DB2 installation and needs to be installed on the Maestro User Interface component server.

In the Client Configuration Assistant, click the Add button to create a new alias. Select the "Search the network" option and continue with the wizard. For more details on IBM DB2 database administration and the definition of database aliases, see the IBM DB2 documentation. Note that the name of this alias is the value for the "Database name" parameter of the IBM DB2 database plugin that comes with the Maestro User Interface.

9.1.4 Preparing MySQL

To use the Maestro User Interface with MySQL, set up MySQL to use the "InnoDB Tables" table type (see the MySQL manual for more details). This table type supports transactions, and the Maestro User Interface requires a table type that supports transactions. If access to a different table type in MySQL that supports transactions is available, it is possible to attempt to use table type. However, the InnoDB tables are the only table type of MySQL officially supported by L-Soft for use with the Maestro User Interface.

Set up MySQL with InnoDB data files and log files of sufficient size to accommodate the planned usage of the Maestro User Interface. After the MySQL database server is set up to use the InnoDB table type, choose between creating a new database specifically for use with the Maestro User Interface (recommended), or an already existing database, into which the Maestro User Interface will create its own tables. In both cases, it is necessary to create a user with certain privileges. This user will then be selected from the Maestro User Interface to connect to the database.

To connect to the database, start the MySQL client program, "mysql.exe", from the "bin" folder of the MySQL binary installation. To create a new database (optional), enter the following command in the MySQL client: create database NAME; where "NAME" is replaced with the name of the database. Grant privileges by entering the following grant command for the username: grant all on DBNAME.* to NAME@HOST identified by 'PASSWORD'; where the uppercase values are replaced as follows:

    DBNAME: The name of the database to be used with the Maestro User Interface (usually the same name used in the "create database" command, see above).

    NAME: The user name of the user to be created and granted privileges.

    HOST: The host name of the server where the Maestro User Interface is running that will access this database.

    PASSWORD: The password associated with the user name.

Using "grant all" as described above grants all privileges on the given database to the given user. This is usually acceptable if the particular database was created specifically for use with the Maestro User Interface. However, if there is concern about granting the full set of privileges to the user (especially if the Maestro User Interface is to share an already existing database), use the following privilege list instead of "all":

    select, insert, update, delete, index, create, drop

9.2 General Optimization Hints

The following general information about how the Maestro User Interface uses the database can help optimize the database installation for use with the Maestro User Interface.

The Maestro User Interface does not use large transactions. Any transactions that are opened are then closed after a maximum of a few hundred inserts or updates.

During normal usage, the Maestro User Interface behaves with OLTP (online transaction processing) characteristics. There is a constant switch between read and write on the database. However, if there are many reports running on the collected tracking data, the characteristics of the Maestro User Interface’s behavior shift more and more into OLAP (online analytical processing), where the amount of (complex) reads outnumbers the amount of writes.

Use this information to optimize the database after analyzing the usage of the Maestro User Interface to determine if it is working more with OLTP or OLAP characteristics.

9.2.1 General Database Configuration Remarks

The database that is used as storage for the Maestro User Interface should be configured in a way that it allows dynamic growth because the data stored by the Maestro User Interface grows over time. The growth rate corresponds to the number and the size of the e-mail jobs that are delivered. Large e-mail jobs with a high volume of collected tracking events will use more database storage space than smaller e-mail jobs.

Some examples of upper limits that might need to be adjusted for large volume environments are:

  • User space quota - Most databases limit the amount of space that a given user may store in the database. This limit should be set to "unlimited" or a sufficiently large value.
  • Database or tablespace size - Many database vendors, especially those supporting larger database environments, support the sub-division of the database server in smaller areas, sometimes called "tablespaces" or a similar term (see the documentation for details). Normally, each database account is assigned to one of these areas, which are then referred to as "default tablespace" or "standard tablespace". This part of the database should be configured in a way that it allows dynamic growth, if possible. Note: It is possible to use the Maestro User Interface with a database that does not support this type of dynamic growth. To do so, an administrator should make it part of the daily or weekly routine to check the amount of space available for the Maestro User Interface.
  • File system size - Like other server applications storing persistent data on the file system, the database storing the Maestro User Interface data must reside on a server whose file system is monitored on a regular basis, either through automated system administration tools or by an administrator who regularly checks the system.

9.3 Connecting to a Different Database

To configure an installation of the Maestro User Interface to use a different database than the one currently being used, it is necessary to transfer all data from the old database to the new database. The following steps describe this procedure:

  1. Install and prepare the database to be used.

  2. Stop LISTSERV® Maestro (or the Maestro User Interface).

  3. Edit the file "lui.ini" in the home folder of the Maestro User Interface. In a default installation that would be in:

    \Program Files\L-Soft\Application Server\lui"

    Add the following entry: MaintenanceMode=true

  4. Restart LISTSERV® Maestro. The Maestro User Interface component of LISTSERV® Maestro is now running in maintenance mode. While in this mode, no users will be able to log into the Maestro User Interface, so it is safe to transfer the data from one database to the other without the danger of a user generating new data or changing data while the transferring process is happening.

  5. Use the inbuilt backup functionality of the LISTSERV® Maestro to extract all required data from the old database so that it can then be imported into the new database.

    • Log into the Administration Hub.
    • Click the Global Component Settings link, and then to the Administration Hub link.
    • Set the "Time for daily backup" to a time (hour and minute) that is shortly ahead of the current time (within the next minute or so).
    • In order not to overwrite the regular backup with this "special" backup, enter a special backup folder, such as "C:\temp\mybackup". If the backup folder is changed in this way, it must be changed for all components.
    • Click OK to save settings.

  6. Wait until the Administration Hub triggers the backup. This happens at the time that was configured in the previous step, (check the log file of the Administration Hub to see when the backup will be triggered). Next, wait until the backup has been successfully completed. The backup is completed when the final entries regarding the success of the backup and the end date have been written into the backup report. For more details about backups, see Section 6 Saving and Restoring a Backup.

  7. Go back to the Administration Hub section of the Global Component Settings in the Administration Hub and reset the "Time for daily backup" and the "Backup folder" to the standard settings. Click OK to save changes.

  8. While still in the Global Components Settings section, click on the Maestro User Interface link, and then the Database Connection link.

  9. Select "The following custom connection is used" radio button.

  10. Select the database plugin that matches the database and JDBC-driver configuration. If the required plugin in not listed, it has to be registered. For more information, see Section 9.6 Registering a Database Plugin.

  11. Fill out the connection parameters as required by the plugin. The type and semantics of these parameters depend on the database used. Usually, these are parameters such as the host name of the server where the database is running, the database name, the user name and password, or the connection port.

  12. Click OK to save the settings.

  13. Shut down LISTSERV® Maestro.

  14. Edit file "lui.ini" and remove the "MaintenanceMode" entry (or simply comment it out or change its value to "false"). Then add a new entry into file "lui.ini", similar to the example here: RestoreBackup=path_to_backup_folder

    "path_to_backup_folder" is replaced with the path name that leads to the backup folder from which the files and folders as described above were copied. This path name may either be a full path name including the drive letter, or it may be an absolute path without the drive letter (starting with "\" or "/", which is then interpreted as being absolute on the drive/root where the application server is installed, for example, in the default case, the same drive where "\Program Files\L-Soft\Application Server" is located). Or a relative path without a drive letter may be used (not starting with either "\" or "/", which is then interpreted as being relative to the home folder of the Maestro User Interface component, for example, in the default case, that would be the folder "\Program Files\L-Soft\Application Server\lui").

    Using forward slashes "/" or backslashes "\" as the filename separator is acceptable. However, if backslashes are used, it is necessary to use double backslashes. For example, with the path above, either write

    c:/temp/mybackup

    or

    C:\\temp\\mybackup

    This entry to the "lui.ini" file will be automatically removed during the first startup of the component. It is only present to signal to the component that it should restore all required data from the given folder. This happens automatically during the next startup, whenever this INI-file entry is present.

  15. Restart LISTSERV® Maestro.

  16. Verify that the Maestro User Interface is running by checking whether the login page is presented when accessed by a browser. If the login page does not appear, check the log file for error messages to help correct the problem.

Note: Connecting to a different database necessitates that all tracking events be inserted into that new database. This occurs during the next cycle of transferring tracking events from the Maestro Tracker component to the Maestro User Interface component. This may take some time, especially if there already were many events collected. So until the first event transfer (which is triggered after the end of the first event transfer interval after you restart LISTSERV Maestro) is completed, all the reports will result in "No events available". Please be patient until the transfer has been completed.

9.4 Disabling and Enabling the Internal Database

If the Maestro User Interface is connected to a different database, there is no longer a need for the internal database (based on MySQL) to be run together with LISTSERV® Maestro. To reduce the resource usage of LISTSERV® Maestro, disable the internal database after configuring the Maestro User Interface to use a different database.

To disable the internal database, execute the following command:

\Program Files\L-Soft\Application Server\commands\DisableInternalDB.cmd

This will stop the internal MySQL database if it is currently running and will disable it, so that it will not be started again if LISTSERV® Maestro is restarted. Also, the Windows service in which the internal database was run is uninstalled. It is no longer possible to choose the "Use Internal Connection" choice in the Database Connection subsection of the "Maestro User Interface" section, (located in Global Component Settings in the Administration Hub). If this choice is selected by mistake, and LISTSERV ® Maestro is restarted, the Maestro User Interface component will not start, as it will not be able to find the now disabled instance of the internal database. If, at a later point, the internal database is desired, it must be re-enabled with this command:

\Program Files\L-Soft\Application Server\commands\EnableInternalDB.cmd

This will re-enable the internal database and install the necessary Windows service. The next time LISTSERV® Maestro is restarted, the internal database will also be restarted, and can then be used.

9.5 Registering a Database Plugin

LISTSERV® Maestro uses "database plugins" to give access to different JDBC drivers (and through them to different databases) available to the Maestro User Interface. Before a plugin can be used, it must first be registered in the list of known plugins. Some plugins are already pre-registered when LISTSERV® Maestro is installed; while others need to be registered after the corresponding JDBC driver has been installed.

Figure 15 Database Plugins

Database plugins

For the L-Soft MySQL driver plugin:

com.lsoft.lui.db.mysql.MySQLDriverPlugin

For the IBM DB2 V7.2 driver plugin:

com.lsoft.lui.db.ibm.DB2V7DriverPlugin

For the Oracle 8i thin driver plugin:

com.lsoft.lui.db.oracle.Oracle8iThinDriverPlugin

For the Microsoft SQL Server 2000 drive plugin:

com.lsoft.lui.db.sqlserver.MSSQLDriverPlugin

For the I-net SPRINTA driver for MS SQL Server 7.0/2000 plugin:

com.lsoft.lui.db.sqlserver.SPRINTADriverPlugin

Figure 16 Add New Database Plugin

Add a new database plugin

Click OK to submit the class name. If the plugin was registered correctly, it will now appear in the list of plugins. If there was a problem during the registration, an error message describing the problem will appear. The most probable causes for problems are misspellings of the class name (which is case sensitive) or a faulty installation of the JDBC driver that is used by the plugin in question (see Section 9.6 Installing JDBC-Drivers for Different Databases for more information).

9.6 Installing JDBC-Drivers for Different Databases

The Maestro User Interface is a Java server application that uses JDBC to connect to the configured database. Therefore, it is necessary to install a compatible JDBC driver for the database. Each database plugin (see Section 9.5 Registering Database Plugins for more information) has been developed to use exactly one JDBC driver. There may be several plugins for the same database, each of which uses a different driver to access that database. The specific plugin to be used depends on the database and the JDBC driver available for that database.

Important Note: After installing a new JDBC driver into LISTSERV® Maestro (see descriptions below), it is necessary to restart LISTSERV® Maestro to make it aware of the new driver.

The plugins available at the time this document was written support five different drivers for four different databases:

L-Soft MySQL JDBC-driver - For connection to the MySQL database 3.23.42 or later. This driver is installed together with LISTSERV® Maestro. No special installation is necessary to access this driver or its plugin.

IBM JDBC-driver for DB2 V7.2 - To use this driver, first install the DB2 run-time clients (from the runtime folder of the DB2 installation package) on the server(s) where the Maestro User Interface and the Administration Hub are running. Use the client to connect to a database on the DB2 server (see Section 9.1.3 Preparing DB2). It is important to install the clients on the Maestro User Interface server and the Administration Hub sever, not on the server where the database is installed (except of course, if both components happen to be on the same server). Next, copy the file "db2java.zip" from the run-time client installation to the LISTSERV® Maestro installation (shown for a default installation):

    Copy the file "db2java.zip" from the "java" folder in the DB2 run-time client installation

    \Program Files\IBM\SQLLIB\java

    into the "lib" folder in the LISTSERV® Maestro installation

    \Program Files\L-Soft\Application Server\lib

    Where to find the driver: The run-time clients (which in turn include the JDBC-driver file as described above) are included in the installation package for DB2 when a license is purchased. At the time this document was written, a 60-day trial version of the database (including the JDBC-driver) was available at IBM’s website. A valid license for the DB2 database must be purchased from IBM before using its driver or using it together with the Maestro User Interface.

Oracle 8i Thin Driver - This driver comes in the form of a file called "classes12.zip". Simply copy this file into the "lib" folder in the LISTSERV® Maestro installation

    \Program Files\L-Soft\Application Server\lib

    Where to find the driver: The driver can be downloaded from the Oracle Technology Network: http://otn.oracle.com/

    Go to the "Downloads" section and select the "Oracle JDBC Drivers" choice. Then follow the link to download the "Oracle8i 8.1.7 JDBC Drivers for use with JDK 1.2.x for NT". After accepting the license agreement, click on the "JDBC-Thin, 100% Java" link in the section "for use with JDK 1.2.x". This should trigger the download of the "classes12.zip" file. This description mirrors the structure of the OTN-Web site at the time this document was written. The location of the pages and the names of the links may have since have changed. A valid license for the Oracle database must be purchased from Oracle before using its driver or using it together with the Maestro User Interface.

Microsoft SQL Server 2000 JDBC-driver - Install the driver on any computer desired. It is not important that the driver be installed on the same computer as the Maestro User Interface, but it is important that the following files are copied from the installation folder of the driver to the installation folder of LISTSERV® Maestro (shown for a default installation):

    Copy the files "msbase.jar", "mssqlserver.jar" and "msutil.jar" from the "lib" folder in the SQL Server JDBC-driver installation

    \Program Files\Microsoft SQL Server 2000 driver for JDBC\lib

    into the "lib" folder in the LISTSERV® Maestro installation

    \Program Files\L-Soft\Application Server\lib

    This driver is published by Microsoft as a driver for SQL Server 2000 only. It will probably not work with SQL Server 7.0. L-Soft has not tested it with SQL Server 7.0 and only recommends using it only with SQL Server 2000. Also, at the time this document was written, the driver was still in a beta stage (L-Soft has tested both Beta 1 and Beta 2 - the final release is announced by Microsoft for spring 2002). L-Soft has not experienced any problems during our tests with the driver. We do recommend waiting until its final release before using it in a production environment.

    Where to find the driver: At the time this document was written, the beta version of the driver was available for download from this URL at Microsoft's website: http://www.microsoft.com/sql/downloads/2000/jdbc.asp

    In case this URL is no longer valid, try the MS SQL Server site, and look for the downloads section: http://www.microsoft.com/sql/

    A valid license for the SQL Server database must be purchased from Microsoft before using it together with the Maestro User Interface.

I-net SPRINTA JDBC-driver for MS SQL Server 7.0/2000. From the SPRINTA download/installation, copy the file "Sprinta2000.jar" into the "lib" folder in the LISTSERV® Maestro installation

    \Program Files\L-Soft\Application Server\lib

    Where to find the driver: The driver can be purchased from I-net software: http://www.inetsoftware.de/ At the time this document was written, the SPRINTA driver home page could be found at the following location: http://www.inetsoftware.de/English/Produkte/JDBC2/Default.htm The evaluation version of this driver, which is (or was at the time this document was written) available for download, may contain a limitation of the number of concurrent database connections that will make the Maestro User Interface fail during operation. The evaluation version is, therefore, not supported for use with the Maestro User Interface.

    While the SPRINTA driver also supports MS SQL Server 6.5, the Maestro User Interface does not. The Maestro User Interface requires MS SQL Server 7.0 or later. A valid license for the SQL Server database must be purchased from Microsoft before using it together with the Maestro User Interface. Also, a valid license for the SPRINTA driver must be purchased from I-net software before using this driver to access SQL Server.