Table of Contents Previous Next Index

Section 25 Adding Content to the Tomcat Server

Section 25 Adding Content to the Tomcat Server
In 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 (for example 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 25.2 Defining the Default Context for details).
25.1 Adding Content as a New Context
To create a new context with your own content, the first question that you have to decide is the following:
“Does the server where Tomcat is running have several different host names, and if yes, do you want your own content to show up for all of these host names or not?”
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?
The way that you proceed depends on how you answer this question:
Create a new folder inside of the “webapps” folder of LISTSERV Maestro, like this:
[install_folder]/webapps/CONTEXT/
where you replace “CONTEXT” with the name of your context, for example:
[install_folder]/webapps/sample/
Then proceed as described further below.
If the server has several host names, and you want your content to show up not for all of them, but only for one (or several) specific host name(s):
First you need to decide which one of the desired host names shall be the “main host name”. All others will be aliases. If you have only one desired host name, then this will be the “main host name” and there are no aliases.
Then create a new folder like this one:
[install_folder]/webapps-MAIN_HOST_NAME/CONTEXT/
where you replace “MAIN_HOST_NAME” with the “main host name” and “CONTEXT” with the name of your context, for example:
[install_folder]/webapps-host.domain.com/sample/
Now, add an entry like the following to the tomcat.ini file:
AdditionalHost.N=MAIN_HOST_NAME,ALIASLIST
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:
AdditionalHost.0=host.domain.com,alias.domain.com,alias.domain.org
AdditionalHost.1=host-without-alias.domain.com
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).
Then proceed as described below.
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:
[install_folder]/webapps/archives/WEB-INF/
So that at the end you have something like this:
[install_folder]/webapps/CONTEXT/WEB-INF/
or (in case you have a specific “main host name”):
[install_folder]/webapps-MAIN_HOST_NAME/CONTEXT/WEB-INF/
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:
<param-value>CONTEXT</param-value>
If your context is in a specific “webapps-MAIN_HOST_NAME” folder, then change the text to the “main host name” plus the context name, separated by a dash “-”, like this:
<param-value>MAIN_HOST_NAME-CONTEXT</param-value>
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.
Restart Maestro to make it aware of the new context.
The files in the new context will then be accessed for example as follows:
access to page other.html in the sub subfolder
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 the default “webapps” folder, then you can use any host name that is assigned for this server to access this context, except for any host names which are used as a “main host name” or as an alias host name, as described above (if any).
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 any files into the WEB-INF folder, as they would not be accessible via a URL.
When creating subfolders in your context, do not create a folder called “META-INF”, as this is a reserved name
25.2 Defining the Default Context
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”.
This is not supported out of the box by Maestro but must be configured first.
To define a default context, create a new context (with a new subfolder either in webapps” or in “webapps-MAIN_HOST_NAME”) as described above.
In addition, before restarting Maestro, include the following entry in the tomcat.ini:
DefaultContext=CONTEXT
If your context is in a specific “webapps-MAIN_HOST_NAME” folder:
DefaultContext.MAIN_HOST_NAME=CONTEXT
where you replace “CONTEXT” with the name of your context and, if applicable, “MAIN_HOST_NAME” with the corresponding “main host name”.
For example for a context called “sample” you would have
DefaultContext=sample
- or -
DefaultContext.host.domain.com=sample
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:
access to page other.html in the sub subfolder
In addition, you can leave out the context in the URL but will still see the same pages (but this works only for the default context, of course):
access to page page.html in the root folder of the default context
access to page other.html in the sub subfolder of the default context
25.3 Enabling Access Logging for Added Content
If you add your own content to be served by the Tomcat server, then you might also want to enable the usual web server logging for this content.
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:
[install_folder]/logs
25.3.1 Enabling Access Logging for WA
To enable access logging for the WA component itself, edit the following file:
[install_folder]/webapps/scripts/META-INF/context.xml
and/or to enable access logging for the WA archives, edit the following file:
[install_folder]/webapps/archives/META-INF/context.xml
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):
<Valve prefix="YOURNAME_access_log."
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).
Then, restart LISTSERV Maestro.
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 2.2.5 Serving Multiple LISTSERV Nodes on a Single Server below), then the procedure is slightly different.

In this case, the locations for the two “context.xml” files are slightly different. Instead of editing the files in the locations quoted above, edit the following files:

(1) To enable access logging for the WA component of a ListPlex node with a certain ListPlex-FQDN, edit the following file:

[install_folder]/webapps-LSVNODE_FQDN/scripts/META-INF/context.xml

(2) And/or, to enable access logging for the WA archives of a ListPlex node with a certain ListPlex-FQDN, edit the following file:

