Libguestfs is a library that can be linked with C and C++ management
programs (or management programs written in OCaml, Perl, Python, Ruby,
-Java, PHP, Haskell or C#). You can also use it from shell scripts or the
-command line.
+Java, PHP, Erlang, Haskell or C#). You can also use it from shell
+scripts or the command line.
You don't need to be root to use libguestfs, although obviously you do
need enough permissions to access the disk images.
=item B<file> to B<file>
-Use L</guestfs_cp> to copy a single file, or
-L</guestfs_cp_a> to copy directories recursively.
+Use L</guestfs_cp> to copy a single file, or L</guestfs_cp_a> to copy
+directories recursively.
-=item B<file or device> to B<file or device>
+To copy part of a file (offset and size) use
+L</guestfs_copy_file_to_file>.
-Use L</guestfs_dd> which efficiently uses L<dd(1)>
-to copy between files and devices in the guest.
+=item B<file> to B<device>
+
+=item B<device> to B<file>
+
+=item B<device> to B<device>
+
+Use L</guestfs_copy_file_to_device>, L</guestfs_copy_device_to_file>,
+or L</guestfs_copy_device_to_device>.
Example: duplicate the contents of an LV:
- guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy");
+ guestfs_copy_device_to_device (g,
+ "/dev/VG/Original", "/dev/VG/Copy",
+ /* -1 marks the end of the list of optional parameters */
+ -1);
The destination (C</dev/VG/Copy>) must be at least as large as the
-source (C</dev/VG/Original>). To copy less than the whole
-source device, use L</guestfs_copy_size>.
+source (C</dev/VG/Original>). To copy less than the whole source
+device, use the optional C<size> parameter:
+
+ guestfs_copy_device_to_device (g,
+ "/dev/VG/Original", "/dev/VG/Copy",
+ GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
+ -1);
=item B<file on the host> to B<file or device>
The C# bindings are highly experimental. Please read the warnings
at the top of C<csharp/Libguestfs.cs>.
+=item B<Erlang>
+
+See L<guestfs-erlang(3)>.
+
=item B<Haskell>
This is the only language binding that is working but incomplete.
=item Mount option C<-o sync> should not be the default.
+I<Update:> L</guestfs_mount> no longer adds any options starting
+from libguestfs 1.13.16. This section only applies to older versions.
+
If you use L</guestfs_mount>, then C<-o sync,noatime> are added
implicitly. However C<-o sync> does not add any reliability benefit,
but does have a very large performance impact.
Note that libguestfs also calls qemu with the -help and -version
options in order to determine features.
+Wrappers can also be used to edit the options passed to qemu. In the
+following example, the C<-machine ...> option (C<-machine> and the
+following argument) are removed from the command line and replaced
+with C<-machine pc,accel=tcg>. The while loop iterates over the
+options until it finds the right one to remove, putting the remaining
+options into the C<args> array.
+
+ #!/bin/bash -
+
+ i=0
+ while [ $# -gt 0 ]; do
+ case "$1" in
+ -machine)
+ shift 2;;
+ *)
+ args[i]="$1"
+ (( i++ ))
+ shift ;;
+ esac
+ done
+
+ exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
+
=head2 ATTACHING TO RUNNING DAEMONS
I<Note (1):> This is B<highly experimental> and has a tendency to eat
can override the printing of trace messages to stderr by setting up a
callback.
+=item GUESTFS_EVENT_ENTER
+(payload type: function name)
+
+The callback function is called whenever a libguestfs function
+is entered.
+
+The payload is a string which contains the name of the function
+that we are entering (not including C<guestfs_> prefix).
+
+Note that libguestfs functions can call themselves, so you may
+see many events from a single call. A few libguestfs functions
+do not generate this event.
+
+If no callback is registered: the event is ignored.
+
=back
=head3 guestfs_set_event_callback
might not terminate unless you also maintain an indication of which
keys have been visited.
+=head1 SYSTEMTAP
+
+The libguestfs C library can be probed using systemtap or DTrace.
+This is true of any library, not just libguestfs. However libguestfs
+also contains static markers to help in probing internal operations.
+
+You can list all the static markers by doing:
+
+ stap -l 'process("/usr/lib*/libguestfs.so.0")
+ .provider("guestfs").mark("*")'
+
+B<Note:> These static markers are I<not> part of the stable API and
+may change in future versions.
+
+=head2 SYSTEMTAP SCRIPT EXAMPLE
+
+This script contains examples of displaying both the static markers
+and some ordinary C entry points:
+
+ global last;
+
+ function display_time () {
+ now = gettimeofday_us ();
+ delta = 0;
+ if (last > 0)
+ delta = now - last;
+ last = now;
+
+ printf ("%d (+%d):", now, delta);
+ }
+
+ probe begin {
+ last = 0;
+ printf ("ready\n");
+ }
+
+ /* Display all calls to static markers. */
+ probe process("/usr/lib*/libguestfs.so.0")
+ .provider("guestfs").mark("*") ? {
+ display_time();
+ printf ("\t%s %s\n", $$name, $$parms);
+ }
+
+ /* Display all calls to guestfs_mkfs* functions. */
+ probe process("/usr/lib*/libguestfs.so.0")
+ .function("guestfs_mkfs*") ? {
+ display_time();
+ printf ("\t%s %s\n", probefunc(), $$parms);
+ }
+
+The script above can be saved to C<test.stap> and run using the
+L<stap(1)> program. Note that you either have to be root, or you have
+to add yourself to several special stap groups. Consult the systemtap
+documentation for more information.
+
+ # stap /tmp/test.stap
+ ready
+
+In another terminal, run a guestfish command such as this:
+
+ guestfish -N fs
+
+In the first terminal, stap trace output similar to this is shown:
+
+ 1318248056692655 (+0): launch_start
+ 1318248056692850 (+195): launch_build_appliance_start
+ 1318248056818285 (+125435): launch_build_appliance_end
+ 1318248056838059 (+19774): launch_run_qemu
+ 1318248061071167 (+4233108): launch_end
+ 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
+
=begin html
<!-- old anchor for the next section -->
=head1 INTERNALS
+=head2 APPLIANCE BOOT PROCESS
+
+This process has evolved and continues to evolve. The description
+here corresponds only to the current version of libguestfs and is
+provided for information only.
+
+In order to follow the stages involved below, enable libguestfs
+debugging (set the environment variable C<LIBGUESTFS_DEBUG=1>).
+
+=over 4
+
+=item Create the appliance
+
+C<febootstrap-supermin-helper> is invoked to create the kernel, a
+small initrd and the appliance.
+
+The appliance is cached in C</var/tmp/.guestfs-E<lt>UIDE<gt>> (or in
+another directory if C<TMPDIR> is set).
+
+For a complete description of how the appliance is created and cached,
+read the L<febootstrap(8)> and L<febootstrap-supermin-helper(8)> man
+pages.
+
+=item Start qemu and boot the kernel
+
+qemu is invoked to boot the kernel.
+
+=item Run the initrd
+
+C<febootstrap-supermin-helper> builds a small initrd. The initrd is
+not the appliance. The purpose of the initrd is to load enough kernel
+modules in order that the appliance itself can be mounted and started.
+
+The initrd is a cpio archive called
+C</var/tmp/.guestfs-E<lt>UIDE<gt>/initrd>.
+
+When the initrd has started you will see messages showing that kernel
+modules are being loaded, similar to this:
+
+ febootstrap: ext2 mini initrd starting up
+ febootstrap: mounting /sys
+ febootstrap: internal insmod libcrc32c.ko
+ febootstrap: internal insmod crc32c-intel.ko
+
+=item Find and mount the appliance device
+
+The appliance is a sparse file containing an ext2 filesystem which
+contains a familiar (although reduced in size) Linux operating system.
+It would normally be called C</var/tmp/.guestfs-E<lt>UIDE<gt>/root>.
+
+The regular disks being inspected by libguestfs are the first
+devices exposed by qemu (eg. as C</dev/vda>).
+
+The last disk added to qemu is the appliance itself (eg. C</dev/vdb>
+if there was only one regular disk).
+
+Thus the final job of the initrd is to locate the appliance disk,
+mount it, and switch root into the appliance, and run C</init> from
+the appliance.
+
+If this works successfully you will see messages such as:
+
+ febootstrap: picked /sys/block/vdb/dev as root device
+ febootstrap: creating /dev/root as block special 252:16
+ febootstrap: mounting new root on /root
+ febootstrap: chroot
+ Starting /init script ...
+
+Note that C<Starting /init script ...> indicates that the appliance's
+init script is now running.
+
+=item Initialize the appliance
+
+The appliance itself now initializes itself. This involves starting
+certain processes like C<udev>, possibly printing some debug
+information, and finally running the daemon (C<guestfsd>).
+
+=item The daemon
+
+Finally the daemon (C<guestfsd>) runs inside the appliance. If it
+runs you should see:
+
+ verbose daemon enabled
+
+The daemon expects to see a named virtio-serial port exposed by qemu
+and connected on the other end to the library.
+
+The daemon connects to this port (and hence to the library) and sends
+a four byte message C<GUESTFS_LAUNCH_FLAG>, which initiates the
+communication protocol (see below).
+
+=back
+
=head2 COMMUNICATION PROTOCOL
Don't rely on using this protocol directly. This section documents
=over 4
+=item C<align>
+
+L<virt-alignment-scan(1)> command and documentation.
+
=item C<appliance>
The libguestfs appliance, build scripts and so on.
The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
and documentation.
-=item C<caution>
+=item C<clone>
-Safety and liveness tests of components that libguestfs depends upon
-(not of libguestfs itself). Mainly this is for qemu and the kernel.
+Tools for cloning virtual machines. Currently contains
+L<virt-sysprep(1)> command and documentation.
=item C<contrib>
C API example code.
+=item C<extratests>
+
+Extra tests. These are not run by default because they require
+special tools or configuration.
+
=item C<fish>
L<guestfish(1)>, the command-line shell, and various shell scripts
L<virt-rescue(1)> command and documentation.
-=item C<src>
+=item C<resize>
-Source code to the C library.
+L<virt-resize(1)> command and documentation.
-=item C<tools>
+=item C<sparsify>
+
+L<virt-sparsify(1)> command and documentation.
+
+=item C<src>
-Command line tools written in Perl (L<virt-resize(1)> and many others).
+Source code to the C library.
=item C<test-tool>
Test tool for end users to test if their qemu/kernel combination
will work with libguestfs.
+=item C<tests>
+
+Tests.
+
+=item C<tools>
+
+Command line tools written in Perl (L<virt-win-reg(1)> and many others).
+
=item C<csharp>
+=item C<erlang>
+
=item C<haskell>
=item C<java>
=head1 SEE ALSO
L<guestfs-examples(3)>,
+L<guestfs-erlang(3)>,
L<guestfs-java(3)>,
L<guestfs-ocaml(3)>,
L<guestfs-perl(3)>,
L<guestfs-ruby(3)>,
L<guestfish(1)>,
L<guestmount(1)>,
+L<virt-alignment-scan(1)>,
L<virt-cat(1)>,
L<virt-copy-in(1)>,
L<virt-copy-out(1)>,
L<virt-ls(1)>,
L<virt-make-fs(1)>,
L<virt-rescue(1)>,
+L<virt-resize(1)>,
+L<virt-sparsify(1)>,
+L<virt-sysprep(1)>,
L<virt-tar(1)>,
L<virt-tar-in(1)>,
L<virt-tar-out(1)>,
L<virt-win-reg(1)>,
+L<guestfs-testing(1)>,
L<qemu(1)>,
L<febootstrap(1)>,
L<febootstrap-supermin-helper(8)>,
L<hivex(3)>,
+L<stap(1)>,
L<http://libguestfs.org/>.
Tools with a similar purpose:
git.annexia.org / libguestfs.git / blobdiff