Docs: group preformatted sections of text together.

[libguestfs.git] / guestfish.pod

diff --git a/guestfish.pod b/guestfish.pod
index f2255f1..026f82d 100644 (file)
--- a/guestfish.pod
+++ b/guestfish.pod
@@ -49,13 +49,13 @@ Remove C</boot/grub/menu.lst> (in reality not such a great idea):
 =head2 As an interactive shell
 
  $ guestfish
 =head2 As an interactive shell
 
  $ guestfish

-
+ 

  Welcome to guestfish, the libguestfs filesystem interactive shell for
  editing virtual machine filesystems.
  Welcome to guestfish, the libguestfs filesystem interactive shell for
  editing virtual machine filesystems.

-
+ 

  Type: 'help' for help with commands
        'quit' to quit the shell
  Type: 'help' for help with commands
        'quit' to quit the shell

-
+ 

  ><fs> help
 
 =head2 As a script interpreter
  ><fs> help
 
 =head2 As a script interpreter


@@ -63,7 +63,7 @@ Remove C</boot/grub/menu.lst> (in reality not such a great idea):
  #!/usr/bin/guestfish -f
  alloc /tmp/output.img 10M
  run
  #!/usr/bin/guestfish -f
  alloc /tmp/output.img 10M
  run

- sfdisk /dev/sda 0 0 0 ,
+ part-disk /dev/sda mbr

  mkfs ext2 /dev/sda1
 
 =head2 Remote control
  mkfs ext2 /dev/sda1
 
 =head2 Remote control


@@ -130,9 +130,9 @@ Typical usage is either:
 
  guestfish -i /dev/Guests/MyGuest
 
 
  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.
+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)>.
 
 
 See also: L<virt-inspector(1)>.
 


@@ -167,6 +167,10 @@ I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 This changes the C<-m> option so that mounts are done read-only
 (see C<guestfs_mount_ro> in the L<guestfs(3)> manpage).
 
 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
 =item B<-v> | B<--verbose>
 
 Enable very verbose messages.  This is particularly useful if you find


@@ -246,9 +250,13 @@ quotes.  For example:
  rm '/"'
 
 A few commands require a list of strings to be passed.  For these, use
  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"
 
  vgcreate VG "/dev/sda1 /dev/sdb1"

+ command "/bin/echo 'foo      bar'"
+ command "/bin/echo \'foo\'"

 
 =head1 WILDCARDS AND GLOBBING
 
 
 =head1 WILDCARDS AND GLOBBING
 


@@ -342,6 +350,23 @@ it, eg:
 
  echo "~"
 
 
  echo "~"
 

+=head1 WINDOWS PATHS
+
+If a path is prefixed with C<win:> then you can use Windows-style
+paths (with some limitations).  The following commands are equivalent:
+
+ file /WINDOWS/system32/config/system.LOG
+
+ file win:/windows/system32/config/system.log
+
+ file win:\windows\system32\config\system.log
+
+ file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG
+
+This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also
+handles case insensitivity like Windows would.  This only works in
+argument positions that expect a path.
+

 =head1 EXIT ON ERROR BEHAVIOUR
 
 By default, guestfish will ignore any errors when in interactive mode
 =head1 EXIT ON ERROR BEHAVIOUR
 
 By default, guestfish will ignore any errors when in interactive mode


@@ -390,13 +415,6 @@ You can have several guestfish listener processes running using:
  guestfish --remote=$pid1 cmd
  guestfish --remote=$pid2 cmd
 
  guestfish --remote=$pid1 cmd
  guestfish --remote=$pid2 cmd
 

-=head2 STANDARD OUTPUT DURING REMOTE CONTROL
-
-Because of limitations in the C<eval> statement, stdout from the
-listener is currently redirected to C</dev/null>.
-
-Stderr is unchanged.
-

 =head2 REMOTE CONTROL DETAILS
 
 Remote control happens over a Unix domain socket called
 =head2 REMOTE CONTROL DETAILS
 
 Remote control happens over a Unix domain socket called


@@ -435,6 +453,18 @@ number of megabytes
 
 number of gigabytes
 
 
 number of gigabytes
 

+=item C<nn>T or C<nn>TB
+
+number of terabytes
+
+=item C<nn>P or C<nn>PB
+
+number of petabytes
+
+=item C<nn>E or C<nn>EB
+
+number of exabytes
+

 =item C<nn>sects
 
 number of 512 byte sectors
 =item C<nn>sects
 
 number of 512 byte sectors


@@ -513,6 +543,55 @@ 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.
 
 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<alloc> 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<qemu-img(1)> utility.
+
+Size can be specified (where C<nn> means a number):
+
+=over 4
+
+=item C<nn> or C<nn>K or C<nn>KB
+
+number of kilobytes, eg: C<1440> = standard 3.5in floppy
+
+=item C<nn>M or C<nn>MB
+
+number of megabytes
+
+=item C<nn>G or C<nn>GB
+
+number of gigabytes
+
+=item C<nn>T or C<nn>TB
+
+number of terabytes
+
+=item C<nn>P or C<nn>PB
+
+number of petabytes
+
+=item C<nn>E or C<nn>EB
+
+number of exabytes
+
+=item C<nn>sects
+
+number of 512 byte sectors
+
+=back
+

 =head2 time
 
  time command args...
 =head2 time
 
  time command args...


@@ -571,6 +650,10 @@ 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.
 
 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
 =item PAGER
 
 The C<more> command uses C<$PAGER> as the pager.  If not


@@ -596,7 +679,12 @@ I<1> if there was an error.
 =head1 SEE ALSO
 
 L<guestfs(3)>,
 =head1 SEE ALSO
 
 L<guestfs(3)>,

-L<http://libguestfs.org/>.
+L<http://libguestfs.org/>,
+L<virt-cat(1)>,
+L<virt-edit(1)>,
+L<virt-ls(1)>,
+L<virt-rescue(1)>,
+L<virt-tar(1)>.

 
 =head1 AUTHORS
 
 
 =head1 AUTHORS