path: root/guestfish.pod

=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</etc/motd> 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</boot/grub/menu.lst> (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
 
 ><fs> 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<guestfs(3)>.

=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<cmd>.

=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<guestfs(3)> 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<guestfs(3)>, 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<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
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<cmd>
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<qemu-img(1)> utility.

Size can be specified (where C<nn> means a number):

=over 4

=item C<nn> or C<nn>K or C<nn>KB

number of kilobytes, eg: C<1440> = standard 3.5in floppy

=item C<nn>M or C<nn>MB

number of megabytes

=item C<nn>G or C<nn>GB

number of gigabytes

=item C<nn>sects

number of 512 byte sectors

=back

@ACTIONS@

=head1 ENVIRONMENT VARIABLES

=over 4

=item LIBGUESTFS_DEBUG

Set C<LIBGUESTFS_DEBUG=1> 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<guestfs(3)>.

=item HOME

If compiled with GNU readline support, then the command history
is saved in C<$HOME/.guestfish>

=back

=head1 SEE ALSO

L<guestfs(3)>,
L<http://et.redhat.com/~rjones/libguestfs>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2009 Red Hat Inc.
L<http://et.redhat.com/~rjones/libguestfs>

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.