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