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
Welcome to guestfish, the libguestfs filesystem interactive shell for
editing virtual machine filesystems.
- Type: 'help' for help with commands
+ Type: 'help' for a list of commands
+ 'man' to read the manual
'quit' to quit the shell
- ><fs> help
+ ><fs> man
=head2 From shell scripts
add disk.img
run
mount /dev/vg_guest/lv_root /
- write_file /etc/motd "Welcome, new users" 0
+ write /etc/motd "Welcome, new users"
_EOF_
List the LVM logical volumes in a guest:
guestfish \
add disk.img : run : mount /dev/vg_guest/lv_root / : \
- write-file /etc/resolv.conf "nameserver 1.2.3.4" 0
+ write /etc/resolv.conf "nameserver 1.2.3.4"
Edit C</boot/grub/grub.conf> interactively:
--mount /dev/sda1:/boot \
edit /boot/grub/grub.conf
-=head2 Using virt-inspector
+=head2 Mount disks automatically
-Use the I<-i> option to get virt-inspector to mount
-the filesystems automatically as they would be mounted
-in the virtual machine:
+Use the I<-i> option to automatically mount the
+disks from a virtual machine:
- guestfish --ro -i disk.img cat /etc/group
+ guestfish --ro -a disk.img -i cat /etc/group
+
+ guestfish --ro -d libvirt-domain -i cat /etc/group
=head2 As a script interpreter
-Create a 50MB disk containing an ext2-formatted partition:
+Create a 100MB disk containing an ext2-formatted partition:
#!/usr/bin/guestfish -f
- alloc /tmp/output.img 50M
+ sparse test1.img 100M
run
part-disk /dev/sda mbr
mkfs ext2 /dev/sda1
+=head2 Start with a prepared disk
+
+An alternate way to create a 100MB disk called C<test1.img> containing
+a single ext2-formatted partition:
+
+ guestfish -N fs
+
+To list what is available do:
+
+ guestfish -N list | less
+
=head2 Remote control
eval `guestfish --listen --ro`
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
=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
+
+Note that the command line syntax changed slightly over older
+versions of guestfish. You can still use the old syntax:
+
+ guestfish [--ro] -i disk.img
-You cannot use I<-a>, I<-m>, I<--listen>, I<--remote> or I<--selinux>
-in conjunction with this option, and options other than I<--ro> might
-not behave correctly.
+ guestfish [--ro] -i libvirt-domain
-See also: L<virt-inspector(1)>.
+=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>
+
+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
might be running, and is generally recommended in cases where you
don't need write access to the disk.
+Note that prepared disk images created with I<-N> are not affected by
+the I<--ro> option.
+
=item B<--selinux>
Enable SELinux support for the guest. See L<guestfs(3)/SELINUX>.
=head1 NUMBERS
-Commands which take integers as parameters use the C convention which
-is to use C<0> to prefix an octal number or C<0x> to prefix a
-hexadecimal number. For example:
+This section applies to all commands which can take integers
+as parameters.
+
+=head2 SIZE SUFFIX
+
+When the command takes a parameter measured in bytes, you can use one
+of the following suffixes to specify kilobytes, megabytes and larger
+sizes:
+
+=over 4
+
+=item B<k> or B<K> or B<KiB>
+
+The size in kilobytes (multiplied by 1024).
+
+=item B<KB>
+
+The size in SI 1000 byte units.
+
+=item B<M> or B<MiB>
+
+The size in megabytes (multiplied by 1048576).
+
+=item B<MB>
+
+The size in SI 1000000 byte units.
+
+=item B<G> or B<GiB>
+
+The size in gigabytes (multiplied by 2**30).
+
+=item B<GB>
+
+The size in SI 10**9 byte units.
+
+=item B<T> or B<TiB>
+
+The size in terabytes (multiplied by 2**40).
+
+=item B<TB>
+
+The size in SI 10**12 byte units.
+
+=item B<P> or B<PiB>
+
+The size in petabytes (multiplied by 2**50).
+
+=item B<PB>
+
+The size in SI 10**15 byte units.
+
+=item B<E> or B<EiB>
+
+The size in exabytes (multiplied by 2**60).
+
+=item B<EB>
+
+The size in SI 10**18 byte units.
+
+=item B<Z> or B<ZiB>
+
+The size in zettabytes (multiplied by 2**70).
+
+=item B<ZB>
+
+The size in SI 10**21 byte units.
+
+=item B<Y> or B<YiB>
+
+The size in yottabytes (multiplied by 2**80).
+
+=item B<YB>
+
+The size in SI 10**24 byte units.
+
+=back
+
+For example:
+
+ truncate-size /file 1G
+
+would truncate the file to 1 gigabyte.
+
+Be careful because a few commands take sizes in kilobytes or megabytes
+(eg. the parameter to L</memsize> is specified in megabytes already).
+Adding a suffix will probably not do what you expect.
+
+=head2 OCTAL AND HEXADECIMAL NUMBERS
+
+For specifying the radix (base) use the C convention: C<0> to prefix
+an octal number or C<0x> to prefix a hexadecimal number. For example:
1234 decimal number 1234
02322 octal number, equivalent to decimal 1234
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
handles case insensitivity like Windows would. This only works in
argument positions that expect a path.
+=head1 UPLOADING AND DOWNLOADING FILES
+
+For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and
+others which upload from or download to a local file, you can use the
+special filename C<-> to mean "from stdin" or "to stdout". For example:
+
+ upload - /foo
+
+reads stdin and creates from that a file C</foo> in the disk image,
+and:
+
+ tar-out /etc - | tar tf -
+
+writes the tarball to stdout and then pipes that into the external
+"tar" command (see L</PIPES>).
+
+When using C<-> to read from stdin, the input is read up to the end of
+stdin. You can also use a special "heredoc"-like syntax to read up to
+some arbitrary end marker:
+
+ upload -<<END /foo
+ input line 1
+ input line 2
+ input line 3
+ END
+
+Any string of characters can be used instead of C<END>. The end
+marker must appear on a line of its own, without any preceeding or
+following characters (not even spaces).
+
+Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
+upload local files (so-called "FileIn" parameters in the generator).
+
=head1 EXIT ON ERROR BEHAVIOUR
By default, guestfish will ignore any errors when in interactive mode
Guestfish client and server versions must match exactly.
-=head1 UPLOADING AND DOWNLOADING FILES
-
-For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and
-others which upload from or download to a local file, you can use the
-special filename C<-> to mean "from stdin" or "to stdout". For example:
-
- upload - /foo
-
-reads stdin and creates from that a file C</foo> in the disk image,
-and:
-
- tar-out /etc - | tar tf -
-
-writes the tarball to stdout and then pipes that into the external
-"tar" command (see L</PIPES>).
+=head1 PREPARED DISK IMAGES
-When using C<-> to read from stdin, the input is read up to the end of
-stdin. You can also use a special "heredoc"-like syntax to read up to
-some arbitrary end marker:
+Use the I<-N type> or I<--new type> parameter to select one of a set
+of preformatted disk images that guestfish can make for you to save
+typing. This is particularly useful for testing purposes. This
+option is used instead of the I<-a> option, and like I<-a> can appear
+multiple times (and can be mixed with I<-a>).
- upload -<<END /foo
- input line 1
- input line 2
- input line 3
- END
+The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
+for the second and so on. Existing files in the current directory are
+I<overwritten>.
-Any string of characters can be used instead of C<END>. The end
-marker must appear on a line of its own, without any preceeding or
-following characters (not even spaces).
+The type briefly describes how the disk should be sized, partitioned,
+how filesystem(s) should be created, and how content should be added.
+Optionally the type can be followed by extra parameters, separated by
+C<:> (colon) characters. For example, I<-N fs> creates a default
+100MB, sparsely-allocated disk, containing a single partition, with
+the partition formatted as ext2. I<-N fs:ext4:1G> is the same, but
+for an ext4 filesystem on a 1GB disk instead.
-Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
-upload local files (so-called "FileIn" parameters in the generator).
+To list the available types and any extra parameters they take, run:
-=head1 GUESTFISH COMMANDS
+ guestfish -N list | less
-The commands in this section are guestfish convenience commands, in
-other words, they are not part of the L<guestfs(3)> API.
+Note that the prepared filesystem is not mounted. You would usually
+have to use the C<mount /dev/sda1 /> command or add the
+I<-m /dev/sda1> option.
-=head2 alloc | allocate
+If any I<-N> or I<--new> options are given, the guest is automatically
+launched.
- alloc filename size
+=head2 EXAMPLES
-This creates an empty (zeroed) file of the given size, and then adds
-so it can be further examined.
+Create a 100MB disk with an ext4-formatted partition:
-For more advanced image creation, see L<qemu-img(1)> utility.
+ guestfish -N fs:ext4
-Size can be specified (where C<nn> means a number):
+Create a 32MB disk with a VFAT-formatted partition, and mount it:
-=over 4
+ guestfish -N fs:vfat:32M -m /dev/sda1
-=item C<nn> or C<nn>K or C<nn>KB
+Create a blank 200MB disk:
-number of kilobytes, eg: C<1440> = standard 3.5in floppy
+ guestfish -N disk:200M
-=item C<nn>M or C<nn>MB
+=head1 PROGRESS BARS
-number of megabytes
+Some (not all) long-running commands send progress notification
+messages as they are running. Guestfish turns these messages into
+progress bars.
-=item C<nn>G or C<nn>GB
+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:
-number of gigabytes
+ ><fs> copy-size /large-file /another-file 2048M
+ / 10% [#####-----------------------------------------] 00:30
-=item C<nn>T or C<nn>TB
+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.
-number of terabytes
+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>.
-=item C<nn>P or C<nn>PB
+=head1 GUESTFISH COMMANDS
-number of petabytes
+The commands in this section are guestfish convenience commands, in
+other words, they are not part of the L<guestfs(3)> API.
-=item C<nn>E or C<nn>EB
+=head2 alloc | allocate
-number of exabytes
+ alloc filename size
-=item C<nn>sects
+This creates an empty (zeroed) file of the given size, and then adds
+so it can be further examined.
-number of 512 byte sectors
+For more advanced image creation, see L<qemu-img(1)> utility.
-=back
+Size can be specified using standard suffixes, eg. C<1M>.
=head2 echo
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
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
+Size can be specified using standard suffixes, eg. C<1M>.
-=item C<nn>M or C<nn>MB
+=head2 supported
-number of megabytes
+ supported
-=item C<nn>G or C<nn>GB
+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.
-number of gigabytes
-
-=item C<nn>T or C<nn>TB
-
-number of terabytes
-
-=item C<nn>P or C<nn>PB
-
-number of petabytes
-
-=item C<nn>E or C<nn>EB
-
-number of exabytes
-
-=item C<nn>sects
-
-number of 512 byte sectors
-
-=back
+See also L<guestfs(3)/AVAILABILITY>.
=head2 time
@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
=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
=back
-=head1 EXIT CODE
+=head1 FILES
+
+=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
-guestfish returns I<0> if the commands completed without error, or
-I<1> if there was an error.
+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
=head1 COPYRIGHT
-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2010 Red Hat Inc.
L<http://libguestfs.org/>
This program is free software; you can redistribute it and/or modify