(read-only) option to use guestfish safely if the disk image or
virtual machine might be live.
+=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)>.
+
+Guestfish gives you structured access to the libguestfs API, from
+shell scripts or the command line or interactively. If you want to
+rescue a broken virtual machine image, you should look at the
+L<virt-rescue(1)> command.
+
=head1 EXAMPLES
=head2 As an interactive shell
'man' to read the manual
'quit' to quit the shell
- ><fs> man
+ ><fs> add-ro disk.img
+ ><fs> run
+ ><fs> list-filesystems
+ /dev/sda1: ext4
+ /dev/vg_guest/lv_root: ext4
+ /dev/vg_guest/lv_swap: swap
+ ><fs> mount /dev/vg_guest/lv_root /
+ ><fs> cat /etc/fstab
+ # /etc/fstab
+ # Created by anaconda
+ [...]
+ ><fs> exit
=head2 From shell scripts
-Create a new C</etc/motd> file in a guest:
+Create a new C</etc/motd> file in a guest or disk image:
guestfish <<_EOF_
add disk.img
write /etc/motd "Welcome, new users"
_EOF_
-List the LVM logical volumes in a guest:
+List the LVM logical volumes in a disk image:
guestfish -a disk.img --ro <<_EOF_
run
lvs
_EOF_
+List all the filesystems in a disk image:
+
+ guestfish -a disk.img --ro <<_EOF_
+ run
+ list-filesystems
+ _EOF_
+
=head2 On one command line
Update C</etc/resolv.conf> in a guest:
guestfish --ro -d libvirt-domain -i cat /etc/group
+Another way to edit C</boot/grub/grub.conf> interactively is:
+
+ guestfish -a disk.img -i edit /boot/grub/grub.conf
+
=head2 As a script interpreter
Create a 100MB disk containing an ext2-formatted partition:
=head2 Remote control
- eval `guestfish --listen --ro`
- guestfish --remote add disk.img
+ eval `guestfish --listen`
+ guestfish --remote add-ro disk.img
guestfish --remote run
guestfish --remote lvs
-=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)>.
-
-Guestfish gives you structured access to the libguestfs API, from
-shell scripts or the command line or interactively. If you want to
-rescue a broken virtual machine image, you should look at the
-L<virt-rescue(1)> command.
-
=head1 OPTIONS
=over 4
Add a block device or virtual machine image to the shell.
+The format of the disk image is auto-detected. To override this and
+force a particular format use the I<--format=..> option.
+
=item B<-c URI> | B<--connect URI>
When used in conjunction with the I<-d> option, this specifies
this causes extra "hidden" guestfs calls to be made, so this option is
here to allow this feature to be disabled.
+=item B<--echo-keys>
+
+When prompting for keys and passphrases, guestfish normally turns
+echoing off so you cannot see what you are typing. If you are not
+worried about Tempest attacks and there is no one else in the room
+you can specify this flag to see what you are typing.
+
=item B<-f file> | B<--file file>
Read commands from C<file>. To write pure guestfish
#!/usr/bin/guestfish -f
+=item B<--format=raw|qcow2|..> | B<--format>
+
+The default for the I<-a> option is to auto-detect the format of the
+disk image. Using this forces the disk format for I<-a> options which
+follow on the command line. Using I<--format> with no argument
+switches back to auto-detection for subsequent I<-a> options.
+
+For example:
+
+ guestfish --format=raw -a disk.img
+
+forces raw format (no auto-detection) for C<disk.img>.
+
+ guestfish --format=raw -a disk.img --format -a another.img
+
+forces raw format (no auto-detection) for C<disk.img> and reverts to
+auto-detection for C<another.img>.
+
+If you have untrusted raw-format guest disk images, you should use
+this option to specify the disk format. This avoids a possible
+security problem with malicious guests (CVE-2010-3851). See also
+L</add-drive-opts>.
+
=item B<-i> | B<--inspector>
Using L<virt-inspector(1)> code, inspect the disks looking for
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 I<-m> or I<--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).
+The only exception is that if any of the I<-i>, I<-m>, I<--mount>,
+I<-N> or I<--new> options were given then C<run> is done
+automatically, simply because guestfish can't perform the action you
+asked for without doing this.
=head1 QUOTING
command "/bin/echo 'foo bar'"
command "/bin/echo \'foo\'"
+=head1 OPTIONAL ARGUMENTS
+
+Some commands take optional arguments. These arguments appear in this
+documentation as C<[argname:..]>. You can use them as in these
+examples:
+
+ add-drive-opts filename
+
+ add-drive-opts filename readonly:true
+
+ add-drive-opts filename format:qcow2 readonly:false
+
+Each optional argument can appear at most once. All optional
+arguments must appear after the required ones.
+
=head1 NUMBERS
This section applies to all commands which can take integers
rm-rf /home/*
-Assuming you don't have a directory literally called C</home/*>
+Assuming you don't have a directory called literally C</home/*>
then the above command will return an error.
To perform wildcard expansion, use the C<glob> command.
C<glob> 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.
+will perform a Cartesian product.
=head1 COMMENTS
Finally you have to tell LVM to scan for volume groups on
the newly created mapper device:
- ><fs> vgscan
- ><fs> vg-activate-all true
+ vgscan
+ vg-activate-all true
The logical volume(s) can now be mounted in the usual way.
it and deactivate the volume groups by calling C<vg-activate false VG>
on each one. Then you can close the mapper device:
- ><fs> vg-activate false /dev/VG
- ><fs> luks-close /dev/mapper/luksdev
+ vg-activate false /dev/VG
+ luks-close /dev/mapper/luksdev
=head1 WINDOWS PATHS
The commands in this section are guestfish convenience commands, in
other words, they are not part of the L<guestfs(3)> API.
-=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 using standard suffixes, eg. C<1M>.
-
-=head2 copy-in
-
- copy-in local [local ...] /remotedir
-
-C<copy-in> copies local files or directories recursively into the disk
-image, placing them in the directory called C</remotedir> (which must
-exist). This guestfish meta-command turns into a sequence of
-L</tar-in> and other commands as necessary.
-
-Multiple local files and directories can be specified, but the last
-parameter must always be a remote directory. Wildcards cannot be
-used.
-
-=head2 copy-out
-
- copy-out remote [remote ...] localdir
-
-C<copy-out> copies remote files or directories recursively out of the
-disk image, placing them on the host disk in a local directory called
-C<localdir> (which must exist). This guestfish meta-command turns
-into a sequence of L</download>, L</tar-out> and other commands as
-necessary.
-
-Multiple remote files and directories can be specified, but the last
-parameter must always be a local directory. To download to the
-current directory, use C<.> as in:
-
- copy-out /home .
-
-Wildcards cannot be used in the ordinary command, but you can use
-them with the help of L</glob> like this:
-
- glob copy-out /home/* .
-
-=head2 echo
-
- echo [params ...]
-
-This echos the parameters to the terminal.
-
-=head2 edit | vi | emacs
-
- edit filename
-
-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<vi> or C<emacs> you will get those corresponding
-editors.
-
-=head2 glob
-
- glob command args...
-
-Expand wildcards in any paths in the args list, and run C<command>
-repeatedly on each matching path.
-
-See section WILDCARDS AND GLOBBING.
-
=head2 help
help
Without any parameter, this lists all commands. With a C<cmd>
parameter, this displays detailed help for a command.
-=head2 lcd
-
- lcd directory
-
-Change the local directory, ie. the current directory of guestfish
-itself.
-
-Note that C<!cd> won't do what you might expect.
-
-=head2 man | manual
-
- man
-
-Opens the manual page for guestfish.
-
-=head2 more | less
-
- more filename
-
- less filename
-
-This is used to view a file.
-
-The default viewer is C<$PAGER>. However if you use the alternate
-command C<less> you will get the C<less> command specifically.
-
=head2 quit | exit
This exits guestfish. You can also use C<^D> key.
-=head2 reopen
-
- reopen
-
-Close and reopen the libguestfs handle. It is not necessary to use
-this normally, because the handle is closed properly when guestfish
-exits. However this is occasionally useful for testing.
-
-=head2 sparse
-
- sparse filename size
-
-This creates an empty sparse file of the given size, and then adds
-so it can be further examined.
-
-In all respects it works the same as the C<alloc> command, except that
-the image file is allocated sparsely, which means that disk blocks are
-not assigned to the file until they are needed. Sparse disk files
-only use space when written to, but they are slower and there is a
-danger you could run out of real disk space during a write operation.
-
-For more advanced image creation, see L<qemu-img(1)> utility.
-
-Size can be specified using standard suffixes, eg. C<1M>.
-
-=head2 supported
-
- supported
-
-This command returns a list of the optional groups
-known to the daemon, and indicates which ones are
-supported by this build of the libguestfs appliance.
-
-See also L<guestfs(3)/AVAILABILITY>.
-
-=head2 time
-
- time command args...
-
-Run the command as usual, but print the elapsed time afterwards. This
-can be useful for benchmarking operations.
+@FISH_COMMANDS@
=head1 COMMANDS
process to control. See section
L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
+=item HEXEDITOR
+
+The L</hexedit> command uses C<$HEXEDITOR> as the external hex
+editor. If not specified, the external L<hexedit(1)> program
+is used.
+
=item HOME
If compiled with GNU readline support, various files in the
Location of temporary directory, defaults to C</tmp>.
-If libguestfs was compiled to use the supermin appliance then each
-handle will require rather a large amount of space in this directory
-for short periods of time (~ 80 MB). You can use C<$TMPDIR> to
+If libguestfs was compiled to use the supermin appliance then the
+real appliance is cached in this directory, shared between all
+handles belonging to the same EUID. You can use C<$TMPDIR> to
configure another directory to use in case C</tmp> is not large
enough.
L<virt-rescue(1)>,
L<virt-resize(1)>,
L<virt-tar(1)>,
-L<virt-win-reg(1)>.
+L<virt-win-reg(1)>,
+L<hexedit(1)>.
=head1 AUTHORS
git.annexia.org / libguestfs.git / blobdiff