Deploy Azure File Sync

1. An Azure file share in the same region that you want to deploy Azure File Sync. For more information, see:

   • Region availability for Azure File Sync.
   • Create a file share for a step-by-step description of how to create a file share.

2. The following storage account settings must be enabled to allow Azure File Sync access to the storage account:

   • SMB security settings must allow SMB 3.1.1 protocol version, NTLM v2 authentication and AES-128-GCM encryption. To check the SMB security settings on the storage account, see SMB security settings.
   • Allow storage account key access must be Enabled. To check this setting, navigate to your storage account and select Configuration under the Settings section.

3. At least one supported instance of Windows Server to sync with Azure File Sync. For more information about supported versions of Windows Server and recommended system resources, see Windows file server considerations.

4. Optional: If you intend to use Azure File Sync with a Windows Server Failover Cluster, the File Server for general use role must be configured prior to installing the Azure File Sync agent on each node in the cluster. For more information on how to configure the File Server for general use role on a Failover Cluster, see Deploying a two-node clustered file server.

   Note

   The only scenario supported by Azure File Sync is Windows Server Failover Cluster with Clustered Disks. See Failover Clustering for Azure File Sync.

5. Although cloud management can be done with the Azure portal, advanced registered server functionality is provided through PowerShell cmdlets that are intended to be run locally in either PowerShell 5.1 or PowerShell 6+. On Windows Server 2012 R2, you can verify that you're running at least PowerShell 5.1.* by looking at the value of the PSVersion property of the $PSVersionTable object:

   $PSVersionTable.PSVersion
   

   If your PSVersion value is less than 5.1.*, you'll need to upgrade by downloading and installing Windows Management Framework (WMF) 5.1. The appropriate package to download and install for Windows Server 2012 R2 is Win8.1AndW2K12R2-KB*******-x64.msu.

   PowerShell 6+ can be used with any supported system, and can be downloaded via its GitHub page.

1. An Azure file share in the same region that you want to deploy Azure File Sync. For more information, see:

   • Region availability for Azure File Sync.
   • Create a file share for a step-by-step description of how to create a file share.

2. The following storage account settings must be enabled to allow Azure File Sync access to the storage account:

   • SMB security settings must allow SMB 3.1.1 protocol version, NTLM v2 authentication and AES-128-GCM encryption. To check the SMB security settings on the storage account, see SMB security settings.
   • Allow storage account key access must be Enabled. To check this setting, navigate to your storage account and select Configuration under the Settings section.

3. At least one supported instance of Windows Server to sync with Azure File Sync. For more information about supported versions of Windows Server and recommended system resources, see Windows file server considerations.

4. Optional: If you intend to use Azure File Sync with a Windows Server Failover Cluster, the File Server for general use role must be configured prior to installing the Azure File Sync agent on each node in the cluster. For more information on how to configure the File Server for general use role on a Failover Cluster, see Deploying a two-node clustered file server.

   Note

   The only scenario supported by Azure File Sync is Windows Server Failover Cluster with Clustered Disks. See Failover Clustering for Azure File Sync.

5. PowerShell 5.1 or PowerShell 6+. You may use the Az PowerShell module for Azure File Sync on any supported system, including non-Windows systems, however the server registration cmdlet must always be run on the Windows Server instance you're registering (you can do this directly or via PowerShell remoting). On Windows Server 2012 R2, verify that you're running at least PowerShell 5.1.* by looking at the value of the PSVersion property of the $PSVersionTable object:

   $PSVersionTable.PSVersion
   

   If your PSVersion value is less than 5.1.*, you'll need to upgrade by downloading and installing Windows Management Framework (WMF) 5.1. The appropriate package to download and install for Windows Server 2012 R2 is Win8.1AndW2K12R2-KB*******-x64.msu.

   PowerShell 6+ can be used with any supported system, and can be downloaded via its GitHub page.

