X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfish.pod;h=f2255f1674a06eae29e8efb40feb345d84347b1c;hp=e3ffe52ce3063df3c479e5adca2978b7712200ac;hb=10258cadd0067cb49b89faf1ce424b1c01f5a7c3;hpb=ad64aff8342198f11cf7d8ffff148a9cd5afe6ce diff --git a/guestfish.pod b/guestfish.pod index e3ffe52..f2255f1 100644 --- a/guestfish.pod +++ b/guestfish.pod @@ -66,6 +66,11 @@ Remove C (in reality not such a great idea): 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 @@ -92,6 +97,13 @@ 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 @@ -118,11 +130,17 @@ Typical usage is either: guestfish -i /dev/Guests/MyGuest -You cannot use I<-a> or I<-m> in conjunction with this option, and -options other than I<--ro> might not behave correctly. +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. @@ -139,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 @@ -149,21 +172,14 @@ 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<-x> - -Echo each command before executing it. - -=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<-V> | B<--version> Display the guestfish / libguestfs version number and exit. +=item B<-x> + +Echo each command before executing it. + =back =head1 COMMANDS ON COMMAND LINE @@ -312,6 +328,20 @@ 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 @@ -323,6 +353,58 @@ 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 REMOTE CONTROL GUESTFISH OVER A SOCKET + +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. + +Start a guestfish server process using: + + eval `guestfish --listen` + +and then send it commands by doing: + + 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 @@ -451,6 +533,12 @@ can be useful for benchmarking operations. 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 @@ -488,6 +576,16 @@ used. The C command uses C<$PAGER> as the pager. If not set, it uses C. +=item TMPDIR + +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 +configure another directory to use in case C is not large +enough. + =back =head1 EXIT CODE