1 # libguestfs generated file
2 # WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.
3 # ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.
5 # Copyright (C) 2009 Red Hat Inc.
7 # This library is free software; you can redistribute it and/or
8 # modify it under the terms of the GNU Lesser General Public
9 # License as published by the Free Software Foundation; either
10 # version 2 of the License, or (at your option) any later version.
12 # This library is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 # Lesser General Public License for more details.
17 # You should have received a copy of the GNU Lesser General Public
18 # License along with this library; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21 u"""Python bindings for libguestfs
24 g = guestfs.GuestFS ()
25 g.add_drive ("guest.img")
28 parts = g.list_partitions ()
30 The guestfs module provides a Python binding to the libguestfs API
31 for examining and modifying virtual machine disk images.
33 Amongst the things this is good for: making batch configuration
34 changes to guests, getting disk used/free statistics (see also:
35 virt-df), migrating between virtualization systems (see also:
36 virt-p2v), performing partial backups, performing partial guest
37 clones, cloning guests and changing registry/UUID/hostname info, and
40 Libguestfs uses Linux kernel and qemu code, and can access any type of
41 guest filesystem that Linux and qemu can, including but not limited
42 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
43 schemes, qcow, qcow2, vmdk.
45 Libguestfs provides ways to enumerate guest storage (eg. partitions,
46 LVs, what filesystem is in each LV, etc.). It can also run commands
47 in the context of the guest. Also you can access filesystems over FTP.
49 Errors which happen while using the API are turned into Python
50 RuntimeError exceptions.
52 To create a guestfs handle you usually have to perform the following
55 # Create the handle, call add_drive at least once, and possibly
56 # several times if the guest has multiple block devices:
57 g = guestfs.GuestFS ()
58 g.add_drive ("guest.img")
60 # Launch the qemu subprocess and wait for it to become ready:
64 # Now you can issue commands, for example:
72 """Instances of this class are libguestfs API handles."""
75 """Create a new libguestfs handle."""
76 self._o = libguestfsmod.create ()
79 libguestfsmod.close (self._o)
82 u"""Internally libguestfs is implemented by running a
83 virtual machine using qemu(1).
85 You should call this after configuring the handle (eg.
86 adding drives) but before performing any actions.
88 return libguestfsmod.launch (self._o)
90 def wait_ready (self):
91 u"""Internally libguestfs is implemented by running a
92 virtual machine using qemu(1).
94 You should call this after "g.launch" to wait for the
97 return libguestfsmod.wait_ready (self._o)
99 def kill_subprocess (self):
100 u"""This kills the qemu subprocess. You should never need to
103 return libguestfsmod.kill_subprocess (self._o)
105 def add_drive (self, filename):
106 u"""This function adds a virtual machine disk image
107 "filename" to the guest. The first time you call this
108 function, the disk appears as IDE disk 0 ("/dev/sda") in
109 the guest, the second time as "/dev/sdb", and so on.
111 You don't necessarily need to be root when using
112 libguestfs. However you obviously do need sufficient
113 permissions to access the filename for whatever
114 operations you want to perform (ie. read access if you
115 just want to read the image or write access if you want
116 to modify the image).
118 This is equivalent to the qemu parameter "-drive
121 return libguestfsmod.add_drive (self._o, filename)
123 def add_cdrom (self, filename):
124 u"""This function adds a virtual CD-ROM disk image to the
127 This is equivalent to the qemu parameter "-cdrom
130 return libguestfsmod.add_cdrom (self._o, filename)
132 def config (self, qemuparam, qemuvalue):
133 u"""This can be used to add arbitrary qemu command line
134 parameters of the form "-param value". Actually it's not
135 quite arbitrary - we prevent you from setting some
136 parameters which would interfere with parameters that we
139 The first character of "param" string must be a "-"
144 return libguestfsmod.config (self._o, qemuparam, qemuvalue)
146 def set_path (self, path):
147 u"""Set the path that libguestfs searches for kernel and
150 The default is "$libdir/guestfs" unless overridden by
151 setting "LIBGUESTFS_PATH" environment variable.
153 The string "path" is stashed in the libguestfs handle,
154 so the caller must make sure it remains valid for the
155 lifetime of the handle.
157 Setting "path" to "NULL" restores the default path.
159 return libguestfsmod.set_path (self._o, path)
162 u"""Return the current search path.
164 This is always non-NULL. If it wasn't set already, then
165 this will return the default path.
167 return libguestfsmod.get_path (self._o)
169 def set_autosync (self, autosync):
170 u"""If "autosync" is true, this enables autosync. Libguestfs
171 will make a best effort attempt to run "g.sync" when the
172 handle is closed (also if the program exits without
175 return libguestfsmod.set_autosync (self._o, autosync)
177 def get_autosync (self):
178 u"""Get the autosync flag.
180 return libguestfsmod.get_autosync (self._o)
182 def set_verbose (self, verbose):
183 u"""If "verbose" is true, this turns on verbose messages (to
186 Verbose messages are disabled unless the environment
187 variable "LIBGUESTFS_DEBUG" is defined and set to 1.
189 return libguestfsmod.set_verbose (self._o, verbose)
191 def get_verbose (self):
192 u"""This returns the verbose messages flag.
194 return libguestfsmod.get_verbose (self._o)
196 def mount (self, device, mountpoint):
197 u"""Mount a guest disk at a position in the filesystem.
198 Block devices are named "/dev/sda", "/dev/sdb" and so
199 on, as they were added to the guest. If those block
200 devices contain partitions, they will have the usual
201 names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
204 The rules are the same as for mount(2): A filesystem
205 must first be mounted on "/" before others can be
206 mounted. Other filesystems can only be mounted on
207 directories which already exist.
209 The mounted filesystem is writable, if we have
210 sufficient permissions on the underlying device.
212 The filesystem options "sync" and "noatime" are set with
213 this call, in order to improve reliability.
215 return libguestfsmod.mount (self._o, device, mountpoint)
218 u"""This syncs the disk, so that any writes are flushed
219 through to the underlying disk image.
221 You should always call this if you have modified a disk
222 image, before closing the handle.
224 return libguestfsmod.sync (self._o)
226 def touch (self, path):
227 u"""Touch acts like the touch(1) command. It can be used to
228 update the timestamps on a file, or, if the file does
229 not exist, to create a new zero-length file.
231 return libguestfsmod.touch (self._o, path)
233 def cat (self, path):
234 u"""Return the contents of the file named "path".
236 Note that this function cannot correctly handle binary
237 files (specifically, files containing "\\0" character
238 which is treated as end of string). For those you need
239 to use the "g.read_file" function which has a more
242 Because of the message protocol, there is a transfer
243 limit of somewhere between 2MB and 4MB. To transfer
244 large files you should use FTP.
246 return libguestfsmod.cat (self._o, path)
248 def ll (self, directory):
249 u"""List the files in "directory" (relative to the root
250 directory, there is no cwd) in the format of 'ls -la'.
252 This command is mostly useful for interactive sessions.
253 It is *not* intended that you try to parse the output
256 return libguestfsmod.ll (self._o, directory)
258 def ls (self, directory):
259 u"""List the files in "directory" (relative to the root
260 directory, there is no cwd). The '.' and '..' entries
261 are not returned, but hidden files are shown.
263 This command is mostly useful for interactive sessions.
264 Programs should probably use "g.readdir" instead.
266 This function returns a list of strings.
268 return libguestfsmod.ls (self._o, directory)
270 def list_devices (self):
271 u"""List all the block devices.
273 The full block device names are returned, eg. "/dev/sda"
275 This function returns a list of strings.
277 return libguestfsmod.list_devices (self._o)
279 def list_partitions (self):
280 u"""List all the partitions detected on all block devices.
282 The full partition device names are returned, eg.
285 This does not return logical volumes. For that you will
286 need to call "g.lvs".
288 This function returns a list of strings.
290 return libguestfsmod.list_partitions (self._o)
293 u"""List all the physical volumes detected. This is the
294 equivalent of the pvs(8) command.
296 This returns a list of just the device names that
297 contain PVs (eg. "/dev/sda2").
299 See also "g.pvs_full".
301 This function returns a list of strings.
303 return libguestfsmod.pvs (self._o)
306 u"""List all the volumes groups detected. This is the
307 equivalent of the vgs(8) command.
309 This returns a list of just the volume group names that
310 were detected (eg. "VolGroup00").
312 See also "g.vgs_full".
314 This function returns a list of strings.
316 return libguestfsmod.vgs (self._o)
319 u"""List all the logical volumes detected. This is the
320 equivalent of the lvs(8) command.
322 This returns a list of the logical volume device names
323 (eg. "/dev/VolGroup00/LogVol00").
325 See also "g.lvs_full".
327 This function returns a list of strings.
329 return libguestfsmod.lvs (self._o)
332 u"""List all the physical volumes detected. This is the
333 equivalent of the pvs(8) command. The "full" version
336 This function returns a list of PVs. Each PV is
337 represented as a dictionary.
339 return libguestfsmod.pvs_full (self._o)
342 u"""List all the volumes groups detected. This is the
343 equivalent of the vgs(8) command. The "full" version
346 This function returns a list of VGs. Each VG is
347 represented as a dictionary.
349 return libguestfsmod.vgs_full (self._o)
352 u"""List all the logical volumes detected. This is the
353 equivalent of the lvs(8) command. The "full" version
356 This function returns a list of LVs. Each LV is
357 represented as a dictionary.
359 return libguestfsmod.lvs_full (self._o)
361 def read_lines (self, path):
362 u"""Return the contents of the file named "path".
364 The file contents are returned as a list of lines.
365 Trailing "LF" and "CRLF" character sequences are *not*
368 Note that this function cannot correctly handle binary
369 files (specifically, files containing "\\0" character
370 which is treated as end of line). For those you need to
371 use the "g.read_file" function which has a more complex
374 This function returns a list of strings.
376 return libguestfsmod.read_lines (self._o, path)
378 def aug_init (self, root, flags):
379 u"""Create a new Augeas handle for editing configuration
380 files. If there was any previous Augeas handle
381 associated with this guestfs session, then it is closed.
383 You must call this before using any other "g.aug_*"
386 "root" is the filesystem root. "root" must not be NULL,
389 The flags are the same as the flags defined in
390 <augeas.h>, the logical *or* of the following integers:
392 "AUG_SAVE_BACKUP" = 1
393 Keep the original file with a ".augsave" extension.
395 "AUG_SAVE_NEWFILE" = 2
396 Save changes into a file with extension ".augnew",
397 and do not overwrite original. Overrides
401 Typecheck lenses (can be expensive).
404 Do not use standard load path for modules.
407 Make save a no-op, just record what would have been
411 Do not load the tree in "g.aug_init".
413 To close the handle, you can call "g.aug_close".
415 To find out more about Augeas, see <http://augeas.net/>.
417 return libguestfsmod.aug_init (self._o, root, flags)
419 def aug_close (self):
420 u"""Close the current Augeas handle and free up any
421 resources used by it. After calling this, you have to
422 call "g.aug_init" again before you can use any other
425 return libguestfsmod.aug_close (self._o)
427 def aug_defvar (self, name, expr):
428 u"""Defines an Augeas variable "name" whose value is the
429 result of evaluating "expr". If "expr" is NULL, then
432 On success this returns the number of nodes in "expr",
433 or 0 if "expr" evaluates to something which is not a
436 return libguestfsmod.aug_defvar (self._o, name, expr)
438 def aug_defnode (self, name, expr, val):
439 u"""Defines a variable "name" whose value is the result of
442 If "expr" evaluates to an empty nodeset, a node is
443 created, equivalent to calling "g.aug_set" "expr",
444 "value". "name" will be the nodeset containing that
447 On success this returns a pair containing the number of
448 nodes in the nodeset, and a boolean flag if a node was
451 This function returns a tuple (int, bool).
453 return libguestfsmod.aug_defnode (self._o, name, expr, val)
455 def aug_get (self, path):
456 u"""Look up the value associated with "path". If "path"
457 matches exactly one node, the "value" is returned.
459 return libguestfsmod.aug_get (self._o, path)
461 def aug_set (self, path, val):
462 u"""Set the value associated with "path" to "value".
464 return libguestfsmod.aug_set (self._o, path, val)
466 def aug_insert (self, path, label, before):
467 u"""Create a new sibling "label" for "path", inserting it
468 into the tree before or after "path" (depending on the
469 boolean flag "before").
471 "path" must match exactly one existing node in the tree,
472 and "label" must be a label, ie. not contain "/", "*" or
473 end with a bracketed index "[N]".
475 return libguestfsmod.aug_insert (self._o, path, label, before)
477 def aug_rm (self, path):
478 u"""Remove "path" and all of its children.
480 On success this returns the number of entries which were
483 return libguestfsmod.aug_rm (self._o, path)
485 def aug_mv (self, src, dest):
486 u"""Move the node "src" to "dest". "src" must match exactly
487 one node. "dest" is overwritten if it exists.
489 return libguestfsmod.aug_mv (self._o, src, dest)
491 def aug_match (self, path):
492 u"""Returns a list of paths which match the path expression
493 "path". The returned paths are sufficiently qualified so
494 that they match exactly one node in the current tree.
496 This function returns a list of strings.
498 return libguestfsmod.aug_match (self._o, path)
501 u"""This writes all pending changes to disk.
503 The flags which were passed to "g.aug_init" affect
504 exactly how files are saved.
506 return libguestfsmod.aug_save (self._o)
509 u"""Load files into the tree.
511 See "aug_load" in the Augeas documentation for the full
514 return libguestfsmod.aug_load (self._o)
516 def aug_ls (self, path):
517 u"""This is just a shortcut for listing "g.aug_match"
518 "path/*" and sorting the resulting nodes into
521 This function returns a list of strings.
523 return libguestfsmod.aug_ls (self._o, path)
526 u"""Remove the single file "path".
528 return libguestfsmod.rm (self._o, path)
530 def rmdir (self, path):
531 u"""Remove the single directory "path".
533 return libguestfsmod.rmdir (self._o, path)
535 def rm_rf (self, path):
536 u"""Remove the file or directory "path", recursively
537 removing the contents if its a directory. This is like
538 the "rm -rf" shell command.
540 return libguestfsmod.rm_rf (self._o, path)
542 def mkdir (self, path):
543 u"""Create a directory named "path".
545 return libguestfsmod.mkdir (self._o, path)
547 def mkdir_p (self, path):
548 u"""Create a directory named "path", creating any parent
549 directories as necessary. This is like the "mkdir -p"
552 return libguestfsmod.mkdir_p (self._o, path)
554 def chmod (self, mode, path):
555 u"""Change the mode (permissions) of "path" to "mode". Only
556 numeric modes are supported.
558 return libguestfsmod.chmod (self._o, mode, path)
560 def chown (self, owner, group, path):
561 u"""Change the file owner to "owner" and group to "group".
563 Only numeric uid and gid are supported. If you want to
564 use names, you will need to locate and parse the
565 password file yourself (Augeas support makes this
568 return libguestfsmod.chown (self._o, owner, group, path)
570 def exists (self, path):
571 u"""This returns "true" if and only if there is a file,
572 directory (or anything) with the given "path" name.
574 See also "g.is_file", "g.is_dir", "g.stat".
576 return libguestfsmod.exists (self._o, path)
578 def is_file (self, path):
579 u"""This returns "true" if and only if there is a file with
580 the given "path" name. Note that it returns false for
581 other objects like directories.
585 return libguestfsmod.is_file (self._o, path)
587 def is_dir (self, path):
588 u"""This returns "true" if and only if there is a directory
589 with the given "path" name. Note that it returns false
590 for other objects like files.
594 return libguestfsmod.is_dir (self._o, path)
596 def pvcreate (self, device):
597 u"""This creates an LVM physical volume on the named
598 "device", where "device" should usually be a partition
599 name such as "/dev/sda1".
601 return libguestfsmod.pvcreate (self._o, device)
603 def vgcreate (self, volgroup, physvols):
604 u"""This creates an LVM volume group called "volgroup" from
605 the non-empty list of physical volumes "physvols".
607 return libguestfsmod.vgcreate (self._o, volgroup, physvols)
609 def lvcreate (self, logvol, volgroup, mbytes):
610 u"""This creates an LVM volume group called "logvol" on the
611 volume group "volgroup", with "size" megabytes.
613 return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
615 def mkfs (self, fstype, device):
616 u"""This creates a filesystem on "device" (usually a
617 partition of LVM logical volume). The filesystem type is
618 "fstype", for example "ext3".
620 return libguestfsmod.mkfs (self._o, fstype, device)
622 def sfdisk (self, device, cyls, heads, sectors, lines):
623 u"""This is a direct interface to the sfdisk(8) program for
624 creating partitions on block devices.
626 "device" should be a block device, for example
629 "cyls", "heads" and "sectors" are the number of
630 cylinders, heads and sectors on the device, which are
631 passed directly to sfdisk as the *-C*, *-H* and *-S*
632 parameters. If you pass 0 for any of these, then the
633 corresponding parameter is omitted. Usually for 'large'
634 disks, you can just pass 0 for these, but for small
635 (floppy-sized) disks, sfdisk (or rather, the kernel)
636 cannot work out the right geometry and you will need to
639 "lines" is a list of lines that we feed to "sfdisk". For
640 more information refer to the sfdisk(8) manpage.
642 To create a single partition occupying the whole disk,
643 you would pass "lines" as a single element list, when
644 the single element being the string "," (comma).
646 This command is dangerous. Without careful use you can
647 easily destroy all your data.
649 return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
651 def write_file (self, path, content, size):
652 u"""This call creates a file called "path". The contents of
653 the file is the string "content" (which can contain any
654 8 bit data), with length "size".
656 As a special case, if "size" is 0 then the length is
657 calculated using "strlen" (so in this case the content
658 cannot contain embedded ASCII NULs).
660 Because of the message protocol, there is a transfer
661 limit of somewhere between 2MB and 4MB. To transfer
662 large files you should use FTP.
664 return libguestfsmod.write_file (self._o, path, content, size)
666 def umount (self, pathordevice):
667 u"""This unmounts the given filesystem. The filesystem may
668 be specified either by its mountpoint (path) or the
669 device which contains the filesystem.
671 return libguestfsmod.umount (self._o, pathordevice)
674 u"""This returns the list of currently mounted filesystems.
675 It returns the list of devices (eg. "/dev/sda1",
678 Some internal mounts are not shown.
680 This function returns a list of strings.
682 return libguestfsmod.mounts (self._o)
684 def umount_all (self):
685 u"""This unmounts all mounted filesystems.
687 Some internal mounts are not unmounted by this call.
689 return libguestfsmod.umount_all (self._o)
691 def lvm_remove_all (self):
692 u"""This command removes all LVM logical volumes, volume
693 groups and physical volumes.
695 This command is dangerous. Without careful use you can
696 easily destroy all your data.
698 return libguestfsmod.lvm_remove_all (self._o)
700 def file (self, path):
701 u"""This call uses the standard file(1) command to determine
702 the type or contents of the file. This also works on
703 devices, for example to find out whether a partition
704 contains a filesystem.
706 The exact command which runs is "file -bsL path". Note
707 in particular that the filename is not prepended to the
708 output (the "-b" option).
710 return libguestfsmod.file (self._o, path)
712 def command (self, arguments):
713 u"""This call runs a command from the guest filesystem. The
714 filesystem must be mounted, and must contain a
715 compatible operating system (ie. something Linux, with
716 the same or compatible processor architecture).
718 The single parameter is an argv-style list of arguments.
719 The first element is the name of the program to run.
720 Subsequent elements are parameters. The list must be
721 non-empty (ie. must contain a program name).
723 The $PATH environment variable will contain at least
724 "/usr/bin" and "/bin". If you require a program from
725 another location, you should provide the full path in
728 Shared libraries and data files required by the program
729 must be available on filesystems which are mounted in
730 the correct places. It is the caller's responsibility to
731 ensure all filesystems that are needed are mounted at
734 return libguestfsmod.command (self._o, arguments)
736 def command_lines (self, arguments):
737 u"""This is the same as "g.command", but splits the result
738 into a list of lines.
740 This function returns a list of strings.
742 return libguestfsmod.command_lines (self._o, arguments)
744 def stat (self, path):
745 u"""Returns file information for the given "path".
747 This is the same as the stat(2) system call.
749 This function returns a dictionary, with keys matching
750 the various fields in the stat structure.
752 return libguestfsmod.stat (self._o, path)
754 def lstat (self, path):
755 u"""Returns file information for the given "path".
757 This is the same as "g.stat" except that if "path" is a
758 symbolic link, then the link is stat-ed, not the file it
761 This is the same as the lstat(2) system call.
763 This function returns a dictionary, with keys matching
764 the various fields in the stat structure.
766 return libguestfsmod.lstat (self._o, path)
768 def statvfs (self, path):
769 u"""Returns file system statistics for any mounted file
770 system. "path" should be a file or directory in the
771 mounted file system (typically it is the mount point
772 itself, but it doesn't need to be).
774 This is the same as the statvfs(2) system call.
776 This function returns a dictionary, with keys matching
777 the various fields in the statvfs structure.
779 return libguestfsmod.statvfs (self._o, path)
781 def tune2fs_l (self, device):
782 u"""This returns the contents of the ext2 or ext3 filesystem
783 superblock on "device".
785 It is the same as running "tune2fs -l device". See
786 tune2fs(8) manpage for more details. The list of fields
787 returned isn't clearly defined, and depends on both the
788 version of "tune2fs" that libguestfs was built against,
789 and the filesystem itself.
791 This function returns a dictionary.
793 return libguestfsmod.tune2fs_l (self._o, device)
795 def blockdev_setro (self, device):
796 u"""Sets the block device named "device" to read-only.
798 This uses the blockdev(8) command.
800 return libguestfsmod.blockdev_setro (self._o, device)
802 def blockdev_setrw (self, device):
803 u"""Sets the block device named "device" to read-write.
805 This uses the blockdev(8) command.
807 return libguestfsmod.blockdev_setrw (self._o, device)
809 def blockdev_getro (self, device):
810 u"""Returns a boolean indicating if the block device is
811 read-only (true if read-only, false if not).
813 This uses the blockdev(8) command.
815 return libguestfsmod.blockdev_getro (self._o, device)
817 def blockdev_getss (self, device):
818 u"""This returns the size of sectors on a block device.
819 Usually 512, but can be larger for modern devices.
821 (Note, this is not the size in sectors, use
822 "g.blockdev_getsz" for that).
824 This uses the blockdev(8) command.
826 return libguestfsmod.blockdev_getss (self._o, device)
828 def blockdev_getbsz (self, device):
829 u"""This returns the block size of a device.
831 (Note this is different from both *size in blocks* and
832 *filesystem block size*).
834 This uses the blockdev(8) command.
836 return libguestfsmod.blockdev_getbsz (self._o, device)
838 def blockdev_setbsz (self, device, blocksize):
839 u"""This sets the block size of a device.
841 (Note this is different from both *size in blocks* and
842 *filesystem block size*).
844 This uses the blockdev(8) command.
846 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
848 def blockdev_getsz (self, device):
849 u"""This returns the size of the device in units of 512-byte
850 sectors (even if the sectorsize isn't 512 bytes ...
853 See also "g.blockdev_getss" for the real sector size of
854 the device, and "g.blockdev_getsize64" for the more
855 useful *size in bytes*.
857 This uses the blockdev(8) command.
859 return libguestfsmod.blockdev_getsz (self._o, device)
861 def blockdev_getsize64 (self, device):
862 u"""This returns the size of the device in bytes.
864 See also "g.blockdev_getsz".
866 This uses the blockdev(8) command.
868 return libguestfsmod.blockdev_getsize64 (self._o, device)
870 def blockdev_flushbufs (self, device):
871 u"""This tells the kernel to flush internal buffers
872 associated with "device".
874 This uses the blockdev(8) command.
876 return libguestfsmod.blockdev_flushbufs (self._o, device)
878 def blockdev_rereadpt (self, device):
879 u"""Reread the partition table on "device".
881 This uses the blockdev(8) command.
883 return libguestfsmod.blockdev_rereadpt (self._o, device)