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 proper work with QEMU. Nevertheless, Parallels Cloud Server 17and Parallels Desktop are able to add some unspecified nodes to xml and use 18them, but they are for internal work and don't affect functionality. Also it 19uses auxiliary xml ``Snapshot.xml``, which allows to store optional snapshot 20information, but it doesn't influence open/read/write functionality. QEMU and 21other software should not use fields not covered in this document and 22``Snapshot.xml`` file and must leave them as is. 23 24Parallels 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 UUID and 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 snapshot image with no parent, the root of 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 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, 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``, that must be ``1.0``. 74 75Schema 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: 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 spec, 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 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 Cluster size for each "Compressed" (see below) image in 132 parallels disk must be equal to this field. Note: cluster 133 size for Parallels Expandable Image is in ``tracks`` field of 134 its header (see :doc:`parallels`). 135* Several ``Image`` child elements. 136 137Each ``Image`` element has 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. 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 ``<ParentGUID>`` 175field as reference. ``ParentGUID`` of root snapshot is 176``{00000000-0000-0000-0000-000000000000}``. There should be only one root 177snapshot. Top snapshot could be described via two ways: via ``TopGUID`` child 178element of the ``Snapshots`` element or via predefined GUID 179``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined, 180predefined GUID is interpreted as usual GUID. All snapshot images 181(except Top Snapshot) should be 182opened read-only. There is another predefined GUID, 183``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by 184original and some third-party software for backup, QEMU and other 185software may operate with images with ``GUID = BackupID`` as usual, 186however, it is not recommended to use this 187GUID for new disks. Top snapshot cannot have this GUID. 188