docs/interop/prl-xml.txt

   1 = License =
   2
   3 Copyright (c) 2015-2017, Virtuozzo, Inc.
   4 Authors:
   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
  10 This work is licensed under the terms of the GNU GPL, version 2 or later.
  11 See the COPYING file in the top-level directory.
  12
  13 This specification contains minimal information about Parallels Disk Format,
  14 which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server
  15 and Parallels Desktop are able to add some unspecified nodes to xml and use
  16 them, but they are for internal work and don't affect functionality. Also it
  17 uses auxiliary xml "Snapshot.xml", which allows to store optional snapshot
  18 information, but it doesn't influence open/read/write functionality. QEMU and
  19 other software should not use fields not covered in this document and
  20 Snapshot.xml file and must leave them as is.
  21
  22 = Parallels Disk Format =
  23
  24 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     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 ==
  61 All information is placed in a single XML element Parallels_disk_image.
  62 The element has only one attribute "Version", that must be 1.0.
  63 Schema 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 ==
  78 The Disk_Parameters element describes the physical layout of the virtual disk
  79 and some general settings.
  80
  81 The 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 ==
  96 This element of the file describes the root image and all snapshot images.
  97
  98 The StorageData element consists of the Storage child element, as shown below:
  99 <StorageData>
 100     <Storage>
 101         ...
 102     </Storage>
 103 </StorageData>
 104
 105 A 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
 117 Each 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 ==
 129 The Snapshots element describes the snapshot relations with the snapshot tree.
 130
 131 The 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
 143 Each Shot element contains the following child elements:
 144     * GUID       - an image GUID.
 145     * ParentGUID - GUID of the image of the parent snapshot.
 146
 147 The software may traverse snapshots from child to parent using <ParentGUID>
 148 field as reference. ParentGUID of root snapshot is
 149 {00000000-0000-0000-0000-000000000000}. There should be only one root
 150 snapshot. Top snapshot could be described via two ways: via TopGUID child
 151 element of the Snapshots element or via predefined GUID
 152 {5fbaabe3-6958-40ff-92a7-860e329aab41}. If TopGUID is defined, predefined GUID is
 153 interpreted as usual GUID. All snapshot images (except Top Snapshot) should be
 154 opened read-only. There is another predefined GUID,
 155 BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}, which is used by original and
 156 some third-party software for backup, QEMU and other software may operate with
 157 images with GUID = BackupID as usual, however, it is not recommended to use this
 158 GUID for new disks. Top snapshot cannot have this GUID.