Author: Infrastructure & Cloud Operations
Target Audience: Tier-2 (L2) Systems Engineers, Cloud Engineers, Citrix Administrators
Environment: Azure IaaS (Windows Server 2016 to Windows Server 2022)
Scope: Citrix User Profile Management (UPM) / FSLogix Profile Containers & Enterprise Home Directories
1. Executive Summary & Architecture
Migrating high-transaction file servers in Azure hosting stateful VDI assets—specifically Citrix UPM / FSLogix Profile Containers (.vhdx) and User Home Directories—carries significant operational risk. A minor oversight in Access Control Lists (ACLs), share caching, or Kerberos SPNs will lead to user logon failures (e.g., temporary profiles or access-denied loops).
This standard operating procedure (SOP) provides an end-to-end blueprint for migrating data volumes between two Azure IaaS Virtual Machines with zero profile corruption, 100% preservation of NTFS Access Control Lists (DACLs/SACLs), and an airtight rollback safety net.
AZURE INFRASTRUCTURE LAYOUT
┌────────────────────────────────────────────────────────┐
│ Target VNet (e.g., 10.240.0.0/16) - Subnet │
└───────────┬────────────────────────────────┬───────────┘
│ │
▼ ▼
┌───────────────────────────────────┐ ┌───────────────────────────────────┐
│ Source VM (Windows Server 2016) │ │ Target VM (Windows Server 2022) │
│ Hostname: FS-OLD (10.240.1.10) │ │ Hostname: FS-NEW (10.240.1.20) │
│ • F:\ (Citrix Profiles) │ │ • F:\ (Citrix Profiles) │
│ • G:\ (User Home Drives) │ │ • G:\ (User Home Drives) │
└─────────────────┬─────────────────┘ └─────────────────┬─────────────────┘
│ ▲
│ Phase 1: Initial Baseline Sync │
│ Phase 2: Off-Peak Delta Sync │
└────── Multi-Threaded Robocopy ─────────┘
(/COPYALL /B /MIR /MT:32)
│
▼
Phase 3: Change Window Cutover
• Freeze Citrix Sessions
• Final Robocopy Sync (/R:0 /W:0)
• DNS / CNAME & Kerberos SPN Swap
2. Pre-Migration Prerequisites & Azure Sizing
Before running any file-transfer commands, verify and complete every check in this section.
A. Target VM Provisioning
- Operating System: Windows Server 2022 Datacenter (Azure Edition recommended).
- Managed Disks Configuration:
- Provision Azure Managed Disks (Premium SSD v2 or Ultra Disk) with capacity matching or exceeding the source.
- Allocation Unit Size (Cluster Size): Must be formatted with 64 KB block size. Standard 4 KB clusters degrade performance when handling large, expanding VHDX containers.
# Format volumes on Target VM using PowerShell: Format-Volume -DriveLetter F -FileSystem NTFS -AllocationUnitSize 65536 -NewFileSystemLabel "Profiles" -Confirm:$false Format-Volume -DriveLetter G -FileSystem NTFS -AllocationUnitSize 65536 -NewFileSystemLabel "HomeDrives" -Confirm:$false - Host Caching Policy: In the Azure Portal, set Data Disk Host Caching to None or Read-Only for write-heavy VHDX profile volumes. Never use Read/Write host caching on multi-terabyte database or VHDX volumes due to write-acknowledgment bottlenecks.
B. Network & Security Port Requirements
Both VMs must communicate over SMB without Network Security Group (NSG) interference:
- TCP 445 (SMB): Inbound/Outbound allowed between
FS-OLDandFS-NEW. - TCP 135 (RPC Endpoint Mapper): Allowed between both hosts.
- TCP 49152–65535 (RPC Dynamic Ports): Allowed between both hosts.
C. Antivirus & EDR Exclusions (Pre-Requisite on Server 2022)
Antivirus agents running active file scans will lock VHDX files during replication, causing Robocopy to abort. Configure Microsoft Defender or third-party EDR exclusions on FS-NEW prior to data migration:
PowerShell
# Add Windows Defender Exclusions on FS-NEW:
Add-MpPreference -ExclusionExtension ".vhd", ".vhdx", ".lock"
Add-MpPreference -ExclusionPath "F:\CitrixProfiles", "G:\HomeDrives"
Add-MpPreference -ExclusionProcess "frxsvc.exe", "frxccds.exe", "frxdrv.sys", "CtxUpmSvc.exe"
3. Share Provisioning & Permission Architecture
Never copy shares by exporting and importing LanmanServer\Shares registry keys from 2016 to 2022. This practice imports default system administrative shares (ADMIN$, C$, IPC$) with legacy attributes that trigger SMB negotiation errors on Server 2022.
Execute the following PowerShell script directly on FS-NEW (Windows Server 2022) to establish clean, standard-compliant shares:
PowerShell
# 1. Create Directories if they do not exist
New-Item -ItemType Directory -Path "F:\CitrixProfiles" -Force
New-Item -ItemType Directory -Path "G:\HomeDrives" -Force
# 2. Configure SMB Shares
# CachingMode 'None' is critical: prevents client-side offline file caching from corrupting VHDX containers.
New-SmbShare -Name "CitrixProfiles" -Path "F:\CitrixProfiles" -FullAccess "Everyone" -CachingMode None -FolderEnumerationMode AccessBased
New-SmbShare -Name "HomeDrives" -Path "G:\HomeDrives" -FullAccess "Authenticated Users" -CachingMode None -FolderEnumerationMode AccessBased
NTFS Permission Baseline (Profiles Root Directory)
Verify the root of F:\CitrixProfiles contains the mandatory permission structure required by FSLogix and Citrix UPM:
| Principal | Access Level | Applies To |
SYSTEM | Full Control | This folder, subfolders, and files |
Administrators | Full Control | This folder, subfolders, and files |
CREATOR OWNER | Full Control | Subfolders and files only |
Domain Users (or VDI Security Group) | Read & Execute, Create Folders / Append Data | This folder only |
4. Phase 1: Baseline Seed Replication (T-Minus 3 Days)
Run the initial data copy during regular business hours. Because Robocopy is reading live data using volume administrative shares, active users will not experience performance degradation.
- Execution Host: Run this command from the Target Server (
FS-NEW) via an elevated PowerShell session as a Domain Administrator.
PowerShell
# Create logging directory
New-Item -ItemType Directory -Path "C:\MigrationLogs" -Force
# 1. Initial Sync: Profiles Drive (Using Admin UNC Share)
robocopy "\\FS-OLD\F$\CitrixProfiles" "F:\CitrixProfiles" /MIR /B /COPYALL /DCOPY:DAT /MT:32 /R:1 /W:1 /LOG:C:\MigrationLogs\Profiles_Initial.log /TEE /NP
# 2. Initial Sync: Home Drives (Using Admin UNC Share)
robocopy "\\FS-OLD\G$\HomeDrives" "G:\HomeDrives" /MIR /B /COPYALL /DCOPY:DAT /MT:32 /R:1 /W:1 /LOG:C:\MigrationLogs\HomeDrives_Initial.log /TEE /NP
Understanding Critical Robocopy Flags:
/MIR: Mirrors the tree structure (copies subdirectories, including empty ones, and purges files on the target that no longer exist on the source)./B: Executes file I/O in Backup Mode. This overrides NTFS permissions using theSeBackupPrivilegeandSeRestorePrivilegeuser rights, preventing “Access Denied” errors when copying user profiles owned by other accounts./COPYALL: Copies all file information (/COPY:DATSOU): Data, Attributes, Timestamps, Security (NTFS DACLs), Owner information, and Auditing info (SACLs)./DCOPY:DAT: Preserves Directory timestamps and attributes./MT:32: Multi-threaded processing using 32 concurrent threads to fully saturate Azure Premium SSD IOPS./R:1 /W:1: Reduces retry count to 1 and wait time to 1 second. This prevents Robocopy from hanging for 30 seconds on active, locked profile containers during the production day.
5. Phase 2: Delta Differential Sync (T-Minus 1 Day)
24 hours before the scheduled maintenance window, run a delta pass. This run copies only newly created or modified files, drastically shortening the final cutover maintenance window to under 15 minutes.
PowerShell
# Run from FS-NEW:
robocopy "\\FS-OLD\F$\CitrixProfiles" "F:\CitrixProfiles" /MIR /B /COPYALL /DCOPY:DAT /MT:32 /R:1 /W:1 /LOG:C:\MigrationLogs\Profiles_Delta.log /TEE /NP
robocopy "\\FS-OLD\G$\HomeDrives" "G:\HomeDrives" /MIR /B /COPYALL /DCOPY:DAT /MT:32 /R:1 /W:1 /LOG:C:\MigrationLogs\HomeDrives_Delta.log /TEE /NP
Quality Gate: Open the log files (C:\MigrationLogs\*_Delta.log) and check the summary table at the bottom. Ensure that Failed files are either 0 or limited strictly to users who were actively logged in during execution.
6. Phase 3: The Maintenance Cutover Runbook (Execution Window)
Schedule a 2-hour maintenance window. Follow these steps in strict sequential order:
MAINTENANCE CUTOVER TIMELINE
[T-00:00] Set Citrix Delivery Groups to Maintenance Mode
│
[T-00:10] Force-logoff remaining active sessions via Citrix Director
│
[T-00:15] Stop LanmanServer on Source (FS-OLD) to drop file locks
│
[T-00:20] Execute Final Delta Robocopy Sync (/R:0 /W:0)
│
[T-00:35] Configure Kerberos SPN & Strict Name Checking on FS-NEW
│
[T-00:45] Update DNS CNAME Record (files.domain.com -> FS-NEW)
│
[T-00:55] Execute Pilot User Validation Test
│
[T-01:10] Disable Maintenance Mode & Release to Production
Step 1: Lock Delivery Groups & Clear Active Sessions
- Open Citrix Studio or Web Studio.
- Navigate to Delivery Groups $\rightarrow$ Select all production delivery groups $\rightarrow$ Right-click and select Turn On Maintenance Mode.
- In Citrix Director, send a 5-minute logoff warning broadcast, then disconnect and log off all active user sessions to release open
.vhdxfile handles.
Step 2: Sever Source SMB Connections
On FS-OLD (Windows Server 2016), stop the Server service to ensure no VDA or client can write any additional bytes to the source disks:
PowerShell
# Run on FS-OLD:
Stop-Service -Name LanmanServer -Force
Set-Service -Name LanmanServer -StartupType Disabled
Verify that all SMB file handles are dropped:
PowerShell
# Run on FS-OLD (Should return 0):
(Get-SmbOpenFile) | Measure-Object | Select-Object -ExpandProperty Count
Step 3: Run the Final Zero-Lock Robocopy Sync
With the source completely offline to clients, run the final sync from FS-NEW:
PowerShell
# Final Cutover Sync (Note: /R:0 /W:0 ensures immediate abort if an anomaly occurs)
robocopy "\\FS-OLD\F$\CitrixProfiles" "F:\CitrixProfiles" /MIR /B /COPYALL /DCOPY:DAT /MT:32 /R:0 /W:0 /LOG:C:\MigrationLogs\Profiles_FinalCutover.log /TEE /NP
robocopy "\\FS-OLD\G$\HomeDrives" "G:\HomeDrives" /MIR /B /COPYALL /DCOPY:DAT /MT:32 /R:0 /W:0 /LOG:C:\MigrationLogs\HomeDrives_FinalCutover.log /TEE /NP
Quality Gate: Verify in both log files that:
Failed: 0Mismatch: 0
7. Phase 4: Identity & Kerberos CNAME Transition
When using a consolidated DNS alias for your file share (e.g., \\files.company.com\CitrixProfiles), updating DNS alone will cause Kerberos authentication to fail. Windows Server 2022 will enforce strict SPN validation and SMB loopback checks, resulting in errors such as The target principal name is incorrect.
Perform the following configurations on the Domain Controller and the Target File Server:
Step 1: Update Service Principal Names (SPN)
Open an elevated command prompt on your Domain Controller:
DOS
:: 1. Remove existing SPNs from FS-OLD
setspn -D host/files.company.com FS-OLD
setspn -D host/files FS-OLD
:: 2. Register SPNs to the new Windows Server 2022 computer account (FS-NEW)
setspn -S host/files.company.com FS-NEW
setspn -S host/files FS-NEW
:: 3. Verify SPN registration
setspn -L FS-NEW
Step 2: Configure Name Checking & Loopback on Target VM (FS-NEW)
Run this PowerShell block on FS-NEW (Windows Server 2022):
PowerShell
# Disable Strict Name Checking (allows access via CNAME alias)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters" -Name "DisableStrictNameChecking" -Value 1 -PropertyType DWORD -Force
# Disable Loopback Check (allows local administration via CNAME)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\Lsa" -Name "DisableLoopbackCheck" -Value 1 -PropertyType DWORD -Force
# Configure Optional Names for SMB Alias
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters" -Name "OptionalNames" -Value @("files", "files.company.com") -PropertyType MultiString -Force
# Restart the Server service to commit changes immediately
Restart-Service -Name LanmanServer -Force
Step 3: Update DNS
- Open the DNS Management Console (
dnsmgmt.msc). - Navigate to your Forward Lookup Zone (e.g.,
company.com). - Locate the CNAME record
files$\rightarrow$ Change target FQDN fromFS-OLD.company.comtoFS-NEW.company.com. - Lower the TTL to 60 seconds temporarily to accelerate client convergence.
8. Post-Migration Verification & Smoke Testing
Do not release the environment to production without completing this validation checklist:
SMOKE TEST VERIFICATION MATRIX
CHECK ITEM TEST METHOD PASS CRITERIA
────────────────────────────────────────────────────────────────────────────────────────
DNS Resolution Resolve CNAME from VDA Points to FS-NEW IP
SMB Connection Test-NetConnection -Port 445 TcpTestSucceeded: True
Kerberos Validation klist inside VDA Session host/files.company.com (Kerberos)
FSLogix VHDX Mount frx list (inside test session) Status: 0 (Attached & Read/Write)
Home Drive Access Browse mapped drive (H:\ or U:\) Write, edit, delete successful
Event Log Cleanliness Check Microsoft-FSLogix/Apps Event ID 56 (Success, no warnings)
Step-by-Step Test Procedure:
- Take a single testing Delivery Group or test VDA out of Maintenance Mode.
- Log on with a non-admin test account.
- Open an administrative command prompt on the VDA and run:DOS
frx listVerify that the Profile VHDX is mounted directly from\\files.company.com\CitrixProfiles\and is set toRead/Write. - Open the user’s mapped Home Drive ($H:$ or $U:$). Create a new
.txtdocument, write test data, save it, and delete it. - Log off the test account. Confirm on
FS-NEWthat the open handle closes and the lock file (.vhdx.lock) disappears.
9. Rollback Plan (Guaranteed Safe State)
Because all migration passes used read-only flags from the source (FS-OLD), the original Windows Server 2016 file server remains completely unaltered. If an irrecoverable issue arises during the maintenance window:
- Re-enable Maintenance Mode across all Citrix Delivery Groups.
- Revert the DNS CNAME record
files.company.comto point back toFS-OLD.company.com. - On the Domain Controller, reassign the SPNs:DOS
setspn -D host/files.company.com FS-NEW setspn -S host/files.company.com FS-OLD - Re-enable and start the SMB service on
FS-OLD:PowerShellSet-Service -Name LanmanServer -StartupType Automatic Start-Service -Name LanmanServer - Remove Delivery Groups from Maintenance Mode. All users will reconnect to their original profiles on Server 2016 with zero data loss.