Missing files from previous release.

[libguestfs.git] / guestfish-actions.pod

diff --git a/guestfish-actions.pod b/guestfish-actions.pod
index 20c34a5..ee3f641 100644 (file)
--- a/guestfish-actions.pod
+++ b/guestfish-actions.pod
@@ -6,6 +6,11 @@ This function adds a virtual CD-ROM disk image to the guest.
 
 This is equivalent to the qemu parameter C<-cdrom filename>.
 
 
 This is equivalent to the qemu parameter C<-cdrom filename>.
 

+Note that this call checks for the existence of C<filename>.  This
+stops you from specifying other types of drive which are supported
+by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
+the general C<config> call instead.
+

 =head2 add-drive | add
 
  add-drive filename
 =head2 add-drive | add
 
  add-drive filename


@@ -23,6 +28,32 @@ image).
 
 This is equivalent to the qemu parameter C<-drive file=filename>.
 
 
 This is equivalent to the qemu parameter C<-drive file=filename>.
 

+Note that this call checks for the existence of C<filename>.  This
+stops you from specifying other types of drive which are supported
+by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
+the general C<config> call instead.
+
+=head2 add-drive-ro | add-ro
+
+ add-drive-ro filename
+
+This adds a drive in snapshot mode, making it effectively
+read-only.
+
+Note that writes to the device are allowed, and will be seen for
+the duration of the guestfs handle, but they are written
+to a temporary file which is discarded as soon as the guestfs
+handle is closed.  We don't currently have any method to enable
+changes to be committed, although qemu can support this.
+
+This is equivalent to the qemu parameter
+C<-drive file=filename,snapshot=on>.
+
+Note that this call checks for the existence of C<filename>.  This
+stops you from specifying other types of drive which are supported
+by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
+the general C<config> call instead.
+

 =head2 aug-close
 
  aug-close
 =head2 aug-close
 
  aug-close


@@ -484,6 +515,17 @@ Setting C<whattodrop> to 3 should drop everything.
 This automatically calls L<sync(2)> before the operation,
 so that the maximum guest memory is freed.
 
 This automatically calls L<sync(2)> before the operation,
 so that the maximum guest memory is freed.
 

+=head2 e2fsck-f
+
+ e2fsck-f device
+
+This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
+filesystem checker on C<device>, noninteractively (C<-p>),
+even if the filesystem appears to be clean (C<-f>).
+
+This command is only needed because of C<resize2fs>
+(q.v.).  Normally you should use C<fsck>.
+

 =head2 equal
 
  equal file1 file2
 =head2 equal
 
  equal file1 file2


@@ -514,6 +556,35 @@ The exact command which runs is C<file -bsL path>.  Note in
 particular that the filename is not prepended to the output
 (the C<-b> option).
 
 particular that the filename is not prepended to the output
 (the C<-b> option).
 

+=head2 find
+
+ find directory
+
+This command lists out all files and directories, recursively,
+starting at C<directory>.  It is essentially equivalent to
+running the shell command C<find directory -print> but some
+post-processing happens on the output, described below.
+
+This returns a list of strings I<without any prefix>.  Thus
+if the directory structure was:
+
+ /tmp/a
+ /tmp/b
+ /tmp/c/d
+
+then the returned list from C<find> C</tmp> would be
+4 elements:
+
+ a
+ b
+ c
+ c/d
+
+If C<directory> is not a directory, then this command returns
+an error.
+
+The returned list is sorted.
+

 =head2 fsck
 
  fsck fstype device
 =head2 fsck
 
  fsck fstype device


@@ -777,6 +848,14 @@ the path to the LV, such as C</dev/VG/LV>.
 You can also remove all LVs in a volume group by specifying
 the VG name, C</dev/VG>.
 
 You can also remove all LVs in a volume group by specifying
 the VG name, C</dev/VG>.
 

