mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-22 07:03:38 +00:00
281 lines
6.0 KiB
Plaintext
281 lines
6.0 KiB
Plaintext
=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<-r> | B<--ro>
|
|
|
|
This changes the C<-m> option so that mounts are done read-only
|
|
(see C<guestfs_mount_ro> 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 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<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.
|