X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=fc32d0a93b3b434af4568a0854b332cc95b2f1d6;hp=cf1140a59597c96ab1e860fb82e5f520d382fd69;hb=406dbf7565e702588f172a8cc534acacb2fd7bee;hpb=4440e22f4f7ebffe0728a8c019319d1a2b260cf5 diff --git a/fish/guestfish.pod b/fish/guestfish.pod index cf1140a..fc32d0a 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -27,6 +27,17 @@ 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 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. + +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 command. + =head1 EXAMPLES =head2 As an interactive shell @@ -40,11 +51,22 @@ virtual machine might be live. 'man' to read the manual 'quit' to quit the shell - > man + > add-ro disk.img + > run + > list-filesystems + /dev/sda1: ext4 + /dev/vg_guest/lv_root: ext4 + /dev/vg_guest/lv_swap: swap + > mount /dev/vg_guest/lv_root / + > cat /etc/fstab + # /etc/fstab + # Created by anaconda + [...] + > exit =head2 From shell scripts -Create a new C file in a guest: +Create a new C file in a guest or disk image: guestfish <<_EOF_ add disk.img @@ -53,13 +75,20 @@ Create a new C file in a guest: 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 in a guest: @@ -84,6 +113,10 @@ disks from a virtual machine: guestfish --ro -d libvirt-domain -i cat /etc/group +Another way to edit C 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: @@ -103,26 +136,15 @@ a single ext2-formatted partition: To list what is available do: - guestfish -N list | less + guestfish -N help | less =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. - -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 command. - =head1 OPTIONS =over 4 @@ -162,6 +184,13 @@ able to hit the tab key to complete paths on the guest filesystem, but 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. To write pure guestfish @@ -225,13 +254,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 @@ -316,9 +356,10 @@ any other commands C is a synonym for C. You must C (or C) 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 is done +automatically, simply because guestfish can't perform the action you +asked for without doing this. =head1 QUOTING @@ -457,7 +498,7 @@ following will not do what you expect: rm-rf /home/* -Assuming you don't have a directory literally called C +Assuming you don't have a directory called literally C then the above command will return an error. To perform wildcard expansion, use the C command. @@ -474,7 +515,7 @@ the command many times), equivalent to: C 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 @@ -566,8 +607,8 @@ device-mapper device called C. Finally you have to tell LVM to scan for volume groups on the newly created mapper device: - > vgscan - > vg-activate-all true + vgscan + vg-activate-all true The logical volume(s) can now be mounted in the usual way. @@ -575,8 +616,8 @@ 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 + vg-activate false /dev/VG + luks-close /dev/mapper/luksdev =head1 WINDOWS PATHS @@ -706,7 +747,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 @@ -729,50 +770,35 @@ Create a blank 200MB disk: 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 API. - -=head2 alloc | allocate +=head1 PROGRESS BARS - alloc filename size +Some (not all) long-running commands send progress notification +messages as they are running. Guestfish turns these messages into +progress bars. -This creates an empty (zeroed) file of the given size, and then adds -so it can be further examined. +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: -For more advanced image creation, see L utility. + > copy-size /large-file /another-file 2048M + / 10% [#####-----------------------------------------] 00:30 -Size can be specified using standard suffixes, eg. C<1M>. +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. -=head2 echo +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>. - 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 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... - -Expand wildcards in any paths in the args list, and run C -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 API. =head2 help @@ -782,80 +808,11 @@ See section WILDCARDS AND GLOBBING. Without any parameter, this lists all commands. With a C 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 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 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. -=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 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 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. - -=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 @@ -881,6 +838,12 @@ Used with the I<--remote> option to specify the remote guestfish process to control. See section L. +=item HEXEDITOR + +The L command uses C<$HEXEDITOR> as the external hex +editor. If not specified, the external L program +is used. + =item HOME If compiled with GNU readline support, various files in the @@ -926,9 +889,9 @@ set, it uses C. Location of temporary directory, defaults to C. -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 is not large enough. @@ -998,7 +961,8 @@ L, L, L, L, -L. +L, +L. =head1 AUTHORS