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
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<file>. To write pure guestfish
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>, I<--remote> or I<--selinux>
+in conjunction with this option, and options other than I<--ro> might
+not behave correctly.
See also: L<virt-inspector(1)>.
+=item B<--listen>
+
+Fork into the background and listen for remote commands. See section
+I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
+
=item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
Mount the named partition or logical volume on the given mountpoint.
Disable autosync. This is enabled by default. See the discussion
of autosync in the L<guestfs(3)> manpage.
+=item B<--remote[=pid]>
+
+Send remote commands to C<$GUESTFISH_PID> or C<pid>. See section
+I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
+
=item B<-r> | B<--ro>
This changes the C<-m> option so that mounts are done read-only
(see C<guestfs_mount_ro> in the L<guestfs(3)> manpage).
+=item B<--selinux>
+
+Enable SELinux support for the guest. See L<guestfs(3)/SELINUX>.
+
=item B<-v> | B<--verbose>
Enable very verbose messages. This is particularly useful if you find
a bug.
-=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
rm '/"'
A few commands require a list of strings to be passed. For these, use
-a space-separated list, enclosed in quotes. For example:
+a whitespace-separated list, enclosed in quotes. Strings containing whitespace
+to be passed through must be enclosed in single quotes. A literal single quote
+must be escaped with a backslash.
vgcreate VG "/dev/sda1 /dev/sdb1"
+ command "/bin/echo 'foo bar'"
+ command "/bin/echo \'foo\'"
=head1 WILDCARDS AND GLOBBING
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<on the
+host>, 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
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<EXIT ON
+ERROR BEHAVIOUR>.
+
+=head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES
+
+The C<eval> 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 REMOTE CONTROL DETAILS
+
+Remote control happens over a Unix domain socket called
+C</tmp/.guestfish-$UID/socket-$PID>, 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
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...
The C<edit> command uses C<$EDITOR> as the editor. If not
set, it uses C<vi>.
+=item GUESTFISH_PID
+
+Used with the I<--remote> option to specify the remote guestfish
+process to control. See section I<REMOTE CONTROL GUESTFISH OVER A
+SOCKET>.
+
=item HOME
If compiled with GNU readline support, then the command history
the qemu which was found at compile time by the configure script is
used.
+=item LIBGUESTFS_TRACE
+
+Set C<LIBGUESTFS_TRACE=1> to enable command traces.
+
=item PAGER
The C<more> command uses C<$PAGER> as the pager. If not
set, it uses C<more>.
+=item TMPDIR
+
+Location of temporary directory, defaults to C</tmp>.
+
+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</tmp> is not large
+enough.
+
=back
=head1 EXIT CODE
git.annexia.org / libguestfs.git / blobdiff