X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfish.pod;h=f2255f1674a06eae29e8efb40feb345d84347b1c;hp=d83a61ca5549042aa9372ebad11b7fa5f680b661;hb=e15ff2113f5b2a7e0aa138c47c14e93268d25aed;hpb=394c8bec21d47b74567a4148fdbf87318c301441 diff --git a/guestfish.pod b/guestfish.pod index d83a61c..f2255f1 100644 --- a/guestfish.pod +++ b/guestfish.pod @@ -8,6 +8,10 @@ guestfish - the libguestfs filesystem interactive shell guestfish [--options] [commands] + guestfish -i libvirt-domain + + guestfish -i disk-image(s) + =head1 EXAMPLES =head2 From shell scripts @@ -40,21 +44,33 @@ Remove C (in reality not such a great idea): guestfish --add disk.img \ --mount /dev/VolGroup00/LogVol00 \ --mount /dev/sda1:/boot \ - rm /boot/grub/menu.lst : \ - sync : exit + rm /boot/grub/menu.lst =head2 As an interactive shell $ guestfish - + Welcome to guestfish, the libguestfs filesystem interactive shell for editing virtual machine filesystems. - + Type: 'help' for help with commands 'quit' to quit the shell - + > help +=head2 As a script interpreter + + #!/usr/bin/guestfish -f + alloc /tmp/output.img 10M + run + sfdisk /dev/sda 0 0 0 , + mkfs ext2 /dev/sda1 + +=head2 Remote control + + eval `guestfish --listen` + guestfish --remote cmd + =head1 DESCRIPTION Guestfish is a shell and command-line tool for examining and modifying @@ -81,6 +97,50 @@ Displays detailed help on a single command C. Add a block device or virtual machine image to the shell. +=item B<-D> | B<--no-dest-paths> + +Don't tab-complete paths on the guest filesystem. It is useful to be +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<-f file> | B<--file file> + +Read commands from C. To write pure guestfish +scripts, use: + + #!/usr/bin/guestfish -f + +=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. + +Typical usage is either: + + guestfish -i myguest + +(for an inactive libvirt domain called I), or: + + guestfish --ro -i myguest + +(for active domains, readonly), or specify the block device directly: + + guestfish -i /dev/Guests/MyGuest + +You cannot use I<-a>, I<-m>, I<--listen> or I<--remote> in conjunction +with this option, and options other than I<--ro> might not behave +correctly. + +See also: L. + +=item B<--listen> + +Fork into the background and listen for remote commands. See section +I below. + =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]> Mount the named partition or logical volume on the given mountpoint. @@ -97,6 +157,11 @@ automatically launched. Disable autosync. This is enabled by default. See the discussion of autosync in the L manpage. +=item B<--remote[=pid]> + +Send remote commands to C<$GUESTFISH_PID> or C. See section +I below. + =item B<-r> | B<--ro> This changes the C<-m> option so that mounts are done read-only @@ -107,12 +172,13 @@ This changes the C<-m> option so that mounts are done read-only Enable very verbose messages. This is particularly useful if you find a bug. -=item B<-D> | B<--no-dest-paths> +=item B<-V> | B<--version> -Don't tab-complete paths on the guest filesystem. It is useful to be -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. +Display the guestfish / libguestfs version number and exit. + +=item B<-x> + +Echo each command before executing it. =back @@ -236,6 +302,46 @@ will create a directory C on the host, and then export the contents of C on the mounted filesystem to C. (See C). +=head1 PIPES + +Use CspaceE | command> to pipe the output of the +first command (a guestfish command) to the second command (any host +command). For example: + + cat /etc/passwd | awk -F: '$3 == 0 { print }' + +(where C is the guestfish cat command, but C is the host awk +program). The above command would list all accounts in the guest +filesystem which have UID 0, ie. root accounts including backdoors. +Other examples: + + hexdump /bin/ls | head + list-devices | tail -1 + +The space before the pipe symbol is required, any space after the pipe +symbol is optional. Everything after the pipe symbol is just passed +straight to the host shell, so it can contain redirections, globs and +anything else that makes sense on the host side. + +To use a literal argument which begins with a pipe symbol, you have +to quote it, eg: + + echo "|" + +=head1 HOME DIRECTORIES + +If a parameter starts with the character C<~> then the tilde may be +expanded as a home directory path (either C<~> for the current user's +home directory, or C<~user> for another user). + +Note that home directory expansion happens for users known I, not in the guest filesystem. + +To use a literal argument which begins with a tilde, you have to quote +it, eg: + + echo "~" + =head1 EXIT ON ERROR BEHAVIOUR By default, guestfish will ignore any errors when in interactive mode @@ -247,19 +353,62 @@ If you prefix a command with a I<-> character, then that command will not cause guestfish to exit, even if that (one) command returns an error. -=head1 COMMANDS +=head1 REMOTE CONTROL GUESTFISH OVER A SOCKET -=head2 help +Guestfish can be remote-controlled over a socket. This is useful +particularly in shell scripts where you want to make several different +changes to a filesystem, but you don't want the overhead of starting +up a guestfish process each time. - help - help cmd +Start a guestfish server process using: -Without any parameter, this lists all commands. With a C -parameter, this displays detailed help for a command. + eval `guestfish --listen` -=head2 quit | exit +and then send it commands by doing: -This exits guestfish. You can also use C<^D> key. + guestfish --remote cmd [...] + +To cause the server to exit, send it the exit command: + + guestfish --remote exit + +Note that the server will normally exit if there is an error in a +command. You can change this in the usual way. See section I. + +=head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES + +The C statement sets the environment variable C<$GUESTFISH_PID>, +which is how the C<--remote> option knows where to send the commands. +You can have several guestfish listener processes running using: + + eval `guestfish --listen` + pid1=$GUESTFISH_PID + eval `guestfish --listen` + pid2=$GUESTFISH_PID + ... + guestfish --remote=$pid1 cmd + guestfish --remote=$pid2 cmd + +=head2 STANDARD OUTPUT DURING REMOTE CONTROL + +Because of limitations in the C statement, stdout from the +listener is currently redirected to C. + +Stderr is unchanged. + +=head2 REMOTE CONTROL DETAILS + +Remote control happens over a Unix domain socket called +C, where C<$UID> is the effective +user ID of the process, and C<$PID> is the process ID of the server. + +Guestfish client and server versions must match exactly. + +=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 @@ -312,6 +461,23 @@ 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. + +See section WILDCARDS AND GLOBBING. + +=head2 help + + help + help cmd + +Without any parameter, this lists all commands. With a C +parameter, this displays detailed help for a command. + =head2 lcd lcd directory @@ -321,14 +487,40 @@ itself. Note that C won't do what you might expect. -=head2 glob +=head2 more | less - glob command args... + more filename -Expand wildcards in any paths in the args list, and run C -repeatedly on each matching path. + less filename -See section WILDCARDS AND GLOBBING. +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 time + + time command args... + +Run the command as usual, but print the elapsed time afterwards. This +can be useful for benchmarking operations. + +=head1 COMMANDS @ACTIONS@ @@ -336,11 +528,38 @@ See section WILDCARDS AND GLOBBING. =over 4 +=item EDITOR + +The C command uses C<$EDITOR> as the editor. If not +set, it uses C. + +=item GUESTFISH_PID + +Used with the I<--remote> option to specify the remote guestfish +process to control. See section I. + +=item HOME + +If compiled with GNU readline support, then the command history +is saved in C<$HOME/.guestfish> + +=item LIBGUESTFS_APPEND + +Pass additional options to the guest kernel. + =item LIBGUESTFS_DEBUG Set C to enable verbose messages. This has the same effect as using the B<-v> option. +=item LIBGUESTFS_MEMSIZE + +Set the memory allocated to the qemu process, in megabytes. For +example: + + LIBGUESTFS_MEMSIZE=700 + =item LIBGUESTFS_PATH Set the path that guestfish uses to search for kernel and initrd.img. @@ -352,19 +571,20 @@ Set the default qemu binary that libguestfs uses. If not set, then the qemu which was found at compile time by the configure script is used. -=item LIBGUESTFS_APPEND +=item PAGER -Pass additional options to the guest kernel. - -=item HOME +The C command uses C<$PAGER> as the pager. If not +set, it uses C. -If compiled with GNU readline support, then the command history -is saved in C<$HOME/.guestfish> +=item TMPDIR -=item EDITOR +Location of temporary directory, defaults to C. -The C command uses C<$EDITOR> as the editor. If not -set, it uses 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 +configure another directory to use in case C is not large +enough. =back