X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=guestfish.pod;fp=guestfish.pod;h=e3e9c14d903bc5ae8df2f0cd674f6001eaaae6db;hb=21ba59ce3cbc594ce9c7aeecd4dadb8430e4042d;hp=0000000000000000000000000000000000000000;hpb=bccbfe5ab55c8aa5bbb0fb6e209936ff1359605a;p=libguestfs.git diff --git a/guestfish.pod b/guestfish.pod new file mode 100644 index 0000000..e3e9c14 --- /dev/null +++ b/guestfish.pod @@ -0,0 +1,268 @@ +=encoding utf8 + +=head1 NAME + +guestfish - the libguestfs filesystem interactive shell + +=head1 SYNOPSIS + + guestfish [--options] [commands] + +=head1 EXAMPLES + +=head2 From shell scripts + +Create a new C file in a guest: + + guestfish <<_EOF_ + add disk.img + run + mount /dev/VolGroup00/LogVol00 / + upload new_motd /etc/motd + _EOF_ + +List the LVs in a guest: + + guestfish <<_EOF_ + add disk.img + run + lvs + _EOF_ + +=head2 On the command line + +List the LVM PVs in a guest image: + + guestfish add disk.img : run : pvs + +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 + +=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 + +=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. + +=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<-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. + +=item B<-n> | B<--no-sync> + +Disable autosync. This is enabled by default. See the discussion +of autosync in the L manpage. + +=item B<-v> | B<--verbose> + +Enable very verbose messages. This is particularly useful if you find +a bug. + +=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 COMMANDS + +=head2 help + + help + help cmd + +Without any parameter, this lists all commands. With a C +parameter, this displays detailed help for a command. + +=head2 quit | exit + +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 + +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 + +number of kilobytes, eg: C<1440> = standard 3.5in floppy + +=item CK or CKB + +number of kilobytes + +=item CM or CMB + +number of megabytes + +=item CG or CGB + +number of gigabytes + +=item Csects + +number of 512 byte sectors + +=back + +=head2 launch | run + +Launch the guest so that you can issue other commands (see below). + +@ACTIONS@ + +=head1 ENVIRONMENT VARIABLES + +=over 4 + +=item LIBGUESTFS_DEBUG + +Set C to enable verbose messages. This has the +same effect as using the B<-v> option. + +=item LIBGUESTFS_PATH + +Set the path that guestfish uses to search for kernel and initrd.img. +See the discussion of paths in L. + +=back + +=head1 SEE ALSO + +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.