6. If you have opted to use PowerShell 5.1, ensure that at least .NET 4.7.2 is installed. Learn more about .NET Framework versions and dependencies on your system.

   Important

   If you're installing .NET 4.7.2+ on Windows Server Core, you must install with the quiet and norestart flags, or the installation will fail. For example, if installing .NET 4.8, the command would look like the following:

   Start-Process -FilePath "ndp48-x86-x64-allos-enu.exe" -ArgumentList "/q /norestart" -Wait
   

7. The Az PowerShell module, which can be installed by following the instructions here: Install and configure Azure PowerShell.

   Note

   The Az.StorageSync module is now installed automatically when you install the Az PowerShell module.

1. An Azure file share in the same region that you want to deploy Azure File Sync. For more information, see:

   • Region availability for Azure File Sync.
   • Create a file share for a step-by-step description of how to create a file share.

2. The following storage account settings must be enabled to allow Azure File Sync access to the storage account:

   • SMB security settings must allow SMB 3.1.1 protocol version, NTLM v2 authentication and AES-128-GCM encryption. To check the SMB security settings on the storage account, see SMB security settings.
   • Allow storage account key access must be Enabled. To check this setting, navigate to your storage account and select Configuration under the Settings section.

3. At least one supported instance of Windows Server to sync with Azure File Sync. For more information about supported versions of Windows Server and recommended system resources, see Windows file server considerations.

4. Optional: If you intend to use Azure File Sync with a Windows Server Failover Cluster, the File Server for general use role must be configured prior to installing the Azure File Sync agent on each node in the cluster. For more information on how to configure the File Server for general use role on a Failover Cluster, see Deploying a two-node clustered file server.

   Note

   The only scenario supported by Azure File Sync is Windows Server Failover Cluster with Clustered Disks. See Failover Clustering for Azure File Sync.

5. Install the Azure CLI

   If you prefer, you can also use Azure Cloud Shell to complete the steps in this tutorial. Azure Cloud Shell is an interactive shell environment that you use through your browser. Start Cloud Shell by using one of these methods:

   • Select Try It in the upper-right corner of a code block. Try It will open Azure Cloud Shell, but it doesn't automatically copy the code to Cloud Shell.

   • Open Cloud Shell by going to https://shell.azure.com

   • Select the Cloud Shell button on the menu bar at the upper right corner in the Azure portal

6. Sign in.

   Sign in using the az login command if you're using a local install of the CLI.

   az login
   

   Follow the steps displayed in your terminal to complete the authentication process.

7. Install the az filesync Azure CLI extension.

   az extension add --name storagesync
   

   After installing the storagesync extension reference, you'll receive the following warning.

   The installed extension 'storagesync' is experimental and not covered by customer support. Please use with discretion.
   

8. Although cloud management can be done with the Azure CLI, advanced registered server functionality is provided through PowerShell cmdlets that are intended to be run locally in either PowerShell 5.1 or PowerShell 6+. On Windows Server 2012 R2, you can verify that you are running at least PowerShell 5.1.* by looking at the value of the PSVersion property of the $PSVersionTable object:

   $PSVersionTable.PSVersion
   

   If your PSVersion value is less than 5.1.*, you'll need to upgrade by downloading and installing Windows Management Framework (WMF) 5.1. The appropriate package to download and install for Windows Server 2012 R2 is Win8.1AndW2K12R2-KB*******-x64.msu.

   PowerShell 6+ can be used with any supported system, and can be downloaded via its GitHub page.

1. Open Server Manager.
2. Click Local Server:
   
3. On the Properties subpane, select the link for IE Enhanced Security Configuration.
   
4. In the Internet Explorer Enhanced Security Configuration dialog box, select Off for Administrators and Users:
   

To disable the Internet Explorer Enhanced Security Configuration, execute the following from an elevated PowerShell session:

