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