In this article

This article explains the recommended process for updating a DNS Relay when the virtual machine (VM) it runs on requires an OS upgrade (for example, moving from Ubuntu 18.04 to Ubuntu 22.04), or when a new Relay is deployed from a VM template.

Relay software itself updates automatically when deployed from the DNSFilter dashboard. However, upgrading the underlying VM image or provisioning a new VM from a template requires attention to machine identity to avoid duplicate Relay entries in the dashboard.

Why VM templates cause duplicate Relays

The DNS Relay uses the host machine's hardware identity to register with DNSFilter. When a VM is provisioned from a VMware template—or any virtualization platform that preserves the source VM's hardware UUID—the new VM inherits the same machine identity as the original. This causes the newly deployed Relay to register under the same Agent ID as the existing one, overwriting it in the DNSFilter dashboard.

This issue is not limited to re-imaging. It occurs any time a VM is cloned or provisioned from a template without first generating a unique machine identity.

Diagnose a duplicate Agent ID

To confirm whether two Relays share the same machine identity, run the following on both VMs:

cat /etc/machine-id

Matching output confirms both machines share the same hardware identity. To verify via Relay Manager, run relay-manager troubleshoot and check the host_id field in the System Information section of the output. Matching host_id values across two VMs confirm the issue.

Resolve a duplicate machine ID (Linux)

To generate a unique machine identity without redeploying the VM from scratch:

1. Run sudo rm /etc/machine-id to remove the existing machine ID file
2. Run sudo systemd-machine-id-setup to regenerate the machine ID
3. Run sudo reboot to apply the changes

Once the VM has rebooted, reinstall the Relay following the latest deployment instructions in the DNSFilter dashboard. The Relay will register as a new entry with a unique Agent ID.

✍️ This resolution applies to Linux deployments. For Windows-based Relay deployments provisioned from a VMware template, deploy the VM from an ISO rather than a template to avoid duplicate machine identity.

Upgrade process for OS-level VM changes

The steps below use Ubuntu as the example, but the same process applies to other operating systems. To complete the update, redeploy the DNS Relay using the latest configuration and install instructions in the Relay section of the DNSFilter dashboard.

1. Review and record the IP configuration of each existing relay
2. Generate replacement images
   1. Create new relay images with distinct hostnames for clarity
   2. Assign new IPv4 addresses to avoid conflicts with existing relays
3. Deploy and test the new relays
   1. Set static IP addresses on new relays
   2. Confirm network connectivity using the DNS Relay Deployment Guide
4. Configure networks to route traffic through the new relays
5. Ensure all devices and networks are functioning correctly with the updated relays
   1. Running new and old relays concurrently allows testing before full migration
6. Decommission old relays
   1. Remove old relays from the network 
   2. Devices with static DNS entries must be updated before decommissioning old relays

Alternative Approach: Existing relay IPs can be reused, but migration must occur one relay at a time to prevent network conflicts. The method above provides greater flexibility and minimizes potential downtime.