Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 191 lines (123 sloc) 5.584 kb
d6767da Michael Santos NIF interface to libvirt
authored
1
2 Erlang bindings to the libvirt virtualization API.
3
01a10bf Michael Santos 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 Michael Santos Macro-ify
authored
11 libvirt-remote uses the (unsupported) libvirtd remote procotol over a
09ab8e5 Michael Santos Update the README for the new API
authored
12 Unix socket.
01a10bf Michael Santos Update the README
authored
13
14
570d18a Michael Santos Add a warning about libvirt
authored
15 ## WARNING
16
09ab8e5 Michael Santos Update the README for the new API
authored
17 The libvirt API is massive, inconsistent and error prone. So consider
d76a568 Michael Santos Macro-ify
authored
18 this language binding to be incomplete, buggy and erratic.
e636465 Michael Santos Use a non-blocking interface to libvirt
authored
19
09ab8e5 Michael Santos 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 Michael Santos 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 Michael Santos Add a warning about libvirt
authored
27
28
d6767da Michael Santos NIF interface to libvirt
authored
29 ## HOW TO BUILD IT
30
570d18a Michael Santos Add a warning about libvirt
authored
31 sudo apt-get install libvirt-dev libvirt-bin
d6767da Michael Santos NIF interface to libvirt
authored
32 make
33
eae74f8 Michael Santos 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 Michael Santos NIF interface to libvirt
authored
50
51 ## HOW TO USE IT
52
09ab8e5 Michael Santos 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 Michael Santos NIF interface to libvirt
authored
66 ## EXAMPLES
67
a903fb6 Michael Santos Add an example for suspend/resume
authored
68 ### CREATING A DOMAIN
69
fefd843 Michael Santos Add an example
authored
70 start(Path) ->
09ab8e5 Michael Santos Update the README for the new API
authored
71 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
fefd843 Michael Santos Add an example
authored
72 {ok, XML} = file:read_file(Path),
09ab8e5 Michael Santos Update the README for the new API
authored
73 {ok, Domain} = vert:virDomainDefineXML(Connect, XML),
c44c041 Michael Santos Convenience wrapper around virDomainCreate/2
authored
74 ok = vert:virDomainCreate(Domain),
fefd843 Michael Santos Add an example
authored
75
09ab8e5 Michael Santos Update the README for the new API
authored
76 Active = vert:virConnectNumOfDomains(Connect),
fefd843 Michael Santos Add an example
authored
77 io:format("Active Domains: ~p~n", [Active]),
78
ebe7b1d Michael Santos Correct example in README
authored
79 {ok, Domain}.
fefd843 Michael Santos Add an example
authored
80
ebe7b1d Michael Santos Correct example in README
authored
81 halt(Domain) ->
82 ok = vert:virDomainDestroy(Domain).
fefd843 Michael Santos Add an example
authored
83
70ee187 Michael Santos 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 Michael Santos Add an example for suspend/resume
authored
107
108 ### SUSPENDING AND RESUMING A DOMAIN
109
09ab8e5 Michael Santos 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 Michael Santos Add an example for suspend/resume
authored
112
01a10bf Michael Santos Update the README
authored
113 <http://www.ibm.com/developerworks/linux/library/l-libvirt/>
a903fb6 Michael Santos 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 Michael Santos Update the README for the new API
authored
141 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
d47fa3e Michael Santos Use virConnectList*/1
authored
142 {ok, DomainIDs} = vert:virConnectListDomains(Connect),
a903fb6 Michael Santos Add an example for suspend/resume
authored
143
144 [ states(Connect, DomainID) || DomainID <- DomainIDs ],
145
146 ok.
147
148 states(Connect, DomainID) ->
09ab8e5 Michael Santos Update the README for the new API
authored
149 {ok, Domain} = vert:virDomainLookupByID(Connect, DomainID),
a903fb6 Michael Santos Add an example for suspend/resume
authored
150 io:format("running: ~p~n", [info(Domain)]),
151
09ab8e5 Michael Santos Update the README for the new API
authored
152 ok = vert:virDomainSuspend(Domain),
a903fb6 Michael Santos Add an example for suspend/resume
authored
153 io:format("suspend: ~p~n", [info(Domain)]),
154
09ab8e5 Michael Santos Update the README for the new API
authored
155 ok = vert:virDomainResume(Domain),
a903fb6 Michael Santos Add an example for suspend/resume
authored
156 io:format("resumed: ~p~n", [info(Domain)]),
157
09ab8e5 Michael Santos Update the README for the new API
authored
158 ok = vert:virDomainDestroy(Domain).
a903fb6 Michael Santos Add an example for suspend/resume
authored
159
160 info(Domain) ->
0084a5a Michael Santos Enforce consistent use of tagged tuples
authored
161 {ok, Name} = vert:virDomainGetName(Domain),
162 {ok, Info} = vert:virDomainGetInfo(Domain),
a903fb6 Michael Santos Add an example for suspend/resume
authored
163
164 [{name, Name}, {info, Info}].
165
166
d6767da Michael Santos NIF interface to libvirt
authored
167 ## TODO
168
f72a223 Michael Santos 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 Michael Santos Update the README for the new API
authored
174 * Carefully check the code. There are many copy/paste defects.
f72a223 Michael Santos Add TODO's
authored
175
09ab8e5 Michael Santos Update the README for the new API
authored
176 * Allow the caller to kill the background thread if it is blocked
cdf064c Michael Santos 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.