| 1 | Parallels Disk Format |
| 2 | ===================== |
| 3 | |
| 4 | .. |
| 5 | Copyright (c) 2015-2017, Virtuozzo, Inc. |
| 6 | Authors: |
| 7 | 2015 Denis Lunev <den@openvz.org> |
| 8 | 2015 Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> |
| 9 | 2016-2017 Klim Kireev <klim.kireev@virtuozzo.com> |
| 10 | 2016-2017 Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com> |
| 11 | |
| 12 | This work is licensed under the terms of the GNU GPL, version 2 or later. |
| 13 | See the COPYING file in the top-level directory. |
| 14 | |
| 15 | This specification contains minimal information about Parallels Disk Format, |
| 16 | which is enough to properly work with QEMU. Nevertheless, Parallels Cloud Server |
| 17 | and Parallels Desktop are able to add some unspecified nodes to the xml and use |
| 18 | them, but they are for internal work and don't affect functionality. Also it |
| 19 | uses auxiliary xml ``Snapshot.xml``, which allows storage of optional snapshot |
| 20 | information, but this doesn't influence open/read/write functionality. QEMU and |
| 21 | other software should not use fields not covered in this document or the |
| 22 | ``Snapshot.xml`` file, and must leave them as is. |
| 23 | |
| 24 | A Parallels disk consists of two parts: the set of snapshots and the disk |
| 25 | descriptor file, which stores information about all files and snapshots. |
| 26 | |
| 27 | Definitions |
| 28 | ----------- |
| 29 | |
| 30 | Snapshot |
| 31 | a record of the contents captured at a particular time, capable |
| 32 | of storing current state. A snapshot has a UUID and a parent UUID. |
| 33 | |
| 34 | Snapshot image |
| 35 | an overlay representing the difference between this |
| 36 | snapshot and some earlier snapshot. |
| 37 | |
| 38 | Overlay |
| 39 | an image storing the different sectors between two captured states. |
| 40 | |
| 41 | Root image |
| 42 | a snapshot image with no parent, the root of the snapshot tree. |
| 43 | |
| 44 | Storage |
| 45 | the backing storage for a subset of the virtual disk. When |
| 46 | there is more than one storage in a Parallels disk then that |
| 47 | is referred to as a split image. In this case every storage |
| 48 | covers a specific address space area of the disk and has its |
| 49 | particular root image. Split images are not considered here |
| 50 | and are not supported. Each storage consists of disk |
| 51 | parameters and a list of images. The list of images always |
| 52 | contains a root image and may also contain overlays. The |
| 53 | root image can be an expandable Parallels image file or |
| 54 | plain. Overlays must be expandable. |
| 55 | |
| 56 | Description file |
| 57 | ``DiskDescriptor.xml`` stores information about disk parameters, |
| 58 | snapshots, and storages. |
| 59 | |
| 60 | Top Snapshot |
| 61 | The overlay between actual state and some previous snapshot. |
| 62 | It is not a snapshot in the classical sense because it |
| 63 | serves as the active image that the guest writes to. |
| 64 | |
| 65 | Sector |
| 66 | a 512-byte data chunk. |
| 67 | |
| 68 | Description file |
| 69 | ---------------- |
| 70 | |
| 71 | All information is placed in a single XML element |
| 72 | ``Parallels_disk_image``. |
| 73 | The element has only one attribute, ``Version``, which must be ``1.0``. |
| 74 | |
| 75 | The schema of ``DiskDescriptor.xml``:: |
| 76 | |
| 77 | <Parallels_disk_image Version="1.0"> |
| 78 | <Disk_Parameters> |
| 79 | ... |
| 80 | </Disk_Parameters> |
| 81 | <StorageData> |
| 82 | ... |
| 83 | </StorageData> |
| 84 | <Snapshots> |
| 85 | ... |
| 86 | </Snapshots> |
| 87 | </Parallels_disk_image> |
| 88 | |
| 89 | ``Disk_Parameters`` element |
| 90 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 91 | |
| 92 | The ``Disk_Parameters`` element describes the physical layout of the |
| 93 | virtual disk and some general settings. |
| 94 | |
| 95 | The ``Disk_Parameters`` element MUST contain the following child elements: |
| 96 | |
| 97 | * ``Disk_size`` - number of sectors in the disk, |
| 98 | desired size of the disk. |
| 99 | * ``Cylinders`` - number of the disk cylinders. |
| 100 | * ``Heads`` - number of the disk heads. |
| 101 | * ``Sectors`` - number of the disk sectors per cylinder |
| 102 | (sector size is 512 bytes) |
| 103 | Limitation: The product of the ``Heads``, ``Sectors`` and ``Cylinders`` |
| 104 | values MUST be equal to the value of the Disk_size parameter. |
| 105 | * ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may |
| 106 | use padding set to 1; however this case is not covered |
| 107 | by this specification. QEMU and other software should not open |
| 108 | such disks and should not create them. |
| 109 | |
| 110 | ``StorageData`` element |
| 111 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 112 | |
| 113 | This element of the file describes the root image and all snapshot images. |
| 114 | |
| 115 | The ``StorageData`` element consists of the ``Storage`` child element, |
| 116 | as shown below:: |
| 117 | |
| 118 | <StorageData> |
| 119 | <Storage> |
| 120 | ... |
| 121 | </Storage> |
| 122 | </StorageData> |
| 123 | |
| 124 | A ``Storage`` element has the following child elements: |
| 125 | |
| 126 | * ``Start`` - start sector of the storage, in case of non split storage |
| 127 | equals to 0. |
| 128 | * ``End`` - number of sector following the last sector, in case of non |
| 129 | split storage equals to ``Disk_size``. |
| 130 | * ``Blocksize`` - storage cluster size, number of sectors per one cluster. |
| 131 | The cluster size for each "Compressed" (see below) image in |
| 132 | a parallels disk must be equal to this field. Note: the cluster |
| 133 | size for a Parallels Expandable Image is in the ``tracks`` field of |
| 134 | its header (see :doc:`parallels`). |
| 135 | * Several ``Image`` child elements. |
| 136 | |
| 137 | Each ``Image`` element has the following child elements: |
| 138 | |
| 139 | * ``GUID`` - image identifier, UUID in curly brackets. |
| 140 | For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.`` |
| 141 | The GUID is used by the Snapshots element to reference images |
| 142 | (see below) |
| 143 | * ``Type`` - image type of the element. It can be: |
| 144 | |
| 145 | * ``Plain`` for raw files. |
| 146 | * ``Compressed`` for expanding disks. |
| 147 | |
| 148 | * ``File`` - path to image file. The path can be relative to |
| 149 | ``DiskDescriptor.xml`` or absolute. |
| 150 | |
| 151 | ``Snapshots`` element |
| 152 | ^^^^^^^^^^^^^^^^^^^^^ |
| 153 | |
| 154 | The ``Snapshots`` element describes the snapshot relations with the snapshot tree. |
| 155 | |
| 156 | The element contains the set of ``Shot`` child elements, as shown below:: |
| 157 | |
| 158 | <Snapshots> |
| 159 | <TopGUID> ... </TopGUID> /* Optional child element */ |
| 160 | <Shot> |
| 161 | ... |
| 162 | </Shot> |
| 163 | <Shot> |
| 164 | ... |
| 165 | </Shot> |
| 166 | ... |
| 167 | </Snapshots> |
| 168 | |
| 169 | Each ``Shot`` element contains the following child elements: |
| 170 | |
| 171 | * ``GUID`` - an image GUID. |
| 172 | * ``ParentGUID`` - GUID of the image of the parent snapshot. |
| 173 | |
| 174 | The software may traverse snapshots from child to parent using the |
| 175 | ``<ParentGUID>`` field as reference. The ``ParentGUID`` of the root |
| 176 | snapshot is ``{00000000-0000-0000-0000-000000000000}``. |
| 177 | There should be only one root snapshot. |
| 178 | |
| 179 | The Top snapshot could be |
| 180 | described via two ways: via the ``TopGUID`` child |
| 181 | element of the ``Snapshots`` element, or via the predefined GUID |
| 182 | ``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined, |
| 183 | the predefined GUID is interpreted as a normal GUID. All snapshot images |
| 184 | (except the Top Snapshot) should be |
| 185 | opened read-only. |
| 186 | |
| 187 | There is another predefined GUID, |
| 188 | ``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by |
| 189 | original and some third-party software for backup. QEMU and other |
| 190 | software may operate with images with ``GUID = BackupID`` as usual. |
| 191 | However, it is not recommended to use this |
| 192 | GUID for new disks. The Top snapshot cannot have this GUID. |