1 (** OCaml bindings for libvirt. *)
2 (* (C) Copyright 2007-2015 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,
9 with the OCaml linking exception described in ../COPYING.LIB.
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.
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
22 {2 Introduction and examples}
24 This is a set of bindings for writing OCaml programs to
25 manage virtual machines through {{:http://libvirt.org/}libvirt}.
27 {3 Using libvirt interactively}
29 Using the interactive toplevel:
33 Objective Caml version 3.10.0
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}
49 {3 Compiling libvirt programs}
51 This command compiles a program to native code:
54 ocamlopt -I +libvirt mllibvirt.cmxa list_domains.ml -o list_domains
57 {3 Example: Connect to the hypervisor}
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:
65 module C = Libvirt.Connect
66 module D = Libvirt.Domain
67 module N = Libvirt.Network
70 To get a connection handle, assuming a Xen hypervisor:
74 let conn = C.connect_readonly ~name ()
77 {3 Example: List running domains}
82 let domains = D.get_domains conn [D.ListActive] in
85 printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
89 {3 Example: List inactive domains}
92 let domains = D.get_domains conn [D.ListInactive] in
95 printf "inactive %s\n%!" (D.get_name dom)
99 {3 Example: Print node info}
102 let node_info = C.get_node_info conn in
103 printf "model = %s\n" node_info.C.model;
104 printf "memory = %Ld K\n" node_info.C.memory;
105 printf "cpus = %d\n" node_info.C.cpus;
106 printf "mhz = %d\n" node_info.C.mhz;
107 printf "nodes = %d\n" node_info.C.nodes;
108 printf "sockets = %d\n" node_info.C.sockets;
109 printf "cores = %d\n" node_info.C.cores;
110 printf "threads = %d\n%!" node_info.C.threads;
112 let hostname = C.get_hostname conn in
113 printf "hostname = %s\n%!" hostname;
115 let uri = C.get_uri conn in
116 printf "uri = %s\n%!" uri
122 (** {2 Programming issues}
124 {3 General safety issues}
126 Memory allocation / automatic garbage collection of all libvirt
127 objects should be completely safe. If you find any safety issues
128 or if your pure OCaml program ever segfaults, please contact the author.
130 You can force a libvirt object to be freed early by calling
131 the [close] function on the object. This shouldn't affect
132 the safety of garbage collection and should only be used when
133 you want to explicitly free memory. Note that explicitly
134 closing a connection object does nothing if there are still
135 unclosed domain or network objects referencing it.
137 Note that even though you hold open (eg) a domain object, that
138 doesn't mean that the domain (virtual machine) actually exists.
139 The domain could have been shut down or deleted by another user.
140 Thus domain objects can raise odd exceptions at any time.
141 This is just the nature of virtualisation.
143 {3 Backwards and forwards compatibility}
145 OCaml-libvirt requires libvirt version 1.0.2 or later. Future
146 releases of OCaml-libvirt will use newer features of libvirt
147 and therefore will require later versions of libvirt. It is always
148 possible to dynamically link your application against a newer
149 libvirt than OCaml-libvirt was originally compiled against.
151 {3 Get list of domains and domain infos}
153 This is a very common operation, and libvirt supports various
154 different methods to do it. We have hidden the complexity in a
155 flexible {!Libvirt.Domain.get_domains} and
156 {!Libvirt.Domain.get_domains_and_infos} calls which is easy to use and
157 automatically chooses the most efficient method depending on the
158 version of libvirt in use.
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
169 (Note that multithreaded code is not well tested. If you find
170 bugs please report them.)
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.
183 (** This is a "raw" UUID, ie. a packed string of bytes. *)
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.
190 type filename = string
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.
197 [get_version ~driver ()] returns the library version in the first
198 part of the tuple, and the version of the driver called [driver]
201 The version numbers are encoded as
202 1,000,000 * major + 1,000 * minor + release.
205 val uuid_length : int
206 (** Length of packed UUIDs. *)
208 val uuid_string_length : int
209 (** Length of UUID strings. *)
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.
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.
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.
227 If you want to handle both read-write and read-only
228 connections at runtime, use a variant similar to this:
232 | Read_only of Libvirt.ro Libvirt.Connect.t
233 | Read_write of Libvirt.rw Libvirt.Connect.t
237 (** {3 Forward definitions}
239 These definitions are placed here to avoid the need to
240 use recursive module dependencies.
243 (** {3 Connections} *)
248 (** Connection. Read-only connections have type [ro Connect.t] and
249 read-write connections have type [rw Connect.t].
253 model : string; (** CPU model *)
254 memory : int64; (** memory size in kilobytes *)
255 cpus : int; (** number of active CPUs *)
256 mhz : int; (** expected CPU frequency *)
257 nodes : int; (** number of NUMA nodes (1 = UMA) *)
258 sockets : int; (** number of CPU sockets per node *)
259 cores : int; (** number of cores per socket *)
260 threads : int; (** number of threads per core *)
263 val connect : ?name:string -> unit -> rw t
264 val connect_readonly : ?name:string -> unit -> ro t
265 (** [connect ~name ()] connects to the hypervisor with URI [name].
267 [connect ()] connects to the default hypervisor.
269 [connect_readonly] is the same but connects in read-only mode.
272 val close : [>`R] t -> unit
273 (** [close conn] closes and frees the connection object in memory.
275 The connection is automatically closed if it is garbage
276 collected. This function just forces it to be closed
277 and freed right away.
280 val get_type : [>`R] t -> string
281 (** Returns the name of the driver (hypervisor). *)
283 val get_version : [>`R] t -> int
284 (** Returns the driver version
285 [major * 1_000_000 + minor * 1000 + release]
287 val get_hostname : [>`R] t -> string
288 (** Returns the hostname of the physical server. *)
289 val get_uri : [>`R] t -> string
290 (** Returns the canonical connection URI. *)
291 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
292 (** Returns the maximum number of virtual CPUs
293 supported by a guest VM of a particular type. *)
294 val list_domains : [>`R] t -> int -> int array
295 (** [list_domains conn max] returns the running domain IDs,
296 up to a maximum of [max] entries.
298 Call {!num_of_domains} first to get a value for [max].
301 {!Libvirt.Domain.get_domains},
302 {!Libvirt.Domain.get_domains_and_infos}.
304 val num_of_domains : [>`R] t -> int
305 (** Returns the number of running domains. *)
306 val get_capabilities : [>`R] t -> xml
307 (** Returns the hypervisor capabilities (as XML). *)
308 val num_of_defined_domains : [>`R] t -> int
309 (** Returns the number of inactive (shutdown) domains. *)
310 val list_defined_domains : [>`R] t -> int -> string array
311 (** [list_defined_domains conn max]
312 returns the names of the inactive domains, up to
313 a maximum of [max] entries.
315 Call {!num_of_defined_domains} first to get a value for [max].
318 {!Libvirt.Domain.get_domains},
319 {!Libvirt.Domain.get_domains_and_infos}.
321 val num_of_networks : [>`R] t -> int
322 (** Returns the number of networks. *)
323 val list_networks : [>`R] t -> int -> string array
324 (** [list_networks conn max]
325 returns the names of the networks, up to a maximum
327 Call {!num_of_networks} first to get a value for [max].
329 val num_of_defined_networks : [>`R] t -> int
330 (** Returns the number of inactive networks. *)
331 val list_defined_networks : [>`R] t -> int -> string array
332 (** [list_defined_networks conn max]
333 returns the names of the inactive networks, up to a maximum
335 Call {!num_of_defined_networks} first to get a value for [max].
338 val num_of_pools : [>`R] t -> int
339 (** Returns the number of storage pools. *)
340 val list_pools : [>`R] t -> int -> string array
341 (** Return list of storage pools. *)
342 val num_of_defined_pools : [>`R] t -> int
343 (** Returns the number of storage pools. *)
344 val list_defined_pools : [>`R] t -> int -> string array
345 (** Return list of storage pools. *)
347 (* The name of this function is inconsistent, but the inconsistency
348 * is really in libvirt itself.
350 val get_node_info : [>`R] t -> node_info
351 (** Return information about the physical server. *)
353 val node_get_free_memory : [> `R] t -> int64
355 [node_get_free_memory conn]
356 returns the amount of free memory (not allocated to any guest)
360 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
362 [node_get_cells_free_memory conn start max]
363 returns the amount of free memory on each NUMA cell in kilobytes.
364 [start] is the first cell for which we return free memory.
365 [max] is the maximum number of cells for which we return free memory.
366 Returns an array of up to [max] entries in length.
369 val maxcpus_of_node_info : node_info -> int
370 (** Calculate the total number of CPUs supported (but not necessarily
374 val cpumaplen : int -> int
375 (** Calculate the length (in bytes) required to store the complete
376 CPU map between a single virtual and all physical CPUs of a domain.
379 val use_cpu : string -> int -> unit
380 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
381 val unuse_cpu : string -> int -> unit
382 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
383 val cpu_usable : string -> int -> int -> int -> bool
384 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
385 [cpu] is usable by [vcpu]. *)
387 val set_keep_alive : [>`R] t -> int -> int -> unit
388 (** [set_keep_alive conn interval count] starts sending keepalive
389 messages after [interval] seconds of inactivity and consider the
390 connection to be broken when no response is received after [count]
392 Note: the client has to implement and run an event loop to
393 be able to use keep-alive messages. *)
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.
400 (** Module dealing with connections. [Connect.t] is the
401 connection object. *)
408 (** Domain handle. Read-only handles have type [ro Domain.t] and
409 read-write handles have type [rw Domain.t].
413 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
414 | InfoShutdown | InfoShutoff | InfoCrashed
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 *)
424 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
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 *)
433 type domain_create_flag =
434 | START_PAUSED (** Launch guest in paused state *)
435 | START_AUTODESTROY (** Automatically kill guest on close *)
436 | START_BYPASS_CACHE (** Avoid filesystem cache pollution *)
437 | START_FORCE_BOOT (** Discard any managed save *)
438 | START_VALIDATE (** Validate XML against schema *)
440 type sched_param = string * sched_param_value
441 and sched_param_value =
442 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
443 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
444 | SchedFieldFloat of float | SchedFieldBool of bool
446 type typed_param = string * typed_param_value
447 and typed_param_value =
448 | TypedFieldInt32 of int32 | TypedFieldUInt32 of int32
449 | TypedFieldInt64 of int64 | TypedFieldUInt64 of int64
450 | TypedFieldFloat of float | TypedFieldBool of bool
451 | TypedFieldString of string
453 type migrate_flag = Live
455 type memory_flag = Virtual
470 type interface_stats = {
481 type get_all_domain_stats_flag =
482 | GetAllDomainsStatsActive
483 | GetAllDomainsStatsInactive
484 | GetAllDomainsStatsOther
485 | GetAllDomainsStatsPaused
486 | GetAllDomainsStatsPersistent
487 | GetAllDomainsStatsRunning
488 | GetAllDomainsStatsShutoff
489 | GetAllDomainsStatsTransient
490 | GetAllDomainsStatsBacking
491 | GetAllDomainsStatsEnforceStats
494 | StatsState | StatsCpuTotal | StatsBalloon | StatsVcpu
495 | StatsInterface | StatsBlock | StatsPerf
497 type 'a domain_stats_record = {
499 params : typed_param array;
502 val max_peek : [>`R] t -> int
503 (** Maximum size supported by the {!block_peek} and {!memory_peek}
504 functions. If you want to peek more than this then you must
505 break your request into chunks. *)
507 val create_linux : [>`W] Connect.t -> xml -> rw t
508 (** Create a new guest domain (not necessarily a Linux one)
509 from the given XML. Use {!create_xml} instead.
511 val create_xml : [>`W] Connect.t -> xml -> domain_create_flag list -> rw t
512 (** Create a new guest domain from the given XML. *)
513 val lookup_by_id : 'a Connect.t -> int -> 'a t
514 (** Lookup a domain by ID. *)
515 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
516 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
517 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
518 (** Lookup a domain by (string) UUID. *)
519 val lookup_by_name : 'a Connect.t -> string -> 'a t
520 (** Lookup a domain by name. *)
521 val destroy : [>`W] t -> unit
522 (** Abruptly destroy a domain. *)
523 val free : [>`R] t -> unit
524 (** [free domain] frees the domain object in memory.
526 The domain object is automatically freed if it is garbage
527 collected. This function just forces it to be freed right
531 val suspend : [>`W] t -> unit
532 (** Suspend a domain. *)
533 val resume : [>`W] t -> unit
534 (** Resume a domain. *)
535 val save : [>`W] t -> filename -> unit
536 (** Suspend a domain, then save it to the file. *)
537 val restore : [>`W] Connect.t -> filename -> unit
538 (** Restore a domain from a file. *)
539 val core_dump : [>`W] t -> filename -> unit
540 (** Force a domain to core dump to the named file. *)
541 val shutdown : [>`W] t -> unit
542 (** Shutdown a domain. *)
543 val reboot : [>`W] t -> unit
544 (** Reboot a domain. *)
545 val get_name : [>`R] t -> string
546 (** Get the domain name. *)
547 val get_uuid : [>`R] t -> uuid
548 (** Get the domain UUID (as a packed byte array). *)
549 val get_uuid_string : [>`R] t -> string
550 (** Get the domain UUID (as a printable string). *)
551 val get_id : [>`R] t -> int
552 (** [get_id dom] returns the ID of the domain. In most cases
553 this returns [-1] if the domain is not running. *)
554 val get_os_type : [>`R] t -> string
555 (** Get the operating system type. *)
556 val get_max_memory : [>`R] t -> int64
557 (** Get the maximum memory allocation. *)
558 val set_max_memory : [>`W] t -> int64 -> unit
559 (** Set the maximum memory allocation. *)
560 val set_memory : [>`W] t -> int64 -> unit
561 (** Set the normal memory allocation. *)
562 val get_info : [>`R] t -> info
563 (** Get information about a domain. *)
564 val get_xml_desc : [>`R] t -> xml
565 (** Get the XML description of a domain. *)
566 val get_scheduler_type : [>`R] t -> string * int
567 (** Get the scheduler type. *)
568 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
569 (** Get the array of scheduler parameters. *)
570 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
571 (** Set the array of scheduler parameters. *)
572 val define_xml : [>`W] Connect.t -> xml -> rw t
573 (** Define a new domain (but don't start it up) from the XML. *)
574 val undefine : [>`W] t -> unit
575 (** Undefine a domain - removes its configuration. *)
576 val create : [>`W] t -> unit
577 (** Launch a defined (inactive) domain. *)
578 val get_autostart : [>`R] t -> bool
579 (** Get the autostart flag for a domain. *)
580 val set_autostart : [>`W] t -> bool -> unit
581 (** Set the autostart flag for a domain. *)
582 val set_vcpus : [>`W] t -> int -> unit
583 (** Change the number of vCPUs available to a domain. *)
584 val pin_vcpu : [>`W] t -> int -> string -> unit
585 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
586 CPUs. See the libvirt documentation for details of the
587 layout of the bitmap. *)
588 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
589 (** [get_vcpus dom maxinfo maplen] returns the pinning information
590 for a domain. See the libvirt documentation for details
591 of the array and bitmap returned from this function.
593 val get_cpu_stats : [>`R] t -> typed_param list array
594 (** [get_pcpu_stats dom] returns the physical CPU stats
595 for a domain. See the libvirt documentation for details.
597 val get_max_vcpus : [>`R] t -> int
598 (** Returns the maximum number of vCPUs supported for this domain. *)
599 val attach_device : [>`W] t -> xml -> unit
600 (** Attach a device (described by the device XML) to a domain. *)
601 val detach_device : [>`W] t -> xml -> unit
602 (** Detach a device (described by the device XML) from a domain. *)
604 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
605 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
606 (** [migrate dom dconn flags ()] migrates a domain to a
607 destination host described by [dconn].
609 The optional flag [?dname] is used to rename the domain.
611 The optional flag [?uri] is used to route the migration.
613 The optional flag [?bandwidth] is used to limit the bandwidth
614 used for migration (in Mbps). *)
616 val block_stats : [>`R] t -> string -> block_stats
617 (** Returns block device stats. *)
618 val interface_stats : [>`R] t -> string -> interface_stats
619 (** Returns network interface stats. *)
621 val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
622 (** [block_peek dom path offset size buf boff] reads [size] bytes at
623 [offset] in the domain's [path] block device.
625 If successful then the data is written into [buf] starting
626 at offset [boff], for [size] bytes.
628 See also {!max_peek}. *)
629 val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
630 string -> int -> unit
631 (** [memory_peek dom Virtual offset size] reads [size] bytes
632 at [offset] in the domain's virtual memory.
634 If successful then the data is written into [buf] starting
635 at offset [boff], for [size] bytes.
637 See also {!max_peek}. *)
639 external get_all_domain_stats : 'a Connect.t -> stats_type list -> get_all_domain_stats_flag list -> 'a domain_stats_record array = "ocaml_libvirt_domain_get_all_domain_stats"
640 (** [get_all_domain_stats conn stats flags] allows you to read
641 all stats across multiple/all domains in a single call.
643 See the libvirt documentation for
644 [virConnectGetAllDomainStats]. *)
646 external const : [>`R] t -> ro t = "%identity"
647 (** [const dom] turns a read/write domain handle into a read-only
648 domain handle. Note that the opposite operation is impossible.
651 val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
652 (** Get the active and/or inactive domains using the most
653 efficient method available.
656 {!get_domains_and_infos},
657 {!Connect.list_domains},
658 {!Connect.list_defined_domains}.
661 val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
663 (** This gets the active and/or inactive domains and the
664 domain info for each one using the most efficient
669 {!Connect.list_domains},
670 {!Connect.list_defined_domains},
675 (** Module dealing with domains. [Domain.t] is the
683 | `Added (** Newly created config file *)
684 | `Updated (** Changed config file *)
688 val to_string: t -> string
691 module Undefined : sig
693 | `Removed (** Deleted the config file *)
697 val to_string: t -> string
702 | `Booted (** Normal startup from boot *)
703 | `Migrated (** Incoming migration from another host *)
704 | `Restored (** Restored from a state file *)
705 | `FromSnapshot (** Restored from snapshot *)
706 | `Wakeup (** Started due to wakeup event *)
710 val to_string: t -> string
713 module Suspended : sig
715 | `Paused (** Normal suspend due to admin pause *)
716 | `Migrated (** Suspended for offline migration *)
717 | `IOError (** Suspended due to a disk I/O error *)
718 | `Watchdog (** Suspended due to a watchdog firing *)
719 | `Restored (** Restored from paused state file *)
720 | `FromSnapshot (** Restored from paused snapshot *)
721 | `APIError (** suspended after failure during libvirt API call *)
725 val to_string: t -> string
730 | `Unpaused (** Normal resume due to admin unpause *)
731 | `Migrated (** Resumed for completion of migration *)
732 | `FromSnapshot (** Resumed from snapshot *)
736 val to_string: t -> string
741 | `Shutdown (** Normal shutdown *)
742 | `Destroyed (** Forced poweroff from host *)
743 | `Crashed (** Guest crashed *)
744 | `Migrated (** Migrated off to another host *)
745 | `Saved (** Saved to a state file *)
746 | `Failed (** Host emulator/mgmt failed *)
747 | `FromSnapshot (** offline snapshot loaded *)
751 val to_string: t -> string
754 module PM_suspended : sig
756 | `Memory (** Guest was PM suspended to memory *)
757 | `Disk (** Guest was PM suspended to disk *)
761 val to_string: t -> string
764 module Lifecycle : sig
766 | `Defined of Defined.t
767 | `Undefined of Undefined.t
768 | `Started of Started.t
769 | `Suspended of Suspended.t
770 | `Resumed of Resumed.t
771 | `Stopped of Stopped.t
772 | `Shutdown (* no detail defined yet *)
773 | `PMSuspended of PM_suspended.t
777 val to_string: t -> string
783 val to_string: t -> string
786 module Rtc_change : sig
789 val to_string: t -> string
792 module Watchdog : sig
794 | `None (** No action, watchdog ignored *)
795 | `Pause (** Guest CPUs are paused *)
796 | `Reset (** Guest CPUs are reset *)
797 | `Poweroff (** Guest is forcably powered off *)
798 | `Shutdown (** Guest is requested to gracefully shutdown *)
799 | `Debug (** No action, a debug message logged *)
800 | `Unknown of int (** newer libvirt *)
803 val to_string: t -> string
806 module Io_error : sig
807 (** Represents both IOError and IOErrorReason *)
809 | `None (** No action, IO error ignored *)
810 | `Pause (** Guest CPUs are paused *)
811 | `Report (** IO error reported to guest OS *)
812 | `Unknown of int (** newer libvirt *)
816 src_path: string option; (** The host file on which the I/O error occurred *)
817 dev_alias: string option; (** The guest device alias associated with the path *)
818 action: action; (** The action that is to be taken due to the IO error *)
819 reason: string option; (** The cause of the IO error *)
822 val to_string: t -> string
825 module Graphics_address : sig
827 | `Ipv4 (** IPv4 address *)
828 | `Ipv6 (** IPv6 address *)
829 | `Unix (** UNIX socket path *)
830 | `Unknown of int (** newer libvirt *)
834 family: family; (** Address family *)
835 node: string option; (** Address of node (eg IP address, or UNIX path *)
836 service: string option; (** Service name/number (eg TCP port, or NULL) *)
839 val to_string: t -> string
842 module Graphics_subject : sig
844 ty: string option; (** Type of identity *)
845 name: string option; (** Identity value *)
848 type t = identity list
850 val to_string: t -> string
853 module Graphics : sig
855 | `Connect (** Initial socket connection established *)
856 | `Initialize (** Authentication & setup completed *)
857 | `Disconnect (** Final socket disconnection *)
858 | `Unknown of int (** newer libvirt *)
862 phase: phase; (** the phase of the connection *)
863 local: Graphics_address.t; (** the local server address *)
864 remote: Graphics_address.t; (** the remote client address *)
865 auth_scheme: string option; (** the authentication scheme activated *)
866 subject: Graphics_subject.t; (** the authenticated subject (user) *)
869 val to_string: t -> string
872 module Control_error : sig
875 val to_string: t -> string
878 module Block_job : sig
880 | `KnownUnknown (** explicitly named UNKNOWN in the spec *)
896 disk: string option; (** fully-qualified name of the affected disk *)
897 ty: ty; (** type of block job *)
898 status: status; (** final status of the operation *)
901 val to_string: t -> string
904 module Disk_change : sig
911 old_src_path: string option; (** old source path *)
912 new_src_path: string option; (** new source path *)
913 dev_alias: string option; (** device alias name *)
914 reason: reason; (** reason why this callback was called *)
917 val to_string: t -> string
920 module Tray_change : sig
928 dev_alias: string option; (** device alias *)
929 reason: reason; (** why the tray status was changed *)
932 val to_string: t -> string
935 module PM_wakeup : sig
942 val to_string: t -> string
945 module PM_suspend : sig
952 val to_string: t -> string
955 module Balloon_change : sig
958 val to_string: t -> string
961 module PM_suspend_disk : sig
968 val to_string: t -> string
973 | Lifecycle of ([`R] Domain.t -> Lifecycle.t -> unit)
974 | Reboot of ([`R] Domain.t -> Reboot.t -> unit)
975 | RtcChange of ([`R] Domain.t -> Rtc_change.t -> unit)
976 | Watchdog of ([`R] Domain.t -> Watchdog.t -> unit)
977 | IOError of ([`R] Domain.t -> Io_error.t -> unit)
978 | Graphics of ([`R] Domain.t -> Graphics.t -> unit)
979 | IOErrorReason of ([`R] Domain.t -> Io_error.t -> unit)
980 | ControlError of ([`R] Domain.t -> Control_error.t -> unit)
981 | BlockJob of ([`R] Domain.t -> Block_job.t -> unit)
982 | DiskChange of ([`R] Domain.t -> Disk_change.t -> unit)
983 | TrayChange of ([`R] Domain.t -> Tray_change.t -> unit)
984 | PMWakeUp of ([`R] Domain.t -> PM_wakeup.t -> unit)
985 | PMSuspend of ([`R] Domain.t -> PM_suspend.t -> unit)
986 | BalloonChange of ([`R] Domain.t -> Balloon_change.t -> unit)
987 | PMSuspendDisk of ([`R] Domain.t -> PM_suspend_disk.t -> unit)
989 (** type of a registered call back function *)
991 val register_default_impl : unit -> unit
992 (** Registers the default event loop based on poll(). This
993 must be done before connections are opened.
995 Once registered call run_default_impl in a loop. *)
997 val run_default_impl : unit -> unit
998 (** Runs one iteration of the event loop. Applications will
999 generally want to have a thread which invokes this in an
1003 (** an individual event registration *)
1005 val register_any : 'a Connect.t -> ?dom:'a Domain.t -> callback -> callback_id
1006 (** [register_any con ?dom callback] registers [callback]
1007 to receive notification of arbitrary domain events. Return
1008 a registration id which can be used in [deregister_any].
1010 If [?dom] is None then register for this kind of event on
1011 all domains. If [dom] is [Some d] then register for this
1012 kind of event only on [d].
1015 val deregister_any : 'a Connect.t -> callback_id -> unit
1016 (** [deregister_any con id] deregisters the previously registered
1017 callback with id [id]. *)
1020 (** an individual timer event *)
1022 val add_timeout : 'a Connect.t -> int -> (unit -> unit) -> timer_id
1023 (** [add_timeout con ms cb] registers [cb] as a timeout callback
1024 which will be called every [ms] milliseconds *)
1026 val remove_timeout : 'a Connect.t -> timer_id -> unit
1027 (** [remove_timeout con t] deregisters timeout callback [t]. *)
1030 (** Module dealing with events generated by domain
1038 (** Network handle. Read-only handles have type [ro Network.t] and
1039 read-write handles have type [rw Network.t].
1042 val lookup_by_name : 'a Connect.t -> string -> 'a t
1043 (** Lookup a network by name. *)
1044 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1045 (** Lookup a network by (packed) UUID. *)
1046 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1047 (** Lookup a network by UUID string. *)
1048 val create_xml : [>`W] Connect.t -> xml -> rw t
1049 (** Create a network. *)
1050 val define_xml : [>`W] Connect.t -> xml -> rw t
1051 (** Define but don't activate a network. *)
1052 val undefine : [>`W] t -> unit
1053 (** Undefine configuration of a network. *)
1054 val create : [>`W] t -> unit
1055 (** Start up a defined (inactive) network. *)
1056 val destroy : [>`W] t -> unit
1057 (** Destroy a network. *)
1058 val free : [>`R] t -> unit
1059 (** [free network] frees the network object in memory.
1061 The network object is automatically freed if it is garbage
1062 collected. This function just forces it to be freed right
1066 val get_name : [>`R] t -> string
1067 (** Get network name. *)
1068 val get_uuid : [>`R] t -> uuid
1069 (** Get network packed UUID. *)
1070 val get_uuid_string : [>`R] t -> string
1071 (** Get network UUID as a printable string. *)
1072 val get_xml_desc : [>`R] t -> xml
1073 (** Get XML description of a network. *)
1074 val get_bridge_name : [>`R] t -> string
1075 (** Get bridge device name of a network. *)
1076 val get_autostart : [>`R] t -> bool
1077 (** Get the autostart flag for a network. *)
1078 val set_autostart : [>`W] t -> bool -> unit
1079 (** Set the autostart flag for a network. *)
1081 external const : [>`R] t -> ro t = "%identity"
1082 (** [const network] turns a read/write network handle into a read-only
1083 network handle. Note that the opposite operation is impossible.
1086 (** Module dealing with networks. [Network.t] is the
1089 (** {3 Storage pools} *)
1094 (** Storage pool handle. *)
1096 type pool_state = Inactive | Building | Running | Degraded
1097 (** State of the storage pool. *)
1099 type pool_build_flags = New | Repair | Resize
1100 (** Flags for creating a storage pool. *)
1102 type pool_delete_flags = Normal | Zeroed
1103 (** Flags for deleting a storage pool. *)
1106 state : pool_state; (** Pool state. *)
1107 capacity : int64; (** Logical size in bytes. *)
1108 allocation : int64; (** Currently allocated in bytes. *)
1109 available : int64; (** Remaining free space bytes. *)
1112 val lookup_by_name : 'a Connect.t -> string -> 'a t
1113 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1114 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1115 (** Look up a storage pool by name, UUID or UUID string. *)
1117 val create_xml : [>`W] Connect.t -> xml -> rw t
1118 (** Create a storage pool. *)
1119 val define_xml : [>`W] Connect.t -> xml -> rw t
1120 (** Define but don't activate a storage pool. *)
1121 val build : [>`W] t -> pool_build_flags -> unit
1122 (** Build a storage pool. *)
1123 val undefine : [>`W] t -> unit
1124 (** Undefine configuration of a storage pool. *)
1125 val create : [>`W] t -> unit
1126 (** Start up a defined (inactive) storage pool. *)
1127 val destroy : [>`W] t -> unit
1128 (** Destroy a storage pool. *)
1129 val delete : [>`W] t -> unit
1130 (** Delete a storage pool. *)
1131 val free : [>`R] t -> unit
1132 (** Free a storage pool object in memory.
1134 The storage pool object is automatically freed if it is garbage
1135 collected. This function just forces it to be freed right
1138 val refresh : [`R] t -> unit
1139 (** Refresh the list of volumes in the storage pool. *)
1141 val get_name : [`R] t -> string
1142 (** Name of the pool. *)
1143 val get_uuid : [`R] t -> uuid
1144 (** Get the UUID (as a packed byte array). *)
1145 val get_uuid_string : [`R] t -> string
1146 (** Get the UUID (as a printable string). *)
1147 val get_info : [`R] t -> pool_info
1148 (** Get information about the pool. *)
1149 val get_xml_desc : [`R] t -> xml
1150 (** Get the XML description. *)
1151 val get_autostart : [`R] t -> bool
1152 (** Get the autostart flag for the storage pool. *)
1153 val set_autostart : [>`W] t -> bool -> unit
1154 (** Set the autostart flag for the storage pool. *)
1156 val num_of_volumes : [`R] t -> int
1157 (** Returns the number of storage volumes within the storage pool. *)
1158 val list_volumes : [`R] t -> int -> string array
1159 (** Return list of storage volumes. *)
1161 external const : [>`R] t -> ro t = "%identity"
1162 (** [const conn] turns a read/write storage pool into a read-only
1163 pool. Note that the opposite operation is impossible.
1166 (** Module dealing with storage pools. *)
1168 (** {3 Storage volumes} *)
1173 (** Storage volume handle. *)
1175 type vol_type = File | Block
1176 (** Type of a storage volume. *)
1178 type vol_delete_flags = Normal | Zeroed
1179 (** Flags for deleting a storage volume. *)
1182 typ : vol_type; (** Type of storage volume. *)
1183 capacity : int64; (** Logical size in bytes. *)
1184 allocation : int64; (** Currently allocated in bytes. *)
1187 val lookup_by_name : 'a Pool.t -> string -> 'a t
1188 val lookup_by_key : 'a Connect.t -> string -> 'a t
1189 val lookup_by_path : 'a Connect.t -> string -> 'a t
1190 (** Look up a storage volume by name, key or path volume. *)
1192 val pool_of_volume : 'a t -> 'a Pool.t
1193 (** Get the storage pool containing this volume. *)
1195 val get_name : [`R] t -> string
1196 (** Name of the volume. *)
1197 val get_key : [`R] t -> string
1198 (** Key of the volume. *)
1199 val get_path : [`R] t -> string
1200 (** Path of the volume. *)
1201 val get_info : [`R] t -> vol_info
1202 (** Get information about the storage volume. *)
1203 val get_xml_desc : [`R] t -> xml
1204 (** Get the XML description. *)
1206 val create_xml : [>`W] Pool.t -> xml -> unit
1207 (** Create a storage volume. *)
1208 val delete : [>`W] t -> vol_delete_flags -> unit
1209 (** Delete a storage volume. *)
1210 val free : [>`R] t -> unit
1211 (** Free a storage volume object in memory.
1213 The storage volume object is automatically freed if it is garbage
1214 collected. This function just forces it to be freed right
1218 external const : [>`R] t -> ro t = "%identity"
1219 (** [const conn] turns a read/write storage volume into a read-only
1220 volume. Note that the opposite operation is impossible.
1223 (** Module dealing with storage volumes. *)
1225 (** {3 Error handling and exceptions} *)
1231 | VIR_ERR_INTERNAL_ERROR
1233 | VIR_ERR_NO_SUPPORT
1234 | VIR_ERR_UNKNOWN_HOST
1235 | VIR_ERR_NO_CONNECT
1236 | VIR_ERR_INVALID_CONN
1237 | VIR_ERR_INVALID_DOMAIN
1238 | VIR_ERR_INVALID_ARG
1239 | VIR_ERR_OPERATION_FAILED
1240 | VIR_ERR_GET_FAILED
1241 | VIR_ERR_POST_FAILED
1242 | VIR_ERR_HTTP_ERROR
1243 | VIR_ERR_SEXPR_SERIAL
1254 | VIR_ERR_NO_XENSTORE
1255 | VIR_ERR_DRIVER_FULL
1256 | VIR_ERR_CALL_FAILED
1259 | VIR_ERR_OPERATION_DENIED
1260 | VIR_ERR_OPEN_FAILED
1261 | VIR_ERR_READ_FAILED
1262 | VIR_ERR_PARSE_FAILED
1263 | VIR_ERR_CONF_SYNTAX
1264 | VIR_ERR_WRITE_FAILED
1265 | VIR_ERR_XML_DETAIL
1266 | VIR_ERR_INVALID_NETWORK
1267 | VIR_ERR_NETWORK_EXIST
1268 | VIR_ERR_SYSTEM_ERROR
1270 | VIR_ERR_GNUTLS_ERROR
1271 | VIR_WAR_NO_NETWORK
1273 | VIR_ERR_NO_NETWORK
1274 | VIR_ERR_INVALID_MAC
1275 | VIR_ERR_AUTH_FAILED
1276 | VIR_ERR_INVALID_STORAGE_POOL
1277 | VIR_ERR_INVALID_STORAGE_VOL
1278 | VIR_WAR_NO_STORAGE
1279 | VIR_ERR_NO_STORAGE_POOL
1280 | VIR_ERR_NO_STORAGE_VOL
1281 (* ^^ NB: If you add a variant you MUST edit
1282 libvirt_c_epilogue.c:MAX_VIR_* *)
1283 | VIR_ERR_UNKNOWN of int
1284 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
1286 val string_of_code : code -> string
1305 | VIR_FROM_STATS_LINUX
1307 (* ^^ NB: If you add a variant you MUST edit
1308 libvirt_c_epilogue.c: MAX_VIR_* *)
1309 | VIR_FROM_UNKNOWN of int
1310 (** Subsystem / driver which produced the error. *)
1312 val string_of_domain : domain -> string
1318 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
1319 | VIR_ERR_UNKNOWN_LEVEL of int
1320 (** No error, a warning or an error. *)
1322 val string_of_level : level -> string
1325 code : code; (** Error code. *)
1326 domain : domain; (** Origin of the error. *)
1327 message : string option; (** Human-readable message. *)
1328 level : level; (** Error or warning. *)
1329 str1 : string option; (** Informational string. *)
1330 str2 : string option; (** Informational string. *)
1331 str3 : string option; (** Informational string. *)
1332 int1 : int32; (** Informational integer. *)
1333 int2 : int32; (** Informational integer. *)
1335 (** An error object. *)
1337 val to_string : t -> string
1338 (** Turn the exception into a printable string. *)
1340 val get_last_error : unit -> t option
1341 val get_last_conn_error : [>`R] Connect.t -> t option
1342 (** Get the last error at a global or connection level.
1344 Normally you do not need to use these functions because
1345 the library automatically turns errors into exceptions.
1348 val reset_last_error : unit -> unit
1349 val reset_last_conn_error : [>`R] Connect.t -> unit
1350 (** Reset the error at a global or connection level.
1352 Normally you do not need to use these functions.
1355 val no_error : unit -> t
1356 (** Creates an empty error message.
1358 Normally you do not need to use this function.
1361 (** Module dealing with errors. *)
1363 exception Virterror of Virterror.t
1364 (** This exception can be raised by any library function that detects
1365 an error. To get a printable error message, call
1366 {!Virterror.to_string} on the content of this exception.
1369 exception Not_supported of string
1372 [Not_supported "virFoo"]
1373 (where [virFoo] is the libvirt function name) if a function is
1374 not supported at either compile or run time. This applies to
1375 any libvirt function added after version 0.2.1.
1377 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
1380 (** {3 Utility functions} *)
1382 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1383 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1385 This is just like [List.map] except that if [f x] throws a
1386 {!Virterror.t} exception, the error is ignored and [f x]
1387 is not returned in the final list.
1389 This function is primarily useful when dealing with domains which
1390 might 'disappear' asynchronously from the currently running