1Sys::Guestfs(3) User Contributed Perl Documentation Sys::Guestfs(3)
2
6 Sys::Guestfs - Perl bindings for libguestfs
7
9 use Sys::Guestfs;
10 my $h = Sys::Guestfs->new ();
12 $h->add_drive_opts ('guest.img', format => 'raw');
13 $h->launch ();
14 $h->mount_options ('', '/dev/sda1', '/');
15 $h->touch ('/hello');
16 $h->sync ();
17
19 The "Sys::Guestfs" module provides a Perl XS binding to the libguestfs
20 API for examining and modifying virtual machine disk images.
21 Amongst the things this is good for: making batch configuration changes
23 to guests, getting disk used/free statistics (see also: virt-df),
24 migrating between virtualization systems (see also: virt-p2v),
25 performing partial backups, performing partial guest clones, cloning
26 guests and changing registry/UUID/hostname info, and much else besides.
27 Libguestfs uses Linux kernel and qemu code, and can access any type of
29 guest filesystem that Linux and qemu can, including but not limited to:
30 ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
31 schemes, qcow, qcow2, vmdk.
32 Libguestfs provides ways to enumerate guest storage (eg. partitions,
34 LVs, what filesystem is in each LV, etc.). It can also run commands in
35 the context of the guest. Also you can access filesystems over FUSE.
36 See also Sys::Guestfs::Lib(3) for a set of useful library functions for
38 using libguestfs from Perl, including integration with libvirt.
39
41 All errors turn into calls to "croak" (see Carp(3)).
42
44 $h = Sys::Guestfs->new ();
45 Create a new guestfs handle.
46 $h->close ();
48 Explicitly close the guestfs handle.
49 Note: You should not usually call this function. The handle will
51 be closed implicitly when its reference count goes to zero (eg.
52 when it goes out of scope or the program ends). This call is only
53 required in some exceptional cases, such as where the program may
54 contain cached references to the handle 'somewhere' and you really
55 have to have the close happen right away. After calling "close"
56 the program must not call any method (including "close") on the
57 handle (but the implicit call to "DESTROY" that happens when the
58 final reference is cleaned up is OK).
59 $h->set_progress_callback (\&cb);
61 Set the progress notification callback for this handle to the Perl
62 closure "cb".
63 "cb" will be called whenever a long-running operation generates a
65 progress notification message. The 4 parameters to the function
66 are: "proc_nr", "serial", "position" and "total".
67 You should carefully read the documentation for
69 "guestfs_set_progress_callback" in guestfs(3) before using this
70 function.
71 $h->clear_progress_callback ();
73 This removes any progress callback function associated with the
74 handle.
75 $h->add_cdrom ($filename);
77 This function adds a virtual CD-ROM disk image to the guest.
78 This is equivalent to the qemu parameter "-cdrom filename".
80 Notes:
82 · This call checks for the existence of "filename". This stops
84 you from specifying other types of drive which are supported by
85 qemu such as "nbd:" and "http:" URLs. To specify those, use
86 the general "$h->config" call instead.
87 · If you just want to add an ISO file (often you use this as an
89 efficient way to transfer large files into the guest), then you
90 should probably use "$h->add_drive_ro" instead.
91 This function is deprecated. In new code, use the "add_drive_opts"
93 call instead.
94 Deprecated functions will not be removed from the API, but the fact
96 that they are deprecated indicates that there are problems with
97 correct use of these functions.
98 $nrdisks = $h->add_domain ($dom [, libvirturi => $libvirturi] [,
100 readonly => $readonly] [, iface => $iface]);
101 This function adds the disk(s) attached to the named libvirt domain
102 "dom". It works by connecting to libvirt, requesting the domain
103 and domain XML from libvirt, parsing it for disks, and calling
104 "$h->add_drive_opts" on each one.
105 The number of disks added is returned. This operation is atomic:
107 if an error is returned, then no disks are added.
108 This function does some minimal checks to make sure the libvirt
110 domain is not running (unless "readonly" is true). In a future
111 version we will try to acquire the libvirt lock on each disk.
112 Disks must be accessible locally. This often means that adding
114 disks from a remote libvirt connection (see
115 <http://libvirt.org/remote.html>) will fail unless those disks are
116 accessible via the same device path locally too.
117 The optional "libvirturi" parameter sets the libvirt URI (see
119 <http://libvirt.org/uri.html>). If this is not set then we connect
120 to the default libvirt URI (or one set through an environment
121 variable, see the libvirt documentation for full details).
122 The other optional parameters are passed directly through to
124 "$h->add_drive_opts".
125 $h->add_drive ($filename);
127 This function is the equivalent of calling "$h->add_drive_opts"
128 with no optional parameters, so the disk is added writable, with
129 the format being detected automatically.
130 Automatic detection of the format opens you up to a potential
132 security hole when dealing with untrusted raw-format images. See
133 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
134 security hole. Therefore you should think about replacing calls to
135 this function with calls to "$h->add_drive_opts", and specifying
136 the format.
137 $h->add_drive_opts ($filename [, readonly => $readonly] [, format =>
139 $format] [, iface => $iface]);
140 This function adds a virtual machine disk image "filename" to
141 libguestfs. The first time you call this function, the disk
142 appears as "/dev/sda", the second time as "/dev/sdb", and so on.
143 You don't necessarily need to be root when using libguestfs.
145 However you obviously do need sufficient permissions to access the
146 filename for whatever operations you want to perform (ie. read
147 access if you just want to read the image or write access if you
148 want to modify the image).
149 This call checks that "filename" exists.
151 The optional arguments are:
153 "readonly"
155 If true then the image is treated as read-only. Writes are
156 still allowed, but they are stored in a temporary snapshot
157 overlay which is discarded at the end. The disk that you add
158 is not modified.
159 "format"
161 This forces the image format. If you omit this (or use
162 "$h->add_drive" or "$h->add_drive_ro") then the format is
163 automatically detected. Possible formats include "raw" and
164 "qcow2".
165 Automatic detection of the format opens you up to a potential
167 security hole when dealing with untrusted raw-format images.
168 See CVE-2010-3851 and RHBZ#642934. Specifying the format
169 closes this security hole.
170 "iface"
172 This rarely-used option lets you emulate the behaviour of the
173 deprecated "$h->add_drive_with_if" call (q.v.)
174 $h->add_drive_ro ($filename);
176 This function is the equivalent of calling "$h->add_drive_opts"
177 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
178 to 1, so the disk is added read-only, with the format being
179 detected automatically.
180 $h->add_drive_ro_with_if ($filename, $iface);
182 This is the same as "$h->add_drive_ro" but it allows you to specify
183 the QEMU interface emulation to use at run time.
184 This function is deprecated. In new code, use the "add_drive_opts"
186 call instead.
187 Deprecated functions will not be removed from the API, but the fact
189 that they are deprecated indicates that there are problems with
190 correct use of these functions.
191 $h->add_drive_with_if ($filename, $iface);
193 This is the same as "$h->add_drive" but it allows you to specify
194 the QEMU interface emulation to use at run time.
195 This function is deprecated. In new code, use the "add_drive_opts"
197 call instead.
198 Deprecated functions will not be removed from the API, but the fact
200 that they are deprecated indicates that there are problems with
201 correct use of these functions.
202 $h->aug_clear ($augpath);
204 Set the value associated with "path" to "NULL". This is the same
205 as the augtool(1) "clear" command.
206 $h->aug_close ();
208 Close the current Augeas handle and free up any resources used by
209 it. After calling this, you have to call "$h->aug_init" again
210 before you can use any other Augeas functions.
211 %nrnodescreated = $h->aug_defnode ($name, $expr, $val);
213 Defines a variable "name" whose value is the result of evaluating
214 "expr".
215 If "expr" evaluates to an empty nodeset, a node is created,
217 equivalent to calling "$h->aug_set" "expr", "value". "name" will
218 be the nodeset containing that single node.
219 On success this returns a pair containing the number of nodes in
221 the nodeset, and a boolean flag if a node was created.
222 $nrnodes = $h->aug_defvar ($name, $expr);
224 Defines an Augeas variable "name" whose value is the result of
225 evaluating "expr". If "expr" is NULL, then "name" is undefined.
226 On success this returns the number of nodes in "expr", or 0 if
228 "expr" evaluates to something which is not a nodeset.
229 $val = $h->aug_get ($augpath);
231 Look up the value associated with "path". If "path" matches
232 exactly one node, the "value" is returned.
233 $h->aug_init ($root, $flags);
235 Create a new Augeas handle for editing configuration files. If
236 there was any previous Augeas handle associated with this guestfs
237 session, then it is closed.
238 You must call this before using any other "$h->aug_*" commands.
240 "root" is the filesystem root. "root" must not be NULL, use "/"
242 instead.
243 The flags are the same as the flags defined in <augeas.h>, the
245 logical or of the following integers:
246 "AUG_SAVE_BACKUP" = 1
248 Keep the original file with a ".augsave" extension.
249 "AUG_SAVE_NEWFILE" = 2
251 Save changes into a file with extension ".augnew", and do not
252 overwrite original. Overrides "AUG_SAVE_BACKUP".
253 "AUG_TYPE_CHECK" = 4
255 Typecheck lenses.
256 This option is only useful when debugging Augeas lenses. Use
258 of this option may require additional memory for the libguestfs
259 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
260 environment variable or call "$h->set_memsize".
261 "AUG_NO_STDINC" = 8
263 Do not use standard load path for modules.
264 "AUG_SAVE_NOOP" = 16
266 Make save a no-op, just record what would have been changed.
267 "AUG_NO_LOAD" = 32
269 Do not load the tree in "$h->aug_init".
270 To close the handle, you can call "$h->aug_close".
272 To find out more about Augeas, see <http://augeas.net/>.
274 $h->aug_insert ($augpath, $label, $before);
276 Create a new sibling "label" for "path", inserting it into the tree
277 before or after "path" (depending on the boolean flag "before").
278 "path" must match exactly one existing node in the tree, and
280 "label" must be a label, ie. not contain "/", "*" or end with a
281 bracketed index "[N]".
282 $h->aug_load ();
284 Load files into the tree.
285 See "aug_load" in the Augeas documentation for the full gory
287 details.
288 @matches = $h->aug_ls ($augpath);
290 This is just a shortcut for listing "$h->aug_match" "path/*" and
291 sorting the resulting nodes into alphabetical order.
292 @matches = $h->aug_match ($augpath);
294 Returns a list of paths which match the path expression "path".
295 The returned paths are sufficiently qualified so that they match
296 exactly one node in the current tree.
297 $h->aug_mv ($src, $dest);
299 Move the node "src" to "dest". "src" must match exactly one node.
300 "dest" is overwritten if it exists.
301 $nrnodes = $h->aug_rm ($augpath);
303 Remove "path" and all of its children.
304 On success this returns the number of entries which were removed.
306 $h->aug_save ();
308 This writes all pending changes to disk.
309 The flags which were passed to "$h->aug_init" affect exactly how
311 files are saved.
312 $h->aug_set ($augpath, $val);
314 Set the value associated with "path" to "val".
315 In the Augeas API, it is possible to clear a node by setting the
317 value to NULL. Due to an oversight in the libguestfs API you
318 cannot do that with this call. Instead you must use the
319 "$h->aug_clear" call.
320 $h->available (\@groups);
322 This command is used to check the availability of some groups of
323 functionality in the appliance, which not all builds of the
324 libguestfs appliance will be able to provide.
325 The libguestfs groups, and the functions that those groups
327 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
328 also fetch this list at runtime by calling
329 "$h->available_all_groups".
330 The argument "groups" is a list of group names, eg: "["inotify",
332 "augeas"]" would check for the availability of the Linux inotify
333 functions and Augeas (configuration file editing) functions.
334 The command returns no error if all requested groups are available.
336 It fails with an error if one or more of the requested groups is
338 unavailable in the appliance.
339 If an unknown group name is included in the list of groups then an
341 error is always returned.
342 Notes:
344 · You must call "$h->launch" before calling this function.
346 The reason is because we don't know what groups are supported
348 by the appliance/daemon until it is running and can be queried.
349 · If a group of functions is available, this does not necessarily
351 mean that they will work. You still have to check for errors
352 when calling individual API functions even if they are
353 available.
354 · It is usually the job of distro packagers to build complete
356 functionality into the libguestfs appliance. Upstream
357 libguestfs, if built from source with all requirements
358 satisfied, will support everything.
359 · This call was added in version 1.0.80. In previous versions of
361 libguestfs all you could do would be to speculatively execute a
362 command to find out if the daemon implemented it. See also
363 "$h->version".
364 @groups = $h->available_all_groups ();
366 This command returns a list of all optional groups that this daemon
367 knows about. Note this returns both supported and unsupported
368 groups. To find out which ones the daemon can actually support you
369 have to call "$h->available" on each member of the returned list.
370 See also "$h->available" and "AVAILABILITY" in guestfs(3).
372 $h->base64_in ($base64file, $filename);
374 This command uploads base64-encoded data from "base64file" to
375 "filename".
376 $h->base64_out ($filename, $base64file);
378 This command downloads the contents of "filename", writing it out
379 to local file "base64file" encoded as base64.
380 $h->blockdev_flushbufs ($device);
382 This tells the kernel to flush internal buffers associated with
383 "device".
384 This uses the blockdev(8) command.
386 $blocksize = $h->blockdev_getbsz ($device);
388 This returns the block size of a device.
389 (Note this is different from both size in blocks and filesystem
391 block size).
392 This uses the blockdev(8) command.
394 $ro = $h->blockdev_getro ($device);
396 Returns a boolean indicating if the block device is read-only (true
397 if read-only, false if not).
398 This uses the blockdev(8) command.
400 $sizeinbytes = $h->blockdev_getsize64 ($device);
402 This returns the size of the device in bytes.
403 See also "$h->blockdev_getsz".
405 This uses the blockdev(8) command.
407 $sectorsize = $h->blockdev_getss ($device);
409 This returns the size of sectors on a block device. Usually 512,
410 but can be larger for modern devices.
411 (Note, this is not the size in sectors, use "$h->blockdev_getsz"
413 for that).
414 This uses the blockdev(8) command.
416 $sizeinsectors = $h->blockdev_getsz ($device);
418 This returns the size of the device in units of 512-byte sectors
419 (even if the sectorsize isn't 512 bytes ... weird).
420 See also "$h->blockdev_getss" for the real sector size of the
422 device, and "$h->blockdev_getsize64" for the more useful size in
423 bytes.
424 This uses the blockdev(8) command.
426 $h->blockdev_rereadpt ($device);
428 Reread the partition table on "device".
429 This uses the blockdev(8) command.
431 $h->blockdev_setbsz ($device, $blocksize);
433 This sets the block size of a device.
434 (Note this is different from both size in blocks and filesystem
436 block size).
437 This uses the blockdev(8) command.
439 $h->blockdev_setro ($device);
441 Sets the block device named "device" to read-only.
442 This uses the blockdev(8) command.
444 $h->blockdev_setrw ($device);
446 Sets the block device named "device" to read-write.
447 This uses the blockdev(8) command.
449 $rpath = $h->case_sensitive_path ($path);
451 This can be used to resolve case insensitive paths on a filesystem
452 which is case sensitive. The use case is to resolve paths which
453 you have read from Windows configuration files or the Windows
454 Registry, to the true path.
455 The command handles a peculiarity of the Linux ntfs-3g filesystem
457 driver (and probably others), which is that although the underlying
458 filesystem is case-insensitive, the driver exports the filesystem
459 to Linux as case-sensitive.
460 One consequence of this is that special directories such as
462 "c:\windows" may appear as "/WINDOWS" or "/windows" (or other
463 things) depending on the precise details of how they were created.
464 In Windows itself this would not be a problem.
465 Bug or feature? You decide:
467 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
468 <http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
469 This function resolves the true case of each element in the path
471 and returns the case-sensitive path.
472 Thus "$h->case_sensitive_path" ("/Windows/System32") might return
474 "/WINDOWS/system32" (the exact return value would depend on details
475 of how the directories were originally created under Windows).
476 Note: This function does not handle drive names, backslashes etc.
478 See also "$h->realpath".
480 $content = $h->cat ($path);
482 Return the contents of the file named "path".
483 Note that this function cannot correctly handle binary files
485 (specifically, files containing "\0" character which is treated as
486 end of string). For those you need to use the "$h->read_file" or
487 "$h->download" functions which have a more complex interface.
488 Because of the message protocol, there is a transfer limit of
490 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
491 guestfs(3).
492 $checksum = $h->checksum ($csumtype, $path);
494 This call computes the MD5, SHAx or CRC checksum of the file named
495 "path".
496 The type of checksum to compute is given by the "csumtype"
498 parameter which must have one of the following values:
499 "crc"
501 Compute the cyclic redundancy check (CRC) specified by POSIX
502 for the "cksum" command.
503 "md5"
505 Compute the MD5 hash (using the "md5sum" program).
506 "sha1"
508 Compute the SHA1 hash (using the "sha1sum" program).
509 "sha224"
511 Compute the SHA224 hash (using the "sha224sum" program).
512 "sha256"
514 Compute the SHA256 hash (using the "sha256sum" program).
515 "sha384"
517 Compute the SHA384 hash (using the "sha384sum" program).
518 "sha512"
520 Compute the SHA512 hash (using the "sha512sum" program).
521 The checksum is returned as a printable string.
523 To get the checksum for a device, use "$h->checksum_device".
525 To get the checksums for many files, use "$h->checksums_out".
527 $checksum = $h->checksum_device ($csumtype, $device);
529 This call computes the MD5, SHAx or CRC checksum of the contents of
530 the device named "device". For the types of checksums supported
531 see the "$h->checksum" command.
532 $h->checksums_out ($csumtype, $directory, $sumsfile);
534 This command computes the checksums of all regular files in
535 "directory" and then emits a list of those checksums to the local
536 output file "sumsfile".
537 This can be used for verifying the integrity of a virtual machine.
539 However to be properly secure you should pay attention to the
540 output of the checksum command (it uses the ones from GNU
541 coreutils). In particular when the filename is not printable,
542 coreutils uses a special backslash syntax. For more information,
543 see the GNU coreutils info file.
544 $h->chmod ($mode, $path);
546 Change the mode (permissions) of "path" to "mode". Only numeric
547 modes are supported.
548 Note: When using this command from guestfish, "mode" by default
550 would be decimal, unless you prefix it with 0 to get octal, ie. use
551 0700 not 700.
552 The mode actually set is affected by the umask.
554 $h->chown ($owner, $group, $path);
556 Change the file owner to "owner" and group to "group".
557 Only numeric uid and gid are supported. If you want to use names,
559 you will need to locate and parse the password file yourself
560 (Augeas support makes this relatively easy).
561 $output = $h->command (\@arguments);
563 This call runs a command from the guest filesystem. The filesystem
564 must be mounted, and must contain a compatible operating system
565 (ie. something Linux, with the same or compatible processor
566 architecture).
567 The single parameter is an argv-style list of arguments. The first
569 element is the name of the program to run. Subsequent elements are
570 parameters. The list must be non-empty (ie. must contain a program
571 name). Note that the command runs directly, and is not invoked via
572 the shell (see "$h->sh").
573 The return value is anything printed to stdout by the command.
575 If the command returns a non-zero exit status, then this function
577 returns an error message. The error message string is the content
578 of stderr from the command.
579 The $PATH environment variable will contain at least "/usr/bin" and
581 "/bin". If you require a program from another location, you should
582 provide the full path in the first parameter.
583 Shared libraries and data files required by the program must be
585 available on filesystems which are mounted in the correct places.
586 It is the caller's responsibility to ensure all filesystems that
587 are needed are mounted at the right locations.
588 Because of the message protocol, there is a transfer limit of
590 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
591 guestfs(3).
592 @lines = $h->command_lines (\@arguments);
594 This is the same as "$h->command", but splits the result into a
595 list of lines.
596 See also: "$h->sh_lines"
598 Because of the message protocol, there is a transfer limit of
600 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
601 guestfs(3).
602 $h->config ($qemuparam, $qemuvalue);
604 This can be used to add arbitrary qemu command line parameters of
605 the form "-param value". Actually it's not quite arbitrary - we
606 prevent you from setting some parameters which would interfere with
607 parameters that we use.
608 The first character of "param" string must be a "-" (dash).
610 "value" can be NULL.
612 $h->copy_size ($src, $dest, $size);
614 This command copies exactly "size" bytes from one source device or
615 file "src" to another destination device or file "dest".
616 Note this will fail if the source is too short or if the
618 destination is not large enough.
619 $h->cp ($src, $dest);
621 This copies a file from "src" to "dest" where "dest" is either a
622 destination filename or destination directory.
623 $h->cp_a ($src, $dest);
625 This copies a file or directory from "src" to "dest" recursively
626 using the "cp -a" command.
627 $h->dd ($src, $dest);
629 This command copies from one source device or file "src" to another
630 destination device or file "dest". Normally you would use this to
631 copy to or from a device or partition, for example to duplicate a
632 filesystem.
633 If the destination is a device, it must be as large or larger than
635 the source file or device, otherwise the copy will fail. This
636 command cannot do partial copies (see "$h->copy_size").
637 $output = $h->df ();
639 This command runs the "df" command to report disk space used.
640 This command is mostly useful for interactive sessions. It is not
642 intended that you try to parse the output string. Use
643 "$h->statvfs" from programs.
644 $output = $h->df_h ();
646 This command runs the "df -h" command to report disk space used in
647 human-readable format.
648 This command is mostly useful for interactive sessions. It is not
650 intended that you try to parse the output string. Use
651 "$h->statvfs" from programs.
652 $kmsgs = $h->dmesg ();
654 This returns the kernel messages ("dmesg" output) from the guest
655 kernel. This is sometimes useful for extended debugging of
656 problems.
657 Another way to get the same information is to enable verbose
659 messages with "$h->set_verbose" or by setting the environment
660 variable "LIBGUESTFS_DEBUG=1" before running the program.
661 $h->download ($remotefilename, $filename);
663 Download file "remotefilename" and save it as "filename" on the
664 local machine.
665 "filename" can also be a named pipe.
667 See also "$h->upload", "$h->cat".
669 $h->download_offset ($remotefilename, $filename, $offset, $size);
671 Download file "remotefilename" and save it as "filename" on the
672 local machine.
673 "remotefilename" is read for "size" bytes starting at "offset"
675 (this region must be within the file or device).
676 Note that there is no limit on the amount of data that can be
678 downloaded with this call, unlike with "$h->pread", and this call
679 always reads the full amount unless an error occurs.
680 See also "$h->download", "$h->pread".
682 $h->drop_caches ($whattodrop);
684 This instructs the guest kernel to drop its page cache, and/or
685 dentries and inode caches. The parameter "whattodrop" tells the
686 kernel what precisely to drop, see http://linux-mm.org/Drop_Caches
687 <http://linux-mm.org/Drop_Caches>
688 Setting "whattodrop" to 3 should drop everything.
690 This automatically calls sync(2) before the operation, so that the
692 maximum guest memory is freed.
693 $sizekb = $h->du ($path);
695 This command runs the "du -s" command to estimate file space usage
696 for "path".
697 "path" can be a file or a directory. If "path" is a directory then
699 the estimate includes the contents of the directory and all
700 subdirectories (recursively).
701 The result is the estimated size in kilobytes (ie. units of 1024
703 bytes).
704 $h->e2fsck_f ($device);
706 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
707 checker on "device", noninteractively ("-p"), even if the
708 filesystem appears to be clean ("-f").
709 This command is only needed because of "$h->resize2fs" (q.v.).
711 Normally you should use "$h->fsck".
712 $output = $h->echo_daemon (\@words);
714 This command concatenates the list of "words" passed with single
715 spaces between them and returns the resulting string.
716 You can use this command to test the connection through to the
718 daemon.
719 See also "$h->ping_daemon".
721 @lines = $h->egrep ($regex, $path);
723 This calls the external "egrep" program and returns the matching
724 lines.
725 Because of the message protocol, there is a transfer limit of
727 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
728 guestfs(3).
729 @lines = $h->egrepi ($regex, $path);
731 This calls the external "egrep -i" program and returns the matching
732 lines.
733 Because of the message protocol, there is a transfer limit of
735 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
736 guestfs(3).
737 $equality = $h->equal ($file1, $file2);
739 This compares the two files "file1" and "file2" and returns true if
740 their content is exactly equal, or false otherwise.
741 The external cmp(1) program is used for the comparison.
743 $existsflag = $h->exists ($path);
745 This returns "true" if and only if there is a file, directory (or
746 anything) with the given "path" name.
747 See also "$h->is_file", "$h->is_dir", "$h->stat".
749 $h->fallocate ($path, $len);
751 This command preallocates a file (containing zero bytes) named
752 "path" of size "len" bytes. If the file exists already, it is
753 overwritten.
754 Do not confuse this with the guestfish-specific "alloc" command
756 which allocates a file in the host and attaches it as a device.
757 This function is deprecated. In new code, use the "fallocate64"
759 call instead.
760 Deprecated functions will not be removed from the API, but the fact
762 that they are deprecated indicates that there are problems with
763 correct use of these functions.
764 $h->fallocate64 ($path, $len);
766 This command preallocates a file (containing zero bytes) named
767 "path" of size "len" bytes. If the file exists already, it is
768 overwritten.
769 Note that this call allocates disk blocks for the file. To create
771 a sparse file use "$h->truncate_size" instead.
772 The deprecated call "$h->fallocate" does the same, but owing to an
774 oversight it only allowed 30 bit lengths to be specified,
775 effectively limiting the maximum size of files created through that
776 call to 1GB.
777 Do not confuse this with the guestfish-specific "alloc" and
779 "sparse" commands which create a file in the host and attach it as
780 a device.
781 @lines = $h->fgrep ($pattern, $path);
783 This calls the external "fgrep" program and returns the matching
784 lines.
785 Because of the message protocol, there is a transfer limit of
787 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
788 guestfs(3).
789 @lines = $h->fgrepi ($pattern, $path);
791 This calls the external "fgrep -i" program and returns the matching
792 lines.
793 Because of the message protocol, there is a transfer limit of
795 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
796 guestfs(3).
797 $description = $h->file ($path);
799 This call uses the standard file(1) command to determine the type
800 or contents of the file.
801 This call will also transparently look inside various types of
803 compressed file.
804 The exact command which runs is "file -zb path". Note in
806 particular that the filename is not prepended to the output (the
807 "-b" option).
808 The output depends on the output of the underlying file(1) command
810 and it can change in future in ways beyond our control. In other
811 words, the output is not guaranteed by the ABI.
812 See also: file(1), "$h->vfs_type", "$h->lstat", "$h->is_file",
814 "$h->is_blockdev" (etc).
815 $arch = $h->file_architecture ($filename);
817 This detects the architecture of the binary "filename", and returns
818 it if known.
819 Currently defined architectures are:
821 "i386"
823 This string is returned for all 32 bit i386, i486, i586, i686
824 binaries irrespective of the precise processor requirements of
825 the binary.
826 "x86_64"
828 64 bit x86-64.
829 "sparc"
831 32 bit SPARC.
832 "sparc64"
834 64 bit SPARC V9 and above.
835 "ia64"
837 Intel Itanium.
838 "ppc"
840 32 bit Power PC.
841 "ppc64"
843 64 bit Power PC.
844 Libguestfs may return other architecture strings in future.
846 The function works on at least the following types of files:
848 · many types of Un*x and Linux binary
850 · many types of Un*x and Linux shared library
852 · Windows Win32 and Win64 binaries
854 · Windows Win32 and Win64 DLLs
856 Win32 binaries and DLLs return "i386".
858 Win64 binaries and DLLs return "x86_64".
860 · Linux kernel modules
862 · Linux new-style initrd images
864 · some non-x86 Linux vmlinuz kernels
866 What it can't do currently:
868 · static libraries (libfoo.a)
870 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
872 · x86 Linux vmlinuz kernels
874 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
876 32- and compressed code, and are horribly hard to unpack. If
877 you want to find the architecture of a kernel, use the
878 architecture of the associated initrd or kernel module(s)
879 instead.
880 $size = $h->filesize ($file);
882 This command returns the size of "file" in bytes.
883 To get other stats about a file, use "$h->stat", "$h->lstat",
885 "$h->is_dir", "$h->is_file" etc. To get the size of block devices,
886 use "$h->blockdev_getsize64".
887 $h->fill ($c, $len, $path);
889 This command creates a new file called "path". The initial content
890 of the file is "len" octets of "c", where "c" must be a number in
891 the range "[0..255]".
892 To fill a file with zero bytes (sparsely), it is much more
894 efficient to use "$h->truncate_size". To create a file with a
895 pattern of repeating bytes use "$h->fill_pattern".
896 $h->fill_pattern ($pattern, $len, $path);
898 This function is like "$h->fill" except that it creates a new file
899 of length "len" containing the repeating pattern of bytes in
900 "pattern". The pattern is truncated if necessary to ensure the
901 length of the file is exactly "len" bytes.
902 @names = $h->find ($directory);
904 This command lists out all files and directories, recursively,
905 starting at "directory". It is essentially equivalent to running
906 the shell command "find directory -print" but some post-processing
907 happens on the output, described below.
908 This returns a list of strings without any prefix. Thus if the
910 directory structure was:
911 /tmp/a
913 /tmp/b
914 /tmp/c/d
915 then the returned list from "$h->find" "/tmp" would be 4 elements:
917 a
919 b
920 c
921 c/d
922 If "directory" is not a directory, then this command returns an
924 error.
925 The returned list is sorted.
927 See also "$h->find0".
929 Because of the message protocol, there is a transfer limit of
931 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
932 guestfs(3).
933 $h->find0 ($directory, $files);
935 This command lists out all files and directories, recursively,
936 starting at "directory", placing the resulting list in the external
937 file called "files".
938 This command works the same way as "$h->find" with the following
940 exceptions:
941 · The resulting list is written to an external file.
943 · Items (filenames) in the result are separated by "\0"
945 characters. See find(1) option -print0.
946 · This command is not limited in the number of names that it can
948 return.
949 · The result list is not sorted.
951 $device = $h->findfs_label ($label);
953 This command searches the filesystems and returns the one which has
954 the given label. An error is returned if no such filesystem can be
955 found.
956 To find the label of a filesystem, use "$h->vfs_label".
958 $device = $h->findfs_uuid ($uuid);
960 This command searches the filesystems and returns the one which has
961 the given UUID. An error is returned if no such filesystem can be
962 found.
963 To find the UUID of a filesystem, use "$h->vfs_uuid".
965 $status = $h->fsck ($fstype, $device);
967 This runs the filesystem checker (fsck) on "device" which should
968 have filesystem type "fstype".
969 The returned integer is the status. See fsck(8) for the list of
971 status codes from "fsck".
972 Notes:
974 · Multiple status codes can be summed together.
976 · A non-zero return code can mean "success", for example if
978 errors have been corrected on the filesystem.
979 · Checking or repairing NTFS volumes is not supported (by linux-
981 ntfs).
982 This command is entirely equivalent to running "fsck -a -t fstype
984 device".
985 $append = $h->get_append ();
987 Return the additional kernel options which are added to the guest
988 kernel command line.
989 If "NULL" then no options are added.
991 $autosync = $h->get_autosync ();
993 Get the autosync flag.
994 $direct = $h->get_direct ();
996 Return the direct appliance mode flag.
997 $label = $h->get_e2label ($device);
999 This returns the ext2/3/4 filesystem label of the filesystem on
1000 "device".
1001 This function is deprecated. In new code, use the "vfs_label" call
1003 instead.
1004 Deprecated functions will not be removed from the API, but the fact
1006 that they are deprecated indicates that there are problems with
1007 correct use of these functions.
1008 $uuid = $h->get_e2uuid ($device);
1010 This returns the ext2/3/4 filesystem UUID of the filesystem on
1011 "device".
1012 This function is deprecated. In new code, use the "vfs_uuid" call
1014 instead.
1015 Deprecated functions will not be removed from the API, but the fact
1017 that they are deprecated indicates that there are problems with
1018 correct use of these functions.
1019 $memsize = $h->get_memsize ();
1021 This gets the memory size in megabytes allocated to the qemu
1022 subprocess.
1023 If "$h->set_memsize" was not called on this handle, and if
1025 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
1026 default value for memsize.
1027 For more information on the architecture of libguestfs, see
1029 guestfs(3).
1030 $network = $h->get_network ();
1032 This returns the enable network flag.
1033 $path = $h->get_path ();
1035 Return the current search path.
1036 This is always non-NULL. If it wasn't set already, then this will
1038 return the default path.
1039 $pid = $h->get_pid ();
1041 Return the process ID of the qemu subprocess. If there is no qemu
1042 subprocess, then this will return an error.
1043 This is an internal call used for debugging and testing.
1045 $qemu = $h->get_qemu ();
1047 Return the current qemu binary.
1048 This is always non-NULL. If it wasn't set already, then this will
1050 return the default qemu binary name.
1051 $recoveryproc = $h->get_recovery_proc ();
1053 Return the recovery process enabled flag.
1054 $selinux = $h->get_selinux ();
1056 This returns the current setting of the selinux flag which is
1057 passed to the appliance at boot time. See "$h->set_selinux".
1058 For more information on the architecture of libguestfs, see
1060 guestfs(3).
1061 $state = $h->get_state ();
1063 This returns the current state as an opaque integer. This is only
1064 useful for printing debug and internal error messages.
1065 For more information on states, see guestfs(3).
1067 $trace = $h->get_trace ();
1069 Return the command trace flag.
1070 $mask = $h->get_umask ();
1072 Return the current umask. By default the umask is 022 unless it
1073 has been set by calling "$h->umask".
1074 $verbose = $h->get_verbose ();
1076 This returns the verbose messages flag.
1077 $context = $h->getcon ();
1079 This gets the SELinux security context of the daemon.
1080 See the documentation about SELINUX in guestfs(3), and "$h->setcon"
1082 $xattr = $h->getxattr ($path, $name);
1084 Get a single extended attribute from file "path" named "name".
1085 This call follows symlinks. If you want to lookup an extended
1086 attribute for the symlink itself, use "$h->lgetxattr".
1087 Normally it is better to get all extended attributes from a file in
1089 one go by calling "$h->getxattrs". However some Linux filesystem
1090 implementations are buggy and do not provide a way to list out
1091 attributes. For these filesystems (notably ntfs-3g) you have to
1092 know the names of the extended attributes you want in advance and
1093 call this function.
1094 Extended attribute values are blobs of binary data. If there is no
1096 extended attribute named "name", this returns an error.
1097 See also: "$h->getxattrs", "$h->lgetxattr", attr(5).
1099 @xattrs = $h->getxattrs ($path);
1101 This call lists the extended attributes of the file or directory
1102 "path".
1103 At the system call level, this is a combination of the listxattr(2)
1105 and getxattr(2) calls.
1106 See also: "$h->lgetxattrs", attr(5).
1108 @paths = $h->glob_expand ($pattern);
1110 This command searches for all the pathnames matching "pattern"
1111 according to the wildcard expansion rules used by the shell.
1112 If no paths match, then this returns an empty list (note: not an
1114 error).
1115 It is just a wrapper around the C glob(3) function with flags
1117 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
1118 @lines = $h->grep ($regex, $path);
1120 This calls the external "grep" program and returns the matching
1121 lines.
1122 Because of the message protocol, there is a transfer limit of
1124 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1125 guestfs(3).
1126 @lines = $h->grepi ($regex, $path);
1128 This calls the external "grep -i" program and returns the matching
1129 lines.
1130 Because of the message protocol, there is a transfer limit of
1132 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1133 guestfs(3).
1134 $h->grub_install ($root, $device);
1136 This command installs GRUB 1 (the Grand Unified Bootloader) on
1137 "device", with the root directory being "root".
1138 Notes:
1140 · There is currently no way in the API to install grub2, which is
1142 used by most modern Linux guests. It is possible to run the
1143 grub2 command from the guest, although see the caveats in
1144 "RUNNING COMMANDS" in guestfs(3).
1145 · This uses "grub-install" from the host. Unfortunately grub is
1147 not always compatible with itself, so this only works in rather
1148 narrow circumstances. Careful testing with each guest version
1149 is advisable.
1150 · If grub-install reports the error "No suitable drive was found
1152 in the generated device map." it may be that you need to
1153 create a "/boot/grub/device.map" file first that contains the
1154 mapping between grub device names and Linux device names. It
1155 is usually sufficient to create a file containing:
1156 (hd0) /dev/vda
1158 replacing "/dev/vda" with the name of the installation device.
1160 @lines = $h->head ($path);
1162 This command returns up to the first 10 lines of a file as a list
1163 of strings.
1164 Because of the message protocol, there is a transfer limit of
1166 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1167 guestfs(3).
1168 @lines = $h->head_n ($nrlines, $path);
1170 If the parameter "nrlines" is a positive number, this returns the
1171 first "nrlines" lines of the file "path".
1172 If the parameter "nrlines" is a negative number, this returns lines
1174 from the file "path", excluding the last "nrlines" lines.
1175 If the parameter "nrlines" is zero, this returns an empty list.
1177 Because of the message protocol, there is a transfer limit of
1179 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1180 guestfs(3).
1181 $dump = $h->hexdump ($path);
1183 This runs "hexdump -C" on the given "path". The result is the
1184 human-readable, canonical hex dump of the file.
1185 Because of the message protocol, there is a transfer limit of
1187 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1188 guestfs(3).
1189 $content = $h->initrd_cat ($initrdpath, $filename);
1191 This command unpacks the file "filename" from the initrd file
1192 called "initrdpath". The filename must be given without the
1193 initial "/" character.
1194 For example, in guestfish you could use the following command to
1196 examine the boot script (usually called "/init") contained in a
1197 Linux initrd or initramfs image:
1198 initrd-cat /boot/initrd-<version>.img init
1200 See also "$h->initrd_list".
1202 Because of the message protocol, there is a transfer limit of
1204 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1205 guestfs(3).
1206 @filenames = $h->initrd_list ($path);
1208 This command lists out files contained in an initrd.
1209 The files are listed without any initial "/" character. The files
1211 are listed in the order they appear (not necessarily alphabetical).
1212 Directory names are listed as separate items.
1213 Old Linux kernels (2.4 and earlier) used a compressed ext2
1215 filesystem as initrd. We only support the newer initramfs format
1216 (compressed cpio files).
1217 $wd = $h->inotify_add_watch ($path, $mask);
1219 Watch "path" for the events listed in "mask".
1220 Note that if "path" is a directory then events within that
1222 directory are watched, but this does not happen recursively (in
1223 subdirectories).
1224 Note for non-C or non-Linux callers: the inotify events are defined
1226 by the Linux kernel ABI and are listed in
1227 "/usr/include/sys/inotify.h".
1228 $h->inotify_close ();
1230 This closes the inotify handle which was previously opened by
1231 inotify_init. It removes all watches, throws away any pending
1232 events, and deallocates all resources.
1233 @paths = $h->inotify_files ();
1235 This function is a helpful wrapper around "$h->inotify_read" which
1236 just returns a list of pathnames of objects that were touched. The
1237 returned pathnames are sorted and deduplicated.
1238 $h->inotify_init ($maxevents);
1240 This command creates a new inotify handle. The inotify subsystem
1241 can be used to notify events which happen to objects in the guest
1242 filesystem.
1243 "maxevents" is the maximum number of events which will be queued up
1245 between calls to "$h->inotify_read" or "$h->inotify_files". If
1246 this is passed as 0, then the kernel (or previously set) default is
1247 used. For Linux 2.6.29 the default was 16384 events. Beyond this
1248 limit, the kernel throws away events, but records the fact that it
1249 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
1250 structure list (see "$h->inotify_read").
1251 Before any events are generated, you have to add some watches to
1253 the internal watch list. See: "$h->inotify_add_watch",
1254 "$h->inotify_rm_watch" and "$h->inotify_watch_all".
1255 Queued up events should be read periodically by calling
1257 "$h->inotify_read" (or "$h->inotify_files" which is just a helpful
1258 wrapper around "$h->inotify_read"). If you don't read the events
1259 out often enough then you risk the internal queue overflowing.
1260 The handle should be closed after use by calling
1262 "$h->inotify_close". This also removes any watches automatically.
1263 See also inotify(7) for an overview of the inotify interface as
1265 exposed by the Linux kernel, which is roughly what we expose via
1266 libguestfs. Note that there is one global inotify handle per
1267 libguestfs instance.
1268 @events = $h->inotify_read ();
1270 Return the complete queue of events that have happened since the
1271 previous read call.
1272 If no events have happened, this returns an empty list.
1274 Note: In order to make sure that all events have been read, you
1276 must call this function repeatedly until it returns an empty list.
1277 The reason is that the call will read events up to the maximum
1278 appliance-to-host message size and leave remaining events in the
1279 queue.
1280 $h->inotify_rm_watch ($wd);
1282 Remove a previously defined inotify watch. See
1283 "$h->inotify_add_watch".
1284 $arch = $h->inspect_get_arch ($root);
1286 This function should only be called with a root device string as
1287 returned by "$h->inspect_os".
1288 This returns the architecture of the inspected operating system.
1290 The possible return values are listed under
1291 "$h->file_architecture".
1292 If the architecture could not be determined, then the string
1294 "unknown" is returned.
1295 Please read "INSPECTION" in guestfs(3) for more details.
1297 $distro = $h->inspect_get_distro ($root);
1299 This function should only be called with a root device string as
1300 returned by "$h->inspect_os".
1301 This returns the distro (distribution) of the inspected operating
1303 system.
1304 Currently defined distros are:
1306 "archlinux"
1308 Arch Linux.
1309 "debian"
1311 Debian.
1312 "fedora"
1314 Fedora.
1315 "gentoo"
1317 Gentoo.
1318 "linuxmint"
1320 Linux Mint.
1321 "mandriva"
1323 Mandriva.
1324 "meego"
1326 MeeGo.
1327 "pardus"
1329 Pardus.
1330 "redhat-based"
1332 Some Red Hat-derived distro.
1333 "rhel"
1335 Red Hat Enterprise Linux and some derivatives.
1336 "ubuntu"
1338 Ubuntu.
1339 "unknown"
1341 The distro could not be determined.
1342 "windows"
1344 Windows does not have distributions. This string is returned
1345 if the OS type is Windows.
1346 Future versions of libguestfs may return other strings here. The
1348 caller should be prepared to handle any string.
1349 Please read "INSPECTION" in guestfs(3) for more details.
1351 @filesystems = $h->inspect_get_filesystems ($root);
1353 This function should only be called with a root device string as
1354 returned by "$h->inspect_os".
1355 This returns a list of all the filesystems that we think are
1357 associated with this operating system. This includes the root
1358 filesystem, other ordinary filesystems, and non-mounted devices
1359 like swap partitions.
1360 In the case of a multi-boot virtual machine, it is possible for a
1362 filesystem to be shared between operating systems.
1363 Please read "INSPECTION" in guestfs(3) for more details. See also
1365 "$h->inspect_get_mountpoints".
1366 $hostname = $h->inspect_get_hostname ($root);
1368 This function should only be called with a root device string as
1369 returned by "$h->inspect_os".
1370 This function returns the hostname of the operating system as found
1372 by inspection of the guest's configuration files.
1373 If the hostname could not be determined, then the string "unknown"
1375 is returned.
1376 Please read "INSPECTION" in guestfs(3) for more details.
1378 $major = $h->inspect_get_major_version ($root);
1380 This function should only be called with a root device string as
1381 returned by "$h->inspect_os".
1382 This returns the major version number of the inspected operating
1384 system.
1385 Windows uses a consistent versioning scheme which is not reflected
1387 in the popular public names used by the operating system. Notably
1388 the operating system known as "Windows 7" is really version 6.1
1389 (ie. major = 6, minor = 1). You can find out the real versions
1390 corresponding to releases of Windows by consulting Wikipedia or
1391 MSDN.
1392 If the version could not be determined, then 0 is returned.
1394 Please read "INSPECTION" in guestfs(3) for more details.
1396 $minor = $h->inspect_get_minor_version ($root);
1398 This function should only be called with a root device string as
1399 returned by "$h->inspect_os".
1400 This returns the minor version number of the inspected operating
1402 system.
1403 If the version could not be determined, then 0 is returned.
1405 Please read "INSPECTION" in guestfs(3) for more details. See also
1407 "$h->inspect_get_major_version".
1408 %mountpoints = $h->inspect_get_mountpoints ($root);
1410 This function should only be called with a root device string as
1411 returned by "$h->inspect_os".
1412 This returns a hash of where we think the filesystems associated
1414 with this operating system should be mounted. Callers should note
1415 that this is at best an educated guess made by reading
1416 configuration files such as "/etc/fstab". In particular note that
1417 this may return filesystems which are non-existent or not mountable
1418 and callers should be prepared to handle or ignore failures if they
1419 try to mount them.
1420 Each element in the returned hashtable has a key which is the path
1422 of the mountpoint (eg. "/boot") and a value which is the filesystem
1423 that would be mounted there (eg. "/dev/sda1").
1424 Non-mounted devices such as swap devices are not returned in this
1426 list.
1427 Please read "INSPECTION" in guestfs(3) for more details. See also
1429 "$h->inspect_get_filesystems".
1430 $packageformat = $h->inspect_get_package_format ($root);
1432 This function should only be called with a root device string as
1433 returned by "$h->inspect_os".
1434 This function and "$h->inspect_get_package_management" return the
1436 package format and package management tool used by the inspected
1437 operating system. For example for Fedora these functions would
1438 return "rpm" (package format) and "yum" (package management).
1439 This returns the string "unknown" if we could not determine the
1441 package format or if the operating system does not have a real
1442 packaging system (eg. Windows).
1443 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman".
1445 Future versions of libguestfs may return other strings.
1446 Please read "INSPECTION" in guestfs(3) for more details.
1448 $packagemanagement = $h->inspect_get_package_management ($root);
1450 This function should only be called with a root device string as
1451 returned by "$h->inspect_os".
1452 "$h->inspect_get_package_format" and this function return the
1454 package format and package management tool used by the inspected
1455 operating system. For example for Fedora these functions would
1456 return "rpm" (package format) and "yum" (package management).
1457 This returns the string "unknown" if we could not determine the
1459 package management tool or if the operating system does not have a
1460 real packaging system (eg. Windows).
1461 Possible strings include: "yum", "up2date", "apt" (for all Debian
1463 derivatives), "portage", "pisi", "pacman", "urpmi". Future
1464 versions of libguestfs may return other strings.
1465 Please read "INSPECTION" in guestfs(3) for more details.
1467 $product = $h->inspect_get_product_name ($root);
1469 This function should only be called with a root device string as
1470 returned by "$h->inspect_os".
1471 This returns the product name of the inspected operating system.
1473 The product name is generally some freeform string which can be
1474 displayed to the user, but should not be parsed by programs.
1475 If the product name could not be determined, then the string
1477 "unknown" is returned.
1478 Please read "INSPECTION" in guestfs(3) for more details.
1480 @roots = $h->inspect_get_roots ();
1482 This function is a convenient way to get the list of root devices,
1483 as returned from a previous call to "$h->inspect_os", but without
1484 redoing the whole inspection process.
1485 This returns an empty list if either no root devices were found or
1487 the caller has not called "$h->inspect_os".
1488 Please read "INSPECTION" in guestfs(3) for more details.
1490 $name = $h->inspect_get_type ($root);
1492 This function should only be called with a root device string as
1493 returned by "$h->inspect_os".
1494 This returns the type of the inspected operating system. Currently
1496 defined types are:
1497 "linux"
1499 Any Linux-based operating system.
1500 "windows"
1502 Any Microsoft Windows operating system.
1503 "freebsd"
1505 FreeBSD.
1506 "unknown"
1508 The operating system type could not be determined.
1509 Future versions of libguestfs may return other strings here. The
1511 caller should be prepared to handle any string.
1512 Please read "INSPECTION" in guestfs(3) for more details.
1514 $systemroot = $h->inspect_get_windows_systemroot ($root);
1516 This function should only be called with a root device string as
1517 returned by "$h->inspect_os".
1518 This returns the Windows systemroot of the inspected guest. The
1520 systemroot is a directory path such as "/WINDOWS".
1521 This call assumes that the guest is Windows and that the systemroot
1523 could be determined by inspection. If this is not the case then an
1524 error is returned.
1525 Please read "INSPECTION" in guestfs(3) for more details.
1527 @applications = $h->inspect_list_applications ($root);
1529 This function should only be called with a root device string as
1530 returned by "$h->inspect_os".
1531 Return the list of applications installed in the operating system.
1533 Note: This call works differently from other parts of the
1535 inspection API. You have to call "$h->inspect_os", then
1536 "$h->inspect_get_mountpoints", then mount up the disks, before
1537 calling this. Listing applications is a significantly more
1538 difficult operation which requires access to the full filesystem.
1539 Also note that unlike the other "$h->inspect_get_*" calls which are
1540 just returning data cached in the libguestfs handle, this call
1541 actually reads parts of the mounted filesystems during the call.
1542 This returns an empty list if the inspection code was not able to
1544 determine the list of applications.
1545 The application structure contains the following fields:
1547 "app_name"
1549 The name of the application. For Red Hat-derived and Debian-
1550 derived Linux guests, this is the package name.
1551 "app_display_name"
1553 The display name of the application, sometimes localized to the
1554 install language of the guest operating system.
1555 If unavailable this is returned as an empty string "". Callers
1557 needing to display something can use "app_name" instead.
1558 "app_epoch"
1560 For package managers which use epochs, this contains the epoch
1561 of the package (an integer). If unavailable, this is returned
1562 as 0.
1563 "app_version"
1565 The version string of the application or package. If
1566 unavailable this is returned as an empty string "".
1567 "app_release"
1569 The release string of the application or package, for package
1570 managers that use this. If unavailable this is returned as an
1571 empty string "".
1572 "app_install_path"
1574 The installation path of the application (on operating systems
1575 such as Windows which use installation paths). This path is in
1576 the format used by the guest operating system, it is not a
1577 libguestfs path.
1578 If unavailable this is returned as an empty string "".
1580 "app_trans_path"
1582 The install path translated into a libguestfs path. If
1583 unavailable this is returned as an empty string "".
1584 "app_publisher"
1586 The name of the publisher of the application, for package
1587 managers that use this. If unavailable this is returned as an
1588 empty string "".
1589 "app_url"
1591 The URL (eg. upstream URL) of the application. If unavailable
1592 this is returned as an empty string "".
1593 "app_source_package"
1595 For packaging systems which support this, the name of the
1596 source package. If unavailable this is returned as an empty
1597 string "".
1598 "app_summary"
1600 A short (usually one line) description of the application or
1601 package. If unavailable this is returned as an empty string
1602 "".
1603 "app_description"
1605 A longer description of the application or package. If
1606 unavailable this is returned as an empty string "".
1607 Please read "INSPECTION" in guestfs(3) for more details.
1609 @roots = $h->inspect_os ();
1611 This function uses other libguestfs functions and certain
1612 heuristics to inspect the disk(s) (usually disks belonging to a
1613 virtual machine), looking for operating systems.
1614 The list returned is empty if no operating systems were found.
1616 If one operating system was found, then this returns a list with a
1618 single element, which is the name of the root filesystem of this
1619 operating system. It is also possible for this function to return
1620 a list containing more than one element, indicating a dual-boot or
1621 multi-boot virtual machine, with each element being the root
1622 filesystem of one of the operating systems.
1623 You can pass the root string(s) returned to other
1625 "$h->inspect_get_*" functions in order to query further information
1626 about each operating system, such as the name and version.
1627 This function uses other libguestfs features such as "$h->mount_ro"
1629 and "$h->umount_all" in order to mount and unmount filesystems and
1630 look at the contents. This should be called with no disks
1631 currently mounted. The function may also use Augeas, so any
1632 existing Augeas handle will be closed.
1633 This function cannot decrypt encrypted disks. The caller must do
1635 that first (supplying the necessary keys) if the disk is encrypted.
1636 Please read "INSPECTION" in guestfs(3) for more details.
1638 See also "$h->list_filesystems".
1640 $flag = $h->is_blockdev ($path);
1642 This returns "true" if and only if there is a block device with the
1643 given "path" name.
1644 See also "$h->stat".
1646 $busy = $h->is_busy ();
1648 This returns true iff this handle is busy processing a command (in
1649 the "BUSY" state).
1650 For more information on states, see guestfs(3).
1652 $flag = $h->is_chardev ($path);
1654 This returns "true" if and only if there is a character device with
1655 the given "path" name.
1656 See also "$h->stat".
1658 $config = $h->is_config ();
1660 This returns true iff this handle is being configured (in the
1661 "CONFIG" state).
1662 For more information on states, see guestfs(3).
1664 $dirflag = $h->is_dir ($path);
1666 This returns "true" if and only if there is a directory with the
1667 given "path" name. Note that it returns false for other objects
1668 like files.
1669 See also "$h->stat".
1671 $flag = $h->is_fifo ($path);
1673 This returns "true" if and only if there is a FIFO (named pipe)
1674 with the given "path" name.
1675 See also "$h->stat".
1677 $fileflag = $h->is_file ($path);
1679 This returns "true" if and only if there is a regular file with the
1680 given "path" name. Note that it returns false for other objects
1681 like directories.
1682 See also "$h->stat".
1684 $launching = $h->is_launching ();
1686 This returns true iff this handle is launching the subprocess (in
1687 the "LAUNCHING" state).
1688 For more information on states, see guestfs(3).
1690 $lvflag = $h->is_lv ($device);
1692 This command tests whether "device" is a logical volume, and
1693 returns true iff this is the case.
1694 $ready = $h->is_ready ();
1696 This returns true iff this handle is ready to accept commands (in
1697 the "READY" state).
1698 For more information on states, see guestfs(3).
1700 $flag = $h->is_socket ($path);
1702 This returns "true" if and only if there is a Unix domain socket
1703 with the given "path" name.
1704 See also "$h->stat".
1706 $flag = $h->is_symlink ($path);
1708 This returns "true" if and only if there is a symbolic link with
1709 the given "path" name.
1710 See also "$h->stat".
1712 $h->kill_subprocess ();
1714 This kills the qemu subprocess. You should never need to call
1715 this.
1716 $h->launch ();
1718 Internally libguestfs is implemented by running a virtual machine
1719 using qemu(1).
1720 You should call this after configuring the handle (eg. adding
1722 drives) but before performing any actions.
1723 $h->lchown ($owner, $group, $path);
1725 Change the file owner to "owner" and group to "group". This is
1726 like "$h->chown" but if "path" is a symlink then the link itself is
1727 changed, not the target.
1728 Only numeric uid and gid are supported. If you want to use names,
1730 you will need to locate and parse the password file yourself
1731 (Augeas support makes this relatively easy).
1732 $xattr = $h->lgetxattr ($path, $name);
1734 Get a single extended attribute from file "path" named "name". If
1735 "path" is a symlink, then this call returns an extended attribute
1736 from the symlink.
1737 Normally it is better to get all extended attributes from a file in
1739 one go by calling "$h->getxattrs". However some Linux filesystem
1740 implementations are buggy and do not provide a way to list out
1741 attributes. For these filesystems (notably ntfs-3g) you have to
1742 know the names of the extended attributes you want in advance and
1743 call this function.
1744 Extended attribute values are blobs of binary data. If there is no
1746 extended attribute named "name", this returns an error.
1747 See also: "$h->lgetxattrs", "$h->getxattr", attr(5).
1749 @xattrs = $h->lgetxattrs ($path);
1751 This is the same as "$h->getxattrs", but if "path" is a symbolic
1752 link, then it returns the extended attributes of the link itself.
1753 @devices = $h->list_devices ();
1755 List all the block devices.
1756 The full block device names are returned, eg. "/dev/sda".
1758 See also "$h->list_filesystems".
1760 %fses = $h->list_filesystems ();
1762 This inspection command looks for filesystems on partitions, block
1763 devices and logical volumes, returning a list of devices containing
1764 filesystems and their type.
1765 The return value is a hash, where the keys are the devices
1767 containing filesystems, and the values are the filesystem types.
1768 For example:
1769 "/dev/sda1" => "ntfs"
1771 "/dev/sda2" => "ext2"
1772 "/dev/vg_guest/lv_root" => "ext4"
1773 "/dev/vg_guest/lv_swap" => "swap"
1774 The value can have the special value "unknown", meaning the content
1776 of the device is undetermined or empty. "swap" means a Linux swap
1777 partition.
1778 This command runs other libguestfs commands, which might include
1780 "$h->mount" and "$h->umount", and therefore you should use this
1781 soon after launch and only when nothing is mounted.
1782 Not all of the filesystems returned will be mountable. In
1784 particular, swap partitions are returned in the list. Also this
1785 command does not check that each filesystem found is valid and
1786 mountable, and some filesystems might be mountable but require
1787 special options. Filesystems may not all belong to a single
1788 logical operating system (use "$h->inspect_os" to look for OSes).
1789 @partitions = $h->list_partitions ();
1791 List all the partitions detected on all block devices.
1792 The full partition device names are returned, eg. "/dev/sda1"
1794 This does not return logical volumes. For that you will need to
1796 call "$h->lvs".
1797 See also "$h->list_filesystems".
1799 $listing = $h->ll ($directory);
1801 List the files in "directory" (relative to the root directory,
1802 there is no cwd) in the format of 'ls -la'.
1803 This command is mostly useful for interactive sessions. It is not
1805 intended that you try to parse the output string.
1806 $h->ln ($target, $linkname);
1808 This command creates a hard link using the "ln" command.
1809 $h->ln_f ($target, $linkname);
1811 This command creates a hard link using the "ln -f" command. The
1812 "-f" option removes the link ("linkname") if it exists already.
1813 $h->ln_s ($target, $linkname);
1815 This command creates a symbolic link using the "ln -s" command.
1816 $h->ln_sf ($target, $linkname);
1818 This command creates a symbolic link using the "ln -sf" command,
1819 The "-f" option removes the link ("linkname") if it exists already.
1820 $h->lremovexattr ($xattr, $path);
1822 This is the same as "$h->removexattr", but if "path" is a symbolic
1823 link, then it removes an extended attribute of the link itself.
1824 @listing = $h->ls ($directory);
1826 List the files in "directory" (relative to the root directory,
1827 there is no cwd). The '.' and '..' entries are not returned, but
1828 hidden files are shown.
1829 This command is mostly useful for interactive sessions. Programs
1831 should probably use "$h->readdir" instead.
1832 $h->lsetxattr ($xattr, $val, $vallen, $path);
1834 This is the same as "$h->setxattr", but if "path" is a symbolic
1835 link, then it sets an extended attribute of the link itself.
1836 %statbuf = $h->lstat ($path);
1838 Returns file information for the given "path".
1839 This is the same as "$h->stat" except that if "path" is a symbolic
1841 link, then the link is stat-ed, not the file it refers to.
1842 This is the same as the lstat(2) system call.
1844 @statbufs = $h->lstatlist ($path, \@names);
1846 This call allows you to perform the "$h->lstat" operation on
1847 multiple files, where all files are in the directory "path".
1848 "names" is the list of files from this directory.
1849 On return you get a list of stat structs, with a one-to-one
1851 correspondence to the "names" list. If any name did not exist or
1852 could not be lstat'd, then the "ino" field of that structure is set
1853 to "-1".
1854 This call is intended for programs that want to efficiently list a
1856 directory contents without making many round-trips. See also
1857 "$h->lxattrlist" for a similarly efficient call for getting
1858 extended attributes. Very long directory listings might cause the
1859 protocol message size to be exceeded, causing this call to fail.
1860 The caller must split up such requests into smaller groups of
1861 names.
1862 $h->luks_add_key ($device, $key, $newkey, $keyslot);
1864 This command adds a new key on LUKS device "device". "key" is any
1865 existing key, and is used to access the device. "newkey" is the
1866 new key to add. "keyslot" is the key slot that will be replaced.
1867 Note that if "keyslot" already contains a key, then this command
1869 will fail. You have to use "$h->luks_kill_slot" first to remove
1870 that key.
1871 $h->luks_close ($device);
1873 This closes a LUKS device that was created earlier by
1874 "$h->luks_open" or "$h->luks_open_ro". The "device" parameter must
1875 be the name of the LUKS mapping device (ie. "/dev/mapper/mapname")
1876 and not the name of the underlying block device.
1877 $h->luks_format ($device, $key, $keyslot);
1879 This command erases existing data on "device" and formats the
1880 device as a LUKS encrypted device. "key" is the initial key, which
1881 is added to key slot "slot". (LUKS supports 8 key slots, numbered
1882 0-7).
1883 This command is dangerous. Without careful use you can easily
1885 destroy all your data.
1886 $h->luks_format_cipher ($device, $key, $keyslot, $cipher);
1888 This command is the same as "$h->luks_format" but it also allows
1889 you to set the "cipher" used.
1890 This command is dangerous. Without careful use you can easily
1892 destroy all your data.
1893 $h->luks_kill_slot ($device, $key, $keyslot);
1895 This command deletes the key in key slot "keyslot" from the
1896 encrypted LUKS device "device". "key" must be one of the other
1897 keys.
1898 $h->luks_open ($device, $key, $mapname);
1900 This command opens a block device which has been encrypted
1901 according to the Linux Unified Key Setup (LUKS) standard.
1902 "device" is the encrypted block device or partition.
1904 The caller must supply one of the keys associated with the LUKS
1906 block device, in the "key" parameter.
1907 This creates a new block device called "/dev/mapper/mapname".
1909 Reads and writes to this block device are decrypted from and
1910 encrypted to the underlying "device" respectively.
1911 If this block device contains LVM volume groups, then calling
1913 "$h->vgscan" followed by "$h->vg_activate_all" will make them
1914 visible.
1915 $h->luks_open_ro ($device, $key, $mapname);
1917 This is the same as "$h->luks_open" except that a read-only mapping
1918 is created.
1919 $h->lvcreate ($logvol, $volgroup, $mbytes);
1921 This creates an LVM logical volume called "logvol" on the volume
1922 group "volgroup", with "size" megabytes.
1923 $lv = $h->lvm_canonical_lv_name ($lvname);
1925 This converts alternative naming schemes for LVs that you might
1926 find to the canonical name. For example, "/dev/mapper/VG-LV" is
1927 converted to "/dev/VG/LV".
1928 This command returns an error if the "lvname" parameter does not
1930 refer to a logical volume.
1931 See also "$h->is_lv".
1933 $h->lvm_clear_filter ();
1935 This undoes the effect of "$h->lvm_set_filter". LVM will be able
1936 to see every block device.
1937 This command also clears the LVM cache and performs a volume group
1939 scan.
1940 $h->lvm_remove_all ();
1942 This command removes all LVM logical volumes, volume groups and
1943 physical volumes.
1944 This command is dangerous. Without careful use you can easily
1946 destroy all your data.
1947 $h->lvm_set_filter (\@devices);
1949 This sets the LVM device filter so that LVM will only be able to
1950 "see" the block devices in the list "devices", and will ignore all
1951 other attached block devices.
1952 Where disk image(s) contain duplicate PVs or VGs, this command is
1954 useful to get LVM to ignore the duplicates, otherwise LVM can get
1955 confused. Note also there are two types of duplication possible:
1956 either cloned PVs/VGs which have identical UUIDs; or VGs that are
1957 not cloned but just happen to have the same name. In normal
1958 operation you cannot create this situation, but you can do it
1959 outside LVM, eg. by cloning disk images or by bit twiddling inside
1960 the LVM metadata.
1961 This command also clears the LVM cache and performs a volume group
1963 scan.
1964 You can filter whole block devices or individual partitions.
1966 You cannot use this if any VG is currently in use (eg. contains a
1968 mounted filesystem), even if you are not filtering out that VG.
1969 $h->lvremove ($device);
1971 Remove an LVM logical volume "device", where "device" is the path
1972 to the LV, such as "/dev/VG/LV".
1973 You can also remove all LVs in a volume group by specifying the VG
1975 name, "/dev/VG".
1976 $h->lvrename ($logvol, $newlogvol);
1978 Rename a logical volume "logvol" with the new name "newlogvol".
1979 $h->lvresize ($device, $mbytes);
1981 This resizes (expands or shrinks) an existing LVM logical volume to
1982 "mbytes". When reducing, data in the reduced part is lost.
1983 $h->lvresize_free ($lv, $percent);
1985 This expands an existing logical volume "lv" so that it fills "pc"%
1986 of the remaining free space in the volume group. Commonly you
1987 would call this with pc = 100 which expands the logical volume as
1988 much as possible, using all remaining free space in the volume
1989 group.
1990 @logvols = $h->lvs ();
1992 List all the logical volumes detected. This is the equivalent of
1993 the lvs(8) command.
1994 This returns a list of the logical volume device names (eg.
1996 "/dev/VolGroup00/LogVol00").
1997 See also "$h->lvs_full", "$h->list_filesystems".
1999 @logvols = $h->lvs_full ();
2001 List all the logical volumes detected. This is the equivalent of
2002 the lvs(8) command. The "full" version includes all fields.
2003 $uuid = $h->lvuuid ($device);
2005 This command returns the UUID of the LVM LV "device".
2006 @xattrs = $h->lxattrlist ($path, \@names);
2008 This call allows you to get the extended attributes of multiple
2009 files, where all files are in the directory "path". "names" is the
2010 list of files from this directory.
2011 On return you get a flat list of xattr structs which must be
2013 interpreted sequentially. The first xattr struct always has a
2014 zero-length "attrname". "attrval" in this struct is zero-length to
2015 indicate there was an error doing "lgetxattr" for this file, or is
2016 a C string which is a decimal number (the number of following
2017 attributes for this file, which could be "0"). Then after the
2018 first xattr struct are the zero or more attributes for the first
2019 named file. This repeats for the second and subsequent files.
2020 This call is intended for programs that want to efficiently list a
2022 directory contents without making many round-trips. See also
2023 "$h->lstatlist" for a similarly efficient call for getting standard
2024 stats. Very long directory listings might cause the protocol
2025 message size to be exceeded, causing this call to fail. The caller
2026 must split up such requests into smaller groups of names.
2027 $h->mkdir ($path);
2029 Create a directory named "path".
2030 $h->mkdir_mode ($path, $mode);
2032 This command creates a directory, setting the initial permissions
2033 of the directory to "mode".
2034 For common Linux filesystems, the actual mode which is set will be
2036 "mode & ~umask & 01777". Non-native-Linux filesystems may
2037 interpret the mode in other ways.
2038 See also "$h->mkdir", "$h->umask"
2040 $h->mkdir_p ($path);
2042 Create a directory named "path", creating any parent directories as
2043 necessary. This is like the "mkdir -p" shell command.
2044 $dir = $h->mkdtemp ($template);
2046 This command creates a temporary directory. The "template"
2047 parameter should be a full pathname for the temporary directory
2048 name with the final six characters being "XXXXXX".
2049 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
2051 second one being suitable for Windows filesystems.
2052 The name of the temporary directory that was created is returned.
2054 The temporary directory is created with mode 0700 and is owned by
2056 root.
2057 The caller is responsible for deleting the temporary directory and
2059 its contents after use.
2060 See also: mkdtemp(3)
2062 $h->mke2fs_J ($fstype, $blocksize, $device, $journal);
2064 This creates an ext2/3/4 filesystem on "device" with an external
2065 journal on "journal". It is equivalent to the command:
2066 mke2fs -t fstype -b blocksize -J device=<journal> <device>
2068 See also "$h->mke2journal".
2070 $h->mke2fs_JL ($fstype, $blocksize, $device, $label);
2072 This creates an ext2/3/4 filesystem on "device" with an external
2073 journal on the journal labeled "label".
2074 See also "$h->mke2journal_L".
2076 $h->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
2078 This creates an ext2/3/4 filesystem on "device" with an external
2079 journal on the journal with UUID "uuid".
2080 See also "$h->mke2journal_U".
2082 $h->mke2journal ($blocksize, $device);
2084 This creates an ext2 external journal on "device". It is
2085 equivalent to the command:
2086 mke2fs -O journal_dev -b blocksize device
2088 $h->mke2journal_L ($blocksize, $label, $device);
2090 This creates an ext2 external journal on "device" with label
2091 "label".
2092 $h->mke2journal_U ($blocksize, $uuid, $device);
2094 This creates an ext2 external journal on "device" with UUID "uuid".
2095 $h->mkfifo ($mode, $path);
2097 This call creates a FIFO (named pipe) called "path" with mode
2098 "mode". It is just a convenient wrapper around "$h->mknod".
2099 The mode actually set is affected by the umask.
2101 $h->mkfs ($fstype, $device);
2103 This creates a filesystem on "device" (usually a partition or LVM
2104 logical volume). The filesystem type is "fstype", for example
2105 "ext3".
2106 $h->mkfs_b ($fstype, $blocksize, $device);
2108 This call is similar to "$h->mkfs", but it allows you to control
2109 the block size of the resulting filesystem. Supported block sizes
2110 depend on the filesystem type, but typically they are 1024, 2048 or
2111 4096 only.
2112 For VFAT and NTFS the "blocksize" parameter is treated as the
2114 requested cluster size.
2115 This function is deprecated. In new code, use the "mkfs_opts" call
2117 instead.
2118 Deprecated functions will not be removed from the API, but the fact
2120 that they are deprecated indicates that there are problems with
2121 correct use of these functions.
2122 $h->mkfs_opts ($fstype, $device [, blocksize => $blocksize]);
2124 This function creates a filesystem on "device". The filesystem
2125 type is "fstype", for example "ext3".
2126 The optional arguments are:
2128 "blocksize"
2130 The filesystem block size. Supported block sizes depend on the
2131 filesystem type, but typically they are 1024, 2048 or 4096 for
2132 Linux ext2/3 filesystems.
2133 For VFAT and NTFS the "blocksize" parameter is treated as the
2135 requested cluster size.
2136 For UFS block sizes, please see mkfs.ufs(8).
2138 $h->mkmountpoint ($exemptpath);
2140 "$h->mkmountpoint" and "$h->rmmountpoint" are specialized calls
2141 that can be used to create extra mountpoints before mounting the
2142 first filesystem.
2143 These calls are only necessary in some very limited circumstances,
2145 mainly the case where you want to mount a mix of unrelated and/or
2146 read-only filesystems together.
2147 For example, live CDs often contain a "Russian doll" nest of
2149 filesystems, an ISO outer layer, with a squashfs image inside, with
2150 an ext2/3 image inside that. You can unpack this as follows in
2151 guestfish:
2152 add-ro Fedora-11-i686-Live.iso
2154 run
2155 mkmountpoint /cd
2156 mkmountpoint /sqsh
2157 mkmountpoint /ext3fs
2158 mount /dev/sda /cd
2159 mount-loop /cd/LiveOS/squashfs.img /sqsh
2160 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
2161 The inner filesystem is now unpacked under the /ext3fs mountpoint.
2163 "$h->mkmountpoint" is not compatible with "$h->umount_all". You
2165 may get unexpected errors if you try to mix these calls. It is
2166 safest to manually unmount filesystems and remove mountpoints after
2167 use.
2168 "$h->umount_all" unmounts filesystems by sorting the paths longest
2170 first, so for this to work for manual mountpoints, you must ensure
2171 that the innermost mountpoints have the longest pathnames, as in
2172 the example code above.
2173 For more details see
2175 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
2176 Autosync [see "$h->set_autosync", this is set by default on
2178 handles] means that "$h->umount_all" is called when the handle is
2179 closed which can also trigger these issues.
2180 $h->mknod ($mode, $devmajor, $devminor, $path);
2182 This call creates block or character special devices, or named
2183 pipes (FIFOs).
2184 The "mode" parameter should be the mode, using the standard
2186 constants. "devmajor" and "devminor" are the device major and
2187 minor numbers, only used when creating block and character special
2188 devices.
2189 Note that, just like mknod(2), the mode must be bitwise OR'd with
2191 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
2192 creates a regular file). These constants are available in the
2193 standard Linux header files, or you can use "$h->mknod_b",
2194 "$h->mknod_c" or "$h->mkfifo" which are wrappers around this
2195 command which bitwise OR in the appropriate constant for you.
2196 The mode actually set is affected by the umask.
2198 $h->mknod_b ($mode, $devmajor, $devminor, $path);
2200 This call creates a block device node called "path" with mode
2201 "mode" and device major/minor "devmajor" and "devminor". It is
2202 just a convenient wrapper around "$h->mknod".
2203 The mode actually set is affected by the umask.
2205 $h->mknod_c ($mode, $devmajor, $devminor, $path);
2207 This call creates a char device node called "path" with mode "mode"
2208 and device major/minor "devmajor" and "devminor". It is just a
2209 convenient wrapper around "$h->mknod".
2210 The mode actually set is affected by the umask.
2212 $h->mkswap ($device);
2214 Create a swap partition on "device".
2215 $h->mkswap_L ($label, $device);
2217 Create a swap partition on "device" with label "label".
2218 Note that you cannot attach a swap label to a block device (eg.
2220 "/dev/sda"), just to a partition. This appears to be a limitation
2221 of the kernel or swap tools.
2222 $h->mkswap_U ($uuid, $device);
2224 Create a swap partition on "device" with UUID "uuid".
2225 $h->mkswap_file ($path);
2227 Create a swap file.
2228 This command just writes a swap file signature to an existing file.
2230 To create the file itself, use something like "$h->fallocate".
2231 $h->modprobe ($modulename);
2233 This loads a kernel module in the appliance.
2234 The kernel module must have been whitelisted when libguestfs was
2236 built (see "appliance/kmod.whitelist.in" in the source).
2237 $h->mount ($device, $mountpoint);
2239 Mount a guest disk at a position in the filesystem. Block devices
2240 are named "/dev/sda", "/dev/sdb" and so on, as they were added to
2241 the guest. If those block devices contain partitions, they will
2242 have the usual names (eg. "/dev/sda1"). Also LVM
2243 "/dev/VG/LV"-style names can be used.
2244 The rules are the same as for mount(2): A filesystem must first be
2246 mounted on "/" before others can be mounted. Other filesystems can
2247 only be mounted on directories which already exist.
2248 The mounted filesystem is writable, if we have sufficient
2250 permissions on the underlying device.
2251 Important note: When you use this call, the filesystem options
2253 "sync" and "noatime" are set implicitly. This was originally done
2254 because we thought it would improve reliability, but it turns out
2255 that -o sync has a very large negative performance impact and
2256 negligible effect on reliability. Therefore we recommend that you
2257 avoid using "$h->mount" in any code that needs performance, and
2258 instead use "$h->mount_options" (use an empty string for the first
2259 parameter if you don't want any options).
2260 $h->mount_loop ($file, $mountpoint);
2262 This command lets you mount "file" (a filesystem image in a file)
2263 on a mount point. It is entirely equivalent to the command "mount
2264 -o loop file mountpoint".
2265 $h->mount_options ($options, $device, $mountpoint);
2267 This is the same as the "$h->mount" command, but it allows you to
2268 set the mount options as for the mount(8) -o flag.
2269 If the "options" parameter is an empty string, then no options are
2271 passed (all options default to whatever the filesystem uses).
2272 $h->mount_ro ($device, $mountpoint);
2274 This is the same as the "$h->mount" command, but it mounts the
2275 filesystem with the read-only (-o ro) flag.
2276 $h->mount_vfs ($options, $vfstype, $device, $mountpoint);
2278 This is the same as the "$h->mount" command, but it allows you to
2279 set both the mount options and the vfstype as for the mount(8) -o
2280 and -t flags.
2281 %mps = $h->mountpoints ();
2283 This call is similar to "$h->mounts". That call returns a list of
2284 devices. This one returns a hash table (map) of device name to
2285 directory where the device is mounted.
2286 @devices = $h->mounts ();
2288 This returns the list of currently mounted filesystems. It returns
2289 the list of devices (eg. "/dev/sda1", "/dev/VG/LV").
2290 Some internal mounts are not shown.
2292 See also: "$h->mountpoints"
2294 $h->mv ($src, $dest);
2296 This moves a file from "src" to "dest" where "dest" is either a
2297 destination filename or destination directory.
2298 $status = $h->ntfs_3g_probe ($rw, $device);
2300 This command runs the ntfs-3g.probe(8) command which probes an NTFS
2301 "device" for mountability. (Not all NTFS volumes can be mounted
2302 read-write, and some cannot be mounted at all).
2303 "rw" is a boolean flag. Set it to true if you want to test if the
2305 volume can be mounted read-write. Set it to false if you want to
2306 test if the volume can be mounted read-only.
2307 The return value is an integer which 0 if the operation would
2309 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
2310 manual page.
2311 $h->ntfsresize ($device);
2313 This command resizes an NTFS filesystem, expanding or shrinking it
2314 to the size of the underlying device.
2315 Note: After the resize operation, the filesystem is marked as
2317 requiring a consistency check (for safety). You have to boot into
2318 Windows to perform this check and clear this condition.
2319 Furthermore, ntfsresize refuses to resize filesystems which have
2320 been marked in this way. So in effect it is not possible to call
2321 ntfsresize multiple times on a single filesystem without booting
2322 into Windows between each resize.
2323 See also ntfsresize(8).
2325 $h->ntfsresize_size ($device, $size);
2327 This command is the same as "$h->ntfsresize" except that it allows
2328 you to specify the new size (in bytes) explicitly.
2329 $h->part_add ($device, $prlogex, $startsect, $endsect);
2331 This command adds a partition to "device". If there is no
2332 partition table on the device, call "$h->part_init" first.
2333 The "prlogex" parameter is the type of partition. Normally you
2335 should pass "p" or "primary" here, but MBR partition tables also
2336 support "l" (or "logical") and "e" (or "extended") partition types.
2337 "startsect" and "endsect" are the start and end of the partition in
2339 sectors. "endsect" may be negative, which means it counts
2340 backwards from the end of the disk ("-1" is the last sector).
2341 Creating a partition which covers the whole disk is not so easy.
2343 Use "$h->part_disk" to do that.
2344 $h->part_del ($device, $partnum);
2346 This command deletes the partition numbered "partnum" on "device".
2347 Note that in the case of MBR partitioning, deleting an extended
2349 partition also deletes any logical partitions it contains.
2350 $h->part_disk ($device, $parttype);
2352 This command is simply a combination of "$h->part_init" followed by
2353 "$h->part_add" to create a single primary partition covering the
2354 whole disk.
2355 "parttype" is the partition table type, usually "mbr" or "gpt", but
2357 other possible values are described in "$h->part_init".
2358 This command is dangerous. Without careful use you can easily
2360 destroy all your data.
2361 $bootable = $h->part_get_bootable ($device, $partnum);
2363 This command returns true if the partition "partnum" on "device"
2364 has the bootable flag set.
2365 See also "$h->part_set_bootable".
2367 $idbyte = $h->part_get_mbr_id ($device, $partnum);
2369 Returns the MBR type byte (also known as the ID byte) from the
2370 numbered partition "partnum".
2371 Note that only MBR (old DOS-style) partitions have type bytes. You
2373 will get undefined results for other partition table types (see
2374 "$h->part_get_parttype").
2375 $parttype = $h->part_get_parttype ($device);
2377 This command examines the partition table on "device" and returns
2378 the partition table type (format) being used.
2379 Common return values include: "msdos" (a DOS/Windows style MBR
2381 partition table), "gpt" (a GPT/EFI-style partition table). Other
2382 values are possible, although unusual. See "$h->part_init" for a
2383 full list.
2384 $h->part_init ($device, $parttype);
2386 This creates an empty partition table on "device" of one of the
2387 partition types listed below. Usually "parttype" should be either
2388 "msdos" or "gpt" (for large disks).
2389 Initially there are no partitions. Following this, you should call
2391 "$h->part_add" for each partition required.
2392 Possible values for "parttype" are:
2394 efi | gpt
2396 Intel EFI / GPT partition table.
2397 This is recommended for >= 2 TB partitions that will be
2399 accessed from Linux and Intel-based Mac OS X. It also has
2400 limited backwards compatibility with the "mbr" format.
2401 mbr | msdos
2403 The standard PC "Master Boot Record" (MBR) format used by MS-
2404 DOS and Windows. This partition type will only work for device
2405 sizes up to 2 TB. For large disks we recommend using "gpt".
2406 Other partition table types that may work but are not supported
2408 include:
2409 aix AIX disk labels.
2411 amiga | rdb
2413 Amiga "Rigid Disk Block" format.
2414 bsd BSD disk labels.
2416 dasd
2418 DASD, used on IBM mainframes.
2419 dvh MIPS/SGI volumes.
2421 mac Old Mac partition format. Modern Macs use "gpt".
2423 pc98
2425 NEC PC-98 format, common in Japan apparently.
2426 sun Sun disk labels.
2428 @partitions = $h->part_list ($device);
2430 This command parses the partition table on "device" and returns the
2431 list of partitions found.
2432 The fields in the returned structure are:
2434 part_num
2436 Partition number, counting from 1.
2437 part_start
2439 Start of the partition in bytes. To get sectors you have to
2440 divide by the device's sector size, see "$h->blockdev_getss".
2441 part_end
2443 End of the partition in bytes.
2444 part_size
2446 Size of the partition in bytes.
2447 $h->part_set_bootable ($device, $partnum, $bootable);
2449 This sets the bootable flag on partition numbered "partnum" on
2450 device "device". Note that partitions are numbered from 1.
2451 The bootable flag is used by some operating systems (notably
2453 Windows) to determine which partition to boot from. It is by no
2454 means universally recognized.
2455 $h->part_set_mbr_id ($device, $partnum, $idbyte);
2457 Sets the MBR type byte (also known as the ID byte) of the numbered
2458 partition "partnum" to "idbyte". Note that the type bytes quoted
2459 in most documentation are in fact hexadecimal numbers, but usually
2460 documented without any leading "0x" which might be confusing.
2461 Note that only MBR (old DOS-style) partitions have type bytes. You
2463 will get undefined results for other partition table types (see
2464 "$h->part_get_parttype").
2465 $h->part_set_name ($device, $partnum, $name);
2467 This sets the partition name on partition numbered "partnum" on
2468 device "device". Note that partitions are numbered from 1.
2469 The partition name can only be set on certain types of partition
2471 table. This works on "gpt" but not on "mbr" partitions.
2472 $device = $h->part_to_dev ($partition);
2474 This function takes a partition name (eg. "/dev/sdb1") and removes
2475 the partition number, returning the device name (eg. "/dev/sdb").
2476 The named partition must exist, for example as a string returned
2478 from "$h->list_partitions".
2479 $h->ping_daemon ();
2481 This is a test probe into the guestfs daemon running inside the
2482 qemu subprocess. Calling this function checks that the daemon
2483 responds to the ping message, without affecting the daemon or
2484 attached block device(s) in any other way.
2485 $content = $h->pread ($path, $count, $offset);
2487 This command lets you read part of a file. It reads "count" bytes
2488 of the file, starting at "offset", from file "path".
2489 This may read fewer bytes than requested. For further details see
2491 the pread(2) system call.
2492 See also "$h->pwrite", "$h->pread_device".
2494 Because of the message protocol, there is a transfer limit of
2496 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2497 guestfs(3).
2498 $content = $h->pread_device ($device, $count, $offset);
2500 This command lets you read part of a file. It reads "count" bytes
2501 of "device", starting at "offset".
2502 This may read fewer bytes than requested. For further details see
2504 the pread(2) system call.
2505 See also "$h->pread".
2507 Because of the message protocol, there is a transfer limit of
2509 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2510 guestfs(3).
2511 $h->pvcreate ($device);
2513 This creates an LVM physical volume on the named "device", where
2514 "device" should usually be a partition name such as "/dev/sda1".
2515 $h->pvremove ($device);
2517 This wipes a physical volume "device" so that LVM will no longer
2518 recognise it.
2519 The implementation uses the "pvremove" command which refuses to
2521 wipe physical volumes that contain any volume groups, so you have
2522 to remove those first.
2523 $h->pvresize ($device);
2525 This resizes (expands or shrinks) an existing LVM physical volume
2526 to match the new size of the underlying device.
2527 $h->pvresize_size ($device, $size);
2529 This command is the same as "$h->pvresize" except that it allows
2530 you to specify the new size (in bytes) explicitly.
2531 @physvols = $h->pvs ();
2533 List all the physical volumes detected. This is the equivalent of
2534 the pvs(8) command.
2535 This returns a list of just the device names that contain PVs (eg.
2537 "/dev/sda2").
2538 See also "$h->pvs_full".
2540 @physvols = $h->pvs_full ();
2542 List all the physical volumes detected. This is the equivalent of
2543 the pvs(8) command. The "full" version includes all fields.
2544 $uuid = $h->pvuuid ($device);
2546 This command returns the UUID of the LVM PV "device".
2547 $nbytes = $h->pwrite ($path, $content, $offset);
2549 This command writes to part of a file. It writes the data buffer
2550 "content" to the file "path" starting at offset "offset".
2551 This command implements the pwrite(2) system call, and like that
2553 system call it may not write the full data requested. The return
2554 value is the number of bytes that were actually written to the
2555 file. This could even be 0, although short writes are unlikely for
2556 regular files in ordinary circumstances.
2557 See also "$h->pread", "$h->pwrite_device".
2559 Because of the message protocol, there is a transfer limit of
2561 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2562 guestfs(3).
2563 $nbytes = $h->pwrite_device ($device, $content, $offset);
2565 This command writes to part of a device. It writes the data buffer
2566 "content" to "device" starting at offset "offset".
2567 This command implements the pwrite(2) system call, and like that
2569 system call it may not write the full data requested (although
2570 short writes to disk devices and partitions are probably impossible
2571 with standard Linux kernels).
2572 See also "$h->pwrite".
2574 Because of the message protocol, there is a transfer limit of
2576 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2577 guestfs(3).
2578 $content = $h->read_file ($path);
2580 This calls returns the contents of the file "path" as a buffer.
2581 Unlike "$h->cat", this function can correctly handle files that
2583 contain embedded ASCII NUL characters. However unlike
2584 "$h->download", this function is limited in the total size of file
2585 that can be handled.
2586 Because of the message protocol, there is a transfer limit of
2588 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2589 guestfs(3).
2590 @lines = $h->read_lines ($path);
2592 Return the contents of the file named "path".
2593 The file contents are returned as a list of lines. Trailing "LF"
2595 and "CRLF" character sequences are not returned.
2596 Note that this function cannot correctly handle binary files
2598 (specifically, files containing "\0" character which is treated as
2599 end of line). For those you need to use the "$h->read_file"
2600 function which has a more complex interface.
2601 @entries = $h->readdir ($dir);
2603 This returns the list of directory entries in directory "dir".
2604 All entries in the directory are returned, including "." and "..".
2606 The entries are not sorted, but returned in the same order as the
2607 underlying filesystem.
2608 Also this call returns basic file type information about each file.
2610 The "ftyp" field will contain one of the following characters:
2611 'b' Block special
2613 'c' Char special
2615 'd' Directory
2617 'f' FIFO (named pipe)
2619 'l' Symbolic link
2621 'r' Regular file
2623 's' Socket
2625 'u' Unknown file type
2627 '?' The readdir(3) call returned a "d_type" field with an
2629 unexpected value
2630 This function is primarily intended for use by programs. To get a
2632 simple list of names, use "$h->ls". To get a printable directory
2633 for human consumption, use "$h->ll".
2634 $link = $h->readlink ($path);
2636 This command reads the target of a symbolic link.
2637 @links = $h->readlinklist ($path, \@names);
2639 This call allows you to do a "readlink" operation on multiple
2640 files, where all files are in the directory "path". "names" is the
2641 list of files from this directory.
2642 On return you get a list of strings, with a one-to-one
2644 correspondence to the "names" list. Each string is the value of
2645 the symbolic link.
2646 If the readlink(2) operation fails on any name, then the
2648 corresponding result string is the empty string "". However the
2649 whole operation is completed even if there were readlink(2) errors,
2650 and so you can call this function with names where you don't know
2651 if they are symbolic links already (albeit slightly less
2652 efficient).
2653 This call is intended for programs that want to efficiently list a
2655 directory contents without making many round-trips. Very long
2656 directory listings might cause the protocol message size to be
2657 exceeded, causing this call to fail. The caller must split up such
2658 requests into smaller groups of names.
2659 $rpath = $h->realpath ($path);
2661 Return the canonicalized absolute pathname of "path". The returned
2662 path has no ".", ".." or symbolic link path elements.
2663 $h->removexattr ($xattr, $path);
2665 This call removes the extended attribute named "xattr" of the file
2666 "path".
2667 See also: "$h->lremovexattr", attr(5).
2669 $h->resize2fs ($device);
2671 This resizes an ext2, ext3 or ext4 filesystem to match the size of
2672 the underlying device.
2673 Note: It is sometimes required that you run "$h->e2fsck_f" on the
2675 "device" before calling this command. For unknown reasons
2676 "resize2fs" sometimes gives an error about this and sometimes not.
2677 In any case, it is always safe to call "$h->e2fsck_f" before
2678 calling this function.
2679 $h->resize2fs_size ($device, $size);
2681 This command is the same as "$h->resize2fs" except that it allows
2682 you to specify the new size (in bytes) explicitly.
2683 $h->rm ($path);
2685 Remove the single file "path".
2686 $h->rm_rf ($path);
2688 Remove the file or directory "path", recursively removing the
2689 contents if its a directory. This is like the "rm -rf" shell
2690 command.
2691 $h->rmdir ($path);
2693 Remove the single directory "path".
2694 $h->rmmountpoint ($exemptpath);
2696 This calls removes a mountpoint that was previously created with
2697 "$h->mkmountpoint". See "$h->mkmountpoint" for full details.
2698 $h->scrub_device ($device);
2700 This command writes patterns over "device" to make data retrieval
2701 more difficult.
2702 It is an interface to the scrub(1) program. See that manual page
2704 for more details.
2705 This command is dangerous. Without careful use you can easily
2707 destroy all your data.
2708 $h->scrub_file ($file);
2710 This command writes patterns over a file to make data retrieval
2711 more difficult.
2712 The file is removed after scrubbing.
2714 It is an interface to the scrub(1) program. See that manual page
2716 for more details.
2717 $h->scrub_freespace ($dir);
2719 This command creates the directory "dir" and then fills it with
2720 files until the filesystem is full, and scrubs the files as for
2721 "$h->scrub_file", and deletes them. The intention is to scrub any
2722 free space on the partition containing "dir".
2723 It is an interface to the scrub(1) program. See that manual page
2725 for more details.
2726 $h->set_append ($append);
2728 This function is used to add additional options to the guest kernel
2729 command line.
2730 The default is "NULL" unless overridden by setting
2732 "LIBGUESTFS_APPEND" environment variable.
2733 Setting "append" to "NULL" means no additional options are passed
2735 (libguestfs always adds a few of its own).
2736 $h->set_autosync ($autosync);
2738 If "autosync" is true, this enables autosync. Libguestfs will make
2739 a best effort attempt to run "$h->umount_all" followed by
2740 "$h->sync" when the handle is closed (also if the program exits
2741 without closing handles).
2742 This is enabled by default (since libguestfs 1.5.24, previously it
2744 was disabled by default).
2745 $h->set_direct ($direct);
2747 If the direct appliance mode flag is enabled, then stdin and stdout
2748 are passed directly through to the appliance once it is launched.
2749 One consequence of this is that log messages aren't caught by the
2751 library and handled by "$h->set_log_message_callback", but go
2752 straight to stdout.
2753 You probably don't want to use this unless you know what you are
2755 doing.
2756 The default is disabled.
2758 $h->set_e2label ($device, $label);
2760 This sets the ext2/3/4 filesystem label of the filesystem on
2761 "device" to "label". Filesystem labels are limited to 16
2762 characters.
2763 You can use either "$h->tune2fs_l" or "$h->get_e2label" to return
2765 the existing label on a filesystem.
2766 $h->set_e2uuid ($device, $uuid);
2768 This sets the ext2/3/4 filesystem UUID of the filesystem on
2769 "device" to "uuid". The format of the UUID and alternatives such
2770 as "clear", "random" and "time" are described in the tune2fs(8)
2771 manpage.
2772 You can use either "$h->tune2fs_l" or "$h->get_e2uuid" to return
2774 the existing UUID of a filesystem.
2775 $h->set_memsize ($memsize);
2777 This sets the memory size in megabytes allocated to the qemu
2778 subprocess. This only has any effect if called before
2779 "$h->launch".
2780 You can also change this by setting the environment variable
2782 "LIBGUESTFS_MEMSIZE" before the handle is created.
2783 For more information on the architecture of libguestfs, see
2785 guestfs(3).
2786 $h->set_network ($network);
2788 If "network" is true, then the network is enabled in the libguestfs
2789 appliance. The default is false.
2790 This affects whether commands are able to access the network (see
2792 "RUNNING COMMANDS" in guestfs(3)).
2793 You must call this before calling "$h->launch", otherwise it has no
2795 effect.
2796 $h->set_path ($searchpath);
2798 Set the path that libguestfs searches for kernel and initrd.img.
2799 The default is "$libdir/guestfs" unless overridden by setting
2801 "LIBGUESTFS_PATH" environment variable.
2802 Setting "path" to "NULL" restores the default path.
2804 $h->set_qemu ($qemu);
2806 Set the qemu binary that we will use.
2807 The default is chosen when the library was compiled by the
2809 configure script.
2810 You can also override this by setting the "LIBGUESTFS_QEMU"
2812 environment variable.
2813 Setting "qemu" to "NULL" restores the default qemu binary.
2815 Note that you should call this function as early as possible after
2817 creating the handle. This is because some pre-launch operations
2818 depend on testing qemu features (by running "qemu -help"). If the
2819 qemu binary changes, we don't retest features, and so you might see
2820 inconsistent results. Using the environment variable
2821 "LIBGUESTFS_QEMU" is safest of all since that picks the qemu binary
2822 at the same time as the handle is created.
2823 $h->set_recovery_proc ($recoveryproc);
2825 If this is called with the parameter "false" then "$h->launch" does
2826 not create a recovery process. The purpose of the recovery process
2827 is to stop runaway qemu processes in the case where the main
2828 program aborts abruptly.
2829 This only has any effect if called before "$h->launch", and the
2831 default is true.
2832 About the only time when you would want to disable this is if the
2834 main process will fork itself into the background ("daemonize"
2835 itself). In this case the recovery process thinks that the main
2836 program has disappeared and so kills qemu, which is not very
2837 helpful.
2838 $h->set_selinux ($selinux);
2840 This sets the selinux flag that is passed to the appliance at boot
2841 time. The default is "selinux=0" (disabled).
2842 Note that if SELinux is enabled, it is always in Permissive mode
2844 ("enforcing=0").
2845 For more information on the architecture of libguestfs, see
2847 guestfs(3).
2848 $h->set_trace ($trace);
2850 If the command trace flag is set to 1, then commands are printed on
2851 stderr before they are executed in a format which is very similar
2852 to the one used by guestfish. In other words, you can run a
2853 program with this enabled, and you will get out a script which you
2854 can feed to guestfish to perform the same set of actions.
2855 If you want to trace C API calls into libguestfs (and other
2857 libraries) then possibly a better way is to use the external
2858 ltrace(1) command.
2859 Command traces are disabled unless the environment variable
2861 "LIBGUESTFS_TRACE" is defined and set to 1.
2862 $h->set_verbose ($verbose);
2864 If "verbose" is true, this turns on verbose messages (to "stderr").
2865 Verbose messages are disabled unless the environment variable
2867 "LIBGUESTFS_DEBUG" is defined and set to 1.
2868 $h->setcon ($context);
2870 This sets the SELinux security context of the daemon to the string
2871 "context".
2872 See the documentation about SELINUX in guestfs(3).
2874 $h->setxattr ($xattr, $val, $vallen, $path);
2876 This call sets the extended attribute named "xattr" of the file
2877 "path" to the value "val" (of length "vallen"). The value is
2878 arbitrary 8 bit data.
2879 See also: "$h->lsetxattr", attr(5).
2881 $h->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
2883 This is a direct interface to the sfdisk(8) program for creating
2884 partitions on block devices.
2885 "device" should be a block device, for example "/dev/sda".
2887 "cyls", "heads" and "sectors" are the number of cylinders, heads
2889 and sectors on the device, which are passed directly to sfdisk as
2890 the -C, -H and -S parameters. If you pass 0 for any of these, then
2891 the corresponding parameter is omitted. Usually for 'large' disks,
2892 you can just pass 0 for these, but for small (floppy-sized) disks,
2893 sfdisk (or rather, the kernel) cannot work out the right geometry
2894 and you will need to tell it.
2895 "lines" is a list of lines that we feed to "sfdisk". For more
2897 information refer to the sfdisk(8) manpage.
2898 To create a single partition occupying the whole disk, you would
2900 pass "lines" as a single element list, when the single element
2901 being the string "," (comma).
2902 See also: "$h->sfdisk_l", "$h->sfdisk_N", "$h->part_init"
2904 This command is dangerous. Without careful use you can easily
2906 destroy all your data.
2907 $h->sfdiskM ($device, \@lines);
2909 This is a simplified interface to the "$h->sfdisk" command, where
2910 partition sizes are specified in megabytes only (rounded to the
2911 nearest cylinder) and you don't need to specify the cyls, heads and
2912 sectors parameters which were rarely if ever used anyway.
2913 See also: "$h->sfdisk", the sfdisk(8) manpage and "$h->part_disk"
2915 This command is dangerous. Without careful use you can easily
2917 destroy all your data.
2918 $h->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
2920 This runs sfdisk(8) option to modify just the single partition "n"
2921 (note: "n" counts from 1).
2922 For other parameters, see "$h->sfdisk". You should usually pass 0
2924 for the cyls/heads/sectors parameters.
2925 See also: "$h->part_add"
2927 This command is dangerous. Without careful use you can easily
2929 destroy all your data.
2930 $partitions = $h->sfdisk_disk_geometry ($device);
2932 This displays the disk geometry of "device" read from the partition
2933 table. Especially in the case where the underlying block device
2934 has been resized, this can be different from the kernel's idea of
2935 the geometry (see "$h->sfdisk_kernel_geometry").
2936 The result is in human-readable format, and not designed to be
2938 parsed.
2939 $partitions = $h->sfdisk_kernel_geometry ($device);
2941 This displays the kernel's idea of the geometry of "device".
2942 The result is in human-readable format, and not designed to be
2944 parsed.
2945 $partitions = $h->sfdisk_l ($device);
2947 This displays the partition table on "device", in the human-
2948 readable output of the sfdisk(8) command. It is not intended to be
2949 parsed.
2950 See also: "$h->part_list"
2952 $output = $h->sh ($command);
2954 This call runs a command from the guest filesystem via the guest's
2955 "/bin/sh".
2956 This is like "$h->command", but passes the command to:
2958 /bin/sh -c "command"
2960 Depending on the guest's shell, this usually results in wildcards
2962 being expanded, shell expressions being interpolated and so on.
2963 All the provisos about "$h->command" apply to this call.
2965 @lines = $h->sh_lines ($command);
2967 This is the same as "$h->sh", but splits the result into a list of
2968 lines.
2969 See also: "$h->command_lines"
2971 $h->sleep ($secs);
2973 Sleep for "secs" seconds.
2974 %statbuf = $h->stat ($path);
2976 Returns file information for the given "path".
2977 This is the same as the stat(2) system call.
2979 %statbuf = $h->statvfs ($path);
2981 Returns file system statistics for any mounted file system. "path"
2982 should be a file or directory in the mounted file system (typically
2983 it is the mount point itself, but it doesn't need to be).
2984 This is the same as the statvfs(2) system call.
2986 @stringsout = $h->strings ($path);
2988 This runs the strings(1) command on a file and returns the list of
2989 printable strings found.
2990 Because of the message protocol, there is a transfer limit of
2992 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2993 guestfs(3).
2994 @stringsout = $h->strings_e ($encoding, $path);
2996 This is like the "$h->strings" command, but allows you to specify
2997 the encoding of strings that are looked for in the source file
2998 "path".
2999 Allowed encodings are:
3001 s Single 7-bit-byte characters like ASCII and the ASCII-
3003 compatible parts of ISO-8859-X (this is what "$h->strings"
3004 uses).
3005 S Single 8-bit-byte characters.
3007 b 16-bit big endian strings such as those encoded in UTF-16BE or
3009 UCS-2BE.
3010 l (lower case letter L)
3012 16-bit little endian such as UTF-16LE and UCS-2LE. This is
3013 useful for examining binaries in Windows guests.
3014 B 32-bit big endian such as UCS-4BE.
3016 L 32-bit little endian such as UCS-4LE.
3018 The returned strings are transcoded to UTF-8.
3020 Because of the message protocol, there is a transfer limit of
3022 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3023 guestfs(3).
3024 $h->swapoff_device ($device);
3026 This command disables the libguestfs appliance swap device or
3027 partition named "device". See "$h->swapon_device".
3028 $h->swapoff_file ($file);
3030 This command disables the libguestfs appliance swap on file.
3031 $h->swapoff_label ($label);
3033 This command disables the libguestfs appliance swap on labeled swap
3034 partition.
3035 $h->swapoff_uuid ($uuid);
3037 This command disables the libguestfs appliance swap partition with
3038 the given UUID.
3039 $h->swapon_device ($device);
3041 This command enables the libguestfs appliance to use the swap
3042 device or partition named "device". The increased memory is made
3043 available for all commands, for example those run using
3044 "$h->command" or "$h->sh".
3045 Note that you should not swap to existing guest swap partitions
3047 unless you know what you are doing. They may contain hibernation
3048 information, or other information that the guest doesn't want you
3049 to trash. You also risk leaking information about the host to the
3050 guest this way. Instead, attach a new host device to the guest and
3051 swap on that.
3052 $h->swapon_file ($file);
3054 This command enables swap to a file. See "$h->swapon_device" for
3055 other notes.
3056 $h->swapon_label ($label);
3058 This command enables swap to a labeled swap partition. See
3059 "$h->swapon_device" for other notes.
3060 $h->swapon_uuid ($uuid);
3062 This command enables swap to a swap partition with the given UUID.
3063 See "$h->swapon_device" for other notes.
3064 $h->sync ();
3066 This syncs the disk, so that any writes are flushed through to the
3067 underlying disk image.
3068 You should always call this if you have modified a disk image,
3070 before closing the handle.
3071 @lines = $h->tail ($path);
3073 This command returns up to the last 10 lines of a file as a list of
3074 strings.
3075 Because of the message protocol, there is a transfer limit of
3077 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3078 guestfs(3).
3079 @lines = $h->tail_n ($nrlines, $path);
3081 If the parameter "nrlines" is a positive number, this returns the
3082 last "nrlines" lines of the file "path".
3083 If the parameter "nrlines" is a negative number, this returns lines
3085 from the file "path", starting with the "-nrlines"th line.
3086 If the parameter "nrlines" is zero, this returns an empty list.
3088 Because of the message protocol, there is a transfer limit of
3090 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3091 guestfs(3).
3092 $h->tar_in ($tarfile, $directory);
3094 This command uploads and unpacks local file "tarfile" (an
3095 uncompressed tar file) into "directory".
3096 To upload a compressed tarball, use "$h->tgz_in" or "$h->txz_in".
3098 $h->tar_out ($directory, $tarfile);
3100 This command packs the contents of "directory" and downloads it to
3101 local file "tarfile".
3102 To download a compressed tarball, use "$h->tgz_out" or
3104 "$h->txz_out".
3105 $h->tgz_in ($tarball, $directory);
3107 This command uploads and unpacks local file "tarball" (a gzip
3108 compressed tar file) into "directory".
3109 To upload an uncompressed tarball, use "$h->tar_in".
3111 $h->tgz_out ($directory, $tarball);
3113 This command packs the contents of "directory" and downloads it to
3114 local file "tarball".
3115 To download an uncompressed tarball, use "$h->tar_out".
3117 $h->touch ($path);
3119 Touch acts like the touch(1) command. It can be used to update the
3120 timestamps on a file, or, if the file does not exist, to create a
3121 new zero-length file.
3122 This command only works on regular files, and will fail on other
3124 file types such as directories, symbolic links, block special etc.
3125 $h->truncate ($path);
3127 This command truncates "path" to a zero-length file. The file must
3128 exist already.
3129 $h->truncate_size ($path, $size);
3131 This command truncates "path" to size "size" bytes. The file must
3132 exist already.
3133 If the current file size is less than "size" then the file is
3135 extended to the required size with zero bytes. This creates a
3136 sparse file (ie. disk blocks are not allocated for the file until
3137 you write to it). To create a non-sparse file of zeroes, use
3138 "$h->fallocate64" instead.
3139 %superblock = $h->tune2fs_l ($device);
3141 This returns the contents of the ext2, ext3 or ext4 filesystem
3142 superblock on "device".
3143 It is the same as running "tune2fs -l device". See tune2fs(8)
3145 manpage for more details. The list of fields returned isn't
3146 clearly defined, and depends on both the version of "tune2fs" that
3147 libguestfs was built against, and the filesystem itself.
3148 $h->txz_in ($tarball, $directory);
3150 This command uploads and unpacks local file "tarball" (an xz
3151 compressed tar file) into "directory".
3152 $h->txz_out ($directory, $tarball);
3154 This command packs the contents of "directory" and downloads it to
3155 local file "tarball" (as an xz compressed tar archive).
3156 $oldmask = $h->umask ($mask);
3158 This function sets the mask used for creating new files and device
3159 nodes to "mask & 0777".
3160 Typical umask values would be 022 which creates new files with
3162 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
3163 creates new files with permissions like "-rw-rw-r--" or
3164 "-rwxrwxr-x".
3165 The default umask is 022. This is important because it means that
3167 directories and device nodes will be created with 0644 or 0755 mode
3168 even if you specify 0777.
3169 See also "$h->get_umask", umask(2), "$h->mknod", "$h->mkdir".
3171 This call returns the previous umask.
3173 $h->umount ($pathordevice);
3175 This unmounts the given filesystem. The filesystem may be
3176 specified either by its mountpoint (path) or the device which
3177 contains the filesystem.
3178 $h->umount_all ();
3180 This unmounts all mounted filesystems.
3181 Some internal mounts are not unmounted by this call.
3183 $h->upload ($filename, $remotefilename);
3185 Upload local file "filename" to "remotefilename" on the filesystem.
3186 "filename" can also be a named pipe.
3188 See also "$h->download".
3190 $h->upload_offset ($filename, $remotefilename, $offset);
3192 Upload local file "filename" to "remotefilename" on the filesystem.
3193 "remotefilename" is overwritten starting at the byte "offset"
3195 specified. The intention is to overwrite parts of existing files
3196 or devices, although if a non-existant file is specified then it is
3197 created with a "hole" before "offset". The size of the data
3198 written is implicit in the size of the source "filename".
3199 Note that there is no limit on the amount of data that can be
3201 uploaded with this call, unlike with "$h->pwrite", and this call
3202 always writes the full amount unless an error occurs.
3203 See also "$h->upload", "$h->pwrite".
3205 $h->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
3207 This command sets the timestamps of a file with nanosecond
3208 precision.
3209 "atsecs, atnsecs" are the last access time (atime) in secs and
3211 nanoseconds from the epoch.
3212 "mtsecs, mtnsecs" are the last modification time (mtime) in secs
3214 and nanoseconds from the epoch.
3215 If the *nsecs field contains the special value "-1" then the
3217 corresponding timestamp is set to the current time. (The *secs
3218 field is ignored in this case).
3219 If the *nsecs field contains the special value "-2" then the
3221 corresponding timestamp is left unchanged. (The *secs field is
3222 ignored in this case).
3223 %version = $h->version ();
3225 Return the libguestfs version number that the program is linked
3226 against.
3227 Note that because of dynamic linking this is not necessarily the
3229 version of libguestfs that you compiled against. You can compile
3230 the program, and then at runtime dynamically link against a
3231 completely different "libguestfs.so" library.
3232 This call was added in version 1.0.58. In previous versions of
3234 libguestfs there was no way to get the version number. From C code
3235 you can use dynamic linker functions to find out if this symbol
3236 exists (if it doesn't, then it's an earlier version).
3237 The call returns a structure with four elements. The first three
3239 ("major", "minor" and "release") are numbers and correspond to the
3240 usual version triplet. The fourth element ("extra") is a string
3241 and is normally empty, but may be used for distro-specific
3242 information.
3243 To construct the original version string:
3245 "$major.$minor.$release$extra"
3246 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
3248 Note: Don't use this call to test for availability of features. In
3250 enterprise distributions we backport features from later versions
3251 into earlier versions, making this an unreliable way to test for
3252 features. Use "$h->available" instead.
3253 $label = $h->vfs_label ($device);
3255 This returns the filesystem label of the filesystem on "device".
3256 If the filesystem is unlabeled, this returns the empty string.
3258 To find a filesystem from the label, use "$h->findfs_label".
3260 $fstype = $h->vfs_type ($device);
3262 This command gets the filesystem type corresponding to the
3263 filesystem on "device".
3264 For most filesystems, the result is the name of the Linux VFS
3266 module which would be used to mount this filesystem if you mounted
3267 it without specifying the filesystem type. For example a string
3268 such as "ext3" or "ntfs".
3269 $uuid = $h->vfs_uuid ($device);
3271 This returns the filesystem UUID of the filesystem on "device".
3272 If the filesystem does not have a UUID, this returns the empty
3274 string.
3275 To find a filesystem from the UUID, use "$h->findfs_uuid".
3277 $h->vg_activate ($activate, \@volgroups);
3279 This command activates or (if "activate" is false) deactivates all
3280 logical volumes in the listed volume groups "volgroups". If
3281 activated, then they are made known to the kernel, ie. they appear
3282 as "/dev/mapper" devices. If deactivated, then those devices
3283 disappear.
3284 This command is the same as running "vgchange -a y|n volgroups..."
3286 Note that if "volgroups" is an empty list then all volume groups
3288 are activated or deactivated.
3289 $h->vg_activate_all ($activate);
3291 This command activates or (if "activate" is false) deactivates all
3292 logical volumes in all volume groups. If activated, then they are
3293 made known to the kernel, ie. they appear as "/dev/mapper" devices.
3294 If deactivated, then those devices disappear.
3295 This command is the same as running "vgchange -a y|n"
3297 $h->vgcreate ($volgroup, \@physvols);
3299 This creates an LVM volume group called "volgroup" from the non-
3300 empty list of physical volumes "physvols".
3301 @uuids = $h->vglvuuids ($vgname);
3303 Given a VG called "vgname", this returns the UUIDs of all the
3304 logical volumes created in this volume group.
3305 You can use this along with "$h->lvs" and "$h->lvuuid" calls to
3307 associate logical volumes and volume groups.
3308 See also "$h->vgpvuuids".
3310 @uuids = $h->vgpvuuids ($vgname);
3312 Given a VG called "vgname", this returns the UUIDs of all the
3313 physical volumes that this volume group resides on.
3314 You can use this along with "$h->pvs" and "$h->pvuuid" calls to
3316 associate physical volumes and volume groups.
3317 See also "$h->vglvuuids".
3319 $h->vgremove ($vgname);
3321 Remove an LVM volume group "vgname", (for example "VG").
3322 This also forcibly removes all logical volumes in the volume group
3324 (if any).
3325 $h->vgrename ($volgroup, $newvolgroup);
3327 Rename a volume group "volgroup" with the new name "newvolgroup".
3328 @volgroups = $h->vgs ();
3330 List all the volumes groups detected. This is the equivalent of
3331 the vgs(8) command.
3332 This returns a list of just the volume group names that were
3334 detected (eg. "VolGroup00").
3335 See also "$h->vgs_full".
3337 @volgroups = $h->vgs_full ();
3339 List all the volumes groups detected. This is the equivalent of
3340 the vgs(8) command. The "full" version includes all fields.
3341 $h->vgscan ();
3343 This rescans all block devices and rebuilds the list of LVM
3344 physical volumes, volume groups and logical volumes.
3345 $uuid = $h->vguuid ($vgname);
3347 This command returns the UUID of the LVM VG named "vgname".
3348 $h->wait_ready ();
3350 This function is a no op.
3351 In versions of the API < 1.0.71 you had to call this function just
3353 after calling "$h->launch" to wait for the launch to complete.
3354 However this is no longer necessary because "$h->launch" now does
3355 the waiting.
3356 If you see any calls to this function in code then you can just
3358 remove them, unless you want to retain compatibility with older
3359 versions of the API.
3360 $chars = $h->wc_c ($path);
3362 This command counts the characters in a file, using the "wc -c"
3363 external command.
3364 $lines = $h->wc_l ($path);
3366 This command counts the lines in a file, using the "wc -l" external
3367 command.
3368 $words = $h->wc_w ($path);
3370 This command counts the words in a file, using the "wc -w" external
3371 command.
3372 $h->write ($path, $content);
3374 This call creates a file called "path". The content of the file is
3375 the string "content" (which can contain any 8 bit data).
3376 Because of the message protocol, there is a transfer limit of
3378 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3379 guestfs(3).
3380 $h->write_file ($path, $content, $size);
3382 This call creates a file called "path". The contents of the file
3383 is the string "content" (which can contain any 8 bit data), with
3384 length "size".
3385 As a special case, if "size" is 0 then the length is calculated
3387 using "strlen" (so in this case the content cannot contain embedded
3388 ASCII NULs).
3389 NB. Owing to a bug, writing content containing ASCII NUL characters
3391 does not work, even if the length is specified.
3392 Because of the message protocol, there is a transfer limit of
3394 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3395 guestfs(3).
3396 This function is deprecated. In new code, use the "write" call
3398 instead.
3399 Deprecated functions will not be removed from the API, but the fact
3401 that they are deprecated indicates that there are problems with
3402 correct use of these functions.
3403 @lines = $h->zegrep ($regex, $path);
3405 This calls the external "zegrep" program and returns the matching
3406 lines.
3407 Because of the message protocol, there is a transfer limit of
3409 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3410 guestfs(3).
3411 @lines = $h->zegrepi ($regex, $path);
3413 This calls the external "zegrep -i" program and returns the
3414 matching lines.
3415 Because of the message protocol, there is a transfer limit of
3417 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3418 guestfs(3).
3419 $h->zero ($device);
3421 This command writes zeroes over the first few blocks of "device".
3422 How many blocks are zeroed isn't specified (but it's not enough to
3424 securely wipe the device). It should be sufficient to remove any
3425 partition tables, filesystem superblocks and so on.
3426 See also: "$h->zero_device", "$h->scrub_device".
3428 $h->zero_device ($device);
3430 This command writes zeroes over the entire "device". Compare with
3431 "$h->zero" which just zeroes the first few blocks of a device.
3432 This command is dangerous. Without careful use you can easily
3434 destroy all your data.
3435 $h->zerofree ($device);
3437 This runs the zerofree program on "device". This program claims to
3438 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
3439 making it possible to compress the filesystem more effectively.
3440 You should not run this program if the filesystem is mounted.
3442 It is possible that using this program can damage the filesystem or
3444 data on the filesystem.
3445 @lines = $h->zfgrep ($pattern, $path);
3447 This calls the external "zfgrep" program and returns the matching
3448 lines.
3449 Because of the message protocol, there is a transfer limit of
3451 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3452 guestfs(3).
3453 @lines = $h->zfgrepi ($pattern, $path);
3455 This calls the external "zfgrep -i" program and returns the
3456 matching lines.
3457 Because of the message protocol, there is a transfer limit of
3459 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3460 guestfs(3).
3461 $description = $h->zfile ($meth, $path);
3463 This command runs "file" after first decompressing "path" using
3464 "method".
3465 "method" must be one of "gzip", "compress" or "bzip2".
3467 Since 1.0.63, use "$h->file" instead which can now process
3469 compressed files.
3470 This function is deprecated. In new code, use the "file" call
3472 instead.
3473 Deprecated functions will not be removed from the API, but the fact
3475 that they are deprecated indicates that there are problems with
3476 correct use of these functions.
3477 @lines = $h->zgrep ($regex, $path);
3479 This calls the external "zgrep" program and returns the matching
3480 lines.
3481 Because of the message protocol, there is a transfer limit of
3483 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3484 guestfs(3).
3485 @lines = $h->zgrepi ($regex, $path);
3487 This calls the external "zgrep -i" program and returns the matching
3488 lines.
3489 Because of the message protocol, there is a transfer limit of
3491 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3492 guestfs(3).
3493
3495 From time to time we add new libguestfs APIs. Also some libguestfs
3496 APIs won't be available in all builds of libguestfs (the Fedora build
3497 is full-featured, but other builds may disable features). How do you
3498 test whether the APIs that your Perl program needs are available in the
3499 version of "Sys::Guestfs" that you are using?
3500 To test if a particular function is available in the "Sys::Guestfs"
3502 class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
3503 perlobj(1)). For example:
3504 use Sys::Guestfs;
3506 if (defined (Sys::Guestfs->can ("set_verbose"))) {
3507 print "\$h->set_verbose is available\n";
3508 }
3509 Perl does not offer a way to list the arguments of a method, and from
3511 time to time we may add extra arguments to calls that take optional
3512 arguments. For this reason, we provide a global hash variable
3513 %guestfs_introspection which contains the arguments and their types for
3514 each libguestfs method. The keys of this hash are the method names,
3515 and the values are an hashref containing useful introspection
3516 information about the method (further fields may be added to this in
3517 future).
3518 use Sys::Guestfs;
3520 $Sys::Guestfs::guestfs_introspection{mkfs_opts}
3521 => {
3522 ret => 'void', # return type
3523 args => [ # required arguments
3524 [ 'fstype', 'string', 0 ],
3525 [ 'device', 'string(device)', 1 ],
3526 ],
3527 optargs => { # optional arguments
3528 blocksize => [ 'blocksize', 'int', 0 ],
3529 features => [ 'features', 'string', 1 ],
3530 inode => [ 'inode', 'int', 2 ],
3531 sectorsize => [ 'sectorsize', 'int', 3 ],
3532 },
3533 name => "mkfs_opts",
3534 description => "make a filesystem",
3535 }
3536 To test if particular features are supported by the current build, use
3538 the "available" method like the example below. Note that the appliance
3539 must be launched first.
3540 $h->available ( ["augeas"] );
3542 Since the "available" method croaks if the feature is not supported,
3544 you might also want to wrap this in an eval and return a boolean. In
3545 fact this has already been done for you: use "feature_available" in
3546 Sys::Guestfs::Lib(3).
3547 For further discussion on this topic, refer to "AVAILABILITY" in
3549 guestfs(3).
3550
3552 The handle returned from "new" is a hash reference. The hash normally
3553 contains a single element:
3554 {
3556 _g => [private data used by libguestfs]
3557 }
3558 Callers can add other elements to this hash to store data for their own
3560 purposes. The data lasts for the lifetime of the handle.
3561 Any fields whose names begin with an underscore are reserved for
3563 private use by libguestfs. We may add more in future.
3564 It is recommended that callers prefix the name of their field(s) with
3566 some unique string, to avoid conflicts with other users.
3567
3569 Copyright (C) 2009-2011 Red Hat Inc.
3570
3572 Please see the file COPYING.LIB for the full license.
3573
3575 guestfs(3), guestfish(1), <http://libguestfs.org>,
3576 Sys::Guestfs::Lib(3).
3577perl v5.12.4 2011-10-31 Sys::Guestfs(3)