Quickstart: Create and manage Azure file shares using Azure CLI

This guide walks you through the basics of working with Azure file shares with the Azure CLI. Azure file shares are just like other file shares, but stored in the cloud and backed by the Azure platform. Azure File shares support the industry standard SMB protocol and enable file sharing across multiple machines, applications, and instances.

If you don't have an Azure subscription, create a free account before you begin.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Cloud Shell lets you use either bash or PowerShell to work with Azure services. You can use the Cloud Shell pre-installed commands to run the code in this article without having to install anything on your local environment.

To launch Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the top-right menu bar in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Launch Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS.

  4. Press Enter to run the code.

If you decide to install and use Azure CLI locally, for the steps in this article, you must be running Azure CLI version 2.0.4 or later. Run az --version to find your Azure CLI version. If you need to install or upgrade, see Install Azure CLI 2.0.

By default, Azure CLI commands return JavaScript Object Notation (JSON). JSON is the standard way to send and receive messages from REST APIs. To facilitate working with JSON responses, some of the examples in this article use the query parameter on Azure CLI commands. This parameter uses the JMESPath query language to parse JSON. To learn more about how to use the results of Azure CLI commands by following the JMESPath query language, see the JMESPath tutorial.

Sign in to Azure

If you are using the Azure CLI locally, open a prompt and sign in to Azure if you haven't done so already.

az login

Create a resource group

A resource group is a logical container in which Azure resources are deployed and managed. If you don't already have an Azure resource group, you can use the az group create command to create one.

The following example creates a resource group named myResourceGroup in the East US location:

az group create --name myResourceGroup --location eastus

Create a storage account

A storage account is a shared pool of storage in which you can deploy Azure file shares or other storage resources, such as blobs or queues. A storage account can contain an unlimited number of file shares. A share can store an unlimited number of files, up to the capacity limits of the storage account.

The following example creates a storage account named mystorageaccount<random number> by using the az storage account create command, and then puts the name of that storage account in the $STORAGEACCT variable. Storage account names must be unique, so make sure to replace "mystorageacct" with a unique name.

STORAGEACCT=$(az storage account create \
    --resource-group "myResourceGroup" \
    --name "mystorageacct" \
    --location eastus \
    --sku Standard_LRS \
    --query "name" | tr -d '"')

Get the storage account key

Storage account keys control access to resources in a storage account. The keys are automatically created when you create a storage account. You can get the storage account keys for your storage account by using the az storage account keys list command:

STORAGEKEY=$(az storage account keys list \
    --resource-group "myResourceGroup" \
    --account-name $STORAGEACCT \
    --query "[0].value" | tr -d '"')

Create an Azure file share

Now, you can create your first Azure file share. Create file shares by using the az storage share create command. This example creates an Azure file share named myshare:

az storage share create \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --name "myshare" 

