How to upload an image VHD to Windows Azure using CSUpload


One of the exciting new possibilites in Windows Azure Infrastructure as a Service (IaaS) is the ability to create Virtual Machine images (VHD files) locally and upload them to your own image store in Windows Azure, and use them as the basis for new VMs. In this article I will demonstrate the process of uploading such an image and creating a virtual machine from it in Windows Azure.


There are many Cloud Storage explorers out there that can connect to Windows Azure blog storage to upload files. In this case I will use CSUpload.exe from Microsoft which is part of the Windows Azure SDK. It looks to have the best security and is specifically designed to upload images to Windows Azure. After you have installed the Windows Azure SDK the easiest way to locate CSUpload is to start the Windows Azure Command Prompt and change to the bin directory.


You can have three types of VHD files, or disks, in Windows Azure:

  • OS Images: These are generalized, read-only, base disks used for creating new virtual machines. They are either provided by Microsoft, third parties or you.
  • OS Disks: These are specialized, dedicated, writable disks that serve as the OS disk for a specific machine. If you have migrated a VM from your local virtualiztion platform to run it unmodified in Windows Azure you will use this kind of disk. Max size for an OS disk is 127 GB.
  • Data Disks: Writable disks that do not contain an operating system. They can either be migrated from your local network or created from Windows Azure. Max size for a data disk is 1 TB. The VM size determines how many data disks you can attach.

CSUpload can upload virtual disks with either the VHD or AVHD extension, meaning you can upload both parent (VHD) and child (AVHD) disks.

Setting up

The first thing we need to do is create a connection string for CSUpload to user for connecting to your Windows Azure subscription. You do this with the CSUpload Set-Connection command. (As you can see CSUpload borrows from the page of PowerShell with its verb-noun command structure. Hopefully this means that it will be replaced by native PowerShell cmdlets in the near future.) CSUpload Set-Connection takes exactly one argument which is a string in quotes consisting of your Windows Azure Subscription ID, Certificate Thumbprint and Service Management Endpoint. These are most easily obtained by running the Get-AzureSubscription cmdlet from a PowerShell prompt where the Windows Azure module is loaded. Here is an example.The strings marked in red are the ones you need to use in CSUpload:


Here’s how the CSUpload command would look (wrapped for readability):

csupload.exe set-connection

Windows(R) Azure(TM) Upload Tool version
for Microsoft(R) .NET Framework 3.5
Copyright (c) Microsoft Corporation. All rights reserved.

Updated the default connection string.


Once you have configured this, CSUpload will remember it until you do something to change your subscription, say delete your management certificate etc. You could also specify these parameters each time you run one of the other CSUpload commands, but that gets old real quick. Better to define them once.

The upload

To upload a disk CSUpload requires four mandatory parameters;

  • Destination: the storage account and path where the disk will be stored in Windows Azure. This is consists of two parts; the URL of the storage account, which you can get either from the portal or the cmdlet Get-AzureStorageAccount, the path where you want to put the VHD in that storage account, and the name of the VHD, including the .vhd extension.
  • Label: The disk’s label, which is displayed when you create new VMs in Windows Azure.
  • LiteralPath: The location of the VHD/AVHD file to upload, this is on your local disk.
  • OS: If the disk contains an operating system, specify either Windows or Linux.

Here is an example (wrapped for readability):

csupload.exe Add-PersistentVMImage
-Label “Windows 7 SP1”
-OS Windows
-LiteralPath “d:Hyper-VVirtual Hard Disksbase_win7sp1x64.vhd” –Name basewin7sp1x64.vhd

The command above produces the following output:

Windows(R) Azure(TM) Upload Tool version
for Microsoft(R) .NET Framework 3.5
Copyright (c) Microsoft Corporation. All rights reserved.

Using the saved connection string…
MD5 hash is being calculated for the file ‘d:Hyper-VVirtual Hard Disksbase_win7sp1x64.vhd’.
MD5 hash calculation is completed.ning Time: 00:00:00; Throughput: 2694,3Mbps
Elapsed time for the operation: 00:00:15
Creating new page blob of size 5368709632…
Elapsed time for upload: 00:00:00
Registering the image ‘basewin7sp1x64.vhd’ with repository.
Image ‘basewin7sp1x64.vhd’ is registered successfully.

