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 type uuid = string
  21 (** This is a "raw" UUID, ie. a packed string of bytes. *)
  22
  23 type xml = string
  24 (** Type of XML (an uninterpreted string of bytes).  Use PXP, expat,
  25     xml-light, etc. if you want to do anything useful with the XML.
  26 *)
  27
  28 type filename = string
  29 (** A filename. *)
  30
  31 val get_version : ?driver:string -> unit -> int * int
  32   (** [get_version ()] returns the library version in the first part
  33       of the tuple, and [0] in the second part.
  34
  35       [get_version ~driver ()] returns the library version in the first
  36       part of the tuple, and the version of the driver called [driver]
  37       in the second part.
  38
  39       The version numbers are encoded as
  40       1,000,000 * major + 1,000 * minor + release.
  41   *)
  42
  43 val uuid_length : int
  44   (** Length of packed UUIDs. *)
  45
  46 val uuid_string_length : int
  47   (** Length of UUID strings. *)
  48
  49 (* These phantom types are used to ensure the type-safety of read-only
  50  * versus read-write connections.  For more information see:
  51  * http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html
  52  *)
  53 type rw = [`R|`W]
  54 type ro = [`R]
  55
  56 module Connect :
  57 sig
  58   type 'rw t
  59     (** Connection.  Read-only connections have type [ro Connect.t] and
  60         read-write connections have type [rw Connect.t].
  61       *)
  62
  63   type node_info = {
  64     model : string;                     (** CPU model *)
  65     memory : int64;                     (** memory size in kilobytes *)
  66     cpus : int;                         (** number of active CPUs *)
  67     mhz : int;                          (** expected CPU frequency *)
  68     nodes : int;                        (** number of NUMA nodes (1 = UMA) *)
  69     sockets : int;                      (** number of CPU sockets per node *)
  70     cores : int;                        (** number of cores per socket *)
  71     threads : int;                      (** number of threads per core *)
  72   }
  73
  74   val connect : ?name:string -> unit -> rw t
  75   val connect_readonly : ?name:string -> unit -> ro t
  76     (** [connect ~name ()] connects to the hypervisor with URI [name].
  77
  78         [connect ()] connects to the default hypervisor.
  79
  80         [connect_readonly] is the same but connects in read-only mode.
  81     *)
  82
  83   val close : [>`R] t -> unit
  84     (** [close conn] closes and frees the connection object in memory.
  85
  86         The connection is automatically closed if it is garbage
  87         collected.  This function just forces it to be closed
  88         and freed right away.
  89     *)
  90
  91   val get_type : [>`R] t -> string
  92     (** Returns the name of the driver (hypervisor). *)
  93
  94   val get_version : [>`R] t -> int
  95     (** Returns the driver version
  96         [major * 1_000_000 + minor * 1000 + release]
  97     *)
  98   val get_hostname : [>`R] t -> string
  99     (** Returns the hostname of the physical server. *)
 100   val get_uri : [>`R] t -> string
 101     (** Returns the canonical connection URI. *)
 102   val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
 103     (** Returns the maximum number of virtual CPUs
 104         supported by a guest VM of a particular type. *)
 105   val list_domains : [>`R] t -> int -> int array
 106     (** [list_domains conn max] returns the running domain IDs,
 107         up to a maximum of [max] entries.
 108         Call {!num_of_domains} first to get a value for [max].
 109     *)
 110   val num_of_domains : [>`R] t -> int
 111     (** Returns the number of running domains. *)
 112   val get_capabilities : [>`R] t -> xml
 113     (** Returns the hypervisor capabilities (as XML). *)
 114   val num_of_defined_domains : [>`R] t -> int
 115     (** Returns the number of inactive (shutdown) domains. *)
 116   val list_defined_domains : [>`R] t -> int -> string array
 117     (** [list_defined_domains conn max]
 118         returns the names of the inactive domains, up to
 119         a maximum of [max] entries.
 120         Call {!num_of_defined_domains} first to get a value for [max].
 121     *)
 122   val num_of_networks : [>`R] t -> int
 123     (** Returns the number of networks. *)
 124   val list_networks : [>`R] t -> int -> string array
 125     (** [list_networks conn max]
 126         returns the names of the networks, up to a maximum
 127         of [max] entries.
 128         Call {!num_of_networks} first to get a value for [max].
 129     *)
 130   val num_of_defined_networks : [>`R] t -> int
 131     (** Returns the number of inactive networks. *)
 132   val list_defined_networks : [>`R] t -> int -> string array
 133     (** [list_defined_networks conn max]
 134         returns the names of the inactive networks, up to a maximum
 135         of [max] entries.
 136         Call {!num_of_defined_networks} first to get a value for [max].
 137     *)
 138
 139     (* The name of this function is inconsistent, but the inconsistency
 140      * is really in libvirt itself.
 141      *)
 142   val get_node_info : [>`R] t -> node_info
 143     (** Return information about the physical server. *)
 144
 145   val node_get_free_memory : [> `R] t -> int64
 146     (**
 147        [node_get_free_memory conn]
 148        returns the amount of free memory (not allocated to any guest)
 149        in the machine.
 150     *)
 151
 152   val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
 153     (**
 154        [node_get_cells_free_memory conn start max]
 155        returns the amount of free memory on each NUMA cell in kilobytes.
 156        [start] is the first cell for which we return free memory.
 157        [max] is the maximum number of cells for which we return free memory.
 158        Returns an array of up to [max] entries in length.
 159     *)
 160
 161   val maxcpus_of_node_info : node_info -> int
 162     (** Calculate the total number of CPUs supported (but not necessarily
 163         active) in the host.
 164     *)
 165
 166   val cpumaplen : int -> int
 167     (** Calculate the length (in bytes) required to store the complete
 168         CPU map between a single virtual and all physical CPUs of a domain.
 169     *)
 170
 171   val use_cpu : string -> int -> unit
 172     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 173   val unuse_cpu : string -> int -> unit
 174     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 175   val cpu_usable : string -> int -> int -> int -> bool
 176     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 177         [cpu] is usable by [vcpu]. *)
 178
 179   external const : [>`R] t -> ro t = "%identity"
 180     (** [const conn] turns a read/write connection into a read-only
 181         connection.  Note that the opposite operation is impossible.
 182       *)
 183 end
 184   (** Module dealing with connections.  [Connect.t] is the
 185       connection object.
 186   *)
 187
 188 module Domain :
 189 sig
 190   type 'rw t
 191     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 192         read-write handles have type [rw Domain.t].
 193     *)
 194
 195   type state =
 196     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 197     | InfoShutdown | InfoShutoff | InfoCrashed
 198
 199   type info = {
 200     state : state;                      (** running state *)
 201     max_mem : int64;                    (** maximum memory in kilobytes *)
 202     memory : int64;                     (** memory used in kilobytes *)
 203     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 204     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 205   }
 206
 207   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 208
 209   type vcpu_info = {
 210     number : int;                       (** virtual CPU number *)
 211     vcpu_state : vcpu_state;            (** state *)
 212     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 213     cpu : int;                          (** real CPU number, -1 if offline *)
 214   }
 215
 216   type sched_param = string * sched_param_value
 217   and sched_param_value =
 218     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 219     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 220     | SchedFieldFloat of float | SchedFieldBool of bool
 221
 222   type migrate_flag = Live
 223
 224   type block_stats = {
 225     rd_req : int64;
 226     rd_bytes : int64;
 227     wr_req : int64;
 228     wr_bytes : int64;
 229     errs : int64;
 230   }
 231
 232   type interface_stats = {
 233     rx_bytes : int64;
 234     rx_packets : int64;
 235     rx_errs : int64;
 236     rx_drop : int64;
 237     tx_bytes : int64;
 238     tx_packets : int64;
 239     tx_errs : int64;
 240     tx_drop : int64;
 241   }
 242
 243   val create_linux : [>`W] Connect.t -> xml -> rw t
 244     (** Create a new guest domain (not necessarily a Linux one)
 245         from the given XML.
 246     *)
 247   val lookup_by_id : 'a Connect.t -> int -> 'a t
 248     (** Lookup a domain by ID. *)
 249   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 250     (** Lookup a domain by UUID.  This uses the packed byte array UUID. *)
 251   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 252     (** Lookup a domain by (string) UUID. *)
 253   val lookup_by_name : 'a Connect.t -> string -> 'a t
 254     (** Lookup a domain by name. *)
 255   val destroy : [>`W] t -> unit
 256     (** Abruptly destroy a domain. *)
 257   val free : [>`R] t -> unit
 258     (** [free domain] frees the domain object in memory.
 259
 260         The domain object is automatically freed if it is garbage
 261         collected.  This function just forces it to be freed right
 262         away.
 263     *)
 264
 265   val suspend : [>`W] t -> unit
 266     (** Suspend a domain. *)
 267   val resume : [>`W] t -> unit
 268     (** Resume a domain. *)
 269   val save : [>`W] t -> filename -> unit
 270     (** Suspend a domain, then save it to the file. *)
 271   val restore : [>`W] Connect.t -> filename -> unit
 272     (** Restore a domain from a file. *)
 273   val core_dump : [>`W] t -> filename -> unit
 274     (** Force a domain to core dump to the named file. *)
 275   val shutdown : [>`W] t -> unit
 276     (** Shutdown a domain. *)
 277   val reboot : [>`W] t -> unit
 278     (** Reboot a domain. *)
 279   val get_name : [>`R] t -> string
 280     (** Get the domain name. *)
 281   val get_uuid : [>`R] t -> uuid
 282     (** Get the domain UUID (as a packed byte array). *)
 283   val get_uuid_string : [>`R] t -> string
 284     (** Get the domain UUID (as a printable string). *)
 285   val get_id : [>`R] t -> int
 286     (** [getid dom] returns the ID of the domain.
 287
 288         Do not call this on a defined but not running domain.  Those
 289         domains don't have IDs, and you'll get an error here.
 290     *)
 291
 292   val get_os_type : [>`R] t -> string
 293     (** Get the operating system type. *)
 294   val get_max_memory : [>`R] t -> int64
 295     (** Get the maximum memory allocation. *)
 296   val set_max_memory : [>`W] t -> int64 -> unit
 297     (** Set the maximum memory allocation. *)
 298   val set_memory : [>`W] t -> int64 -> unit
 299     (** Set the normal memory allocation. *)
 300   val get_info : [>`R] t -> info
 301     (** Get information about a domain. *)
 302   val get_xml_desc : [>`R] t -> xml
 303     (** Get the XML description of a domain. *)
 304   val get_scheduler_type : [>`R] t -> string * int
 305     (** Get the scheduler type. *)
 306   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 307     (** Get the array of scheduler parameters. *)
 308   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 309     (** Set the array of scheduler parameters. *)
 310   val define_xml : [>`W] Connect.t -> xml -> rw t
 311     (** Define a new domain (but don't start it up) from the XML. *)
 312   val undefine : [>`W] t -> unit
 313     (** Undefine a domain - removes its configuration. *)
 314   val create : [>`W] t -> unit
 315     (** Launch a defined (inactive) domain. *)
 316   val get_autostart : [>`R] t -> bool
 317     (** Get the autostart flag for a domain. *)
 318   val set_autostart : [>`W] t -> bool -> unit
 319     (** Set the autostart flag for a domain. *)
 320   val set_vcpus : [>`W] t -> int -> unit
 321     (** Change the number of vCPUs available to a domain. *)
 322   val pin_vcpu : [>`W] t -> int -> string -> unit
 323     (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
 324         CPUs.  See the libvirt documentation for details of the
 325         layout of the bitmap. *)
 326   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 327     (** [get_vcpus dom maxinfo maplen] returns the pinning information
 328         for a domain.  See the libvirt documentation for details
 329         of the array and bitmap returned from this function.
 330     *)
 331   val get_max_vcpus : [>`R] t -> int
 332     (** Returns the maximum number of vCPUs supported for this domain. *)
 333   val attach_device : [>`W] t -> xml -> unit
 334     (** Attach a device (described by the device XML) to a domain. *)
 335   val detach_device : [>`W] t -> xml -> unit
 336     (** Detach a device (described by the device XML) from a domain. *)
 337
 338   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 339     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 340     (** [migrate dom dconn flags ()] migrates a domain to a
 341         destination host described by [dconn].
 342
 343         The optional flag [?dname] is used to rename the domain.
 344
 345         The optional flag [?uri] is used to route the migration.
 346
 347         The optional flag [?bandwidth] is used to limit the bandwidth
 348         used for migration (in Mbps). *)
 349
 350   val block_stats : [>`R] t -> string -> block_stats
 351     (** Returns block device stats. *)
 352   val interface_stats : [>`R] t -> string -> interface_stats
 353     (** Returns network interface stats. *)
 354
 355   external const : [>`R] t -> ro t = "%identity"
 356     (** [const dom] turns a read/write domain handle into a read-only
 357         domain handle.  Note that the opposite operation is impossible.
 358       *)
 359 end
 360   (** Module dealing with domains.  [Domain.t] is the
 361       domain object.
 362   *)
 363
 364 module Network :
 365 sig
 366   type 'rw t
 367     (** Network handle.  Read-only handles have type [ro Network.t] and
 368         read-write handles have type [rw Network.t].
 369     *)
 370
 371   val lookup_by_name : 'a Connect.t -> string -> 'a t
 372     (** Lookup a network by name. *)
 373   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 374     (** Lookup a network by (packed) UUID. *)
 375   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 376     (** Lookup a network by UUID string. *)
 377   val create_xml : [>`W] Connect.t -> xml -> rw t
 378     (** Create a network. *)
 379   val define_xml : [>`W] Connect.t -> xml -> rw t
 380     (** Define but don't activate a network. *)
 381   val undefine : [>`W] t -> unit
 382     (** Undefine configuration of a network. *)
 383   val create : [>`W] t -> unit
 384     (** Start up a defined (inactive) network. *)
 385   val destroy : [>`W] t -> unit
 386     (** Destroy a network. *)
 387   val free : [>`R] t -> unit
 388     (** [free network] frees the network object in memory.
 389
 390         The network object is automatically freed if it is garbage
 391         collected.  This function just forces it to be freed right
 392         away.
 393     *)
 394
 395   val get_name : [>`R] t -> string
 396     (** Get network name. *)
 397   val get_uuid : [>`R] t -> uuid
 398     (** Get network packed UUID. *)
 399   val get_uuid_string : [>`R] t -> string
 400     (** Get network UUID as a printable string. *)
 401   val get_xml_desc : [>`R] t -> xml
 402     (** Get XML description of a network. *)
 403   val get_bridge_name : [>`R] t -> string
 404     (** Get bridge device name of a network. *)
 405   val get_autostart : [>`R] t -> bool
 406     (** Get the autostart flag for a network. *)
 407   val set_autostart : [>`W] t -> bool -> unit
 408     (** Set the autostart flag for a network. *)
 409
 410   external const : [>`R] t -> ro t = "%identity"
 411     (** [const network] turns a read/write network handle into a read-only
 412         network handle.  Note that the opposite operation is impossible.
 413       *)
 414 end
 415   (** Module dealing with networks.  [Network.t] is the
 416       network object.
 417   *)
 418
 419 module Virterror :
 420 sig
 421   type code =
 422     | VIR_ERR_OK
 423     | VIR_ERR_INTERNAL_ERROR
 424     | VIR_ERR_NO_MEMORY
 425     | VIR_ERR_NO_SUPPORT
 426     | VIR_ERR_UNKNOWN_HOST
 427     | VIR_ERR_NO_CONNECT
 428     | VIR_ERR_INVALID_CONN
 429     | VIR_ERR_INVALID_DOMAIN
 430     | VIR_ERR_INVALID_ARG
 431     | VIR_ERR_OPERATION_FAILED
 432     | VIR_ERR_GET_FAILED
 433     | VIR_ERR_POST_FAILED
 434     | VIR_ERR_HTTP_ERROR
 435     | VIR_ERR_SEXPR_SERIAL
 436     | VIR_ERR_NO_XEN
 437     | VIR_ERR_XEN_CALL
 438     | VIR_ERR_OS_TYPE
 439     | VIR_ERR_NO_KERNEL
 440     | VIR_ERR_NO_ROOT
 441     | VIR_ERR_NO_SOURCE
 442     | VIR_ERR_NO_TARGET
 443     | VIR_ERR_NO_NAME
 444     | VIR_ERR_NO_OS
 445     | VIR_ERR_NO_DEVICE
 446     | VIR_ERR_NO_XENSTORE
 447     | VIR_ERR_DRIVER_FULL
 448     | VIR_ERR_CALL_FAILED
 449     | VIR_ERR_XML_ERROR
 450     | VIR_ERR_DOM_EXIST
 451     | VIR_ERR_OPERATION_DENIED
 452     | VIR_ERR_OPEN_FAILED
 453     | VIR_ERR_READ_FAILED
 454     | VIR_ERR_PARSE_FAILED
 455     | VIR_ERR_CONF_SYNTAX
 456     | VIR_ERR_WRITE_FAILED
 457     | VIR_ERR_XML_DETAIL
 458     | VIR_ERR_INVALID_NETWORK
 459     | VIR_ERR_NETWORK_EXIST
 460     | VIR_ERR_SYSTEM_ERROR
 461     | VIR_ERR_RPC
 462     | VIR_ERR_GNUTLS_ERROR
 463     | VIR_WAR_NO_NETWORK
 464     | VIR_ERR_NO_DOMAIN
 465     | VIR_ERR_NO_NETWORK
 466         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
 467
 468   val string_of_code : code -> string
 469
 470   type level =
 471     | VIR_ERR_NONE
 472     | VIR_ERR_WARNING
 473     | VIR_ERR_ERROR
 474         (** No error, a warning or an error. *)
 475
 476   val string_of_level : level -> string
 477
 478   type domain =
 479     | VIR_FROM_NONE
 480     | VIR_FROM_XEN
 481     | VIR_FROM_XEND
 482     | VIR_FROM_XENSTORE
 483     | VIR_FROM_SEXPR
 484     | VIR_FROM_XML
 485     | VIR_FROM_DOM
 486     | VIR_FROM_RPC
 487     | VIR_FROM_PROXY
 488     | VIR_FROM_CONF
 489     | VIR_FROM_QEMU
 490     | VIR_FROM_NET
 491     | VIR_FROM_TEST
 492     | VIR_FROM_REMOTE
 493     | VIR_FROM_OPENVZ
 494         (** Subsystem / driver which produced the error. *)
 495
 496   val string_of_domain : domain -> string
 497
 498   type t = {
 499     code : code;                        (** Error code. *)
 500     domain : domain;                    (** Origin of the error. *)
 501     message : string option;            (** Human-readable message. *)
 502     level : level;                      (** Error or warning. *)
 503     conn : ro Connect.t option;         (** Associated connection. *)
 504     dom : ro Domain.t option;           (** Associated domain. *)
 505     str1 : string option;               (** Informational string. *)
 506     str2 : string option;               (** Informational string. *)
 507     str3 : string option;               (** Informational string. *)
 508     int1 : int32;                       (** Informational integer. *)
 509     int2 : int32;                       (** Informational integer. *)
 510     net : ro Network.t option;          (** Associated network. *)
 511   }
 512     (** An error object. *)
 513
 514   val to_string : t -> string
 515     (** Turn the exception into a printable string. *)
 516
 517   val get_last_error : unit -> t option
 518   val get_last_conn_error : [>`R] Connect.t -> t option
 519     (** Get the last error at a global or connection level.
 520
 521         Normally you do not need to use these functions because
 522         the library automatically turns errors into exceptions.
 523     *)
 524
 525   val reset_last_error : unit -> unit
 526   val reset_last_conn_error : [>`R] Connect.t -> unit
 527     (** Reset the error at a global or connection level.
 528
 529         Normally you do not need to use these functions.
 530     *)
 531
 532   val no_error : unit -> t
 533     (** Creates an empty error message.
 534
 535         Normally you do not need to use this function.
 536     *)
 537 end
 538   (** Module dealing with errors. *)
 539
 540 exception Virterror of Virterror.t
 541 (** This exception can be raised by any library function that detects
 542     an error.  To get a printable error message, call
 543     {!Virterror.to_string} on the content of this exception.
 544
 545     Note that functions may also raise
 546     [Invalid_argument "virFoo not supported"]
 547     (where virFoo is the libvirt function name) if a function is
 548     not supported at either compile or runtime.  This applies to
 549     any libvirt function added after version 0.2.1.
 550     See also [http://libvirt.org/hvsupport.html]
 551 *)
 552