1Parallels 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 15This specification contains minimal information about Parallels Disk Format, 16which is enough to properly work with QEMU. Nevertheless, Parallels Cloud Server 17and Parallels Desktop are able to add some unspecified nodes to the xml and use 18them, but they are for internal work and don't affect functionality. Also it 19uses auxiliary xml ``Snapshot.xml``, which allows storage of optional snapshot 20information, but this doesn't influence open/read/write functionality. QEMU and 21other software should not use fields not covered in this document or the 22``Snapshot.xml`` file, and must leave them as is. 23 24A Parallels disk consists of two parts: the set of snapshots and the disk 25descriptor file, which stores information about all files and snapshots. 26 27Definitions 28----------- 29 30Snapshot 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 34Snapshot image 35 an overlay representing the difference between this 36 snapshot and some earlier snapshot. 37 38Overlay 39 an image storing the different sectors between two captured states. 40 41Root image 42 a snapshot image with no parent, the root of the snapshot tree. 43 44Storage 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 56Description file 57 ``DiskDescriptor.xml`` stores information about disk parameters, 58 snapshots, and storages. 59 60Top 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 65Sector 66 a 512-byte data chunk. 67 68Description file 69---------------- 70 71All information is placed in a single XML element 72``Parallels_disk_image``. 73The element has only one attribute, ``Version``, which must be ``1.0``. 74 75The 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 92The ``Disk_Parameters`` element describes the physical layout of the 93virtual disk and some general settings. 94 95The ``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 113This element of the file describes the root image and all snapshot images. 114 115The ``StorageData`` element consists of the ``Storage`` child element, 116as shown below:: 117 118 <StorageData> 119 <Storage> 120 ... 121 </Storage> 122 </StorageData> 123 124A ``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 137Each ``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 154The ``Snapshots`` element describes the snapshot relations with the snapshot tree. 155 156The 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 169Each ``Shot`` element contains the following child elements: 170 171* ``GUID`` - an image GUID. 172* ``ParentGUID`` - GUID of the image of the parent snapshot. 173 174The software may traverse snapshots from child to parent using the 175``<ParentGUID>`` field as reference. The ``ParentGUID`` of the root 176snapshot is ``{00000000-0000-0000-0000-000000000000}``. 177There should be only one root snapshot. 178 179The Top snapshot could be 180described via two ways: via the ``TopGUID`` child 181element of the ``Snapshots`` element, or via the predefined GUID 182``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined, 183the predefined GUID is interpreted as a normal GUID. All snapshot images 184(except the Top Snapshot) should be 185opened read-only. 186 187There is another predefined GUID, 188``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by 189original and some third-party software for backup. QEMU and other 190software may operate with images with ``GUID = BackupID`` as usual. 191However, it is not recommended to use this 192GUID for new disks. The Top snapshot cannot have this GUID. 193