lib/diskimage.mli

   1 (** Diskimage library for reading disk images. *)
   2 (* (C) Copyright 2007-2008 Richard W.M. Jones, Red Hat Inc.
   3    http://libvirt.org/
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 2 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software
  17    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  *)
  19
  20 (**
  21    {2 Examples}
  22
  23 {[
  24   let machine = open_machine "host" ["hda", "/dev/hda"] in
  25   let machine = scan_machine machine in
  26   (* do what you want with the scan results ... *)
  27   close_machine machine
  28 ]}
  29 *)
  30
  31 (** {2 Device class and specialized subclasses} *)
  32
  33 class virtual device :
  34   object
  35     method virtual name : string
  36       (** Return some printable name for the device. *)
  37     method virtual size : int64
  38       (** Return the size of the device in bytes.
  39
  40           Note: For some types of devices, the device may have
  41           "holes", alignment requirements, etc. so this method doesn't
  42           imply that every byte from [0..size-1] is readable. *)
  43     method read : int64 -> int -> string
  44       (** [read offset len] reads len bytes starting at offset.
  45
  46           Note: A default implementation is provided for [read],
  47           but it is fairly inefficient because it uses {!mapblock} to
  48           map each block in the request. *)
  49     method read_bitstring : int64 -> int -> Bitmatch.bitstring
  50       (** [read_bitstring] is the same as [read] but returns
  51           a pa_bitmatch-style bitstring. *)
  52     method virtual blocksize : int
  53       (** [blocksize] returns the natural block size of the device. *)
  54     method virtual mapblock : int64 -> (device * int64) list
  55       (** [mapblock] describes how a block in this device is
  56           mapped down to any underlying device(s).
  57
  58           Returns [[]] (empty list) if there is no underlying
  59           device for this block.  Otherwise returns a list of
  60           [(device, byte-offset)] locations where this block is mapped.
  61
  62           Normally the returned list has length 1, but in cases
  63           such as mirroring you can have the same block mapped
  64           to several underlying devices. *)
  65   end
  66   (**
  67      A virtual (or physical!) device, encapsulating any translation
  68      that has to be done to access the device.  eg. For partitions
  69      there is a simple offset, but for LVM you may need complicated
  70      table lookups.
  71
  72      Note this very rare use of OOP in OCaml!
  73   *)
  74
  75 class block_device : string -> int ->
  76   object
  77     method name : string
  78     method size : int64
  79     method read : int64 -> int -> string
  80     method read_bitstring : int64 -> int -> Bitmatch.bitstring
  81     method blocksize : int
  82     method mapblock : int64 -> (device * int64) list
  83     method close : unit -> unit
  84       (** Close the device, freeing up the file descriptor. *)
  85   end
  86     (** A concrete device which just direct-maps a file or /dev device.
  87
  88         Create the device with [new block_device filename blocksize]
  89         where [filename] is the path to the file or device and
  90         [blocksize] is the blocksize of the device. *)
  91
  92 class offset_device : string -> int64 -> int64 -> int -> device ->
  93   object
  94     method name : string
  95     method size : int64
  96     method read : int64 -> int -> string
  97     method read_bitstring : int64 -> int -> Bitmatch.bitstring
  98     method blocksize : int
  99     method mapblock : int64 -> (device * int64) list
 100   end
 101     (** A concrete device which maps a linear part of an underlying device.
 102
 103         [new offset_device name start size blocksize dev] creates a new
 104         device which maps bytes from [start] to [start+size-1]
 105         of the underlying device [dev] (ie. in this device they
 106         appear as bytes [0] to [size-1]).
 107
 108         Useful for things like partitions.
 109     *)
 110
 111 val null_device : device
 112     (** The null device.  Any attempt to read generates an error. *)
 113
 114 (**
 115    {2 Structures used to describe machines, disks, partitions and filesystems}
 116
 117    {3 Machine/device model}
 118
 119    The "machine/device model" that we currently understand looks
 120    like this:
 121
 122 {v
 123 machines
 124   |
 125   \--- host partitions / disk image files
 126          ||
 127        guest block devices
 128          |
 129          +--> guest partitions (eg. using MBR)
 130          |      |
 131          \-(1)->+--- filesystems (eg. ext3)
 132                 |
 133                 \--- PVs for LVM
 134                        |||
 135                      VGs and LVs
 136 v}
 137
 138    (1) Filesystems and PVs may also appear directly on guest
 139    block devices.
 140
 141    Partition schemes (eg. MBR) and filesystems register themselves
 142    with this main module and they are queried first to get an idea
 143    of the physical devices, partitions and filesystems potentially
 144    available to the guest.
 145
 146    Volume management schemes (eg. LVM2) register themselves here
 147    and are called later with "spare" physical devices and partitions
 148    to see if they contain LVM data.  If this results in additional
 149    logical volumes then these are checked for filesystems.
 150
 151    Swap space is considered to be a dumb filesystem for the purposes
 152    of this discussion.
 153 *)
 154
 155 type machine = {
 156   m_name : string;                      (** Machine name. *)
 157   m_disks : disk list;                  (** Machine disks. *)
 158   m_lv_filesystems :
 159     (lv * filesystem) list;             (** Machine LV filesystems. *)
 160 }
 161     (** A 'machine' is just a convenient holder for collections of disks. *)
 162
 163 and disk = {
 164   d_name : string;                      (** Device name (eg "hda") *)
 165   d_dev : block_device;                 (** Disk device. *)
 166   d_content : disk_content;             (** What's on it. *)
 167 }
 168     (** A single physical disk image. *)
 169
 170 and disk_content =
 171     [ `Filesystem of filesystem         (** Contains a direct filesystem. *)
 172     | `Partitions of partitions         (** Contains partitions. *)
 173     | `PhysicalVolume of pv             (** Contains an LVM PV. *)
 174     | `Unknown                          (** Not probed or unknown. *)
 175     ]
 176
 177 and partitions = {
 178   parts_plugin_id : parts_plugin_id;    (** Partitioning scheme. *)
 179   parts : partition list;               (** Partitions. *)
 180 }
 181 and partition = {
 182   part_status : partition_status;       (** Bootable, etc. *)
 183   part_type : int;                      (** Partition filesystem type. *)
 184   part_dev : device;                    (** Partition device. *)
 185   part_content : partition_content;     (** What's on it. *)
 186 }
 187     (** Partitions as found on a disk image. *)
 188
 189 and partition_status = Bootable | Nonbootable | Malformed | NullEntry
 190 and partition_content =
 191     [ `Filesystem of filesystem         (** Filesystem. *)
 192     | `PhysicalVolume of pv             (** Contains an LVM PV. *)
 193     | `Unknown                          (** Not probed or unknown. *)
 194     ]
 195
 196 and filesystem = {
 197   fs_plugin_id : fs_plugin_id;          (** Filesystem type. *)
 198   fs_block_size : int64;                (** Block size (bytes). *)
 199   fs_blocks_total : int64;              (** Total blocks. *)
 200   fs_is_swap : bool;                    (** If swap, following not valid. *)
 201   fs_blocks_reserved : int64;           (** Blocks reserved for super-user. *)
 202   fs_blocks_avail : int64;              (** Blocks free (available). *)
 203   fs_blocks_used : int64;               (** Blocks in use. *)
 204   fs_inodes_total : int64;              (** Total inodes. *)
 205   fs_inodes_reserved : int64;           (** Inodes reserved for super-user. *)
 206   fs_inodes_avail : int64;              (** Inodes free (available). *)
 207   fs_inodes_used : int64;               (** Inodes in use. *)
 208 }
 209     (** A filesystem, with superblock contents. *)
 210
 211 and pv = {
 212   lvm_plugin_id : lvm_plugin_id;        (** The LVM plug-in which detected
 213                                             this. *)
 214   pv_uuid : string;                     (** UUID. *)
 215 }
 216 and lv = {
 217   lv_dev : device;                      (** Logical volume device. *)
 218 }
 219     (** Physical and logical volumes as used by LVM plug-ins. *)
 220
 221 and parts_plugin_id
 222 and fs_plugin_id
 223 and lvm_plugin_id
 224   (** Opaque IDs used to refer to the plug-ins. *)
 225
 226 val name_of_parts : parts_plugin_id -> string
 227 val name_of_filesystem : fs_plugin_id -> string
 228 val name_of_lvm : lvm_plugin_id -> string
 229   (** Convert plug-in IDs to printable strings. *)
 230
 231 (** {2 Scanning functions} *)
 232
 233 val open_machine : string -> (string * string) list -> machine
 234   (** [open_machine m_name devs]
 235       creates a {!machine} containing the devices listed.
 236
 237       [devs] is a list of pairs of [(name, path)] elements
 238       where [name] is something like ["hda"] and [path]
 239       is a path to a disk image or [/dev] device.
 240
 241       This function does not do any scanning, so all disk
 242       contents are just set to [`Unknown] and there are no
 243       LV filesystems in the returned structure.
 244   *)
 245
 246 val close_machine : machine -> unit
 247   (** This is a convenience function which calls the [dev#close]
 248       method on any open {!block_device}s owned by the machine.  This just
 249       has the effect of closing any file descriptors which are
 250       opened by these devices.
 251   *)
 252
 253 val scan_machine : machine -> machine
 254   (** This does a complete scan of all devices owned by a machine,
 255       identifying all partitions, filesystems, physical and logical
 256       volumes that are known to this library.
 257
 258       This scans down to the level of the filesystem superblocks.
 259
 260       Returns an updated {!machine} structure with the scan results.
 261   *)
 262
 263 (** {2 Debugging} *)
 264
 265 val debug : bool ref
 266   (** If set to true, functions emit debugging information to stderr. *)