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