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