Bill Stewart's Apache Tomcat Setup for Windows

This Apache Tomcat installer (referred to herein as Setup) is publicly available thanks to permission from the Apache Tomcat Project Management Committee (PMC). If you build a custom version of this installer, you cannot redistribute it publicly without permission from the Apache Tomcat PMC. Please see the Apache Tomcat Legal Page for more information.

---

Table of Contents

• Background
• Download
• Reinstalling or Upgrading
• Setup Command Line Parameters
  • Common Command Line Parameters
  • Windows Service Installation Command Line Parameters
  • Instance Name Defaults
  • Other Command Line Parameters
• Administrative vs. Non-administrative Installation Mode
• Installing Separate Instances
• Setup Type and Components
• Setup Tasks
  • Setting File System Permissions
  • Backing Up the conf Directory
• Finding the jvm.dll File
• Uninstalling Apache Tomcat
• Setup Limitations
• Sample Command Line Parameters
• Acknowledgments

---

Background

I wrote this Inno Setup installer because I needed more functionality than was provided by the Apache Software Foundation (ASF) 32-bit/64-bit Windows service installer, which was built using NSIS. Specifically:

• The ASF installer doesn't provide an easy way to upgrade a Tomcat installation. Using the ASF installer, an upgrade consists of uninstall, click No when it asks if you want to delete all the files (a dangerous question), then install new version using the same options (hopefully you documented your settings). If you installed the service, you will need to reconfigure that as well. If you run the service using a specific account, you will need to specify it again and re-enter the credentials (because the uninstall deleted the service). Java runtime parameters (such as memory sizes, JVM options, etc.) must also be reconfigured.

• The installer-specific documentation is quite brief, and it doesn't mention some very peculiar command line parsing rules (e.g., the /D= command line option must be UPPER CASE and must not be quoted on the command line, even if the target directory name contains whitespace). The configuration options for a silent installation must sit in a text-based configuration file, and some notable Windows service configuration options are missing (service user account, etc.).

• The ASF installer doesn't set file system permissions for the service user account to actually be able to run any web applications because it doesn't have a way to specify the service user account name. This is a peculiar state of affairs when installing the Windows service: The service gets installed, but unless you run the service using the local system or an administrative account (not recommended), web applications won't work because the service user account doesn't have permission to write to the logs, temp, and work directories.

This custom Apache Tomcat Setup installer rectifies these limitations.

Download

You can download the latest version from the Github Releases page:

https://github.com/Bill-Stewart/ApacheTomcatSetup/releases/

Reinstalling or Upgrading

Please note the following when using Setup to reinstall or upgrade Apache Tomcat:

• IMPORTANT: If a file in Setup is newer than the corresponding file already on disk, Setup assumes the file needs to be upgraded and will overwrite it. Therefore, to prevent accidental overwriting of customized files (e.g., configuration files in the conf directory), the Tomcat administrator must update all customized configuration files (open and save to update date and time, or use a "touch" utility) before reinstalling or upgrading.

• Obsolete files in the included web applications are not removed when upgrading. It is the Tomcat administrator's responsibility to manually manage the web application files in the webapps directory.

• If the Windows service is installed, Setup can automatically stop the service, upgrade the binaries, and restart the service. All service installation details are retained when reinstalling or upgrading.

Setup Command Line Parameters

Common Command Line Parameters

Parameter	Description
/currentuser	Runs Setup in non-administrative installation mode (not recommended). See Administrative vs. Non-administrative Installation Mode.
/instancename="name"	Runs Setup to install a separate instance of Apache Tomcat. See Installing Separate Instances.
/dir="location"	Specifies the installation directory. The default location is d:\Program Files\Apache Tomcat (where d: is the Windows system partition).
/type=type	Specifies the installation type. See Setup Type and Components.
/components="componentlist"	Specifies the components Setup should install. See Setup Type and Components.
/group="name"	Specifies the Start Menu group name. The default group name is Apache Tomcat.
/noicons	Prevents creation of a Start Menu group.
/tasks="tasklist"	Specifies the tasks Setup should perform. See Setup Tasks.
/jvmpath="location"	Specifies the path and filename of the jvm.dll file. See Finding the jvm.dll File.
/silent	Runs Setup silently (i.e., without user interaction). For a fully hands-free installation when upgrading, it is recommended to also specify the /closeapplications parameter (see below).
/closeapplications	Setup should automatically stop running services and applications before installing and restart services after installation. (If you omit this parameter and one or more Tomcat services and/or applications are running, Setup will prompt interactively to close them before continuing.)
/log="filename"	Logs Setup activity to the specified file. The default is not to create a log file.

Windows Service Installation Command Line Parameters

