=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 / write_file /etc/motd "Hello users" 0 _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<-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. =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 space-separated list, enclosed in quotes. For example: vgcreate VG "/dev/sda1 /dev/sdb1" =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 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 Csects number of 512 byte sectors =back @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. =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 HOME If compiled with GNU readline support, then the command history is saved in C<$HOME/.guestfish> =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.