Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 191 lines (123 sloc) 5.584 kB
d6767da @msantos NIF interface to libvirt
authored
1
2 Erlang bindings to the libvirt virtualization API.
3
01a10bf @msantos Update the README
authored
4
5 ## ALTERNATIVES
6
7 An (almost) pure Erlang libvirt binding is available here:
8
9 <https://github.com/msantos/erlang-libvirt-remote>
10
d76a568 @msantos Macro-ify
authored
11 libvirt-remote uses the (unsupported) libvirtd remote procotol over a
09ab8e5 @msantos Update the README for the new API
authored
12 Unix socket.
01a10bf @msantos Update the README
authored
13
14
570d18a @msantos Add a warning about libvirt
authored
15 ## WARNING
16
09ab8e5 @msantos Update the README for the new API
authored
17 The libvirt API is massive, inconsistent and error prone. So consider
d76a568 @msantos Macro-ify
authored
18 this language binding to be incomplete, buggy and erratic.
e636465 @msantos Use a non-blocking interface to libvirt
authored
19
09ab8e5 @msantos Update the README for the new API
authored
20 The current implementation calls all libvirt functions in a thread so
21 that the Erlang VM will not block. If libvirt blocks, the caller will
e636465 @msantos Use a non-blocking interface to libvirt
authored
22 receive an error immediately ({error, eagain}). This means only one
23 call from a single Erlang VM into libvirt can be running at any time.
24
25 These bindings have not been heavily tested, are still under
26 development and will undergo many changes.
570d18a @msantos Add a warning about libvirt
authored
27
28
d6767da @msantos NIF interface to libvirt
authored
29 ## HOW TO BUILD IT
30
570d18a @msantos Add a warning about libvirt
authored
31 sudo apt-get install libvirt-dev libvirt-bin
d6767da @msantos NIF interface to libvirt
authored
32 make
33
eae74f8 @msantos Instructions for setting up a test VM
authored
34 ## CREATING A TEST VM
35
36 If you don't have a VM ready to test, you can download a test image
37 by running:
38
39 bin/get_image.escript
40
41 The script will download an OpenWRT image and set up the configuration
42 in priv/example.xml. By default, it will set up the VM to run under
43 KVM using user mode networking.
44
45 You can manually modify the configuration afterwards or set these
46 environment variables before running the script:
47
48 VERT_QEMU_BIN : path to the qemu binary (default: /usr/bin/kvm)
49 VERT_BRIDGE_INTERFACE : bridge interface (default: user networking)
d6767da @msantos NIF interface to libvirt
authored
50
51 ## HOW TO USE IT
52
09ab8e5 @msantos Update the README for the new API
authored
53 The Erlang libvirt API follows the libvirt C API. For example, if the
54 C API has:
55
56 virConnectOpen(char *name)
57 virConnectGetLibVersion(virConnectPtr(conn), unsigned long *version)
58
59 To call the same functions in Erlang:
60
61 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
62 {ok,{0,7,5}} = vert:virConnectGetLibVersion(Connect).
63
64
65
d6767da @msantos NIF interface to libvirt
authored
66 ## EXAMPLES
67
a903fb6 @msantos Add an example for suspend/resume
authored
68 ### CREATING A DOMAIN
69
fefd843 @msantos Add an example
authored
70 start(Path) ->
09ab8e5 @msantos Update the README for the new API
authored
71 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
fefd843 @msantos Add an example
authored
72 {ok, XML} = file:read_file(Path),
09ab8e5 @msantos Update the README for the new API
authored
73 {ok, Domain} = vert:virDomainDefineXML(Connect, XML),
c44c041 @msantos Convenience wrapper around virDomainCreate/2
authored
74 ok = vert:virDomainCreate(Domain),
fefd843 @msantos Add an example
authored
75
09ab8e5 @msantos Update the README for the new API
authored
76 Active = vert:virConnectNumOfDomains(Connect),
fefd843 @msantos Add an example
authored
77 io:format("Active Domains: ~p~n", [Active]),
78
ebe7b1d @msantos Correct example in README
authored
79 {ok, Domain}.
fefd843 @msantos Add an example
authored
80
ebe7b1d @msantos Correct example in README
authored
81 halt(Domain) ->
82 ok = vert:virDomainDestroy(Domain).
fefd843 @msantos Add an example
authored
83
70ee187 @msantos Example of dumping XML for defined domain
authored
84 ### DUMPING XML CONFIGURATION
85
86 This example dumps the XML of a defined (not running) domain.
87
88 1> {ok, Connect} = vert:virConnectOpen("qemu:///system"),
89 {ok,{resource,connect,#Ref<0.0.0.30>,<<>>}}
90
91 2> {ok, [Host|_]} = vert:virConnectListDefinedDomains(Connect).
92 {ok, ["vm1"]}
93
94 3> {ok, Domain} = vert:virDomainLookupByName(Connect, Host).
95 {ok,{resource,domain,#Ref<0.0.0.56>,<<>>}}
96
97 4> {ok, XML} = vert:virDomainGetXMLDesc(Domain, 0).
98
99 5> {Doc, _} = xmerl_scan:string(XML).
100
101 6> rr(xmerl).
102
103 7> [Memory|_] = xmerl_xpath:string("/domain/memory/text()", Doc).
104
105 8> Memory#xmlText.value.
106 "1048576"
a903fb6 @msantos Add an example for suspend/resume
authored
107
108 ### SUSPENDING AND RESUMING A DOMAIN
109
09ab8e5 @msantos Update the README for the new API
authored
110 This example is the Erlang equivalent of a Python script to manipulate
111 running domains. The example is taken from:
a903fb6 @msantos Add an example for suspend/resume
authored
112
01a10bf @msantos Update the README
authored
113 <http://www.ibm.com/developerworks/linux/library/l-libvirt/>
a903fb6 @msantos Add an example for suspend/resume
authored
114
115
116 -module(ex6).
117
118 %% Listing 6. Sample Python script for domain control (libvtest.py)
119 %%
120 %% import libvirt
121 %%
122 %% conn = libvirt.open('qemu:///system')
123 %%
124 %% for id in conn.listDomainsID():
125 %%
126 %% dom = conn.lookupByID(id)
127 %%
128 %% print "Dom %s State %s" % ( dom.name(), dom.info()[0] )
129 %%
130 %% dom.suspend()
131 %% print "Dom %s State %s (after suspend)" % ( dom.name(), dom.info()[0] )
132 %%
133 %% dom.resume()
134 %% print "Dom %s State %s (after resume)" % ( dom.name(), dom.info()[0] )
135 %%
136 %% dom.destroy()
137 %%
138 -export([start/0]).
139
140 start() ->
09ab8e5 @msantos Update the README for the new API
authored
141 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
d47fa3e @msantos Use virConnectList*/1
authored
142 {ok, DomainIDs} = vert:virConnectListDomains(Connect),
a903fb6 @msantos Add an example for suspend/resume
authored
143
144 [ states(Connect, DomainID) || DomainID <- DomainIDs ],
145
146 ok.
147
148 states(Connect, DomainID) ->
09ab8e5 @msantos Update the README for the new API
authored
149 {ok, Domain} = vert:virDomainLookupByID(Connect, DomainID),
a903fb6 @msantos Add an example for suspend/resume
authored
150 io:format("running: ~p~n", [info(Domain)]),
151
09ab8e5 @msantos Update the README for the new API
authored
152 ok = vert:virDomainSuspend(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
153 io:format("suspend: ~p~n", [info(Domain)]),
154
09ab8e5 @msantos Update the README for the new API
authored
155 ok = vert:virDomainResume(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
156 io:format("resumed: ~p~n", [info(Domain)]),
157
09ab8e5 @msantos Update the README for the new API
authored
158 ok = vert:virDomainDestroy(Domain).
a903fb6 @msantos Add an example for suspend/resume
authored
159
160 info(Domain) ->
0084a5a @msantos Enforce consistent use of tagged tuples
authored
161 {ok, Name} = vert:virDomainGetName(Domain),
162 {ok, Info} = vert:virDomainGetInfo(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
163
164 [{name, Name}, {info, Info}].
165
166
d6767da @msantos NIF interface to libvirt
authored
167 ## TODO
168
f72a223 @msantos Add TODO's
authored
169 * review the Erlang interface
170 * find examples of code in other languages using libvirt and discover
171 how awkward the Erlang interface is by porting them
172 * then of course document the interface
173
09ab8e5 @msantos Update the README for the new API
authored
174 * Carefully check the code. There are many copy/paste defects.
f72a223 @msantos Add TODO's
authored
175
09ab8e5 @msantos Update the README for the new API
authored
176 * Allow the caller to kill the background thread if it is blocked
cdf064c @msantos Update TODOs and copyright dates
authored
177
178 * Figure out how to deal with backwards compatibility (functions
179 unsupported in older versions of libvirt)
180
181 * Generate as much of the code as possible automatically from the libvirt
182 XML documentation file (another rewrite!)
183
184 * Reduce macro usage, many of them obscure the logic (returning from
185 functions, setting variables, ...). Rename macros to show intent, e.g.,
186 VERTERR() should be something like RETURN\_ERR\_IF\_FALSE(), ISNULL()
187 should be RETURN\_ERR\_IF\_NULL().
188
189 * Modify the resource structure to hold function pointers based on
190 resource type, e.g., freeing the resource, etc.
Something went wrong with that request. Please try again.