Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 171 lines (109 sloc) 4.722 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
37e535f @msantos Update verx URL
authored
7 A "pure" Erlang libvirt interface is available here:
01a10bf @msantos Update the README
authored
8
37e535f @msantos Update verx URL
authored
9 <https://github.com/msantos/verx>
01a10bf @msantos Update the README
authored
10
37e535f @msantos Update verx URL
authored
11 verx uses the libvirtd remote procotol over a socket. By default, verx
12 uses a Unix socket which depends on a library written in C but verx
13 also supports TCP and TLS transports which do not have any external
14 dependencies.
01a10bf @msantos Update the README
authored
15
16
570d18a @msantos Add a warning about libvirt
authored
17 ## WARNING
18
f451e32 @msantos Add support for virNodeDevice
authored
19 The current implementation prevents the Erlang VM from being blocked
20 by calling all libvirt functions in a thread. If libvirt blocks,
21 the caller will receive an error immediately ({error, eagain}).
22 Only one call from Erlang into libvirt can be running at a time.
e636465 @msantos Use a non-blocking interface to libvirt
authored
23
f451e32 @msantos Add support for virNodeDevice
authored
24 These bindings have only been lightly tested. It's still possible
25 that some of the functions may segfault.
570d18a @msantos Add a warning about libvirt
authored
26
27
d6767da @msantos NIF interface to libvirt
authored
28 ## HOW TO BUILD IT
29
570d18a @msantos Add a warning about libvirt
authored
30 sudo apt-get install libvirt-dev libvirt-bin
d6767da @msantos NIF interface to libvirt
authored
31 make
32
eae74f8 @msantos Instructions for setting up a test VM
authored
33 ## CREATING A TEST VM
34
35 If you don't have a VM ready to test, you can download a test image
36 by running:
37
38 bin/get_image.escript
39
40 The script will download an OpenWRT image and set up the configuration
41 in priv/example.xml. By default, it will set up the VM to run under
42 KVM using user mode networking.
43
44 You can manually modify the configuration afterwards or set these
45 environment variables before running the script:
46
47 VERT_QEMU_BIN : path to the qemu binary (default: /usr/bin/kvm)
48 VERT_BRIDGE_INTERFACE : bridge interface (default: user networking)
d6767da @msantos NIF interface to libvirt
authored
49
50 ## HOW TO USE IT
51
09ab8e5 @msantos Update the README for the new API
authored
52 The Erlang libvirt API follows the libvirt C API. For example, if the
53 C API has:
54
55 virConnectOpen(char *name)
56 virConnectGetLibVersion(virConnectPtr(conn), unsigned long *version)
57
58 To call the same functions in Erlang:
59
60 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
61 {ok,{0,7,5}} = vert:virConnectGetLibVersion(Connect).
62
63
64
d6767da @msantos NIF interface to libvirt
authored
65 ## EXAMPLES
66
a903fb6 @msantos Add an example for suspend/resume
authored
67 ### CREATING A DOMAIN
68
fefd843 @msantos Add an example
authored
69 start(Path) ->
09ab8e5 @msantos Update the README for the new API
authored
70 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
fefd843 @msantos Add an example
authored
71 {ok, XML} = file:read_file(Path),
09ab8e5 @msantos Update the README for the new API
authored
72 {ok, Domain} = vert:virDomainDefineXML(Connect, XML),
c44c041 @msantos Convenience wrapper around virDomainCreate/2
authored
73 ok = vert:virDomainCreate(Domain),
fefd843 @msantos Add an example
authored
74
09ab8e5 @msantos Update the README for the new API
authored
75 Active = vert:virConnectNumOfDomains(Connect),
fefd843 @msantos Add an example
authored
76 io:format("Active Domains: ~p~n", [Active]),
77
ebe7b1d @msantos Correct example in README
authored
78 {ok, Domain}.
fefd843 @msantos Add an example
authored
79
ebe7b1d @msantos Correct example in README
authored
80 halt(Domain) ->
81 ok = vert:virDomainDestroy(Domain).
fefd843 @msantos Add an example
authored
82
70ee187 @msantos Example of dumping XML for defined domain
authored
83 ### DUMPING XML CONFIGURATION
84
85 This example dumps the XML of a defined (not running) domain.
86
f451e32 @msantos Add support for virNodeDevice
authored
87 1> {ok, Connect} = vert:virConnectOpen("qemu:///system").
70ee187 @msantos Example of dumping XML for defined domain
authored
88 {ok,{resource,connect,#Ref<0.0.0.30>,<<>>}}
89
90 2> {ok, [Host|_]} = vert:virConnectListDefinedDomains(Connect).
91 {ok, ["vm1"]}
92
93 3> {ok, Domain} = vert:virDomainLookupByName(Connect, Host).
94 {ok,{resource,domain,#Ref<0.0.0.56>,<<>>}}
95
96 4> {ok, XML} = vert:virDomainGetXMLDesc(Domain, 0).
97
98 5> {Doc, _} = xmerl_scan:string(XML).
99
100 6> rr(xmerl).
101
102 7> [Memory|_] = xmerl_xpath:string("/domain/memory/text()", Doc).
103
104 8> Memory#xmlText.value.
105 "1048576"
a903fb6 @msantos Add an example for suspend/resume
authored
106
107 ### SUSPENDING AND RESUMING A DOMAIN
108
09ab8e5 @msantos Update the README for the new API
authored
109 This example is the Erlang equivalent of a Python script to manipulate
110 running domains. The example is taken from:
a903fb6 @msantos Add an example for suspend/resume
authored
111
01a10bf @msantos Update the README
authored
112 <http://www.ibm.com/developerworks/linux/library/l-libvirt/>
a903fb6 @msantos Add an example for suspend/resume
authored
113
114
115 -module(ex6).
116
117 %% Listing 6. Sample Python script for domain control (libvtest.py)
118 %%
119 %% import libvirt
120 %%
121 %% conn = libvirt.open('qemu:///system')
122 %%
123 %% for id in conn.listDomainsID():
124 %%
125 %% dom = conn.lookupByID(id)
126 %%
127 %% print "Dom %s State %s" % ( dom.name(), dom.info()[0] )
128 %%
129 %% dom.suspend()
130 %% print "Dom %s State %s (after suspend)" % ( dom.name(), dom.info()[0] )
131 %%
132 %% dom.resume()
133 %% print "Dom %s State %s (after resume)" % ( dom.name(), dom.info()[0] )
134 %%
135 %% dom.destroy()
136 %%
137 -export([start/0]).
138
139 start() ->
09ab8e5 @msantos Update the README for the new API
authored
140 {ok, Connect} = vert:virConnectOpen("qemu:///system"),
d47fa3e @msantos Use virConnectList*/1
authored
141 {ok, DomainIDs} = vert:virConnectListDomains(Connect),
a903fb6 @msantos Add an example for suspend/resume
authored
142
143 [ states(Connect, DomainID) || DomainID <- DomainIDs ],
144
145 ok.
146
147 states(Connect, DomainID) ->
09ab8e5 @msantos Update the README for the new API
authored
148 {ok, Domain} = vert:virDomainLookupByID(Connect, DomainID),
a903fb6 @msantos Add an example for suspend/resume
authored
149 io:format("running: ~p~n", [info(Domain)]),
150
09ab8e5 @msantos Update the README for the new API
authored
151 ok = vert:virDomainSuspend(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
152 io:format("suspend: ~p~n", [info(Domain)]),
153
09ab8e5 @msantos Update the README for the new API
authored
154 ok = vert:virDomainResume(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
155 io:format("resumed: ~p~n", [info(Domain)]),
156
09ab8e5 @msantos Update the README for the new API
authored
157 ok = vert:virDomainDestroy(Domain).
a903fb6 @msantos Add an example for suspend/resume
authored
158
159 info(Domain) ->
0084a5a @msantos Enforce consistent use of tagged tuples
authored
160 {ok, Name} = vert:virDomainGetName(Domain),
161 {ok, Info} = vert:virDomainGetInfo(Domain),
a903fb6 @msantos Add an example for suspend/resume
authored
162
163 [{name, Name}, {info, Info}].
164
165
d6767da @msantos NIF interface to libvirt
authored
166 ## TODO
167
f451e32 @msantos Add support for virNodeDevice
authored
168 * allow caller to optionally run a libvirt operations in a new thread
cdf064c @msantos Update TODOs and copyright dates
authored
169
f451e32 @msantos Add support for virNodeDevice
authored
170 * add remaining libvirt API functions
Something went wrong with that request. Please try again.