1 (** OCaml bindings for libvirt.
2 (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc.
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.
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.
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
21 (** This is a "raw" UUID, ie. a packed string of bytes. *)
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.
28 type filename = string
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.
35 [get_version ~driver ()] returns the library version in the first
36 part of the tuple, and the version of the driver called [driver]
39 The version numbers are encoded as
40 1,000,000 * major + 1,000 * minor + release.
44 (** Length of packed UUIDs. *)
46 val uuid_string_length : int
47 (** Length of UUID strings. *)
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
59 (** Connection. Read-only connections have type [ro Connect.t] and
60 read-write connections have type [rw Connect.t].
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 *)
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].
78 [connect ()] connects to the default hypervisor.
80 [connect_readonly] is the same but connects in read-only mode.
83 val close : [>`R] t -> unit
84 (** [close conn] closes and frees the connection object in memory.
86 The connection is automatically closed if it is garbage
87 collected. This function just forces it to be closed
91 val get_type : [>`R] t -> string
92 (** Returns the name of the driver (hypervisor). *)
94 val get_version : [>`R] t -> int
95 (** Returns the driver version
96 [major * 1_000_000 + minor * 1000 + release]
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].
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].
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
128 Call {!num_of_networks} first to get a value for [max].
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
136 Call {!num_of_defined_networks} first to get a value for [max].
139 (* The name of this function is inconsistent, but the inconsistency
140 * is really in libvirt itself.
142 val get_node_info : [>`R] t -> node_info
143 (** Return information about the physical server. *)
145 val node_get_free_memory : [> `R] t -> int64
147 [node_get_free_memory conn]
148 returns the amount of free memory (not allocated to any guest)
152 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
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.
161 val maxcpus_of_node_info : node_info -> int
162 (** Calculate the total number of CPUs supported (but not necessarily
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.
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]. *)
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.
184 (** Module dealing with connections. [Connect.t] is the
191 (** Domain handle. Read-only handles have type [ro Domain.t] and
192 read-write handles have type [rw Domain.t].
196 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
197 | InfoShutdown | InfoShutoff | InfoCrashed
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 *)
207 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
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 *)
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
222 type migrate_flag = Live
232 type interface_stats = {
243 val create_linux : [>`W] Connect.t -> xml -> rw t
244 (** Create a new guest domain (not necessarily a Linux one)
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.
260 The domain object is automatically freed if it is garbage
261 collected. This function just forces it to be freed right
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.
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.
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.
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. *)
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].
343 The optional flag [?dname] is used to rename the domain.
345 The optional flag [?uri] is used to route the migration.
347 The optional flag [?bandwidth] is used to limit the bandwidth
348 used for migration (in Mbps). *)
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. *)
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.
360 (** Module dealing with domains. [Domain.t] is the
367 (** Network handle. Read-only handles have type [ro Network.t] and
368 read-write handles have type [rw Network.t].
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.
390 The network object is automatically freed if it is garbage
391 collected. This function just forces it to be freed right
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. *)
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.
415 (** Module dealing with networks. [Network.t] is the
423 | VIR_ERR_INTERNAL_ERROR
426 | VIR_ERR_UNKNOWN_HOST
428 | VIR_ERR_INVALID_CONN
429 | VIR_ERR_INVALID_DOMAIN
430 | VIR_ERR_INVALID_ARG
431 | VIR_ERR_OPERATION_FAILED
433 | VIR_ERR_POST_FAILED
435 | VIR_ERR_SEXPR_SERIAL
446 | VIR_ERR_NO_XENSTORE
447 | VIR_ERR_DRIVER_FULL
448 | VIR_ERR_CALL_FAILED
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
458 | VIR_ERR_INVALID_NETWORK
459 | VIR_ERR_NETWORK_EXIST
460 | VIR_ERR_SYSTEM_ERROR
462 | VIR_ERR_GNUTLS_ERROR
466 | VIR_ERR_INVALID_MAC
467 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c:MAX_VIR_* *)
468 | VIR_ERR_UNKNOWN of int
469 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
471 val string_of_code : code -> string
490 | VIR_FROM_STATS_LINUX
491 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
492 | VIR_FROM_UNKNOWN of int
493 (** Subsystem / driver which produced the error. *)
495 val string_of_domain : domain -> string
501 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
502 | VIR_ERR_UNKNOWN_LEVEL of int
503 (** No error, a warning or an error. *)
505 val string_of_level : level -> string
508 code : code; (** Error code. *)
509 domain : domain; (** Origin of the error. *)
510 message : string option; (** Human-readable message. *)
511 level : level; (** Error or warning. *)
512 conn : ro Connect.t option; (** Associated connection. *)
513 dom : ro Domain.t option; (** Associated domain. *)
514 str1 : string option; (** Informational string. *)
515 str2 : string option; (** Informational string. *)
516 str3 : string option; (** Informational string. *)
517 int1 : int32; (** Informational integer. *)
518 int2 : int32; (** Informational integer. *)
519 net : ro Network.t option; (** Associated network. *)
521 (** An error object. *)
523 val to_string : t -> string
524 (** Turn the exception into a printable string. *)
526 val get_last_error : unit -> t option
527 val get_last_conn_error : [>`R] Connect.t -> t option
528 (** Get the last error at a global or connection level.
530 Normally you do not need to use these functions because
531 the library automatically turns errors into exceptions.
534 val reset_last_error : unit -> unit
535 val reset_last_conn_error : [>`R] Connect.t -> unit
536 (** Reset the error at a global or connection level.
538 Normally you do not need to use these functions.
541 val no_error : unit -> t
542 (** Creates an empty error message.
544 Normally you do not need to use this function.
547 (** Module dealing with errors. *)
549 exception Virterror of Virterror.t
550 (** This exception can be raised by any library function that detects
551 an error. To get a printable error message, call
552 {!Virterror.to_string} on the content of this exception.
555 exception Not_supported of string
558 [Not_supported "virFoo"]
559 (where [virFoo] is the libvirt function name) if a function is
560 not supported at either compile or run time. This applies to
561 any libvirt function added after version 0.2.1.
563 See also [http://libvirt.org/hvsupport.html]