(** OCaml bindings for libvirt. *)
-(* (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc.
- http://libvirt.org/
+(* (C) Copyright 2007-2015 Richard W.M. Jones, Red Hat Inc.
+ https://libvirt.org/
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
{2 Introduction and examples}
This is a set of bindings for writing OCaml programs to
- manage virtual machines through {{:http://libvirt.org/}libvirt}.
+ manage virtual machines through {{:https://libvirt.org/}libvirt}.
{3 Using libvirt interactively}
The main modules are {!Libvirt.Connect}, {!Libvirt.Domain} and
{!Libvirt.Network} corresponding respectively to the
- {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
+ {{:https://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
For brevity I usually rename these modules like this:
{[
type rw = [`R|`W]
type ro = [`R]
(** These
- {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
+ {{:https://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
are used to ensure the type-safety of read-only
versus read-write connections.
threads : int; (** number of threads per core *)
}
+ type credential_type =
+ | CredentialUsername (** Identity to act as *)
+ | CredentialAuthname (** Identify to authorize as *)
+ | CredentialLanguage (** RFC 1766 languages, comma separated *)
+ | CredentialCnonce (** client supplies a nonce *)
+ | CredentialPassphrase (** Passphrase secret *)
+ | CredentialEchoprompt (** Challenge response *)
+ | CredentialNoechoprompt (** Challenge response *)
+ | CredentialRealm (** Authentication realm *)
+ | CredentialExternal (** Externally managed credential *)
+
+ type credential = {
+ typ : credential_type; (** The type of credential *)
+ prompt : string; (** Prompt to show to user *)
+ challenge : string option; (** Additional challenge to show *)
+ defresult : string option; (** Optional default result *)
+ }
+
+ type auth = {
+ credtype : credential_type list; (** List of supported credential_type values *)
+ cb : (credential list -> string option list);
+ (** Callback used to collect credentials.
+
+ The input is a list of all the requested credentials.
+
+ The function returns a list of all the results from the
+ requested credentials, so the number of results {e must} match
+ the number of input credentials. Each result is optional,
+ and in case it is [None] it means there was no result.
+ *)
+ }
+
val connect : ?name:string -> unit -> rw t
val connect_readonly : ?name:string -> unit -> ro t
(** [connect ~name ()] connects to the hypervisor with URI [name].
[connect_readonly] is the same but connects in read-only mode.
*)
+ val connect_auth : ?name:string -> auth -> rw t
+ val connect_auth_readonly : ?name:string -> auth -> ro t
+
val close : [>`R] t -> unit
(** [close conn] closes and frees the connection object in memory.
(* The name of this function is inconsistent, but the inconsistency
* is really in libvirt itself.
*)
+ val num_of_secrets : [>`R] t -> int
+ (** Returns the number of secrets. *)
+ val list_secrets : [>`R] t -> int -> string array
+ (** Returns the list of secrets. *)
val get_node_info : [>`R] t -> node_info
(** Return information about the physical server. *)
CPU map between a single virtual and all physical CPUs of a domain.
*)
- val use_cpu : string -> int -> unit
+ val use_cpu : bytes -> int -> unit
(** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
- val unuse_cpu : string -> int -> unit
+ val unuse_cpu : bytes -> int -> unit
(** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
- val cpu_usable : string -> int -> int -> int -> bool
+ val cpu_usable : bytes -> int -> int -> int -> bool
(** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
[cpu] is usable by [vcpu]. *)
Note: the client has to implement and run an event loop to
be able to use keep-alive messages. *)
+ val get_auth_default : unit -> auth
+ (** [get_auth_default ()] returns the default authentication handler
+ of libvirt.
+ *)
+
external const : [>`R] t -> ro t = "%identity"
(** [const conn] turns a read/write connection into a read-only
connection. Note that the opposite operation is impossible.
cpu : int; (** real CPU number, -1 if offline *)
}
+ type domain_create_flag =
+ | START_PAUSED (** Launch guest in paused state *)
+ | START_AUTODESTROY (** Automatically kill guest on close *)
+ | START_BYPASS_CACHE (** Avoid filesystem cache pollution *)
+ | START_FORCE_BOOT (** Discard any managed save *)
+ | START_VALIDATE (** Validate XML against schema *)
+
type sched_param = string * sched_param_value
and sched_param_value =
| SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
tx_drop : int64;
}
+ type get_all_domain_stats_flag =
+ | GetAllDomainsStatsActive
+ | GetAllDomainsStatsInactive
+ | GetAllDomainsStatsOther
+ | GetAllDomainsStatsPaused
+ | GetAllDomainsStatsPersistent
+ | GetAllDomainsStatsRunning
+ | GetAllDomainsStatsShutoff
+ | GetAllDomainsStatsTransient
+ | GetAllDomainsStatsBacking
+ | GetAllDomainsStatsEnforceStats
+
+ type stats_type =
+ | StatsState | StatsCpuTotal | StatsBalloon | StatsVcpu
+ | StatsInterface | StatsBlock | StatsPerf
+
+ type domain_stats_record = {
+ dom_uuid : uuid;
+ params : typed_param array;
+ }
+
+ type xml_desc_flag =
+ | XmlSecure (* dump security sensitive information too *)
+ | XmlInactive (* dump inactive domain information *)
+ | XmlUpdateCPU (* update guest CPU requirements according to host CPU *)
+ | XmlMigratable (* dump XML suitable for migration *)
+
val max_peek : [>`R] t -> int
(** Maximum size supported by the {!block_peek} and {!memory_peek}
functions. If you want to peek more than this then you must
val create_linux : [>`W] Connect.t -> xml -> rw t
(** Create a new guest domain (not necessarily a Linux one)
- from the given XML.
+ from the given XML. Use {!create_xml} instead.
*)
+ val create_xml : [>`W] Connect.t -> xml -> domain_create_flag list -> rw t
+ (** Create a new guest domain from the given XML. *)
val lookup_by_id : 'a Connect.t -> int -> 'a t
(** Lookup a domain by ID. *)
val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
(** Get information about a domain. *)
val get_xml_desc : [>`R] t -> xml
(** Get the XML description of a domain. *)
+ val get_xml_desc_flags : [>`W] t -> xml_desc_flag list -> xml
+ (** Get the XML description of a domain, with the possibility
+ to specify flags. *)
val get_scheduler_type : [>`R] t -> string * int
(** Get the scheduler type. *)
val get_scheduler_parameters : [>`R] t -> int -> sched_param array
See also {!max_peek}. *)
+ external get_all_domain_stats : [>`R] Connect.t -> stats_type list -> get_all_domain_stats_flag list -> domain_stats_record array = "ocaml_libvirt_domain_get_all_domain_stats"
+ (** [get_all_domain_stats conn stats flags] allows you to read
+ all stats across multiple/all domains in a single call.
+
+ See the libvirt documentation for
+ [virConnectGetAllDomainStats]. *)
+
external const : [>`R] t -> ro t = "%identity"
(** [const dom] turns a read/write domain handle into a read-only
domain handle. Note that the opposite operation is impossible.
end
(** Module dealing with storage volumes. *)
+(** {3 Secrets} *)
+
+module Secret :
+sig
+ type 'rw t
+ (** Secret handle. *)
+
+ type secret_usage_type =
+ | NoType
+ | Volume
+ | Ceph
+ | ISCSI
+ | TLS
+ (** Usage type of a secret. *)
+
+ val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
+ (** Lookup a secret by UUID. This uses the packed byte array UUID. *)
+ val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
+ (** Lookup a secret by (string) UUID. *)
+ val lookup_by_usage : 'a Connect.t -> secret_usage_type -> string -> 'a t
+ (** Lookup a secret by usage type, and usage ID. *)
+
+ val define_xml : [>`W] Connect.t -> xml -> rw t
+ (** Define a secret. *)
+
+ val get_uuid : [>`R] t -> uuid
+ (** Get the UUID (as a packed byte array) of the secret. *)
+ val get_uuid_string : [>`R] t -> string
+ (** Get the UUID (as a printable string) of the secret. *)
+ val get_usage_type : [>`R] t -> secret_usage_type
+ (** Get the usage type of the secret. *)
+ val get_usage_id : [>`R] t -> string
+ (** Get the usage ID of the secret. *)
+ val get_xml_desc : [>`R] t -> xml
+ (** Get the XML description. *)
+
+ val set_value : [>`W] t -> bytes -> unit
+ (** Set a new value for the secret. *)
+ val get_value : [>`R] t -> bytes
+ (** Get the value of the secret. *)
+
+ val undefine : [>`W] t -> unit
+ (** Undefine a secret. *)
+
+ val free : [>`R] t -> unit
+ (** Free a secret object in memory.
+
+ The secret object is automatically freed if it is garbage
+ collected. This function just forces it to be freed right
+ away.
+ *)
+
+ external const : [>`R] t -> ro t = "%identity"
+ (** [const conn] turns a read/write secret into a read-only
+ secret. Note that the opposite operation is impossible.
+ *)
+end
+ (** Module dealing with secrets. *)
+
(** {3 Error handling and exceptions} *)
module Virterror :
| VIR_WAR_NO_STORAGE
| VIR_ERR_NO_STORAGE_POOL
| VIR_ERR_NO_STORAGE_VOL
+ | VIR_WAR_NO_NODE
+ | VIR_ERR_INVALID_NODE_DEVICE
+ | VIR_ERR_NO_NODE_DEVICE
+ | VIR_ERR_NO_SECURITY_MODEL
+ | VIR_ERR_OPERATION_INVALID
+ | VIR_WAR_NO_INTERFACE
+ | VIR_ERR_NO_INTERFACE
+ | VIR_ERR_INVALID_INTERFACE
+ | VIR_ERR_MULTIPLE_INTERFACES
+ | VIR_WAR_NO_NWFILTER
+ | VIR_ERR_INVALID_NWFILTER
+ | VIR_ERR_NO_NWFILTER
+ | VIR_ERR_BUILD_FIREWALL
+ | VIR_WAR_NO_SECRET
+ | VIR_ERR_INVALID_SECRET
+ | VIR_ERR_NO_SECRET
+ | VIR_ERR_CONFIG_UNSUPPORTED
+ | VIR_ERR_OPERATION_TIMEOUT
+ | VIR_ERR_MIGRATE_PERSIST_FAILED
+ | VIR_ERR_HOOK_SCRIPT_FAILED
+ | VIR_ERR_INVALID_DOMAIN_SNAPSHOT
+ | VIR_ERR_NO_DOMAIN_SNAPSHOT
+ | VIR_ERR_INVALID_STREAM
+ | VIR_ERR_ARGUMENT_UNSUPPORTED
+ | VIR_ERR_STORAGE_PROBE_FAILED
+ | VIR_ERR_STORAGE_POOL_BUILT
+ | VIR_ERR_SNAPSHOT_REVERT_RISKY
+ | VIR_ERR_OPERATION_ABORTED
+ | VIR_ERR_AUTH_CANCELLED
+ | VIR_ERR_NO_DOMAIN_METADATA
+ | VIR_ERR_MIGRATE_UNSAFE
+ | VIR_ERR_OVERFLOW
+ | VIR_ERR_BLOCK_COPY_ACTIVE
+ | VIR_ERR_OPERATION_UNSUPPORTED
+ | VIR_ERR_SSH
+ | VIR_ERR_AGENT_UNRESPONSIVE
+ | VIR_ERR_RESOURCE_BUSY
+ | VIR_ERR_ACCESS_DENIED
+ | VIR_ERR_DBUS_SERVICE
+ | VIR_ERR_STORAGE_VOL_EXIST
+ | VIR_ERR_CPU_INCOMPATIBLE
+ | VIR_ERR_XML_INVALID_SCHEMA
+ | VIR_ERR_MIGRATE_FINISH_OK
+ | VIR_ERR_AUTH_UNAVAILABLE
+ | VIR_ERR_NO_SERVER
+ | VIR_ERR_NO_CLIENT
+ | VIR_ERR_AGENT_UNSYNCED
+ | VIR_ERR_LIBSSH
+ | VIR_ERR_DEVICE_MISSING
+ | VIR_ERR_INVALID_NWFILTER_BINDING
+ | VIR_ERR_NO_NWFILTER_BINDING
(* ^^ NB: If you add a variant you MUST edit
libvirt_c_epilogue.c:MAX_VIR_* *)
| VIR_ERR_UNKNOWN of int
| VIR_FROM_OPENVZ
| VIR_FROM_XENXM
| VIR_FROM_STATS_LINUX
+ | VIR_FROM_LXC
| VIR_FROM_STORAGE
+ | VIR_FROM_NETWORK
+ | VIR_FROM_DOMAIN
+ | VIR_FROM_UML
+ | VIR_FROM_NODEDEV
+ | VIR_FROM_XEN_INOTIFY
+ | VIR_FROM_SECURITY
+ | VIR_FROM_VBOX
+ | VIR_FROM_INTERFACE
+ | VIR_FROM_ONE
+ | VIR_FROM_ESX
+ | VIR_FROM_PHYP
+ | VIR_FROM_SECRET
+ | VIR_FROM_CPU
+ | VIR_FROM_XENAPI
+ | VIR_FROM_NWFILTER
+ | VIR_FROM_HOOK
+ | VIR_FROM_DOMAIN_SNAPSHOT
+ | VIR_FROM_AUDIT
+ | VIR_FROM_SYSINFO
+ | VIR_FROM_STREAMS
+ | VIR_FROM_VMWARE
+ | VIR_FROM_EVENT
+ | VIR_FROM_LIBXL
+ | VIR_FROM_LOCKING
+ | VIR_FROM_HYPERV
+ | VIR_FROM_CAPABILITIES
+ | VIR_FROM_URI
+ | VIR_FROM_AUTH
+ | VIR_FROM_DBUS
+ | VIR_FROM_PARALLELS
+ | VIR_FROM_DEVICE
+ | VIR_FROM_SSH
+ | VIR_FROM_LOCKSPACE
+ | VIR_FROM_INITCTL
+ | VIR_FROM_IDENTITY
+ | VIR_FROM_CGROUP
+ | VIR_FROM_ACCESS
+ | VIR_FROM_SYSTEMD
+ | VIR_FROM_BHYVE
+ | VIR_FROM_CRYPTO
+ | VIR_FROM_FIREWALL
+ | VIR_FROM_POLKIT
+ | VIR_FROM_THREAD
+ | VIR_FROM_ADMIN
+ | VIR_FROM_LOGGING
+ | VIR_FROM_XENXL
+ | VIR_FROM_PERF
+ | VIR_FROM_LIBSSH
+ | VIR_FROM_RESCTRL
(* ^^ NB: If you add a variant you MUST edit
libvirt_c_epilogue.c: MAX_VIR_* *)
| VIR_FROM_UNKNOWN of int
not supported at either compile or run time. This applies to
any libvirt function added after version 0.2.1.
- See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
+ See also {{:https://libvirt.org/hvsupport.html}https://libvirt.org/hvsupport.html}
*)
(** {3 Utility functions} *)
git.annexia.org / ocaml-libvirt.git / blobdiff