The following command line parameters set the default values for the text boxes on the Select Service Configuration Options page and are applicable only when installing the Windows service:

Parameter	Description
/servicename=name	Specifies the Windows service name. This name cannot contain whitespace. The default is Tomcat.
/servicedisplayname="displayname"	Specifies the Windows service display name. The default is Apache Tomcat.
/serviceusername="username"	Specifies the name of the user account that will run the Windows service. The default is NT AUTHORITY\Local Service. For a local account, specify .\username. For a domain account, specify domainname\username.
/jvmoptions="options"	Specifies a semicolon-delimited list of additional JVM (Java Virtual Machine) options.
/jvmms=size	Specifies the initial memory pool size, in megabytes. The default size is 256.
/jvmmx=size	Specifies the maximum memory pool size, in megabytes. The default size is 256.

If the service user account requires a password, you must enter its password in the service configuration dialog after Setup completes.

IMPORTANT - It is not recommended to run the service using an administrative account or the LocalSystem account.

Instance Name Defaults

If you install a separate instance (see Installing Separate Instances), the default values of the /dir, /group, /servicename, and /servicedisplayname parameters will include the instance name. For example, if you specify /instancename="XWiki", the following will be defaults:

• /dir="d:\Program Files\Apache Tomcat - XWiki"
• /group="Apache Tomcat - XWiki"
• /servicename=Tomcat-XWiki
• /servicedisplayname="Apache Tomcat - XWiki"

Other Command Line Parameters

Setup is built using Inno Setup, so it supports the command line parameters common to all Inno Setup installers. Run Setup with the /? parameter for more details.

Administrative vs. Non-administrative Installation Mode

Setup supports both administrative and non-administrative installation modes:

• In administrative installation mode (the default), Setup installs Apache Tomcat for all users of the computer and allows installation of the Windows service.

• In non-administrative installation mode (not recommended), Setup installs Apache Tomcat in the current user's profile. To run Setup in non-administrative installation mode, you must specify the /currentuser parameter on Setup's command line. You cannot install the Windows service using non-administrative installation mode.

Installing Separate Instances

An instance is an independent installation of Apache Tomcat in a separate location. You can use the /instance command line parameter to install multiple Apache Tomcat services on the same computer, or if you need to run separate specific versions of Apache Tomcat.

If you install multiple instances, each installation is considered as a separate application. Each instance will appear as a separate entry in the installed application list in Windows. Each instance must be upgraded, reinstalled, or uninstalled separately. (That is, a reinstall, upgrade, or uninstall of a specific instance affects only that instance.)

Setup Type and Components

Setup's Select Components page allows selection of the setup type and components.

The setup type corresponds to the drop-down list on the Select Components page. Changing the drop-down list selection changes the selected components. The types are as follows:

Type	Name	Components Selected
Default installation	default	core,webapps/docs,webapps/manager
Core only	core	core
Full installation	full	Selects all components
Custom installation	custom	Selects a custom list of components

The /type command line parameter specifies a default setup type; e.g. /type=core specifies that Core only should be the default type.

The default is /type=default.

The components correspond to the checkboxes that represent individual components. The components are as follows:

Component	Name	Notes
Apache Tomcat core	core	Always selected
Web applications	webapps	Can't be selected alone
Documentation bundle	webapps/docs
Manager application	webapps/manager
Host Manager application	webapps/hostmanager
Examples	webapps/examples

The core component consists of the Apache Tomcat binaries and jar files.

The /components command line parameter is a comma-delimited list of components that should be selected by default. For example, /components="core,webapps/docs" selects the core and webapps/docs components by default. (This is equivalent to /components="webapps/docs" because the core component is always selected.)

The default is /components="core,webapps/docs,webapps/manager".

Setup Tasks

Setup's Select Additional Tasks page provides a list of additional tasks that Setup should perform:

Task	Name	Notes
Install Windows service	installservice
Set file system permissions for service user account	installservice/setpermissions	See Setting File System Permissions
Automatically start service when computer starts	installservice/setautostart
Create shortcut to start the service monitor at logon	installservice/startmonitoratlogon
Back up conf directory before installation	backupconf	See Backing Up the conf Directory

The /tasks parameter specifies which tasks are selected by default. Specifying an installservice subtask implies the installservice task (that is, /tasks="installservice/setautostart" is equivalent to /tasks="installservice,installservice/setautostart").

The default is /tasks="installservice/setpermissions,installservice/setautostart,backupconf".

Setting File System Permissions

The installservice/setpermissions task grants file system permissions to the account used to run the service, as follows:

• Apache Tomcat installation directory and subdirectories: Read-only