$installType = (Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\").InstallationType

# This step is not required for Server Core
if ($installType -ne "Server Core") {
    # Disable Internet Explorer Enhanced Security Configuration 
    # for Administrators
    Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Active Setup\Installed Components\{A509B1A7-37EF-4b3f-8CFC-4F3A74704073}" -Name "IsInstalled" -Value 0 -Force

    # Disable Internet Explorer Enhanced Security Configuration 
    # for Users
    Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Active Setup\Installed Components\{A509B1A8-37EF-4b3f-8CFC-4F3A74704073}" -Name "IsInstalled" -Value 0 -Force

    # Force Internet Explorer closed, if open. This is required to fully apply the setting.
    # Save any work you have open in the Internet Explorer browser. This will not affect other browsers,
    # including Microsoft Edge.
    Stop-Process -Name iexplore -ErrorAction SilentlyContinue
}

Follow the instructions for the Azure portal or PowerShell.

To deploy a Storage Sync Service, go to the Azure portal, select Create a resource, and then search for Azure File Sync. In the search results, select Azure File Sync, and then select Create to open the Deploy Storage Sync tab.

On the pane that opens, enter the following information:

• Name: A unique name (per region) for the Storage Sync Service.
• Subscription: The subscription in which you want to create the Storage Sync Service. Depending on your organization's configuration strategy, you might have access to one or more subscriptions. An Azure subscription is the most basic container for billing for each cloud service (such as Azure Files).
• Resource group: A resource group is a logical group of Azure resources, such as a storage account or a Storage Sync Service. You can create a new resource group or use an existing resource group for Azure File Sync. We recommend using resource groups as containers to isolate resources logically for your organization, such as grouping HR resources or resources for a specific project.
• Location: The region in which you want to deploy Azure File Sync. Only supported regions are available in this list.

When you're finished, select Create to deploy the Storage Sync Service.

Replace <Az_Region>, <RG_Name>, and <my_storage_sync_service> with your own values, then use the following commands to create and deploy a Storage Sync Service:

$hostType = (Get-Host).Name

if ($installType -eq "Server Core" -or $hostType -eq "ServerRemoteHost") {
    Connect-AzAccount -UseDeviceAuthentication
}
else {
    Connect-AzAccount
}

# this variable holds the Azure region you want to deploy 
# Azure File Sync into
$region = '<Az_Region>'

# Check to ensure Azure File Sync is available in the selected Azure
# region.
$regions = @()
Get-AzLocation | ForEach-Object { 
    if ($_.Providers -contains "Microsoft.StorageSync") { 
        $regions += $_.Location 
    } 
}

if ($regions -notcontains $region) {
    throw [System.Exception]::new("Azure File Sync is either not available in the selected Azure Region or the region is mistyped.")
}

# the resource group to deploy the Storage Sync Service into
$resourceGroup = '<RG_Name>'

# Check to ensure resource group exists and create it if doesn't
$resourceGroups = @()
Get-AzResourceGroup | ForEach-Object { 
    $resourceGroups += $_.ResourceGroupName 
}

if ($resourceGroups -notcontains $resourceGroup) {
    New-AzResourceGroup -Name $resourceGroup -Location $region
}

$storageSyncName = "<my_storage_sync_service>"
$storageSync = New-AzStorageSyncService -ResourceGroupName $resourceGroup -Name $storageSyncName -Location $region

Follow the instructions for the Azure portal or PowerShell.

You can download the agent from the Microsoft Download Center. When the download is finished, double-click the MSI package to start the Azure File Sync agent installation.

We recommend that you do the following:

• Leave the default installation path (C:\Program Files\Azure\StorageSyncAgent) to simplify troubleshooting and server maintenance.
• Enable Microsoft Update to keep Azure File Sync up to date. All updates to the Azure File Sync agent, including feature updates and hotfixes, occur from Microsoft Update. We recommend installing the latest update to Azure File Sync. For more information, see Azure File Sync update policy.

When the Azure File Sync agent installation is finished, the Server Registration UI automatically opens. You must have a Storage Sync Service before registering; see the next section on how to create a Storage Sync Service.

Execute the following PowerShell code to download the appropriate version of the Azure File Sync agent for your OS and install it on your system.

# Gather the OS version
$osver = [System.Environment]::OSVersion.Version

# Download the appropriate version of the Azure File Sync agent for your OS.
if ($osver.Equals([System.Version]::new(10, 0, 20348, 0))) {
    Invoke-WebRequest `
        -Uri https://aka.ms/afs/agent/Server2022 `
        -OutFile "StorageSyncAgent.msi" 
} elseif ($osver.Equals([System.Version]::new(10, 0, 17763, 0))) {
    Invoke-WebRequest `
        -Uri https://aka.ms/afs/agent/Server2019 `
        -OutFile "StorageSyncAgent.msi" 
} elseif ($osver.Equals([System.Version]::new(10, 0, 14393, 0))) {
    Invoke-WebRequest `
        -Uri https://aka.ms/afs/agent/Server2016 `
        -OutFile "StorageSyncAgent.msi" 
} elseif ($osver.Equals([System.Version]::new(6, 3, 9600, 0))) {
    Invoke-WebRequest `
        -Uri https://aka.ms/afs/agent/Server2012R2 `
        -OutFile "StorageSyncAgent.msi" 
} else {
    throw [System.PlatformNotSupportedException]::new("Azure File Sync is only supported on Windows Server 2012 R2, Windows Server 2016, Windows Server 2019 and Windows Server 2022")
}

# Install the MSI. Start-Process is used to PowerShell blocks until the operation is complete.
# Note that the installer currently forces all PowerShell sessions closed - this is a known issue.
Start-Process -FilePath "StorageSyncAgent.msi" -ArgumentList "/quiet" -Wait

# Note that this cmdlet will need to be run in a new session based on the above comment.
# You may remove the temp folder containing the MSI and the EXE installer
Remove-Item -Path ".\StorageSyncAgent.msi" -Recurse -Force

Follow the instructions for the Azure portal or PowerShell.

The Server Registration UI should open automatically after the Azure File Sync agent installs. If it doesn't, you can open it manually from its file location: C:\Program Files\Azure\StorageSyncAgent\ServerRegistration.exe. When the Server Registration UI opens, select Sign-in to begin.

After you sign in, you're prompted for the following information:

• Azure Subscription: The subscription that contains the Storage Sync Service (see Deploy the Storage Sync Service).
• Resource Group: The resource group that contains the Storage Sync Service.
• Storage Sync Service: The name of the Storage Sync Service with which you want to register.

Select the appropriate information and then select Register to complete the server registration. As part of the registration process, you're prompted for an additional sign-in.

$registeredServer = Register-AzStorageSyncServer -ParentObject $storageSync

Follow the instructions for the Azure portal or PowerShell.

To create a sync group, in the Azure portal, go to your Storage Sync Service, and then select + Sync group:

In the pane that opens, enter the following information to create a sync group with a cloud endpoint:

• Sync group name: The name of the sync group to be created. This name must be unique within the Storage Sync Service, but can be any name that is logical for you.
• Subscription: The subscription where you deployed the Storage Sync Service in Deploy the Storage Sync Service.
• Storage account: If you select Select storage account, another pane appears in which you can select the storage account that has the Azure file share that you want to sync with.
• Azure file share: The name of the Azure file share with which you want to sync.

To create the sync group, execute the following PowerShell. Replace <my-sync-group> with the desired name of the sync group.

$syncGroupName = "<my-sync-group>"
$syncGroup = New-AzStorageSyncGroup -ParentObject $storageSync -Name $syncGroupName

Once the sync group has been successfully created, you can create your cloud endpoint. Be sure to replace <my-storage-account> and <my-file-share> with the expected values.

# Get or create a storage account with desired name
$storageAccountName = "<my-storage-account>"
$storageAccount = Get-AzStorageAccount -ResourceGroupName $resourceGroup | Where-Object {
    $_.StorageAccountName -eq $storageAccountName
}

if ($storageAccount -eq $null) {
    $storageAccount = New-AzStorageAccount `
        -Name $storageAccountName `
        -ResourceGroupName $resourceGroup `
        -Location $region `
        -SkuName Standard_LRS `
        -Kind StorageV2 `
        -EnableHttpsTrafficOnly:$true
}

# Get or create an Azure file share within the desired storage account
$fileShareName = "<my-file-share>"
$fileShare = Get-AzStorageShare -Context $storageAccount.Context | Where-Object {
    $_.Name -eq $fileShareName -and $_.IsSnapshot -eq $false
}

if ($fileShare -eq $null) {
    $fileShare = New-AzStorageShare -Context $storageAccount.Context -Name $fileShareName
}

# Create the cloud endpoint
New-AzStorageSyncCloudEndpoint `
    -Name $fileShare.Name `
    -ParentObject $syncGroup `
    -StorageAccountResourceId $storageAccount.Id `
    -AzureFileShareName $fileShare.Name

Use the az storagesync sync-group command to create a new sync group. To default a resource group for all CLI commands, use az configure.

az storagesync sync-group create --resource-group myResourceGroupName \
                                 --name myNewSyncGroupName \
                                 --storage-sync-service myStorageSyncServiceName \

Use the az storagesync sync-group cloud-endpoint command to create a new cloud endpoint.

az storagesync sync-group cloud-endpoint create --resource-group myResourceGroup \
                                                --storage-sync-service myStorageSyncServiceName \
                                                --sync-group-name mySyncGroupName \
                                                --name myNewCloudEndpointName \
                                                --storage-account mystorageaccountname \
                                                --azure-file-share-name azure-file-share-name

To add a server endpoint, go to the newly created sync group. Under Server endpoints, select +Add server endpoint. The Add server endpoint blade opens. Enter the following information to create a server endpoint:

• Registered server: The name of the server or cluster where you want to create the server endpoint.
• Path: The path on the Windows Server to be synced to the Azure file share. The path can be a folder (for example, D:\Data), volume root (for example, D:\), or volume mount point (for example, D:\Mount).
• Cloud Tiering: A switch to enable or disable cloud tiering. With cloud tiering, infrequently used or accessed files can be tiered to Azure Files. When you enable cloud tiering, there are two policies that you can set to inform Azure File Sync when to tier cool files: the Volume Free Space Policy and the Date Policy.
  • Volume Free Space: The amount of free space to reserve on the volume on which the server endpoint is located. For example, if volume free space is set to 50% on a volume that has only one server endpoint, roughly half the amount of data is tiered to Azure Files. Regardless of whether cloud tiering is enabled, your Azure file share always has a complete copy of the data in the sync group.
  • Date Policy: Files are tiered to the cloud if they haven't been accessed (that is, read or written to) for the specified number of days. For example, if you noticed that files that have gone more than 15 days without being accessed are typically archival files, you should set your date policy to 15 days.
• Initial Sync: The Initial Sync section is available only for the first server endpoint in a sync group (section changes to Initial Download when creating more than one server endpoint in a sync group). Within the Initial Sync section, you can select the Initial Upload and Initial Download behavior.

  • Initial Upload: You can select how the server initially uploads the data to the Azure file share:

    • Option #1: Merge the content of this server path with the content in the Azure file share. Files with the same name and path will lead to conflicts if their content is different. Both versions of those files will be stored next to each other. If your server path or Azure file share is empty, always choose this option.
    • Option #2: Authoritatively overwrite files and folders in the Azure file share with content in this server’s path. This option avoids file conflicts.

    To learn more, see Initial sync.

  • Initial Download: You can select how the server initially downloads the Azure file share data. This setting is important when the server is connecting to an Azure file share with files in it. "Namespace" stands for the file and folder structure without the file content. File content of "tiered files" is recalled from the cloud to the server by local access or policy.

    • Option #1: Download the namespace first and then recall the file content, as much as will fit on the local disk.
    • Option #2: Download the namespace only. The file content will be recalled when accessed.
    • Option #3: Avoid tiered files. Files will only appear on the server once they're fully downloaded.

    To learn more, see Initial download.

To add the server endpoint, select Create. Your files are now kept in sync across your Azure file share and Windows Server.

Execute the following PowerShell commands to create the server endpoint, and be sure to replace <your-server-endpoint-path> and <your-volume-free-space> with the desired values. Check the settings for the optional initial download and initial upload policies.

$serverEndpointPath = "<your-server-endpoint-path>"
$cloudTieringDesired = $true
$volumeFreeSpacePercentage = <your-volume-free-space>
# Optional property. Choose from: [NamespaceOnly] default when cloud tiering is enabled. [NamespaceThenModifiedFiles] default when cloud tiering is disabled. [AvoidTieredFiles] only available when cloud tiering is disabled.
$initialDownloadPolicy = "NamespaceOnly"
$initialUploadPolicy = "Merge"
# Optional property. Choose from: [Merge] default for all new server endpoints. Content from the server and the cloud merge. This is the right choice if one location is empty or other server endpoints already exist in the sync group. [ServerAuthoritative] This is the right choice when you seeded the Azure file share (e.g. with Data Box) AND you are connecting the server location you seeded from. This enables you to catch up the Azure file share with the changes that happened on the local server since the seeding.

if ($cloudTieringDesired) {
    # Ensure endpoint path is not the system volume
    $directoryRoot = [System.IO.Directory]::GetDirectoryRoot($serverEndpointPath)
    $osVolume = "$($env:SystemDrive)\"
    if ($directoryRoot -eq $osVolume) {
        throw [System.Exception]::new("Cloud tiering cannot be enabled on the system volume")
    }

    # Create server endpoint
    New-AzStorageSyncServerEndpoint `
        -Name $registeredServer.FriendlyName `
        -SyncGroup $syncGroup `
        -ServerResourceId $registeredServer.ResourceId `
        -ServerLocalPath $serverEndpointPath `
        -CloudTiering `
        -VolumeFreeSpacePercent $volumeFreeSpacePercentage `
        -InitialDownloadPolicy $initialDownloadPolicy `
        -InitialUploadPolicy $initialUploadPolicy
} else {
    # Create server endpoint
    New-AzStorageSyncServerEndpoint `
        -Name $registeredServer.FriendlyName `
        -SyncGroup $syncGroup `
        -ServerResourceId $registeredServer.ResourceId `
        -ServerLocalPath $serverEndpointPath `
        -InitialDownloadPolicy $initialDownloadPolicy
}

Use the az storagesync sync-group server-endpoint command to create a new server endpoint.

# Create a new sync group server endpoint 
az storagesync sync-group server-endpoint create --resource-group myResourceGroupName \
                                                 --name myNewServerEndpointName
                                                 --registered-server-id 91beed22-7e9e-4bda-9313-fec96c286e0
                                                 --server-local-path d:\myPath
                                                 --storage-sync-service myStorageSyncServiceNAme
                                                 --sync-group-name mySyncGroupName

# Create a new sync group server endpoint with additional optional parameters
az storagesync sync-group server-endpoint create --resource-group myResourceGroupName \
                                                 --storage-sync-service myStorageSyncServiceName \
                                                 --sync-group-name mySyncGroupName \
                                                 --name myNewServerEndpointName \
                                                 --registered-server-id 91beed22-7e9e-4bda-9313-fec96c286e0 \
                                                 --server-local-path d:\myPath \
                                                 --cloud-tiering on \
                                                 --volume-free-space-percent 85 \
                                                 --tier-files-older-than-days 15 \
                                                 --initial-download-policy NamespaceOnly [OR] NamespaceThenModifiedFiles [OR] AvoidTieredFiles
                                                 --initial-upload-policy Merge [OR] ServerAuthoritative

1. In the Azure portal, go to your Storage Sync Service, select the correct sync group, and then identify the server endpoint for which you want to closely track changes in the Azure file share (cloud endpoint).
2. In the cloud tiering section, find the Azure file share download topic. You'll see the currently selected mode, and you can change it to track Azure file share changes more closely and proactively recall them to the server.

You can modify server endpoint properties in PowerShell through the Set-AzStorageSyncServerEndpoint cmdlet.

# Optional parameter. Default: "UpdateLocallyCachedFiles", alternative behavior: "DownloadNewAndModifiedFiles"
$recallBehavior = "DownloadNewAndModifiedFiles"

Set-AzStorageSyncServerEndpoint -InputObject <PSServerEndpoint> -LocalCacheMode $recallBehavior