Migrating Roaming Clients between organizations in DNSFilter

Bailey Taylor Community Manager DNSFilter Staff

• September 26, 2024 21:29
• Edited

For customers needing to move Roaming Clients between organizations within DNSFilter, here’s a step-by-step guide. This can help ensure a smooth transition and avoid any disruptions.

🚨 Important: starting with Windows Roaming Client version 3.0.0, configuration preferences are no longer made through the registry. If trying to migrate a 3.x.x agent, remove the appsettings.overrides.json file from the Settings folder before following these steps. 

Steps to migrate Roaming Clients

1. Manual Reinstallation: If you’d prefer a manual approach, you can uninstall and reinstall the Roaming Clients. After reinstallation, restart the "DNSFilter Agent" service for the clients to resume normal functionality without requiring a full system reboot.
2. Use of a Script: Alternatively, DNSFilter provides a script to handle the removal and reinstallation of Roaming Clients. You will just need to configure the $nkey variable with your Site Secret Key:

#Make sure PS is in Admin/elevate mode.

if (!([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) { Start-Process powershell.exe "-NoProfile -ExecutionPolicy Bypass -File `"$PSCommandPath`"" -Verb RunAs; exit }

Write-Host "DNS Filter Removal and Install Tool"

# Temp Directory 
$TempDir = 'C:\Temp\DNS_Filter_Install' 
 
# Checks to See if Temp Directory Exists & if not, create one.
if ((Test-Path $TempDir) -eq $false) {
    New-Item -Path $TempDir -ItemType Directory
}
 
#pass a network key into the install msiexec command
$nkey = Read-Host "Enter Network Key/Secret Site Key"
 
 
# Downloads 
$InstallerDownload = 'https://download.dnsfilter.com/User_Agent/Windows/DNS_Agent_Setup.msi' # Download for DNS Filter 
$InstallerFile = 'DNS_Agent_Setup.msi'
 ß
# Download Agent 
Invoke-WebRequest -Uri $InstallerDownload -OutFile ('{0}\{1}' -f $TempDir, $InstallerFile)
 
# Remove DNS Filter ---
Write-Host "Uninstalling..."
function Uninstall-App {
    Write-Output "Uninstalling $($args[0])"
    foreach($obj in Get-ChildItem "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall") {
        $dname = $obj.GetValue("DisplayName")
        if ($dname -contains $args[0]) {
            $uninstString = $obj.GetValue("UninstallString")
            foreach ($line in $uninstString) {
                $found = $line -match '(\{.+\}).*'
                If ($found) {
                    $appid = $matches[1]
                    Write-Output $appid
                    start-process "msiexec.exe" -arg "/X $appid /qb" -Wait
                }
            }
        }
    }
}
Uninstall-App "DNSFilter Agent"
Uninstall-App "DNS Agent"
 
start-sleep 4
 
Write-Host "Removing Registry Keys..."
 
Remove-Item -Path "HKLM:\Software\DNSFilter" -Recurse
Remove-Item -Path "HKLM:\Software\DNSAgent" -Recurse
Remove-Item "C:\Program Files\DNSFilter Agent\" -Recurse
Remove-Item "C:\Program Files\DNS Agent\" -Recurse

 
# Wait 5 Secconds 
start-sleep 5
 
 
# Install Agent
Write-Host "Installing..."
 msiexec.exe /qn /i $TempDir\$InstallerFile NKEY="$nkey"

#wait 10 seconds then cleanup.
start-sleep 10

#Remove-Item -Recurse -Force $TempDir

Troubleshooting Common Issues

• Missing DNS Resolution: If Roaming Clients aren’t resolving post-migration, restarting the agent service or the devices may be necessary

If you've managed internal Roaming Client migrations in alternative ways, you're welcome to share any insights below!

print

• 

  Colby Lawrence

  • August 08, 2025 20:36

  Could we get a MacOS version of this that works with 2.2.0+ please?

  Thanks!

  -4
• 

  Minetta Gould Community Team DNSFilter Staff

  • August 11, 2025 14:25

  Hi Colby Lawrence ! Happy to help. This script is for the branded agent, so if you're working with a whitelabeled version replace any “DNSFilter Agent” with “DNS Agent.”

  It will:

  1. Stop any existing processes for DNS(Filter) Agent
  2. If the uninstall script is found, it will then execute the uninstall.
  3. It will then install the new agent, with the new site key/settings.
  4. Cleanup after itself.

  #!/bin/bash
  set -x 
  
  # Configuration, this is for DNSFilter Agent. Change DNSFilter Agent to DNS Agent in all locations for Whitelabel. 
  VERSION="2.3.0"
  FILENAME="DNSFilter Agent-$VERSION-Installer.pkg"
  LOCATION="/tmp"
  DOWNLOADURL="fromyourcdn/path/to/file.pkg"
  CONFIG_FILE="/Library/Application Support/DNSFilter Agent/daemon.info"
  INSTALLED_CONFIG="/Library/Application Support/DNSFilter Agent/daemon.conf"
  UNINSTALL_SCRIPT="/Applications/DNSFilter Agent.app/Contents/Resources/uninstall.sh"
  SITE_SECRET_KEY="Your_Site_key_here"
  
  # Stop existing DNSFilter Agent
  echo "Stopping existing DNSFilter Agent..."
  pkill -f "DNSFilter Agent.app" || true
  
  # Check if uninstall script exists
  echo "Checking for uninstall script at: $UNINSTALL_SCRIPT"
  ls -la "/Applications/DNSFilter Agent.app/Contents/Resources/uninstall.sh" 2>/dev/null || echo "Uninstall script not found"
  
  uninstall_agent() {
    echo "Uninstalling DNSFilter Agent..."
    echo y | sudo sh "$UNINSTALL_SCRIPT" || echo "Uninstall failed, continuing with installation"
  }
  
  # Only run uninstall if the script exists
  if [ -f "$UNINSTALL_SCRIPT" ]; then
    uninstall_agent
  else
    echo "Uninstall script not found, skipping uninstall step"
  fi
  
  # Flush DNS cache
  echo "Flushing DNS cache..."
  dscacheutil -flushcache
  killall -HUP mDNSResponder || true
  killall mDNSResponderHelper || true
  
  #Download and Install
  echo "Downloading DNSFilter Agent..."
  curl -kL --silent -o "$LOCATION/$FILENAME" "$DOWNLOADURL"
  cd $LOCATION
  echo "Creating configuration file..."
  cat > dns_agent.conf << EOF
  SITE_SECRET_KEY="$SITE_SECRET_KEY"
  LOCAL_DNS_AND_DOMAINS=""
  OVERRIDE_CONFIG_FILE=yes
  EOF
  
  echo "Installing DNSFilter Agent..."
  sudo installer -dumplog -pkg "$FILENAME" -target /
  
  # Remove temp files
  rm -rf "$FILENAME"
  rm -f "dns_agent.conf"

  0

Please sign in to leave a comment.