In this article

Use this article to move an existing Windows or macOS Roaming Client to a different Site or Organization without reinstalling the agent.

This process updates the local configuration to use a new Site Key and forces the agent to re-register with DNSFilter. After the re-registration completes, the device will appear in the dashboard under the new Site or Organization.

This method is useful when a device was accidentally installed with the wrong Site Key or assigned to the wrong deployment.

Windows Roaming Client

On Windows devices, the Roaming Client can be re-registered by replacing the Site Key in the configuration and removing the existing registration data.

1. Stop the DNSFilter Agent service
2. Open the appsettings.json configuration file

3. Replace the file contents with the configuration below, updating the Site Key value

   {
       "Registration": {
           "SiteKey": "NEW_SITE_KEY"
       }
   }

4. Save the file
5. Start the DNSFilter Agent service

When the service starts, the agent will generate a new registration and associate the device with the Site that corresponds to the new Site Key.

Note: Replacing the entire configuration file helps prevent conflicts with settings from the previous installation.

macOS Roaming Client

On macOS, reassigning the Site Key requires updating the configuration file, removing the previous registration record, and restarting the agent service.

File locations

File paths vary depending on whether the Standard or Whitelabel version of the agent is installed.

Migration workflow

Complete the following steps in order:

1. Update the secret_key value in daemon.conf with the new Site Key
2. Delete the daemon.reg file. This file stores the existing registration state
3. Restart the DNSFilter Agent service so the device registers again with the new key

If the registration file is not removed, the agent will continue communicating with the previously assigned identity.

Example script (Standard version)

The script below updates the Site Key, removes the previous registration file, and restarts the agent service. 

Key notes for scripted updates:

• Administrative privileges are required to modify files in /Library/Application Support
• The secret_key value must remain enclosed in double quotes in the configuration file
• When migrating to a Whitelabel deployment, update the file paths and service identifiers accordingly

#!/bin/bash

NEW_KEY="YourNewSecretKey"
CONFIG_PATH="/Library/Application Support/DNSFilter Agent/daemon.conf"
REG_FILE="/Library/Application Support/DNSFilter Agent/daemon.reg"
PLIST_PATH="/Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist"

if [ "$EUID" -ne 0 ]; then
  echo "Please run as root (sudo)"
  exit 1
fi

if [ -f "$CONFIG_PATH" ]; then
    sed -i '' "s/^[[:space:]]*secret_key[[:space:]]*=.*/secret_key = \"$NEW_KEY\"/" "$CONFIG_PATH"
else
    echo "daemon.conf not found"
    exit 1
fi

if [ -f "$REG_FILE" ]; then
    rm "$REG_FILE"
fi

launchctl bootout system "$PLIST_PATH" 2>/dev/null
sleep 2
launchctl bootstrap system "$PLIST_PATH"

echo "Migration complete."

After the agent restarts, a new registration file will be created and the device will appear in the DNSFilter dashboard under the new Site.