From 8980c01b46eafcf4b5dc127e4696c2cbe1bff09f Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Thu, 31 Dec 2009 12:26:04 +0000 Subject: Move guestfs(3) and guestfish(1) man pages into subdirectories. These manual pages have for a very long time 'lived' in the top source directory. Clean up this situation by moving those manual pages (plus associated generated files) into the src/ and fish/ subdirectories respectively. --- Makefile.am | 58 +-- fish/Makefile.am | 20 +- fish/guestfish.pod | 749 ++++++++++++++++++++++++++++++ guestfish.pod | 749 ------------------------------ guestfs.pod | 1300 ---------------------------------------------------- libguestfs.3 | 1 - src/Makefile.am | 34 +- src/generator.ml | 8 +- src/guestfs.pod | 1300 ++++++++++++++++++++++++++++++++++++++++++++++++++++ src/libguestfs.3 | 1 + 10 files changed, 2112 insertions(+), 2108 deletions(-) create mode 100644 fish/guestfish.pod delete mode 100644 guestfish.pod delete mode 100644 guestfs.pod delete mode 100644 libguestfs.3 create mode 100644 src/guestfs.pod create mode 100644 src/libguestfs.3 diff --git a/Makefile.am b/Makefile.am index c33710ad..38beecdb 100644 --- a/Makefile.am +++ b/Makefile.am @@ -56,16 +56,8 @@ if HAVE_HASKELL SUBDIRS += haskell endif -generator_built = \ - guestfs-actions.pod \ - guestfs-availability.pod \ - guestfs-structs.pod \ - guestfish-actions.pod - EXTRA_DIST = \ $(generator_built) \ - guestfs.pod \ - guestfish.pod \ html/pod.css \ HACKING TODO \ libguestfs.pc libguestfs.pc.in \ @@ -77,52 +69,16 @@ EXTRA_DIST = \ html/recipes.css \ make-recipes.sh \ contrib/README \ - bindtests \ - libguestfs.3 - -# Manual pages. -# guestfs-actions.pod, guestfs-availability.pod and guestfs-structs -# are autogenerated. There is no include mechanism for POD, so we -# have to do it by hand. + bindtests -man_MANS = guestfs.3 libguestfs.3 guestfish.1 - -guestfs.3: guestfs.pod \ - guestfs-actions.pod \ - guestfs-availability.pod \ - guestfs-structs.pod - sed \ - -e '/@ACTIONS@/rguestfs-actions.pod' \ - -e 's/@ACTIONS@//' \ - -e '/@AVAILABILITY@/rguestfs-availability.pod' \ - -e 's/@AVAILABILITY@//' \ - -e '/@STRUCTS@/rguestfs-structs.pod' \ - -e 's/@STRUCTS@//' \ - < $< | \ - $(POD2MAN) \ - --section 3 \ - -c "Virtualization Support" \ - --name "guestfs" \ - --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ - > $@ - -guestfish.1: guestfish.pod guestfish-actions.pod - sed \ - -e '/@ACTIONS@/rguestfish-actions.pod' -e 's/@ACTIONS@//' \ - < $< | \ - $(POD2MAN) \ - --section 1 \ - -c "Virtualization Support" \ - --name "guestfish" \ - --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ - > $@ +# HTML versions of manual pages. noinst_DATA = html/guestfs.3.html html/guestfish.1.html -html/guestfs.3.html: guestfs.pod \ - guestfs-actions.pod \ - guestfs-availability.pod \ - guestfs-structs.pod +html/guestfs.3.html: src/guestfs.pod \ + src/guestfs-actions.pod \ + src/guestfs-availability.pod \ + src/guestfs-structs.pod mkdir -p html sed \ -e '/@ACTIONS@/rguestfs-actions.pod' \ @@ -138,7 +94,7 @@ html/guestfs.3.html: guestfs.pod \ --htmldir html \ --outfile $@ -html/guestfish.1.html: guestfish.pod guestfish-actions.pod +html/guestfish.1.html: fish/guestfish.pod fish/guestfish-actions.pod mkdir -p html sed \ -e '/@ACTIONS@/rguestfish-actions.pod' -e 's/@ACTIONS@//' \ diff --git a/fish/Makefile.am b/fish/Makefile.am index 795952a9..1652c545 100644 --- a/fish/Makefile.am +++ b/fish/Makefile.am @@ -21,7 +21,8 @@ bin_PROGRAMS = guestfish generator_built = \ cmds.c \ - completion.c + completion.c \ + guestfish-actions.pod BUILT_SOURCES = \ $(generator_built) \ @@ -79,3 +80,20 @@ rc_protocol.h: rc_protocol.x $(RPCGEN) -h -o $@-t $< mv $@-t $@ endif + +# Manual page. +# guestfish-actions.pod is autogenerated. There is no include +# mechanism for POD, so we have to do it by hand. + +man_MANS = guestfish.1 + +guestfish.1: guestfish.pod guestfish-actions.pod + sed \ + -e '/@ACTIONS@/rguestfish-actions.pod' -e 's/@ACTIONS@//' \ + < $< | \ + $(POD2MAN) \ + --section 1 \ + -c "Virtualization Support" \ + --name "guestfish" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + > $@ diff --git a/fish/guestfish.pod b/fish/guestfish.pod new file mode 100644 index 00000000..13a9fa7d --- /dev/null +++ b/fish/guestfish.pod @@ -0,0 +1,749 @@ +=encoding utf8 + +=head1 NAME + +guestfish - the libguestfs Filesystem Interactive SHell + +=head1 SYNOPSIS + + guestfish [--options] [commands] + + guestfish + + guestfish -a disk.img + + guestfish -a disk.img -m dev[:mountpoint] + + guestfish -i libvirt-domain + + guestfish -i disk.img [disk.img ...] + +=head1 EXAMPLES + +=head2 As an interactive shell + + $ guestfish + + Welcome to guestfish, the libguestfs filesystem interactive shell for + editing virtual machine filesystems. + + Type: 'help' for help with commands + 'quit' to quit the shell + + > help + +=head2 From shell scripts + +Create a new C file in a guest: + + guestfish <<_EOF_ + add disk.img + run + mount /dev/vg_guest/lv_root / + write_file /etc/motd "Welcome, new users" 0 + _EOF_ + +List the LVM logical volumes in a guest: + + guestfish -a disk.img --ro <<_EOF_ + run + lvs + _EOF_ + +=head2 On one command line + +Update C in a guest: + + guestfish \ + add disk.img : run : mount /dev/vg_guest/lv_root / : \ + write-file /etc/resolv.conf "nameserver 1.2.3.4" 0 + +Edit C interactively: + + guestfish --add disk.img \ + --mount /dev/vg_guest/lv_root \ + --mount /dev/sda1:/boot \ + edit /boot/grub/grub.conf + +=head2 Using virt-inspector + +Use the I<-i> option to get virt-inspector to mount +the filesystems automatically as they would be mounted +in the virtual machine: + + guestfish --ro -i disk.img cat /etc/group + +=head2 As a script interpreter + +Create a 50MB disk containing an ext2-formatted partition: + + #!/usr/bin/guestfish -f + alloc /tmp/output.img 50M + run + part-disk /dev/sda mbr + mkfs ext2 /dev/sda1 + +=head2 Remote control + + eval `guestfish --listen --ro` + guestfish --remote add disk.img + guestfish --remote run + guestfish --remote lvs + +=head1 DESCRIPTION + +Guestfish is a shell and command-line tool for examining and modifying +virtual machine filesystems. It uses libguestfs and exposes all of +the functionality of the guestfs API, see L. + +Guestfish gives you structured access to the libguestfs API, from +shell scripts or the command line or interactively. If you want to +rescue a broken virtual machine image, you might want to look at the +L command. + +Using guestfish in read/write mode on live virtual machines can be +dangerous, potentially causing disk corruption. Use the I<--ro> +(read-only) option to use guestfish safely if the disk image or +virtual machine might be live. + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Displays general help on options. + +=item B<-h> | B<--cmd-help> + +Lists all available guestfish commands. + +=item B<-h cmd> | B<--cmd-help cmd> + +Displays detailed help on a single command C. + +=item B<-a image> | B<--add image> + +Add a block device or virtual machine image to the shell. + +=item B<-D> | B<--no-dest-paths> + +Don't tab-complete paths on the guest filesystem. It is useful to be +able to hit the tab key to complete paths on the guest filesystem, but +this causes extra "hidden" guestfs calls to be made, so this option is +here to allow this feature to be disabled. + +=item B<-f file> | B<--file file> + +Read commands from C. To write pure guestfish +scripts, use: + + #!/usr/bin/guestfish -f + +=item B<-i> | B<--inspector> + +Run virt-inspector on the named libvirt domain or list of disk +images. If virt-inspector is available and if it can identify +the domain or disk images, then partitions will be mounted +correctly at start-up. + +Typical usage is either: + + guestfish -i myguest + +(for an inactive libvirt domain called I), or: + + guestfish --ro -i myguest + +(for active domains, readonly), or specify the block device directly: + + guestfish -i /dev/Guests/MyGuest + +You cannot use I<-a>, I<-m>, I<--listen>, I<--remote> or I<--selinux> +in conjunction with this option, and options other than I<--ro> might +not behave correctly. + +See also: L. + +=item B<--listen> + +Fork into the background and listen for remote commands. See section +I below. + +=item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]> + +Mount the named partition or logical volume on the given mountpoint. + +If the mountpoint is omitted, it defaults to C. + +You have to mount something on C before most commands will work. + +If any C<-m> or C<--mount> options are given, the guest is +automatically launched. + +If you don't know what filesystems a disk image contains, you +can either run guestfish without this option, then list the partitions +and LVs available (see L and L commands), +or you can use the L program. + +=item B<-n> | B<--no-sync> + +Disable autosync. This is enabled by default. See the discussion +of autosync in the L manpage. + +=item B<--remote[=pid]> + +Send remote commands to C<$GUESTFISH_PID> or C. See section +I below. + +=item B<-r> | B<--ro> + +This changes the C<-a> and C<-m> options so that disks are added and +mounts are done read-only (see L). + +The option must always be used if the disk image or virtual machine +might be running, and is generally recommended in cases where you +don't need write access to the disk. + +=item B<--selinux> + +Enable SELinux support for the guest. See L. + +=item B<-v> | B<--verbose> + +Enable very verbose messages. This is particularly useful if you find +a bug. + +=item B<-V> | B<--version> + +Display the guestfish / libguestfs version number and exit. + +=item B<-x> + +Echo each command before executing it. + +=back + +=head1 COMMANDS ON COMMAND LINE + +Any additional (non-option) arguments are treated as commands to +execute. + +Commands to execute should be separated by a colon (C<:>), where the +colon is a separate parameter. Thus: + + guestfish cmd [args...] : cmd [args...] : cmd [args...] ... + +If there are no additional arguments, then we enter a shell, either an +interactive shell with a prompt (if the input is a terminal) or a +non-interactive shell. + +In either command line mode or non-interactive shell, the first +command that gives an error causes the whole shell to exit. In +interactive mode (with a prompt) if a command fails, you can continue +to enter commands. + +=head1 USING launch (OR run) + +As with L, you must first configure your guest by adding +disks, then launch it, then mount any disks you need, and finally +issue actions/commands. So the general order of the day is: + +=over 4 + +=item * + +add or -a/--add + +=item * + +launch (aka run) + +=item * + +mount or -m/--mount + +=item * + +any other commands + +=back + +C is a synonym for C. You must C (or C) +your guest before mounting or performing any other commands. + +The only exception is that if the C<-m> or C<--mount> option was +given, the guest is automatically run for you (simply because +guestfish can't mount the disks you asked for without doing this). + +=head1 QUOTING + +You can quote ordinary parameters using either single or double +quotes. For example: + + add "file with a space.img" + + rm '/file name' + + rm '/"' + +A few commands require a list of strings to be passed. For these, use +a whitespace-separated list, enclosed in quotes. Strings containing whitespace +to be passed through must be enclosed in single quotes. A literal single quote +must be escaped with a backslash. + + vgcreate VG "/dev/sda1 /dev/sdb1" + command "/bin/echo 'foo bar'" + command "/bin/echo \'foo\'" + +=head1 WILDCARDS AND GLOBBING + +Neither guestfish nor the underlying guestfs API performs +wildcard expansion (globbing) by default. So for example the +following will not do what you expect: + + rm-rf /home/* + +Assuming you don't have a directory literally called C +then the above command will return an error. + +To perform wildcard expansion, use the C command. + + glob rm-rf /home/* + +runs C on each path that matches (ie. potentially running +the command many times), equivalent to: + + rm-rf /home/jim + rm-rf /home/joe + rm-rf /home/mary + +C only works on simple guest paths and not on device names. + +If you have several parameters, each containing a wildcard, then glob +will perform a cartesian product. + +=head1 COMMENTS + +Any line which starts with a I<#> character is treated as a comment +and ignored. The I<#> can optionally be preceeded by whitespace, +but B by a command. For example: + + # this is a comment + # this is a comment + foo # NOT a comment + +Blank lines are also ignored. + +=head1 RUNNING COMMANDS LOCALLY + +Any line which starts with a I character is treated as a command +sent to the local shell (C or whatever L uses). +For example: + + !mkdir local + tgz-out /remote local/remote-data.tar.gz + +will create a directory C on the host, and then export +the contents of C on the mounted filesystem to +C. (See C). + +=head1 PIPES + +Use CspaceE | command> to pipe the output of the +first command (a guestfish command) to the second command (any host +command). For example: + + cat /etc/passwd | awk -F: '$3 == 0 { print }' + +(where C is the guestfish cat command, but C is the host awk +program). The above command would list all accounts in the guest +filesystem which have UID 0, ie. root accounts including backdoors. +Other examples: + + hexdump /bin/ls | head + list-devices | tail -1 + +The space before the pipe symbol is required, any space after the pipe +symbol is optional. Everything after the pipe symbol is just passed +straight to the host shell, so it can contain redirections, globs and +anything else that makes sense on the host side. + +To use a literal argument which begins with a pipe symbol, you have +to quote it, eg: + + echo "|" + +=head1 HOME DIRECTORIES + +If a parameter starts with the character C<~> then the tilde may be +expanded as a home directory path (either C<~> for the current user's +home directory, or C<~user> for another user). + +Note that home directory expansion happens for users known I, not in the guest filesystem. + +To use a literal argument which begins with a tilde, you have to quote +it, eg: + + echo "~" + +=head1 WINDOWS PATHS + +If a path is prefixed with C then you can use Windows-style +paths (with some limitations). The following commands are equivalent: + + file /WINDOWS/system32/config/system.LOG + + file win:/windows/system32/config/system.log + + file win:\windows\system32\config\system.log + + file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG + +This syntax implicitly calls C (q.v.) so it also +handles case insensitivity like Windows would. This only works in +argument positions that expect a path. + +=head1 EXIT ON ERROR BEHAVIOUR + +By default, guestfish will ignore any errors when in interactive mode +(ie. taking commands from a human over a tty), and will exit on the +first error in non-interactive mode (scripts, commands given on the +command line). + +If you prefix a command with a I<-> character, then that command will +not cause guestfish to exit, even if that (one) command returns an +error. + +=head1 REMOTE CONTROL GUESTFISH OVER A SOCKET + +Guestfish can be remote-controlled over a socket. This is useful +particularly in shell scripts where you want to make several different +changes to a filesystem, but you don't want the overhead of starting +up a guestfish process each time. + +Start a guestfish server process using: + + eval `guestfish --listen` + +and then send it commands by doing: + + guestfish --remote cmd [...] + +To cause the server to exit, send it the exit command: + + guestfish --remote exit + +Note that the server will normally exit if there is an error in a +command. You can change this in the usual way. See section I. + +=head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES + +The C statement sets the environment variable C<$GUESTFISH_PID>, +which is how the C<--remote> option knows where to send the commands. +You can have several guestfish listener processes running using: + + eval `guestfish --listen` + pid1=$GUESTFISH_PID + eval `guestfish --listen` + pid2=$GUESTFISH_PID + ... + guestfish --remote=$pid1 cmd + guestfish --remote=$pid2 cmd + +=head2 REMOTE CONTROL DETAILS + +Remote control happens over a Unix domain socket called +C, where C<$UID> is the effective +user ID of the process, and C<$PID> is the process ID of the server. + +Guestfish client and server versions must match exactly. + +=head1 GUESTFISH COMMANDS + +The commands in this section are guestfish convenience commands, in +other words, they are not part of the L API. + +=head2 alloc | allocate + + alloc filename size + +This creates an empty (zeroed) file of the given size, and then adds +so it can be further examined. + +For more advanced image creation, see L utility. + +Size can be specified (where C means a number): + +=over 4 + +=item C or CK or CKB + +number of kilobytes, eg: C<1440> = standard 3.5in floppy + +=item CM or CMB + +number of megabytes + +=item CG or CGB + +number of gigabytes + +=item CT or CTB + +number of terabytes + +=item CP or CPB + +number of petabytes + +=item CE or CEB + +number of exabytes + +=item Csects + +number of 512 byte sectors + +=back + +=head2 echo + + echo [params ...] + +This echos the parameters to the terminal. + +=head2 edit | vi | emacs + + edit filename + +This is used to edit a file. It downloads the file, edits it +locally using your editor, then uploads the result. + +The editor is C<$EDITOR>. However if you use the alternate +commands C or C you will get those corresponding +editors. + +NOTE: This will not work reliably for large files +(> 2 MB) or binary files containing \0 bytes. + +=head2 glob + + glob command args... + +Expand wildcards in any paths in the args list, and run C +repeatedly on each matching path. + +See section WILDCARDS AND GLOBBING. + +=head2 help + + help + help cmd + +Without any parameter, this lists all commands. With a C +parameter, this displays detailed help for a command. + +=head2 lcd + + lcd directory + +Change the local directory, ie. the current directory of guestfish +itself. + +Note that C won't do what you might expect. + +=head2 more | less + + more filename + + less filename + +This is used to view a file. + +The default viewer is C<$PAGER>. However if you use the alternate +command C you will get the C command specifically. + +NOTE: This will not work reliably for large files +(> 2 MB) or binary files containing \0 bytes. + +=head2 quit | exit + +This exits guestfish. You can also use C<^D> key. + +=head2 reopen + + reopen + +Close and reopen the libguestfs handle. It is not necessary to use +this normally, because the handle is closed properly when guestfish +exits. However this is occasionally useful for testing. + +=head2 sparse + + sparse filename size + +This creates an empty sparse file of the given size, and then adds +so it can be further examined. + +In all respects it works the same as the C command, except that +the image file is allocated sparsely, which means that disk blocks are +not assigned to the file until they are needed. Sparse disk files +only use space when written to, but they are slower and there is a +danger you could run out of real disk space during a write operation. + +For more advanced image creation, see L utility. + +Size can be specified (where C means a number): + +=over 4 + +=item C or CK or CKB + +number of kilobytes, eg: C<1440> = standard 3.5in floppy + +=item CM or CMB + +number of megabytes + +=item CG or CGB + +number of gigabytes + +=item CT or CTB + +number of terabytes + +=item CP or CPB + +number of petabytes + +=item CE or CEB + +number of exabytes + +=item Csects + +number of 512 byte sectors + +=back + +=head2 time + + time command args... + +Run the command as usual, but print the elapsed time afterwards. This +can be useful for benchmarking operations. + +=head1 COMMANDS + +@ACTIONS@ + +=head1 ENVIRONMENT VARIABLES + +=over 4 + +=item EDITOR + +The C command uses C<$EDITOR> as the editor. If not +set, it uses C. + +=item GUESTFISH_PID + +Used with the I<--remote> option to specify the remote guestfish +process to control. See section I. + +=item HOME + +If compiled with GNU readline support, then the command history +is saved in C<$HOME/.guestfish> + +=item LIBGUESTFS_APPEND + +Pass additional options to the guest kernel. + +=item LIBGUESTFS_DEBUG + +Set C to enable verbose messages. This has the +same effect as using the B<-v> option. + +=item LIBGUESTFS_MEMSIZE + +Set the memory allocated to the qemu process, in megabytes. For +example: + + LIBGUESTFS_MEMSIZE=700 + +=item LIBGUESTFS_PATH + +Set the path that guestfish uses to search for kernel and initrd.img. +See the discussion of paths in L. + +=item LIBGUESTFS_QEMU + +Set the default qemu binary that libguestfs uses. If not set, then +the qemu which was found at compile time by the configure script is +used. + +=item LIBGUESTFS_TRACE + +Set C to enable command traces. + +=item PAGER + +The C command uses C<$PAGER> as the pager. If not +set, it uses C. + +=item TMPDIR + +Location of temporary directory, defaults to C. + +If libguestfs was compiled to use the supermin appliance then each +handle will require rather a large amount of space in this directory +for short periods of time (~ 80 MB). You can use C<$TMPDIR> to +configure another directory to use in case C is not large +enough. + +=back + +=head1 EXIT CODE + +guestfish returns I<0> if the commands completed without error, or +I<1> if there was an error. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. diff --git a/guestfish.pod b/guestfish.pod deleted file mode 100644 index 13a9fa7d..00000000 --- a/guestfish.pod +++ /dev/null @@ -1,749 +0,0 @@ -=encoding utf8 - -=head1 NAME - -guestfish - the libguestfs Filesystem Interactive SHell - -=head1 SYNOPSIS - - guestfish [--options] [commands] - - guestfish - - guestfish -a disk.img - - guestfish -a disk.img -m dev[:mountpoint] - - guestfish -i libvirt-domain - - guestfish -i disk.img [disk.img ...] - -=head1 EXAMPLES - -=head2 As an interactive shell - - $ guestfish - - Welcome to guestfish, the libguestfs filesystem interactive shell for - editing virtual machine filesystems. - - Type: 'help' for help with commands - 'quit' to quit the shell - - > help - -=head2 From shell scripts - -Create a new C file in a guest: - - guestfish <<_EOF_ - add disk.img - run - mount /dev/vg_guest/lv_root / - write_file /etc/motd "Welcome, new users" 0 - _EOF_ - -List the LVM logical volumes in a guest: - - guestfish -a disk.img --ro <<_EOF_ - run - lvs - _EOF_ - -=head2 On one command line - -Update C in a guest: - - guestfish \ - add disk.img : run : mount /dev/vg_guest/lv_root / : \ - write-file /etc/resolv.conf "nameserver 1.2.3.4" 0 - -Edit C interactively: - - guestfish --add disk.img \ - --mount /dev/vg_guest/lv_root \ - --mount /dev/sda1:/boot \ - edit /boot/grub/grub.conf - -=head2 Using virt-inspector - -Use the I<-i> option to get virt-inspector to mount -the filesystems automatically as they would be mounted -in the virtual machine: - - guestfish --ro -i disk.img cat /etc/group - -=head2 As a script interpreter - -Create a 50MB disk containing an ext2-formatted partition: - - #!/usr/bin/guestfish -f - alloc /tmp/output.img 50M - run - part-disk /dev/sda mbr - mkfs ext2 /dev/sda1 - -=head2 Remote control - - eval `guestfish --listen --ro` - guestfish --remote add disk.img - guestfish --remote run - guestfish --remote lvs - -=head1 DESCRIPTION - -Guestfish is a shell and command-line tool for examining and modifying -virtual machine filesystems. It uses libguestfs and exposes all of -the functionality of the guestfs API, see L. - -Guestfish gives you structured access to the libguestfs API, from -shell scripts or the command line or interactively. If you want to -rescue a broken virtual machine image, you might want to look at the -L command. - -Using guestfish in read/write mode on live virtual machines can be -dangerous, potentially causing disk corruption. Use the I<--ro> -(read-only) option to use guestfish safely if the disk image or -virtual machine might be live. - -=head1 OPTIONS - -=over 4 - -=item B<--help> - -Displays general help on options. - -=item B<-h> | B<--cmd-help> - -Lists all available guestfish commands. - -=item B<-h cmd> | B<--cmd-help cmd> - -Displays detailed help on a single command C. - -=item B<-a image> | B<--add image> - -Add a block device or virtual machine image to the shell. - -=item B<-D> | B<--no-dest-paths> - -Don't tab-complete paths on the guest filesystem. It is useful to be -able to hit the tab key to complete paths on the guest filesystem, but -this causes extra "hidden" guestfs calls to be made, so this option is -here to allow this feature to be disabled. - -=item B<-f file> | B<--file file> - -Read commands from C. To write pure guestfish -scripts, use: - - #!/usr/bin/guestfish -f - -=item B<-i> | B<--inspector> - -Run virt-inspector on the named libvirt domain or list of disk -images. If virt-inspector is available and if it can identify -the domain or disk images, then partitions will be mounted -correctly at start-up. - -Typical usage is either: - - guestfish -i myguest - -(for an inactive libvirt domain called I), or: - - guestfish --ro -i myguest - -(for active domains, readonly), or specify the block device directly: - - guestfish -i /dev/Guests/MyGuest - -You cannot use I<-a>, I<-m>, I<--listen>, I<--remote> or I<--selinux> -in conjunction with this option, and options other than I<--ro> might -not behave correctly. - -See also: L. - -=item B<--listen> - -Fork into the background and listen for remote commands. See section -I below. - -=item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]> - -Mount the named partition or logical volume on the given mountpoint. - -If the mountpoint is omitted, it defaults to C. - -You have to mount something on C before most commands will work. - -If any C<-m> or C<--mount> options are given, the guest is -automatically launched. - -If you don't know what filesystems a disk image contains, you -can either run guestfish without this option, then list the partitions -and LVs available (see L and L commands), -or you can use the L program. - -=item B<-n> | B<--no-sync> - -Disable autosync. This is enabled by default. See the discussion -of autosync in the L manpage. - -=item B<--remote[=pid]> - -Send remote commands to C<$GUESTFISH_PID> or C. See section -I below. - -=item B<-r> | B<--ro> - -This changes the C<-a> and C<-m> options so that disks are added and -mounts are done read-only (see L). - -The option must always be used if the disk image or virtual machine -might be running, and is generally recommended in cases where you -don't need write access to the disk. - -=item B<--selinux> - -Enable SELinux support for the guest. See L. - -=item B<-v> | B<--verbose> - -Enable very verbose messages. This is particularly useful if you find -a bug. - -=item B<-V> | B<--version> - -Display the guestfish / libguestfs version number and exit. - -=item B<-x> - -Echo each command before executing it. - -=back - -=head1 COMMANDS ON COMMAND LINE - -Any additional (non-option) arguments are treated as commands to -execute. - -Commands to execute should be separated by a colon (C<:>), where the -colon is a separate parameter. Thus: - - guestfish cmd [args...] : cmd [args...] : cmd [args...] ... - -If there are no additional arguments, then we enter a shell, either an -interactive shell with a prompt (if the input is a terminal) or a -non-interactive shell. - -In either command line mode or non-interactive shell, the first -command that gives an error causes the whole shell to exit. In -interactive mode (with a prompt) if a command fails, you can continue -to enter commands. - -=head1 USING launch (OR run) - -As with L, you must first configure your guest by adding -disks, then launch it, then mount any disks you need, and finally -issue actions/commands. So the general order of the day is: - -=over 4 - -=item * - -add or -a/--add - -=item * - -launch (aka run) - -=item * - -mount or -m/--mount - -=item * - -any other commands - -=back - -C is a synonym for C. You must C (or C) -your guest before mounting or performing any other commands. - -The only exception is that if the C<-m> or C<--mount> option was -given, the guest is automatically run for you (simply because -guestfish can't mount the disks you asked for without doing this). - -=head1 QUOTING - -You can quote ordinary parameters using either single or double -quotes. For example: - - add "file with a space.img" - - rm '/file name' - - rm '/"' - -A few commands require a list of strings to be passed. For these, use -a whitespace-separated list, enclosed in quotes. Strings containing whitespace -to be passed through must be enclosed in single quotes. A literal single quote -must be escaped with a backslash. - - vgcreate VG "/dev/sda1 /dev/sdb1" - command "/bin/echo 'foo bar'" - command "/bin/echo \'foo\'" - -=head1 WILDCARDS AND GLOBBING - -Neither guestfish nor the underlying guestfs API performs -wildcard expansion (globbing) by default. So for example the -following will not do what you expect: - - rm-rf /home/* - -Assuming you don't have a directory literally called C -then the above command will return an error. - -To perform wildcard expansion, use the C command. - - glob rm-rf /home/* - -runs C on each path that matches (ie. potentially running -the command many times), equivalent to: - - rm-rf /home/jim - rm-rf /home/joe - rm-rf /home/mary - -C only works on simple guest paths and not on device names. - -If you have several parameters, each containing a wildcard, then glob -will perform a cartesian product. - -=head1 COMMENTS - -Any line which starts with a I<#> character is treated as a comment -and ignored. The I<#> can optionally be preceeded by whitespace, -but B by a command. For example: - - # this is a comment - # this is a comment - foo # NOT a comment - -Blank lines are also ignored. - -=head1 RUNNING COMMANDS LOCALLY - -Any line which starts with a I character is treated as a command -sent to the local shell (C or whatever L uses). -For example: - - !mkdir local - tgz-out /remote local/remote-data.tar.gz - -will create a directory C on the host, and then export -the contents of C on the mounted filesystem to -C. (See C). - -=head1 PIPES - -Use CspaceE | command> to pipe the output of the -first command (a guestfish command) to the second command (any host -command). For example: - - cat /etc/passwd | awk -F: '$3 == 0 { print }' - -(where C is the guestfish cat command, but C is the host awk -program). The above command would list all accounts in the guest -filesystem which have UID 0, ie. root accounts including backdoors. -Other examples: - - hexdump /bin/ls | head - list-devices | tail -1 - -The space before the pipe symbol is required, any space after the pipe -symbol is optional. Everything after the pipe symbol is just passed -straight to the host shell, so it can contain redirections, globs and -anything else that makes sense on the host side. - -To use a literal argument which begins with a pipe symbol, you have -to quote it, eg: - - echo "|" - -=head1 HOME DIRECTORIES - -If a parameter starts with the character C<~> then the tilde may be -expanded as a home directory path (either C<~> for the current user's -home directory, or C<~user> for another user). - -Note that home directory expansion happens for users known I, not in the guest filesystem. - -To use a literal argument which begins with a tilde, you have to quote -it, eg: - - echo "~" - -=head1 WINDOWS PATHS - -If a path is prefixed with C then you can use Windows-style -paths (with some limitations). The following commands are equivalent: - - file /WINDOWS/system32/config/system.LOG - - file win:/windows/system32/config/system.log - - file win:\windows\system32\config\system.log - - file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG - -This syntax implicitly calls C (q.v.) so it also -handles case insensitivity like Windows would. This only works in -argument positions that expect a path. - -=head1 EXIT ON ERROR BEHAVIOUR - -By default, guestfish will ignore any errors when in interactive mode -(ie. taking commands from a human over a tty), and will exit on the -first error in non-interactive mode (scripts, commands given on the -command line). - -If you prefix a command with a I<-> character, then that command will -not cause guestfish to exit, even if that (one) command returns an -error. - -=head1 REMOTE CONTROL GUESTFISH OVER A SOCKET - -Guestfish can be remote-controlled over a socket. This is useful -particularly in shell scripts where you want to make several different -changes to a filesystem, but you don't want the overhead of starting -up a guestfish process each time. - -Start a guestfish server process using: - - eval `guestfish --listen` - -and then send it commands by doing: - - guestfish --remote cmd [...] - -To cause the server to exit, send it the exit command: - - guestfish --remote exit - -Note that the server will normally exit if there is an error in a -command. You can change this in the usual way. See section I. - -=head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES - -The C statement sets the environment variable C<$GUESTFISH_PID>, -which is how the C<--remote> option knows where to send the commands. -You can have several guestfish listener processes running using: - - eval `guestfish --listen` - pid1=$GUESTFISH_PID - eval `guestfish --listen` - pid2=$GUESTFISH_PID - ... - guestfish --remote=$pid1 cmd - guestfish --remote=$pid2 cmd - -=head2 REMOTE CONTROL DETAILS - -Remote control happens over a Unix domain socket called -C, where C<$UID> is the effective -user ID of the process, and C<$PID> is the process ID of the server. - -Guestfish client and server versions must match exactly. - -=head1 GUESTFISH COMMANDS - -The commands in this section are guestfish convenience commands, in -other words, they are not part of the L API. - -=head2 alloc | allocate - - alloc filename size - -This creates an empty (zeroed) file of the given size, and then adds -so it can be further examined. - -For more advanced image creation, see L utility. - -Size can be specified (where C means a number): - -=over 4 - -=item C or CK or CKB - -number of kilobytes, eg: C<1440> = standard 3.5in floppy - -=item CM or CMB - -number of megabytes - -=item CG or CGB - -number of gigabytes - -=item CT or CTB - -number of terabytes - -=item CP or CPB - -number of petabytes - -=item CE or CEB - -number of exabytes - -=item Csects - -number of 512 byte sectors - -=back - -=head2 echo - - echo [params ...] - -This echos the parameters to the terminal. - -=head2 edit | vi | emacs - - edit filename - -This is used to edit a file. It downloads the file, edits it -locally using your editor, then uploads the result. - -The editor is C<$EDITOR>. However if you use the alternate -commands C or C you will get those corresponding -editors. - -NOTE: This will not work reliably for large files -(> 2 MB) or binary files containing \0 bytes. - -=head2 glob - - glob command args... - -Expand wildcards in any paths in the args list, and run C -repeatedly on each matching path. - -See section WILDCARDS AND GLOBBING. - -=head2 help - - help - help cmd - -Without any parameter, this lists all commands. With a C -parameter, this displays detailed help for a command. - -=head2 lcd - - lcd directory - -Change the local directory, ie. the current directory of guestfish -itself. - -Note that C won't do what you might expect. - -=head2 more | less - - more filename - - less filename - -This is used to view a file. - -The default viewer is C<$PAGER>. However if you use the alternate -command C you will get the C command specifically. - -NOTE: This will not work reliably for large files -(> 2 MB) or binary files containing \0 bytes. - -=head2 quit | exit - -This exits guestfish. You can also use C<^D> key. - -=head2 reopen - - reopen - -Close and reopen the libguestfs handle. It is not necessary to use -this normally, because the handle is closed properly when guestfish -exits. However this is occasionally useful for testing. - -=head2 sparse - - sparse filename size - -This creates an empty sparse file of the given size, and then adds -so it can be further examined. - -In all respects it works the same as the C command, except that -the image file is allocated sparsely, which means that disk blocks are -not assigned to the file until they are needed. Sparse disk files -only use space when written to, but they are slower and there is a -danger you could run out of real disk space during a write operation. - -For more advanced image creation, see L utility. - -Size can be specified (where C means a number): - -=over 4 - -=item C or CK or CKB - -number of kilobytes, eg: C<1440> = standard 3.5in floppy - -=item CM or CMB - -number of megabytes - -=item CG or CGB - -number of gigabytes - -=item CT or CTB - -number of terabytes - -=item CP or CPB - -number of petabytes - -=item CE or CEB - -number of exabytes - -=item Csects - -number of 512 byte sectors - -=back - -=head2 time - - time command args... - -Run the command as usual, but print the elapsed time afterwards. This -can be useful for benchmarking operations. - -=head1 COMMANDS - -@ACTIONS@ - -=head1 ENVIRONMENT VARIABLES - -=over 4 - -=item EDITOR - -The C command uses C<$EDITOR> as the editor. If not -set, it uses C. - -=item GUESTFISH_PID - -Used with the I<--remote> option to specify the remote guestfish -process to control. See section I. - -=item HOME - -If compiled with GNU readline support, then the command history -is saved in C<$HOME/.guestfish> - -=item LIBGUESTFS_APPEND - -Pass additional options to the guest kernel. - -=item LIBGUESTFS_DEBUG - -Set C to enable verbose messages. This has the -same effect as using the B<-v> option. - -=item LIBGUESTFS_MEMSIZE - -Set the memory allocated to the qemu process, in megabytes. For -example: - - LIBGUESTFS_MEMSIZE=700 - -=item LIBGUESTFS_PATH - -Set the path that guestfish uses to search for kernel and initrd.img. -See the discussion of paths in L. - -=item LIBGUESTFS_QEMU - -Set the default qemu binary that libguestfs uses. If not set, then -the qemu which was found at compile time by the configure script is -used. - -=item LIBGUESTFS_TRACE - -Set C to enable command traces. - -=item PAGER - -The C command uses C<$PAGER> as the pager. If not -set, it uses C. - -=item TMPDIR - -Location of temporary directory, defaults to C. - -If libguestfs was compiled to use the supermin appliance then each -handle will require rather a large amount of space in this directory -for short periods of time (~ 80 MB). You can use C<$TMPDIR> to -configure another directory to use in case C is not large -enough. - -=back - -=head1 EXIT CODE - -guestfish returns I<0> if the commands completed without error, or -I<1> if there was an error. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L. - -=head1 AUTHORS - -Richard W.M. Jones (C) - -=head1 COPYRIGHT - -Copyright (C) 2009 Red Hat Inc. -L - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; if not, write to the Free Software -Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. diff --git a/guestfs.pod b/guestfs.pod deleted file mode 100644 index 30759602..00000000 --- a/guestfs.pod +++ /dev/null @@ -1,1300 +0,0 @@ -=encoding utf8 - -=head1 NAME - -guestfs - Library for accessing and modifying virtual machine images - -=head1 SYNOPSIS - - #include - - guestfs_h *handle = guestfs_create (); - guestfs_add_drive (handle, "guest.img"); - guestfs_launch (handle); - guestfs_mount (handle, "/dev/sda1", "/"); - guestfs_touch (handle, "/hello"); - guestfs_sync (handle); - guestfs_close (handle); - -=head1 DESCRIPTION - -Libguestfs is a library for accessing and modifying guest disk images. -Amongst the things this is good for: making batch configuration -changes to guests, getting disk used/free statistics (see also: -virt-df), migrating between virtualization systems (see also: -virt-p2v), performing partial backups, performing partial guest -clones, cloning guests and changing registry/UUID/hostname info, and -much else besides. - -Libguestfs uses Linux kernel and qemu code, and can access any type of -guest filesystem that Linux and qemu can, including but not limited -to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition -schemes, qcow, qcow2, vmdk. - -Libguestfs provides ways to enumerate guest storage (eg. partitions, -LVs, what filesystem is in each LV, etc.). It can also run commands -in the context of the guest. Also you can access filesystems over FTP. - -Libguestfs is a library that can be linked with C and C++ management -programs (or management programs written in OCaml, Perl, Python, Ruby, Java -or Haskell). 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. - -Libguestfs is a large API because it can do many things. For a gentle -introduction, please read the L section next. - -=head1 API OVERVIEW - -This section provides a gentler overview of the libguestfs API. We -also try to group API calls together, where that may not be obvious -from reading about the individual calls below. - -=head2 HANDLES - -Before you can use libguestfs calls, you have to create a handle. -Then you must add at least one disk image to the handle, followed by -launching the handle, then performing whatever operations you want, -and finally closing the handle. So the general structure of all -libguestfs-using programs looks like this: - - guestfs_h *handle = guestfs_create (); - - /* Call guestfs_add_drive additional times if there are - * multiple disk images. - */ - guestfs_add_drive (handle, "guest.img"); - - /* Most manipulation calls won't work until you've launched - * the handle. You have to do this _after_ adding drives - * and _before_ other commands. - */ - guestfs_launch (handle); - - /* Now you can examine what partitions, LVs etc are available. - */ - char **partitions = guestfs_list_partitions (handle); - char **logvols = guestfs_lvs (handle); - - /* To access a filesystem in the image, you must mount it. - */ - guestfs_mount (handle, "/dev/sda1", "/"); - - /* Now you can perform filesystem actions on the guest - * disk image. - */ - guestfs_touch (handle, "/hello"); - - /* You only need to call guestfs_sync if you have made - * changes to the guest image. - */ - guestfs_sync (handle); - - /* Close the handle. */ - guestfs_close (handle); - -The code above doesn't include any error checking. In real code you -should check return values carefully for errors. In general all -functions that return integers return C<-1> on error, and all -functions that return pointers return C on error. See section -L below for how to handle errors, and consult the -documentation for each function call below to see precisely how they -return error indications. - -=head2 DISK IMAGES - -The image filename (C<"guest.img"> in the example above) could be a -disk image from a virtual machine, a L copy of a physical hard -disk, an actual block device, or simply an empty file of zeroes that -you have created through L. Libguestfs lets you -do useful things to all of these. - -You can add a disk read-only using C, in which -case libguestfs won't modify the file. - -Be extremely cautious if the disk image is in use, eg. if it is being -used by a virtual machine. Adding it read-write will almost certainly -cause disk corruption, but adding it read-only is safe. - -You must add at least one disk image, and you may add multiple disk -images. In the API, the disk images are usually referred to as -C (for the first one you added), C (for the second -one you added), etc. - -Once C has been called you cannot add any more images. -You can call C to get a list of the device -names, in the order that you added them. See also L below. - -=head2 MOUNTING - -Before you can read or write files, create directories and so on in a -disk image that contains filesystems, you have to mount those -filesystems using C. If you already know that a disk -image contains (for example) one partition with a filesystem on that -partition, then you can mount it directly: - - guestfs_mount (handle, "/dev/sda1", "/"); - -where C means literally the first partition (C<1>) of the -first disk image that we added (C). If the disk contains -Linux LVM2 logical volumes you could refer to those instead (eg. C). - -If you are given a disk image and you don't know what it contains then -you have to find out. Libguestfs can do that too: use -C and C to list possible -partitions and LVs, and either try mounting each to see what is -mountable, or else examine them with C. But you might -find it easier to look at higher level programs built on top of -libguestfs, in particular L. - -To mount a disk image read-only, use C. There are -several other variations of the C call. - -=head2 FILESYSTEM ACCESS AND MODIFICATION - -The majority of the libguestfs API consists of fairly low-level calls -for accessing and modifying the files, directories, symlinks etc on -mounted filesystems. There are over a hundred such calls which you -can find listed in detail below in this man page, and we don't even -pretend to cover them all in this overview. - -Specify filenames as full paths including the mount point. - -For example, if you mounted a filesystem at C<"/"> and you want to -read the file called C<"etc/passwd"> then you could do: - - char *data = guestfs_cat (handle, "/etc/passwd"); - -This would return C as a newly allocated buffer containing the -full content of that file (with some conditions: see also -L below), or C if there was an error. - -As another example, to create a top-level directory on that filesystem -called C<"var"> you would do: - - guestfs_mkdir (handle, "/var"); - -To create a symlink you could do: - - guestfs_ln_s (handle, "/etc/init.d/portmap", - "/etc/rc3.d/S30portmap"); - -Libguestfs will reject attempts to use relative paths. There is no -concept of a current working directory. Libguestfs can return errors -in many situations: for example if the filesystem isn't writable, or -if a file or directory that you requested doesn't exist. If you are -using the C API (documented here) you have to check for those error -conditions after each call. (Other language bindings turn these -errors into exceptions). - -File writes are affected by the per-handle umask, set by calling -C and defaulting to 022. - -=head2 PARTITIONING - -Libguestfs contains API calls to read, create and modify partition -tables on disk images. - -In the common case where you want to create a single partition -covering the whole disk, you should use the C -call: - - const char *parttype = "mbr"; - if (disk_is_larger_than_2TB) - parttype = "gpt"; - guestfs_part_disk (g, "/dev/sda", parttype); - -Obviously this effectively wipes anything that was on that disk image -before. - -In general MBR partitions are both unnecessarily complicated and -depend on archaic details, namely the Cylinder-Head-Sector (CHS) -geometry of the disk. C 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 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. - -=head2 LVM2 - -Libguestfs provides access to a large part of the LVM2 API, such as -C and C. It won't make much sense -unless you familiarize yourself with the concepts of physical volumes, -volume groups and logical volumes. - -This author strongly recommends reading the LVM HOWTO, online at -L. - -=head2 DOWNLOADING - -Use C to download small, text only files. This call -is limited to files which are less than 2 MB and which cannot contain -any ASCII NUL (C<\0>) characters. However it has a very simple -to use API. - -C can be used to read files which contain -arbitrary 8 bit data, since it returns a (pointer, size) pair. -However it is still limited to "small" files, less than 2 MB. - -C can be used to download any file, with no -limits on content or size (even files larger than 4 GB). - -To download multiple files, see C and -C. - -=head2 UPLOADING - -It's often the case that you want to write a file or files to the disk -image. - -For small, single files, use C. This call -currently contains a bug which limits the call to plain text files -(not containing ASCII NUL characters). - -To upload a single file, use C. This call has no -limits on file content or size (even files larger than 4 GB). - -To upload multiple files, see C and C. - -However the fastest way to upload I -is to turn them into a squashfs or CD ISO (see L and -L), then attach this using C. If -you add the drive in a predictable way (eg. adding it last after all -other drives) then you can get the device name from -C and mount it directly using -C. Note that squashfs images are sometimes -non-portable between kernel versions, and they don't support labels or -UUIDs. If you want to pre-build an image or you need to mount it -using a label or UUID, use an ISO image instead. - -=head2 COPYING - -There are various different commands for copying between files and -devices and in and out of the guest filesystem. These are summarised -in the table below. - -=over 4 - -=item B to B - -Use L to copy a single file, or -L to copy directories recursively. - -=item B to B - -Use L which efficiently uses L -to copy between files and devices in the guest. - -Example: duplicate the contents of an LV: - - guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy"); - -The destination (C) must be at least as large as the -source (C). - -=item B to B - -Use L. See L above. - -=item B to B - -Use L. See L above. - -=back - -=head2 LISTING FILES - -C is just designed for humans to read (mainly when using -the L-equivalent command C). - -C is a quick way to get a list of files in a directory -from programs, as a flat list of strings. - -C is a programmatic way to get a list of files in a -directory, plus additional information about each one. It is more -equivalent to using the L call on a local filesystem. - -C can be used to recursively list files. - -=head2 RUNNING COMMANDS - -Although libguestfs is a primarily an API for manipulating files -inside guest images, we also provide some limited facilities for -running commands inside guests. - -There are many limitations to this: - -=over 4 - -=item * - -The kernel version that the command runs under will be different -from what it expects. - -=item * - -If the command needs to communicate with daemons, then most likely -they won't be running. - -=item * - -The command will be running in limited memory. - -=item * - -Only supports Linux guests (not Windows, BSD, etc). - -=item * - -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 in this manpage. - -=back - -The two main API calls to run commands are C and -C (there are also variations). - -The difference is that C runs commands using the shell, so -any shell globs, redirections, etc will work. - -=head2 CONFIGURATION FILES - -To read and write configuration files in Linux guest filesystems, we -strongly recommend using Augeas. For example, Augeas understands how -to read and write, say, a Linux shadow password file or X.org -configuration file, and so avoids you having to write that code. - -The main Augeas calls are bound through the C APIs. We -don't document Augeas itself here because there is excellent -documentation on the L website. - -If you don't want to use Augeas (you fool!) then try calling -C to get the file as a list of lines which -you can iterate over. - -=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 command in the -guest itself: - - guestfs_sh (g, "/usr/sbin/load_policy"); - -(Older versions of C 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. - -=head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS - -Libguestfs can mount NTFS partitions. It does this using the -L driver. - -DOS and Windows still use drive letters, and the filesystems are -always treated as case insensitive by Windows itself, and therefore -you might find a Windows configuration file referring to a path like -C. When the filesystem is mounted in libguestfs, -that directory might be referred to as C. - -Drive letter mappings are outside the scope of libguestfs. You have -to use libguestfs to read the appropriate Windows Registry and -configuration files, to determine yourself how drives are mapped (see -also L). - -Replacing backslash characters with forward slash characters is also -outside the scope of libguestfs, but something that you can easily do. - -Where we can help is in resolving the case insensitivity of paths. -For this, call C. - -Libguestfs also provides some help for decoding Windows Registry -"hive" files, through the library C which is part of -libguestfs. You have to locate and download the hive file(s) -yourself, and then pass them to C functions. See also the -programs L, L and L for more -help on this issue. - -=head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES - -Although we don't want to discourage you from using the C API, we will -mention here that the same API is also available in other languages. - -The API is broadly identical in all supported languages. This means -that the C call C is -C<$handle-Emount($path)> in Perl, C in Python, -and C in OCaml. In other words, a -straightforward, predictable isomorphism between each language. - -Error messages are automatically transformed -into exceptions if the language supports it. - -We don't try to "object orientify" parts of the API in OO languages, -although contributors are welcome to write higher level APIs above -what we provide in their favourite languages if they wish. - -=over 4 - -=item B - -You can use the I header file from C++ programs. The C++ -API is identical to the C API. C++ classes and exceptions are -not implemented. - -=item B - -This is the only language binding that is incomplete. Only calls -which return simple integers have been bound in Haskell, and we are -looking for help to complete this binding. - -=item B - -Full documentation is contained in the Javadoc which is distributed -with libguestfs. - -=item B - -For documentation see the file C. - -=item B - -For documentation see L. - -=item B - -For documentation do: - - $ python - >>> import guestfs - >>> help (guestfs) - -=item B - -Use the Guestfs module. There is no Ruby-specific documentation, but -you can find examples written in Ruby in the libguestfs source. - -=item B - -For documentation see L. - -=back - -=head1 CONNECTION MANAGEMENT - -=head2 guestfs_h * - -C is the opaque type representing a connection handle. -Create a handle by calling C. Call C -to free the handle and release all resources used. - -For information on using multiple handles and threads, see the section -L below. - -=head2 guestfs_create - - guestfs_h *guestfs_create (void); - -Create a connection handle. - -You have to call C on the handle at least once. - -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. - -You may also want to configure error handling for the handle. See -L section below. - -=head2 guestfs_close - - void guestfs_close (guestfs_h *handle); - -This closes the connection handle and frees up all resources used. - -=head1 ERROR HANDLING - -The convention in all functions that return C is that they return -C<-1> to indicate an error. You can get additional information on -errors by calling C and/or by setting up an error -handler with C. - -The default error handler prints the information string to C. - -Out of memory errors are handled differently. The default action is -to call L. If this is undesirable, then you can set a -handler using C. - -=head2 guestfs_last_error - - const char *guestfs_last_error (guestfs_h *handle); - -This returns the last error message that happened on C. If -there has not been an error since the handle was created, then this -returns C. - -The lifetime of the returned string is until the next error occurs, or -C is called. - -The error string is not localized (ie. is always in English), because -this makes searching for error messages in search engines give the -largest number of results. - -=head2 guestfs_set_error_handler - - typedef void (*guestfs_error_handler_cb) (guestfs_h *handle, - void *data, - const char *msg); - void guestfs_set_error_handler (guestfs_h *handle, - guestfs_error_handler_cb cb, - void *data); - -The callback C will be called if there is an error. The -parameters passed to the callback are an opaque data pointer and the -error message string. - -Note that the message string C is freed as soon as the callback -function returns, so if you want to stash it somewhere you must make -your own copy. - -The default handler prints messages on C. - -If you set C to C then I handler is called. - -=head2 guestfs_get_error_handler - - guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle, - void **data_rtn); - -Returns the current error handler callback. - -=head2 guestfs_set_out_of_memory_handler - - typedef void (*guestfs_abort_cb) (void); - int guestfs_set_out_of_memory_handler (guestfs_h *handle, - guestfs_abort_cb); - -The callback C will be called if there is an out of memory -situation. I. - -The default is to call L. - -You cannot set C to C. You can't ignore out of memory -situations. - -=head2 guestfs_get_out_of_memory_handler - - guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle); - -This returns the current out of memory handler. - -=head1 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 or C). - -Use C or set the environment variable -C to change the directories that libguestfs will -search in. The value is a colon-separated list of paths. The current -directory is I searched unless the path contains an empty element -or C<.>. For example C would -search the current directory and then C. - -=head1 HIGH-LEVEL API ACTIONS - -=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 libguestfs. - -@ACTIONS@ - -=head1 STRUCTURES - -@STRUCTS@ - -=head1 AVAILABILITY - -=head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE - -Using L you can test availability of -the following groups of functions. This test queries the -appliance to see if the appliance you are currently using -supports the functionality. - -@AVAILABILITY@ - -=head2 SINGLE CALLS AT COMPILE TIME - -If you need to test whether a single libguestfs function is -available at compile time, we recommend using build tools -such as autoconf or cmake. For example in autotools you could -use: - - AC_CHECK_LIB([guestfs],[guestfs_create]) - AC_CHECK_FUNCS([guestfs_dd]) - -which would result in C being either defined -or not defined in your program. - -=head2 SINGLE CALLS AT RUN TIME - -Testing at compile time doesn't guarantee that a function really -exists in the library. The reason is that you might be dynamically -linked against a previous I (dynamic library) -which doesn't have the call. This situation unfortunately results -in a segmentation fault, which is a shortcoming of the C dynamic -linking system itself. - -You can use L to test if a function is available -at run time, as in this example program (note that you still -need the compile time check as well): - - #include - - #include - #include - #include - #include - #include - - main () - { - #ifdef HAVE_GUESTFS_DD - void *dl; - int has_function; - - /* Test if the function guestfs_dd is really available. */ - dl = dlopen (NULL, RTLD_LAZY); - if (!dl) { - fprintf (stderr, "dlopen: %s\n", dlerror ()); - exit (1); - } - has_function = dlsym (dl, "guestfs_dd") != NULL; - dlclose (dl); - - if (!has_function) - printf ("this libguestfs.so does NOT have guestfs_dd function\n"); - else { - printf ("this libguestfs.so has guestfs_dd function\n"); - /* Now it's safe to call - guestfs_dd (g, "foo", "bar"); - */ - } - #else - printf ("guestfs_dd function was not found at compile time\n"); - #endif - } - -You may think the above is an awful lot of hassle, and it is. -There are other ways outside of the C linking system to ensure -that this kind of incompatibility never arises, such as using -package versioning: - - Requires: libguestfs >= 1.0.80 - -=begin html - - - - -=end html - -=head1 ARCHITECTURE - -Internally, libguestfs is implemented by running an appliance (a -special type of small virtual machine) using L. Qemu runs as -a child process of the main program. - - ___________________ - / \ - | main program | - | | - | | child process / appliance - | | __________________________ - | | / qemu \ - +-------------------+ RPC | +-----------------+ | - | libguestfs <--------------------> guestfsd | | - | | | +-----------------+ | - \___________________/ | | Linux kernel | | - | +--^--------------+ | - \_________|________________/ - | - _______v______ - / \ - | Device or | - | disk image | - \______________/ - -The library, linked to the main program, creates the child process and -hence the appliance in the L function. - -Inside the appliance is a Linux kernel and a complete stack of -userspace tools (such as LVM and ext2 programs) and a small -controlling daemon called C. The library talks to -C using remote procedure calls (RPC). There is a mostly -one-to-one correspondence between libguestfs API calls and RPC calls -to the daemon. Lastly the disk image(s) are attached to the qemu -process which translates device access by the appliance's Linux kernel -into accesses to the image. - -A common misunderstanding is that the appliance "is" the virtual -machine. Although the disk image you are attached to might also be -used by some virtual machine, libguestfs doesn't know or care about -this. (But you will care if both libguestfs's qemu process and your -virtual machine are trying to update the disk image at the same time, -since these usually results in massive disk corruption). - -=head1 STATE MACHINE - -libguestfs uses a state machine to model the child process: - - | - guestfs_create - | - | - ____V_____ - / \ - | CONFIG | - \__________/ - ^ ^ ^ \ - / | \ \ guestfs_launch - / | _\__V______ - / | / \ - / | | LAUNCHING | - / | \___________/ - / | / - / | guestfs_launch - / | / - ______ / __|____V - / \ ------> / \ - | BUSY | | READY | - \______/ <------ \________/ - -The normal transitions are (1) CONFIG (when the handle is created, but -there is no child process), (2) LAUNCHING (when the child process is -booting up), (3) alternating between READY and BUSY as commands are -issued to, and carried out by, the child process. - -The guest may be killed by C, or may die -asynchronously at any time (eg. due to some internal error), and that -causes the state to transition back to CONFIG. - -Configuration commands for qemu such as C can only -be issued when in the CONFIG state. - -The high-level API offers two calls that go from CONFIG through -LAUNCHING to READY. C blocks until the child process -is READY to accept commands (or until some failure or timeout). -C internally moves the state from CONFIG to LAUNCHING -while it is running. - -High-level API actions such as C can only be issued -when in the READY state. These high-level API calls block waiting for -the command to be carried out (ie. the state to transition to BUSY and -then back to READY). But using the low-level event API, you get -non-blocking versions. (But you can still only carry out one -operation per handle at a time - that is a limitation of the -communications protocol we use). - -Finally, the child process sends asynchronous messages back to the -main program, such as kernel log messages. Mostly these are ignored -by the high-level API, but using the low-level event API you can -register to receive these messages. - -=head2 SETTING CALLBACKS TO HANDLE EVENTS - -The child process generates events in some situations. Current events -include: receiving a log message, the child process exits. - -Use the C functions to set a callback for -different types of events. - -Only I can be registered for each handle. -Calling C again overwrites the previous -callback of that type. Cancel all callbacks of this type by calling -this function with C set to C. - -=head2 guestfs_set_log_message_callback - - typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, - char *buf, int len); - void guestfs_set_log_message_callback (guestfs_h *handle, - guestfs_log_message_cb cb, - void *opaque); - -The callback function C will be called whenever qemu or the guest -writes anything to the console. - -Use this function to capture kernel messages and similar. - -Normally there is no log message handler, and log messages are just -discarded. - -=head2 guestfs_set_subprocess_quit_callback - - typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque); - void guestfs_set_subprocess_quit_callback (guestfs_h *handle, - guestfs_subprocess_quit_cb cb, - void *opaque); - -The callback function C will be called when the child process -quits, either asynchronously or if killed by -C. (This corresponds to a transition from -any state to the CONFIG state). - -=head2 guestfs_set_launch_done_callback - - typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque); - void guestfs_set_launch_done_callback (guestfs_h *handle, - guestfs_ready_cb cb, - void *opaque); - -The callback function C will be called when the child process -becomes ready first time after it has been launched. (This -corresponds to a transition from LAUNCHING to the READY state). - -=head1 BLOCK DEVICE NAMING - -In the kernel there is now quite a profusion of schemata for naming -block devices (in this context, by I I mean a physical -or virtual hard drive). The original Linux IDE driver used names -starting with C. SCSI devices have historically used a -different naming scheme, C. When the Linux kernel I -driver became a popular replacement for the old IDE driver -(particularly for SATA devices) those devices also used the -C scheme. Additionally we now have virtual machines with -paravirtualized drivers. This has created several different naming -systems, such as C for virtio disks and C 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 as the I. Internally C names are translated, if necessary, -to other names as required. For example, under RHEL 5 which uses the -C scheme, any device parameter C is translated to -C transparently. - -Note that this I applies to parameters. The -C, C and similar calls -return the true names of the devices and partitions as known to the -appliance. - -=head2 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 C to add a mixture of virtio and IDE -devices to the qemu-based appliance, so have a mixture of C -and C devices. - -The algorithm is applied only to I which are known to be -either device or partition names. Return values from functions such -as C 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? - -=item * - -Does the named device exist? If so, we use that device. -However if I then we continue with this algorithm. - -=item * - -Replace initial C string with C. - -For example, change C to C. - -If that named device exists, use it. If not, continue. - -=item * - -Replace initial C string with C. - -If that named device exists, use it. If not, return an error. - -=back - -=head2 PORTABILITY CONCERNS - -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 C or C 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 INTERNALS - -=head2 COMMUNICATION PROTOCOL - -Don't rely on using this protocol directly. This section documents -how it currently works, but it may change at any time. - -The protocol used to talk between the library and the daemon running -inside the qemu virtual machine is a simple RPC mechanism built on top -of XDR (RFC 1014, RFC 1832, RFC 4506). - -The detailed format of structures is in C -(note: this file is automatically generated). - -There are two broad cases, ordinary functions that don't have any -C and C parameters, which are handled with very -simple request/reply messages. Then there are functions that have any -C or C parameters, which use the same request and -reply messages, but they may also be followed by files sent using a -chunked encoding. - -=head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS) - -For ordinary functions, the request message is: - - total length (header + arguments, - but not including the length word itself) - struct guestfs_message_header (encoded as XDR) - struct guestfs__args (encoded as XDR) - -The total length field allows the daemon to allocate a fixed size -buffer into which it slurps the rest of the message. As a result, the -total length is limited to C bytes (currently -4MB), which means the effective size of any request is limited to -somewhere under this size. - -Note also that many functions don't take any arguments, in which case -the C_args> is completely omitted. - -The header contains the procedure number (C) which is -how the receiver knows what type of args structure to expect, or none -at all. - -The reply message for ordinary functions is: - - total length (header + ret, - but not including the length word itself) - struct guestfs_message_header (encoded as XDR) - struct guestfs__ret (encoded as XDR) - -As above the C_ret> structure may be completely omitted -for functions that return no formal return values. - -As above the total length of the reply is limited to -C. - -In the case of an error, a flag is set in the header, and the reply -message is slightly changed: - - total length (header + error, - but not including the length word itself) - struct guestfs_message_header (encoded as XDR) - struct guestfs_message_error (encoded as XDR) - -The C structure contains the error message as a -string. - -=head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS - -A C parameter indicates that we transfer a file I the -guest. The normal request message is sent (see above). However this -is followed by a sequence of file chunks. - - total length (header + arguments, - but not including the length word itself, - and not including the chunks) - struct guestfs_message_header (encoded as XDR) - struct guestfs__args (encoded as XDR) - sequence of chunks for FileIn param #0 - sequence of chunks for FileIn param #1 etc. - -The "sequence of chunks" is: - - length of chunk (not including length word itself) - struct guestfs_chunk (encoded as XDR) - length of chunk - struct guestfs_chunk (encoded as XDR) - ... - length of chunk - struct guestfs_chunk (with data.data_len == 0) - -The final chunk has the C field set to zero. Additionally a -flag is set in the final chunk to indicate either successful -completion or early cancellation. - -At time of writing there are no functions that have more than one -FileIn parameter. However this is (theoretically) supported, by -sending the sequence of chunks for each FileIn parameter one after -another (from left to right). - -Both the library (sender) I the daemon (receiver) may cancel the -transfer. The library does this by sending a chunk with a special -flag set to indicate cancellation. When the daemon sees this, it -cancels the whole RPC, does I send any reply, and goes back to -reading the next request. - -The daemon may also cancel. It does this by writing a special word -C to the socket. The library listens for this -during the transfer, and if it gets it, it will cancel the transfer -(it sends a cancel chunk). The special word is chosen so that even if -cancellation happens right at the end of the transfer (after the -library has finished writing and has started listening for the reply), -the "spurious" cancel flag will not be confused with the reply -message. - -This protocol allows the transfer of arbitrary sized files (no 32 bit -limit), and also files where the size is not known in advance -(eg. from pipes or sockets). However the chunks are rather small -(C), so that neither the library nor the -daemon need to keep much in memory. - -=head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS - -The protocol for FileOut parameters is exactly the same as for FileIn -parameters, but with the roles of daemon and library reversed. - - total length (header + ret, - but not including the length word itself, - and not including the chunks) - struct guestfs_message_header (encoded as XDR) - struct guestfs__ret (encoded as XDR) - sequence of chunks for FileOut param #0 - sequence of chunks for FileOut param #1 etc. - -=head3 INITIAL MESSAGE - -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) which indicates that the guest -and daemon is alive. This is what C waits for. - -=head1 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. - -=head1 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> 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 (or wherever), C, -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. - -=head1 ENVIRONMENT VARIABLES - -=over 4 - -=item LIBGUESTFS_APPEND - -Pass additional options to the guest kernel. - -=item LIBGUESTFS_DEBUG - -Set C to enable verbose messages. This -has the same effect as calling C. - -=item LIBGUESTFS_MEMSIZE - -Set the memory allocated to the qemu process, in megabytes. For -example: - - LIBGUESTFS_MEMSIZE=700 - -=item LIBGUESTFS_PATH - -Set the path that libguestfs uses to search for kernel and initrd.img. -See the discussion of paths in section PATH above. - -=item LIBGUESTFS_QEMU - -Set the default qemu binary that libguestfs uses. If not set, then -the qemu which was found at compile time by the configure script is -used. - -See also L above. - -=item LIBGUESTFS_TRACE - -Set C to enable command traces. This -has the same effect as calling C. - -=item TMPDIR - -Location of temporary directory, defaults to C. - -If libguestfs was compiled to use the supermin appliance then each -handle will require rather a large amount of space in this directory -for short periods of time (~ 80 MB). You can use C<$TMPDIR> to -configure another directory to use in case C is not large -enough. - -=back - -=head1 SEE ALSO - -L, -L, -L, -L. - -Tools with a similar purpose: -L, -L, -L, -L, -L. - -=head1 BUGS - -To get a list of bugs against libguestfs use this link: - -L - -To report a new bug against libguestfs use this link: - -L - -When reporting a bug, please check: - -=over 4 - -=item * - -That the bug hasn't been reported already. - -=item * - -That you are testing a recent version. - -=item * - -Describe the bug accurately, and give a way to reproduce it. - -=item * - -Run libguestfs-test-tool and paste the B -output into the bug report. - -=back - -=head1 AUTHORS - -Richard W.M. Jones (C) - -=head1 COPYRIGHT - -Copyright (C) 2009 Red Hat Inc. -L - -This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2 of the License, or (at your option) any later version. - -This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details. - -You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA diff --git a/libguestfs.3 b/libguestfs.3 deleted file mode 100644 index 548f8cd9..00000000 --- a/libguestfs.3 +++ /dev/null @@ -1 +0,0 @@ -.so man3/guestfs.3 diff --git a/src/Makefile.am b/src/Makefile.am index 2e33c1a7..7d9220a7 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -23,7 +23,10 @@ generator_built = \ guestfs-actions.h \ guestfs-internal-actions.h \ guestfs-actions.c \ - guestfs-bindtests.c + guestfs-bindtests.c \ + guestfs-actions.pod \ + guestfs-availability.pod \ + guestfs-structs.pod $(generator_built): stamp-generator @@ -36,7 +39,8 @@ EXTRA_DIST = \ $(BUILT_SOURCES) \ MAX_PROC_NR \ stamp-generator \ - generator.ml + generator.ml \ + libguestfs.3 # Rerun the generator if it has changed. # Git removes empty directories, so in cases where the @@ -140,3 +144,29 @@ guestfs_protocol.h: guestfs_protocol.x $(RPCGEN) -h -o $@-t $< mv $@-t $@ endif + +# Manual page. +# guestfs-actions.pod, guestfs-availability.pod and guestfs-structs +# are autogenerated. There is no include mechanism for POD, so we +# have to do it by hand. + +man_MANS = guestfs.3 libguestfs.3 + +guestfs.3: guestfs.pod \ + guestfs-actions.pod \ + guestfs-availability.pod \ + guestfs-structs.pod + sed \ + -e '/@ACTIONS@/rguestfs-actions.pod' \ + -e 's/@ACTIONS@//' \ + -e '/@AVAILABILITY@/rguestfs-availability.pod' \ + -e 's/@AVAILABILITY@//' \ + -e '/@STRUCTS@/rguestfs-structs.pod' \ + -e 's/@STRUCTS@//' \ + < $< | \ + $(POD2MAN) \ + --section 3 \ + -c "Virtualization Support" \ + --name "guestfs" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + > $@ diff --git a/src/generator.ml b/src/generator.ml index 8d2a075b..dc0c9c14 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -10884,6 +10884,9 @@ Run it from the top source directory using the command output_to "src/guestfs-internal-actions.h" generate_internal_actions_h; output_to "src/guestfs-actions.c" generate_client_actions; output_to "src/guestfs-bindtests.c" generate_bindtests; + output_to "src/guestfs-structs.pod" generate_structs_pod; + output_to "src/guestfs-actions.pod" generate_actions_pod; + output_to "src/guestfs-availability.pod" generate_availability_pod; output_to "daemon/actions.h" generate_daemon_actions_h; output_to "daemon/stubs.c" generate_daemon_actions; output_to "daemon/names.c" generate_daemon_names; @@ -10892,10 +10895,7 @@ Run it from the top source directory using the command output_to "capitests/tests.c" generate_tests; output_to "fish/cmds.c" generate_fish_cmds; output_to "fish/completion.c" generate_fish_completion; - output_to "guestfs-structs.pod" generate_structs_pod; - output_to "guestfs-actions.pod" generate_actions_pod; - output_to "guestfs-availability.pod" generate_availability_pod; - output_to "guestfish-actions.pod" generate_fish_actions_pod; + output_to "fish/guestfish-actions.pod" generate_fish_actions_pod; output_to "ocaml/guestfs.mli" generate_ocaml_mli; output_to "ocaml/guestfs.ml" generate_ocaml_ml; output_to "ocaml/guestfs_c_actions.c" generate_ocaml_c; diff --git a/src/guestfs.pod b/src/guestfs.pod new file mode 100644 index 00000000..30759602 --- /dev/null +++ b/src/guestfs.pod @@ -0,0 +1,1300 @@ +=encoding utf8 + +=head1 NAME + +guestfs - Library for accessing and modifying virtual machine images + +=head1 SYNOPSIS + + #include + + guestfs_h *handle = guestfs_create (); + guestfs_add_drive (handle, "guest.img"); + guestfs_launch (handle); + guestfs_mount (handle, "/dev/sda1", "/"); + guestfs_touch (handle, "/hello"); + guestfs_sync (handle); + guestfs_close (handle); + +=head1 DESCRIPTION + +Libguestfs is a library for accessing and modifying guest disk images. +Amongst the things this is good for: making batch configuration +changes to guests, getting disk used/free statistics (see also: +virt-df), migrating between virtualization systems (see also: +virt-p2v), performing partial backups, performing partial guest +clones, cloning guests and changing registry/UUID/hostname info, and +much else besides. + +Libguestfs uses Linux kernel and qemu code, and can access any type of +guest filesystem that Linux and qemu can, including but not limited +to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition +schemes, qcow, qcow2, vmdk. + +Libguestfs provides ways to enumerate guest storage (eg. partitions, +LVs, what filesystem is in each LV, etc.). It can also run commands +in the context of the guest. Also you can access filesystems over FTP. + +Libguestfs is a library that can be linked with C and C++ management +programs (or management programs written in OCaml, Perl, Python, Ruby, Java +or Haskell). 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. + +Libguestfs is a large API because it can do many things. For a gentle +introduction, please read the L section next. + +=head1 API OVERVIEW + +This section provides a gentler overview of the libguestfs API. We +also try to group API calls together, where that may not be obvious +from reading about the individual calls below. + +=head2 HANDLES + +Before you can use libguestfs calls, you have to create a handle. +Then you must add at least one disk image to the handle, followed by +launching the handle, then performing whatever operations you want, +and finally closing the handle. So the general structure of all +libguestfs-using programs looks like this: + + guestfs_h *handle = guestfs_create (); + + /* Call guestfs_add_drive additional times if there are + * multiple disk images. + */ + guestfs_add_drive (handle, "guest.img"); + + /* Most manipulation calls won't work until you've launched + * the handle. You have to do this _after_ adding drives + * and _before_ other commands. + */ + guestfs_launch (handle); + + /* Now you can examine what partitions, LVs etc are available. + */ + char **partitions = guestfs_list_partitions (handle); + char **logvols = guestfs_lvs (handle); + + /* To access a filesystem in the image, you must mount it. + */ + guestfs_mount (handle, "/dev/sda1", "/"); + + /* Now you can perform filesystem actions on the guest + * disk image. + */ + guestfs_touch (handle, "/hello"); + + /* You only need to call guestfs_sync if you have made + * changes to the guest image. + */ + guestfs_sync (handle); + + /* Close the handle. */ + guestfs_close (handle); + +The code above doesn't include any error checking. In real code you +should check return values carefully for errors. In general all +functions that return integers return C<-1> on error, and all +functions that return pointers return C on error. See section +L below for how to handle errors, and consult the +documentation for each function call below to see precisely how they +return error indications. + +=head2 DISK IMAGES + +The image filename (C<"guest.img"> in the example above) could be a +disk image from a virtual machine, a L copy of a physical hard +disk, an actual block device, or simply an empty file of zeroes that +you have created through L. Libguestfs lets you +do useful things to all of these. + +You can add a disk read-only using C, in which +case libguestfs won't modify the file. + +Be extremely cautious if the disk image is in use, eg. if it is being +used by a virtual machine. Adding it read-write will almost certainly +cause disk corruption, but adding it read-only is safe. + +You must add at least one disk image, and you may add multiple disk +images. In the API, the disk images are usually referred to as +C (for the first one you added), C (for the second +one you added), etc. + +Once C has been called you cannot add any more images. +You can call C to get a list of the device +names, in the order that you added them. See also L below. + +=head2 MOUNTING + +Before you can read or write files, create directories and so on in a +disk image that contains filesystems, you have to mount those +filesystems using C. If you already know that a disk +image contains (for example) one partition with a filesystem on that +partition, then you can mount it directly: + + guestfs_mount (handle, "/dev/sda1", "/"); + +where C means literally the first partition (C<1>) of the +first disk image that we added (C). If the disk contains +Linux LVM2 logical volumes you could refer to those instead (eg. C). + +If you are given a disk image and you don't know what it contains then +you have to find out. Libguestfs can do that too: use +C and C to list possible +partitions and LVs, and either try mounting each to see what is +mountable, or else examine them with C. But you might +find it easier to look at higher level programs built on top of +libguestfs, in particular L. + +To mount a disk image read-only, use C. There are +several other variations of the C call. + +=head2 FILESYSTEM ACCESS AND MODIFICATION + +The majority of the libguestfs API consists of fairly low-level calls +for accessing and modifying the files, directories, symlinks etc on +mounted filesystems. There are over a hundred such calls which you +can find listed in detail below in this man page, and we don't even +pretend to cover them all in this overview. + +Specify filenames as full paths including the mount point. + +For example, if you mounted a filesystem at C<"/"> and you want to +read the file called C<"etc/passwd"> then you could do: + + char *data = guestfs_cat (handle, "/etc/passwd"); + +This would return C as a newly allocated buffer containing the +full content of that file (with some conditions: see also +L below), or C if there was an error. + +As another example, to create a top-level directory on that filesystem +called C<"var"> you would do: + + guestfs_mkdir (handle, "/var"); + +To create a symlink you could do: + + guestfs_ln_s (handle, "/etc/init.d/portmap", + "/etc/rc3.d/S30portmap"); + +Libguestfs will reject attempts to use relative paths. There is no +concept of a current working directory. Libguestfs can return errors +in many situations: for example if the filesystem isn't writable, or +if a file or directory that you requested doesn't exist. If you are +using the C API (documented here) you have to check for those error +conditions after each call. (Other language bindings turn these +errors into exceptions). + +File writes are affected by the per-handle umask, set by calling +C and defaulting to 022. + +=head2 PARTITIONING + +Libguestfs contains API calls to read, create and modify partition +tables on disk images. + +In the common case where you want to create a single partition +covering the whole disk, you should use the C +call: + + const char *parttype = "mbr"; + if (disk_is_larger_than_2TB) + parttype = "gpt"; + guestfs_part_disk (g, "/dev/sda", parttype); + +Obviously this effectively wipes anything that was on that disk image +before. + +In general MBR partitions are both unnecessarily complicated and +depend on archaic details, namely the Cylinder-Head-Sector (CHS) +geometry of the disk. C 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 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. + +=head2 LVM2 + +Libguestfs provides access to a large part of the LVM2 API, such as +C and C. It won't make much sense +unless you familiarize yourself with the concepts of physical volumes, +volume groups and logical volumes. + +This author strongly recommends reading the LVM HOWTO, online at +L. + +=head2 DOWNLOADING + +Use C to download small, text only files. This call +is limited to files which are less than 2 MB and which cannot contain +any ASCII NUL (C<\0>) characters. However it has a very simple +to use API. + +C can be used to read files which contain +arbitrary 8 bit data, since it returns a (pointer, size) pair. +However it is still limited to "small" files, less than 2 MB. + +C can be used to download any file, with no +limits on content or size (even files larger than 4 GB). + +To download multiple files, see C and +C. + +=head2 UPLOADING + +It's often the case that you want to write a file or files to the disk +image. + +For small, single files, use C. This call +currently contains a bug which limits the call to plain text files +(not containing ASCII NUL characters). + +To upload a single file, use C. This call has no +limits on file content or size (even files larger than 4 GB). + +To upload multiple files, see C and C. + +However the fastest way to upload I +is to turn them into a squashfs or CD ISO (see L and +L), then attach this using C. If +you add the drive in a predictable way (eg. adding it last after all +other drives) then you can get the device name from +C and mount it directly using +C. Note that squashfs images are sometimes +non-portable between kernel versions, and they don't support labels or +UUIDs. If you want to pre-build an image or you need to mount it +using a label or UUID, use an ISO image instead. + +=head2 COPYING + +There are various different commands for copying between files and +devices and in and out of the guest filesystem. These are summarised +in the table below. + +=over 4 + +=item B to B + +Use L to copy a single file, or +L to copy directories recursively. + +=item B to B + +Use L which efficiently uses L +to copy between files and devices in the guest. + +Example: duplicate the contents of an LV: + + guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy"); + +The destination (C) must be at least as large as the +source (C). + +=item B to B + +Use L. See L above. + +=item B to B + +Use L. See L above. + +=back + +=head2 LISTING FILES + +C is just designed for humans to read (mainly when using +the L-equivalent command C). + +C is a quick way to get a list of files in a directory +from programs, as a flat list of strings. + +C is a programmatic way to get a list of files in a +directory, plus additional information about each one. It is more +equivalent to using the L call on a local filesystem. + +C can be used to recursively list files. + +=head2 RUNNING COMMANDS + +Although libguestfs is a primarily an API for manipulating files +inside guest images, we also provide some limited facilities for +running commands inside guests. + +There are many limitations to this: + +=over 4 + +=item * + +The kernel version that the command runs under will be different +from what it expects. + +=item * + +If the command needs to communicate with daemons, then most likely +they won't be running. + +=item * + +The command will be running in limited memory. + +=item * + +Only supports Linux guests (not Windows, BSD, etc). + +=item * + +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 in this manpage. + +=back + +The two main API calls to run commands are C and +C (there are also variations). + +The difference is that C runs commands using the shell, so +any shell globs, redirections, etc will work. + +=head2 CONFIGURATION FILES + +To read and write configuration files in Linux guest filesystems, we +strongly recommend using Augeas. For example, Augeas understands how +to read and write, say, a Linux shadow password file or X.org +configuration file, and so avoids you having to write that code. + +The main Augeas calls are bound through the C APIs. We +don't document Augeas itself here because there is excellent +documentation on the L website. + +If you don't want to use Augeas (you fool!) then try calling +C to get the file as a list of lines which +you can iterate over. + +=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 command in the +guest itself: + + guestfs_sh (g, "/usr/sbin/load_policy"); + +(Older versions of C 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. + +=head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS + +Libguestfs can mount NTFS partitions. It does this using the +L driver. + +DOS and Windows still use drive letters, and the filesystems are +always treated as case insensitive by Windows itself, and therefore +you might find a Windows configuration file referring to a path like +C. When the filesystem is mounted in libguestfs, +that directory might be referred to as C. + +Drive letter mappings are outside the scope of libguestfs. You have +to use libguestfs to read the appropriate Windows Registry and +configuration files, to determine yourself how drives are mapped (see +also L). + +Replacing backslash characters with forward slash characters is also +outside the scope of libguestfs, but something that you can easily do. + +Where we can help is in resolving the case insensitivity of paths. +For this, call C. + +Libguestfs also provides some help for decoding Windows Registry +"hive" files, through the library C which is part of +libguestfs. You have to locate and download the hive file(s) +yourself, and then pass them to C functions. See also the +programs L, L and L for more +help on this issue. + +=head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES + +Although we don't want to discourage you from using the C API, we will +mention here that the same API is also available in other languages. + +The API is broadly identical in all supported languages. This means +that the C call C is +C<$handle-Emount($path)> in Perl, C in Python, +and C in OCaml. In other words, a +straightforward, predictable isomorphism between each language. + +Error messages are automatically transformed +into exceptions if the language supports it. + +We don't try to "object orientify" parts of the API in OO languages, +although contributors are welcome to write higher level APIs above +what we provide in their favourite languages if they wish. + +=over 4 + +=item B + +You can use the I header file from C++ programs. The C++ +API is identical to the C API. C++ classes and exceptions are +not implemented. + +=item B + +This is the only language binding that is incomplete. Only calls +which return simple integers have been bound in Haskell, and we are +looking for help to complete this binding. + +=item B + +Full documentation is contained in the Javadoc which is distributed +with libguestfs. + +=item B + +For documentation see the file C. + +=item B + +For documentation see L. + +=item B + +For documentation do: + + $ python + >>> import guestfs + >>> help (guestfs) + +=item B + +Use the Guestfs module. There is no Ruby-specific documentation, but +you can find examples written in Ruby in the libguestfs source. + +=item B + +For documentation see L. + +=back + +=head1 CONNECTION MANAGEMENT + +=head2 guestfs_h * + +C is the opaque type representing a connection handle. +Create a handle by calling C. Call C +to free the handle and release all resources used. + +For information on using multiple handles and threads, see the section +L below. + +=head2 guestfs_create + + guestfs_h *guestfs_create (void); + +Create a connection handle. + +You have to call C on the handle at least once. + +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. + +You may also want to configure error handling for the handle. See +L section below. + +=head2 guestfs_close + + void guestfs_close (guestfs_h *handle); + +This closes the connection handle and frees up all resources used. + +=head1 ERROR HANDLING + +The convention in all functions that return C is that they return +C<-1> to indicate an error. You can get additional information on +errors by calling C and/or by setting up an error +handler with C. + +The default error handler prints the information string to C. + +Out of memory errors are handled differently. The default action is +to call L. If this is undesirable, then you can set a +handler using C. + +=head2 guestfs_last_error + + const char *guestfs_last_error (guestfs_h *handle); + +This returns the last error message that happened on C. If +there has not been an error since the handle was created, then this +returns C. + +The lifetime of the returned string is until the next error occurs, or +C is called. + +The error string is not localized (ie. is always in English), because +this makes searching for error messages in search engines give the +largest number of results. + +=head2 guestfs_set_error_handler + + typedef void (*guestfs_error_handler_cb) (guestfs_h *handle, + void *data, + const char *msg); + void guestfs_set_error_handler (guestfs_h *handle, + guestfs_error_handler_cb cb, + void *data); + +The callback C will be called if there is an error. The +parameters passed to the callback are an opaque data pointer and the +error message string. + +Note that the message string C is freed as soon as the callback +function returns, so if you want to stash it somewhere you must make +your own copy. + +The default handler prints messages on C. + +If you set C to C then I handler is called. + +=head2 guestfs_get_error_handler + + guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle, + void **data_rtn); + +Returns the current error handler callback. + +=head2 guestfs_set_out_of_memory_handler + + typedef void (*guestfs_abort_cb) (void); + int guestfs_set_out_of_memory_handler (guestfs_h *handle, + guestfs_abort_cb); + +The callback C will be called if there is an out of memory +situation. I. + +The default is to call L. + +You cannot set C to C. You can't ignore out of memory +situations. + +=head2 guestfs_get_out_of_memory_handler + + guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle); + +This returns the current out of memory handler. + +=head1 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 or C). + +Use C or set the environment variable +C to change the directories that libguestfs will +search in. The value is a colon-separated list of paths. The current +directory is I searched unless the path contains an empty element +or C<.>. For example C would +search the current directory and then C. + +=head1 HIGH-LEVEL API ACTIONS + +=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 libguestfs. + +@ACTIONS@ + +=head1 STRUCTURES + +@STRUCTS@ + +=head1 AVAILABILITY + +=head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE + +Using L you can test availability of +the following groups of functions. This test queries the +appliance to see if the appliance you are currently using +supports the functionality. + +@AVAILABILITY@ + +=head2 SINGLE CALLS AT COMPILE TIME + +If you need to test whether a single libguestfs function is +available at compile time, we recommend using build tools +such as autoconf or cmake. For example in autotools you could +use: + + AC_CHECK_LIB([guestfs],[guestfs_create]) + AC_CHECK_FUNCS([guestfs_dd]) + +which would result in C being either defined +or not defined in your program. + +=head2 SINGLE CALLS AT RUN TIME + +Testing at compile time doesn't guarantee that a function really +exists in the library. The reason is that you might be dynamically +linked against a previous I (dynamic library) +which doesn't have the call. This situation unfortunately results +in a segmentation fault, which is a shortcoming of the C dynamic +linking system itself. + +You can use L to test if a function is available +at run time, as in this example program (note that you still +need the compile time check as well): + + #include + + #include + #include + #include + #include + #include + + main () + { + #ifdef HAVE_GUESTFS_DD + void *dl; + int has_function; + + /* Test if the function guestfs_dd is really available. */ + dl = dlopen (NULL, RTLD_LAZY); + if (!dl) { + fprintf (stderr, "dlopen: %s\n", dlerror ()); + exit (1); + } + has_function = dlsym (dl, "guestfs_dd") != NULL; + dlclose (dl); + + if (!has_function) + printf ("this libguestfs.so does NOT have guestfs_dd function\n"); + else { + printf ("this libguestfs.so has guestfs_dd function\n"); + /* Now it's safe to call + guestfs_dd (g, "foo", "bar"); + */ + } + #else + printf ("guestfs_dd function was not found at compile time\n"); + #endif + } + +You may think the above is an awful lot of hassle, and it is. +There are other ways outside of the C linking system to ensure +that this kind of incompatibility never arises, such as using +package versioning: + + Requires: libguestfs >= 1.0.80 + +=begin html + + + + +=end html + +=head1 ARCHITECTURE + +Internally, libguestfs is implemented by running an appliance (a +special type of small virtual machine) using L. Qemu runs as +a child process of the main program. + + ___________________ + / \ + | main program | + | | + | | child process / appliance + | | __________________________ + | | / qemu \ + +-------------------+ RPC | +-----------------+ | + | libguestfs <--------------------> guestfsd | | + | | | +-----------------+ | + \___________________/ | | Linux kernel | | + | +--^--------------+ | + \_________|________________/ + | + _______v______ + / \ + | Device or | + | disk image | + \______________/ + +The library, linked to the main program, creates the child process and +hence the appliance in the L function. + +Inside the appliance is a Linux kernel and a complete stack of +userspace tools (such as LVM and ext2 programs) and a small +controlling daemon called C. The library talks to +C using remote procedure calls (RPC). There is a mostly +one-to-one correspondence between libguestfs API calls and RPC calls +to the daemon. Lastly the disk image(s) are attached to the qemu +process which translates device access by the appliance's Linux kernel +into accesses to the image. + +A common misunderstanding is that the appliance "is" the virtual +machine. Although the disk image you are attached to might also be +used by some virtual machine, libguestfs doesn't know or care about +this. (But you will care if both libguestfs's qemu process and your +virtual machine are trying to update the disk image at the same time, +since these usually results in massive disk corruption). + +=head1 STATE MACHINE + +libguestfs uses a state machine to model the child process: + + | + guestfs_create + | + | + ____V_____ + / \ + | CONFIG | + \__________/ + ^ ^ ^ \ + / | \ \ guestfs_launch + / | _\__V______ + / | / \ + / | | LAUNCHING | + / | \___________/ + / | / + / | guestfs_launch + / | / + ______ / __|____V + / \ ------> / \ + | BUSY | | READY | + \______/ <------ \________/ + +The normal transitions are (1) CONFIG (when the handle is created, but +there is no child process), (2) LAUNCHING (when the child process is +booting up), (3) alternating between READY and BUSY as commands are +issued to, and carried out by, the child process. + +The guest may be killed by C, or may die +asynchronously at any time (eg. due to some internal error), and that +causes the state to transition back to CONFIG. + +Configuration commands for qemu such as C can only +be issued when in the CONFIG state. + +The high-level API offers two calls that go from CONFIG through +LAUNCHING to READY. C blocks until the child process +is READY to accept commands (or until some failure or timeout). +C internally moves the state from CONFIG to LAUNCHING +while it is running. + +High-level API actions such as C can only be issued +when in the READY state. These high-level API calls block waiting for +the command to be carried out (ie. the state to transition to BUSY and +then back to READY). But using the low-level event API, you get +non-blocking versions. (But you can still only carry out one +operation per handle at a time - that is a limitation of the +communications protocol we use). + +Finally, the child process sends asynchronous messages back to the +main program, such as kernel log messages. Mostly these are ignored +by the high-level API, but using the low-level event API you can +register to receive these messages. + +=head2 SETTING CALLBACKS TO HANDLE EVENTS + +The child process generates events in some situations. Current events +include: receiving a log message, the child process exits. + +Use the C functions to set a callback for +different types of events. + +Only I can be registered for each handle. +Calling C again overwrites the previous +callback of that type. Cancel all callbacks of this type by calling +this function with C set to C. + +=head2 guestfs_set_log_message_callback + + typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, + char *buf, int len); + void guestfs_set_log_message_callback (guestfs_h *handle, + guestfs_log_message_cb cb, + void *opaque); + +The callback function C will be called whenever qemu or the guest +writes anything to the console. + +Use this function to capture kernel messages and similar. + +Normally there is no log message handler, and log messages are just +discarded. + +=head2 guestfs_set_subprocess_quit_callback + + typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque); + void guestfs_set_subprocess_quit_callback (guestfs_h *handle, + guestfs_subprocess_quit_cb cb, + void *opaque); + +The callback function C will be called when the child process +quits, either asynchronously or if killed by +C. (This corresponds to a transition from +any state to the CONFIG state). + +=head2 guestfs_set_launch_done_callback + + typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque); + void guestfs_set_launch_done_callback (guestfs_h *handle, + guestfs_ready_cb cb, + void *opaque); + +The callback function C will be called when the child process +becomes ready first time after it has been launched. (This +corresponds to a transition from LAUNCHING to the READY state). + +=head1 BLOCK DEVICE NAMING + +In the kernel there is now quite a profusion of schemata for naming +block devices (in this context, by I I mean a physical +or virtual hard drive). The original Linux IDE driver used names +starting with C. SCSI devices have historically used a +different naming scheme, C. When the Linux kernel I +driver became a popular replacement for the old IDE driver +(particularly for SATA devices) those devices also used the +C scheme. Additionally we now have virtual machines with +paravirtualized drivers. This has created several different naming +systems, such as C for virtio disks and C 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 as the I. Internally C names are translated, if necessary, +to other names as required. For example, under RHEL 5 which uses the +C scheme, any device parameter C is translated to +C transparently. + +Note that this I applies to parameters. The +C, C and similar calls +return the true names of the devices and partitions as known to the +appliance. + +=head2 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 C to add a mixture of virtio and IDE +devices to the qemu-based appliance, so have a mixture of C +and C devices. + +The algorithm is applied only to I which are known to be +either device or partition names. Return values from functions such +as C 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? + +=item * + +Does the named device exist? If so, we use that device. +However if I then we continue with this algorithm. + +=item * + +Replace initial C string with C. + +For example, change C to C. + +If that named device exists, use it. If not, continue. + +=item * + +Replace initial C string with C. + +If that named device exists, use it. If not, return an error. + +=back + +=head2 PORTABILITY CONCERNS + +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 C or C 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 INTERNALS + +=head2 COMMUNICATION PROTOCOL + +Don't rely on using this protocol directly. This section documents +how it currently works, but it may change at any time. + +The protocol used to talk between the library and the daemon running +inside the qemu virtual machine is a simple RPC mechanism built on top +of XDR (RFC 1014, RFC 1832, RFC 4506). + +The detailed format of structures is in C +(note: this file is automatically generated). + +There are two broad cases, ordinary functions that don't have any +C and C parameters, which are handled with very +simple request/reply messages. Then there are functions that have any +C or C parameters, which use the same request and +reply messages, but they may also be followed by files sent using a +chunked encoding. + +=head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS) + +For ordinary functions, the request message is: + + total length (header + arguments, + but not including the length word itself) + struct guestfs_message_header (encoded as XDR) + struct guestfs__args (encoded as XDR) + +The total length field allows the daemon to allocate a fixed size +buffer into which it slurps the rest of the message. As a result, the +total length is limited to C bytes (currently +4MB), which means the effective size of any request is limited to +somewhere under this size. + +Note also that many functions don't take any arguments, in which case +the C_args> is completely omitted. + +The header contains the procedure number (C) which is +how the receiver knows what type of args structure to expect, or none +at all. + +The reply message for ordinary functions is: + + total length (header + ret, + but not including the length word itself) + struct guestfs_message_header (encoded as XDR) + struct guestfs__ret (encoded as XDR) + +As above the C_ret> structure may be completely omitted +for functions that return no formal return values. + +As above the total length of the reply is limited to +C. + +In the case of an error, a flag is set in the header, and the reply +message is slightly changed: + + total length (header + error, + but not including the length word itself) + struct guestfs_message_header (encoded as XDR) + struct guestfs_message_error (encoded as XDR) + +The C structure contains the error message as a +string. + +=head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS + +A C parameter indicates that we transfer a file I the +guest. The normal request message is sent (see above). However this +is followed by a sequence of file chunks. + + total length (header + arguments, + but not including the length word itself, + and not including the chunks) + struct guestfs_message_header (encoded as XDR) + struct guestfs__args (encoded as XDR) + sequence of chunks for FileIn param #0 + sequence of chunks for FileIn param #1 etc. + +The "sequence of chunks" is: + + length of chunk (not including length word itself) + struct guestfs_chunk (encoded as XDR) + length of chunk + struct guestfs_chunk (encoded as XDR) + ... + length of chunk + struct guestfs_chunk (with data.data_len == 0) + +The final chunk has the C field set to zero. Additionally a +flag is set in the final chunk to indicate either successful +completion or early cancellation. + +At time of writing there are no functions that have more than one +FileIn parameter. However this is (theoretically) supported, by +sending the sequence of chunks for each FileIn parameter one after +another (from left to right). + +Both the library (sender) I the daemon (receiver) may cancel the +transfer. The library does this by sending a chunk with a special +flag set to indicate cancellation. When the daemon sees this, it +cancels the whole RPC, does I send any reply, and goes back to +reading the next request. + +The daemon may also cancel. It does this by writing a special word +C to the socket. The library listens for this +during the transfer, and if it gets it, it will cancel the transfer +(it sends a cancel chunk). The special word is chosen so that even if +cancellation happens right at the end of the transfer (after the +library has finished writing and has started listening for the reply), +the "spurious" cancel flag will not be confused with the reply +message. + +This protocol allows the transfer of arbitrary sized files (no 32 bit +limit), and also files where the size is not known in advance +(eg. from pipes or sockets). However the chunks are rather small +(C), so that neither the library nor the +daemon need to keep much in memory. + +=head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS + +The protocol for FileOut parameters is exactly the same as for FileIn +parameters, but with the roles of daemon and library reversed. + + total length (header + ret, + but not including the length word itself, + and not including the chunks) + struct guestfs_message_header (encoded as XDR) + struct guestfs__ret (encoded as XDR) + sequence of chunks for FileOut param #0 + sequence of chunks for FileOut param #1 etc. + +=head3 INITIAL MESSAGE + +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) which indicates that the guest +and daemon is alive. This is what C waits for. + +=head1 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. + +=head1 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> 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 (or wherever), C, +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. + +=head1 ENVIRONMENT VARIABLES + +=over 4 + +=item LIBGUESTFS_APPEND + +Pass additional options to the guest kernel. + +=item LIBGUESTFS_DEBUG + +Set C to enable verbose messages. This +has the same effect as calling C. + +=item LIBGUESTFS_MEMSIZE + +Set the memory allocated to the qemu process, in megabytes. For +example: + + LIBGUESTFS_MEMSIZE=700 + +=item LIBGUESTFS_PATH + +Set the path that libguestfs uses to search for kernel and initrd.img. +See the discussion of paths in section PATH above. + +=item LIBGUESTFS_QEMU + +Set the default qemu binary that libguestfs uses. If not set, then +the qemu which was found at compile time by the configure script is +used. + +See also L above. + +=item LIBGUESTFS_TRACE + +Set C to enable command traces. This +has the same effect as calling C. + +=item TMPDIR + +Location of temporary directory, defaults to C. + +If libguestfs was compiled to use the supermin appliance then each +handle will require rather a large amount of space in this directory +for short periods of time (~ 80 MB). You can use C<$TMPDIR> to +configure another directory to use in case C is not large +enough. + +=back + +=head1 SEE ALSO + +L, +L, +L, +L. + +Tools with a similar purpose: +L, +L, +L, +L, +L. + +=head1 BUGS + +To get a list of bugs against libguestfs use this link: + +L + +To report a new bug against libguestfs use this link: + +L + +When reporting a bug, please check: + +=over 4 + +=item * + +That the bug hasn't been reported already. + +=item * + +That you are testing a recent version. + +=item * + +Describe the bug accurately, and give a way to reproduce it. + +=item * + +Run libguestfs-test-tool and paste the B +output into the bug report. + +=back + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA diff --git a/src/libguestfs.3 b/src/libguestfs.3 new file mode 100644 index 00000000..548f8cd9 --- /dev/null +++ b/src/libguestfs.3 @@ -0,0 +1 @@ +.so man3/guestfs.3 -- cgit