Hot Reloading server.xml in Tomcat 8: Adding New Host Without Server Restart


4 views

When working with Apache Tomcat 8, many administrators wonder about the possibility of modifying the server.xml configuration without downtime. The good news is that Tomcat does support limited hot reloading capabilities, though with some important caveats.

Not all modifications to server.xml can be applied dynamically. Major structural changes like:


<Server>
    <Service>
        <Connector port="8080" protocol="HTTP/1.1"/>
        <Engine>
            <Host name="newdomain.com" appBase="webapps_new"/>
        </Engine>
    </Service>
</Server>

Adding a new Host element as shown above generally requires a full restart. However, Tomcat 8 introduced improved JMX capabilities that can sometimes help avoid this.

For adding new virtual hosts without restarting, you can use Tomcat's JMX interface:


import javax.management.*;
import java.lang.management.*;

MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
ObjectName engineName = new ObjectName("Catalina:type=Engine");

mbs.invoke(engineName, "addChild", 
    new Object[]{new Host()}, 
    new String[]{"org.apache.catalina.Host"});

This programmatic approach allows you to dynamically add hosts while the server is running.

Instead of modifying server.xml, consider using context XML fragments in $CATALINA_BASE/conf/[enginename]/[hostname]/. For example:


<!-- conf/Catalina/localhost/example.xml -->
<Context docBase="/path/to/webapp" 
         reloadable="true" 
         path="/example"/>

Tomcat automatically detects new files in this directory, providing a cleaner hot-deployment solution.

When you do modify server.xml, Tomcat's JMX beans can help verify if changes were applied:


// Check host configuration
ObjectName hostName = new ObjectName("Catalina:type=Host,host=localhost");
String appBase = (String)mbs.getAttribute(hostName, "appBase");

While some hot-reloading is possible, for production environments we recommend:

  • Scheduling planned restarts during low-traffic periods
  • Using load-balanced setups to allow rolling restarts
  • Testing configuration changes thoroughly in staging first

When working with Apache Tomcat 8+, many administrators face the same dilemma: server.xml modifications requiring full restarts disrupt production environments. The Host element configuration is particularly problematic since it controls vital web application routing.

By default, Tomcat only reads server.xml during startup. After modifying the file, the official documentation states:

// Standard behavior requires restart
$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh

For partial configuration reloads without full restarts, use Tomcat's JMX interface:

import javax.management.*;
import java.lang.management.*;

MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
ObjectName serviceName = new ObjectName("Catalina:type=Service");
mbs.invoke(serviceName, "reload", null, null);

When adding new Host elements, consider these alternatives:

  1. External Configuration:
    <Host name="new.domain.com" appBase="webapps/newhost"
          unpackWARs="true" autoDeploy="true">
    </Host>
  2. Context Fragments:
    // conf/Catalina/new.domain.com/ROOT.xml
    <Context path="" docBase="/path/to/webapp">
        <WatchedResource>WEB-INF/web.xml</WatchedResource>
    </Context>

For mission-critical systems:

  • Always test configuration changes in staging
  • Consider using configuration management tools (Ansible/Puppet)
  • Cluster-wide changes require coordination

Verify successful application of Host changes:

tail -f $CATALINA_HOME/logs/catalina.out
grep "HostConfig" $CATALINA_HOME/logs/catalina.out