github.com/Microsoft/azure-vhd-utils@v0.0.0-20230613175315-7c30a3748a1b/README.md (about)

     1  
     2  # Azure VHD utilities.
     3  
     4  This project provides a Go package to read Virtual Hard Disk (VHD) file, a CLI interface to upload local VHD to Azure storage and to inspect a local VHD.
     5  
     6  An implementation of VHD [VHD specification](https://technet.microsoft.com/en-us/virtualization/bb676673.aspx) can be found in the [vhdcore](/vhdcore) package. 
     7  
     8  
     9  [![Go Report Card](https://goreportcard.com/badge/github.com/Microsoft/azure-vhd-utils)](https://goreportcard.com/report/github.com/Microsoft/azure-vhd-utils)
    10  
    11  # Installation
    12  > Note: You must have Go installed on your machine, at version 1.11 or greater. [https://golang.org/dl/](https://golang.org/dl/) 
    13  
    14      go get github.com/Microsoft/azure-vhd-utils
    15  
    16  # Features
    17  
    18  1. Fast uploads - This tool offers faster uploads by using multiple routines and balancing the load across them.
    19  2. Efficient uploads - This tool will only upload used (non-zero) portions of the disk.
    20  3. Parallelism - This tool can upload segements of the VHD concurrently (user configurable).
    21  
    22  # Usage
    23  
    24  ### Upload local VHD to Azure storage as page blob
    25  
    26  ```bash
    27  USAGE:
    28     azure-vhd-utils upload [command options] [arguments...]
    29  
    30  OPTIONS:
    31     --localvhdpath       Path to source VHD in the local machine.
    32     --stgaccountname     Azure storage account name.
    33     --stgaccountkey      Azure storage account key.
    34     --containername      Name of the container holding destination page blob. (Default: vhds)
    35     --blobname           Name of the destination page blob.
    36     --parallelism        Number of concurrent goroutines to be used for upload
    37  ```
    38  
    39  The upload command uploads local VHD to Azure storage as page blob. Once uploaded, you can use Microsoft Azure portal to register an image based on this page blob and use it to create Azure Virtual Machines.
    40  
    41  #### Note
    42  When creating a VHD for Microsoft Azure, the size of the VHD must be a whole number in megabytes, otherwise you will see an error similar to the following when you attempt to create image from the uploaded VHD in Azure:
    43  
    44  "The VHD http://<mystorageaccount>.blob.core.windows.net/vhds/<vhd-pageblob-name>.vhd has an unsupported virtual size of <number> bytes. The size must be a whole number (in MBs)."
    45  
    46  You should ensure the VHD size is even MB before uploading
    47  
    48  ##### For virtual box:
    49  -------------------
    50  VBoxManage modifyhd <absolute path to file> --resize &lt;size in MB&gt;
    51  
    52  ##### For Hyper V:
    53  ----------------
    54  Resize-VHD -Path <absolute path to file> -SizeBytes 
    55  
    56       http://azure.microsoft.com/blog/2014/05/22/running-freebsd-in-azure/
    57  
    58  ##### For Qemu:
    59  -------------
    60  qemu-img resize &lt;path-to-raw-file&gt; size
    61  
    62       http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-linux-create-upload-vhd-generic/
    63   
    64  #### How upload work
    65  
    66  Azure requires VHD to be in Fixed Disk format. The command converts Dynamic and Differencing Disk to Fixed Disk during upload process, the conversion will not consume any additional space in local machine.
    67  
    68  In case of Fixed Disk, the command detects blocks containing zeros and those will not be uploaded. In case of expandable disks (dynamic and differencing) only the blocks those are marked as non-empty in
    69  the Block Allocation Table (BAT) will be uploaded.
    70  
    71  The blocks containing data will be uploaded as chunks of 2 MB pages. Consecutive blocks will be merged to create 2 MB pages if the block size of disk is less than 2 MB. If the block size is greater than 2 MB, 
    72  tool will split them as 2 MB pages.  
    73  
    74  With page blob, we can upload multiple pages in parallel to decrease upload time. The command accepts the number of concurrent goroutines to use for upload through parallelism parameter. If the parallelism parameter is not proivded then it default to 8 * number_of_cpus.
    75  
    76  ### Inspect local VHD
    77  
    78  A subset of command are exposed under inspect command for inspecting various segments of VHD in the local machine.
    79  
    80  #### Show VHD footer
    81  
    82  ```bash
    83  USAGE:
    84     azure-vhd-utils inspect footer [command options] [arguments...]
    85  
    86  OPTIONS:
    87     --path   Path to VHD.
    88  ```
    89  
    90  #### Show VHD header of an expandable disk
    91  
    92  ```bash
    93  USAGE:
    94     azure-vhd-utils inspect header [command options] [arguments...]
    95  
    96  OPTIONS:
    97     --path   Path to VHD.
    98  ```
    99  
   100  Only expandable disks (dynamic and differencing) VHDs has header.
   101  
   102  #### Show Block Allocation Table (BAT) of an expandable disk
   103  
   104  ```bash
   105  USAGE:
   106     azure-vhd-utils inspect bat [command options] [arguments...]
   107  
   108  OPTIONS:
   109     --path           Path to VHD.
   110     --start-range    Start range.
   111     --end-range      End range.
   112     --skip-empty     Do not show BAT entries pointing to empty blocks.
   113  ```
   114  
   115  Only expandable disks (dynamic and differencing) VHDs has BAT.
   116  
   117  #### Show block general information
   118  
   119  ```bash
   120  USAGE:
   121     azure-vhd-utils inspect block info [command options] [arguments...]
   122  
   123  OPTIONS:
   124     --path   Path to VHD.
   125  ```
   126  
   127  This command shows the total number blocks, block size and size of block sector
   128  
   129  ### Show sector bitmap of an expandable disk's block
   130  
   131  ```bash
   132  USAGE:
   133     azure-vhd-utils inspect block bitmap [command options] [arguments...]
   134  
   135  OPTIONS:
   136     --path           Path to VHD.
   137     --block-index    Index of the block.
   138     
   139  ```
   140  
   141  # License
   142  
   143  This project is published under [MIT License](LICENSE).