Description

Move HPA from a source server to a target server and keep all the data (users, settings, DPS, dashboards, alerts, metrics history):

Copy the HPA directory, then run the installation of the same version again. No fresh installation, no export/import.
The HPA DNS changes from the DNS of the source server (<old DNS>) to the DNS of the target server (<new DNS>). This changes the HPA configuration, the certificates, Keycloak and the agents.
The directory path, the HPA user and the Linux distribution can be different. Both servers must be Linux x86_64.
Applies to HPA 2025.11.x and later.

Prerequisites on the target server: the requirements of a first installation, a user to run HPA (not root), the firewall rules, and an HTTPS certificate for <new DNS> (or a self-signed one is generated).

Warning If users and agents reach HPA through a DNS alias (for example hpa.mycompany.com) that stays the same, skip steps 5, 9 and 10, apply step 4 only for <old IP> and paths, and point the alias to the target server after step 8.

Steps

{{hpa_base_dir}} is the full path of the directory containing hpa on each server: for /opt/hexagon/hpa, it is /opt/hexagon. It can be different on the two servers. Details are in the appendix.

1. Source server: stop HPA and note the version

cd {{hpa_base_dir}}/hpa
./hpa_controller.sh stop
./hpa_controller.sh status
cat current_version.config

2. Source server: archive the directory, then copy the archive to {{hpa_base_dir}} on the target server

cd {{hpa_base_dir}}
tar -czf hpa_migration.tar.gz hpa

3. Target server: extract, as the user that runs HPA

cd {{hpa_base_dir}}
tar -xpzf hpa_migration.tar.gz

4. Configuration: set the new DNS

In {{hpa_base_dir}}/hpa/environment.config:

export HPA_EXTERNAL_DNS=<new DNS>

If HPA_EM_DNS, HPA_KEYCLOAK_DNS or HPA_SERVER_DNS are set with <old DNS>, set <new DNS>.

If HPA_EM_LISTENIP or HPA_EM_WEB_HOST are set with <old IP>, put back their default value from environment.config.template (or set the IP of the target server).

Then search for any <old DNS>, <old IP> or path of the source server left, and replace it:

cd {{hpa_base_dir}}/hpa
grep -rn "<old DNS>\|<old IP>\|<source hpa_base_dir>/hpa" environment.config security.config override_config

5. Certificates: move the old ones aside

cd {{hpa_base_dir}}/hpa/var/certificates
mkdir old
mv hpa_keystore.p12 nginx_fullchain.pem nginx_privkey.pem nginx_privkey.pass old/

Then copy the HTTPS certificate of <new DNS> in {{hpa_base_dir}}/hpa/var/certificates:

nginx_fullchain.pem: the certificate with its chain
nginx_privkey.pem: the private key
nginx_privkey.pass: the password of the private key, if it has one

The installation generates a new keystore with <new DNS>, and a self-signed HTTPS certificate if none is there.

6. Install the same version

cd {{hpa_base_dir}}/hpa
./hpa_controller.sh i <version from step 1>

7. Systemd service, if used

In {{hpa_base_dir}}/hpa/versions/hexagon-hpa.service, set these lines:

User=<hpa user>
Group=<hpa group>
ExecStart={{hpa_base_dir}}/hpa/controller.sh start
ExecStop={{hpa_base_dir}}/hpa/controller.sh stop
WorkingDirectory={{hpa_base_dir}}/hpa/

Then:

sudo cp {{hpa_base_dir}}/hpa/versions/hexagon-hpa.service /etc/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable hexagon-hpa.service

8. Start HPA

cd {{hpa_base_dir}}/hpa
./hpa_controller.sh start
./hpa_controller.sh status

9. Keycloak: set the new DNS

In https://<new DNS>:<port>/keycloak, Realm Hexagon-Hpa > Clients, replace <old DNS> and click Save:

