Upgrading server.xml for Tomcat 11

iGrafx Platform 20.0 upgrades the bundled Tomcat from version 9 to version 11. If you have customized your installation's conf/server.xml — most commonly for HTTPS certificates, AJP connectors, or other non-default settings — some of those customizations won't work as-is on Tomcat 11. This guide walks through the changes that matter to iGrafx customers and shows the updated syntax for each.

If you have not customized server.xml, you don't need to change anything. The installer ships a known-good server.xml that works out of the box with Tomcat 11.

Before you upgrade

1. Back up your current conf/server.xml.
2. Identify any sections that differ from the iGrafx default (we ship reference copies with each release — see Reference configurations below).
3. Apply the syntax changes documented below.
4. Restart Tomcat and verify the application starts cleanly.

If Tomcat fails to start after the upgrade, the cause is almost always one of the items in the Breaking changes section.

Breaking changes

These changes prevent Tomcat from starting or break specific features. Address them before upgrading.

HTTPS connector: old SSL attributes have been removed

This is the most common customization affected by the upgrade.

Before (Tomcat 9):

<Connector port="8443" SSLEnabled="true" scheme="https"
           keystoreFile="conf/keystore.jks" keystorePass="changeit"
           keyAlias="tomcat" clientAuth="false" sslProtocol="TLS"
           keystoreType="JKS" />

After (Tomcat 11):

<Connector port="8443" SSLEnabled="true">
    <SSLHostConfig protocols="TLSv1.2+TLSv1.3">
        <Certificate certificateKeystoreFile="conf/keystore.jks"
                     certificateKeystorePassword="changeit"
                     certificateKeyAlias="tomcat"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

Attribute name mapping:

Tomcat 9 attribute	Tomcat 11 equivalent	Location
keystoreFile	certificateKeystoreFile	<Certificate>
keystorePass	certificateKeystorePassword	<Certificate>
keyAlias	certificateKeyAlias	<Certificate>
keystoreType	certificateKeystoreType	<Certificate>
clientAuth	certificateVerification	<SSLHostConfig>
sslProtocol	protocols	<SSLHostConfig>
truststoreFile	truststoreFile	<SSLHostConfig> (unchanged name, new location)
truststorePass	truststorePassword	<SSLHostConfig>

AprLifecycleListener: SSLEngine attribute removed

Before:

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />

After:

<Listener className="org.apache.catalina.core.AprLifecycleListener" />

OpenSSL support is now controlled via the useOpenSSL attribute, which defaults to true.

AJP connector: now requires a shared secret

If you use mod_jk or mod_proxy_ajp to front Tomcat with Apache HTTP Server or another reverse proxy, your AJP connector must declare a secret. A bare:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

fails to start with a secretRequired error.

Recommended: set a shared secret and configure the same secret in your AJP worker.

<Connector port="8009" protocol="AJP/1.3"
           address="::1"
           secret="your-shared-secret-here"
           redirectPort="8443" />

Alternative (only when AJP is bound to a trusted local network):

<Connector port="8009" protocol="AJP/1.3"
           address="::1"
           secretRequired="false"
           redirectPort="8443" />

Additionally, AJP now binds to localhost only by default (::1 or 127.0.0.1). If your reverse proxy is on a different host, set address="0.0.0.0" or a specific interface IP.

LegacyCookieProcessor has been removed

If your server.xml includes:

<CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />

remove the line. Tomcat 11 supports only the RFC 6265 cookie processor, which is the default. There is no in-Tomcat workaround for RFC 2109 compatibility; if you have clients that depend on the legacy cookie format, you'll need to update them.

Changes in default behavior

These changes don't prevent startup, but may change behavior in ways worth verifying.

TLS 1.0 and TLS 1.1 are disabled by default

If you have explicitly configured your connector to accept TLS 1.0 or 1.1:

<SSLHostConfig protocols="TLSv1+TLSv1.1+TLSv1.2">

Tomcat 11 accepts the configuration, but the underlying JDK (Java 11 and later) disables TLS 1.0 and 1.1 by default and refuses to negotiate them. If you have legacy clients that require older TLS, they fail to connect. The recommended configuration is:

<SSLHostConfig protocols="TLSv1.2+TLSv1.3">

Session cookie SameSite default

Tomcat 11 keeps SameSite=Lax as the default for session cookies. If you previously set a different value:

<CookieProcessor sameSiteCookies="None" />

the configuration still works, but verify it remains appropriate for your deployment. Browsers require SameSite=None cookies to also carry the Secure flag, so this setting is only viable over HTTPS.

JDBCRealm has been removed

If you use a custom realm declaration:

<Realm className="org.apache.catalina.realm.JDBCRealm" ... />

replace it with DataSourceRealm:

<Realm className="org.apache.catalina.realm.DataSourceRealm"
       dataSourceName="jdbc/UserDB"
       userTable="users" userNameCol="user_name" userCredCol="user_pass"
       userRoleTable="user_roles" roleNameCol="role_name" />

This change is unlikely to affect standard iGrafx installations, since iGrafx manages authentication within the application rather than via Tomcat realms.

Unchanged

For reference, the following are unchanged between Tomcat 9 and Tomcat 11 and require no migration:

• <Engine>, <Host>, <Server>, <Service> element structure and attributes
• Standard valves: AccessLogValve, ErrorReportValve, SingleSignOn, StuckThreadDetectionValve, RemoteIpValve
• LockOutRealm, UserDatabaseRealm
• <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"> and Tribes membership classes
• Shutdown port configuration (port="-1" to disable)
• <Context> element inside server.xml (still supported, though placing it in META-INF/context.xml has been the recommended approach since Tomcat 7)

Other configuration files

While server.xml is the focus, customizations in adjacent files in conf/ may also need attention:

• catalina.properties — the package.access and package.definition allow-lists have been updated for Jakarta EE 11. If you have added custom entries, review them against the iGrafx default.
• web.xml (the global default web descriptor) — the namespace has been updated to Jakarta EE 11: xmlns="https://jakarta.ee/xml/ns/jakartaee".
• context.xml — <WatchedResource> entries are unchanged; the <Resources> child element structure is stable.

Reference configurations

The iGrafx installer ships a known-good server.xml for each deployment type. If you want to start fresh and discard your customizations, copy the appropriate reference file into your installation:

Deployment	Reference path
Standard distribution	platform-distribution/externalbin/apache-tomcat-igrafx/conf/server.xml
Docker	platform-distribution/externalbin/docker/server.xml
Azure App Service	platform-distribution/externalbin/azure-wrapper/server.xml

Related

• Official Tomcat 11 migration guide — the upstream reference covering every change between Tomcat 9 and 11.
• Tomcat 11 documentation — the full configuration reference for the new version.

Getting help

If you encounter issues that aren't covered here after upgrading, contact iGrafx support with your modified server.xml and the contents of logs/catalina.out from the first failed start. Most upgrade issues can be diagnosed from the Tomcat startup log.