X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=70de8e3982f3678b5fdfb2eb3c72aee09de6c4ce;hp=5737c464759ca1577245d41c7d036bc408c8def5;hb=2635a9c70e5f8aab85bbcb6b7a645f720d1e4466;hpb=21bd2db7cf259a17cc3922409937b849e4b83c0f diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 5737c46..70de8e3 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -14,9 +14,11 @@ guestfish - the libguestfs Filesystem Interactive SHell 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 @@ -73,13 +75,14 @@ Edit C interactively: --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 @@ -100,7 +103,7 @@ a single ext2-formatted partition: To list what is available do: - guestfish -N list | less + guestfish -N help | less =head2 Remote control @@ -140,6 +143,18 @@ Displays detailed help on a single command C. 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 @@ -156,28 +171,33 @@ scripts, use: =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 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), 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. + 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. =item B<--listen> @@ -205,13 +225,24 @@ or you can use the L program. Disable autosync. This is enabled by default. See the discussion of autosync in the L 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 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. See section @@ -525,6 +556,39 @@ it, eg: 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 /dev/sda2 + crypto_LUKS + +Then open those devices using L. This creates a +device-mapper device called C. + + > luks-open /dev/sda2 luksdev + Enter key or passphrase ("key"): + +Finally you have to tell LVM to scan for volume groups on +the newly created mapper device: + + > vgscan + > 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 +on each one. Then you can close the mapper device: + + > vg-activate false /dev/VG + > luks-close /dev/mapper/luksdev + =head1 WINDOWS PATHS If a path is prefixed with C then you can use Windows-style @@ -653,7 +717,7 @@ for an ext4 filesystem on a 1GB disk instead. 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 command or add the @@ -676,6 +740,31 @@ Create a blank 200MB disk: guestfish -N disk:200M +=head1 PROGRESS BARS + +Some (not all) long-running commands send progress notification +messages as they are running. Guestfish turns these messages into +progress bars. + +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: + + > copy-size /large-file /another-file 2048M + / 10% [#####-----------------------------------------] 00:30 + +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. + +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>. + =head1 GUESTFISH COMMANDS The commands in this section are guestfish convenience commands, in @@ -692,6 +781,40 @@ For more advanced image creation, see L utility. Size can be specified using standard suffixes, eg. C<1M>. +=head2 copy-in + + copy-in local [local ...] /remotedir + +C copies local files or directories recursively into the disk +image, placing them in the directory called C (which must +exist). This guestfish meta-command turns into a sequence of +L 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 copies remote files or directories recursively out of the +disk image, placing them on the host disk in a local directory called +C (which must exist). This guestfish meta-command turns +into a sequence of L, L 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 +this with the help of L like this: + + glob copy-out /home/* . + =head2 echo echo [params ...] @@ -709,9 +832,6 @@ The editor is C<$EDITOR>. However if you use the alternate commands C or C 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... @@ -755,9 +875,6 @@ This is used to view a file. The default viewer is C<$PAGER>. However if you use the alternate command C you will get the C 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.