guestfish -a disk.img -m dev[:mountpoint]
- guestfish -i libvirt-domain
+ guestfish -d libvirt-domain
- guestfish -i disk.img [disk.img ...]
+ guestfish -a disk.img -i
+
+ guestfish -d libvirt-domain -i
+
+=head1 WARNING
+
+Using guestfish in read/write mode on live virtual machines can be
+dangerous, potentially causing disk corruption. Use the I<--ro>
+(read-only) option to use guestfish safely if the disk image or
+virtual machine might be live.
=head1 EXAMPLES
--mount /dev/sda1:/boot \
edit /boot/grub/grub.conf
-=head2 Using virt-inspector
+=head2 Mount disks automatically
+
+Use the I<-i> option to automatically mount the
+disks from a virtual machine:
-Use the I<-i> option to get virt-inspector to mount
-the filesystems automatically as they would be mounted
-in the virtual machine:
+ guestfish --ro -a disk.img -i cat /etc/group
- guestfish --ro -i disk.img cat /etc/group
+ guestfish --ro -d libvirt-domain -i cat /etc/group
=head2 As a script interpreter
To list what is available do:
- guestfish -N list | less
+ guestfish -N help | less
=head2 Remote control
rescue a broken virtual machine image, you should look at the
L<virt-rescue(1)> command.
-Using guestfish in read/write mode on live virtual machines can be
-dangerous, potentially causing disk corruption. Use the I<--ro>
-(read-only) option to use guestfish safely if the disk image or
-virtual machine might be live.
-
=head1 OPTIONS
=over 4
Add a block device or virtual machine image to the shell.
+=item B<-c URI> | B<--connect URI>
+
+When used in conjunction with the I<-d> option, this specifies
+the libvirt URI to use. The default is to use the default libvirt
+connection.
+
+=item B<-d libvirt-domain> | B<--domain libvirt-domain>
+
+Add disks from the named libvirt domain. If the I<--ro> option is
+also used, then any libvirt domain can be used. However in write
+mode, only libvirt domains which are shut down can be named here.
+
=item B<-D> | B<--no-dest-paths>
Don't tab-complete paths on the guest filesystem. It is useful to be
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
=item B<-i> | B<--inspector>
-Run virt-inspector on the named libvirt domain or list of disk
-images. If virt-inspector is available and if it can identify
-the domain or disk images, then partitions will be mounted
-correctly at start-up.
+Using L<virt-inspector(1)> code, inspect the disks looking for
+an operating system and mount filesystems as they would be
+mounted on the real virtual machine.
Typical usage is either:
- guestfish -i myguest
+ guestfish -d myguest -i
(for an inactive libvirt domain called I<myguest>), or:
- guestfish --ro -i myguest
+ guestfish --ro -d myguest -i
(for active domains, readonly), or specify the block device directly:
- guestfish -i /dev/Guests/MyGuest
+ guestfish -a /dev/Guests/MyGuest -i
-You cannot use I<-a>, I<-m>, I<-N>, I<--listen>, I<--remote> or
-I<--selinux> in conjunction with this option, and options other than
-I<--ro> might not behave correctly.
+Note that the command line syntax changed slightly over older
+versions of guestfish. You can still use the old syntax:
-See also: L<virt-inspector(1)>.
+ guestfish [--ro] -i disk.img
+
+ guestfish [--ro] -i libvirt-domain
+
+=item B<--keys-from-stdin>
+
+Read key or passphrase parameters from stdin. The default is
+to try to read passphrases from the user by opening C</dev/tty>.
=item B<--listen>
Disable autosync. This is enabled by default. See the discussion
of autosync in the L<guestfs(3)> manpage.
-=item B<-N type> | B<--new type> | B<-N list>
+=item B<-N type> | B<--new type> | B<-N help>
Prepare a fresh disk image formatted as "type". This is an
alternative to the I<-a> option: whereas I<-a> adds an existing disk,
I<-N> creates a preformatted disk with a filesystem and adds it.
See L</PREPARED DISK IMAGES> below.
+=item B<--progress-bars>
+
+Enable progress bars, even when guestfish is used non-interactively.
+
+Progress bars are enabled by default when guestfish is used as an
+interactive shell.
+
+=item B<--no-progress-bars>
+
+Disable progress bars.
+
=item B<--remote[=pid]>
Send remote commands to C<$GUESTFISH_PID> or C<pid>. See section
echo "~"
+=head1 ENCRYPTED DISKS
+
+Libguestfs has some support for Linux guests encrypted according to
+the Linux Unified Key Setup (LUKS) standard, which includes nearly all
+whole disk encryption systems used by modern Linux guests. Currently
+only LVM-on-LUKS is supported.
+
+Identify encrypted block devices and partitions using L</vfs-type>:
+
+ ><fs> vfs-type /dev/sda2
+ crypto_LUKS
+
+Then open those devices using L</luks-open>. This creates a
+device-mapper device called C</dev/mapper/luksdev>.
+
+ ><fs> luks-open /dev/sda2 luksdev
+ Enter key or passphrase ("key"): <enter the passphrase>
+
+Finally you have to tell LVM to scan for volume groups on
+the newly created mapper device:
+
+ ><fs> vgscan
+ ><fs> vg-activate-all true
+
+The logical volume(s) can now be mounted in the usual way.
+
+Before closing a LUKS device you must unmount any logical volumes on
+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
+
=head1 WINDOWS PATHS
If a path is prefixed with C<win:> then you can use Windows-style
To list the available types and any extra parameters they take, run:
- guestfish -N list | less
+ guestfish -N help | less
Note that the prepared filesystem is not mounted. You would usually
have to use the C<mount /dev/sda1 /> command or add the
guestfish -N disk:200M
-=head1 GUESTFISH COMMANDS
-
-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.
+=head1 PROGRESS BARS
-For more advanced image creation, see L<qemu-img(1)> utility.
+Some (not all) long-running commands send progress notification
+messages as they are running. Guestfish turns these messages into
+progress bars.
-Size can be specified using standard suffixes, eg. C<1M>.
+When a command that supports progress bars takes longer than two
+seconds to run, and if progress bars are enabled, then you will see
+one appearing below the command:
-=head2 echo
+ ><fs> copy-size /large-file /another-file 2048M
+ / 10% [#####-----------------------------------------] 00:30
- echo [params ...]
+The spinner on the left hand side moves round once for every progress
+notification received from the backend. This is a (reasonably) golden
+assurance that the command is "doing something" even if the progress
+bar is not moving, because the command is able to send the progress
+notifications. When the bar reaches 100% and the command finishes,
+the spinner disappears.
-This echos the parameters to the terminal.
+Progress bars are enabled by default when guestfish is used
+interactively. You can enable them even for non-interactive modes
+using I<--progress-bars>, and you can disable them completely using
+I<--no-progress-bars>.
-=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.
-
-NOTE: This will not work reliably for large files
-(> 2 MB) or binary files containing \0 bytes.
-
-=head2 glob
-
- glob command args...
-
-Expand wildcards in any paths in the args list, and run C<command>
-repeatedly on each matching path.
+=head1 GUESTFISH COMMANDS
-See section WILDCARDS AND GLOBBING.
+The commands in this section are guestfish convenience commands, in
+other words, they are not part of the L<guestfs(3)> API.
=head2 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.
-
-NOTE: This will not work reliably for large files
-(> 2 MB) or binary files containing \0 bytes.
-
=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
@ACTIONS@
+=head1 EXIT CODE
+
+guestfish returns 0 if the commands completed without error, or
+1 if there was an error.
+
=head1 ENVIRONMENT VARIABLES
=over 4
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, then the command history
-is saved in C<$HOME/.guestfish>
+If compiled with GNU readline support, various files in the
+home directory can be used. See L</FILES>.
=item LIBGUESTFS_APPEND
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.
=back
-=head1 EXIT CODE
+=head1 FILES
-guestfish returns 0 if the commands completed without error, or
-1 if there was an error.
+=over 4
+
+=item $HOME/.guestfish
+
+If compiled with GNU readline support, then the command history
+is saved in this file.
+
+=item $HOME/.inputrc
+
+=item /etc/inputrc
+
+If compiled with GNU readline support, then these files can be used to
+configure readline. For further information, please see
+L<readline(3)/INITIALIZATION FILE>.
+
+To write rules which only apply to guestfish, use:
+
+ $if guestfish
+ ...
+ $endif
+
+Variables that you can set in inputrc that change the behaviour
+of guestfish in useful ways include:
+
+=over 4
+
+=item completion-ignore-case (default: on)
+
+By default, guestfish will ignore case when tab-completing
+paths on the disk. Use:
+
+ set completion-ignore-case off
+
+to make guestfish case sensitive.
+
+=back
+
+=item test1.img
+
+=item test2.img (etc)
+
+When using the C<-N> or C<--new> option, the prepared disk or
+filesystem will be created in the file C<test1.img> in the current
+directory. The second use of C<-N> will use C<test2.img> and so on.
+Any existing file with the same name will be overwritten.
+
+=back
=head1 SEE ALSO
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