Linux migration to Azure File Sync

Summary — Migrate from Linux (Samba) to a hybrid Azure File Sync deployment

Applicability

• Data source: NAS running Linux with Samba (SMB shares).

• Migration route covered: Linux Samba ⇒ Windows Server (2012 R2 or later) ⇒ Azure File Sync to Azure file shares.

• Not applicable if your source is NFS or if you plan to sync directly from Linux. Azure File Sync runs on Windows Server with direct-attached storage (DAS) only.

Goals

• Move SMB shares from a Linux Samba server to Windows Server, then use Azure File Sync for a hybrid cloud setup with on-premises caching.

• Preserve data integrity and minimize downtime (fit within maintenance windows where possible).

Phased approach (overview)

1

Phase 1 — Decide how many Azure file shares you need

• A single Windows Server (or cluster) can sync up to 30 Azure file shares.

• Consider 1:1 mapping (on-prem share → Azure file share) if under 30.

• Options when >30 shares:

  • Share grouping: place multiple top-level folders under a common root and sync that root to one Azure file share.

  • Volume sync: sync a volume root to a single Azure file share.

• Keep items per share low for performance: tested to 100M items, best practice <20–30M items.

• Create a namespace-mapping table (template provided) to plan mapping of on-prem folders → Azure file shares.

2

Phase 2 — Provision Windows Server instance on-premises

• Deploy Windows Server 2012 R2 minimum (2022 recommended) as VM or physical server (clusters supported).

• Attach direct-attached storage (DAS). NAS isn't supported.

• You may provision less local storage if you plan to use Azure File Sync cloud tiering — then migrate in batches or use Robocopy /LFSM.

• Consider deduplication and sizing of CPU/RAM based on the number of items to sync.

3

Phase 3 — Deploy Storage Sync Service (Azure cloud resource)

• Create a Storage Sync Service in an Azure region close to your location; house sync and storage resources in the same region and resource group.

• Usually use a single Storage Sync Service unless you must isolate distinct server sets.

4

Phase 4 — Deploy Azure storage resources

• Provision storage accounts and Azure file shares per your mapping.

• Best practice: place highly active shares in separate storage accounts (IOPS/throughput are per account).

• Default file share size is 5 TiB; follow steps to create larger shares (100 TiB has redundancy constraints).

• Make resource names meaningful and consistent with on-prem shares.

5

Phase 5 — Install Azure File Sync agent on Windows Server

• Turn off Internet Explorer Enhanced Security Configuration during installation stage.

• Install required PowerShell modules:

Install-Module -Name Az -AllowClobber
Install-Module -Name Az.StorageSync

• During agent install, register the server to your Storage Sync Service.

• Configure proxy/firewall as needed. After registration, verify the server appears under Storage Sync Service → Registered servers in the Azure portal.

6

Phase 6 — Configure Azure File Sync (create sync groups & endpoints)

• For each Azure file share create a sync group in the Storage Sync Service; Azure file share becomes the cloud endpoint.

• Add a server endpoint (the local folder on your Windows Server) to each sync group.

• Cloud tiering is optional per server endpoint but mandatory if local storage < total data size. For migration, temporarily set tiering to 99% free space to ensure local space is freed quickly; revert after migration.

• Test sync by creating a file locally and confirming it appears in the cloud endpoint.

7

Phase 7 — Migrate data with Robocopy

• Use Robocopy from a Windows machine (or copy tools if not using Samba) to copy data from the Linux SMB share to the Windows Server folder that’s configured as a server endpoint; Azure File Sync will move data to the cloud.

• Recommended Robocopy example (mirror/purge, multithreaded, logging):

robocopy <SourcePath> <Dest.Path> /MT:20 /R:2 /W:1 /B /MIR /IT /COPY:DATSO /DCOPY:DAT /NP /NFL /NDL /XD "System Volume Information" /UNILOG:<FilePathAndName>

• Important switch notes:

  • /MT:n — multithreaded; 8–20 often balanced for initial copy.

  • /R:n and /W:n — retry and wait behavior for transient failures.

  • /B — backup mode (requires elevated rights).

  • /MIR — mirror; be careful to match source/target folder levels to avoid deletions.

  • /IT — helps preserve certain metadata changes.

  • /COPY and /DCOPY — control fidelity (ACLs, timestamps, etc.).

  • /LFSM — low free space mode for tiered targets (useful when destination is tiered; not compatible with some switches).

  • /L — test run only (list files without copying).

• If local storage is smaller than source, enable cloud tiering and/or use /LFSM to prevent running out of space. Robocopy may still outrun tiering — plan job sequencing and batch sizes accordingly.

• Recommendation: use Windows Server 2022; if using 2019 ensure required patches are installed.

8

Phase 8 — User cut-over

• Run initial Robocopy to move the bulk of data.

• Re-run Robocopy repeatedly (only deltas transfer) until the remaining change set is acceptable for downtime.

• For final cutover: prevent further changes on Linux share (e.g., change ACLs or take server offline), run last Robocopy to catch final changes, create SMB shares on Windows Server and set share-level permissions to match the original.

• Recreate local users if used on Linux and map SIDs as required; AD-based ACLs transfer as-is.

• After migration, revert cloud tiering free-space policy from 99% to a suitable cache level (e.g., ~20%) for normal operations — ensure you update all sync groups.

Robocopy troubleshooting & common issues

• Most common failure: "Volume full" on Windows Server when Robocopy outpaces cloud tiering.

  • Let Azure File Sync finish syncing and cloud tiering free local space (runs hourly), then rerun the Robocopy job.

  • Plan Robocopy batches and avoid running all jobs in parallel if local capacity is limited.

• Other topology/scale constraints and considerations:

  • A cloud endpoint (Azure file share) can be in only one sync group.

  • A sync group supports only one server endpoint per registered server.

  • A single server can register up to 30 Azure file shares; add servers to extend total concurrent syncs.

  • Cross-tenant setups (resources in different Microsoft Entra tenants) are not supported.

Next steps / additional resources

• Azure File Sync overview: https://docs.azure.cn/en-us/storage/file-sync/file-sync-planning

• Deploy Azure File Sync (deployment guide): https://docs.azure.cn/en-us/storage/file-sync/file-sync-deployment-guide

• Troubleshooting Azure File Sync: https://learn.microsoft.com/troubleshoot/azure/azure-storage/file-sync-troubleshoot

Notes and warnings

• Azure File Sync does not support syncing from Linux clients or NFS shares.

• Be cautious with /MIR and folder-level mismatches to avoid unintended deletions.

• If you used cloud tiering with 99% free space during migration, remember to lower that threshold after cutover; otherwise cache behavior will remain severely constrained.

Last updated: 05/31/2024

If you want, I can:

• Produce a concise checklist for the migration cutover.

• Extract the Robocopy recommended command and generate a set of runnable/test variations (dry-run, LFSM variant, low-thread variant).