Key Considerations Before Migrating File Shares to Azure
Every file share migration that fails does so in the planning phase — not the execution phase. Source inventory, compatibility scanning, bandwidth reality, identity readiness, ACL strategy, tool selection, wave sequencing, and a transparent cutover. Work through all eight before you move a single byte.
2026
Why File Share Migrations Fail Before They Start
Migrating file shares to Azure is one of the most common infrastructure projects in cloud adoption. It is also one of the most frequently underestimated. Teams that treat it as a copy-and-paste job — move the data, update the UNC paths, done — discover during cutover weekend that users cannot authenticate, ACLs did not transfer, port 445 is blocked by the corporate firewall, and the bandwidth calculation that seemed fine on paper takes four times as long in practice. Every one of those problems was discoverable before the migration started. None of them had to surface at 23:00 on a Saturday.
The purpose of pre-migration planning is not to produce documentation for its own sake. It is to surface every problem that will cost you time and credibility during execution — before execution begins. This guide covers the eight considerations that must be resolved before a file share migration begins. Each consideration maps to a concrete deliverable: a measurement, a decision, a configuration, or a verified output. Work through all eight. Do not skip any of them because the migration looks simple. The ones that look simple are frequently the ones that hide the worst surprises.
Source Inventory — Know What You Are Moving Before You Plan How to Move It
You cannot design a migration for data you have not inventoried. The source inventory is the document that drives every subsequent decision: bandwidth calculation, wave sequencing, tool selection, cost modelling, and cutover timing. Without it, every other planning decision is based on estimates that may be wrong by an order of magnitude.
Since April 2026, Azure Migrate supports automated, agentless discovery and assessment of SMB and NFS file shares hosted on Windows and Linux servers — a significant improvement over the previous approach of manual PowerShell scripts and spreadsheets. The appliance automatically discovers file shares, collects metadata including storage consumed, file counts, and access patterns, and classifies each share as Ready, Ready with Conditions, or Not Ready for Azure Files. This should be your first step.
Deploy the Azure Migrate appliance into your on-premises environment
Create an Azure Migrate project in the Azure portal and deploy the Azure Migrate appliance on-premises. For VMware environments, import the OVA template directly into vSphere. For Hyper-V, use the VHD template. For physical servers or NAS devices, use the PowerShell installer script. The appliance connects to your servers agentlessly and automatically discovers all SMB and NFS file shares on both Windows and Linux servers alongside their host metadata — storage consumed, file counts, and access patterns. Discovery typically completes within a few hours depending on environment size.
Create a file share assessment and review per-share readiness
Select the discovered file shares you want to include in scope and configure the assessment settings: target region, pricing tier preference (Standard or Premium), and redundancy option. Azure Migrate evaluates IOPS, throughput, size, capacity, and regional availability for each share and returns a readiness classification: Ready, Ready with Conditions, or Not Ready. It also recommends the appropriate Azure Files tier and estimates monthly costs. Shares classified as Not Ready are recommended for an Azure VM-based file server path instead. Use the TCO comparison to build the business case.
Supplement with PowerShell for NAS devices and environments >100TiB
For environments over 100TiB — or NAS devices not fully supported by Azure Migrate's appliance discovery — run the PowerShell inventory script below from a domain-joined Windows machine with read access to each share. This captures file counts, sizes, last-write dates, and access pattern data needed for tier selection and bandwidth calculation.
$results = @()
foreach ($share in $shares) {
# Count files and get total size
$items = Get-ChildItem -Path $share -Recurse -File -ErrorAction SilentlyContinue
$sizeGB = ($items | Measure-Object -Property Length -Sum).Sum / 1GB
$fileCount = $items.Count
# Find most recent write — useful for access pattern classification
$lastWrite = ($items | Sort-Object LastWriteTime -Descending | Select-Object -First 1).LastWriteTime
# Count unique ACL entries at root — indicates SID complexity
$aclCount = (Get-Acl $share).Access.Count
$results += [PSCustomObject]@{
Share = $share; SizeGB = [math]::Round($sizeGB,2)
FileCount = $fileCount; LastWriteTime = $lastWrite; RootACLCount = $aclCount
}
}
$results | Format-Table -AutoSize
$results | Export-Csv "share-inventory.csv" -NoTypeInformation
# Output: share-inventory.csv — the input document for all subsequent planning decisions
Compatibility Scanning — What Azure Files Will and Will Not Accept
Azure Files enforces naming and metadata rules that are stricter than most on-premises NAS filesystems. Files that exist without issue on a QNAP or Windows file server will be silently skipped during migration — no error, no warning, no entry in the migration log — if they contain illegal characters, exceed the maximum path length, or use Windows-reserved names. Finding and fixing these on day two of planning costs nothing. Finding them during a production cutover at midnight costs credibility, time, and potentially data integrity.
Bandwidth Measurement — Use Measured Throughput, Not Line Capacity
Every migration timeline that has slipped did so because someone used the WAN line capacity specification rather than the measured business-hours available throughput. A 500 Mbps connection with 60% available bandwidth during business hours and a 1.2× Azure Files overhead multiplier transfers approximately 414 GB per day — not 5,400 GB per day. Measure the actual throughput, apply all the multipliers, and make the timeline decision before you commit to a go-live date.
Network Readiness — Port 445, Private Endpoints, and DNS Resolution
The most common reason a file share migration fails during cutover is a network problem that was entirely avoidable. Port 445 — the port SMB uses — is blocked by many corporate and ISP firewalls. Users who need to access Azure Files directly from an office network may discover on cutover day that their firewall policy blocks outbound port 445. Azure Files supports SMB over HTTPS on port 443 as a workaround, but this requires configuration and testing in advance. DNS resolution must return the Private Endpoint IP from every network segment that needs access. Each of these must be verified before the migration starts.
Identity Readiness — Authentication Must Be Configured Before Data Moves
Identity-based authentication must be configured and tested on the target Azure Files storage account before the migration data transfer begins. If you configure authentication after the migration, users cannot access the newly migrated shares until authentication is validated — which converts a smooth cutover into a help desk incident. The question is not whether to configure identity-based authentication. The question is which method is appropriate for your environment, and whether your identity infrastructure is ready for it.
For most organisations migrating from on-premises Windows file servers, on-premises AD DS authentication is the correct path — it allows domain-joined machines to access Azure file shares using their existing Kerberos credentials with no client changes. This requires the storage account to be joined to your AD domain using the AzFilesHybrid PowerShell module, and requires your on-premises AD to be synchronised to Entra ID via Entra Connect. For cloud-native deployments without an on-premises domain controller, Entra ID Kerberos is the recommended approach.
Confirm identity sync readiness before any configuration work
For AD DS authentication: verify that all users and groups who need access to Azure Files are synchronised to Entra ID via Entra Connect. Only hybrid identities (users that exist in both on-premises AD and Entra ID) can use AD DS-based authentication to Azure Files. Cloud-only accounts cannot. If users who need file share access are not yet synced, address the sync gap before proceeding. Run Get-MgUser -Filter "onPremisesSyncEnabled eq true" to enumerate synced accounts and verify coverage.
Domain-join the storage account to on-premises AD DS
Download and import the AzFilesHybrid PowerShell module. Run Join-AzStorageAccountForAuth to create a computer object (or service logon account) in your AD representing the storage account. This enables Kerberos authentication — users accessing Azure Files over SMB receive a Kerberos ticket from the domain controller, identical to how they authenticate to any domain-joined file server. Set ACLs on the root directory of each file share before copying large amounts of data — root ACL changes take significantly longer to propagate after a large dataset has been written.
Assign share-level RBAC and configure NTFS ACLs on the root directory
Assign share-level RBAC roles to users and groups before any data is copied. The role assignment controls the maximum permissions a user can have regardless of NTFS ACL — a user with Storage File Data SMB Share Reader at the share level cannot write files even if the NTFS ACL grants write access. To migrate existing SMB server root permissions to RBAC, use the Move-OnPremSharePermissionsToAzureFileShare PowerShell cmdlet from the AzFilesHybrid module. Test access with at least one real user account from each user type before proceeding to data transfer.
ACL Strategy — Permissions Are Data and Must Be Treated as Such
NTFS ACLs are not metadata that travels alongside files automatically. They are data that must be explicitly copied using a tool that supports file fidelity — specifically a tool that copies file attributes, timestamps, and ACLs via SMB. RoboCopy with the /COPY:DATSO flag is the standard for SMB ACL preservation. Azure Storage Mover and Azure File Sync also preserve ACLs. AzCopy does not preserve NTFS ACLs by default on file share transfers — understand your tool's ACL handling before you rely on it in production.
Tool Selection — Match the Tool to Your Requirement, Document the Rationale
The correct migration tool depends on whether you need ongoing hybrid sync after migration, your network bandwidth relative to data volume, your source type, and whether you want a managed service or a command-line approach. Azure Storage Mover is the default recommended path for file share migrations as of 2026 — it is a fully managed, first-party service that maintains full file fidelity including NTFS ACLs, timestamps, and file attributes. Azure File Sync is the correct choice when you need ongoing hybrid caching after migration. Azure Data Box is for offline bulk transfer when bandwidth makes online transfer impractical.
| Tool | Azure Storage Mover | Azure File Sync | RoboCopy + AFS |
|---|---|---|---|
| Capability | |||
| NTFS ACL preservation | ✓ Full fidelity | ✓ Full fidelity | ✓ With /COPY:DATSO flag |
| Metadata preservation (timestamps, attributes) | ✓ Full | ✓ Full | ✓ With /COPY:DATSO |
| Ongoing hybrid sync post-migration | ✗ One-time only | ✓ Continuous sync | ✗ Manual re-runs required |
| Cloud tiering (hot data local, cold in Azure) | ✗ Not supported | ✓ AFS feature | ✗ Not supported |
| Management overhead | ✓ Fully managed service | ~ Agent deployment required | ✗ Manual scripting |
| Use when | |||
| Best fit | One-time migration from NAS, Windows Server, or Linux NFS. Good WAN bandwidth. | Hybrid ongoing access needed. Branch offices. Cloud tiering wanted. | Migration to Windows Server intermediate before AFS. Known scripting expertise. |
| Not appropriate when | Ongoing sync needed after cutover | Pure cloud migration, no ongoing on-prem access | Large datasets >50TB with complex ACLs |
Cutover Strategy — DFS-N, Rollback, and the Communication Plan
Cutover is the moment users stop seeing the on-premises file server and start seeing Azure Files. Done well, it is transparent — users open files from the same mapped drive letter they have always used. Done poorly, it is a major incident involving broken UNC paths, application failures, and help desk calls. The key technology that makes transparent cutover possible for SMB shares is DFS-Namespaces (DFS-N). DFS-N provides a namespace routing service for SMB by redirecting clients to Azure file shares while preserving the share addresses that users and scripts have been using for years. A cutover without DFS-N requires re-configuring every client, every script, and every application that has a hardcoded UNC path.
Configure DFS-Namespaces before migration begins
Install the DFS Namespaces role on a Windows Server in your environment. Create a domain-based namespace (e.g. \\corp.local\files). Create DFS targets for each file share pointing to the current on-premises file server paths — for example \\corp.local\files\Finance → \\FILESERVER01\Finance. Communicate to users that the new share path is the DFS path. When cutover occurs, you change the DFS target — not the clients, not the applications, not the scripts.
Execute cutover with DFS-N redirect and verify immediately
Schedule the cutover during the lowest-impact window — typically Saturday 22:00. Run a final delta sync to minimise data gap. Execute the DFS-N target change: Set-DfsnFolderTarget -Path "\\corp.local\files\Finance" -TargetPath "\\storageaccount.file.core.windows.net\finance" -State Online. Immediately verify access with a real user account — open a file, create a file, delete a file. Monitor sign-in logs and Defender for Cloud alerts for the first two hours. Have on-prem file server ready to reactivate for rollback. Do not decommission the source until validation is complete and at least one full business day has passed without issues.
Send the user communication before cutover, not after
Send a pre-cutover communication to all affected users at least five business days before the cutover window. Describe what is changing (the file share moves to Azure), what stays the same (the UNC path via DFS-N), what the maintenance window is, and who to contact if there are problems after cutover. A wave of help desk calls on Monday morning is not a sign that the migration failed — it is a sign that the communication plan did not reach the right people. Send the communication to managers as well as users, because managers are the ones who escalate.
Every item below must be completed and verified before the first byte of production data moves to Azure Files. This checklist is the gate between planning and execution.
- ✓Azure Migrate assessment complete — every share has a readiness status (Ready / Ready with Conditions / Not Ready), recommended tier, and monthly cost estimate
- ✓Illegal character scan complete — results exported to CSV, all flagged files renamed at source before migration begins
- ✓Path length scan complete — all paths >2,048 characters identified and restructuring plan in place
- ✓Bandwidth measured at business hours — actual Mbps recorded at 9am, 12pm, 3pm; daily GB transfer calculated; timeline confirmed against migration window
- ✓Port 445 verified from all network segments (on-prem, VPN, branch office, Azure VNet) using Test-NetConnection — fallback to port 443 configured if blocked
- ✓Private Endpoint created for file sub-resource — public access disabled — DNS resolves to private IP from all VNets and on-prem networks
- ✓Identity sync verified — all users needing access are synced to Entra ID via Entra Connect; storage account domain-joined to AD DS or Entra ID Kerberos configured
- ✓Share-level RBAC assigned — roles assigned at share level (not account level) for all user groups; tested with real accounts from each OS type
- ✓Root directory ACL set on Azure Files share — root ACL configured before bulk data copy begins; NTFS ACL migration strategy confirmed
- ✓Migration tool selected with written rationale — Storage Mover / AFS / RoboCopy; ACL fidelity confirmed for chosen tool on a test share
- ✓AFS agent version verified — all Azure File Sync agents running v22 or later; v18 and v19 expired May 13, 2026
- ✓Wave plan documented — three waves with explicit go/no-go gates; Wave 1 = archives/low-risk; Wave 3 = Finance/HR last
- ✓DFS-Namespace configured — users already accessing shares via DFS path; DFS target change tested in non-prod environment
- ✓Rollback plan documented — on-prem file server in read-only mode, retained for 14 days post-cutover; rollback command tested
- ✓User communication sent — 5+ business days before cutover; includes what changes, what stays the same, maintenance window, and contact for issues
- ✓Project plan signed off — all stakeholders including business representatives have approved the timeline and cutover window
"Migrations without structured checklists face data loss from unmapped dependencies, unexpected cloud bill overruns averaging 30–40%, compliance violations in regulated industries, extended downtime during cutover, and post-migration security misconfigurations. A rigorous pre-migration process eliminates the guesswork — replacing costly surprises with predictable, wave-by-wave execution."
— Azure Migration Checklist Report, 2026Lessons Learned from the Field
- The compatibility scan always finds something. It is never a wasted step. On a 15TB QNAP migration, we found 23 files with colons in their names — legacy reports named Finance_Report_2023:04:01.xlsx by a user who had been doing it the same way for six years. Silent skip in Azure Files. Found during the scan, fixed in 20 minutes. If we had skipped the scan, 23 files would not have migrated, and nobody would have noticed until someone went looking for a specific quarterly report three months later.
- Configure Private Endpoints before registering the AFS agent. If an Azure File Sync server endpoint is registered against the public endpoint and you add a Private Endpoint later, the agent must be re-registered. The correct sequence is: Private Endpoint first, DNS zone linked, resolution verified — then agent registration. Doing it in the wrong order adds hours of rework.
- The bandwidth calculation is almost always optimistic. Add a 1.5× contingency buffer to your estimated transfer time. Traffic shaping policies that nobody in the project team knew existed have extended three migrations I have run past their scheduled completion window. Measure at multiple times of day. Ask IT explicitly whether QoS or traffic prioritisation applies to the storage account subnet.
- DFS-N is worth configuring even if you are not using it for anything else. The entire value is the rollback. A DFS-N target change takes ten seconds. Asking 200 users to update their mapped drives at 07:00 on a Monday takes three hours and generates 40 help desk tickets.
- The user communication is not the last step in planning — it is a milestone in the project plan. If it goes out five days before cutover, it has a chance of being read before cutover. If it goes out the day before, it will be read the day after, when users are already calling the help desk.