Table of Contents Previous Next Index

Section 26 Adding Content to the Tomcat Server

Section 26 Adding Content to the Tomcat Server
26.1 Adding the LISTSERV Web Interface tothe Tomcat Server
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.
This can be done either with the LISTSERV configuration tool or by manually editing the site.cfg file:
Open the configuration tool, then click on Advanced Configuration > Web Archives…, and then enter the following information:
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.)
Finally, confirm your settings by clicking [OK]. Restart LISTSERV to make the changes effective.
Editing the SITE.CFG file:
Add (or edit) the following entries:
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.
Verify that the account which is used to run LISTSERV Maestro (i.e. the account which is used to run the "L-Soft Tomcat" service) has execute rights on this wa.exe file. If not, add the execute right.
26.2 Adding Custom Content to the Tomcat Server
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).
26.2.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:
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 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
26.2.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
26.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
26.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 26.4 ListPlex and the Tomcat Server), 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.
26.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”:
26.4 ListPlex and the Tomcat Server
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.
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.1 Adding the LISTSERV Web Interface tothe 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 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.
The ability to run multiple ListPlex 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 ListPlex node:
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:
Below, we call this one additional FQDN the “shared-LMA-FQDN”.
The shared-LMA-FQDN must not reuse any of the ListPlex-FQDNs, but must be a separated 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 ListPlex-FQDNs of above).
If you want all users to access the Maestro User Interface with the same personal FQDN that they also use to access the ListPlex nodes, then you do not need any further FQDNs. Each user will then access LISTSERV Maestro with the same ListPlex-FQDN as he uses to access the WA.
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.
2. Install the ListPlex Nodes
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.
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 ListPlex Nodes
The following procedure must be repeated once for each of the ListPlex nodes:
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.
[install_folder]/webapps-ListPlex_FQDN
Copy the following two folders (and the subfolders and files in them) into the webapps-ListPlex_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-ListPlex_FQDN/archives
[install_folder]/webapps-ListPlex_FQDN/scripts
[install_folder]/webapps-ListPlex_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>ListPlex_FQDN-archives</param-value>
[install_folder]/webapps-ListPlex_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>ListPlex_FQDN-scripts</param-value>
Create four directory junctions (NTFS junction points) in the following folder: [install_folder]/webapps-LISTPLEX_FQDN/
The first junction must be called "lui" and must point to:
[install_folder]/webapps/lui/
The second junction must be called "hub" and must point to:
[install_folder]/webapps/hub/
The third junction must be called "trk" and must point to:
[install_folder]/webapps/trk/
The fourth junction must be called "list" and must point to:
[install_folder]/webapps/list/
To create these junctions, do so here:
On Windows 2000, Windows XP, Windows Server 2003:
You need the tool linkd.exe from the Windows Resource Kit (for example the "Windows Server 2003 Resource Kit", can be downloaded from Microsoft).
Open a command line window and use the cd command to change into the following directory: [install_folder]/webapps-LISTPLEX_FQDN/
Then type (submit with ENTER):
linkd lui "[install_folder]/webapps/lui"
On Windows Vista, Windows 7, Windows Server 2008:
Open a command line window and use the cd command to change into the following directory: [install_folder]/webapps-LISTPLEX_FQDN/
Then type (submit with ENTER):
mklink /J lui "[install_folder]/webapps/lui"
Junctions behave more or less like normal folders. But any changes you make in one of these folders will also affect the original folder in "[install_folder]/webapps" and vice versa.
[install_folder]/conf/tomcat.ini
Add an entry like the following:
AdditionalHost.N=ListPlex_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 ListPlex 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
Verify that the account used to run LISTSERV Maestro (i.e. the account used to run the "L-Soft Tomcat" service) has execute rights on this wa.exe file. If not, add the execute right.
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 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):
WWW_ARCHIVE_CGI=/scripts/WA_EXE_NAME
WWW_ARCHIVE_DIR=[install_folder]\webappsListPlex_FQDN\archives
SITE_CONFIG_CGI_DIR=[install_folder]\webapps-ListPlex_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 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\”.
Repeat the above steps for the next ListPlex 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.
5. Restart all LISTSERV Instances and LISTSERV Maestro.
6. Configure the LUI Access URLs
The LUI access URLs that are configured in the Administration Hub must now also be modified to include the FQDNs used above.
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.
 
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 the ListPlex-FQDNs are used even to access LISTSERV Maestro, then for each user, the Maestro User Interface is accessible via his personal dedicated FQDN, with the following URL:
http://LISTPLEX_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 ListPlex node, you must use the ListPlex-FQDN of that node. Using one of the other ListPlex-FQDNs or the shared-LMA-FQDN (if any) will not work.
When using a shared-LMA-FQDN, you must use this FQDN to access the Maestro User Interface. Using one of the ListPlex-FQDNs will not work.
When using the ListPlex-FQDNs to access LISTSERV Maestro, then to access it with a certain user account, you must use the ListPlex-FQDN associated with this account (or its group). Using one of the other ListPlex-FQDNs will not work.