Let’s look at what happens…

1. MD5 Hash

CSUpload starts by generating an MD5 hash of your file to gurantee that it has been transferred correctly.CSUpload will report its progress as a percentage and display the speed at which it reads data from you local disk. This number is given in Mbps. No actual transfer of data has started yet.

MD5 hash is being calculated for the file ‘d:Hyper-VVirtual Hard Disksbase_win7sp1x64.vhd’.
MD5 hash calculation is completed.ning Time: 00:00:00; Throughput: 2694,3Mbps
Elapsed time for the operation: 00:00:15

2. Allocate blob

Once the MD5 calculation is finished CSUpload will allocate a blob of the same size as the disk in your storage account.

Creating new page blob of size 5368709632…
Elapsed time for upload: 00:00:00

3. Transfer data

Now CSUpload will transfer the contents of the disk to Windows Azure. Note that only blocks in the VHD that actually contain data will be transferred, empty blocks are skipped. If you have a large disk you will see CSUpload use some time maping which blocks contain data.

Uploading: 2,2% complete; Remaining Time: 00:10:29; Throughput: 18,9Mbps
Elapsed time for upload: 00:04:22

4. Register in repository

We are using the CSUpload command Add-PersistentVMImage, which means we are uploading something that can be the basis of new VMs in Windows Azure IaaS. We need to tell Widnows Azure that it is dealing with an image so CSUpload will register the image in your subscriptions image repository. This means it will be visible both under Images in the Virtual Machine node and in your blob storage account.

Registering the image ‘basewin7sp1x64.vhd’ with repository.
Image ‘basewin7sp1x64.vhd’ is registered successfully.

Image in the image repository.

Image in the storage account.


  • I have a 50 Mbps fiber optic connection at home, and I was able to max it out while uploading the VHD to Windows Azure. It seems there is no upload limit into the datacenter when performing this kind of operation. VM sizes set a cap on bandwidth, but since the VHD is not yet associated with any VM it seems there is no limit. Further investigation required…
  • The VHD file must have a size that is a mutiple of 1024 bytes. Or else you will get this error:
    The VHD has an unsupported virtual size of 500000
    0000 bytes.  The size must be a whole number (in MBs).
  • For you so successfully connect to a new VM based on your image, any image you upload must have Remote Desktop enabled and allowed through the host based firewall.
  • The local Administrator account must be enabled and must have a password set. Later versions of Windows do not allow logon through Remote Desktop with a blank password.
  • You should use HTTPS when specifying you blob storage. HTTP could leak data during transfer, which CSUpload will warn you about:Use of http is insecure, can leak data to untrusted viewers and make your content vulnerable to data tampering by a malicious third party.

UPDATE: As of December 2012 a new cmdlet has been included in the Windows Azure PowerShell module; Add-AzureVHD. It performs the same functions as CSUpload with regards to uploading images and disks. Get the latest PS module here:

More free stuff in Windows Azure Active Directory

Microsoft announced today that they will offer two features in Windows Azure Active Directory free of charge; Access Control and Core Directory and Authentication.

  • Access Control provides centralized authentication and authorization by integrating with consumer identity providers such as Facebook or by using an on-premises deployment of the Windows Server Active Directory service. With Access Control, you can create a single application that can allow users to sign in with both their organizational credentials stored in Windows Azure Active Directory or Windows Server Active Directory, or by using popular consumer identity services like Microsoft Account, Facebook, Google, or Twitter. Historically, Access Control has been priced by number of transactions, but now it is available at no charge.
  • Core Directory and Authentication enables capabilities such as single sign-on, user and group management, directory synchronization, and directory federation. These capabilities are currently free of charge in the Windows Azure Active Directory Developer Preview and will remain free of charge after Windows Azure Active Directory reaches general availability.

Good times!