Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 178 lines (114 sloc) 5.112 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
34
35 ## HOW TO USE IT
36
09ab8e5 @msantos Update the README for the new API
authored
37 The Erlang libvirt API follows the libvirt C API. For example, if the
38 C API has:
39
40 virConnectOpen(char *name)
41 virConnectGetLibVersion(virConnectPtr(conn), unsigned long *version)
42
43 To call the same functions in Erlang:
44
45 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
46 {ok,{0,7,5}} = vert:virConnectGetLibVersion(Connect).
47
48
49
d6767da @msantos NIF interface to libvirt
authored
50 ## EXAMPLES
51
a903fb6 @msantos Add an example for suspend/resume
authored
52 ### CREATING A DOMAIN
53
fefd843 @msantos Add an example
authored
54 start(Path) ->
09ab8e5 @msantos Update the README for the new API
authored
55 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
fefd843 @msantos Add an example
authored
56 {ok, XML} = file:read_file(Path),
09ab8e5 @msantos Update the README for the new API
authored
57 {ok, Domain} = vert:virDomainDefineXML(Connect, XML),
58 ok = vert:virDomainCreate(Domain, 0),
fefd843 @msantos Add an example
authored
59
09ab8e5 @msantos Update the README for the new API
authored
60 Active = vert:virConnectNumOfDomains(Connect),
fefd843 @msantos Add an example
authored
61 io:format("Active Domains: ~p~n", [Active]),
62
63 {ok, Connect, Domain}.
64
65 halt(Connect, Domain) ->
09ab8e5 @msantos Update the README for the new API
authored
66 ok = vert:virDomainDestroy(Domain),
67 ok = vert:virConnectClose(Connect).
fefd843 @msantos Add an example
authored
68
70ee187 @msantos Example of dumping XML for defined domain
authored
69 ### DUMPING XML CONFIGURATION
70
71 This example dumps the XML of a defined (not running) domain.
72
73 1> {ok, Connect} = vert:virConnectOpen("qemu:///system"),
74 {ok,{resource,connect,#Ref<0.0.0.30>,<<>>}}
75
76 2> {ok, [Host|_]} = vert:virConnectListDefinedDomains(Connect).
77 {ok, ["vm1"]}
78
79 3> {ok, Domain} = vert:virDomainLookupByName(Connect, Host).
80 {ok,{resource,domain,#Ref<0.0.0.56>,<<>>}}
81
82 4> {ok, XML} = vert:virDomainGetXMLDesc(Domain, 0).
83
84 5> {Doc, _} = xmerl_scan:string(XML).
85
86 6> rr(xmerl).
87
88 7> [Memory|_] = xmerl_xpath:string("/domain/memory/text()", Doc).
89
90 8> Memory#xmlText.value.
91 "1048576"
a903fb6 @msantos Add an example for suspend/resume
authored
92
93 ### SUSPENDING AND RESUMING A DOMAIN
94
09ab8e5 @msantos Update the README for the new API
authored
95 This example is the Erlang equivalent of a Python script to manipulate
96 running domains. The example is taken from:
a903fb6 @msantos Add an example for suspend/resume
authored
97
01a10bf @msantos Update the README
authored
98 <http://www.ibm.com/developerworks/linux/library/l-libvirt/>
a903fb6 @msantos Add an example for suspend/resume
authored
99
100
101 -module(ex6).
102
103 %% Listing 6. Sample Python script for domain control (libvtest.py)
104 %%
105 %% import libvirt
106 %%
107 %% conn = libvirt.open('qemu:///system')
108 %%
109 %% for id in conn.listDomainsID():
110 %%
111 %% dom = conn.lookupByID(id)
112 %%
113 %% print "Dom %s State %s" % ( dom.name(), dom.info()[0] )
114 %%
115 %% dom.suspend()
116 %% print "Dom %s State %s (after suspend)" % ( dom.name(), dom.info()[0] )
117 %%
118 %% dom.resume()
119 %% print "Dom %s State %s (after resume)" % ( dom.name(), dom.info()[0] )
120 %%
121 %% dom.destroy()
122 %%
123 -export([start/0]).
124
125 start() ->
09ab8e5 @msantos Update the README for the new API
authored
126 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
d47fa3e @msantos Use virConnectList*/1
authored
127 {ok, DomainIDs} = vert:virConnectListDomains(Connect),
a903fb6 @msantos Add an example for suspend/resume
authored
128
129 [ states(Connect, DomainID) || DomainID <- DomainIDs ],
130
131 ok.
132
133 states(Connect, DomainID) ->
09ab8e5 @msantos Update the README for the new API
authored
134 {ok, Domain} = vert:virDomainLookupByID(Connect, DomainID),
a903fb6 @msantos Add an example for suspend/resume
authored
135 io:format("running: ~p~n", [info(Domain)]),
136
09ab8e5 @msantos Update the README for the new API
authored
137 ok = vert:virDomainSuspend(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
138 io:format("suspend: ~p~n", [info(Domain)]),
139
09ab8e5 @msantos Update the README for the new API
authored
140 ok = vert:virDomainResume(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
141 io:format("resumed: ~p~n", [info(Domain)]),
142
09ab8e5 @msantos Update the README for the new API
authored
143 ok = vert:virDomainDestroy(Domain).
a903fb6 @msantos Add an example for suspend/resume
authored
144
145 info(Domain) ->
0084a5a @msantos Enforce consistent use of tagged tuples
authored
146 {ok, Name} = vert:virDomainGetName(Domain),
147 {ok, Info} = vert:virDomainGetInfo(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
148
149 [{name, Name}, {info, Info}].
150
151
d6767da @msantos NIF interface to libvirt
authored
152 ## TODO
153
f72a223 @msantos Add TODO's
authored
154 * tests: use the libvirt test driver and make a set of tests
155
156 * review the Erlang interface
157 * find examples of code in other languages using libvirt and discover
158 how awkward the Erlang interface is by porting them
159 * then of course document the interface
160
09ab8e5 @msantos Update the README for the new API
authored
161 * Carefully check the code. There are many copy/paste defects.
f72a223 @msantos Add TODO's
authored
162
09ab8e5 @msantos Update the README for the new API
authored
163 * Allow the caller to kill the background thread if it is blocked
cdf064c @msantos Update TODOs and copyright dates
authored
164
165 * Figure out how to deal with backwards compatibility (functions
166 unsupported in older versions of libvirt)
167
168 * Generate as much of the code as possible automatically from the libvirt
169 XML documentation file (another rewrite!)
170
171 * Reduce macro usage, many of them obscure the logic (returning from
172 functions, setting variables, ...). Rename macros to show intent, e.g.,
173 VERTERR() should be something like RETURN\_ERR\_IF\_FALSE(), ISNULL()
174 should be RETURN\_ERR\_IF\_NULL().
175
176 * Modify the resource structure to hold function pointers based on
177 resource type, e.g., freeing the resource, etc.
Something went wrong with that request. Please try again.