Client	Field	Value
`hpa-client`	Valid redirect URIs	`https://<new DNS>:<port>/login`
`hpa-client`	Valid post logout redirect URIs	`https://<new DNS>:<port>`
`com.ca.apm.webview.serviceprovider`	Master SAML Processing URL	`https://<new DNS>:<port>/introscope/saml.jsp`

If users log in through an external identity provider (OpenID, SAML, ADFS), it must declare <new DNS> too.

10. Agents: set the new DNS

On every monitored server, in {{hpa_agent_dir}}/hpa_agent_config.sh:

export HPA_EM_HOST=ssl://<new DNS>:5443

Then, as the user that starts Calypso, with x.xx the installed agent version:

bash {{hpa_agent_dir}}/deploy.sh x.xx

Restart the infrastructure agent and the Calypso components. Windows navigators: set EM_HOST in their launch script.

11. Check

Appendix

1. Stop HPA

The databases must be stopped, otherwise the copy is corrupted.
Use hpa_controller.sh even with systemd: the generated service file may not stop HPA.

2. Archive

Optional, to reduce the size, exclude older versions and debug sessions (ls hpa/versions):

tar -czf hpa_migration.tar.gz \
    --exclude='hpa/versions/2025.04.04*' \
    --exclude='hpa/versions/2025.11.02*' \
    --exclude='hpa/var/hpadumpsessions/*' \
    hpa

Warning Keep the folder and the .tar.gz of the current version: the installation stops without it.

3. Extract

The HPA user must own the files, otherwise PostgreSQL does not start. If needed: sudo chown -R <hpa user>:<hpa group> {{hpa_base_dir}}/hpa
Any supported distribution works: the databases are created without locale.

4. Configuration

HPA_EM_LISTENIP: IP the EM listens on. 0.0.0.0 (all) is the default. With <old IP>, the EM does not start.
HPA_EM_WEB_HOST: IP the HPA services use to call the EM. 127.0.0.1 is the default. If HPA_EM_LISTENIP is a specific IP, use the same one.
Generated files are rebuilt by the installation. Only your own files need the grep.

5. Certificates

Warning If you installed your own certificates in hpa_keystore.p12, have them reissued with <new DNS> and import them in a new keystore before step 6. Otherwise they are replaced by self-signed ones.

Certificates using <old DNS>:

hpa_keystore.p12: the self-signed certificates of the HPA services (portal, Keycloak, Introscope EM, WebView and agent channel, MCP, external API), generated by the installation
nginx_fullchain.pem, nginx_privkey.pem: the HTTPS certificate of Nginx, used by the browsers, and nginx_privkey.pass: the password of its private key (empty if the key has no password)

To list the certificates of the old keystore (HPA ones have the issuer CN=hpa, OU=demo, DC=hexagon-perf, DC=com):

cd {{hpa_base_dir}}/hpa
modules/java/current/bin/keytool -J-Duser.language=en -list -v -storetype PKCS12 -storepass changeit \
    -keystore var/certificates/old/hpa_keystore.p12 | grep -E "^Alias|^Issuer|DNSName|IPAddress"

If the HTTPS certificate already covers <new DNS> (wildcard), keep the nginx_* files in place.

6. Install

If Nginx listens on a port lower than 1024, run the setcap command displayed by the installation.

7. Systemd

The generated file has a fixed user, group and an empty path: fix it before use. With SELinux, see start/stop.

9. Keycloak

Leave out :<port> for port 443. Add /<context path> if HPA_URL_CONTEXTPATH is set.
Screens: see Upgrade to 2025.11.01.

10. Agents

Keep the port already in HPA_EM_HOST (5443 with SSL, 5001 without).
Agents configured with <old IP> must be updated too, even with a DNS alias.

11. Check

./hpa_controller.sh status: all modules running
Login to HPA and WebView, dashboards and metrics history present, agents sending metrics

Then, on the source server: remove the controller.sh logrotate line (crontab -e) and run sudo systemctl disable hexagon-hpa.service.

Rollback

Stop HPA on the target server, restore <old DNS> in the agents, start HPA on the source server.

HPA installation and deployment HPA portal Move HPA to another server