[install_folder]/webapps-LSVNODE_FQDN/archives/META-INF/context.xml

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.
25.3.2 Enabling Access Logging for Custom Content
To enable access logging for a given custom content that you have added to Tomcat, use the following procedure:
Copy the following folder (and the files in it) from the “archives” context to your own context (the archives context is automatically installed with each Maestro Tomcat). Copy this folder:
[install_folder]/webapps/archives/META-INF/
So that at the end you have something like this:
[install_folder]/webapps/CONTEXT/META-INF/
or (in case you have a specific “main host name”):
[install_folder]/webapps-MAIN_HOST_NAME/CONTEXT/META-INF
(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):
<Valve prefix="CONTEXT_access_log."
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 default folder “webapps”:
<Valve prefix="sample_access_log."
Example for the context “sample” in the specific folder “webapps host.domain.com”:
25.4 Serving Multiple LISTSERV Nodes on a Single Server
Important: Setting up a server that has LISTSERV Maestro and multiple LISTSERV 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 Adding the LISTSERV Web Interface to the 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 LISTSERV nodes. The following describes how to set up the Tomcat server in this situation, to serve the WA for all nodes on the server.
Notes: The following procedure is only meant for the situation where Tomcat is supposed to serve several WAs at once. For the normal case with a single non-ListPlex LISTSERV installation and its WA, see Section 26 Adding the LISTSERV Web Interface to the Tomcat 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 LISTSERV nodes. However, the procedure can easily be adapted to situations where LISTSERV Maestro is already installed and addition LISTSERV nodes will be added, or the other way round, where some LISTSERV nodes are already installed and LISTSERV Maestro is added and is supposed to serve the WAs for these nodes.

The ability to run multiple LISTSERV nodes on the same server is only available on Windows; therefore, the information in this section only applies to those using Windows.
1. Preparation
For this procedure to work, it is necessary that for the server in question you have several fully qualified domain names (FQDNs) as well as several IP-addresses.
One set of FQDNs and IP-addresses is required for each LISTSERV node:
For each LISTSERV node, you need one separate FQDN whose DNS entry points to a separate IP-address that is assigned to this server (i.e. all LISTSERV nodes must have dedicated FQDNs and IP-addresses). The same IP-address should not be used by any other FQDN (except for a possible second FQDN for the Maestro User Interface access, see below). Below, we call these FQDNs the “LISTSERV-FQDNs”.
For LISTSERV Maestro, you can either use a single FQDN or there can be a separate FQDN for accessing Maestro to match each LISTSERV node.
If all users are supposed to access the Maestro User Interface using the same shared FQDN, then you only need one additional FQDN.
Below, we call this one additional FQDN the “shared-LMA-FQDN”.
The shared-LMA-FQDN must not reuse any of the LISTSERV-FQDNs, but must be a separate FQDN. However, it does not have to point to a separate IP-address. It can point to one of the already existing addresses (for example also share it with one of the LISTSERV-FQDNs of above).
If you want users to access the Maestro User Interface with a personal FQDN, then you need several additional FQDNs, namely one per node.
Below, we call these additional FQDNs the “dedicated-LMA-FQDNs”
The dedicated-LMA-FQDNs must not reuse any of the LISTSERV-FQDNs, but each must be a separate FQDN. However, these dedicated-LMA-FQDNs do not have to use separate IP-addresses, but can share the dedicated IP-address of the corresponding LISTSERV-FQDN of above. The best practice for this is to define a dedicated IP-address per LISTSERV node (as described above) and then define the LISTSERV-FQDN and the dedicated-LMA-FQDN for this customer to both point to this dedicated IP-address.
2. Install the LISTSERV Nodes
First, install the LISTSERV nodes as you usually would. Follow the usual procedure for setting up several LISTSERV nodes on one server. When installing the LISTSERV nodes, do not set them up for using the WWW Interface (WA) at this time (this will come later, as explained below); instead, install all nodes as if no WA access was required.
When installing the nodes, use the dedicated LISTSERV-FQDN with the dedicated IP-address for each node, as is customary when setting up multiple LISTSERV nodes (see above).
Note: Procedures for installing multiple LISTSERV nodes on a single server are available from L-Soft Support.
3. Install LISTSERV Maestro
Install a fresh instance of LISTSERV Maestro on the server. Use the following options and choices in the install wizard:
On the Default LISTSERV Settings screen, leave all entries empty for now. The LISTSERV connection settings will later be supplied in the HUB.
4. Configure Tomcat to serve the WA application for all LISTSERV Nodes
The following procedure must be repeated once for each of the LISTSERV nodes:
Note: In the following, certain placeholders are used which need to be replaced as follows:

LISTSERV_FQDN – Replace with the LISTSERV-FQDN of the node that you are currently configuring.

