5 guestfs - Library for accessing and modifying virtual machine images
9 guestfs_h handle = guestfs_create ();
10 guestfs_add_drive (handle, "guest.img");
11 guestfs_launch (handle);
12 guestfs_wait_ready (handle);
13 guestfs_mount (handle, "/dev/sda1", "/");
14 guestfs_touch_file (handle, "/hello");
15 guestfs_sync (handle);
16 guestfs_close (handle);
20 Libguestfs is a library for accessing and modifying guest disk images.
21 Amongst the things this is good for: making batch configuration
22 changes to guests, getting disk used/free statistics (see also:
23 virt-df), migrating between virtualization systems (see also:
24 virt-p2v), performing partial backups, performing partial guest
25 clones, cloning guests and changing registry/UUID/hostname info, and
28 Libguestfs uses Linux kernel and qemu code, and can access any type of
29 guest filesystem that Linux and qemu can, including but not limited
30 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
31 schemes, qcow, qcow2, vmdk.
33 Libguestfs provides ways to enumerate guest storage (eg. partitions,
34 LVs, what filesystem is in each LV, etc.). It can also run commands
35 in the context of the guest. Also you can mount guest filesystems on
36 the host (requires root privs and NFS).
38 Libguestfs is a library that can be linked with C and C++ management
39 programs (or management programs written in other languages, if people
40 contribute the language bindings). You can also use it from shell
41 scripts or the command line.
43 =head1 CONNECTION MANAGEMENT
50 =head1 CONFIGURATION MANAGEMENT
74 =head1 STATE MACHINE AND LOW-LEVEL EVENT API
76 Internally, libguestfs is implemented by running a virtual machine
77 using L<qemu(1)>. QEmu runs as a child process of the main program,
78 and most of this discussion won't make sense unless you understand
79 that the complexity is dealing with the (asynchronous) actions of the
84 libguestfs uses a state machine to model the child process:
95 / | \ \ guestfs_launch
101 / | guestfs_wait_ready
106 \______/ <------ \________/
108 The normal transitions are (1) CONFIG (when the handle is created, but
109 there is no child process), (2) LAUNCHING (when the child process is
110 booting up), (3) alternating between READY and BUSY as commands are
111 issued to, and carried out by, the child process.
113 The guest may be killed by C<guestfs_kill_subprocess>, or may die
114 asynchronously at any time (eg. due to some internal error), and that
115 causes the state to transition back to CONFIG.
117 Configuration commands for qemu such as C<guestfs_add_drive> can only
118 be issued when in the CONFIG state.
120 The high-level API offers two calls that go from CONFIG through
121 LAUNCHING to READY. C<guestfs_launch> is a non-blocking call that
122 starts up the child process, immediately moving from CONFIG to
123 LAUNCHING. C<guestfs_wait_ready> blocks until the child process is
124 READY to accept commands (or until some failure or timeout). The
125 low-level event API described below provides a non-blocking way to
126 replace C<guestfs_wait_ready>.
128 High-level API actions such as C<guestfs_mount> can only be issued
129 when in the READY state. These high-level API calls block waiting for
130 the command to be carried out (ie. the state to transition to BUSY and
131 then back to READY). But using the low-level event API, you get
132 non-blocking versions. (But you can still only carry out one
133 operation per handle at a time - that is a limitation of the
134 communications protocol we use).
136 Finally, the child process sends asynchronous messages back to the
137 main program, such as kernel log messages. Mostly these are ignored
138 by the high-level API, but using the low-level event API you can
139 register to receive these messages.
141 =head2 SETTING CALLBACKS TO HANDLE EVENTS
143 The child process generates events in some situations. Current events
144 include: receiving a reply message after some action, receiving a log
145 message, the child process exits, &c.
147 Use the C<guestfs_set_*_callback> functions to set a callback for
148 different types of events.
150 Only I<one callback of each type> can be registered for each handle.
151 Calling C<guestfs_set_*_callback> again overwrites the previous
152 callback of that type. Cancel all callbacks of this type by calling
153 this function with C<cb> set to C<NULL>.
155 =head2 NON-BLOCKING ACTIONS
157 C<guestfs_set_reply_callback> is the most interesting callback to
158 play with, since it allows you to perform actions without blocking.
165 guestfs_main_loop_run (); /* --> blocks, then calls my_cb */
170 guestfs_set_reply_callback (handle, my_cb, data);
171 guestfs_nb_[action] (handle, [other parameters ...]);
172 /* returns immediately */
175 my_cb (guestfs_h handle, void *data)
177 retval = guestfs_nb_[action]_r (handle);
181 There are C<guestfs_nb_*> and C<guestfs_nb_*_r> functions
182 corresponding to (very nearly) every C<guestfs_*> action in the
185 =head2 guestfs_set_reply_callback
187 void guestfs_set_reply_callback (guestfs_handle h,
191 The callback function C<cb> will be called whenever a reply is
192 received from the child process. (This corresponds to a transition
193 from the BUSY state to the READY state).
195 Note (I<important!>) that high-level API calls overwrite this
198 =head2 guestfs_set_log_message_callback
200 void guestfs_set_log_message_callback (guestfs_handle h,
201 guestfs_log_message_cb cb,
204 The callback function C<cb> will be called whenever qemu or the guest
205 writes anything to the console.
207 Use this function to capture kernel messages and similar.
209 Normally there is no log message handler, and log messages are just
212 =head2 guestfs_set_subprocess_quit_callback
214 void guestfs_set_subprocess_quit_callback (guestfs_handle h,
215 guestfs_subprocess_quit_cb cb,
218 The callback function C<cb> will be called when the child process
219 quits, either asynchronously or if killed by
220 C<guestfs_kill_subprocess>. (This corresponds to a transition from
221 any state to the CONFIG state).
223 =head2 guestfs_set_ready_callback
225 void guestfs_set_ready_callback (guestfs_handle h,
229 The callback function C<cb> will be called when the child process
230 becomes ready. (This corresponds to a transition from I<either>
231 LAUNCHING I<or> BUSY to the READY state).
233 You can use this instead of C<guestfs_wait_ready> to implement a
234 non-blocking wait for the child process to finish booting up.
236 =head2 EVENT MAIN LOOP
238 To use the low-level event API, you have to provide an event "main
239 loop". You can write your own, but if you don't want to write one,
240 two are provided for you:
244 =item libguestfs-poll
246 A simple main loop that is implemented using L<poll(2)>.
248 This is the default main loop unless you call C<guestfs_set_main_loop>
249 or C<guestfs_glib_set_main_loop>.
251 =item libguestfs-glib
253 An implementation which can be used with GLib and GTK+ programs. You
254 can use this to write graphical (GTK+) programs which use libguestfs
255 without hanging during long or slow operations.
259 =head2 guestfs_set_main_loop
261 void guestfs_set_main_loop (guestfs_main_loop *);
263 This call sets the current main loop to the list of callbacks
264 contained in the C<guestfs_main_loop> structure.
266 Only one main loop implementation can be used by libguestfs, so
267 calling this replaces the previous one. (So this is something that
268 has to be done by the main program, but only the main program "knows"
269 that it is a GTK+ program or whatever).
271 You should call this early in the main program, certainly before
272 calling C<guestfs_create>.
274 =head2 guestfs_glib_set_main_loop
276 void guestfs_glib_set_main_loop (GMainLoop *);
278 This helper calls C<guestfs_set_main_loop> with the correct callbacks
279 for integrating with the GLib main loop.
281 The libguestfs-glib main loop is contained in a separate library, so
282 that libguestfs doesn't depend on the whole of GLib:
285 #include <guestfs-glib.h>
290 g_main_loop_new (g_main_context_default (), 1);
292 guestfs_glib_set_main_loop (loop);
294 g_main_loop_run (loop);
297 To use this main loop you must link with C<-lguestfs-glib>. (See also
298 the GLib and GTK+ documentation).
300 =head2 guestfs_main_loop_run
302 void guestfs_main_loop_run (void);
304 This calls the main loop.
306 For some types of main loop you may want or prefer to call another
307 function, eg. C<g_main_loop_run>, or the main loop may already be
308 invoked by another part of your program. In those cases, ignore this
311 =head2 guestfs_main_loop_quit
313 void guestfs_main_loop_quit (void);
315 This instructs the main loop to quit. In other words,
316 C<guestfs_main_loop_run> will return.
318 For some types of main loop you may want or prefer to call another
319 function, eg. C<g_main_loop_quit>. In those cases, ignore this call.
321 =head2 WRITING A CUSTOM MAIN LOOP
323 This isn't documented. Please see the libguestfs-poll and libguestfs-glib
336 Richard W.M. Jones (C<rjones at redhat dot com>)
340 Copyright (C) 2009 Red Hat Inc.
341 L<http://et.redhat.com/~rjones/libguestfs>
343 This library is free software; you can redistribute it and/or
344 modify it under the terms of the GNU Lesser General Public
345 License as published by the Free Software Foundation; either
346 version 2 of the License, or (at your option) any later version.
348 This library is distributed in the hope that it will be useful,
349 but WITHOUT ANY WARRANTY; without even the implied warranty of
350 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
351 Lesser General Public License for more details.
353 You should have received a copy of the GNU Lesser General Public
354 License along with this library; if not, write to the Free Software
355 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA