+=head2 MULTIPLE HANDLES AND MULTIPLE THREADS
+
+All high-level libguestfs actions are synchronous. If you want
+to use libguestfs asynchronously then you must create a thread.
+
+Only use the handle from a single thread. Either use the handle
+exclusively from one thread, or provide your own mutex so that two
+threads cannot issue calls on the same handle at the same time.
+
+See the graphical program guestfs-browser for one possible
+architecture for multithreaded programs using libvirt and libguestfs.
+
+=head2 PATH
+
+Libguestfs needs a kernel and initrd.img, which it finds by looking
+along an internal path.
+
+By default it looks for these in the directory C<$libdir/guestfs>
+(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
+
+Use L</guestfs_set_path> or set the environment variable
+L</LIBGUESTFS_PATH> to change the directories that libguestfs will
+search in. The value is a colon-separated list of paths. The current
+directory is I<not> searched unless the path contains an empty element
+or C<.>. For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
+search the current directory and then C</usr/lib/guestfs>.
+
+=head2 QEMU WRAPPERS
+
+If you want to compile your own qemu, run qemu from a non-standard
+location, or pass extra arguments to qemu, then you can write a
+shell-script wrapper around qemu.
+
+There is one important rule to remember: you I<must C<exec qemu>> as
+the last command in the shell script (so that qemu replaces the shell
+and becomes the direct child of the libguestfs-using program). If you
+don't do this, then the qemu process won't be cleaned up correctly.
+
+Here is an example of a wrapper, where I have built my own copy of
+qemu from source:
+
+ #!/bin/sh -
+ qemudir=/home/rjones/d/qemu
+ exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
+
+Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
+and then use it by setting the LIBGUESTFS_QEMU environment variable.
+For example:
+
+ LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
+
+Note that libguestfs also calls qemu with the -help and -version
+options in order to determine features.
+
+=head2 ABI GUARANTEE
+
+We guarantee the libguestfs ABI (binary interface), for public,
+high-level actions as outlined in this section. Although we will
+deprecate some actions, for example if they get replaced by newer
+calls, we will keep the old actions forever. This allows you the
+developer to program in confidence against the libguestfs API.
+
+=head2 BLOCK DEVICE NAMING
+
+In the kernel there is now quite a profusion of schemata for naming
+block devices (in this context, by I<block device> I mean a physical
+or virtual hard drive). The original Linux IDE driver used names
+starting with C</dev/hd*>. SCSI devices have historically used a
+different naming scheme, C</dev/sd*>. When the Linux kernel I<libata>
+driver became a popular replacement for the old IDE driver
+(particularly for SATA devices) those devices also used the
+C</dev/sd*> scheme. Additionally we now have virtual machines with
+paravirtualized drivers. This has created several different naming
+systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
+PV disks.
+
+As discussed above, libguestfs uses a qemu appliance running an
+embedded Linux kernel to access block devices. We can run a variety
+of appliances based on a variety of Linux kernels.
+
+This causes a problem for libguestfs because many API calls use device
+or partition names. Working scripts and the recipe (example) scripts
+that we make available over the internet could fail if the naming
+scheme changes.
+
+Therefore libguestfs defines C</dev/sd*> as the I<standard naming
+scheme>. Internally C</dev/sd*> names are translated, if necessary,
+to other names as required. For example, under RHEL 5 which uses the
+C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
+C</dev/hda2> transparently.
+
+Note that this I<only> applies to parameters. The
+L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
+return the true names of the devices and partitions as known to the
+appliance.
+
+=head3 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
+
+Usually this translation is transparent. However in some (very rare)
+cases you may need to know the exact algorithm. Such cases include
+where you use L</guestfs_config> to add a mixture of virtio and IDE
+devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
+and C</dev/vd*> devices.
+
+The algorithm is applied only to I<parameters> which are known to be
+either device or partition names. Return values from functions such
+as L</guestfs_list_devices> are never changed.
+
+=over 4
+
+=item *
+
+Is the string a parameter which is a device or partition name?
+
+=item *
+
+Does the string begin with C</dev/sd>?
+
+=item *
+
+Does the named device exist? If so, we use that device.
+However if I<not> then we continue with this algorithm.
+
+=item *
+
+Replace initial C</dev/sd> string with C</dev/hd>.
+
+For example, change C</dev/sda2> to C</dev/hda2>.
+
+If that named device exists, use it. If not, continue.
+
+=item *
+
+Replace initial C</dev/sd> string with C</dev/vd>.
+
+If that named device exists, use it. If not, return an error.
+
+=back
+
+=head3 PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING
+
+Although the standard naming scheme and automatic translation is
+useful for simple programs and guestfish scripts, for larger programs
+it is best not to rely on this mechanism.
+
+Where possible for maximum future portability programs using
+libguestfs should use these future-proof techniques:
+
+=over 4
+
+=item *
+
+Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
+actual device names, and then use those names directly.
+
+Since those device names exist by definition, they will never be
+translated.
+
+=item *
+
+Use higher level ways to identify filesystems, such as LVM names,
+UUIDs and filesystem labels.
+
+=back
+
+=head1 SECURITY
+
+This section discusses security implications of using libguestfs,
+particularly with untrusted or malicious guests or disk images.
+
+=head2 GENERAL SECURITY CONSIDERATIONS
+
+Be careful with any files or data that you download from a guest (by
+"download" we mean not just the L</guestfs_download> command but any
+command that reads files, filenames, directories or anything else from
+a disk image). An attacker could manipulate the data to fool your
+program into doing the wrong thing. Consider cases such as:
+
+=over 4
+
+=item *
+
+the data (file etc) not being present
+
+=item *
+
+being present but empty
+
+=item *
+
+being much larger than normal
+
+=item *
+
+containing arbitrary 8 bit data
+
+=item *
+
+being in an unexpected character encoding
+
+=item *
+
+containing homoglyphs.
+
+=back
+
+=head2 SECURITY OF MOUNTING FILESYSTEMS
+
+When you mount a filesystem under Linux, mistakes in the kernel
+filesystem (VFS) module can sometimes be escalated into exploits by
+deliberately creating a malicious, malformed filesystem. These
+exploits are very severe for two reasons. Firstly there are very many
+filesystem drivers in the kernel, and many of them are infrequently
+used and not much developer attention has been paid to the code.
+Linux userspace helps potential crackers by detecting the filesystem
+type and automatically choosing the right VFS driver, even if that
+filesystem type is obscure or unexpected for the administrator.
+Secondly, a kernel-level exploit is like a local root exploit (worse
+in some ways), giving immediate and total access to the system right
+down to the hardware level.
+
+That explains why you should never mount a filesystem from an
+untrusted guest on your host kernel. How about libguestfs? We run a
+Linux kernel inside a qemu virtual machine, usually running as a
+non-root user. The attacker would need to write a filesystem which
+first exploited the kernel, and then exploited either qemu
+virtualization (eg. a faulty qemu driver) or the libguestfs protocol,
+and finally to be as serious as the host kernel exploit it would need
+to escalate its privileges to root. This multi-step escalation,
+performed by a static piece of data, is thought to be extremely hard
+to do, although we never say 'never' about security issues.
+
+In any case callers can reduce the attack surface by forcing the
+filesystem type when mounting (use L</guestfs_mount_vfs>).
+
+=head2 PROTOCOL SECURITY
+
+The protocol is designed to be secure, being based on RFC 4506 (XDR)
+with a defined upper message size. However a program that uses
+libguestfs must also take care - for example you can write a program
+that downloads a binary from a disk image and executes it locally, and
+no amount of protocol security will save you from the consequences.
+
+=head2 INSPECTION SECURITY
+
+Parts of the inspection API (see L</INSPECTION>) return untrusted
+strings directly from the guest, and these could contain any 8 bit
+data. Callers should be careful to escape these before printing them
+to a structured file (for example, use HTML escaping if creating a web
+page).
+
+The inspection API parses guest configuration using two external
+libraries: Augeas (Linux configuration) and hivex (Windows Registry).
+Both are designed to be robust in the face of malicious data, although
+denial of service attacks are still possible, for example with
+oversized configuration files.
+
+=head2 RUNNING UNTRUSTED GUEST COMMANDS
+
+Be very cautious about running commands from the guest. By running a
+command in the guest, you are giving CPU time to a binary that you do
+not control, under the same user account as the library, albeit
+wrapped in qemu virtualization. More information and alternatives can
+be found in the section L</RUNNING COMMANDS>.
+
+=head2 CVE-2010-3851
+
+https://bugzilla.redhat.com/642934
+
+This security bug concerns the automatic disk format detection that
+qemu does on disk images.
+
+A raw disk image is just the raw bytes, there is no header. Other
+disk images like qcow2 contain a special header. Qemu deals with this
+by looking for one of the known headers, and if none is found then
+assuming the disk image must be raw.
+
+This allows a guest which has been given a raw disk image to write
+some other header. At next boot (or when the disk image is accessed
+by libguestfs) qemu would do autodetection and think the disk image
+format was, say, qcow2 based on the header written by the guest.
+
+This in itself would not be a problem, but qcow2 offers many features,
+one of which is to allow a disk image to refer to another image
+(called the "backing disk"). It does this by placing the path to the
+backing disk into the qcow2 header. This path is not validated and
+could point to any host file (eg. "/etc/passwd"). The backing disk is
+then exposed through "holes" in the qcow2 disk image, which of course
+is completely under the control of the attacker.
+
+In libguestfs this is rather hard to exploit except under two
+circumstances:
+
+=over 4
+
+=item 1.
+
+You have enabled the network or have opened the disk in write mode.
+
+=item 2.
+
+You are also running untrusted code from the guest (see
+L</RUNNING COMMANDS>).
+
+=back
+
+The way to avoid this is to specify the expected disk format when
+adding disks (the optional C<format> option to
+L</guestfs_add_drive_opts>). You should always do this if the disk is
+raw format, and it's a good idea for other cases too.
+
+For disks added from libvirt using calls like L</guestfs_add_domain>,
+the format is fetched from libvirt and passed through.
+
+For libguestfs tools, use the I<--format> command line parameter as
+appropriate.
+
git.annexia.org / libguestfs.git / blobdiff