Share names can contain only lowercase letters, numbers, and single hyphens (but they can't start with a hyphen). For complete details about naming file shares and files, see Naming and referencing shares, directories, files, and metadata.

Use your Azure file share

Azure Files provides two methods of working with files and folders within your Azure file share: the industry standard Server Message Block (SMB) protocol and the File REST protocol.

To mount a file share with SMB, see the following document based on your OS:

Using an Azure file share with the File REST protocol

It is possible work directly with the File REST protocol directly (handcrafting REST HTTP calls yourself), but the most common way to use the File REST protocol is to use the Azure CLI, the Azure PowerShell module, or an Azure Storage SDK, all of which provide a nice wrapper around the File REST protocol in the scripting/programming language of your choice.

We expect most uses of Azure Files will want to work with their Azure file share over the SMB protocol, as this allows them to use the existing applications and tools they expect to be able to use, but there are several reasons why it is advantageous to use the File REST API rather than SMB, such as:

  • You are browsing your file share from the Azure Bash Cloud Shell (which cannot mount file shares over SMB).
  • You need to execute a script or application from a client that cannot mount an SMB share, such as on-premises clients that do not have port 445 unblocked.
  • You are taking advantage of serverless resources, such as Azure Functions.

The following examples show how to use the Azure CLI to manipulate your Azure file share with the File REST protocol.

Create a directory

To create a new directory named myDirectory at the root of your Azure file share, use the az storage directory create command:

az storage directory create \
   --account-name $STORAGEACCT \
   --account-key $STORAGEKEY \
   --share-name "myshare" \
   --name "myDirectory" 

Upload a file

To demonstrate how to upload a file by using the az storage file upload command, first create a file to upload on the Cloud Shell scratch drive. In the following example, you create and then upload the file:

date > ~/clouddrive/SampleUpload.txt

az storage file upload \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
	--share-name "myshare" \
	--source "~/clouddrive/SampleUpload.txt" \
    --path "myDirectory/SampleUpload.txt"

If you're running Azure CLI locally, substitute ~/clouddrive with a path that exists on your machine.

After you upload the file, you can use the az storage file list command to make sure that the file was uploaded to your Azure file share:

az storage file list \
    --account-name $STORAGEACCT \
	--account-key $STORAGEKEY \
	--share-name "myshare" \
    --path "myDirectory" \
	--output table

Download a file

You can use the az storage file download command to download a copy of the file that you uploaded to the Cloud Shell scratch drive:

# Delete an existing file by the same name as SampleDownload.txt, if it exists, because you've run this example before
rm -rf ~/clouddrive/SampleDownload.txt

az storage file download \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --share-name "myshare" \
    --path "myDirectory/SampleUpload.txt" \
    --dest "~/clouddrive/SampleDownload.txt"

Copy files

A common task is to copy files from one file share to another file share, or to or from an Azure Blob storage container. To demonstrate this functionality, create a new share. Copy the file that you uploaded to this new share by using the az storage file copy command:

az storage share create \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --name "myshare2"

az storage directory create \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --share-name "myshare2" \
    --name "myDirectory2"

az storage file copy start \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --source-share "myshare" \
	--source-path "myDirectory/SampleUpload.txt" \
    --destination-share "myshare2" \
	--destination-path "myDirectory2/SampleCopy.txt"

Now, if you list the files in the new share, you should see your copied file:

az storage file list \
    --account-name $STORAGEACCT \
	--account-key $STORAGEKEY \
	--share-name "myshare2" \
	--output table

Although the az storage file copy start command is convenient for file moves between Azure file shares and Azure Blob storage containers, we recommend that you use AzCopy for larger moves. (Larger in terms of the number or size of files being moved.) Learn more about AzCopy for Linux and AzCopy for Windows. AzCopy must be installed locally. AzCopy isn't available in Cloud Shell.

Create and manage share snapshots

Another useful task that you can do with an Azure file share is create share snapshots. A snapshot preserves a point-in-time copy of an Azure file share. Share snapshots are similar to some operating system technologies that you might already be familiar with:

SNAPSHOT=$(az storage share snapshot \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --name "myshare" \
    --query "snapshot" | tr -d '"')

Browse share snapshot contents

You can browse the contents of a share snapshot by passing the time stamp of the share snapshot that you captured in the $SNAPSHOT variable to the az storage file list command:

az storage file list \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --share-name "myshare" \
    --snapshot $SNAPSHOT \
    --output table

List share snapshots

To see the list of snapshots that you've taken for your share, use the following command:

az storage share list \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --include-snapshot \
    --query "[? name=='myshare' && snapshot!=null]" | tr -d '"'

Restore from a share snapshot

You can restore a file by using the az storage file copy start command that you used earlier. First, delete the SampleUpload.txt file that you uploaded, so you can restore it from the snapshot:

# Delete SampleUpload.txt
az storage file delete \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --share-name "myshare" \
    --path "myDirectory/SampleUpload.txt"
 # Build the source URI for a snapshot restore
URI=$(az storage account show \
    --resource-group "myResourceGroup" \
    --name $STORAGEACCT \
    --query "primaryEndpoints.file" | tr -d '"')
 URI=$URI"myshare/myDirectory/SampleUpload.txt?sharesnapshot="$SNAPSHOT
 # Restore SampleUpload.txt from the share snapshot
az storage file copy start \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --source-uri $URI \
    --destination-share "myshare" \
    --destination-path "myDirectory/SampleUpload.txt"

Delete a share snapshot

You can delete a share snapshot by using the az storage share delete command. Use the variable that contains the $SNAPSHOT reference to the --snapshot parameter:

az storage share delete \
    --account-name $STORAGEACCT \
    --account-key $STORAGEKEY \
    --name "myshare" \
    --snapshot $SNAPSHOT

Clean up resources

When you are done, you can use the az group delete command to remove the resource group and all related resources:

az group delete --name "myResourceGroup"

Alternatively, you can remove resources individually.

  • To remove the Azure file shares that you created for this article:

    az storage share delete \
        --account-name $STORAGEACCT \
        --account-key $STORAGEKEY \
        --name "myshare" \
        --delete-snapshots include
    
    az storage share delete \
        --account-name $STORAGEACCT \
        --account-key $STORAGEKEY \
        --name "myshare2" \
        --delete-snapshots include
    
  • To remove the storage account itself. (This implicitly removes the Azure file shares that you created, and any other storage resources that you might have created, such as an Azure Blob storage container.)

    az storage account delete \
        --resource-group "myResourceGroup" \
        --name $STORAGEACCT \
        --yes
    

Next steps