+=head2 lvresize
+
+ lvresize device mbytes
+
+This resizes (expands or shrinks) an existing LVM logical
+volume to C<mbytes>.  When reducing, data in the reduced part
+is lost.
+

 =head2 lvs
 
  lvs
 =head2 lvs
 
  lvs


@@ -877,6 +956,22 @@ Some internal mounts are not shown.
 This moves a file from C<src> to C<dest> where C<dest> is
 either a destination filename or destination directory.
 
 This moves a file from C<src> to C<dest> where C<dest> is
 either a destination filename or destination directory.
 

+=head2 ntfs-3g-probe
+
+ ntfs-3g-probe true|false device
+
+This command runs the L<ntfs-3g.probe(8)> command which probes
+an NTFS C<device> for mountability.  (Not all NTFS volumes can
+be mounted read-write, and some cannot be mounted at all).
+
+C<rw> is a boolean flag.  Set it to true if you want to test
+if the volume can be mounted read-write.  Set it to false if
+you want to test if the volume can be mounted read-only.
+
+The return value is an integer which C<0> if the operation
+would succeed, or some non-zero value documented in the
+L<ntfs-3g.probe(8)> manual page.
+

 =head2 ping-daemon
 
  ping-daemon
 =head2 ping-daemon
 
  ping-daemon


@@ -905,6 +1000,13 @@ The implementation uses the C<pvremove> command which refuses to
 wipe physical volumes that contain any volume groups, so you have
 to remove those first.
 
 wipe physical volumes that contain any volume groups, so you have
 to remove those first.
 

+=head2 pvresize
+
+ pvresize device
+
+This resizes (expands or shrinks) an existing LVM physical
+volume to match the new size of the underlying device.
+

 =head2 pvs
 
  pvs
 =head2 pvs
 
  pvs


@@ -938,6 +1040,19 @@ Note that this function cannot correctly handle binary files
 as end of line).  For those you need to use the C<read-file>
 function which has a more complex interface.
 
 as end of line).  For those you need to use the C<read-file>
 function which has a more complex interface.
 

+=head2 resize2fs
+
+ resize2fs device
+
+This resizes an ext2 or ext3 filesystem to match the size of
+the underlying device.
+
+I<Note:> It is sometimes required that you run C<e2fsck-f>
+on the C<device> before calling this command.  For unknown reasons
+C<resize2fs> sometimes gives an error about this and sometimes not.
+In any case, it is always safe to call C<e2fsck-f> before
+calling this function.
+

 =head2 rm
 
  rm path
 =head2 rm
 
  rm path


@@ -968,9 +1083,6 @@ guest kernel command line.
 The default is C<NULL> unless overridden by setting
 C<LIBGUESTFS_APPEND> environment variable.
 
 The default is C<NULL> unless overridden by setting
 C<LIBGUESTFS_APPEND> environment variable.
 

-The string C<append> is stashed in the libguestfs handle, so the caller
-must make sure it remains valid for the lifetime of the handle.
-

 Setting C<append> to C<NULL> means I<no> additional options
 are passed (libguestfs always adds a few of its own).
 
 Setting C<append> to C<NULL> means I<no> additional options
 are passed (libguestfs always adds a few of its own).
 


@@ -1018,9 +1130,6 @@ Set the path that libguestfs searches for kernel and initrd.img.
 The default is C<$libdir/guestfs> unless overridden by setting
 C<LIBGUESTFS_PATH> environment variable.
 
 The default is C<$libdir/guestfs> unless overridden by setting
 C<LIBGUESTFS_PATH> environment variable.
 

-The string C<path> is stashed in the libguestfs handle, so the caller
-must make sure it remains valid for the lifetime of the handle.
-

 Setting C<path> to C<NULL> restores the default path.
 
 =head2 set-qemu | qemu
 Setting C<path> to C<NULL> restores the default path.
 
 =head2 set-qemu | qemu


@@ -1035,9 +1144,6 @@ configure script.
 You can also override this by setting the C<LIBGUESTFS_QEMU>
 environment variable.
 
 You can also override this by setting the C<LIBGUESTFS_QEMU>
 environment variable.
 

