guestfish-actions.pod

   1 =head2 add-cdrom | cdrom
   2
   3  add-cdrom filename
   4
   5 This function adds a virtual CD-ROM disk image to the guest.
   6
   7 This is equivalent to the qemu parameter C<-cdrom filename>.
   8
   9 =head2 add-drive | add
  10
  11  add-drive filename
  12
  13 This function adds a virtual machine disk image C<filename> to the
  14 guest.  The first time you call this function, the disk appears as IDE
  15 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
  16 so on.
  17
  18 You don't necessarily need to be root when using libguestfs.  However
  19 you obviously do need sufficient permissions to access the filename
  20 for whatever operations you want to perform (ie. read access if you
  21 just want to read the image or write access if you want to modify the
  22 image).
  23
  24 This is equivalent to the qemu parameter C<-drive file=filename>.
  25
  26 =head2 cat
  27
  28  cat path
  29
  30 Return the contents of the file named C<path>.
  31
  32 Note that this function cannot correctly handle binary files
  33 (specifically, files containing C<\0> character which is treated
  34 as end of string).  For those you need to use the C<read_file>
  35 function which has a more complex interface.
  36
  37 =head2 config
  38
  39  config qemuparam qemuvalue
  40
  41 This can be used to add arbitrary qemu command line parameters
  42 of the form C<-param value>.  Actually it's not quite arbitrary - we
  43 prevent you from setting some parameters which would interfere with
  44 parameters that we use.
  45
  46 The first character of C<param> string must be a C<-> (dash).
  47
  48 C<value> can be NULL.
  49
  50 =head2 get-autosync
  51
  52  get-autosync
  53
  54 Get the autosync flag.
  55
  56 =head2 get-path
  57
  58  get-path
  59
  60 Return the current search path.
  61
  62 This is always non-NULL.  If it wasn't set already, then this will
  63 return the default path.
  64
  65 =head2 get-verbose
  66
  67  get-verbose
  68
  69 This returns the verbose messages flag.
  70
  71 =head2 kill-subprocess
  72
  73  kill-subprocess
  74
  75 This kills the qemu subprocess.  You should never need to call this.
  76
  77 =head2 launch | run
  78
  79  launch
  80
  81 Internally libguestfs is implemented by running a virtual machine
  82 using L<qemu(1)>.
  83
  84 You should call this after configuring the handle
  85 (eg. adding drives) but before performing any actions.
  86
  87 =head2 list-devices
  88
  89  list-devices
  90
  91 List all the block devices.
  92
  93 The full block device names are returned, eg. C</dev/sda>
  94
  95 =head2 list-partitions
  96
  97  list-partitions
  98
  99 List all the partitions detected on all block devices.
 100
 101 The full partition device names are returned, eg. C</dev/sda1>
 102
 103 This does not return logical volumes.  For that you will need to
 104 call C<lvs>.
 105
 106 =head2 ll
 107
 108  ll directory
 109
 110 List the files in C<directory> (relative to the root directory,
 111 there is no cwd) in the format of 'ls -la'.
 112
 113 This command is mostly useful for interactive sessions.  It
 114 is I<not> intended that you try to parse the output string.
 115
 116 =head2 ls
 117
 118  ls directory
 119
 120 List the files in C<directory> (relative to the root directory,
 121 there is no cwd).  The '.' and '..' entries are not returned, but
 122 hidden files are shown.
 123
 124 This command is mostly useful for interactive sessions.  Programs
 125 should probably use C<readdir> instead.
 126
 127 =head2 lvs
 128
 129  lvs
 130
 131 List all the logical volumes detected.  This is the equivalent
 132 of the L<lvs(8)> command.
 133
 134 This returns a list of the logical volume device names
 135 (eg. C</dev/VolGroup00/LogVol00>).
 136
 137 See also C<lvs_full>.
 138
 139 =head2 lvs-full
 140
 141  lvs-full
 142
 143 List all the logical volumes detected.  This is the equivalent
 144 of the L<lvs(8)> command.  The "full" version includes all fields.
 145
 146 =head2 mount
 147
 148  mount device mountpoint
 149
 150 Mount a guest disk at a position in the filesystem.  Block devices
 151 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
 152 the guest.  If those block devices contain partitions, they will have
 153 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
 154 names can be used.
 155
 156 The rules are the same as for L<mount(2)>:  A filesystem must
 157 first be mounted on C</> before others can be mounted.  Other
 158 filesystems can only be mounted on directories which already
 159 exist.
 160
 161 The mounted filesystem is writable, if we have sufficient permissions
 162 on the underlying device.
 163
 164 The filesystem options C<sync> and C<noatime> are set with this
 165 call, in order to improve reliability.
 166
 167 =head2 pvs
 168
 169  pvs
 170
 171 List all the physical volumes detected.  This is the equivalent
 172 of the L<pvs(8)> command.
 173
 174 This returns a list of just the device names that contain
 175 PVs (eg. C</dev/sda2>).
 176
 177 See also C<pvs_full>.
 178
 179 =head2 pvs-full
 180
 181  pvs-full
 182
 183 List all the physical volumes detected.  This is the equivalent
 184 of the L<pvs(8)> command.  The "full" version includes all fields.
 185
 186 =head2 set-autosync | autosync
 187
 188  set-autosync true|false
 189
 190 If C<autosync> is true, this enables autosync.  Libguestfs will make a
 191 best effort attempt to run C<sync> when the handle is closed
 192 (also if the program exits without closing handles).
 193
 194 =head2 set-path | path
 195
 196  set-path path
 197
 198 Set the path that libguestfs searches for kernel and initrd.img.
 199
 200 The default is C<$libdir/guestfs> unless overridden by setting
 201 C<LIBGUESTFS_PATH> environment variable.
 202
 203 The string C<path> is stashed in the libguestfs handle, so the caller
 204 must make sure it remains valid for the lifetime of the handle.
 205
 206 Setting C<path> to C<NULL> restores the default path.
 207
 208 =head2 set-verbose | verbose
 209
 210  set-verbose true|false
 211
 212 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
 213
 214 Verbose messages are disabled unless the environment variable
 215 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
 216
 217 =head2 sync
 218
 219  sync
 220
 221 This syncs the disk, so that any writes are flushed through to the
 222 underlying disk image.
 223
 224 You should always call this if you have modified a disk image, before
 225 closing the handle.
 226
 227 =head2 touch
 228
 229  touch path
 230
 231 Touch acts like the L<touch(1)> command.  It can be used to
 232 update the timestamps on a file, or, if the file does not exist,
 233 to create a new zero-length file.
 234
 235 =head2 vgs
 236
 237  vgs
 238
 239 List all the volumes groups detected.  This is the equivalent
 240 of the L<vgs(8)> command.
 241
 242 This returns a list of just the volume group names that were
 243 detected (eg. C<VolGroup00>).
 244
 245 See also C<vgs_full>.
 246
 247 =head2 vgs-full
 248
 249  vgs-full
 250
 251 List all the volumes groups detected.  This is the equivalent
 252 of the L<vgs(8)> command.  The "full" version includes all fields.
 253