• conf\Catalina\localhost, logs, temp, and work directories: Modify

Web applications can start successfully with these minimum permissions.

If the service user account is not found, the permission changes will fail silently. In this case, you will need to grant the permissions manually.

IMPORTANT - You may need to change the permissions on one or more of the directories and/or files to properly secure the Apache Tomcat application. (For example, if you use SSL, you will most likely want to restrict access to the certificate's private key file.)

Backing Up the conf Directory

The backupconf task makes a backup copy of the conf directory if it exists (i.e., when reinstalling or upgrading). The backup directory will be named conf-backup-time (where time is the date and time the backup was created).

Finding the jvm.dll File

Apache Tomcat requires a Java Virtual Machine (JVM), so Setup needs to know the location of the jvm.dll file if you are installing the service. Setup attempts to find it automatically in the following ways:

1. It checks for the presence of the JAVA_HOME, JDK_HOME, and JRE_HOME environment variables (in that order). The value of the environment variable is the Java home directory.

2. If the environment variables noted above are not defined, Setup searches the directories named in the Path environment variable for java.exe. The Java home directory is the parent directory of the directory where java.exe is found. For example, if C:\Program Files\Eclipse Adoptium\JRE11\bin is in the path (and java.exe is in that directory), the Java home directory is C:\Program Files\Eclipse Adoptium\JRE11.

3. If java.exe is not found in the Path, Setup searches in the registry for the home directory of the latest Java version installed.

NOTE: If you are running on a 64-bit version of Windows, Setup won't search the 32-bit portion of the registry if it finds any 64-bit versions of Java in the registry. This only applies to the registry search; if Setup finds a 32-bit installation of Java in the environment variables or Path, it will not search the registry.

If any of the above attempts to find the Java home directory succeed (in the above order), Setup appends \bin\server\jvm.dll to the Java home directory and uses the result as the path to the jvm.dll file.

If you have Java installed but Setup fails to find it, you must specify the path to the jvm.dll file on the Select Java Virtual Machine page or by using the /jvmpath command line parameter.

Setup installs the 64-bit Apache Tomcat binaries if the jvm.dll file is 64-bit; otherwise, it installs the 32-bit Apache Tomcat binaries.

The file version of jvm.dll must be at least the minimum version required by the version of Tomcat you are installing. If the jvm.dll file version is older than the minimum version required by the version of Tomcat you are installing, Setup will not continue.

If Setup can't find the jvm.dll file, you can work around the problem by setting the JAVA_HOME environment variable to the Java home directory, and then running Setup again. In recent versions of Windows, you can add an environment variable by running the following command:

rundll32 sysdm.cpl EditEnvironmentVariables

Uninstalling Apache Tomcat

You can uninstall Apache Tomcat installed using Setup by using the standard Windows application management list. The uninstall process does not remove the conf directory or any files Setup did not install.

The uninstall program is located in the uninstall directory in the installation directory and is named uninsnnn.exe (where nnn is three digits, usually 000). Some common uninstall command line parameters are the following:

Parameter	Description
/silent	Runs the install silently (i.e., without user interaction).
/log="filename"	Logs uninstall activity to the specified file. The default is not to create a log file.

See the Inno Setup documentation for more uninstaller command line parameters.

Setup Limitations

• Setup doesn't provide a way to configure server port (server.xml) or Manager web application (tomcat-users.xml) details (these items must be configured separately after installation).

• Setup does not provide the ability to uninstall an upgrade (i.e., downgrade). To downgrade, you must first uninstall the current version and then install the desired version. For this reason, it is recommended to keep the Setup programs of previous versions available just in case.

• Setup uses WMI (Windows Management Instrumentation) API calls to detect running services and applications. If you have stopped or disabled the WMI service (not recommended), Setup will not be able to detect running services and applications and will attempt to replace files that are in use. The only workaround in this case is to manually stop running Tomcat services and/or applications before reinstalling or upgrading.

Sample Command Line Parameters

/type=core
/serviceusername="FABRIKAM\AppService"
/jvmoptions="-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT"
/silent
/closeapplications
/log="C:\Users\KenDyer\Documents\ApacheTomcatSetup.log"

(All on one line)

These options perform a silent installation of Apache Tomcat. The service will run using the account FABRIKAM\AppService and will trust the Windows certificate store. Setup will log its activity to the specified log file.

Acknowledgments

Special thanks to the following:

• Apache Software Foundation: For providing the Apache Tomcat software.

• The Apache Tomcat Project Management Committee (PMC): For granting permission to publicly distribute this Setup program with the copyrighted Apache Tomcat images.

• Jordan Russell and Martijn Laan: For making the excellent Inno Setup tool publicly available.