Migrate the webserver (IP change)

The webserver is the trust anchor of the infrastructure. Changing its IP is the reverse of a probe migration: the webserver regenerates its own certificate, then every component must trust the new certificate and be re-pointed at the new address.

Why the webserver is different

Unlike a monitor or an integrator, the webserver has no migrate and no register command. Its CLI only exposes install, uninstall, run, start, stop, restart and help. Nothing registers “up” to a higher server — the webserver is the central authority that every probe registers to.

However, the webserver’s certificate embeds its IP address in the certificate’s Subject Alternative Name (SAN). When the webserver’s IP changes, the existing webserver.pem no longer matches, so mutual TLS with the components breaks until the certificate is regenerated and redistributed.

This is a coordinated operation. Until every component has the new webserver.pem in its trust store and points at the new IP, that component cannot talk to the webserver. Plan a maintenance window.

Migration steps

1. Regenerate the webserver certificate

On the webserver host, stop the service, delete the old certificate and its private key, then start the service. The webserver detects the missing certificate at startup and regenerates a new self-signed certificate with the new IP in its SAN.


# Windows
webserver.exe stop
del config\ssl\certificates\webserver.pem
del config\ssl\private\webserver.key
webserver.exe start

# Linux
./webserver stop
rm config/ssl/certificates/webserver.pem config/ssl/private/webserver.key
./webserver start

There is no migrate command for the webserver — the certificate regeneration happens automatically at startup when webserver.pem is absent. Make sure the host already has its new IP address before starting.

2. Verify the webserver’s own entry updated to the new IP

The webserver registers itself in the components list, under a single fixed entry named webserver. At every service start it rewrites that entry in place with the host’s current IP and API port — so the restart in step 1 normally heals it automatically. There is no risk of ending up with two webserver entries: the record is keyed by the constant name webserver, not by its IP, so the old address is overwritten, never duplicated.

After the step-1 restart, open the Components page and confirm the webserver entry shows the new IP.

If the entry still shows the old IP, the service was started before the host actually received its new address (the IP is detected once, at startup). Fix the host’s network configuration, then simply restart the webserver — the entry updates itself at the next start.

The webserver / webserverUrl references stored on each component’s record (used by components to reach back to the webserver) are refreshed automatically when the component re-registers in step 4 below — no manual edit needed. The webserver.json configuration file contains ports only, never an IP, so it requires no change either.

3. Distribute the new webserver certificate to every component

Copy the freshly generated config/ssl/certificates/webserver.pem into the certificates store of every component (each monitor and each integrator):

<component_install_dir>/config/ssl/certificates/webserver.pem

Without the new certificate in its store, a component will reject the webserver’s TLS handshake.

4. Re-point and re-register each component

On every monitor and integrator, run its own migrate command against the new webserver endpoint. This updates the component to reach the webserver at its new address and re-pushes the component’s certificate.


# Monitor
monitor.exe migrate <new_webserver_ip>:<webserver_api_port> <webserver_api_token>

# Integrator
integrator.exe migrate <new_webserver_ip>:<webserver_api_port> <webserver_api_token>

Then start each component and reload the webserver certificate store, as described in the monitor and integrator migration pages.

5. Verify communication

Confirm each component reaches the webserver at its new IP and that the webserver shows the components as reachable / online.

Two “webserver” nodes in the Component Topology? That is expected mid-migration. The topology draws one webserver node per distinct webserver endpoint referenced by the component records — each component stores the endpoint it last registered against. Components already migrated point at the new-IP node; components not yet re-registered still point at the old-IP node. Use it as a progress indicator: the edges into the old node show exactly which components remain to migrate. Once the last component has re-registered (step 4), the old node disappears at the next page refresh.

Not related to this procedure: the migrate_wmi_config.go / migrate_snmp_config.go routines inside the webserver are one-time data-schema migrations of stored monitor configurations — they have nothing to do with IP or certificate migration.

Translations

fr: Migrer le serveur web (changement d'IP)

Migrate an integrator probe

Security