X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfish.pod;h=56d941f822e310ce880a6c8847212b5dd468ff52;hp=e3e9c14d903bc5ae8df2f0cd674f6001eaaae6db;hb=e1c62f6332ae07cb6f95130dcc9852701d085e2b;hpb=21ba59ce3cbc594ce9c7aeecd4dadb8430e4042d diff --git a/guestfish.pod b/guestfish.pod index e3e9c14..56d941f 100644 --- a/guestfish.pod +++ b/guestfish.pod @@ -8,6 +8,10 @@ guestfish - the libguestfs filesystem interactive shell guestfish [--options] [commands] + guestfish -i libvirt-domain + + guestfish -i disk-image(s) + =head1 EXAMPLES =head2 From shell scripts @@ -18,7 +22,7 @@ Create a new C file in a guest: add disk.img run mount /dev/VolGroup00/LogVol00 / - upload new_motd /etc/motd + write_file /etc/motd "Hello users" 0 _EOF_ List the LVs in a guest: @@ -40,8 +44,7 @@ Remove C (in reality not such a great idea): guestfish --add disk.img \ --mount /dev/VolGroup00/LogVol00 \ --mount /dev/sda1:/boot \ - rm /boot/grub/menu.lst : \ - sync : exit + rm /boot/grub/menu.lst =head2 As an interactive shell @@ -55,6 +58,14 @@ Remove C (in reality not such a great idea): > help +=head2 As a script interpreter + + #!/usr/bin/guestfish -f + alloc /tmp/output.img 10M + run + sfdisk /dev/sda 0 0 0 , + mkfs ext2 /dev/sda1 + =head1 DESCRIPTION Guestfish is a shell and command-line tool for examining and modifying @@ -81,6 +92,37 @@ Displays detailed help on a single command C. Add a block device or virtual machine image to the shell. +=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> or I<-m> in conjunction with this option, and +options other than I<--ro> might not behave correctly. + +See also: L. + =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]> Mount the named partition or logical volume on the given mountpoint. @@ -97,11 +139,23 @@ automatically launched. Disable autosync. This is enabled by default. See the discussion of autosync in the L manpage. +=item B<-r> | B<--ro> + +This changes the C<-m> option so that mounts are done read-only +(see C in the L manpage). + =item B<-v> | B<--verbose> Enable very verbose messages. This is particularly useful if you find a bug. +=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. + =back =head1 COMMANDS ON COMMAND LINE @@ -156,6 +210,85 @@ 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 space-separated list, enclosed in quotes. For example: + + vgcreate VG "/dev/sda1 /dev/sdb1" + +=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 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 COMMANDS =head2 help @@ -170,18 +303,6 @@ parameter, this displays detailed help for a command. This exits guestfish. You can also use C<^D> key. -=head2 add | drive | add-drive - - add filename - -This adds a block device to be examined or modified. - -=head2 cdrom | add-cdrom - - cdrom iso-file - -This adds a CD-ROM device to be examined. - =head2 alloc | allocate alloc filename size @@ -195,14 +316,10 @@ Size can be specified (where C means a number): =over 4 -=item C +=item C or CK or CKB number of kilobytes, eg: C<1440> = standard 3.5in floppy -=item CK or CKB - -number of kilobytes - =item CM or CMB number of megabytes @@ -217,9 +334,43 @@ number of 512 byte sectors =back -=head2 launch | run +=head2 echo + + echo [params ...] + +This echos the parameters to the terminal. + +=head2 edit | vi | emacs + + edit filename -Launch the guest so that you can issue other commands (see below). +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 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 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. @ACTIONS@ @@ -237,12 +388,37 @@ same effect as using the B<-v> option. 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_APPEND + +Pass additional options to the guest kernel. + +=item HOME + +If compiled with GNU readline support, then the command history +is saved in C<$HOME/.guestfish> + +=item EDITOR + +The C command uses C<$EDITOR> as the editor. If not +set, it uses C. + =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. =head1 AUTHORS @@ -251,7 +427,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT Copyright (C) 2009 Red Hat Inc. -L +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