1 =head2 add-cdrom | cdrom
5 This function adds a virtual CD-ROM disk image to the guest.
7 This is equivalent to the qemu parameter C<-cdrom filename>.
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
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
24 This is equivalent to the qemu parameter C<-drive file=filename>.
30 Close the current Augeas handle and free up any resources
31 used by it. After calling this, you have to call
32 C<aug_init> again before you can use any other
37 aug-defnode name expr val
39 Defines a variable C<name> whose value is the result of
42 If C<expr> evaluates to an empty nodeset, a node is created,
43 equivalent to calling C<aug_set> C<expr>, C<value>.
44 C<name> will be the nodeset containing that single node.
46 On success this returns a pair containing the
47 number of nodes in the nodeset, and a boolean flag
48 if a node was created.
54 Defines an Augeas variable C<name> whose value is the result
55 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
58 On success this returns the number of nodes in C<expr>, or
59 C<0> if C<expr> evaluates to something which is not a nodeset.
65 Look up the value associated with C<path>. If C<path>
66 matches exactly one node, the C<value> is returned.
72 Create a new Augeas handle for editing configuration files.
73 If there was any previous Augeas handle associated with this
74 guestfs session, then it is closed.
76 You must call this before using any other C<aug_*>
79 C<root> is the filesystem root. C<root> must not be NULL,
82 The flags are the same as the flags defined in
83 E<lt>augeas.hE<gt>, the logical I<or> of the following
88 =item C<AUG_SAVE_BACKUP> = 1
90 Keep the original file with a C<.augsave> extension.
92 =item C<AUG_SAVE_NEWFILE> = 2
94 Save changes into a file with extension C<.augnew>, and
95 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
97 =item C<AUG_TYPE_CHECK> = 4
99 Typecheck lenses (can be expensive).
101 =item C<AUG_NO_STDINC> = 8
103 Do not use standard load path for modules.
105 =item C<AUG_SAVE_NOOP> = 16
107 Make save a no-op, just record what would have been changed.
109 =item C<AUG_NO_LOAD> = 32
111 Do not load the tree in C<aug_init>.
115 To close the handle, you can call C<aug_close>.
117 To find out more about Augeas, see L<http://augeas.net/>.
121 aug-insert path label true|false
123 Create a new sibling C<label> for C<path>, inserting it into
124 the tree before or after C<path> (depending on the boolean
127 C<path> must match exactly one existing node in the tree, and
128 C<label> must be a label, ie. not contain C</>, C<*> or end
129 with a bracketed index C<[N]>.
135 Load files into the tree.
137 See C<aug_load> in the Augeas documentation for the full gory
144 This is just a shortcut for listing C<aug_match>
145 C<path/*> and sorting the resulting nodes into alphabetical order.
151 Returns a list of paths which match the path expression C<path>.
152 The returned paths are sufficiently qualified so that they match
153 exactly one node in the current tree.
159 Move the node C<src> to C<dest>. C<src> must match exactly
160 one node. C<dest> is overwritten if it exists.
166 Remove C<path> and all of its children.
168 On success this returns the number of entries which were removed.
174 This writes all pending changes to disk.
176 The flags which were passed to C<aug_init> affect exactly
183 Set the value associated with C<path> to C<value>.
185 =head2 blockdev-flushbufs
187 blockdev-flushbufs device
189 This tells the kernel to flush internal buffers associated
192 This uses the L<blockdev(8)> command.
194 =head2 blockdev-getbsz
196 blockdev-getbsz device
198 This returns the block size of a device.
200 (Note this is different from both I<size in blocks> and
201 I<filesystem block size>).
203 This uses the L<blockdev(8)> command.
205 =head2 blockdev-getro
207 blockdev-getro device
209 Returns a boolean indicating if the block device is read-only
210 (true if read-only, false if not).
212 This uses the L<blockdev(8)> command.
214 =head2 blockdev-getsize64
216 blockdev-getsize64 device
218 This returns the size of the device in bytes.
220 See also C<blockdev_getsz>.
222 This uses the L<blockdev(8)> command.
224 =head2 blockdev-getss
226 blockdev-getss device
228 This returns the size of sectors on a block device.
229 Usually 512, but can be larger for modern devices.
231 (Note, this is not the size in sectors, use C<blockdev_getsz>
234 This uses the L<blockdev(8)> command.
236 =head2 blockdev-getsz
238 blockdev-getsz device
240 This returns the size of the device in units of 512-byte sectors
241 (even if the sectorsize isn't 512 bytes ... weird).
243 See also C<blockdev_getss> for the real sector size of
244 the device, and C<blockdev_getsize64> for the more
245 useful I<size in bytes>.
247 This uses the L<blockdev(8)> command.
249 =head2 blockdev-rereadpt
251 blockdev-rereadpt device
253 Reread the partition table on C<device>.
255 This uses the L<blockdev(8)> command.
257 =head2 blockdev-setbsz
259 blockdev-setbsz device blocksize
261 This sets the block size of a device.
263 (Note this is different from both I<size in blocks> and
264 I<filesystem block size>).
266 This uses the L<blockdev(8)> command.
268 =head2 blockdev-setro
270 blockdev-setro device
272 Sets the block device named C<device> to read-only.
274 This uses the L<blockdev(8)> command.
276 =head2 blockdev-setrw
278 blockdev-setrw device
280 Sets the block device named C<device> to read-write.
282 This uses the L<blockdev(8)> command.
288 Return the contents of the file named C<path>.
290 Note that this function cannot correctly handle binary files
291 (specifically, files containing C<\0> character which is treated
292 as end of string). For those you need to use the C<download>
293 function which has a more complex interface.
295 Because of the message protocol, there is a transfer limit
296 of somewhere between 2MB and 4MB. To transfer large files you should use
301 checksum csumtype path
303 This call computes the MD5, SHAx or CRC checksum of the
306 The type of checksum to compute is given by the C<csumtype>
307 parameter which must have one of the following values:
313 Compute the cyclic redundancy check (CRC) specified by POSIX
314 for the C<cksum> command.
318 Compute the MD5 hash (using the C<md5sum> program).
322 Compute the SHA1 hash (using the C<sha1sum> program).
326 Compute the SHA224 hash (using the C<sha224sum> program).
330 Compute the SHA256 hash (using the C<sha256sum> program).
334 Compute the SHA384 hash (using the C<sha384sum> program).
338 Compute the SHA512 hash (using the C<sha512sum> program).
342 The checksum is returned as a printable string.
348 Change the mode (permissions) of C<path> to C<mode>. Only
349 numeric modes are supported.
353 chown owner group path
355 Change the file owner to C<owner> and group to C<group>.
357 Only numeric uid and gid are supported. If you want to use
358 names, you will need to locate and parse the password file
359 yourself (Augeas support makes this relatively easy).
363 command 'arguments ...'
365 This call runs a command from the guest filesystem. The
366 filesystem must be mounted, and must contain a compatible
367 operating system (ie. something Linux, with the same
368 or compatible processor architecture).
370 The single parameter is an argv-style list of arguments.
371 The first element is the name of the program to run.
372 Subsequent elements are parameters. The list must be
373 non-empty (ie. must contain a program name).
375 The C<$PATH> environment variable will contain at least
376 C</usr/bin> and C</bin>. If you require a program from
377 another location, you should provide the full path in the
380 Shared libraries and data files required by the program
381 must be available on filesystems which are mounted in the
382 correct places. It is the caller's responsibility to ensure
383 all filesystems that are needed are mounted at the right
388 command-lines 'arguments ...'
390 This is the same as C<command>, but splits the
391 result into a list of lines.
395 config qemuparam qemuvalue
397 This can be used to add arbitrary qemu command line parameters
398 of the form C<-param value>. Actually it's not quite arbitrary - we
399 prevent you from setting some parameters which would interfere with
400 parameters that we use.
402 The first character of C<param> string must be a C<-> (dash).
404 C<value> can be NULL.
408 download remotefilename (filename|-)
410 Download file C<remotefilename> and save it as C<filename>
411 on the local machine.
413 C<filename> can also be a named pipe.
415 See also C<upload>, C<cat>.
417 Use C<-> instead of a filename to read/write from stdin/stdout.
423 This returns C<true> if and only if there is a file, directory
424 (or anything) with the given C<path> name.
426 See also C<is_file>, C<is_dir>, C<stat>.
432 This call uses the standard L<file(1)> command to determine
433 the type or contents of the file. This also works on devices,
434 for example to find out whether a partition contains a filesystem.
436 The exact command which runs is C<file -bsL path>. Note in
437 particular that the filename is not prepended to the output
444 Get the autosync flag.
450 Return the current search path.
452 This is always non-NULL. If it wasn't set already, then this will
453 return the default path.
459 Return the current qemu binary.
461 This is always non-NULL. If it wasn't set already, then this will
462 return the default qemu binary name.
468 This returns the current state as an opaque integer. This is
469 only useful for printing debug and internal error messages.
471 For more information on states, see L<guestfs(3)>.
477 This returns the verbose messages flag.
483 This returns true iff this handle is busy processing a command
484 (in the C<BUSY> state).
486 For more information on states, see L<guestfs(3)>.
492 This returns true iff this handle is being configured
493 (in the C<CONFIG> state).
495 For more information on states, see L<guestfs(3)>.
501 This returns C<true> if and only if there is a directory
502 with the given C<path> name. Note that it returns false for
503 other objects like files.
511 This returns C<true> if and only if there is a file
512 with the given C<path> name. Note that it returns false for
513 other objects like directories.
521 This returns true iff this handle is launching the subprocess
522 (in the C<LAUNCHING> state).
524 For more information on states, see L<guestfs(3)>.
530 This returns true iff this handle is ready to accept commands
531 (in the C<READY> state).
533 For more information on states, see L<guestfs(3)>.
535 =head2 kill-subprocess
539 This kills the qemu subprocess. You should never need to call this.
545 Internally libguestfs is implemented by running a virtual machine
548 You should call this after configuring the handle
549 (eg. adding drives) but before performing any actions.
555 List all the block devices.
557 The full block device names are returned, eg. C</dev/sda>
559 =head2 list-partitions
563 List all the partitions detected on all block devices.
565 The full partition device names are returned, eg. C</dev/sda1>
567 This does not return logical volumes. For that you will need to
574 List the files in C<directory> (relative to the root directory,
575 there is no cwd) in the format of 'ls -la'.
577 This command is mostly useful for interactive sessions. It
578 is I<not> intended that you try to parse the output string.
584 List the files in C<directory> (relative to the root directory,
585 there is no cwd). The '.' and '..' entries are not returned, but
586 hidden files are shown.
588 This command is mostly useful for interactive sessions. Programs
589 should probably use C<readdir> instead.
595 Returns file information for the given C<path>.
597 This is the same as C<stat> except that if C<path>
598 is a symbolic link, then the link is stat-ed, not the file it
601 This is the same as the C<lstat(2)> system call.
605 lvcreate logvol volgroup mbytes
607 This creates an LVM volume group called C<logvol>
608 on the volume group C<volgroup>, with C<size> megabytes.
610 =head2 lvm-remove-all
614 This command removes all LVM logical volumes, volume groups
615 and physical volumes.
617 B<This command is dangerous. Without careful use you
618 can easily destroy all your data>.
624 List all the logical volumes detected. This is the equivalent
625 of the L<lvs(8)> command.
627 This returns a list of the logical volume device names
628 (eg. C</dev/VolGroup00/LogVol00>).
630 See also C<lvs_full>.
636 List all the logical volumes detected. This is the equivalent
637 of the L<lvs(8)> command. The "full" version includes all fields.
643 Create a directory named C<path>.
649 Create a directory named C<path>, creating any parent directories
650 as necessary. This is like the C<mkdir -p> shell command.
656 This creates a filesystem on C<device> (usually a partition
657 of LVM logical volume). The filesystem type is C<fstype>, for
662 mount device mountpoint
664 Mount a guest disk at a position in the filesystem. Block devices
665 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
666 the guest. If those block devices contain partitions, they will have
667 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
670 The rules are the same as for L<mount(2)>: A filesystem must
671 first be mounted on C</> before others can be mounted. Other
672 filesystems can only be mounted on directories which already
675 The mounted filesystem is writable, if we have sufficient permissions
676 on the underlying device.
678 The filesystem options C<sync> and C<noatime> are set with this
679 call, in order to improve reliability.
683 mount-options options device mountpoint
685 This is the same as the C<mount> command, but it
686 allows you to set the mount options as for the
687 L<mount(8)> I<-o> flag.
691 mount-ro device mountpoint
693 This is the same as the C<mount> command, but it
694 mounts the filesystem with the read-only (I<-o ro>) flag.
698 mount-vfs options vfstype device mountpoint
700 This is the same as the C<mount> command, but it
701 allows you to set both the mount options and the vfstype
702 as for the L<mount(8)> I<-o> and I<-t> flags.
708 This returns the list of currently mounted filesystems. It returns
709 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
711 Some internal mounts are not shown.
717 This creates an LVM physical volume on the named C<device>,
718 where C<device> should usually be a partition name such
725 List all the physical volumes detected. This is the equivalent
726 of the L<pvs(8)> command.
728 This returns a list of just the device names that contain
729 PVs (eg. C</dev/sda2>).
731 See also C<pvs_full>.
737 List all the physical volumes detected. This is the equivalent
738 of the L<pvs(8)> command. The "full" version includes all fields.
744 Return the contents of the file named C<path>.
746 The file contents are returned as a list of lines. Trailing
747 C<LF> and C<CRLF> character sequences are I<not> returned.
749 Note that this function cannot correctly handle binary files
750 (specifically, files containing C<\0> character which is treated
751 as end of line). For those you need to use the C<read_file>
752 function which has a more complex interface.
758 Remove the single file C<path>.
764 Remove the file or directory C<path>, recursively removing the
765 contents if its a directory. This is like the C<rm -rf> shell
772 Remove the single directory C<path>.
774 =head2 set-autosync | autosync
776 set-autosync true|false
778 If C<autosync> is true, this enables autosync. Libguestfs will make a
779 best effort attempt to run C<sync> when the handle is closed
780 (also if the program exits without closing handles).
782 =head2 set-path | path
786 Set the path that libguestfs searches for kernel and initrd.img.
788 The default is C<$libdir/guestfs> unless overridden by setting
789 C<LIBGUESTFS_PATH> environment variable.
791 The string C<path> is stashed in the libguestfs handle, so the caller
792 must make sure it remains valid for the lifetime of the handle.
794 Setting C<path> to C<NULL> restores the default path.
796 =head2 set-qemu | qemu
800 Set the qemu binary that we will use.
802 The default is chosen when the library was compiled by the
805 You can also override this by setting the C<LIBGUESTFS_QEMU>
806 environment variable.
808 The string C<qemu> is stashed in the libguestfs handle, so the caller
809 must make sure it remains valid for the lifetime of the handle.
811 Setting C<qemu> to C<NULL> restores the default qemu binary.
813 =head2 set-verbose | verbose
815 set-verbose true|false
817 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
819 Verbose messages are disabled unless the environment variable
820 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
824 sfdisk device cyls heads sectors 'lines ...'
826 This is a direct interface to the L<sfdisk(8)> program for creating
827 partitions on block devices.
829 C<device> should be a block device, for example C</dev/sda>.
831 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
832 and sectors on the device, which are passed directly to sfdisk as
833 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
834 of these, then the corresponding parameter is omitted. Usually for
835 'large' disks, you can just pass C<0> for these, but for small
836 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
837 out the right geometry and you will need to tell it.
839 C<lines> is a list of lines that we feed to C<sfdisk>. For more
840 information refer to the L<sfdisk(8)> manpage.
842 To create a single partition occupying the whole disk, you would
843 pass C<lines> as a single element list, when the single element being
844 the string C<,> (comma).
846 B<This command is dangerous. Without careful use you
847 can easily destroy all your data>.
853 Returns file information for the given C<path>.
855 This is the same as the C<stat(2)> system call.
861 Returns file system statistics for any mounted file system.
862 C<path> should be a file or directory in the mounted file system
863 (typically it is the mount point itself, but it doesn't need to be).
865 This is the same as the C<statvfs(2)> system call.
871 This syncs the disk, so that any writes are flushed through to the
872 underlying disk image.
874 You should always call this if you have modified a disk image, before
879 tar-in (tarfile|-) directory
881 This command uploads and unpacks local file C<tarfile> (an
882 I<uncompressed> tar file) into C<directory>.
884 To upload a compressed tarball, use C<tgz_in>.
886 Use C<-> instead of a filename to read/write from stdin/stdout.
890 tar-out directory (tarfile|-)
892 This command packs the contents of C<directory> and downloads
893 it to local file C<tarfile>.
895 To download a compressed tarball, use C<tgz_out>.
897 Use C<-> instead of a filename to read/write from stdin/stdout.
901 tgz-in (tarball|-) directory
903 This command uploads and unpacks local file C<tarball> (a
904 I<gzip compressed> tar file) into C<directory>.
906 To upload an uncompressed tarball, use C<tar_in>.
908 Use C<-> instead of a filename to read/write from stdin/stdout.
912 tgz-out directory (tarball|-)
914 This command packs the contents of C<directory> and downloads
915 it to local file C<tarball>.
917 To download an uncompressed tarball, use C<tar_out>.
919 Use C<-> instead of a filename to read/write from stdin/stdout.
925 Touch acts like the L<touch(1)> command. It can be used to
926 update the timestamps on a file, or, if the file does not exist,
927 to create a new zero-length file.
933 This returns the contents of the ext2 or ext3 filesystem superblock
936 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
937 manpage for more details. The list of fields returned isn't
938 clearly defined, and depends on both the version of C<tune2fs>
939 that libguestfs was built against, and the filesystem itself.
941 =head2 umount | unmount
945 This unmounts the given filesystem. The filesystem may be
946 specified either by its mountpoint (path) or the device which
947 contains the filesystem.
949 =head2 umount-all | unmount-all
953 This unmounts all mounted filesystems.
955 Some internal mounts are not unmounted by this call.
959 upload (filename|-) remotefilename
961 Upload local file C<filename> to C<remotefilename> on the
964 C<filename> can also be a named pipe.
966 See also C<download>.
968 Use C<-> instead of a filename to read/write from stdin/stdout.
972 vgcreate volgroup 'physvols ...'
974 This creates an LVM volume group called C<volgroup>
975 from the non-empty list of physical volumes C<physvols>.
981 List all the volumes groups detected. This is the equivalent
982 of the L<vgs(8)> command.
984 This returns a list of just the volume group names that were
985 detected (eg. C<VolGroup00>).
987 See also C<vgs_full>.
993 List all the volumes groups detected. This is the equivalent
994 of the L<vgs(8)> command. The "full" version includes all fields.
998 write-file path content size
1000 This call creates a file called C<path>. The contents of the
1001 file is the string C<content> (which can contain any 8 bit data),
1002 with length C<size>.
1004 As a special case, if C<size> is C<0>
1005 then the length is calculated using C<strlen> (so in this case
1006 the content cannot contain embedded ASCII NULs).
1008 Because of the message protocol, there is a transfer limit
1009 of somewhere between 2MB and 4MB. To transfer large files you should use