-The string C<qemu> is stashed in the libguestfs handle, so the caller
-must make sure it remains valid for the lifetime of the handle.
-

 Setting C<qemu> to C<NULL> restores the default qemu binary.
 
 =head2 set-verbose | verbose
 Setting C<qemu> to C<NULL> restores the default qemu binary.
 
 =head2 set-verbose | verbose


@@ -1073,9 +1179,59 @@ To create a single partition occupying the whole disk, you would
 pass C<lines> as a single element list, when the single element being
 the string C<,> (comma).
 
 pass C<lines> as a single element list, when the single element being
 the string C<,> (comma).
 

+See also: C<sfdisk-l>, C<sfdisk-N>
+
+B<This command is dangerous.  Without careful use you
+can easily destroy all your data>.
+
+=head2 sfdisk-N
+
+ sfdisk-N device n cyls heads sectors line
+
+This runs L<sfdisk(8)> option to modify just the single
+partition C<n> (note: C<n> counts from 1).
+
+For other parameters, see C<sfdisk>.  You should usually
+pass C<0> for the cyls/heads/sectors parameters.
+

 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 

+=head2 sfdisk-disk-geometry
+
+ sfdisk-disk-geometry device
+
+This displays the disk geometry of C<device> read from the
+partition table.  Especially in the case where the underlying
+block device has been resized, this can be different from the
+kernel's idea of the geometry (see C<sfdisk-kernel-geometry>).
+
+The result is in human-readable format, and not designed to
+be parsed.
+
+=head2 sfdisk-kernel-geometry
+
+ sfdisk-kernel-geometry device
+
+This displays the kernel's idea of the geometry of C<device>.
+
+The result is in human-readable format, and not designed to
+be parsed.
+
+=head2 sfdisk-l
+
+ sfdisk-l device
+
+This displays the partition table on C<device>, in the
+human-readable output of the L<sfdisk(8)> command.  It is
+not intended to be parsed.
+
+=head2 sleep
+
+ sleep secs
+
+Sleep for C<secs> seconds.
+

 =head2 stat
 
  stat path
 =head2 stat
 
  stat path


@@ -1226,6 +1382,33 @@ See also C<download>.
 
 Use C<-> instead of a filename to read/write from stdin/stdout.
 
 
 Use C<-> instead of a filename to read/write from stdin/stdout.
 

+=head2 vg-activate
+
+ vg-activate true|false 'volgroups ...'
+
+This command activates or (if C<activate> is false) deactivates
+all logical volumes in the listed volume groups C<volgroups>.
+If activated, then they are made known to the
+kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
+then those devices disappear.
+
+This command is the same as running C<vgchange -a y|n volgroups...>
+
+Note that if C<volgroups> is an empty list then B<all> volume groups
+are activated or deactivated.
+
+=head2 vg-activate-all
+
+ vg-activate-all true|false
+
+This command activates or (if C<activate> is false) deactivates
+all logical volumes in all volume groups.
+If activated, then they are made known to the
+kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
+then those devices disappear.
+
+This command is the same as running C<vgchange -a y|n>
+

 =head2 vgcreate
 
  vgcreate volgroup 'physvols ...'
 =head2 vgcreate
 
  vgcreate volgroup 'physvols ...'


@@ -1292,3 +1475,18 @@ How many blocks are zeroed isn't specified (but it's I<not> enough
 to securely wipe the device).  It should be sufficient to remove
 any partition tables, filesystem superblocks and so on.
 
 to securely wipe the device).  It should be sufficient to remove
 any partition tables, filesystem superblocks and so on.
 

+=head2 zerofree
+
+ zerofree device
+
+This runs the I<zerofree> program on C<device>.  This program
+claims to zero unused inodes and disk blocks on an ext2/3
+filesystem, thus making it possible to compress the filesystem
+more effectively.
+
+You should B<not> run this program if the filesystem is
+mounted.
+
+It is possible that using this program can damage the filesystem
+or data on the filesystem.
+