Migrating from MTG-Apache2 to the OS Apache Package

This page describes how to replace the MTG-provided mtg-apache2 package with the operating system’s apache2 or httpd package. Apache remains the reverse proxy for the MTG applications. The application packages do not need to be upgraded as part of this procedure.

Use the Recommended Apache Configuration to prepare the replacement configuration, including the TLS 1.3 configuration and the recommended service-per-host layout. That page explains when additional virtual hosts are needed for mutual TLS (mTLS).

1. Inventory and Existing Installation Back Up

Run the migration with root privileges during a maintenance window. For a highly available deployment, migrate and verify one node at a time, removing it from traffic before changing its proxy.

  1. Record the installed mtg-apache2 version and retain the matching installation package for rollback.

  2. Back up /etc/opt/apache2, the certificates, private keys and client CA bundles referenced by the configuration, and any content served from /opt/apache2. Protect the backup because it contains private keys.

  3. Record the mtg-apache2 systemd unit and any overrides, certificate renewal hooks, log rotation configuration, monitoring checks and automation that manage it.

  4. Inventory every public hostname and path, proxy target, authentication policy, redirect, and HTTP exception. Include services configured outside the main virtual host files.

systemctl cat mtg-apache2
systemctl status mtg-apache2

The legacy configuration commonly uses /etc/opt/apache2/httpd.conf, with virtual hosts included from /etc/opt/apache2/vhosts/*.conf, and application or challenge content under /opt/apache2. Use the actual installation as the source of truth.

2. Replacement Configuration Preparation

  1. Follow the Recommended Apache Configuration to select the virtual hosts for the deployed services and adapt all example names, paths, ports and secrets.

  2. Provision DNS and server certificates for any new service names before switching traffic. Update client endpoint settings, application public URLs, Keycloak settings and integration URLs as needed.

  3. Compare each proxy target with the installed application’s listener and context path. In particular, do not replace legacy CARA or EST backend paths with newer example paths without checking them.

  4. Preserve existing client CA trust and client certificate revocation checks. Keep /rev-info reachable over HTTP at the URLs already embedded in issued certificates.

  5. Prepare certificate renewal deployment paths and service reload hooks for the new Apache service.

An HTTP redirect cannot replace the initial TLS client certificate exchange. Configure mTLS clients to use their new service hostname directly, as explained in TLS 1.3 Virtual Host Changes.

3. Legacy Service Stopping & OS Package Installation

With the node removed from traffic, stop and disable the legacy service:

systemctl disable --now mtg-apache2

Install the OS package from the distribution’s repositories:

OS family Command

RHEL

dnf install httpd mod_ssl mod_http2

Ubuntu

apt update followed by apt install apache2

SUSE

zypper install apache2 apache2-event

Package installation may start the new service automatically. Stop it while deploying the prepared configuration: systemctl stop httpd on RHEL, or systemctl stop apache2 on Ubuntu and SUSE.

Keep the legacy package installed until verification is complete if the package manager allows both packages to coexist. If a package conflict requires its removal first, verify the backup and rollback package before proceeding. Inspect the proposed package transaction and resolve any dependencies from MTG applications before accepting removal. Do not force removal or bypass dependency checks.

4. Deployment & Configuration Check

  1. Enable the required modules before installing configuration files that use their directives.

  2. Install the prepared configuration in the OS-specific directories and enable it where required.

  3. Install the certificates and client CA bundles with appropriate permissions and, where applicable, SELinux labels.

  4. Check the HTTP and HTTPS listeners, firewall permissions and the proxy’s permission to reach its backends.

  5. Update monitoring, log rotation, backups, deployment automation and certificate renewal hooks to use the new directories and service name.

Check the syntax, loaded modules and virtual host mapping:

OS family Commands

RHEL

httpd -t, httpd -M, httpd -S

Ubuntu

apache2ctl configtest, apache2ctl -M, apache2ctl -S

SUSE

apachectl configtest, apachectl -M, apachectl -S

Resolve all errors before starting the service. Confirm that each public name selects the intended virtual host and that no duplicate Listen directive or stock HTTPS virtual host overrides the prepared configuration.

5. Starting and Verifying the New Service

On RHEL:

systemctl enable --now httpd
systemctl status httpd
journalctl -u httpd -n 100 --no-pager

On Ubuntu and SUSE:

systemctl enable --now apache2
systemctl status apache2
journalctl -u apache2 -n 100 --no-pager

Complete the configuration verification checks, including:

  • TLS 1.3 and TLS 1.2 connections with server certificate verification enabled.

  • Browser login, application APIs and every deployed enrollment protocol.

  • mTLS with a trusted certificate, no certificate and an untrusted certificate, including the first request on a new connection.

  • HTTP access to the existing CRL and OCSP URLs and any ACME HTTP-01 challenge webroot.

  • Certificate renewal and reload of the new Apache service.

Return the node to traffic only after these checks pass.

6. Legacy Package Removal

After accepting the new service, remove mtg-apache2 using the OS package manager:

OS family Command

RHEL

dnf remove mtg-apache2

Ubuntu

apt remove mtg-apache2

SUSE

zypper remove mtg-apache2

Inspect the removal transaction before accepting it. Retain the protected backup and rollback package for the agreed rollback period. Remove obsolete service reload hooks and log rotation rules once their replacements are verified.

Rollback

Remove the affected node from traffic. Stop and disable the OS Apache service, using systemctl disable --now httpd or systemctl disable --now apache2. If the legacy package was removed, reinstall the recorded version after resolving any package conflicts. Restore its configuration, certificate material, served content and service overrides from the backup. Restore changed public URLs, client settings, DNS routing and renewal hooks as needed.

Start the legacy service with systemctl enable --now mtg-apache2 and verify the original endpoints before returning the node to traffic. The legacy TLS configuration also returns with the rollback; resolve the migration problem before attempting the switch again.