[install_folder] – The installation folder for LISTSERV Maestro.
[install_folder]/webapps-LISTSERV_FQDN
Copy the following two folders (and the subfolders and files in them) into the webapps-LISTSERV_FQDN” you created above, so that this folder then contains an “archives” and a “scripts” subfolder. Copy these folders:
[install_folder]/webapps/archives
[install_folder]/webapps/scripts
to create these folders:
[install_folder]/webapps-LISTSERV_FQDN/archives
[install_folder]/webapps-LISTSERV_FQDN/scripts
[install_folder]/webapps-LISTSERV_FQDN/archives/WEB-INF/web.xml
Look for the entry that says “<param-value>archives</param-value>”. Edit the value of this entry so that the entry instead looks like this:
<param-value>LISTSERV_FQDN-archives</param-value>
[install_folder]/webapps-LISTSERV_FQDN/scripts/WEB-INF/web.xml
Look for the entry that says “<param-value>scripts</param-value>”. Edit the value of this entry so that the entry instead looks like this:
<param-value>LISTSERV_FQDN-scripts</param-value>
[install_folder]/conf/tomcat.ini
Add an entry like the following:
AdditionalHost.N=LISTSERV_FQDN
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 LISTSERV node), then each entry must use a different value for “N”.
Copy the file wa.exe from the “MAIN” folder of the ListPlex node to the following folder:
[install_folder]/webapps-LISTPLEX_FQDN/scripts/WEB-INF/cgi
Skip this step if you are currently configuring the main LISTSERV instance. Only do this step if you are currently configuring one of the secondary LISTSERV instances:
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 LISTSERV node that you are currently configuring. For example “wa-hq.exe”.
Edit the SITE.CFG of the LISTSERV node that you are currently configuring and add the following entries (linebreak added for readability only):
WWW_ARCHIVE_CGI=/scripts/WA_EXE_NAME
WWW_ARCHIVE_DIR=[install_folder]\webappsLISTSERV_FQDN\archives
SITE_CONFIG_CGI_DIR=[install_folder]\webapps-LISTSERV_FQDN\scripts\
WEB-INF\cgi
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 LISTSERV node has in the [install_folder]\webapps-LISTSERV_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\”.
Repeat the above steps for the next LISTSERV node, until all nodes have been configured in the same fashion. If you later add a new node, repeat the same steps for this node too.
Restart all LISTSERV Instances and LISTSERV Maestro.
LISTSERV Maestro and the LISTSERV Web Interface for each of the nodes will now be available with a web browser via the following URLs:
To access LISTSERV Maestro:
If a shared-LMA-FQDN is used, then for all users, the Maestro User Interface is accessible via this shared name, with the following URL:
http://SHARED_LMA_FQDN/lui
If dedicated-LMA-FQDNs are used, then for each user, the Maestro User Interface is accessible via his personal dedicated FQDN, with the following URL:
http://DEDICATED_LMA_FQDN/lui
To access the LISTSERV interface (WA):
http://LISTSERV_FQDN/archives
http://LISTSERV_FQDN/scripts/wa.exe
With this setup, you now have the following behavior/restrictions:
To access the Web Interface of a certain LISTSERV node, you must use the LISTSERV-FQDN of that node. Using one of the other LISTSERV-FQDNs or the shared-LMA-FQDN or any of the dedicated-LMA-FQDNs (whichever is applicable) will not work.
When using a shared-LMA-FQDN, you must use this FQDN to access the Maestro User Interface. Using one of the LISTSERV-FQDNs will not work.
When using dedicated-LMA-FQDNs, then by default you will be able to use any of these FQDNs to access the Maestro User Interface (this default can however be changed, see below for details). Using one of the LISTSERV-FQDNs will however not work.
As described in the last bullet above, if you are using dedicated-LMA-FQDNs, then by default any of these FQDNs can be used to access the Maestro User Interface. This is because in reality there is actually only one LISTSERV Maestro instance on a server sharing the same IP address. Therefore, any of these host names will allow you to access the Maestro User Interface.
When using dedicated-LMA-FQDNs, you may restrict each group (or non-group account) in such a way that the users of this group/account are only allowed to login if they use their assigned dedicated-LMA-FQDN. If they use a different FQDN (even if that would theoretically be a valid LMA-FQDN) their login shall be rejected.
This is configured in the Administration Hub and needs to be configured for each group and each non-group account that shares the LISTSERV Maestro server with its own dedicated-LMA-FQDN. From the Administration Hub home page, click on Administer User Accounts, click on the group name or non-group account name, click on Maestro User Interface, and then click Login Restrictions.
On the Login Restrictions screen, enter the dedicated-LMA-FQDN that is assigned to the selected group/account into the Required Login Host Name field.
Once you have done this for all groups and non-group accounts, then each group/account will only be allowed to login if they use their assigned dedicated-LMA-FQDN. So if customer-A tried to login using the FQDN of customer-B, then his login would be rejected in the same manner as if his account/group was not known at all, i.e. to one group it would look exactly as if there actually was a different server behind the FQDN used by a different group.