guestfs_h *handle = guestfs_create ();
guestfs_add_drive (handle, "guest.img");
guestfs_launch (handle);
- guestfs_wait_ready (handle);
guestfs_mount (handle, "/dev/sda1", "/");
guestfs_touch (handle, "/hello");
guestfs_sync (handle);
*/
guestfs_launch (handle);
- guestfs_wait_ready (handle);
/* now you can examine what partitions, LVs etc are available
* you have to mount / at least
guestfs_close (handle);
-C<guestfs_wait_ready> and all of the actions including C<guestfs_sync>
+C<guestfs_launch> and all of the actions including C<guestfs_sync>
are blocking calls. You can use the low-level event API to do
non-blocking operations instead.
All functions that return integers, return C<-1> on error. See
-section ERROR HANDLING below for how to handle errors.
+section L</ERROR HANDLING> below for how to handle errors.
=head2 guestfs_h *
to free the handle and release all resources used.
For information on using multiple handles and threads, see the section
-MULTIPLE HANDLES AND MULTIPLE THREADS below.
+L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
=head2 guestfs_create
This function returns a non-NULL pointer to a handle on success or
NULL on error.
-After configuring the handle, you have to call C<guestfs_launch> and
-C<guestfs_wait_ready>.
+After configuring the handle, you have to call C<guestfs_launch>.
You may also want to configure error handling for the handle. See
-ERROR HANDLING section below.
+L</ERROR HANDLING> section below.
=head2 guestfs_close
=head2 PARTITIONING
-To create MBR-style (ie. normal PC) partitions use one of the
-C<guestfs_sfdisk*> variants. These calls use the external
-L<sfdisk(8)> command.
+In the common case where you want to create a single partition
+covering the whole disk, you should use the C<guestfs_part_disk>
+call:
-The simplest call is:
-
- char *lines[] = { ",", NULL };
- guestfs_sfdiskM (g, "/dev/sda", lines);
-
-This will create a single partition on C</dev/sda> called
-C</dev/sda1> covering the whole disk.
+ const char *parttype = "mbr";
+ if (disk_is_larger_than_2TB)
+ parttype = "gpt";
+ guestfs_part_disk (g, "/dev/sda", parttype);
In general MBR partitions are both unnecessarily complicated and
depend on archaic details, namely the Cylinder-Head-Sector (CHS)
-geometry of the disk. C<guestfs_sfdiskM> allows you to specify sizes
-in megabytes instead of cylinders, which is a small win.
+geometry of the disk. C<guestfs_sfdiskM> can be used to
+create more complex arrangements where the relative sizes are
+expressed in megabytes instead of cylinders, which is a small win.
C<guestfs_sfdiskM> will choose the nearest cylinder to approximate the
requested size. There's a lot of crazy stuff to do with IDE and
virtio disks having different, incompatible CHS geometries, that you
-probably don't want to know about. My advice: make a single partition
-to cover the whole disk, then use LVM on top.
+probably don't want to know about.
-In future we aim to provide access to libparted.
+My advice: make a single partition to cover the whole disk, then use
+LVM on top.
=head2 UPLOADING
Architecture limitations (eg. won't work for a PPC guest on
an X86 host).
+=item *
+
+For SELinux guests, you may need to enable SELinux and load policy
+first. See L</SELINUX> in this manpage.
+
=back
The two main API calls to run commands are C<guestfs_command> and
C<guestfs_find> can be used to recursively list files.
+=head2 SELINUX
+
+We support SELinux guests. To ensure that labeling happens correctly
+in SELinux guests, you need to enable SELinux and load the guest's
+policy:
+
+=over 4
+
+=item 1.
+
+Before launching, do:
+
+ guestfs_set_selinux (g, 1);
+
+=item 2.
+
+After mounting the guest's filesystem(s), load the policy. This
+is best done by running the L<load_policy(8)> command in the
+guest itself:
+
+ guestfs_sh (g, "/usr/sbin/load_policy");
+
+(Older versions of C<load_policy> require you to specify the
+name of the policy file).
+
+=item 3.
+
+Optionally, set the security context for the API. The correct
+security context to use can only be known by inspecting the
+guest. As an example:
+
+ guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
+
+=back
+
+This will work for running commands and editing existing files.
+
+When new files are created, you may need to label them explicitly,
+for example by running the external command
+C<restorecon pathname>.
+
=head1 HIGH-LEVEL API ACTIONS
=head2 ABI GUARANTEE
/ | | LAUNCHING |
/ | \___________/
/ | /
- / | guestfs_wait_ready
+ / | guestfs_launch
/ | /
______ / __|____V
/ \ ------> / \
be issued when in the CONFIG state.
The high-level API offers two calls that go from CONFIG through
-LAUNCHING to READY. C<guestfs_launch> is a non-blocking call that
-starts up the child process, immediately moving from CONFIG to
-LAUNCHING. C<guestfs_wait_ready> blocks until the child process is
-READY to accept commands (or until some failure or timeout). The
-low-level event API described below provides a non-blocking way to
-replace C<guestfs_wait_ready>.
+LAUNCHING to READY. C<guestfs_launch> blocks until the child process
+is READY to accept commands (or until some failure or timeout).
+C<guestfs_launch> internally moves the state from CONFIG to LAUNCHING
+while it is running.
High-level API actions such as C<guestfs_mount> can only be issued
when in the READY state. These high-level API calls block waiting for
=head2 SETTING CALLBACKS TO HANDLE EVENTS
The child process generates events in some situations. Current events
-include: receiving a reply message after some action, receiving a log
-message, the child process exits, &c.
+include: receiving a log message, the child process exits.
Use the C<guestfs_set_*_callback> functions to set a callback for
different types of events.
callback of that type. Cancel all callbacks of this type by calling
this function with C<cb> set to C<NULL>.
-=head2 NON-BLOCKING ACTIONS
-
-XXX This section was documented in previous versions but never
-implemented in a way which matched the documentation. For now I have
-removed the documentation, pending a working implementation. See also
-C<src/guestfs-actions.c> in the source.
-
-
-=head2 guestfs_set_send_callback
-
- typedef void (*guestfs_send_cb) (guestfs_h *g, void *opaque);
- void guestfs_set_send_callback (guestfs_h *handle,
- guestfs_send_cb cb,
- void *opaque);
-
-The callback function C<cb> will be called whenever a message
-which is queued for sending, has been sent.
-
-=head2 guestfs_set_reply_callback
-
- typedef void (*guestfs_reply_cb) (guestfs_h *g, void *opaque, XDR *xdr);
- void guestfs_set_reply_callback (guestfs_h *handle,
- guestfs_reply_cb cb,
- void *opaque);
-
-The callback function C<cb> will be called whenever a reply is
-received from the child process. (This corresponds to a transition
-from the BUSY state to the READY state).
-
-Note that the C<xdr> that you get in the callback is in C<XDR_DECODE>
-mode, and you need to consume it before you return from the callback
-function (since it gets destroyed after).
-
=head2 guestfs_set_log_message_callback
typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
becomes ready first time after it has been launched. (This
corresponds to a transition from LAUNCHING to the READY state).
-You can use this instead of C<guestfs_wait_ready> to implement a
-non-blocking wait for the child process to finish booting up.
-
-=head2 EVENT MAIN LOOP
-
-To use the low-level event API and/or to use handles from multiple
-threads, you have to provide an event "main loop". You can write your
-own, but if you don't want to write one, two types are provided for
-you:
-
-=over 4
-
-=item libguestfs-select
-
-A simple main loop that is implemented using L<select(2)>.
-
-This is the default main loop for new guestfs handles, unless you
-call C<guestfs_set_main_loop> after a handle is created.
-
-=item libguestfs-glib
-
-An implementation which can be used with GLib and GTK+ programs. You
-can use this to write graphical (GTK+) programs which use libguestfs
-without hanging during long or slow operations.
-
-=back
-
-=head2 MULTIPLE HANDLES AND MULTIPLE THREADS
-
-The support for multiple handles and multiple threads is modelled
-after glib (although doesn't require glib, if you use the select-based
-main loop).
-
-L<http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html>
-
-You will need to create one main loop for each thread that wants to
-use libguestfs. Each guestfs handle should be confined to one thread.
-If you try to pass guestfs handles between threads, you will get
-undefined results.
-
-If you only want to use guestfs handles from one thread in your
-program, but your program has other threads doing other things, then
-you don't need to do anything special.
-
-=head2 SINGLE THREAD CASE
-
-In the single thread case, there is a single select-based main loop
-created for you. All guestfs handles will use this main loop to
-execute high level API actions.
-
-=head2 MULTIPLE THREADS CASE
-
-In the multiple threads case, you will need to create a main loop for
-each thread that wants to use libguestfs.
-
-To create main loops for other threads, use
-C<guestfs_create_main_loop> or C<guestfs_glib_create_main_loop>.
-
-Then you will need to attach each handle to the thread-specific main
-loop by calling:
-
- handle = guestfs_create ();
- guestfs_set_main_loop (handle, main_loop_of_current_thread);
-
-=head2 guestfs_set_main_loop
-
- void guestfs_set_main_loop (guestfs_h *handle,
- guestfs_main_loop *main_loop);
-
-Sets the main loop used by high level API actions for this handle. By
-default, the select-based main loop is used (see
-C<guestfs_get_default_main_loop>).
-
-You only need to use this in multi-threaded programs, where multiple
-threads want to use libguestfs. Create a main loop for each thread,
-then call this function.
-
-You cannot pass guestfs handles between threads.
-
-=head2 guestfs_get_main_loop
-
- guestfs_main_loop *guestfs_get_main_loop (guestfs_h *handle);
-
-Return the main loop used by C<handle>.
-
-=head2 guestfs_get_default_main_loop
-
- guestfs_main_loop *guestfs_get_default_main_loop (void);
-
-Return the default select-based main loop.
-
-=head2 guestfs_create_main_loop
-
- guestfs_main_loop *guestfs_create_main_loop (void);
-
-This creates a select-based main loop. You should create one main
-loop for each additional thread that needs to use libguestfs.
-
-=head2 guestfs_free_main_loop
-
- void guestfs_free_main_loop (guestfs_main_loop *);
-
-Free the select-based main loop which was previously allocated with
-C<guestfs_create_main_loop>.
-
-=head2 WRITING A CUSTOM MAIN LOOP
-
-This isn't documented. Please see the libguestfs-select and
-libguestfs-glib implementations.
-
=head1 BLOCK DEVICE NAMING
In the kernel there is now quite a profusion of schemata for naming
Because the underlying channel (QEmu -net channel) doesn't have any
sort of connection control, when the daemon launches it sends an
initial word (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
-and daemon is alive. This is what C<guestfs_wait_ready> waits for.
+and daemon is alive. This is what C<guestfs_launch> waits for.
=head1 QEMU WRAPPERS
Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This
has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
-=item LIBGUESTFS_KERNEL
-
-Override the ordinary selection of appliance kernel.
-
=item LIBGUESTFS_MEMSIZE
Set the memory allocated to the qemu process, in megabytes. For
the qemu which was found at compile time by the configure script is
used.
-See also L<QEMU WRAPPERS> above.
+See also L</QEMU WRAPPERS> above.
+
+=item LIBGUESTFS_TRACE
+
+Set C<LIBGUESTFS_TRACE=1> to enable command traces. This
+has the same effect as calling C<guestfs_set_trace (handle, 1)>.
=item TMPDIR
L<febootstrap(1)>,
L<http://libguestfs.org/>.
+Tools with a similar purpose:
+L<fdisk(8)>,
+L<parted(8)>,
+L<kpartx(8)>,
+L<lvm(8)>,
+L<disktype(1)>.
+
=head1 BUGS
To get a list of bugs against libguestfs use this link:
Describe the bug accurately, and give a way to reproduce it.
+=item *
+
+Run libguestfs-test-tool and paste the B<complete, unedited>
+output into the bug report.
+
=back
=head1 AUTHORS
git.annexia.org / libguestfs.git / blobdiff