1 # libguestfs generated file
2 # WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.
3 # ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.
5 # Copyright (C) 2009 Red Hat Inc.
7 # This library is free software; you can redistribute it and/or
8 # modify it under the terms of the GNU Lesser General Public
9 # License as published by the Free Software Foundation; either
10 # version 2 of the License, or (at your option) any later version.
12 # This library is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 # Lesser General Public License for more details.
17 # You should have received a copy of the GNU Lesser General Public
18 # License along with this library; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 Sys::Guestfs - Perl bindings for libguestfs
31 my $h = Sys::Guestfs->new ();
32 $h->add_drive ('guest.img');
35 $h->mount ('/dev/sda1', '/');
41 The C<Sys::Guestfs> module provides a Perl XS binding to the
42 libguestfs API for examining and modifying virtual machine
45 Amongst the things this is good for: making batch configuration
46 changes to guests, getting disk used/free statistics (see also:
47 virt-df), migrating between virtualization systems (see also:
48 virt-p2v), performing partial backups, performing partial guest
49 clones, cloning guests and changing registry/UUID/hostname info, and
52 Libguestfs uses Linux kernel and qemu code, and can access any type of
53 guest filesystem that Linux and qemu can, including but not limited
54 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
55 schemes, qcow, qcow2, vmdk.
57 Libguestfs provides ways to enumerate guest storage (eg. partitions,
58 LVs, what filesystem is in each LV, etc.). It can also run commands
59 in the context of the guest. Also you can access filesystems over FTP.
63 All errors turn into calls to C<croak> (see L<Carp(3)>).
77 XSLoader::load ('Sys::Guestfs');
79 =item $h = Sys::Guestfs->new ();
81 Create a new guestfs handle.
87 my $class = ref ($proto) || $proto;
89 my $self = Sys::Guestfs::_create ();
94 =item $h->add_cdrom ($filename);
96 This function adds a virtual CD-ROM disk image to the guest.
98 This is equivalent to the qemu parameter C<-cdrom filename>.
100 Note that this call checks for the existence of C<filename>. This
101 stops you from specifying other types of drive which are supported
102 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
103 the general C<$h-E<gt>config> call instead.
105 =item $h->add_drive ($filename);
107 This function adds a virtual machine disk image C<filename> to the
108 guest. The first time you call this function, the disk appears as IDE
109 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
112 You don't necessarily need to be root when using libguestfs. However
113 you obviously do need sufficient permissions to access the filename
114 for whatever operations you want to perform (ie. read access if you
115 just want to read the image or write access if you want to modify the
118 This is equivalent to the qemu parameter
119 C<-drive file=filename,cache=off,if=virtio>.
121 Note that this call checks for the existence of C<filename>. This
122 stops you from specifying other types of drive which are supported
123 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
124 the general C<$h-E<gt>config> call instead.
126 =item $h->add_drive_ro ($filename);
128 This adds a drive in snapshot mode, making it effectively
131 Note that writes to the device are allowed, and will be seen for
132 the duration of the guestfs handle, but they are written
133 to a temporary file which is discarded as soon as the guestfs
134 handle is closed. We don't currently have any method to enable
135 changes to be committed, although qemu can support this.
137 This is equivalent to the qemu parameter
138 C<-drive file=filename,snapshot=on,if=virtio>.
140 Note that this call checks for the existence of C<filename>. This
141 stops you from specifying other types of drive which are supported
142 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
143 the general C<$h-E<gt>config> call instead.
145 =item $h->aug_close ();
147 Close the current Augeas handle and free up any resources
148 used by it. After calling this, you have to call
149 C<$h-E<gt>aug_init> again before you can use any other
152 =item ($nrnodes, $created) = $h->aug_defnode ($name, $expr, $val);
154 Defines a variable C<name> whose value is the result of
157 If C<expr> evaluates to an empty nodeset, a node is created,
158 equivalent to calling C<$h-E<gt>aug_set> C<expr>, C<value>.
159 C<name> will be the nodeset containing that single node.
161 On success this returns a pair containing the
162 number of nodes in the nodeset, and a boolean flag
163 if a node was created.
165 =item $nrnodes = $h->aug_defvar ($name, $expr);
167 Defines an Augeas variable C<name> whose value is the result
168 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
171 On success this returns the number of nodes in C<expr>, or
172 C<0> if C<expr> evaluates to something which is not a nodeset.
174 =item $val = $h->aug_get ($path);
176 Look up the value associated with C<path>. If C<path>
177 matches exactly one node, the C<value> is returned.
179 =item $h->aug_init ($root, $flags);
181 Create a new Augeas handle for editing configuration files.
182 If there was any previous Augeas handle associated with this
183 guestfs session, then it is closed.
185 You must call this before using any other C<$h-E<gt>aug_*>
188 C<root> is the filesystem root. C<root> must not be NULL,
191 The flags are the same as the flags defined in
192 E<lt>augeas.hE<gt>, the logical I<or> of the following
197 =item C<AUG_SAVE_BACKUP> = 1
199 Keep the original file with a C<.augsave> extension.
201 =item C<AUG_SAVE_NEWFILE> = 2
203 Save changes into a file with extension C<.augnew>, and
204 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
206 =item C<AUG_TYPE_CHECK> = 4
208 Typecheck lenses (can be expensive).
210 =item C<AUG_NO_STDINC> = 8
212 Do not use standard load path for modules.
214 =item C<AUG_SAVE_NOOP> = 16
216 Make save a no-op, just record what would have been changed.
218 =item C<AUG_NO_LOAD> = 32
220 Do not load the tree in C<$h-E<gt>aug_init>.
224 To close the handle, you can call C<$h-E<gt>aug_close>.
226 To find out more about Augeas, see L<http://augeas.net/>.
228 =item $h->aug_insert ($path, $label, $before);
230 Create a new sibling C<label> for C<path>, inserting it into
231 the tree before or after C<path> (depending on the boolean
234 C<path> must match exactly one existing node in the tree, and
235 C<label> must be a label, ie. not contain C</>, C<*> or end
236 with a bracketed index C<[N]>.
238 =item $h->aug_load ();
240 Load files into the tree.
242 See C<aug_load> in the Augeas documentation for the full gory
245 =item @matches = $h->aug_ls ($path);
247 This is just a shortcut for listing C<$h-E<gt>aug_match>
248 C<path/*> and sorting the resulting nodes into alphabetical order.
250 =item @matches = $h->aug_match ($path);
252 Returns a list of paths which match the path expression C<path>.
253 The returned paths are sufficiently qualified so that they match
254 exactly one node in the current tree.
256 =item $h->aug_mv ($src, $dest);
258 Move the node C<src> to C<dest>. C<src> must match exactly
259 one node. C<dest> is overwritten if it exists.
261 =item $nrnodes = $h->aug_rm ($path);
263 Remove C<path> and all of its children.
265 On success this returns the number of entries which were removed.
267 =item $h->aug_save ();
269 This writes all pending changes to disk.
271 The flags which were passed to C<$h-E<gt>aug_init> affect exactly
274 =item $h->aug_set ($path, $val);
276 Set the value associated with C<path> to C<value>.
278 =item $h->blockdev_flushbufs ($device);
280 This tells the kernel to flush internal buffers associated
283 This uses the L<blockdev(8)> command.
285 =item $blocksize = $h->blockdev_getbsz ($device);
287 This returns the block size of a device.
289 (Note this is different from both I<size in blocks> and
290 I<filesystem block size>).
292 This uses the L<blockdev(8)> command.
294 =item $ro = $h->blockdev_getro ($device);
296 Returns a boolean indicating if the block device is read-only
297 (true if read-only, false if not).
299 This uses the L<blockdev(8)> command.
301 =item $sizeinbytes = $h->blockdev_getsize64 ($device);
303 This returns the size of the device in bytes.
305 See also C<$h-E<gt>blockdev_getsz>.
307 This uses the L<blockdev(8)> command.
309 =item $sectorsize = $h->blockdev_getss ($device);
311 This returns the size of sectors on a block device.
312 Usually 512, but can be larger for modern devices.
314 (Note, this is not the size in sectors, use C<$h-E<gt>blockdev_getsz>
317 This uses the L<blockdev(8)> command.
319 =item $sizeinsectors = $h->blockdev_getsz ($device);
321 This returns the size of the device in units of 512-byte sectors
322 (even if the sectorsize isn't 512 bytes ... weird).
324 See also C<$h-E<gt>blockdev_getss> for the real sector size of
325 the device, and C<$h-E<gt>blockdev_getsize64> for the more
326 useful I<size in bytes>.
328 This uses the L<blockdev(8)> command.
330 =item $h->blockdev_rereadpt ($device);
332 Reread the partition table on C<device>.
334 This uses the L<blockdev(8)> command.
336 =item $h->blockdev_setbsz ($device, $blocksize);
338 This sets the block size of a device.
340 (Note this is different from both I<size in blocks> and
341 I<filesystem block size>).
343 This uses the L<blockdev(8)> command.
345 =item $h->blockdev_setro ($device);
347 Sets the block device named C<device> to read-only.
349 This uses the L<blockdev(8)> command.
351 =item $h->blockdev_setrw ($device);
353 Sets the block device named C<device> to read-write.
355 This uses the L<blockdev(8)> command.
357 =item $content = $h->cat ($path);
359 Return the contents of the file named C<path>.
361 Note that this function cannot correctly handle binary files
362 (specifically, files containing C<\0> character which is treated
363 as end of string). For those you need to use the C<$h-E<gt>download>
364 function which has a more complex interface.
366 Because of the message protocol, there is a transfer limit
367 of somewhere between 2MB and 4MB. To transfer large files you should use
370 =item $checksum = $h->checksum ($csumtype, $path);
372 This call computes the MD5, SHAx or CRC checksum of the
375 The type of checksum to compute is given by the C<csumtype>
376 parameter which must have one of the following values:
382 Compute the cyclic redundancy check (CRC) specified by POSIX
383 for the C<cksum> command.
387 Compute the MD5 hash (using the C<md5sum> program).
391 Compute the SHA1 hash (using the C<sha1sum> program).
395 Compute the SHA224 hash (using the C<sha224sum> program).
399 Compute the SHA256 hash (using the C<sha256sum> program).
403 Compute the SHA384 hash (using the C<sha384sum> program).
407 Compute the SHA512 hash (using the C<sha512sum> program).
411 The checksum is returned as a printable string.
413 =item $h->chmod ($mode, $path);
415 Change the mode (permissions) of C<path> to C<mode>. Only
416 numeric modes are supported.
418 =item $h->chown ($owner, $group, $path);
420 Change the file owner to C<owner> and group to C<group>.
422 Only numeric uid and gid are supported. If you want to use
423 names, you will need to locate and parse the password file
424 yourself (Augeas support makes this relatively easy).
426 =item $output = $h->command (\@arguments);
428 This call runs a command from the guest filesystem. The
429 filesystem must be mounted, and must contain a compatible
430 operating system (ie. something Linux, with the same
431 or compatible processor architecture).
433 The single parameter is an argv-style list of arguments.
434 The first element is the name of the program to run.
435 Subsequent elements are parameters. The list must be
436 non-empty (ie. must contain a program name). Note that
437 the command runs directly, and is I<not> invoked via
438 the shell (see C<$h-E<gt>sh>).
440 The return value is anything printed to I<stdout> by
443 If the command returns a non-zero exit status, then
444 this function returns an error message. The error message
445 string is the content of I<stderr> from the command.
447 The C<$PATH> environment variable will contain at least
448 C</usr/bin> and C</bin>. If you require a program from
449 another location, you should provide the full path in the
452 Shared libraries and data files required by the program
453 must be available on filesystems which are mounted in the
454 correct places. It is the caller's responsibility to ensure
455 all filesystems that are needed are mounted at the right
458 Because of the message protocol, there is a transfer limit
459 of somewhere between 2MB and 4MB. To transfer large files you should use
462 =item @lines = $h->command_lines (\@arguments);
464 This is the same as C<$h-E<gt>command>, but splits the
465 result into a list of lines.
467 See also: C<$h-E<gt>sh_lines>
469 Because of the message protocol, there is a transfer limit
470 of somewhere between 2MB and 4MB. To transfer large files you should use
473 =item $h->config ($qemuparam, $qemuvalue);
475 This can be used to add arbitrary qemu command line parameters
476 of the form C<-param value>. Actually it's not quite arbitrary - we
477 prevent you from setting some parameters which would interfere with
478 parameters that we use.
480 The first character of C<param> string must be a C<-> (dash).
482 C<value> can be NULL.
484 =item $h->cp ($src, $dest);
486 This copies a file from C<src> to C<dest> where C<dest> is
487 either a destination filename or destination directory.
489 =item $h->cp_a ($src, $dest);
491 This copies a file or directory from C<src> to C<dest>
492 recursively using the C<cp -a> command.
494 =item $result = $h->debug ($subcmd, \@extraargs);
496 The C<$h-E<gt>debug> command exposes some internals of
497 C<guestfsd> (the guestfs daemon) that runs inside the
500 There is no comprehensive help for this command. You have
501 to look at the file C<daemon/debug.c> in the libguestfs source
502 to find out what you can do.
504 =item $output = $h->df ();
506 This command runs the C<df> command to report disk space used.
508 This command is mostly useful for interactive sessions. It
509 is I<not> intended that you try to parse the output string.
510 Use C<statvfs> from programs.
512 =item $output = $h->df_h ();
514 This command runs the C<df -h> command to report disk space used
515 in human-readable format.
517 This command is mostly useful for interactive sessions. It
518 is I<not> intended that you try to parse the output string.
519 Use C<statvfs> from programs.
521 =item $kmsgs = $h->dmesg ();
523 This returns the kernel messages (C<dmesg> output) from
524 the guest kernel. This is sometimes useful for extended
525 debugging of problems.
527 Another way to get the same information is to enable
528 verbose messages with C<$h-E<gt>set_verbose> or by setting
529 the environment variable C<LIBGUESTFS_DEBUG=1> before
532 =item $h->download ($remotefilename, $filename);
534 Download file C<remotefilename> and save it as C<filename>
535 on the local machine.
537 C<filename> can also be a named pipe.
539 See also C<$h-E<gt>upload>, C<$h-E<gt>cat>.
541 =item $h->drop_caches ($whattodrop);
543 This instructs the guest kernel to drop its page cache,
544 and/or dentries and inode caches. The parameter C<whattodrop>
545 tells the kernel what precisely to drop, see
546 L<http://linux-mm.org/Drop_Caches>
548 Setting C<whattodrop> to 3 should drop everything.
550 This automatically calls L<sync(2)> before the operation,
551 so that the maximum guest memory is freed.
553 =item $sizekb = $h->du ($path);
555 This command runs the C<du -s> command to estimate file space
558 C<path> can be a file or a directory. If C<path> is a directory
559 then the estimate includes the contents of the directory and all
560 subdirectories (recursively).
562 The result is the estimated size in I<kilobytes>
563 (ie. units of 1024 bytes).
565 =item $h->e2fsck_f ($device);
567 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
568 filesystem checker on C<device>, noninteractively (C<-p>),
569 even if the filesystem appears to be clean (C<-f>).
571 This command is only needed because of C<$h-E<gt>resize2fs>
572 (q.v.). Normally you should use C<$h-E<gt>fsck>.
574 =item $h->end_busy ();
576 This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
577 state as is. This is only used when implementing
578 actions using the low-level API.
580 For more information on states, see L<guestfs(3)>.
582 =item $equality = $h->equal ($file1, $file2);
584 This compares the two files C<file1> and C<file2> and returns
585 true if their content is exactly equal, or false otherwise.
587 The external L<cmp(1)> program is used for the comparison.
589 =item $existsflag = $h->exists ($path);
591 This returns C<true> if and only if there is a file, directory
592 (or anything) with the given C<path> name.
594 See also C<$h-E<gt>is_file>, C<$h-E<gt>is_dir>, C<$h-E<gt>stat>.
596 =item $description = $h->file ($path);
598 This call uses the standard L<file(1)> command to determine
599 the type or contents of the file. This also works on devices,
600 for example to find out whether a partition contains a filesystem.
602 The exact command which runs is C<file -bsL path>. Note in
603 particular that the filename is not prepended to the output
606 =item @names = $h->find ($directory);
608 This command lists out all files and directories, recursively,
609 starting at C<directory>. It is essentially equivalent to
610 running the shell command C<find directory -print> but some
611 post-processing happens on the output, described below.
613 This returns a list of strings I<without any prefix>. Thus
614 if the directory structure was:
620 then the returned list from C<$h-E<gt>find> C</tmp> would be
628 If C<directory> is not a directory, then this command returns
631 The returned list is sorted.
633 =item $status = $h->fsck ($fstype, $device);
635 This runs the filesystem checker (fsck) on C<device> which
636 should have filesystem type C<fstype>.
638 The returned integer is the status. See L<fsck(8)> for the
639 list of status codes from C<fsck>.
647 Multiple status codes can be summed together.
651 A non-zero return code can mean "success", for example if
652 errors have been corrected on the filesystem.
656 Checking or repairing NTFS volumes is not supported
661 This command is entirely equivalent to running C<fsck -a -t fstype device>.
663 =item $append = $h->get_append ();
665 Return the additional kernel options which are added to the
666 guest kernel command line.
668 If C<NULL> then no options are added.
670 =item $autosync = $h->get_autosync ();
672 Get the autosync flag.
674 =item $label = $h->get_e2label ($device);
676 This returns the ext2/3/4 filesystem label of the filesystem on
679 =item $uuid = $h->get_e2uuid ($device);
681 This returns the ext2/3/4 filesystem UUID of the filesystem on
684 =item $memsize = $h->get_memsize ();
686 This gets the memory size in megabytes allocated to the
689 If C<$h-E<gt>set_memsize> was not called
690 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
691 then this returns the compiled-in default value for memsize.
693 For more information on the architecture of libguestfs,
696 =item $path = $h->get_path ();
698 Return the current search path.
700 This is always non-NULL. If it wasn't set already, then this will
701 return the default path.
703 =item $qemu = $h->get_qemu ();
705 Return the current qemu binary.
707 This is always non-NULL. If it wasn't set already, then this will
708 return the default qemu binary name.
710 =item $state = $h->get_state ();
712 This returns the current state as an opaque integer. This is
713 only useful for printing debug and internal error messages.
715 For more information on states, see L<guestfs(3)>.
717 =item $verbose = $h->get_verbose ();
719 This returns the verbose messages flag.
721 =item @paths = $h->glob_expand ($pattern);
723 This command searches for all the pathnames matching
724 C<pattern> according to the wildcard expansion rules
727 If no paths match, then this returns an empty list
728 (note: not an error).
730 It is just a wrapper around the C L<glob(3)> function
731 with flags C<GLOB_MARK|GLOB_BRACE>.
732 See that manual page for more details.
734 =item $h->grub_install ($root, $device);
736 This command installs GRUB (the Grand Unified Bootloader) on
737 C<device>, with the root directory being C<root>.
739 =item @lines = $h->head ($path);
741 This command returns up to the first 10 lines of a file as
744 Because of the message protocol, there is a transfer limit
745 of somewhere between 2MB and 4MB. To transfer large files you should use
748 =item @lines = $h->head_n ($nrlines, $path);
750 If the parameter C<nrlines> is a positive number, this returns the first
751 C<nrlines> lines of the file C<path>.
753 If the parameter C<nrlines> is a negative number, this returns lines
754 from the file C<path>, excluding the last C<nrlines> lines.
756 If the parameter C<nrlines> is zero, this returns an empty list.
758 Because of the message protocol, there is a transfer limit
759 of somewhere between 2MB and 4MB. To transfer large files you should use
762 =item $dump = $h->hexdump ($path);
764 This runs C<hexdump -C> on the given C<path>. The result is
765 the human-readable, canonical hex dump of the file.
767 Because of the message protocol, there is a transfer limit
768 of somewhere between 2MB and 4MB. To transfer large files you should use
771 =item @filenames = $h->initrd_list ($path);
773 This command lists out files contained in an initrd.
775 The files are listed without any initial C</> character. The
776 files are listed in the order they appear (not necessarily
777 alphabetical). Directory names are listed as separate items.
779 Old Linux kernels (2.4 and earlier) used a compressed ext2
780 filesystem as initrd. We I<only> support the newer initramfs
781 format (compressed cpio files).
783 =item $busy = $h->is_busy ();
785 This returns true iff this handle is busy processing a command
786 (in the C<BUSY> state).
788 For more information on states, see L<guestfs(3)>.
790 =item $config = $h->is_config ();
792 This returns true iff this handle is being configured
793 (in the C<CONFIG> state).
795 For more information on states, see L<guestfs(3)>.
797 =item $dirflag = $h->is_dir ($path);
799 This returns C<true> if and only if there is a directory
800 with the given C<path> name. Note that it returns false for
801 other objects like files.
803 See also C<$h-E<gt>stat>.
805 =item $fileflag = $h->is_file ($path);
807 This returns C<true> if and only if there is a file
808 with the given C<path> name. Note that it returns false for
809 other objects like directories.
811 See also C<$h-E<gt>stat>.
813 =item $launching = $h->is_launching ();
815 This returns true iff this handle is launching the subprocess
816 (in the C<LAUNCHING> state).
818 For more information on states, see L<guestfs(3)>.
820 =item $ready = $h->is_ready ();
822 This returns true iff this handle is ready to accept commands
823 (in the C<READY> state).
825 For more information on states, see L<guestfs(3)>.
827 =item $h->kill_subprocess ();
829 This kills the qemu subprocess. You should never need to call this.
833 Internally libguestfs is implemented by running a virtual machine
836 You should call this after configuring the handle
837 (eg. adding drives) but before performing any actions.
839 =item @devices = $h->list_devices ();
841 List all the block devices.
843 The full block device names are returned, eg. C</dev/sda>
845 =item @partitions = $h->list_partitions ();
847 List all the partitions detected on all block devices.
849 The full partition device names are returned, eg. C</dev/sda1>
851 This does not return logical volumes. For that you will need to
854 =item $listing = $h->ll ($directory);
856 List the files in C<directory> (relative to the root directory,
857 there is no cwd) in the format of 'ls -la'.
859 This command is mostly useful for interactive sessions. It
860 is I<not> intended that you try to parse the output string.
862 =item @listing = $h->ls ($directory);
864 List the files in C<directory> (relative to the root directory,
865 there is no cwd). The '.' and '..' entries are not returned, but
866 hidden files are shown.
868 This command is mostly useful for interactive sessions. Programs
869 should probably use C<$h-E<gt>readdir> instead.
871 =item %statbuf = $h->lstat ($path);
873 Returns file information for the given C<path>.
875 This is the same as C<$h-E<gt>stat> except that if C<path>
876 is a symbolic link, then the link is stat-ed, not the file it
879 This is the same as the C<lstat(2)> system call.
881 =item $h->lvcreate ($logvol, $volgroup, $mbytes);
883 This creates an LVM volume group called C<logvol>
884 on the volume group C<volgroup>, with C<size> megabytes.
886 =item $h->lvm_remove_all ();
888 This command removes all LVM logical volumes, volume groups
889 and physical volumes.
891 B<This command is dangerous. Without careful use you
892 can easily destroy all your data>.
894 =item $h->lvremove ($device);
896 Remove an LVM logical volume C<device>, where C<device> is
897 the path to the LV, such as C</dev/VG/LV>.
899 You can also remove all LVs in a volume group by specifying
900 the VG name, C</dev/VG>.
902 =item $h->lvresize ($device, $mbytes);
904 This resizes (expands or shrinks) an existing LVM logical
905 volume to C<mbytes>. When reducing, data in the reduced part
908 =item @logvols = $h->lvs ();
910 List all the logical volumes detected. This is the equivalent
911 of the L<lvs(8)> command.
913 This returns a list of the logical volume device names
914 (eg. C</dev/VolGroup00/LogVol00>).
916 See also C<$h-E<gt>lvs_full>.
918 =item @logvols = $h->lvs_full ();
920 List all the logical volumes detected. This is the equivalent
921 of the L<lvs(8)> command. The "full" version includes all fields.
923 =item $h->mkdir ($path);
925 Create a directory named C<path>.
927 =item $h->mkdir_p ($path);
929 Create a directory named C<path>, creating any parent directories
930 as necessary. This is like the C<mkdir -p> shell command.
932 =item $dir = $h->mkdtemp ($template);
934 This command creates a temporary directory. The
935 C<template> parameter should be a full pathname for the
936 temporary directory name with the final six characters being
939 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX",
940 the second one being suitable for Windows filesystems.
942 The name of the temporary directory that was created
945 The temporary directory is created with mode 0700
946 and is owned by root.
948 The caller is responsible for deleting the temporary
949 directory and its contents after use.
951 See also: L<mkdtemp(3)>
953 =item $h->mkfifo ($mode, $path);
955 This call creates a FIFO (named pipe) called C<path> with
956 mode C<mode>. It is just a convenient wrapper around
959 =item $h->mkfs ($fstype, $device);
961 This creates a filesystem on C<device> (usually a partition
962 or LVM logical volume). The filesystem type is C<fstype>, for
965 =item $h->mknod ($mode, $devmajor, $devminor, $path);
967 This call creates block or character special devices, or
970 The C<mode> parameter should be the mode, using the standard
971 constants. C<devmajor> and C<devminor> are the
972 device major and minor numbers, only used when creating block
973 and character special devices.
975 =item $h->mknod_b ($mode, $devmajor, $devminor, $path);
977 This call creates a block device node called C<path> with
978 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
979 It is just a convenient wrapper around C<$h-E<gt>mknod>.
981 =item $h->mknod_c ($mode, $devmajor, $devminor, $path);
983 This call creates a char device node called C<path> with
984 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
985 It is just a convenient wrapper around C<$h-E<gt>mknod>.
987 =item $h->mkswap ($device);
989 Create a swap partition on C<device>.
991 =item $h->mkswap_L ($label, $device);
993 Create a swap partition on C<device> with label C<label>.
995 =item $h->mkswap_U ($uuid, $device);
997 Create a swap partition on C<device> with UUID C<uuid>.
999 =item $h->mount ($device, $mountpoint);
1001 Mount a guest disk at a position in the filesystem. Block devices
1002 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1003 the guest. If those block devices contain partitions, they will have
1004 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
1007 The rules are the same as for L<mount(2)>: A filesystem must
1008 first be mounted on C</> before others can be mounted. Other
1009 filesystems can only be mounted on directories which already
1012 The mounted filesystem is writable, if we have sufficient permissions
1013 on the underlying device.
1015 The filesystem options C<sync> and C<noatime> are set with this
1016 call, in order to improve reliability.
1018 =item $h->mount_loop ($file, $mountpoint);
1020 This command lets you mount C<file> (a filesystem image
1021 in a file) on a mount point. It is entirely equivalent to
1022 the command C<mount -o loop file mountpoint>.
1024 =item $h->mount_options ($options, $device, $mountpoint);
1026 This is the same as the C<$h-E<gt>mount> command, but it
1027 allows you to set the mount options as for the
1028 L<mount(8)> I<-o> flag.
1030 =item $h->mount_ro ($device, $mountpoint);
1032 This is the same as the C<$h-E<gt>mount> command, but it
1033 mounts the filesystem with the read-only (I<-o ro>) flag.
1035 =item $h->mount_vfs ($options, $vfstype, $device, $mountpoint);
1037 This is the same as the C<$h-E<gt>mount> command, but it
1038 allows you to set both the mount options and the vfstype
1039 as for the L<mount(8)> I<-o> and I<-t> flags.
1041 =item @devices = $h->mounts ();
1043 This returns the list of currently mounted filesystems. It returns
1044 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1046 Some internal mounts are not shown.
1048 =item $h->mv ($src, $dest);
1050 This moves a file from C<src> to C<dest> where C<dest> is
1051 either a destination filename or destination directory.
1053 =item $status = $h->ntfs_3g_probe ($rw, $device);
1055 This command runs the L<ntfs-3g.probe(8)> command which probes
1056 an NTFS C<device> for mountability. (Not all NTFS volumes can
1057 be mounted read-write, and some cannot be mounted at all).
1059 C<rw> is a boolean flag. Set it to true if you want to test
1060 if the volume can be mounted read-write. Set it to false if
1061 you want to test if the volume can be mounted read-only.
1063 The return value is an integer which C<0> if the operation
1064 would succeed, or some non-zero value documented in the
1065 L<ntfs-3g.probe(8)> manual page.
1067 =item $h->ping_daemon ();
1069 This is a test probe into the guestfs daemon running inside
1070 the qemu subprocess. Calling this function checks that the
1071 daemon responds to the ping message, without affecting the daemon
1072 or attached block device(s) in any other way.
1074 =item $h->pvcreate ($device);
1076 This creates an LVM physical volume on the named C<device>,
1077 where C<device> should usually be a partition name such
1080 =item $h->pvremove ($device);
1082 This wipes a physical volume C<device> so that LVM will no longer
1085 The implementation uses the C<pvremove> command which refuses to
1086 wipe physical volumes that contain any volume groups, so you have
1087 to remove those first.
1089 =item $h->pvresize ($device);
1091 This resizes (expands or shrinks) an existing LVM physical
1092 volume to match the new size of the underlying device.
1094 =item @physvols = $h->pvs ();
1096 List all the physical volumes detected. This is the equivalent
1097 of the L<pvs(8)> command.
1099 This returns a list of just the device names that contain
1100 PVs (eg. C</dev/sda2>).
1102 See also C<$h-E<gt>pvs_full>.
1104 =item @physvols = $h->pvs_full ();
1106 List all the physical volumes detected. This is the equivalent
1107 of the L<pvs(8)> command. The "full" version includes all fields.
1109 =item @lines = $h->read_lines ($path);
1111 Return the contents of the file named C<path>.
1113 The file contents are returned as a list of lines. Trailing
1114 C<LF> and C<CRLF> character sequences are I<not> returned.
1116 Note that this function cannot correctly handle binary files
1117 (specifically, files containing C<\0> character which is treated
1118 as end of line). For those you need to use the C<$h-E<gt>read_file>
1119 function which has a more complex interface.
1121 =item @entries = $h->readdir ($dir);
1123 This returns the list of directory entries in directory C<dir>.
1125 All entries in the directory are returned, including C<.> and
1126 C<..>. The entries are I<not> sorted, but returned in the same
1127 order as the underlying filesystem.
1129 This function is primarily intended for use by programs. To
1130 get a simple list of names, use C<$h-E<gt>ls>. To get a printable
1131 directory for human consumption, use C<$h-E<gt>ll>.
1133 =item $h->resize2fs ($device);
1135 This resizes an ext2 or ext3 filesystem to match the size of
1136 the underlying device.
1138 I<Note:> It is sometimes required that you run C<$h-E<gt>e2fsck_f>
1139 on the C<device> before calling this command. For unknown reasons
1140 C<resize2fs> sometimes gives an error about this and sometimes not.
1141 In any case, it is always safe to call C<$h-E<gt>e2fsck_f> before
1142 calling this function.
1144 =item $h->rm ($path);
1146 Remove the single file C<path>.
1148 =item $h->rm_rf ($path);
1150 Remove the file or directory C<path>, recursively removing the
1151 contents if its a directory. This is like the C<rm -rf> shell
1154 =item $h->rmdir ($path);
1156 Remove the single directory C<path>.
1158 =item $h->scrub_device ($device);
1160 This command writes patterns over C<device> to make data retrieval
1163 It is an interface to the L<scrub(1)> program. See that
1164 manual page for more details.
1166 B<This command is dangerous. Without careful use you
1167 can easily destroy all your data>.
1169 =item $h->scrub_file ($file);
1171 This command writes patterns over a file to make data retrieval
1174 The file is I<removed> after scrubbing.
1176 It is an interface to the L<scrub(1)> program. See that
1177 manual page for more details.
1179 =item $h->scrub_freespace ($dir);
1181 This command creates the directory C<dir> and then fills it
1182 with files until the filesystem is full, and scrubs the files
1183 as for C<$h-E<gt>scrub_file>, and deletes them.
1184 The intention is to scrub any free space on the partition
1187 It is an interface to the L<scrub(1)> program. See that
1188 manual page for more details.
1190 =item $h->set_append ($append);
1192 This function is used to add additional options to the
1193 guest kernel command line.
1195 The default is C<NULL> unless overridden by setting
1196 C<LIBGUESTFS_APPEND> environment variable.
1198 Setting C<append> to C<NULL> means I<no> additional options
1199 are passed (libguestfs always adds a few of its own).
1201 =item $h->set_autosync ($autosync);
1203 If C<autosync> is true, this enables autosync. Libguestfs will make a
1204 best effort attempt to run C<$h-E<gt>umount_all> followed by
1205 C<$h-E<gt>sync> when the handle is closed
1206 (also if the program exits without closing handles).
1208 This is disabled by default (except in guestfish where it is
1209 enabled by default).
1211 =item $h->set_busy ();
1213 This sets the state to C<BUSY>. This is only used when implementing
1214 actions using the low-level API.
1216 For more information on states, see L<guestfs(3)>.
1218 =item $h->set_e2label ($device, $label);
1220 This sets the ext2/3/4 filesystem label of the filesystem on
1221 C<device> to C<label>. Filesystem labels are limited to
1224 You can use either C<$h-E<gt>tune2fs_l> or C<$h-E<gt>get_e2label>
1225 to return the existing label on a filesystem.
1227 =item $h->set_e2uuid ($device, $uuid);
1229 This sets the ext2/3/4 filesystem UUID of the filesystem on
1230 C<device> to C<uuid>. The format of the UUID and alternatives
1231 such as C<clear>, C<random> and C<time> are described in the
1232 L<tune2fs(8)> manpage.
1234 You can use either C<$h-E<gt>tune2fs_l> or C<$h-E<gt>get_e2uuid>
1235 to return the existing UUID of a filesystem.
1237 =item $h->set_memsize ($memsize);
1239 This sets the memory size in megabytes allocated to the
1240 qemu subprocess. This only has any effect if called before
1243 You can also change this by setting the environment
1244 variable C<LIBGUESTFS_MEMSIZE> before the handle is
1247 For more information on the architecture of libguestfs,
1250 =item $h->set_path ($path);
1252 Set the path that libguestfs searches for kernel and initrd.img.
1254 The default is C<$libdir/guestfs> unless overridden by setting
1255 C<LIBGUESTFS_PATH> environment variable.
1257 Setting C<path> to C<NULL> restores the default path.
1259 =item $h->set_qemu ($qemu);
1261 Set the qemu binary that we will use.
1263 The default is chosen when the library was compiled by the
1266 You can also override this by setting the C<LIBGUESTFS_QEMU>
1267 environment variable.
1269 Setting C<qemu> to C<NULL> restores the default qemu binary.
1271 =item $h->set_ready ();
1273 This sets the state to C<READY>. This is only used when implementing
1274 actions using the low-level API.
1276 For more information on states, see L<guestfs(3)>.
1278 =item $h->set_verbose ($verbose);
1280 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
1282 Verbose messages are disabled unless the environment variable
1283 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
1285 =item $h->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
1287 This is a direct interface to the L<sfdisk(8)> program for creating
1288 partitions on block devices.
1290 C<device> should be a block device, for example C</dev/sda>.
1292 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1293 and sectors on the device, which are passed directly to sfdisk as
1294 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1295 of these, then the corresponding parameter is omitted. Usually for
1296 'large' disks, you can just pass C<0> for these, but for small
1297 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1298 out the right geometry and you will need to tell it.
1300 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1301 information refer to the L<sfdisk(8)> manpage.
1303 To create a single partition occupying the whole disk, you would
1304 pass C<lines> as a single element list, when the single element being
1305 the string C<,> (comma).
1307 See also: C<$h-E<gt>sfdisk_l>, C<$h-E<gt>sfdisk_N>
1309 B<This command is dangerous. Without careful use you
1310 can easily destroy all your data>.
1312 =item $h->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
1314 This runs L<sfdisk(8)> option to modify just the single
1315 partition C<n> (note: C<n> counts from 1).
1317 For other parameters, see C<$h-E<gt>sfdisk>. You should usually
1318 pass C<0> for the cyls/heads/sectors parameters.
1320 B<This command is dangerous. Without careful use you
1321 can easily destroy all your data>.
1323 =item $partitions = $h->sfdisk_disk_geometry ($device);
1325 This displays the disk geometry of C<device> read from the
1326 partition table. Especially in the case where the underlying
1327 block device has been resized, this can be different from the
1328 kernel's idea of the geometry (see C<$h-E<gt>sfdisk_kernel_geometry>).
1330 The result is in human-readable format, and not designed to
1333 =item $partitions = $h->sfdisk_kernel_geometry ($device);
1335 This displays the kernel's idea of the geometry of C<device>.
1337 The result is in human-readable format, and not designed to
1340 =item $partitions = $h->sfdisk_l ($device);
1342 This displays the partition table on C<device>, in the
1343 human-readable output of the L<sfdisk(8)> command. It is
1344 not intended to be parsed.
1346 =item $output = $h->sh ($command);
1348 This call runs a command from the guest filesystem via the
1351 This is like C<$h-E<gt>command>, but passes the command to:
1353 /bin/sh -c "command"
1355 Depending on the guest's shell, this usually results in
1356 wildcards being expanded, shell expressions being interpolated
1359 All the provisos about C<$h-E<gt>command> apply to this call.
1361 =item @lines = $h->sh_lines ($command);
1363 This is the same as C<$h-E<gt>sh>, but splits the result
1364 into a list of lines.
1366 See also: C<$h-E<gt>command_lines>
1368 =item $h->sleep ($secs);
1370 Sleep for C<secs> seconds.
1372 =item %statbuf = $h->stat ($path);
1374 Returns file information for the given C<path>.
1376 This is the same as the C<stat(2)> system call.
1378 =item %statbuf = $h->statvfs ($path);
1380 Returns file system statistics for any mounted file system.
1381 C<path> should be a file or directory in the mounted file system
1382 (typically it is the mount point itself, but it doesn't need to be).
1384 This is the same as the C<statvfs(2)> system call.
1386 =item @stringsout = $h->strings ($path);
1388 This runs the L<strings(1)> command on a file and returns
1389 the list of printable strings found.
1391 Because of the message protocol, there is a transfer limit
1392 of somewhere between 2MB and 4MB. To transfer large files you should use
1395 =item @stringsout = $h->strings_e ($encoding, $path);
1397 This is like the C<$h-E<gt>strings> command, but allows you to
1398 specify the encoding.
1400 See the L<strings(1)> manpage for the full list of encodings.
1402 Commonly useful encodings are C<l> (lower case L) which will
1403 show strings inside Windows/x86 files.
1405 The returned strings are transcoded to UTF-8.
1407 Because of the message protocol, there is a transfer limit
1408 of somewhere between 2MB and 4MB. To transfer large files you should use
1413 This syncs the disk, so that any writes are flushed through to the
1414 underlying disk image.
1416 You should always call this if you have modified a disk image, before
1419 =item @lines = $h->tail ($path);
1421 This command returns up to the last 10 lines of a file as
1424 Because of the message protocol, there is a transfer limit
1425 of somewhere between 2MB and 4MB. To transfer large files you should use
1428 =item @lines = $h->tail_n ($nrlines, $path);
1430 If the parameter C<nrlines> is a positive number, this returns the last
1431 C<nrlines> lines of the file C<path>.
1433 If the parameter C<nrlines> is a negative number, this returns lines
1434 from the file C<path>, starting with the C<-nrlines>th line.
1436 If the parameter C<nrlines> is zero, this returns an empty list.
1438 Because of the message protocol, there is a transfer limit
1439 of somewhere between 2MB and 4MB. To transfer large files you should use
1442 =item $h->tar_in ($tarfile, $directory);
1444 This command uploads and unpacks local file C<tarfile> (an
1445 I<uncompressed> tar file) into C<directory>.
1447 To upload a compressed tarball, use C<$h-E<gt>tgz_in>.
1449 =item $h->tar_out ($directory, $tarfile);
1451 This command packs the contents of C<directory> and downloads
1452 it to local file C<tarfile>.
1454 To download a compressed tarball, use C<$h-E<gt>tgz_out>.
1456 =item $h->tgz_in ($tarball, $directory);
1458 This command uploads and unpacks local file C<tarball> (a
1459 I<gzip compressed> tar file) into C<directory>.
1461 To upload an uncompressed tarball, use C<$h-E<gt>tar_in>.
1463 =item $h->tgz_out ($directory, $tarball);
1465 This command packs the contents of C<directory> and downloads
1466 it to local file C<tarball>.
1468 To download an uncompressed tarball, use C<$h-E<gt>tar_out>.
1470 =item $h->touch ($path);
1472 Touch acts like the L<touch(1)> command. It can be used to
1473 update the timestamps on a file, or, if the file does not exist,
1474 to create a new zero-length file.
1476 =item %superblock = $h->tune2fs_l ($device);
1478 This returns the contents of the ext2, ext3 or ext4 filesystem
1479 superblock on C<device>.
1481 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
1482 manpage for more details. The list of fields returned isn't
1483 clearly defined, and depends on both the version of C<tune2fs>
1484 that libguestfs was built against, and the filesystem itself.
1486 =item $oldmask = $h->umask ($mask);
1488 This function sets the mask used for creating new files and
1489 device nodes to C<mask & 0777>.
1491 Typical umask values would be C<022> which creates new files
1492 with permissions like "-rw-r--r--" or "-rwxr-xr-x", and
1493 C<002> which creates new files with permissions like
1494 "-rw-rw-r--" or "-rwxrwxr-x".
1496 The default umask is C<022>. This is important because it
1497 means that directories and device nodes will be created with
1498 C<0644> or C<0755> mode even if you specify C<0777>.
1500 See also L<umask(2)>, C<$h-E<gt>mknod>, C<$h-E<gt>mkdir>.
1502 This call returns the previous umask.
1504 =item $h->umount ($pathordevice);
1506 This unmounts the given filesystem. The filesystem may be
1507 specified either by its mountpoint (path) or the device which
1508 contains the filesystem.
1510 =item $h->umount_all ();
1512 This unmounts all mounted filesystems.
1514 Some internal mounts are not unmounted by this call.
1516 =item $h->upload ($filename, $remotefilename);
1518 Upload local file C<filename> to C<remotefilename> on the
1521 C<filename> can also be a named pipe.
1523 See also C<$h-E<gt>download>.
1525 =item $h->vg_activate ($activate, \@volgroups);
1527 This command activates or (if C<activate> is false) deactivates
1528 all logical volumes in the listed volume groups C<volgroups>.
1529 If activated, then they are made known to the
1530 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
1531 then those devices disappear.
1533 This command is the same as running C<vgchange -a y|n volgroups...>
1535 Note that if C<volgroups> is an empty list then B<all> volume groups
1536 are activated or deactivated.
1538 =item $h->vg_activate_all ($activate);
1540 This command activates or (if C<activate> is false) deactivates
1541 all logical volumes in all volume groups.
1542 If activated, then they are made known to the
1543 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
1544 then those devices disappear.
1546 This command is the same as running C<vgchange -a y|n>
1548 =item $h->vgcreate ($volgroup, \@physvols);
1550 This creates an LVM volume group called C<volgroup>
1551 from the non-empty list of physical volumes C<physvols>.
1553 =item $h->vgremove ($vgname);
1555 Remove an LVM volume group C<vgname>, (for example C<VG>).
1557 This also forcibly removes all logical volumes in the volume
1560 =item @volgroups = $h->vgs ();
1562 List all the volumes groups detected. This is the equivalent
1563 of the L<vgs(8)> command.
1565 This returns a list of just the volume group names that were
1566 detected (eg. C<VolGroup00>).
1568 See also C<$h-E<gt>vgs_full>.
1570 =item @volgroups = $h->vgs_full ();
1572 List all the volumes groups detected. This is the equivalent
1573 of the L<vgs(8)> command. The "full" version includes all fields.
1575 =item $h->wait_ready ();
1577 Internally libguestfs is implemented by running a virtual machine
1580 You should call this after C<$h-E<gt>launch> to wait for the launch
1583 =item $chars = $h->wc_c ($path);
1585 This command counts the characters in a file, using the
1586 C<wc -c> external command.
1588 =item $lines = $h->wc_l ($path);
1590 This command counts the lines in a file, using the
1591 C<wc -l> external command.
1593 =item $words = $h->wc_w ($path);
1595 This command counts the words in a file, using the
1596 C<wc -w> external command.
1598 =item $h->write_file ($path, $content, $size);
1600 This call creates a file called C<path>. The contents of the
1601 file is the string C<content> (which can contain any 8 bit data),
1602 with length C<size>.
1604 As a special case, if C<size> is C<0>
1605 then the length is calculated using C<strlen> (so in this case
1606 the content cannot contain embedded ASCII NULs).
1608 I<NB.> Owing to a bug, writing content containing ASCII NUL
1609 characters does I<not> work, even if the length is specified.
1610 We hope to resolve this bug in a future version. In the meantime
1611 use C<$h-E<gt>upload>.
1613 Because of the message protocol, there is a transfer limit
1614 of somewhere between 2MB and 4MB. To transfer large files you should use
1617 =item $h->zero ($device);
1619 This command writes zeroes over the first few blocks of C<device>.
1621 How many blocks are zeroed isn't specified (but it's I<not> enough
1622 to securely wipe the device). It should be sufficient to remove
1623 any partition tables, filesystem superblocks and so on.
1625 See also: C<$h-E<gt>scrub_device>.
1627 =item $h->zerofree ($device);
1629 This runs the I<zerofree> program on C<device>. This program
1630 claims to zero unused inodes and disk blocks on an ext2/3
1631 filesystem, thus making it possible to compress the filesystem
1634 You should B<not> run this program if the filesystem is
1637 It is possible that using this program can damage the filesystem
1638 or data on the filesystem.
1648 Copyright (C) 2009 Red Hat Inc.
1652 Please see the file COPYING.LIB for the full license.
1656 L<guestfs(3)>, L<guestfish(1)>.