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>.
9 Note that this call checks for the existence of C<filename>. This
10 stops you from specifying other types of drive which are supported
11 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
12 the general C<config> call instead.
14 =head2 add-drive | add
18 This function adds a virtual machine disk image C<filename> to the
19 guest. The first time you call this function, the disk appears as IDE
20 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
23 You don't necessarily need to be root when using libguestfs. However
24 you obviously do need sufficient permissions to access the filename
25 for whatever operations you want to perform (ie. read access if you
26 just want to read the image or write access if you want to modify the
29 This is equivalent to the qemu parameter
30 C<-drive file=filename,cache=off,if=virtio>.
32 Note that this call checks for the existence of C<filename>. This
33 stops you from specifying other types of drive which are supported
34 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
35 the general C<config> call instead.
37 =head2 add-drive-ro | add-ro
41 This adds a drive in snapshot mode, making it effectively
44 Note that writes to the device are allowed, and will be seen for
45 the duration of the guestfs handle, but they are written
46 to a temporary file which is discarded as soon as the guestfs
47 handle is closed. We don't currently have any method to enable
48 changes to be committed, although qemu can support this.
50 This is equivalent to the qemu parameter
51 C<-drive file=filename,snapshot=on,if=virtio>.
53 Note that this call checks for the existence of C<filename>. This
54 stops you from specifying other types of drive which are supported
55 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
56 the general C<config> call instead.
62 Close the current Augeas handle and free up any resources
63 used by it. After calling this, you have to call
64 C<aug-init> again before you can use any other
69 aug-defnode name expr val
71 Defines a variable C<name> whose value is the result of
74 If C<expr> evaluates to an empty nodeset, a node is created,
75 equivalent to calling C<aug-set> C<expr>, C<value>.
76 C<name> will be the nodeset containing that single node.
78 On success this returns a pair containing the
79 number of nodes in the nodeset, and a boolean flag
80 if a node was created.
86 Defines an Augeas variable C<name> whose value is the result
87 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
90 On success this returns the number of nodes in C<expr>, or
91 C<0> if C<expr> evaluates to something which is not a nodeset.
97 Look up the value associated with C<path>. If C<path>
98 matches exactly one node, the C<value> is returned.
104 Create a new Augeas handle for editing configuration files.
105 If there was any previous Augeas handle associated with this
106 guestfs session, then it is closed.
108 You must call this before using any other C<aug-*>
111 C<root> is the filesystem root. C<root> must not be NULL,
114 The flags are the same as the flags defined in
115 E<lt>augeas.hE<gt>, the logical I<or> of the following
120 =item C<AUG_SAVE_BACKUP> = 1
122 Keep the original file with a C<.augsave> extension.
124 =item C<AUG_SAVE_NEWFILE> = 2
126 Save changes into a file with extension C<.augnew>, and
127 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
129 =item C<AUG_TYPE_CHECK> = 4
131 Typecheck lenses (can be expensive).
133 =item C<AUG_NO_STDINC> = 8
135 Do not use standard load path for modules.
137 =item C<AUG_SAVE_NOOP> = 16
139 Make save a no-op, just record what would have been changed.
141 =item C<AUG_NO_LOAD> = 32
143 Do not load the tree in C<aug-init>.
147 To close the handle, you can call C<aug-close>.
149 To find out more about Augeas, see L<http://augeas.net/>.
153 aug-insert path label true|false
155 Create a new sibling C<label> for C<path>, inserting it into
156 the tree before or after C<path> (depending on the boolean
159 C<path> must match exactly one existing node in the tree, and
160 C<label> must be a label, ie. not contain C</>, C<*> or end
161 with a bracketed index C<[N]>.
167 Load files into the tree.
169 See C<aug_load> in the Augeas documentation for the full gory
176 This is just a shortcut for listing C<aug-match>
177 C<path/*> and sorting the resulting nodes into alphabetical order.
183 Returns a list of paths which match the path expression C<path>.
184 The returned paths are sufficiently qualified so that they match
185 exactly one node in the current tree.
191 Move the node C<src> to C<dest>. C<src> must match exactly
192 one node. C<dest> is overwritten if it exists.
198 Remove C<path> and all of its children.
200 On success this returns the number of entries which were removed.
206 This writes all pending changes to disk.
208 The flags which were passed to C<aug-init> affect exactly
215 Set the value associated with C<path> to C<value>.
217 =head2 blockdev-flushbufs
219 blockdev-flushbufs device
221 This tells the kernel to flush internal buffers associated
224 This uses the L<blockdev(8)> command.
226 =head2 blockdev-getbsz
228 blockdev-getbsz device
230 This returns the block size of a device.
232 (Note this is different from both I<size in blocks> and
233 I<filesystem block size>).
235 This uses the L<blockdev(8)> command.
237 =head2 blockdev-getro
239 blockdev-getro device
241 Returns a boolean indicating if the block device is read-only
242 (true if read-only, false if not).
244 This uses the L<blockdev(8)> command.
246 =head2 blockdev-getsize64
248 blockdev-getsize64 device
250 This returns the size of the device in bytes.
252 See also C<blockdev-getsz>.
254 This uses the L<blockdev(8)> command.
256 =head2 blockdev-getss
258 blockdev-getss device
260 This returns the size of sectors on a block device.
261 Usually 512, but can be larger for modern devices.
263 (Note, this is not the size in sectors, use C<blockdev-getsz>
266 This uses the L<blockdev(8)> command.
268 =head2 blockdev-getsz
270 blockdev-getsz device
272 This returns the size of the device in units of 512-byte sectors
273 (even if the sectorsize isn't 512 bytes ... weird).
275 See also C<blockdev-getss> for the real sector size of
276 the device, and C<blockdev-getsize64> for the more
277 useful I<size in bytes>.
279 This uses the L<blockdev(8)> command.
281 =head2 blockdev-rereadpt
283 blockdev-rereadpt device
285 Reread the partition table on C<device>.
287 This uses the L<blockdev(8)> command.
289 =head2 blockdev-setbsz
291 blockdev-setbsz device blocksize
293 This sets the block size of a device.
295 (Note this is different from both I<size in blocks> and
296 I<filesystem block size>).
298 This uses the L<blockdev(8)> command.
300 =head2 blockdev-setro
302 blockdev-setro device
304 Sets the block device named C<device> to read-only.
306 This uses the L<blockdev(8)> command.
308 =head2 blockdev-setrw
310 blockdev-setrw device
312 Sets the block device named C<device> to read-write.
314 This uses the L<blockdev(8)> command.
320 Return the contents of the file named C<path>.
322 Note that this function cannot correctly handle binary files
323 (specifically, files containing C<\0> character which is treated
324 as end of string). For those you need to use the C<download>
325 function which has a more complex interface.
327 Because of the message protocol, there is a transfer limit
328 of somewhere between 2MB and 4MB. To transfer large files you should use
333 checksum csumtype path
335 This call computes the MD5, SHAx or CRC checksum of the
338 The type of checksum to compute is given by the C<csumtype>
339 parameter which must have one of the following values:
345 Compute the cyclic redundancy check (CRC) specified by POSIX
346 for the C<cksum> command.
350 Compute the MD5 hash (using the C<md5sum> program).
354 Compute the SHA1 hash (using the C<sha1sum> program).
358 Compute the SHA224 hash (using the C<sha224sum> program).
362 Compute the SHA256 hash (using the C<sha256sum> program).
366 Compute the SHA384 hash (using the C<sha384sum> program).
370 Compute the SHA512 hash (using the C<sha512sum> program).
374 The checksum is returned as a printable string.
380 Change the mode (permissions) of C<path> to C<mode>. Only
381 numeric modes are supported.
385 chown owner group path
387 Change the file owner to C<owner> and group to C<group>.
389 Only numeric uid and gid are supported. If you want to use
390 names, you will need to locate and parse the password file
391 yourself (Augeas support makes this relatively easy).
395 command 'arguments ...'
397 This call runs a command from the guest filesystem. The
398 filesystem must be mounted, and must contain a compatible
399 operating system (ie. something Linux, with the same
400 or compatible processor architecture).
402 The single parameter is an argv-style list of arguments.
403 The first element is the name of the program to run.
404 Subsequent elements are parameters. The list must be
405 non-empty (ie. must contain a program name). Note that
406 the command runs directly, and is I<not> invoked via
407 the shell (see C<sh>).
409 The return value is anything printed to I<stdout> by
412 If the command returns a non-zero exit status, then
413 this function returns an error message. The error message
414 string is the content of I<stderr> from the command.
416 The C<$PATH> environment variable will contain at least
417 C</usr/bin> and C</bin>. If you require a program from
418 another location, you should provide the full path in the
421 Shared libraries and data files required by the program
422 must be available on filesystems which are mounted in the
423 correct places. It is the caller's responsibility to ensure
424 all filesystems that are needed are mounted at the right
427 Because of the message protocol, there is a transfer limit
428 of somewhere between 2MB and 4MB. To transfer large files you should use
433 command-lines 'arguments ...'
435 This is the same as C<command>, but splits the
436 result into a list of lines.
438 See also: C<sh-lines>
440 Because of the message protocol, there is a transfer limit
441 of somewhere between 2MB and 4MB. To transfer large files you should use
446 config qemuparam qemuvalue
448 This can be used to add arbitrary qemu command line parameters
449 of the form C<-param value>. Actually it's not quite arbitrary - we
450 prevent you from setting some parameters which would interfere with
451 parameters that we use.
453 The first character of C<param> string must be a C<-> (dash).
455 C<value> can be NULL.
461 This copies a file from C<src> to C<dest> where C<dest> is
462 either a destination filename or destination directory.
468 This copies a file or directory from C<src> to C<dest>
469 recursively using the C<cp -a> command.
473 debug subcmd 'extraargs ...'
475 The C<debug> command exposes some internals of
476 C<guestfsd> (the guestfs daemon) that runs inside the
479 There is no comprehensive help for this command. You have
480 to look at the file C<daemon/debug.c> in the libguestfs source
481 to find out what you can do.
487 This command runs the C<df> command to report disk space used.
489 This command is mostly useful for interactive sessions. It
490 is I<not> intended that you try to parse the output string.
491 Use C<statvfs> from programs.
497 This command runs the C<df -h> command to report disk space used
498 in human-readable format.
500 This command is mostly useful for interactive sessions. It
501 is I<not> intended that you try to parse the output string.
502 Use C<statvfs> from programs.
508 This returns the kernel messages (C<dmesg> output) from
509 the guest kernel. This is sometimes useful for extended
510 debugging of problems.
512 Another way to get the same information is to enable
513 verbose messages with C<set-verbose> or by setting
514 the environment variable C<LIBGUESTFS_DEBUG=1> before
519 download remotefilename (filename|-)
521 Download file C<remotefilename> and save it as C<filename>
522 on the local machine.
524 C<filename> can also be a named pipe.
526 See also C<upload>, C<cat>.
528 Use C<-> instead of a filename to read/write from stdin/stdout.
532 drop-caches whattodrop
534 This instructs the guest kernel to drop its page cache,
535 and/or dentries and inode caches. The parameter C<whattodrop>
536 tells the kernel what precisely to drop, see
537 L<http://linux-mm.org/Drop_Caches>
539 Setting C<whattodrop> to 3 should drop everything.
541 This automatically calls L<sync(2)> before the operation,
542 so that the maximum guest memory is freed.
548 This command runs the C<du -s> command to estimate file space
551 C<path> can be a file or a directory. If C<path> is a directory
552 then the estimate includes the contents of the directory and all
553 subdirectories (recursively).
555 The result is the estimated size in I<kilobytes>
556 (ie. units of 1024 bytes).
562 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
563 filesystem checker on C<device>, noninteractively (C<-p>),
564 even if the filesystem appears to be clean (C<-f>).
566 This command is only needed because of C<resize2fs>
567 (q.v.). Normally you should use C<fsck>.
573 This compares the two files C<file1> and C<file2> and returns
574 true if their content is exactly equal, or false otherwise.
576 The external L<cmp(1)> program is used for the comparison.
582 This returns C<true> if and only if there is a file, directory
583 (or anything) with the given C<path> name.
585 See also C<is-file>, C<is-dir>, C<stat>.
591 This call uses the standard L<file(1)> command to determine
592 the type or contents of the file. This also works on devices,
593 for example to find out whether a partition contains a filesystem.
595 The exact command which runs is C<file -bsL path>. Note in
596 particular that the filename is not prepended to the output
603 This command lists out all files and directories, recursively,
604 starting at C<directory>. It is essentially equivalent to
605 running the shell command C<find directory -print> but some
606 post-processing happens on the output, described below.
608 This returns a list of strings I<without any prefix>. Thus
609 if the directory structure was:
615 then the returned list from C<find> C</tmp> would be
623 If C<directory> is not a directory, then this command returns
626 The returned list is sorted.
632 This runs the filesystem checker (fsck) on C<device> which
633 should have filesystem type C<fstype>.
635 The returned integer is the status. See L<fsck(8)> for the
636 list of status codes from C<fsck>.
644 Multiple status codes can be summed together.
648 A non-zero return code can mean "success", for example if
649 errors have been corrected on the filesystem.
653 Checking or repairing NTFS volumes is not supported
658 This command is entirely equivalent to running C<fsck -a -t fstype device>.
664 Return the additional kernel options which are added to the
665 guest kernel command line.
667 If C<NULL> then no options are added.
673 Get the autosync flag.
679 This returns the ext2/3/4 filesystem label of the filesystem on
686 This returns the ext2/3/4 filesystem UUID of the filesystem on
693 This gets the memory size in megabytes allocated to the
696 If C<set-memsize> was not called
697 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
698 then this returns the compiled-in default value for memsize.
700 For more information on the architecture of libguestfs,
707 Return the current search path.
709 This is always non-NULL. If it wasn't set already, then this will
710 return the default path.
716 Return the current qemu binary.
718 This is always non-NULL. If it wasn't set already, then this will
719 return the default qemu binary name.
725 This returns the current state as an opaque integer. This is
726 only useful for printing debug and internal error messages.
728 For more information on states, see L<guestfs(3)>.
734 This returns the verbose messages flag.
740 This command searches for all the pathnames matching
741 C<pattern> according to the wildcard expansion rules
744 If no paths match, then this returns an empty list
745 (note: not an error).
747 It is just a wrapper around the C L<glob(3)> function
748 with flags C<GLOB_MARK|GLOB_BRACE>.
749 See that manual page for more details.
753 grub-install root device
755 This command installs GRUB (the Grand Unified Bootloader) on
756 C<device>, with the root directory being C<root>.
762 This command returns up to the first 10 lines of a file as
765 Because of the message protocol, there is a transfer limit
766 of somewhere between 2MB and 4MB. To transfer large files you should use
773 If the parameter C<nrlines> is a positive number, this returns the first
774 C<nrlines> lines of the file C<path>.
776 If the parameter C<nrlines> is a negative number, this returns lines
777 from the file C<path>, excluding the last C<nrlines> lines.
779 If the parameter C<nrlines> is zero, this returns an empty list.
781 Because of the message protocol, there is a transfer limit
782 of somewhere between 2MB and 4MB. To transfer large files you should use
789 This runs C<hexdump -C> on the given C<path>. The result is
790 the human-readable, canonical hex dump of the file.
792 Because of the message protocol, there is a transfer limit
793 of somewhere between 2MB and 4MB. To transfer large files you should use
800 This command lists out files contained in an initrd.
802 The files are listed without any initial C</> character. The
803 files are listed in the order they appear (not necessarily
804 alphabetical). Directory names are listed as separate items.
806 Old Linux kernels (2.4 and earlier) used a compressed ext2
807 filesystem as initrd. We I<only> support the newer initramfs
808 format (compressed cpio files).
814 This returns true iff this handle is busy processing a command
815 (in the C<BUSY> state).
817 For more information on states, see L<guestfs(3)>.
823 This returns true iff this handle is being configured
824 (in the C<CONFIG> state).
826 For more information on states, see L<guestfs(3)>.
832 This returns C<true> if and only if there is a directory
833 with the given C<path> name. Note that it returns false for
834 other objects like files.
842 This returns C<true> if and only if there is a file
843 with the given C<path> name. Note that it returns false for
844 other objects like directories.
852 This returns true iff this handle is launching the subprocess
853 (in the C<LAUNCHING> state).
855 For more information on states, see L<guestfs(3)>.
861 This returns true iff this handle is ready to accept commands
862 (in the C<READY> state).
864 For more information on states, see L<guestfs(3)>.
866 =head2 kill-subprocess
870 This kills the qemu subprocess. You should never need to call this.
876 Internally libguestfs is implemented by running a virtual machine
879 You should call this after configuring the handle
880 (eg. adding drives) but before performing any actions.
886 List all the block devices.
888 The full block device names are returned, eg. C</dev/sda>
890 =head2 list-partitions
894 List all the partitions detected on all block devices.
896 The full partition device names are returned, eg. C</dev/sda1>
898 This does not return logical volumes. For that you will need to
905 List the files in C<directory> (relative to the root directory,
906 there is no cwd) in the format of 'ls -la'.
908 This command is mostly useful for interactive sessions. It
909 is I<not> intended that you try to parse the output string.
915 List the files in C<directory> (relative to the root directory,
916 there is no cwd). The '.' and '..' entries are not returned, but
917 hidden files are shown.
919 This command is mostly useful for interactive sessions. Programs
920 should probably use C<readdir> instead.
926 Returns file information for the given C<path>.
928 This is the same as C<stat> except that if C<path>
929 is a symbolic link, then the link is stat-ed, not the file it
932 This is the same as the C<lstat(2)> system call.
936 lvcreate logvol volgroup mbytes
938 This creates an LVM volume group called C<logvol>
939 on the volume group C<volgroup>, with C<size> megabytes.
941 =head2 lvm-remove-all
945 This command removes all LVM logical volumes, volume groups
946 and physical volumes.
948 B<This command is dangerous. Without careful use you
949 can easily destroy all your data>.
955 Remove an LVM logical volume C<device>, where C<device> is
956 the path to the LV, such as C</dev/VG/LV>.
958 You can also remove all LVs in a volume group by specifying
959 the VG name, C</dev/VG>.
963 lvresize device mbytes
965 This resizes (expands or shrinks) an existing LVM logical
966 volume to C<mbytes>. When reducing, data in the reduced part
973 List all the logical volumes detected. This is the equivalent
974 of the L<lvs(8)> command.
976 This returns a list of the logical volume device names
977 (eg. C</dev/VolGroup00/LogVol00>).
979 See also C<lvs-full>.
985 List all the logical volumes detected. This is the equivalent
986 of the L<lvs(8)> command. The "full" version includes all fields.
992 Create a directory named C<path>.
998 Create a directory named C<path>, creating any parent directories
999 as necessary. This is like the C<mkdir -p> shell command.
1005 This command creates a temporary directory. The
1006 C<template> parameter should be a full pathname for the
1007 temporary directory name with the final six characters being
1010 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX",
1011 the second one being suitable for Windows filesystems.
1013 The name of the temporary directory that was created
1016 The temporary directory is created with mode 0700
1017 and is owned by root.
1019 The caller is responsible for deleting the temporary
1020 directory and its contents after use.
1022 See also: L<mkdtemp(3)>
1028 This call creates a FIFO (named pipe) called C<path> with
1029 mode C<mode>. It is just a convenient wrapper around
1036 This creates a filesystem on C<device> (usually a partition
1037 or LVM logical volume). The filesystem type is C<fstype>, for
1042 mknod mode devmajor devminor path
1044 This call creates block or character special devices, or
1045 named pipes (FIFOs).
1047 The C<mode> parameter should be the mode, using the standard
1048 constants. C<devmajor> and C<devminor> are the
1049 device major and minor numbers, only used when creating block
1050 and character special devices.
1054 mknod-b mode devmajor devminor path
1056 This call creates a block device node called C<path> with
1057 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
1058 It is just a convenient wrapper around C<mknod>.
1062 mknod-c mode devmajor devminor path
1064 This call creates a char device node called C<path> with
1065 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
1066 It is just a convenient wrapper around C<mknod>.
1072 Create a swap partition on C<device>.
1076 mkswap-L label device
1078 Create a swap partition on C<device> with label C<label>.
1082 mkswap-U uuid device
1084 Create a swap partition on C<device> with UUID C<uuid>.
1088 mount device mountpoint
1090 Mount a guest disk at a position in the filesystem. Block devices
1091 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1092 the guest. If those block devices contain partitions, they will have
1093 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
1096 The rules are the same as for L<mount(2)>: A filesystem must
1097 first be mounted on C</> before others can be mounted. Other
1098 filesystems can only be mounted on directories which already
1101 The mounted filesystem is writable, if we have sufficient permissions
1102 on the underlying device.
1104 The filesystem options C<sync> and C<noatime> are set with this
1105 call, in order to improve reliability.
1109 mount-loop file mountpoint
1111 This command lets you mount C<file> (a filesystem image
1112 in a file) on a mount point. It is entirely equivalent to
1113 the command C<mount -o loop file mountpoint>.
1115 =head2 mount-options
1117 mount-options options device mountpoint
1119 This is the same as the C<mount> command, but it
1120 allows you to set the mount options as for the
1121 L<mount(8)> I<-o> flag.
1125 mount-ro device mountpoint
1127 This is the same as the C<mount> command, but it
1128 mounts the filesystem with the read-only (I<-o ro>) flag.
1132 mount-vfs options vfstype device mountpoint
1134 This is the same as the C<mount> command, but it
1135 allows you to set both the mount options and the vfstype
1136 as for the L<mount(8)> I<-o> and I<-t> flags.
1142 This returns the list of currently mounted filesystems. It returns
1143 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1145 Some internal mounts are not shown.
1151 This moves a file from C<src> to C<dest> where C<dest> is
1152 either a destination filename or destination directory.
1154 =head2 ntfs-3g-probe
1156 ntfs-3g-probe true|false device
1158 This command runs the L<ntfs-3g.probe(8)> command which probes
1159 an NTFS C<device> for mountability. (Not all NTFS volumes can
1160 be mounted read-write, and some cannot be mounted at all).
1162 C<rw> is a boolean flag. Set it to true if you want to test
1163 if the volume can be mounted read-write. Set it to false if
1164 you want to test if the volume can be mounted read-only.
1166 The return value is an integer which C<0> if the operation
1167 would succeed, or some non-zero value documented in the
1168 L<ntfs-3g.probe(8)> manual page.
1174 This is a test probe into the guestfs daemon running inside
1175 the qemu subprocess. Calling this function checks that the
1176 daemon responds to the ping message, without affecting the daemon
1177 or attached block device(s) in any other way.
1183 This creates an LVM physical volume on the named C<device>,
1184 where C<device> should usually be a partition name such
1191 This wipes a physical volume C<device> so that LVM will no longer
1194 The implementation uses the C<pvremove> command which refuses to
1195 wipe physical volumes that contain any volume groups, so you have
1196 to remove those first.
1202 This resizes (expands or shrinks) an existing LVM physical
1203 volume to match the new size of the underlying device.
1209 List all the physical volumes detected. This is the equivalent
1210 of the L<pvs(8)> command.
1212 This returns a list of just the device names that contain
1213 PVs (eg. C</dev/sda2>).
1215 See also C<pvs-full>.
1221 List all the physical volumes detected. This is the equivalent
1222 of the L<pvs(8)> command. The "full" version includes all fields.
1228 Return the contents of the file named C<path>.
1230 The file contents are returned as a list of lines. Trailing
1231 C<LF> and C<CRLF> character sequences are I<not> returned.
1233 Note that this function cannot correctly handle binary files
1234 (specifically, files containing C<\0> character which is treated
1235 as end of line). For those you need to use the C<read-file>
1236 function which has a more complex interface.
1242 This resizes an ext2 or ext3 filesystem to match the size of
1243 the underlying device.
1245 I<Note:> It is sometimes required that you run C<e2fsck-f>
1246 on the C<device> before calling this command. For unknown reasons
1247 C<resize2fs> sometimes gives an error about this and sometimes not.
1248 In any case, it is always safe to call C<e2fsck-f> before
1249 calling this function.
1255 Remove the single file C<path>.
1261 Remove the file or directory C<path>, recursively removing the
1262 contents if its a directory. This is like the C<rm -rf> shell
1269 Remove the single directory C<path>.
1275 This command writes patterns over C<device> to make data retrieval
1278 It is an interface to the L<scrub(1)> program. See that
1279 manual page for more details.
1281 B<This command is dangerous. Without careful use you
1282 can easily destroy all your data>.
1288 This command writes patterns over a file to make data retrieval
1291 The file is I<removed> after scrubbing.
1293 It is an interface to the L<scrub(1)> program. See that
1294 manual page for more details.
1296 =head2 scrub-freespace
1300 This command creates the directory C<dir> and then fills it
1301 with files until the filesystem is full, and scrubs the files
1302 as for C<scrub-file>, and deletes them.
1303 The intention is to scrub any free space on the partition
1306 It is an interface to the L<scrub(1)> program. See that
1307 manual page for more details.
1309 =head2 set-append | append
1313 This function is used to add additional options to the
1314 guest kernel command line.
1316 The default is C<NULL> unless overridden by setting
1317 C<LIBGUESTFS_APPEND> environment variable.
1319 Setting C<append> to C<NULL> means I<no> additional options
1320 are passed (libguestfs always adds a few of its own).
1322 =head2 set-autosync | autosync
1324 set-autosync true|false
1326 If C<autosync> is true, this enables autosync. Libguestfs will make a
1327 best effort attempt to run C<umount-all> followed by
1328 C<sync> when the handle is closed
1329 (also if the program exits without closing handles).
1331 This is disabled by default (except in guestfish where it is
1332 enabled by default).
1336 set-e2label device label
1338 This sets the ext2/3/4 filesystem label of the filesystem on
1339 C<device> to C<label>. Filesystem labels are limited to
1342 You can use either C<tune2fs-l> or C<get-e2label>
1343 to return the existing label on a filesystem.
1347 set-e2uuid device uuid
1349 This sets the ext2/3/4 filesystem UUID of the filesystem on
1350 C<device> to C<uuid>. The format of the UUID and alternatives
1351 such as C<clear>, C<random> and C<time> are described in the
1352 L<tune2fs(8)> manpage.
1354 You can use either C<tune2fs-l> or C<get-e2uuid>
1355 to return the existing UUID of a filesystem.
1357 =head2 set-memsize | memsize
1361 This sets the memory size in megabytes allocated to the
1362 qemu subprocess. This only has any effect if called before
1365 You can also change this by setting the environment
1366 variable C<LIBGUESTFS_MEMSIZE> before the handle is
1369 For more information on the architecture of libguestfs,
1372 =head2 set-path | path
1376 Set the path that libguestfs searches for kernel and initrd.img.
1378 The default is C<$libdir/guestfs> unless overridden by setting
1379 C<LIBGUESTFS_PATH> environment variable.
1381 Setting C<path> to C<NULL> restores the default path.
1383 =head2 set-qemu | qemu
1387 Set the qemu binary that we will use.
1389 The default is chosen when the library was compiled by the
1392 You can also override this by setting the C<LIBGUESTFS_QEMU>
1393 environment variable.
1395 Setting C<qemu> to C<NULL> restores the default qemu binary.
1397 =head2 set-verbose | verbose
1399 set-verbose true|false
1401 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
1403 Verbose messages are disabled unless the environment variable
1404 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
1408 sfdisk device cyls heads sectors 'lines ...'
1410 This is a direct interface to the L<sfdisk(8)> program for creating
1411 partitions on block devices.
1413 C<device> should be a block device, for example C</dev/sda>.
1415 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1416 and sectors on the device, which are passed directly to sfdisk as
1417 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1418 of these, then the corresponding parameter is omitted. Usually for
1419 'large' disks, you can just pass C<0> for these, but for small
1420 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1421 out the right geometry and you will need to tell it.
1423 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1424 information refer to the L<sfdisk(8)> manpage.
1426 To create a single partition occupying the whole disk, you would
1427 pass C<lines> as a single element list, when the single element being
1428 the string C<,> (comma).
1430 See also: C<sfdisk-l>, C<sfdisk-N>
1432 B<This command is dangerous. Without careful use you
1433 can easily destroy all your data>.
1437 sfdisk-N device partnum cyls heads sectors line
1439 This runs L<sfdisk(8)> option to modify just the single
1440 partition C<n> (note: C<n> counts from 1).
1442 For other parameters, see C<sfdisk>. You should usually
1443 pass C<0> for the cyls/heads/sectors parameters.
1445 B<This command is dangerous. Without careful use you
1446 can easily destroy all your data>.
1448 =head2 sfdisk-disk-geometry
1450 sfdisk-disk-geometry device
1452 This displays the disk geometry of C<device> read from the
1453 partition table. Especially in the case where the underlying
1454 block device has been resized, this can be different from the
1455 kernel's idea of the geometry (see C<sfdisk-kernel-geometry>).
1457 The result is in human-readable format, and not designed to
1460 =head2 sfdisk-kernel-geometry
1462 sfdisk-kernel-geometry device
1464 This displays the kernel's idea of the geometry of C<device>.
1466 The result is in human-readable format, and not designed to
1473 This displays the partition table on C<device>, in the
1474 human-readable output of the L<sfdisk(8)> command. It is
1475 not intended to be parsed.
1481 This call runs a command from the guest filesystem via the
1484 This is like C<command>, but passes the command to:
1486 /bin/sh -c "command"
1488 Depending on the guest's shell, this usually results in
1489 wildcards being expanded, shell expressions being interpolated
1492 All the provisos about C<command> apply to this call.
1498 This is the same as C<sh>, but splits the result
1499 into a list of lines.
1501 See also: C<command-lines>
1507 Sleep for C<secs> seconds.
1513 Returns file information for the given C<path>.
1515 This is the same as the C<stat(2)> system call.
1521 Returns file system statistics for any mounted file system.
1522 C<path> should be a file or directory in the mounted file system
1523 (typically it is the mount point itself, but it doesn't need to be).
1525 This is the same as the C<statvfs(2)> system call.
1531 This runs the L<strings(1)> command on a file and returns
1532 the list of printable strings found.
1534 Because of the message protocol, there is a transfer limit
1535 of somewhere between 2MB and 4MB. To transfer large files you should use
1540 strings-e encoding path
1542 This is like the C<strings> command, but allows you to
1543 specify the encoding.
1545 See the L<strings(1)> manpage for the full list of encodings.
1547 Commonly useful encodings are C<l> (lower case L) which will
1548 show strings inside Windows/x86 files.
1550 The returned strings are transcoded to UTF-8.
1552 Because of the message protocol, there is a transfer limit
1553 of somewhere between 2MB and 4MB. To transfer large files you should use
1560 This syncs the disk, so that any writes are flushed through to the
1561 underlying disk image.
1563 You should always call this if you have modified a disk image, before
1570 This command returns up to the last 10 lines of a file as
1573 Because of the message protocol, there is a transfer limit
1574 of somewhere between 2MB and 4MB. To transfer large files you should use
1581 If the parameter C<nrlines> is a positive number, this returns the last
1582 C<nrlines> lines of the file C<path>.
1584 If the parameter C<nrlines> is a negative number, this returns lines
1585 from the file C<path>, starting with the C<-nrlines>th line.
1587 If the parameter C<nrlines> is zero, this returns an empty list.
1589 Because of the message protocol, there is a transfer limit
1590 of somewhere between 2MB and 4MB. To transfer large files you should use
1595 tar-in (tarfile|-) directory
1597 This command uploads and unpacks local file C<tarfile> (an
1598 I<uncompressed> tar file) into C<directory>.
1600 To upload a compressed tarball, use C<tgz-in>.
1602 Use C<-> instead of a filename to read/write from stdin/stdout.
1606 tar-out directory (tarfile|-)
1608 This command packs the contents of C<directory> and downloads
1609 it to local file C<tarfile>.
1611 To download a compressed tarball, use C<tgz-out>.
1613 Use C<-> instead of a filename to read/write from stdin/stdout.
1617 tgz-in (tarball|-) directory
1619 This command uploads and unpacks local file C<tarball> (a
1620 I<gzip compressed> tar file) into C<directory>.
1622 To upload an uncompressed tarball, use C<tar-in>.
1624 Use C<-> instead of a filename to read/write from stdin/stdout.
1628 tgz-out directory (tarball|-)
1630 This command packs the contents of C<directory> and downloads
1631 it to local file C<tarball>.
1633 To download an uncompressed tarball, use C<tar-out>.
1635 Use C<-> instead of a filename to read/write from stdin/stdout.
1641 Touch acts like the L<touch(1)> command. It can be used to
1642 update the timestamps on a file, or, if the file does not exist,
1643 to create a new zero-length file.
1649 This returns the contents of the ext2, ext3 or ext4 filesystem
1650 superblock on C<device>.
1652 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
1653 manpage for more details. The list of fields returned isn't
1654 clearly defined, and depends on both the version of C<tune2fs>
1655 that libguestfs was built against, and the filesystem itself.
1661 This function sets the mask used for creating new files and
1662 device nodes to C<mask & 0777>.
1664 Typical umask values would be C<022> which creates new files
1665 with permissions like "-rw-r--r--" or "-rwxr-xr-x", and
1666 C<002> which creates new files with permissions like
1667 "-rw-rw-r--" or "-rwxrwxr-x".
1669 The default umask is C<022>. This is important because it
1670 means that directories and device nodes will be created with
1671 C<0644> or C<0755> mode even if you specify C<0777>.
1673 See also L<umask(2)>, C<mknod>, C<mkdir>.
1675 This call returns the previous umask.
1677 =head2 umount | unmount
1681 This unmounts the given filesystem. The filesystem may be
1682 specified either by its mountpoint (path) or the device which
1683 contains the filesystem.
1685 =head2 umount-all | unmount-all
1689 This unmounts all mounted filesystems.
1691 Some internal mounts are not unmounted by this call.
1695 upload (filename|-) remotefilename
1697 Upload local file C<filename> to C<remotefilename> on the
1700 C<filename> can also be a named pipe.
1702 See also C<download>.
1704 Use C<-> instead of a filename to read/write from stdin/stdout.
1708 vg-activate true|false 'volgroups ...'
1710 This command activates or (if C<activate> is false) deactivates
1711 all logical volumes in the listed volume groups C<volgroups>.
1712 If activated, then they are made known to the
1713 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
1714 then those devices disappear.
1716 This command is the same as running C<vgchange -a y|n volgroups...>
1718 Note that if C<volgroups> is an empty list then B<all> volume groups
1719 are activated or deactivated.
1721 =head2 vg-activate-all
1723 vg-activate-all true|false
1725 This command activates or (if C<activate> is false) deactivates
1726 all logical volumes in all volume groups.
1727 If activated, then they are made known to the
1728 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
1729 then those devices disappear.
1731 This command is the same as running C<vgchange -a y|n>
1735 vgcreate volgroup 'physvols ...'
1737 This creates an LVM volume group called C<volgroup>
1738 from the non-empty list of physical volumes C<physvols>.
1744 Remove an LVM volume group C<vgname>, (for example C<VG>).
1746 This also forcibly removes all logical volumes in the volume
1753 List all the volumes groups detected. This is the equivalent
1754 of the L<vgs(8)> command.
1756 This returns a list of just the volume group names that were
1757 detected (eg. C<VolGroup00>).
1759 See also C<vgs-full>.
1765 List all the volumes groups detected. This is the equivalent
1766 of the L<vgs(8)> command. The "full" version includes all fields.
1772 This command counts the characters in a file, using the
1773 C<wc -c> external command.
1779 This command counts the lines in a file, using the
1780 C<wc -l> external command.
1786 This command counts the words in a file, using the
1787 C<wc -w> external command.
1791 write-file path content size
1793 This call creates a file called C<path>. The contents of the
1794 file is the string C<content> (which can contain any 8 bit data),
1795 with length C<size>.
1797 As a special case, if C<size> is C<0>
1798 then the length is calculated using C<strlen> (so in this case
1799 the content cannot contain embedded ASCII NULs).
1801 I<NB.> Owing to a bug, writing content containing ASCII NUL
1802 characters does I<not> work, even if the length is specified.
1803 We hope to resolve this bug in a future version. In the meantime
1806 Because of the message protocol, there is a transfer limit
1807 of somewhere between 2MB and 4MB. To transfer large files you should use
1814 This command writes zeroes over the first few blocks of C<device>.
1816 How many blocks are zeroed isn't specified (but it's I<not> enough
1817 to securely wipe the device). It should be sufficient to remove
1818 any partition tables, filesystem superblocks and so on.
1820 See also: C<scrub-device>.
1826 This runs the I<zerofree> program on C<device>. This program
1827 claims to zero unused inodes and disk blocks on an ext2/3
1828 filesystem, thus making it possible to compress the filesystem
1831 You should B<not> run this program if the filesystem is
1834 It is possible that using this program can damage the filesystem
1835 or data on the filesystem.