The Tomcat server of LISTSERV Maestro can also be used to serve the LISTSERV Web Interface (WA) when LISTSERV is installed on the same server as LISTSERV Maestro. This eliminates the need for an extra web-server for serving the web interface pages of LISTSERV.
Note: The following procedure is only meant for the situation where a single LISTSERV instance is present on the LISTSERV Maestro server, and Tomcat is supposed to serve the WA of this instance. If there are several ListPlex LISTSERV nodes on the server, see Section 26.4
ListPlex and the Tomcat Server.
If LISTSERV Maestro and LISTSERV were installed together via the Express Setup option of the LISTSERV Maestro Setup-Suite, then this integration of the LISTSERV Web Interface into the Tomcat server has already been performed by the setup procedure.
If LISTSERV Maestro and LISTSERV are installed independently (but on the same server), then it is still possible to use LISTSERV Maestro’s Tomcat server to also serve the LISTSERV Web Interface pages. The necessary folders are already in place in the Tomcat installation folder; therefore, the only additional configuration necessary is to tell LISTSERV about this.
•
|
In the Directory from which the web server is authorized to run scripts field, enter: [install folder]\webapps\scripts\WEB-INF\cgi
|
•
|
In the URL to use to access the web archive script in the above directory field, enter: /scripts/wa.exe
|
•
|
In the Directory in which LISTSERV should place the files it creates and uses for the Web archive interface field, enter: install folder]\webapps\archives
|
(Replace “[install folder]” with the LISTSERV Maestro installation folder on your system.)
WWW_ARCHIVE_CGI=/scripts/wa.exe
WWW_ARCHIVE_DIR=[install folder]\webapps\archive
SITE_CONFIG_CGI_DIR=[install folder]\webapps\scripts\WEB-INF\cgi
(Replace “[install folder]” with the LISTSERV Maestro installation folder on your system.)
Finally, save the SITE.CFG file with the new settings. Restart LISTSERV to make the changes effective.
n LISTSERV Maestro, the various parts that are served by Tomcat are called “contexts”. Each context is an entity of its own inside of the Tomcat server. Each context has a name, which is also part of the URL that you use to access the context. More precisely, the context’s name is the part which appears right after the server name. For example, for LUI, the context name is
lui, so the URL is
http://yourhost/lui. Other LISTSERV Maestro contexts are
hub,
trk,
list,
archives, and
scripts, with the respective URLs (
http://yourhost/hub,
http://yourhost/list, etc).
If you enter a context’s access URL (as above), what you actually get is the default page for that context (usually a page called
index.html,
index.jsp,
default.htm, etc.). Therefore, if you type
http://yourhost/lui, then what you actually get is the default page for the
lui context (
http://yourhost/lui/index.jsp).
To add content of your own (e.g. HTML pages, images, downloadable files, etc.) to the Tomcat installation of LISTSERV Maestro, you simply create a new context and put your files into that context. The files are then accessible using the URLs in that context.
Out of the box, Maestro does not support content or pages that are not part of a context. However, it is possible to support such content or pages once some additional configuration steps are taken (see Section 26.2.2
Defining the Default Context).
Or in different words: Depending on which host name is used in the access URL when the user tries to access your content, is the content to show up for all host names in the URL, or only for specific ones?
where you replace “MAIN_HOST_NAME” with the “main host name” and “
CONTEXT” with the name of your context, for example:
where you replace “MAIN_HOST_NAME” with the “main host name” and “ALIASLIST” with a comma-separated list of all aliases (or leave out the “,ALIASLIST” part if there are no aliases). Also you need to replace the “N” with a unique number, i.e. there must not be two “AdditionalHost.N” entries with the same “N”. For example:
Note: You can have several such “
AdditionalHost” entries in the tomcat.ini file (as shown in the example above). Each of these entries defines one additional host, with a “main host name” and optionally a list of aliases for this host. The host names used by these entries must be unique, i.e. you must not use the same host name in two different “
AdditionalHost” entries (neither as a “main host name” nor as an alias).
As your next step, copy the following folder (and the files in it) from the “archives” context to your own freshly created context (the archives context is automatically installed with each Maestro Tomcat). Copy the following folder:
In the “WEB-INF” folder that you just copied, edit the file “web.xml” and look for the entry that says “
<param-value>archives</param-value>”. Change the text “
archives” as follows:
Now you can put whatever files you want into your “CONTEXT” folder (you can also create subfolders). Usually you may want to include a start page like “index.html” or similar, but you can also have other pages, even in subfolders. Also image files or other downloadable content if you want.
Where of course you have to replace “CONTEXT” with your own context name and “
HOST” with the correct host name for this context:
•
|
If your context is in a specific “webapps-MAIN_HOST_NAME” folder, then you can only use this “main host name” and its aliases to access this context. Also, you can not use this “main host name” or any of its aliases to access any contexts in the default “webapps” folder (including the default Maestro contexts) or any contexts in other “webapps-DIFFERENT_MAIN_HOST_NAME” folders (if there are any).
|
Warnings: In the default “
webapps” folder,
do not create custom contexts with one of the reserved names used by LISTSERV Maestro, i.e. do not call your context lui, hub, trk, list, archives, or scripts.
Do not put files into the
WEB-INF folder, as they would not be accessible via a URL.
The default context is the context that is used if the user types the access URL without any context name; for example, only “
http://yourhost” or “
http://yourhost/” or “
http://yourhost/somepage.html”.
where you replace “CONTEXT” with the name of your context and, if applicable, “
MAIN_HOST_NAME” with the corresponding “main host name”.
Warning: Do not define any of the reserved LISTSERV Maestro contexts as the default context (lui, hub, trk, list, archives or scripts)!
With this entry in the tomcat.ini, the specified default context can now be accessed in two ways:
With enabled access logging, Tomcat will create log files in the same format as those created by standard web servers. These logs can later be analyzed by standard log analysis tools to track page hit counts, user session activity, and so on. The log files are created separately (under different names) for all contexts for which access logging is enabled and are rolled over nightly at midnight. All access log files are created in the following folder:
In this file, add a “<Valve>” tag similar to the following, just before the “
</Context>” closing tag, so that the resulting “
context.xml” file looks similar to this (the part that you should add is marked with bold):
In this tag, replace “YOURNAME” with a name that uniquely identifies the context for which you are enabling the logging, for example “
WA” or “
Archives” (this will become part of the log file name).
Note: The above procedure applies to a normal LISTSERV installation only, with a single LISTSERV instance, whose WA is served by Tomcat. In case you are dealing with an installation, with several LISTSERV instances where Tomcat serves the WA applications of all of these instances (see Section 26.4
ListPlex and the Tomcat Server), then the procedure is slightly different.
Also, when deciding on a substitution for “YOURNAME” (see above), you should include the FQDN of the LISTSERV node you are configuring (for example “
LSVNODE_FQDN-WA” or “
LSVNODE_FQDN-Archives”), so that the access logs of the WA applications of the various LISTSERV nodes will get different file names.
(where “CONTEXT” stands for the name of your context).
•
|
In the “META-INF” folder that you just copied, edit the file “ context.xml” and look for the “ <Valve>” tag. If one already exists, edit the value of its “ prefix” attribute. If no such “ <Valve>” tag exists, add a new one similar to the following, just before the closing “ </Context>” tag. The resulting “ context.xml” file should then look similar to this (the part that you are supposed to add is marked with bold):
|
•
|
In this tag, replace “CONTEXT” with the name of your context, or in case that you have a specific “main host name”, replace it with the “main host name” and the context name, separated by a dash “–” (this prefix will become part of the log file name).
|
Example for the context “sample” in the specific folder “
webapps host.domain.com”:
Important: Setting up a server that has LISTSERV Maestro and multiple ListPlex nodes is a complex operation. For best results, we recommend that you utilize
L-Soft’s consulting and installation services.
As described in Section 26.1 Adding the LISTSERV Web Interface tothe Tomcat Server, it is possible to use LISTSERV Maestro’s Tomcat server to serve the LISTSERV Web Interface (WA) for a LISTSERV instance that is installed on the same server as LISTSERV Maestro.
This is also possible if on the LISTSERV Maestro server there is not only a single LISTSERV instance, but a whole array of ListPlex nodes. The following describes how to set up the Tomcat server in this situation, to serve the WA for all nodes on the server.
The procedure described here assumes that you are starting with a clean server, on which neither LISTSERV Maestro or any LISTSERV instance is installed yet. For example, a server where you freshly set up a LISTSERV Maestro installation plus a number of ListPlex nodes. However, the procedure can easily be adapted to situations where LISTSERV Maestro is already installed and addition ListPlex nodes will be added, or the other way round, where some ListPlex nodes are already installed and LISTSERV Maestro is added and is supposed to serve the WAs for these nodes.
•
|
For each ListPlex node, you need one separate FQDN whose DNS entry points to a separate IP-address that is assigned to this server (i.e. all ListPlex nodes must have dedicated FQDNs and IP-addresses). The same IP-address should not be used by any other FQDN. Below, we call these FQDNs the “ListPlex-FQDNs”.
|
One of the reasons for the dedicated ListPlex-FQDNs is, that this makes it possible for each ListPlex customer to access his personal ListPlex node by using his personal ListPlex-FQDN.
The question now is, do you want to offer the same behavior when accessing the Maestro User Interface? Depending on how you answer this, you need slightly different setups:
The dedicated-LMA-FQDNs must not reuse any of the ListPlex-FQDNs, but each must be a separate FQDN. However, these dedicated-LMA-FQDNs do not have to use separate IP-addresses, but can for example share the dedicated IP-address of the corresponding ListPlex-FQDN of above. The best practice for this is, to define a dedicated IP-address per ListPlex node (as described above) and then define the ListPlex-FQDN and the dedicated-LMA-FQDN for this customer to both point to this dedicated IP-address.
First, install the ListPlex nodes as you usually would. I.e. follow the usual procedure about how to set up several ListPlex nodes on one server. When installing the ListPlex nodes, do not set them up for using the WWW Interface (WA) at this time (this will come later, as explained below). That is, install all nodes as if no WA access was required.
When installing the nodes, use the dedicated ListPlex-FQDN with the dedicated IP-address for each node, as is customary when setting up ListPlex nodes (see above).
Note: Procedures for installing multiple ListPlex nodes on a single server are available from L-Soft Support.
Note: In the following, certain placeholders are used which need to be replaced as follows:
ListPlex_FQDN – Replace with the ListPlex-FQDN of the node that you are currently configuring.
[install_folder] – The installation folder for LISTSERV Maestro.
where you replace the “N” with a unique number (for example “0”, or “1” or similar), in such a fashion, that if there are several “
AdditionalHost.N” entries in the
tomcat.ini file (as is the case as soon as you configure the second ListPlex node), then each entry must use a different value for “
N”.
Rename the wa.exe file that you just copied into the “
cgi” folder from “
wa.exe” to “
wa-INSTANCE_NAME.exe”, where “
INSTANCE_NAME” must be replaced with the value of the “
INSTANCE” variable in the
SITE.CFG of the ListPlex node that you are currently configuring. For example “wa-hq.exe”.
•
|
Edit the SITE.CFG of the ListPlex node that you are currently configuring and add the following entries (linebreak added for readability only):
|
where you replace “WA_EXE_NAME” with the name that you gave the WA executable in the previous step (make sure to check which name the WA executable for this ListPlex node has in the
[install_folder]\webapps-ListPlex_FQDN\scripts\WEB-INF\cgi folder).
Important: In the above entries in the
SITE.CFG, make sure not to specify a path which contains spaces. This means, that if the path of “
[install folder]” contains folders with spaces in their names (which is, for example, the case for LISTSERV Maestro’s default install folder “
C:\Program Files\L Soft\Application Server\”), then you must use the space-free 8.3 variants of these folder names, for example “
C:\Progra~1\L-Soft\Applic~1\”.
•
|
If a shared-LMA-FQDN is used, then you should simply configure the Default LUI Access URL and let all accounts/group inherit this default setting (since they are all using the shared-LMA-FQDN). Edit the Default LUI Access URL to use this shared-LMA-FQDN. To edit, selct Global Settings > Maestro User Interface > Default URL Settings. All accounts and groups should then simply inherit this setting.
|
•
|
If the ListPlex-FQDNs are used even to access LISTSERV Maestro, then each account/group has its own FQDN, so each has a different LUI access URL too. Because of this, you need to edit the LUI Access URL of each account/group to use the corresponding ListPlex-FQDN. To access, select the user account or group, then User Account or Group > URL Settings. Edit the LUI Access URL for Users or LUI Access URL for Group.
|