libvirt/libvirt.mli

   1 (** OCaml bindings for libvirt. *)
   2 (* (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc.
   3    http://libvirt.org/
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version,
   9    with the OCaml linking exception described in ../COPYING.LIB.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  19 *)
  20
  21 (**
  22    {2 Introduction and examples}
  23
  24    This is a set of bindings for writing OCaml programs to
  25    manage virtual machines through {{:http://libvirt.org/}libvirt}.
  26
  27    {3 Using libvirt interactively}
  28
  29    Using the interactive toplevel:
  30
  31 {v
  32 $ ocaml -I +libvirt
  33         Objective Caml version 3.10.0
  34
  35 # #load "unix.cma";;
  36 # #load "mllibvirt.cma";;
  37 # let name = "test:///default";;
  38 val name : string = "test:///default"
  39 # let conn = Libvirt.Connect.connect_readonly ~name () ;;
  40 val conn : Libvirt.ro Libvirt.Connect.t = <abstr>
  41 # Libvirt.Connect.get_node_info conn;;
  42   : Libvirt.Connect.node_info =
  43 {Libvirt.Connect.model = "i686"; Libvirt.Connect.memory = 3145728L;
  44  Libvirt.Connect.cpus = 16; Libvirt.Connect.mhz = 1400;
  45  Libvirt.Connect.nodes = 2; Libvirt.Connect.sockets = 2;
  46  Libvirt.Connect.cores = 2; Libvirt.Connect.threads = 2}
  47 v}
  48
  49    {3 Compiling libvirt programs}
  50
  51    This command compiles a program to native code:
  52
  53 {v
  54 ocamlopt -I +libvirt mllibvirt.cmxa list_domains.ml -o list_domains
  55 v}
  56
  57    {3 Example: Connect to the hypervisor}
  58
  59    The main modules are {!Libvirt.Connect}, {!Libvirt.Domain} and
  60    {!Libvirt.Network} corresponding respectively to the
  61    {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
  62    For brevity I usually rename these modules like this:
  63
  64 {v
  65 module C = Libvirt.Connect
  66 module D = Libvirt.Domain
  67 module N = Libvirt.Network
  68 v}
  69
  70    To get a connection handle, assuming a Xen hypervisor:
  71
  72 {v
  73 let name = "xen:///"
  74 let conn = C.connect_readonly ~name ()
  75 v}
  76
  77    {3 Example: List running domains}
  78
  79 {v
  80 open Printf
  81
  82 let n = C.num_of_domains conn in
  83 let ids = C.list_domains conn n in
  84 let domains = Array.map (D.lookup_by_id conn) ids in
  85 Array.iter (
  86   fun dom ->
  87     printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
  88 ) domains;
  89 v}
  90
  91    {3 Example: List inactive domains}
  92
  93 {v
  94 let n = C.num_of_defined_domains conn in
  95 let names = C.list_defined_domains conn n in
  96 Array.iter (
  97   fun name ->
  98     printf "inactive %s\n%!" name
  99 ) names;
 100 v}
 101
 102    {3 Example: Print node info}
 103
 104 {v
 105 let node_info = C.get_node_info conn in
 106 printf "model = %s\n" node_info.C.model;
 107 printf "memory = %Ld K\n" node_info.C.memory;
 108 printf "cpus = %d\n" node_info.C.cpus;
 109 printf "mhz = %d\n" node_info.C.mhz;
 110 printf "nodes = %d\n" node_info.C.nodes;
 111 printf "sockets = %d\n" node_info.C.sockets;
 112 printf "cores = %d\n" node_info.C.cores;
 113 printf "threads = %d\n%!" node_info.C.threads;
 114
 115 let hostname = C.get_hostname conn in
 116 printf "hostname = %s\n%!" hostname;
 117
 118 let uri = C.get_uri conn in
 119 printf "uri = %s\n%!" uri
 120 v}
 121
 122 *)
 123
 124
 125 (** {2 Programming issues}
 126
 127     {3 General safety issues}
 128
 129     Memory allocation / automatic garbage collection of all libvirt
 130     objects should be completely safe.  If you find any safety issues
 131     or if your pure OCaml program ever segfaults, please contact the author.
 132
 133     You can force a libvirt object to be freed early by calling
 134     the [close] function on the object.  This shouldn't affect
 135     the safety of garbage collection and should only be used when
 136     you want to explicitly free memory.  Note that explicitly
 137     closing a connection object does nothing if there are still
 138     unclosed domain or network objects referencing it.
 139
 140     Note that even though you hold open (eg) a domain object, that
 141     doesn't mean that the domain (virtual machine) actually exists.
 142     The domain could have been shut down or deleted by another user.
 143     Thus domain objects can through odd exceptions at any time.
 144     This is just the nature of virtualisation.
 145
 146     {3 Backwards and forwards compatibility}
 147
 148     OCaml-libvirt is backwards and forwards compatible with
 149     any libvirt >= 0.2.1.  One consequence of this is that
 150     your program can dynamically link to a {i newer} version of
 151     libvirt than it was compiled with, and it should still
 152     work.
 153
 154     When we link to an older version of libvirt.so, there may
 155     be missing functions.  If ocaml-libvirt was compiled with
 156     gcc, then these are turned into OCaml {!Libvirt.Not_supported}
 157     exceptions.
 158
 159     We don't support libvirt < 0.2.1, and never will so don't ask us.
 160
 161     {3 Threads}
 162
 163     You can issue multiple concurrent libvirt requests in
 164     different threads.  However you must follow this rule:
 165     Each thread must have its own separate libvirt connection, {i or}
 166     you must implement your own mutex scheme to ensure that no
 167     two threads can ever make concurrent calls using the same
 168     libvirt connection.
 169
 170     (Note that multithreaded code is not well tested.  If you find
 171     bugs please report them.)
 172
 173     {3 Initialisation}
 174
 175     Libvirt requires all callers to call virInitialize before
 176     using the library.  This is done automatically for you by
 177     these bindings when the program starts up, and we believe
 178     that the way this is done is safe.
 179
 180     {2 Reference}
 181 *)
 182
 183 type uuid = string
 184     (** This is a "raw" UUID, ie. a packed string of bytes. *)
 185
 186 type xml = string
 187     (** Type of XML (an uninterpreted string of bytes).  Use PXP, expat,
 188         xml-light, etc. if you want to do anything useful with the XML.
 189     *)
 190
 191 type filename = string
 192     (** A filename. *)
 193
 194 val get_version : ?driver:string -> unit -> int * int
 195   (** [get_version ()] returns the library version in the first part
 196       of the tuple, and [0] in the second part.
 197
 198       [get_version ~driver ()] returns the library version in the first
 199       part of the tuple, and the version of the driver called [driver]
 200       in the second part.
 201
 202       The version numbers are encoded as
 203       1,000,000 * major + 1,000 * minor + release.
 204   *)
 205
 206 val uuid_length : int
 207   (** Length of packed UUIDs. *)
 208
 209 val uuid_string_length : int
 210   (** Length of UUID strings. *)
 211
 212 type rw = [`R|`W]
 213 type ro = [`R]
 214     (** These
 215         {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
 216         are used to ensure the type-safety of read-only
 217         versus read-write connections.
 218
 219         All connection/domain/etc. objects are marked with
 220         a phantom read-write or read-only type, and trying to
 221         pass a read-only object into a function which could
 222         mutate the object will cause a compile time error.
 223
 224         Each module provides a function like {!Libvirt.Connect.const}
 225         to demote a read-write object into a read-only object.  The
 226         opposite operation is, of course, not allowed.
 227
 228         If you want to handle both read-write and read-only
 229         connections at runtime, use a variant similar to this:
 230 {v
 231 type conn_t =
 232     | No_connection
 233     | Read_only of Libvirt.ro Libvirt.Connect.t
 234     | Read_write of Libvirt.rw Libvirt.Connect.t
 235 v}
 236         See also the source of [mlvirsh].
 237     *)
 238
 239 type ('a, 'b) job_t
 240 (** Forward definition of {!Job.t} to avoid recursive module dependencies. *)
 241
 242 (** {3 Connections} *)
 243
 244 module Connect :
 245 sig
 246   type 'rw t
 247     (** Connection.  Read-only connections have type [ro Connect.t] and
 248         read-write connections have type [rw Connect.t].
 249       *)
 250
 251   type node_info = {
 252     model : string;                     (** CPU model *)
 253     memory : int64;                     (** memory size in kilobytes *)
 254     cpus : int;                         (** number of active CPUs *)
 255     mhz : int;                          (** expected CPU frequency *)
 256     nodes : int;                        (** number of NUMA nodes (1 = UMA) *)
 257     sockets : int;                      (** number of CPU sockets per node *)
 258     cores : int;                        (** number of cores per socket *)
 259     threads : int;                      (** number of threads per core *)
 260   }
 261
 262   val connect : ?name:string -> unit -> rw t
 263   val connect_readonly : ?name:string -> unit -> ro t
 264     (** [connect ~name ()] connects to the hypervisor with URI [name].
 265
 266         [connect ()] connects to the default hypervisor.
 267
 268         [connect_readonly] is the same but connects in read-only mode.
 269     *)
 270
 271   val close : [>`R] t -> unit
 272     (** [close conn] closes and frees the connection object in memory.
 273
 274         The connection is automatically closed if it is garbage
 275         collected.  This function just forces it to be closed
 276         and freed right away.
 277     *)
 278
 279   val get_type : [>`R] t -> string
 280     (** Returns the name of the driver (hypervisor). *)
 281
 282   val get_version : [>`R] t -> int
 283     (** Returns the driver version
 284         [major * 1_000_000 + minor * 1000 + release]
 285     *)
 286   val get_hostname : [>`R] t -> string
 287     (** Returns the hostname of the physical server. *)
 288   val get_uri : [>`R] t -> string
 289     (** Returns the canonical connection URI. *)
 290   val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
 291     (** Returns the maximum number of virtual CPUs
 292         supported by a guest VM of a particular type. *)
 293   val list_domains : [>`R] t -> int -> int array
 294     (** [list_domains conn max] returns the running domain IDs,
 295         up to a maximum of [max] entries.
 296         Call {!num_of_domains} first to get a value for [max].
 297     *)
 298   val num_of_domains : [>`R] t -> int
 299     (** Returns the number of running domains. *)
 300   val get_capabilities : [>`R] t -> xml
 301     (** Returns the hypervisor capabilities (as XML). *)
 302   val num_of_defined_domains : [>`R] t -> int
 303     (** Returns the number of inactive (shutdown) domains. *)
 304   val list_defined_domains : [>`R] t -> int -> string array
 305     (** [list_defined_domains conn max]
 306         returns the names of the inactive domains, up to
 307         a maximum of [max] entries.
 308         Call {!num_of_defined_domains} first to get a value for [max].
 309     *)
 310   val num_of_networks : [>`R] t -> int
 311     (** Returns the number of networks. *)
 312   val list_networks : [>`R] t -> int -> string array
 313     (** [list_networks conn max]
 314         returns the names of the networks, up to a maximum
 315         of [max] entries.
 316         Call {!num_of_networks} first to get a value for [max].
 317     *)
 318   val num_of_defined_networks : [>`R] t -> int
 319     (** Returns the number of inactive networks. *)
 320   val list_defined_networks : [>`R] t -> int -> string array
 321     (** [list_defined_networks conn max]
 322         returns the names of the inactive networks, up to a maximum
 323         of [max] entries.
 324         Call {!num_of_defined_networks} first to get a value for [max].
 325     *)
 326
 327   val num_of_pools : [>`R] t -> int
 328     (** Returns the number of storage pools. *)
 329   val list_pools : [>`R] t -> int -> string array
 330     (** Return list of storage pools. *)
 331   val num_of_defined_pools : [>`R] t -> int
 332     (** Returns the number of storage pools. *)
 333   val list_defined_pools : [>`R] t -> int -> string array
 334     (** Return list of storage pools. *)
 335
 336     (* The name of this function is inconsistent, but the inconsistency
 337      * is really in libvirt itself.
 338      *)
 339   val get_node_info : [>`R] t -> node_info
 340     (** Return information about the physical server. *)
 341
 342   val node_get_free_memory : [> `R] t -> int64
 343     (**
 344        [node_get_free_memory conn]
 345        returns the amount of free memory (not allocated to any guest)
 346        in the machine.
 347     *)
 348
 349   val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
 350     (**
 351        [node_get_cells_free_memory conn start max]
 352        returns the amount of free memory on each NUMA cell in kilobytes.
 353        [start] is the first cell for which we return free memory.
 354        [max] is the maximum number of cells for which we return free memory.
 355        Returns an array of up to [max] entries in length.
 356     *)
 357
 358   val maxcpus_of_node_info : node_info -> int
 359     (** Calculate the total number of CPUs supported (but not necessarily
 360         active) in the host.
 361     *)
 362
 363   val cpumaplen : int -> int
 364     (** Calculate the length (in bytes) required to store the complete
 365         CPU map between a single virtual and all physical CPUs of a domain.
 366     *)
 367
 368   val use_cpu : string -> int -> unit
 369     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 370   val unuse_cpu : string -> int -> unit
 371     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 372   val cpu_usable : string -> int -> int -> int -> bool
 373     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 374         [cpu] is usable by [vcpu]. *)
 375
 376   external const : [>`R] t -> ro t = "%identity"
 377     (** [const conn] turns a read/write connection into a read-only
 378         connection.  Note that the opposite operation is impossible.
 379       *)
 380 end
 381   (** Module dealing with connections.  [Connect.t] is the
 382       connection object. *)
 383
 384 (** {3 Domains} *)
 385
 386 module Domain :
 387 sig
 388   type 'rw t
 389     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 390         read-write handles have type [rw Domain.t].
 391     *)
 392
 393   type state =
 394     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 395     | InfoShutdown | InfoShutoff | InfoCrashed
 396
 397   type info = {
 398     state : state;                      (** running state *)
 399     max_mem : int64;                    (** maximum memory in kilobytes *)
 400     memory : int64;                     (** memory used in kilobytes *)
 401     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 402     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 403   }
 404
 405   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 406
 407   type vcpu_info = {
 408     number : int;                       (** virtual CPU number *)
 409     vcpu_state : vcpu_state;            (** state *)
 410     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 411     cpu : int;                          (** real CPU number, -1 if offline *)
 412   }
 413
 414   type sched_param = string * sched_param_value
 415   and sched_param_value =
 416     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 417     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 418     | SchedFieldFloat of float | SchedFieldBool of bool
 419
 420   type migrate_flag = Live
 421
 422   type memory_flag = Virtual
 423
 424   type block_stats = {
 425     rd_req : int64;
 426     rd_bytes : int64;
 427     wr_req : int64;
 428     wr_bytes : int64;
 429     errs : int64;
 430   }
 431
 432   type interface_stats = {
 433     rx_bytes : int64;
 434     rx_packets : int64;
 435     rx_errs : int64;
 436     rx_drop : int64;
 437     tx_bytes : int64;
 438     tx_packets : int64;
 439     tx_errs : int64;
 440     tx_drop : int64;
 441   }
 442
 443   val max_peek : [>`R] t -> int
 444     (** Maximum size supported by the {!block_peek} and {!memory_peek}
 445         functions.  If you want to peek more than this then you must
 446         break your request into chunks. *)
 447
 448   val create_linux : [>`W] Connect.t -> xml -> rw t
 449     (** Create a new guest domain (not necessarily a Linux one)
 450         from the given XML.
 451     *)
 452   val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
 453     (** Asynchronous domain creation. *)
 454   val lookup_by_id : 'a Connect.t -> int -> 'a t
 455     (** Lookup a domain by ID. *)
 456   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 457     (** Lookup a domain by UUID.  This uses the packed byte array UUID. *)
 458   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 459     (** Lookup a domain by (string) UUID. *)
 460   val lookup_by_name : 'a Connect.t -> string -> 'a t
 461     (** Lookup a domain by name. *)
 462   val destroy : [>`W] t -> unit
 463     (** Abruptly destroy a domain. *)
 464   val free : [>`R] t -> unit
 465     (** [free domain] frees the domain object in memory.
 466
 467         The domain object is automatically freed if it is garbage
 468         collected.  This function just forces it to be freed right
 469         away.
 470     *)
 471
 472   val suspend : [>`W] t -> unit
 473     (** Suspend a domain. *)
 474   val resume : [>`W] t -> unit
 475     (** Resume a domain. *)
 476   val save : [>`W] t -> filename -> unit
 477     (** Suspend a domain, then save it to the file. *)
 478   val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
 479     (** Asynchronous domain suspend. *)
 480   val restore : [>`W] Connect.t -> filename -> unit
 481     (** Restore a domain from a file. *)
 482   val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
 483     (** Asynchronous domain restore. *)
 484   val core_dump : [>`W] t -> filename -> unit
 485     (** Force a domain to core dump to the named file. *)
 486   val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
 487     (** Asynchronous core dump. *)
 488   val shutdown : [>`W] t -> unit
 489     (** Shutdown a domain. *)
 490   val reboot : [>`W] t -> unit
 491     (** Reboot a domain. *)
 492   val get_name : [>`R] t -> string
 493     (** Get the domain name. *)
 494   val get_uuid : [>`R] t -> uuid
 495     (** Get the domain UUID (as a packed byte array). *)
 496   val get_uuid_string : [>`R] t -> string
 497     (** Get the domain UUID (as a printable string). *)
 498   val get_id : [>`R] t -> int
 499     (** [getid dom] returns the ID of the domain.
 500
 501         Do not call this on a defined but not running domain.  Those
 502         domains don't have IDs, and you'll get an error here.
 503     *)
 504
 505   val get_os_type : [>`R] t -> string
 506     (** Get the operating system type. *)
 507   val get_max_memory : [>`R] t -> int64
 508     (** Get the maximum memory allocation. *)
 509   val set_max_memory : [>`W] t -> int64 -> unit
 510     (** Set the maximum memory allocation. *)
 511   val set_memory : [>`W] t -> int64 -> unit
 512     (** Set the normal memory allocation. *)
 513   val get_info : [>`R] t -> info
 514     (** Get information about a domain. *)
 515   val get_xml_desc : [>`R] t -> xml
 516     (** Get the XML description of a domain. *)
 517   val get_scheduler_type : [>`R] t -> string * int
 518     (** Get the scheduler type. *)
 519   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 520     (** Get the array of scheduler parameters. *)
 521   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 522     (** Set the array of scheduler parameters. *)
 523   val define_xml : [>`W] Connect.t -> xml -> rw t
 524     (** Define a new domain (but don't start it up) from the XML. *)
 525   val undefine : [>`W] t -> unit
 526     (** Undefine a domain - removes its configuration. *)
 527   val create : [>`W] t -> unit
 528     (** Launch a defined (inactive) domain. *)
 529   val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
 530     (** Asynchronous launch domain. *)
 531   val get_autostart : [>`R] t -> bool
 532     (** Get the autostart flag for a domain. *)
 533   val set_autostart : [>`W] t -> bool -> unit
 534     (** Set the autostart flag for a domain. *)
 535   val set_vcpus : [>`W] t -> int -> unit
 536     (** Change the number of vCPUs available to a domain. *)
 537   val pin_vcpu : [>`W] t -> int -> string -> unit
 538     (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
 539         CPUs.  See the libvirt documentation for details of the
 540         layout of the bitmap. *)
 541   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 542     (** [get_vcpus dom maxinfo maplen] returns the pinning information
 543         for a domain.  See the libvirt documentation for details
 544         of the array and bitmap returned from this function.
 545     *)
 546   val get_max_vcpus : [>`R] t -> int
 547     (** Returns the maximum number of vCPUs supported for this domain. *)
 548   val attach_device : [>`W] t -> xml -> unit
 549     (** Attach a device (described by the device XML) to a domain. *)
 550   val detach_device : [>`W] t -> xml -> unit
 551     (** Detach a device (described by the device XML) from a domain. *)
 552
 553   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 554     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 555     (** [migrate dom dconn flags ()] migrates a domain to a
 556         destination host described by [dconn].
 557
 558         The optional flag [?dname] is used to rename the domain.
 559
 560         The optional flag [?uri] is used to route the migration.
 561
 562         The optional flag [?bandwidth] is used to limit the bandwidth
 563         used for migration (in Mbps). *)
 564
 565   val block_stats : [>`R] t -> string -> block_stats
 566     (** Returns block device stats. *)
 567   val interface_stats : [>`R] t -> string -> interface_stats
 568     (** Returns network interface stats. *)
 569
 570   val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
 571     (** [block_peek dom path offset size buf boff] reads [size] bytes at
 572         [offset] in the domain's [path] block device.
 573
 574         If successful then the data is written into [buf] starting
 575         at offset [boff], for [size] bytes.
 576
 577         See also {!max_peek}. *)
 578   val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
 579     string -> int -> unit
 580     (** [memory_peek dom Virtual offset size] reads [size] bytes
 581         at [offset] in the domain's virtual memory.
 582
 583         If successful then the data is written into [buf] starting
 584         at offset [boff], for [size] bytes.
 585
 586         See also {!max_peek}. *)
 587
 588   external const : [>`R] t -> ro t = "%identity"
 589     (** [const dom] turns a read/write domain handle into a read-only
 590         domain handle.  Note that the opposite operation is impossible.
 591       *)
 592 end
 593   (** Module dealing with domains.  [Domain.t] is the
 594       domain object. *)
 595
 596 (** {3 Networks} *)
 597
 598 module Network :
 599 sig
 600   type 'rw t
 601     (** Network handle.  Read-only handles have type [ro Network.t] and
 602         read-write handles have type [rw Network.t].
 603     *)
 604
 605   val lookup_by_name : 'a Connect.t -> string -> 'a t
 606     (** Lookup a network by name. *)
 607   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 608     (** Lookup a network by (packed) UUID. *)
 609   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 610     (** Lookup a network by UUID string. *)
 611   val create_xml : [>`W] Connect.t -> xml -> rw t
 612     (** Create a network. *)
 613   val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
 614     (** Asynchronous create network. *)
 615   val define_xml : [>`W] Connect.t -> xml -> rw t
 616     (** Define but don't activate a network. *)
 617   val undefine : [>`W] t -> unit
 618     (** Undefine configuration of a network. *)
 619   val create : [>`W] t -> unit
 620     (** Start up a defined (inactive) network. *)
 621   val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
 622     (** Asynchronous start network. *)
 623   val destroy : [>`W] t -> unit
 624     (** Destroy a network. *)
 625   val free : [>`R] t -> unit
 626     (** [free network] frees the network object in memory.
 627
 628         The network object is automatically freed if it is garbage
 629         collected.  This function just forces it to be freed right
 630         away.
 631     *)
 632
 633   val get_name : [>`R] t -> string
 634     (** Get network name. *)
 635   val get_uuid : [>`R] t -> uuid
 636     (** Get network packed UUID. *)
 637   val get_uuid_string : [>`R] t -> string
 638     (** Get network UUID as a printable string. *)
 639   val get_xml_desc : [>`R] t -> xml
 640     (** Get XML description of a network. *)
 641   val get_bridge_name : [>`R] t -> string
 642     (** Get bridge device name of a network. *)
 643   val get_autostart : [>`R] t -> bool
 644     (** Get the autostart flag for a network. *)
 645   val set_autostart : [>`W] t -> bool -> unit
 646     (** Set the autostart flag for a network. *)
 647
 648   external const : [>`R] t -> ro t = "%identity"
 649     (** [const network] turns a read/write network handle into a read-only
 650         network handle.  Note that the opposite operation is impossible.
 651       *)
 652 end
 653   (** Module dealing with networks.  [Network.t] is the
 654       network object. *)
 655
 656 (** {3 Storage pools} *)
 657
 658 module Pool :
 659 sig
 660   type 'rw t
 661     (** Storage pool handle. *)
 662
 663   type pool_state = Inactive | Building | Running | Degraded
 664     (** State of the storage pool. *)
 665
 666   type pool_build_flags = New | Repair | Resize
 667     (** Flags for creating a storage pool. *)
 668
 669   type pool_delete_flags = Normal | Zeroed
 670     (** Flags for deleting a storage pool. *)
 671
 672   type pool_info = {
 673     state : pool_state;                 (** Pool state. *)
 674     capacity : int64;                   (** Logical size in bytes. *)
 675     allocation : int64;                 (** Currently allocated in bytes. *)
 676     available : int64;                  (** Remaining free space bytes. *)
 677   }
 678
 679   val lookup_by_name : 'a Connect.t -> string -> 'a t
 680   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 681   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 682     (** Look up a storage pool by name, UUID or UUID string. *)
 683
 684   val create_xml : [>`W] Connect.t -> xml -> rw t
 685     (** Create a storage pool. *)
 686   val define_xml : [>`W] Connect.t -> xml -> rw t
 687     (** Define but don't activate a storage pool. *)
 688   val build : [>`W] t -> pool_build_flags -> unit
 689     (** Build a storage pool. *)
 690   val undefine : [>`W] t -> unit
 691     (** Undefine configuration of a storage pool. *)
 692   val create : [>`W] t -> unit
 693     (** Start up a defined (inactive) storage pool. *)
 694   val destroy : [>`W] t -> unit
 695     (** Destroy a storage pool. *)
 696   val delete : [>`W] t -> unit
 697     (** Delete a storage pool. *)
 698   val free : [>`R] t -> unit
 699     (** Free a storage pool object in memory.
 700
 701         The storage pool object is automatically freed if it is garbage
 702         collected.  This function just forces it to be freed right
 703         away.
 704     *)
 705   val refresh : [`R] t -> unit
 706     (** Refresh the list of volumes in the storage pool. *)
 707
 708   val get_name : [`R] t -> string
 709     (** Name of the pool. *)
 710   val get_uuid : [`R] t -> uuid
 711     (** Get the UUID (as a packed byte array). *)
 712   val get_uuid_string : [`R] t -> string
 713     (** Get the UUID (as a printable string). *)
 714   val get_info : [`R] t -> pool_info
 715     (** Get information about the pool. *)
 716   val get_xml_desc : [`R] t -> xml
 717     (** Get the XML description. *)
 718   val get_autostart : [`R] t -> bool
 719     (** Get the autostart flag for the storage pool. *)
 720   val set_autostart : [`W] t -> bool -> unit
 721     (** Set the autostart flag for the storage pool. *)
 722
 723   val num_of_volumes : [`R] t -> int
 724     (** Returns the number of storage volumes within the storage pool. *)
 725   val list_volumes : [`R] t -> int -> string array
 726     (** Return list of storage volumes. *)
 727
 728   external const : [>`R] t -> ro t = "%identity"
 729     (** [const conn] turns a read/write storage pool into a read-only
 730         pool.  Note that the opposite operation is impossible.
 731       *)
 732 end
 733   (** Module dealing with storage pools. *)
 734
 735 (** {3 Storage volumes} *)
 736
 737 module Volume :
 738 sig
 739   type 'rw t
 740     (** Storage volume handle. *)
 741
 742   type vol_type = File | Block
 743     (** Type of a storage volume. *)
 744
 745   type vol_delete_flags = Normal | Zeroed
 746     (** Flags for deleting a storage volume. *)
 747
 748   type vol_info = {
 749     typ : vol_type;                     (** Type of storage volume. *)
 750     capacity : int64;                   (** Logical size in bytes. *)
 751     allocation : int64;                 (** Currently allocated in bytes. *)
 752   }
 753
 754   val lookup_by_name : 'a Pool.t -> string -> 'a t
 755   val lookup_by_key : 'a Connect.t -> string -> 'a t
 756   val lookup_by_path : 'a Connect.t -> string -> 'a t
 757     (** Look up a storage volume by name, key or path volume. *)
 758
 759   val pool_of_volume : 'a t -> 'a Pool.t
 760     (** Get the storage pool containing this volume. *)
 761
 762   val get_name : [`R] t -> string
 763     (** Name of the volume. *)
 764   val get_key : [`R] t -> string
 765     (** Key of the volume. *)
 766   val get_path : [`R] t -> string
 767     (** Path of the volume. *)
 768   val get_info : [`R] t -> vol_info
 769     (** Get information about the storage volume. *)
 770   val get_xml_desc : [`R] t -> xml
 771     (** Get the XML description. *)
 772
 773   val create_xml : [`W] Pool.t -> xml -> unit
 774     (** Create a storage volume. *)
 775   val delete : [`W] t -> unit
 776     (** Delete a storage volume. *)
 777   val free : [>`R] t -> unit
 778     (** Free a storage volume object in memory.
 779
 780         The storage volume object is automatically freed if it is garbage
 781         collected.  This function just forces it to be freed right
 782         away.
 783     *)
 784
 785   external const : [>`R] t -> ro t = "%identity"
 786     (** [const conn] turns a read/write storage volume into a read-only
 787         volume.  Note that the opposite operation is impossible.
 788       *)
 789 end
 790   (** Module dealing with storage volumes. *)
 791
 792 (** {3 Jobs and asynchronous processing} *)
 793
 794 module Job :
 795 sig
 796   type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
 797     (** A background asynchronous job.
 798
 799         Jobs represent a pending operation such as domain creation.
 800         The possible types for a job are:
 801
 802 {v
 803 (`Domain, `W) Job.t            Job creating a new domain
 804 (`Domain_nocreate, `W) Job.t   Job acting on an existing domain
 805 (`Network, `W) Job.t           Job creating a new network
 806 (`Network_nocreate, `W) Job.t  Job acting on an existing network
 807 v}
 808       *)
 809
 810   type job_type = Bounded | Unbounded
 811     (** A Bounded job is one where we can estimate time to completion. *)
 812
 813   type job_state = Running | Complete | Failed | Cancelled
 814     (** State of the job. *)
 815
 816   type job_info = {
 817     typ : job_type;                     (** Job type (Bounded, Unbounded) *)
 818     state : job_state;                  (** Job state (Running, etc.) *)
 819     running_time : int;                 (** Actual running time (seconds) *)
 820     (** The following fields are only available in Bounded jobs: *)
 821     remaining_time : int;               (** Estimated time left (seconds) *)
 822     percent_complete : int              (** Estimated percent complete *)
 823   }
 824
 825   val get_info : ('a,'b) t -> job_info
 826     (** Get information and status about the job. *)
 827
 828   val get_domain : ([`Domain], 'a) t -> 'a Domain.t
 829     (** Get the completed domain from a job.
 830
 831         You should only call it on a job in state Complete. *)
 832
 833   val get_network : ([`Network], 'a) t -> 'a Network.t
 834     (** Get the completed network from a job.
 835
 836         You should only call it on a job in state Complete. *)
 837
 838   val cancel : ('a,'b) t -> unit
 839     (** Cancel a job. *)
 840
 841   val free : ('a, [>`R]) t -> unit
 842     (** Free a job object in memory.
 843
 844         The job object is automatically freed if it is garbage
 845         collected.  This function just forces it to be freed right
 846         away.
 847     *)
 848
 849   external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
 850     (** [const conn] turns a read/write job into a read-only
 851         job.  Note that the opposite operation is impossible.
 852       *)
 853 end
 854   (** Module dealing with asynchronous jobs. *)
 855
 856 (** {3 Error handling and exceptions} *)
 857
 858 module Virterror :
 859 sig
 860   type code =
 861     | VIR_ERR_OK
 862     | VIR_ERR_INTERNAL_ERROR
 863     | VIR_ERR_NO_MEMORY
 864     | VIR_ERR_NO_SUPPORT
 865     | VIR_ERR_UNKNOWN_HOST
 866     | VIR_ERR_NO_CONNECT
 867     | VIR_ERR_INVALID_CONN
 868     | VIR_ERR_INVALID_DOMAIN
 869     | VIR_ERR_INVALID_ARG
 870     | VIR_ERR_OPERATION_FAILED
 871     | VIR_ERR_GET_FAILED
 872     | VIR_ERR_POST_FAILED
 873     | VIR_ERR_HTTP_ERROR
 874     | VIR_ERR_SEXPR_SERIAL
 875     | VIR_ERR_NO_XEN
 876     | VIR_ERR_XEN_CALL
 877     | VIR_ERR_OS_TYPE
 878     | VIR_ERR_NO_KERNEL
 879     | VIR_ERR_NO_ROOT
 880     | VIR_ERR_NO_SOURCE
 881     | VIR_ERR_NO_TARGET
 882     | VIR_ERR_NO_NAME
 883     | VIR_ERR_NO_OS
 884     | VIR_ERR_NO_DEVICE
 885     | VIR_ERR_NO_XENSTORE
 886     | VIR_ERR_DRIVER_FULL
 887     | VIR_ERR_CALL_FAILED
 888     | VIR_ERR_XML_ERROR
 889     | VIR_ERR_DOM_EXIST
 890     | VIR_ERR_OPERATION_DENIED
 891     | VIR_ERR_OPEN_FAILED
 892     | VIR_ERR_READ_FAILED
 893     | VIR_ERR_PARSE_FAILED
 894     | VIR_ERR_CONF_SYNTAX
 895     | VIR_ERR_WRITE_FAILED
 896     | VIR_ERR_XML_DETAIL
 897     | VIR_ERR_INVALID_NETWORK
 898     | VIR_ERR_NETWORK_EXIST
 899     | VIR_ERR_SYSTEM_ERROR
 900     | VIR_ERR_RPC
 901     | VIR_ERR_GNUTLS_ERROR
 902     | VIR_WAR_NO_NETWORK
 903     | VIR_ERR_NO_DOMAIN
 904     | VIR_ERR_NO_NETWORK
 905     | VIR_ERR_INVALID_MAC
 906     | VIR_ERR_AUTH_FAILED
 907     | VIR_ERR_INVALID_STORAGE_POOL
 908     | VIR_ERR_INVALID_STORAGE_VOL
 909     | VIR_WAR_NO_STORAGE
 910     | VIR_ERR_NO_STORAGE_POOL
 911     | VIR_ERR_NO_STORAGE_VOL
 912         (* ^^ NB: If you add a variant you MUST edit
 913            libvirt_c_epilogue.c:MAX_VIR_* *)
 914     | VIR_ERR_UNKNOWN of int
 915         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
 916
 917   val string_of_code : code -> string
 918
 919   type domain =
 920     | VIR_FROM_NONE
 921     | VIR_FROM_XEN
 922     | VIR_FROM_XEND
 923     | VIR_FROM_XENSTORE
 924     | VIR_FROM_SEXPR
 925     | VIR_FROM_XML
 926     | VIR_FROM_DOM
 927     | VIR_FROM_RPC
 928     | VIR_FROM_PROXY
 929     | VIR_FROM_CONF
 930     | VIR_FROM_QEMU
 931     | VIR_FROM_NET
 932     | VIR_FROM_TEST
 933     | VIR_FROM_REMOTE
 934     | VIR_FROM_OPENVZ
 935     | VIR_FROM_XENXM
 936     | VIR_FROM_STATS_LINUX
 937     | VIR_FROM_STORAGE
 938         (* ^^ NB: If you add a variant you MUST edit
 939            libvirt_c_epilogue.c: MAX_VIR_* *)
 940     | VIR_FROM_UNKNOWN of int
 941         (** Subsystem / driver which produced the error. *)
 942
 943   val string_of_domain : domain -> string
 944
 945   type level =
 946     | VIR_ERR_NONE
 947     | VIR_ERR_WARNING
 948     | VIR_ERR_ERROR
 949         (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
 950     | VIR_ERR_UNKNOWN_LEVEL of int
 951         (** No error, a warning or an error. *)
 952
 953   val string_of_level : level -> string
 954
 955   type t = {
 956     code : code;                        (** Error code. *)
 957     domain : domain;                    (** Origin of the error. *)
 958     message : string option;            (** Human-readable message. *)
 959     level : level;                      (** Error or warning. *)
 960     str1 : string option;               (** Informational string. *)
 961     str2 : string option;               (** Informational string. *)
 962     str3 : string option;               (** Informational string. *)
 963     int1 : int32;                       (** Informational integer. *)
 964     int2 : int32;                       (** Informational integer. *)
 965   }
 966     (** An error object. *)
 967
 968   val to_string : t -> string
 969     (** Turn the exception into a printable string. *)
 970
 971   val get_last_error : unit -> t option
 972   val get_last_conn_error : [>`R] Connect.t -> t option
 973     (** Get the last error at a global or connection level.
 974
 975         Normally you do not need to use these functions because
 976         the library automatically turns errors into exceptions.
 977     *)
 978
 979   val reset_last_error : unit -> unit
 980   val reset_last_conn_error : [>`R] Connect.t -> unit
 981     (** Reset the error at a global or connection level.
 982
 983         Normally you do not need to use these functions.
 984     *)
 985
 986   val no_error : unit -> t
 987     (** Creates an empty error message.
 988
 989         Normally you do not need to use this function.
 990     *)
 991 end
 992   (** Module dealing with errors. *)
 993
 994 exception Virterror of Virterror.t
 995 (** This exception can be raised by any library function that detects
 996     an error.  To get a printable error message, call
 997     {!Virterror.to_string} on the content of this exception.
 998 *)
 999
1000 exception Not_supported of string
1001 (**
1002     Functions may raise
1003     [Not_supported "virFoo"]
1004     (where [virFoo] is the libvirt function name) if a function is
1005     not supported at either compile or run time.  This applies to
1006     any libvirt function added after version 0.2.1.
1007
1008     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
1009 *)
1010