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_qemu (self, qemu):
147 u"""Set the qemu binary that we will use.
149 The default is chosen when the library was compiled by
150 the configure script.
152 You can also override this by setting the
153 "LIBGUESTFS_QEMU" environment variable.
155 The string "qemu" is stashed in the libguestfs handle,
156 so the caller must make sure it remains valid for the
157 lifetime of the handle.
159 Setting "qemu" to "NULL" restores the default qemu
162 return libguestfsmod.set_qemu (self._o, qemu)
165 u"""Return the current qemu binary.
167 This is always non-NULL. If it wasn't set already, then
168 this will return the default qemu binary name.
170 return libguestfsmod.get_qemu (self._o)
172 def set_path (self, path):
173 u"""Set the path that libguestfs searches for kernel and
176 The default is "$libdir/guestfs" unless overridden by
177 setting "LIBGUESTFS_PATH" environment variable.
179 The string "path" is stashed in the libguestfs handle,
180 so the caller must make sure it remains valid for the
181 lifetime of the handle.
183 Setting "path" to "NULL" restores the default path.
185 return libguestfsmod.set_path (self._o, path)
188 u"""Return the current search path.
190 This is always non-NULL. If it wasn't set already, then
191 this will return the default path.
193 return libguestfsmod.get_path (self._o)
195 def set_autosync (self, autosync):
196 u"""If "autosync" is true, this enables autosync. Libguestfs
197 will make a best effort attempt to run "g.umount_all"
198 followed by "g.sync" when the handle is closed (also if
199 the program exits without closing handles).
201 This is disabled by default (except in guestfish where
202 it is enabled by default).
204 return libguestfsmod.set_autosync (self._o, autosync)
206 def get_autosync (self):
207 u"""Get the autosync flag.
209 return libguestfsmod.get_autosync (self._o)
211 def set_verbose (self, verbose):
212 u"""If "verbose" is true, this turns on verbose messages (to
215 Verbose messages are disabled unless the environment
216 variable "LIBGUESTFS_DEBUG" is defined and set to 1.
218 return libguestfsmod.set_verbose (self._o, verbose)
220 def get_verbose (self):
221 u"""This returns the verbose messages flag.
223 return libguestfsmod.get_verbose (self._o)
226 u"""This returns true iff this handle is ready to accept
227 commands (in the "READY" state).
229 For more information on states, see guestfs(3).
231 return libguestfsmod.is_ready (self._o)
233 def is_config (self):
234 u"""This returns true iff this handle is being configured
235 (in the "CONFIG" state).
237 For more information on states, see guestfs(3).
239 return libguestfsmod.is_config (self._o)
241 def is_launching (self):
242 u"""This returns true iff this handle is launching the
243 subprocess (in the "LAUNCHING" state).
245 For more information on states, see guestfs(3).
247 return libguestfsmod.is_launching (self._o)
250 u"""This returns true iff this handle is busy processing a
251 command (in the "BUSY" state).
253 For more information on states, see guestfs(3).
255 return libguestfsmod.is_busy (self._o)
257 def get_state (self):
258 u"""This returns the current state as an opaque integer.
259 This is only useful for printing debug and internal
262 For more information on states, see guestfs(3).
264 return libguestfsmod.get_state (self._o)
267 u"""This sets the state to "BUSY". This is only used when
268 implementing actions using the low-level API.
270 For more information on states, see guestfs(3).
272 return libguestfsmod.set_busy (self._o)
274 def set_ready (self):
275 u"""This sets the state to "READY". This is only used when
276 implementing actions using the low-level API.
278 For more information on states, see guestfs(3).
280 return libguestfsmod.set_ready (self._o)
283 u"""This sets the state to "READY", or if in "CONFIG" then
284 it leaves the state as is. This is only used when
285 implementing actions using the low-level API.
287 For more information on states, see guestfs(3).
289 return libguestfsmod.end_busy (self._o)
291 def mount (self, device, mountpoint):
292 u"""Mount a guest disk at a position in the filesystem.
293 Block devices are named "/dev/sda", "/dev/sdb" and so
294 on, as they were added to the guest. If those block
295 devices contain partitions, they will have the usual
296 names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
299 The rules are the same as for mount(2): A filesystem
300 must first be mounted on "/" before others can be
301 mounted. Other filesystems can only be mounted on
302 directories which already exist.
304 The mounted filesystem is writable, if we have
305 sufficient permissions on the underlying device.
307 The filesystem options "sync" and "noatime" are set with
308 this call, in order to improve reliability.
310 return libguestfsmod.mount (self._o, device, mountpoint)
313 u"""This syncs the disk, so that any writes are flushed
314 through to the underlying disk image.
316 You should always call this if you have modified a disk
317 image, before closing the handle.
319 return libguestfsmod.sync (self._o)
321 def touch (self, path):
322 u"""Touch acts like the touch(1) command. It can be used to
323 update the timestamps on a file, or, if the file does
324 not exist, to create a new zero-length file.
326 return libguestfsmod.touch (self._o, path)
328 def cat (self, path):
329 u"""Return the contents of the file named "path".
331 Note that this function cannot correctly handle binary
332 files (specifically, files containing "\\0" character
333 which is treated as end of string). For those you need
334 to use the "g.download" function which has a more
337 Because of the message protocol, there is a transfer
338 limit of somewhere between 2MB and 4MB. To transfer
339 large files you should use FTP.
341 return libguestfsmod.cat (self._o, path)
343 def ll (self, directory):
344 u"""List the files in "directory" (relative to the root
345 directory, there is no cwd) in the format of 'ls -la'.
347 This command is mostly useful for interactive sessions.
348 It is *not* intended that you try to parse the output
351 return libguestfsmod.ll (self._o, directory)
353 def ls (self, directory):
354 u"""List the files in "directory" (relative to the root
355 directory, there is no cwd). The '.' and '..' entries
356 are not returned, but hidden files are shown.
358 This command is mostly useful for interactive sessions.
359 Programs should probably use "g.readdir" instead.
361 This function returns a list of strings.
363 return libguestfsmod.ls (self._o, directory)
365 def list_devices (self):
366 u"""List all the block devices.
368 The full block device names are returned, eg. "/dev/sda"
370 This function returns a list of strings.
372 return libguestfsmod.list_devices (self._o)
374 def list_partitions (self):
375 u"""List all the partitions detected on all block devices.
377 The full partition device names are returned, eg.
380 This does not return logical volumes. For that you will
381 need to call "g.lvs".
383 This function returns a list of strings.
385 return libguestfsmod.list_partitions (self._o)
388 u"""List all the physical volumes detected. This is the
389 equivalent of the pvs(8) command.
391 This returns a list of just the device names that
392 contain PVs (eg. "/dev/sda2").
394 See also "g.pvs_full".
396 This function returns a list of strings.
398 return libguestfsmod.pvs (self._o)
401 u"""List all the volumes groups detected. This is the
402 equivalent of the vgs(8) command.
404 This returns a list of just the volume group names that
405 were detected (eg. "VolGroup00").
407 See also "g.vgs_full".
409 This function returns a list of strings.
411 return libguestfsmod.vgs (self._o)
414 u"""List all the logical volumes detected. This is the
415 equivalent of the lvs(8) command.
417 This returns a list of the logical volume device names
418 (eg. "/dev/VolGroup00/LogVol00").
420 See also "g.lvs_full".
422 This function returns a list of strings.
424 return libguestfsmod.lvs (self._o)
427 u"""List all the physical volumes detected. This is the
428 equivalent of the pvs(8) command. The "full" version
431 This function returns a list of PVs. Each PV is
432 represented as a dictionary.
434 return libguestfsmod.pvs_full (self._o)
437 u"""List all the volumes groups detected. This is the
438 equivalent of the vgs(8) command. The "full" version
441 This function returns a list of VGs. Each VG is
442 represented as a dictionary.
444 return libguestfsmod.vgs_full (self._o)
447 u"""List all the logical volumes detected. This is the
448 equivalent of the lvs(8) command. The "full" version
451 This function returns a list of LVs. Each LV is
452 represented as a dictionary.
454 return libguestfsmod.lvs_full (self._o)
456 def read_lines (self, path):
457 u"""Return the contents of the file named "path".
459 The file contents are returned as a list of lines.
460 Trailing "LF" and "CRLF" character sequences are *not*
463 Note that this function cannot correctly handle binary
464 files (specifically, files containing "\\0" character
465 which is treated as end of line). For those you need to
466 use the "g.read_file" function which has a more complex
469 This function returns a list of strings.
471 return libguestfsmod.read_lines (self._o, path)
473 def aug_init (self, root, flags):
474 u"""Create a new Augeas handle for editing configuration
475 files. If there was any previous Augeas handle
476 associated with this guestfs session, then it is closed.
478 You must call this before using any other "g.aug_*"
481 "root" is the filesystem root. "root" must not be NULL,
484 The flags are the same as the flags defined in
485 <augeas.h>, the logical *or* of the following integers:
487 "AUG_SAVE_BACKUP" = 1
488 Keep the original file with a ".augsave" extension.
490 "AUG_SAVE_NEWFILE" = 2
491 Save changes into a file with extension ".augnew",
492 and do not overwrite original. Overrides
496 Typecheck lenses (can be expensive).
499 Do not use standard load path for modules.
502 Make save a no-op, just record what would have been
506 Do not load the tree in "g.aug_init".
508 To close the handle, you can call "g.aug_close".
510 To find out more about Augeas, see <http://augeas.net/>.
512 return libguestfsmod.aug_init (self._o, root, flags)
514 def aug_close (self):
515 u"""Close the current Augeas handle and free up any
516 resources used by it. After calling this, you have to
517 call "g.aug_init" again before you can use any other
520 return libguestfsmod.aug_close (self._o)
522 def aug_defvar (self, name, expr):
523 u"""Defines an Augeas variable "name" whose value is the
524 result of evaluating "expr". If "expr" is NULL, then
527 On success this returns the number of nodes in "expr",
528 or 0 if "expr" evaluates to something which is not a
531 return libguestfsmod.aug_defvar (self._o, name, expr)
533 def aug_defnode (self, name, expr, val):
534 u"""Defines a variable "name" whose value is the result of
537 If "expr" evaluates to an empty nodeset, a node is
538 created, equivalent to calling "g.aug_set" "expr",
539 "value". "name" will be the nodeset containing that
542 On success this returns a pair containing the number of
543 nodes in the nodeset, and a boolean flag if a node was
546 This function returns a tuple (int, bool).
548 return libguestfsmod.aug_defnode (self._o, name, expr, val)
550 def aug_get (self, path):
551 u"""Look up the value associated with "path". If "path"
552 matches exactly one node, the "value" is returned.
554 return libguestfsmod.aug_get (self._o, path)
556 def aug_set (self, path, val):
557 u"""Set the value associated with "path" to "value".
559 return libguestfsmod.aug_set (self._o, path, val)
561 def aug_insert (self, path, label, before):
562 u"""Create a new sibling "label" for "path", inserting it
563 into the tree before or after "path" (depending on the
564 boolean flag "before").
566 "path" must match exactly one existing node in the tree,
567 and "label" must be a label, ie. not contain "/", "*" or
568 end with a bracketed index "[N]".
570 return libguestfsmod.aug_insert (self._o, path, label, before)
572 def aug_rm (self, path):
573 u"""Remove "path" and all of its children.
575 On success this returns the number of entries which were
578 return libguestfsmod.aug_rm (self._o, path)
580 def aug_mv (self, src, dest):
581 u"""Move the node "src" to "dest". "src" must match exactly
582 one node. "dest" is overwritten if it exists.
584 return libguestfsmod.aug_mv (self._o, src, dest)
586 def aug_match (self, path):
587 u"""Returns a list of paths which match the path expression
588 "path". The returned paths are sufficiently qualified so
589 that they match exactly one node in the current tree.
591 This function returns a list of strings.
593 return libguestfsmod.aug_match (self._o, path)
596 u"""This writes all pending changes to disk.
598 The flags which were passed to "g.aug_init" affect
599 exactly how files are saved.
601 return libguestfsmod.aug_save (self._o)
604 u"""Load files into the tree.
606 See "aug_load" in the Augeas documentation for the full
609 return libguestfsmod.aug_load (self._o)
611 def aug_ls (self, path):
612 u"""This is just a shortcut for listing "g.aug_match"
613 "path/*" and sorting the resulting nodes into
616 This function returns a list of strings.
618 return libguestfsmod.aug_ls (self._o, path)
621 u"""Remove the single file "path".
623 return libguestfsmod.rm (self._o, path)
625 def rmdir (self, path):
626 u"""Remove the single directory "path".
628 return libguestfsmod.rmdir (self._o, path)
630 def rm_rf (self, path):
631 u"""Remove the file or directory "path", recursively
632 removing the contents if its a directory. This is like
633 the "rm -rf" shell command.
635 return libguestfsmod.rm_rf (self._o, path)
637 def mkdir (self, path):
638 u"""Create a directory named "path".
640 return libguestfsmod.mkdir (self._o, path)
642 def mkdir_p (self, path):
643 u"""Create a directory named "path", creating any parent
644 directories as necessary. This is like the "mkdir -p"
647 return libguestfsmod.mkdir_p (self._o, path)
649 def chmod (self, mode, path):
650 u"""Change the mode (permissions) of "path" to "mode". Only
651 numeric modes are supported.
653 return libguestfsmod.chmod (self._o, mode, path)
655 def chown (self, owner, group, path):
656 u"""Change the file owner to "owner" and group to "group".
658 Only numeric uid and gid are supported. If you want to
659 use names, you will need to locate and parse the
660 password file yourself (Augeas support makes this
663 return libguestfsmod.chown (self._o, owner, group, path)
665 def exists (self, path):
666 u"""This returns "true" if and only if there is a file,
667 directory (or anything) with the given "path" name.
669 See also "g.is_file", "g.is_dir", "g.stat".
671 return libguestfsmod.exists (self._o, path)
673 def is_file (self, path):
674 u"""This returns "true" if and only if there is a file with
675 the given "path" name. Note that it returns false for
676 other objects like directories.
680 return libguestfsmod.is_file (self._o, path)
682 def is_dir (self, path):
683 u"""This returns "true" if and only if there is a directory
684 with the given "path" name. Note that it returns false
685 for other objects like files.
689 return libguestfsmod.is_dir (self._o, path)
691 def pvcreate (self, device):
692 u"""This creates an LVM physical volume on the named
693 "device", where "device" should usually be a partition
694 name such as "/dev/sda1".
696 return libguestfsmod.pvcreate (self._o, device)
698 def vgcreate (self, volgroup, physvols):
699 u"""This creates an LVM volume group called "volgroup" from
700 the non-empty list of physical volumes "physvols".
702 return libguestfsmod.vgcreate (self._o, volgroup, physvols)
704 def lvcreate (self, logvol, volgroup, mbytes):
705 u"""This creates an LVM volume group called "logvol" on the
706 volume group "volgroup", with "size" megabytes.
708 return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
710 def mkfs (self, fstype, device):
711 u"""This creates a filesystem on "device" (usually a
712 partition or LVM logical volume). The filesystem type is
713 "fstype", for example "ext3".
715 return libguestfsmod.mkfs (self._o, fstype, device)
717 def sfdisk (self, device, cyls, heads, sectors, lines):
718 u"""This is a direct interface to the sfdisk(8) program for
719 creating partitions on block devices.
721 "device" should be a block device, for example
724 "cyls", "heads" and "sectors" are the number of
725 cylinders, heads and sectors on the device, which are
726 passed directly to sfdisk as the *-C*, *-H* and *-S*
727 parameters. If you pass 0 for any of these, then the
728 corresponding parameter is omitted. Usually for 'large'
729 disks, you can just pass 0 for these, but for small
730 (floppy-sized) disks, sfdisk (or rather, the kernel)
731 cannot work out the right geometry and you will need to
734 "lines" is a list of lines that we feed to "sfdisk". For
735 more information refer to the sfdisk(8) manpage.
737 To create a single partition occupying the whole disk,
738 you would pass "lines" as a single element list, when
739 the single element being the string "," (comma).
741 This command is dangerous. Without careful use you can
742 easily destroy all your data.
744 return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
746 def write_file (self, path, content, size):
747 u"""This call creates a file called "path". The contents of
748 the file is the string "content" (which can contain any
749 8 bit data), with length "size".
751 As a special case, if "size" is 0 then the length is
752 calculated using "strlen" (so in this case the content
753 cannot contain embedded ASCII NULs).
755 *NB.* Owing to a bug, writing content containing ASCII
756 NUL characters does *not* work, even if the length is
757 specified. We hope to resolve this bug in a future
758 version. In the meantime use "g.upload".
760 Because of the message protocol, there is a transfer
761 limit of somewhere between 2MB and 4MB. To transfer
762 large files you should use FTP.
764 return libguestfsmod.write_file (self._o, path, content, size)
766 def umount (self, pathordevice):
767 u"""This unmounts the given filesystem. The filesystem may
768 be specified either by its mountpoint (path) or the
769 device which contains the filesystem.
771 return libguestfsmod.umount (self._o, pathordevice)
774 u"""This returns the list of currently mounted filesystems.
775 It returns the list of devices (eg. "/dev/sda1",
778 Some internal mounts are not shown.
780 This function returns a list of strings.
782 return libguestfsmod.mounts (self._o)
784 def umount_all (self):
785 u"""This unmounts all mounted filesystems.
787 Some internal mounts are not unmounted by this call.
789 return libguestfsmod.umount_all (self._o)
791 def lvm_remove_all (self):
792 u"""This command removes all LVM logical volumes, volume
793 groups and physical volumes.
795 This command is dangerous. Without careful use you can
796 easily destroy all your data.
798 return libguestfsmod.lvm_remove_all (self._o)
800 def file (self, path):
801 u"""This call uses the standard file(1) command to determine
802 the type or contents of the file. This also works on
803 devices, for example to find out whether a partition
804 contains a filesystem.
806 The exact command which runs is "file -bsL path". Note
807 in particular that the filename is not prepended to the
808 output (the "-b" option).
810 return libguestfsmod.file (self._o, path)
812 def command (self, arguments):
813 u"""This call runs a command from the guest filesystem. The
814 filesystem must be mounted, and must contain a
815 compatible operating system (ie. something Linux, with
816 the same or compatible processor architecture).
818 The single parameter is an argv-style list of arguments.
819 The first element is the name of the program to run.
820 Subsequent elements are parameters. The list must be
821 non-empty (ie. must contain a program name).
823 The return value is anything printed to *stdout* by the
826 If the command returns a non-zero exit status, then this
827 function returns an error message. The error message
828 string is the content of *stderr* from the command.
830 The $PATH environment variable will contain at least
831 "/usr/bin" and "/bin". If you require a program from
832 another location, you should provide the full path in
835 Shared libraries and data files required by the program
836 must be available on filesystems which are mounted in
837 the correct places. It is the caller's responsibility to
838 ensure all filesystems that are needed are mounted at
841 Because of the message protocol, there is a transfer
842 limit of somewhere between 2MB and 4MB. To transfer
843 large files you should use FTP.
845 return libguestfsmod.command (self._o, arguments)
847 def command_lines (self, arguments):
848 u"""This is the same as "g.command", but splits the result
849 into a list of lines.
851 This function returns a list of strings.
853 Because of the message protocol, there is a transfer
854 limit of somewhere between 2MB and 4MB. To transfer
855 large files you should use FTP.
857 return libguestfsmod.command_lines (self._o, arguments)
859 def stat (self, path):
860 u"""Returns file information for the given "path".
862 This is the same as the stat(2) system call.
864 This function returns a dictionary, with keys matching
865 the various fields in the stat structure.
867 return libguestfsmod.stat (self._o, path)
869 def lstat (self, path):
870 u"""Returns file information for the given "path".
872 This is the same as "g.stat" except that if "path" is a
873 symbolic link, then the link is stat-ed, not the file it
876 This is the same as the lstat(2) system call.
878 This function returns a dictionary, with keys matching
879 the various fields in the stat structure.
881 return libguestfsmod.lstat (self._o, path)
883 def statvfs (self, path):
884 u"""Returns file system statistics for any mounted file
885 system. "path" should be a file or directory in the
886 mounted file system (typically it is the mount point
887 itself, but it doesn't need to be).
889 This is the same as the statvfs(2) system call.
891 This function returns a dictionary, with keys matching
892 the various fields in the statvfs structure.
894 return libguestfsmod.statvfs (self._o, path)
896 def tune2fs_l (self, device):
897 u"""This returns the contents of the ext2, ext3 or ext4
898 filesystem superblock on "device".
900 It is the same as running "tune2fs -l device". See
901 tune2fs(8) manpage for more details. The list of fields
902 returned isn't clearly defined, and depends on both the
903 version of "tune2fs" that libguestfs was built against,
904 and the filesystem itself.
906 This function returns a dictionary.
908 return libguestfsmod.tune2fs_l (self._o, device)
910 def blockdev_setro (self, device):
911 u"""Sets the block device named "device" to read-only.
913 This uses the blockdev(8) command.
915 return libguestfsmod.blockdev_setro (self._o, device)
917 def blockdev_setrw (self, device):
918 u"""Sets the block device named "device" to read-write.
920 This uses the blockdev(8) command.
922 return libguestfsmod.blockdev_setrw (self._o, device)
924 def blockdev_getro (self, device):
925 u"""Returns a boolean indicating if the block device is
926 read-only (true if read-only, false if not).
928 This uses the blockdev(8) command.
930 return libguestfsmod.blockdev_getro (self._o, device)
932 def blockdev_getss (self, device):
933 u"""This returns the size of sectors on a block device.
934 Usually 512, but can be larger for modern devices.
936 (Note, this is not the size in sectors, use
937 "g.blockdev_getsz" for that).
939 This uses the blockdev(8) command.
941 return libguestfsmod.blockdev_getss (self._o, device)
943 def blockdev_getbsz (self, device):
944 u"""This returns the block size of a device.
946 (Note this is different from both *size in blocks* and
947 *filesystem block size*).
949 This uses the blockdev(8) command.
951 return libguestfsmod.blockdev_getbsz (self._o, device)
953 def blockdev_setbsz (self, device, blocksize):
954 u"""This sets the block size of a device.
956 (Note this is different from both *size in blocks* and
957 *filesystem block size*).
959 This uses the blockdev(8) command.
961 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
963 def blockdev_getsz (self, device):
964 u"""This returns the size of the device in units of 512-byte
965 sectors (even if the sectorsize isn't 512 bytes ...
968 See also "g.blockdev_getss" for the real sector size of
969 the device, and "g.blockdev_getsize64" for the more
970 useful *size in bytes*.
972 This uses the blockdev(8) command.
974 return libguestfsmod.blockdev_getsz (self._o, device)
976 def blockdev_getsize64 (self, device):
977 u"""This returns the size of the device in bytes.
979 See also "g.blockdev_getsz".
981 This uses the blockdev(8) command.
983 return libguestfsmod.blockdev_getsize64 (self._o, device)
985 def blockdev_flushbufs (self, device):
986 u"""This tells the kernel to flush internal buffers
987 associated with "device".
989 This uses the blockdev(8) command.
991 return libguestfsmod.blockdev_flushbufs (self._o, device)
993 def blockdev_rereadpt (self, device):
994 u"""Reread the partition table on "device".
996 This uses the blockdev(8) command.
998 return libguestfsmod.blockdev_rereadpt (self._o, device)
1000 def upload (self, filename, remotefilename):
1001 u"""Upload local file "filename" to "remotefilename" on the
1004 "filename" can also be a named pipe.
1006 See also "g.download".
1008 return libguestfsmod.upload (self._o, filename, remotefilename)
1010 def download (self, remotefilename, filename):
1011 u"""Download file "remotefilename" and save it as "filename"
1012 on the local machine.
1014 "filename" can also be a named pipe.
1016 See also "g.upload", "g.cat".
1018 return libguestfsmod.download (self._o, remotefilename, filename)
1020 def checksum (self, csumtype, path):
1021 u"""This call computes the MD5, SHAx or CRC checksum of the
1024 The type of checksum to compute is given by the
1025 "csumtype" parameter which must have one of the
1029 Compute the cyclic redundancy check (CRC) specified
1030 by POSIX for the "cksum" command.
1033 Compute the MD5 hash (using the "md5sum" program).
1036 Compute the SHA1 hash (using the "sha1sum" program).
1039 Compute the SHA224 hash (using the "sha224sum"
1043 Compute the SHA256 hash (using the "sha256sum"
1047 Compute the SHA384 hash (using the "sha384sum"
1051 Compute the SHA512 hash (using the "sha512sum"
1054 The checksum is returned as a printable string.
1056 return libguestfsmod.checksum (self._o, csumtype, path)
1058 def tar_in (self, tarfile, directory):
1059 u"""This command uploads and unpacks local file "tarfile"
1060 (an *uncompressed* tar file) into "directory".
1062 To upload a compressed tarball, use "g.tgz_in".
1064 return libguestfsmod.tar_in (self._o, tarfile, directory)
1066 def tar_out (self, directory, tarfile):
1067 u"""This command packs the contents of "directory" and
1068 downloads it to local file "tarfile".
1070 To download a compressed tarball, use "g.tgz_out".
1072 return libguestfsmod.tar_out (self._o, directory, tarfile)
1074 def tgz_in (self, tarball, directory):
1075 u"""This command uploads and unpacks local file "tarball" (a
1076 *gzip compressed* tar file) into "directory".
1078 To upload an uncompressed tarball, use "g.tar_in".
1080 return libguestfsmod.tgz_in (self._o, tarball, directory)
1082 def tgz_out (self, directory, tarball):
1083 u"""This command packs the contents of "directory" and
1084 downloads it to local file "tarball".
1086 To download an uncompressed tarball, use "g.tar_out".
1088 return libguestfsmod.tgz_out (self._o, directory, tarball)
1090 def mount_ro (self, device, mountpoint):
1091 u"""This is the same as the "g.mount" command, but it mounts
1092 the filesystem with the read-only (*-o ro*) flag.
1094 return libguestfsmod.mount_ro (self._o, device, mountpoint)
1096 def mount_options (self, options, device, mountpoint):
1097 u"""This is the same as the "g.mount" command, but it allows
1098 you to set the mount options as for the mount(8) *-o*
1101 return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1103 def mount_vfs (self, options, vfstype, device, mountpoint):
1104 u"""This is the same as the "g.mount" command, but it allows
1105 you to set both the mount options and the vfstype as for
1106 the mount(8) *-o* and *-t* flags.
1108 return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1110 def debug (self, subcmd, extraargs):
1111 u"""The "g.debug" command exposes some internals of
1112 "guestfsd" (the guestfs daemon) that runs inside the
1115 There is no comprehensive help for this command. You
1116 have to look at the file "daemon/debug.c" in the
1117 libguestfs source to find out what you can do.
1119 return libguestfsmod.debug (self._o, subcmd, extraargs)
1121 def lvremove (self, device):
1122 u"""Remove an LVM logical volume "device", where "device" is
1123 the path to the LV, such as "/dev/VG/LV".
1125 You can also remove all LVs in a volume group by
1126 specifying the VG name, "/dev/VG".
1128 return libguestfsmod.lvremove (self._o, device)
1130 def vgremove (self, vgname):
1131 u"""Remove an LVM volume group "vgname", (for example "VG").
1133 This also forcibly removes all logical volumes in the
1134 volume group (if any).
1136 return libguestfsmod.vgremove (self._o, vgname)
1138 def pvremove (self, device):
1139 u"""This wipes a physical volume "device" so that LVM will
1140 no longer recognise it.
1142 The implementation uses the "pvremove" command which
1143 refuses to wipe physical volumes that contain any volume
1144 groups, so you have to remove those first.
1146 return libguestfsmod.pvremove (self._o, device)
1148 def set_e2label (self, device, label):
1149 u"""This sets the ext2/3/4 filesystem label of the
1150 filesystem on "device" to "label". Filesystem labels are
1151 limited to 16 characters.
1153 You can use either "g.tune2fs_l" or "g.get_e2label" to
1154 return the existing label on a filesystem.
1156 return libguestfsmod.set_e2label (self._o, device, label)
1158 def get_e2label (self, device):
1159 u"""This returns the ext2/3/4 filesystem label of the
1160 filesystem on "device".
1162 return libguestfsmod.get_e2label (self._o, device)
1164 def set_e2uuid (self, device, uuid):
1165 u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1166 on "device" to "uuid". The format of the UUID and
1167 alternatives such as "clear", "random" and "time" are
1168 described in the tune2fs(8) manpage.
1170 You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1171 return the existing UUID of a filesystem.
1173 return libguestfsmod.set_e2uuid (self._o, device, uuid)
1175 def get_e2uuid (self, device):
1176 u"""This returns the ext2/3/4 filesystem UUID of the
1177 filesystem on "device".
1179 return libguestfsmod.get_e2uuid (self._o, device)
1181 def fsck (self, fstype, device):
1182 u"""This runs the filesystem checker (fsck) on "device"
1183 which should have filesystem type "fstype".
1185 The returned integer is the status. See fsck(8) for the
1186 list of status codes from "fsck".
1190 * Multiple status codes can be summed together.
1192 * A non-zero return code can mean "success", for
1193 example if errors have been corrected on the
1196 * Checking or repairing NTFS volumes is not supported
1199 This command is entirely equivalent to running "fsck -a
1202 return libguestfsmod.fsck (self._o, fstype, device)
1204 def zero (self, device):
1205 u"""This command writes zeroes over the first few blocks of
1208 How many blocks are zeroed isn't specified (but it's
1209 *not* enough to securely wipe the device). It should be
1210 sufficient to remove any partition tables, filesystem
1211 superblocks and so on.
1213 return libguestfsmod.zero (self._o, device)
1215 def grub_install (self, root, device):
1216 u"""This command installs GRUB (the Grand Unified
1217 Bootloader) on "device", with the root directory being
1220 return libguestfsmod.grub_install (self._o, root, device)
1222 def cp (self, src, dest):
1223 u"""This copies a file from "src" to "dest" where "dest" is
1224 either a destination filename or destination directory.
1226 return libguestfsmod.cp (self._o, src, dest)
1228 def cp_a (self, src, dest):
1229 u"""This copies a file or directory from "src" to "dest"
1230 recursively using the "cp -a" command.
1232 return libguestfsmod.cp_a (self._o, src, dest)
1234 def mv (self, src, dest):
1235 u"""This moves a file from "src" to "dest" where "dest" is
1236 either a destination filename or destination directory.
1238 return libguestfsmod.mv (self._o, src, dest)
1240 def drop_caches (self, whattodrop):
1241 u"""This instructs the guest kernel to drop its page cache,
1242 and/or dentries and inode caches. The parameter
1243 "whattodrop" tells the kernel what precisely to drop,
1244 see <http://linux-mm.org/Drop_Caches>
1246 Setting "whattodrop" to 3 should drop everything.
1248 This automatically calls sync(2) before the operation,
1249 so that the maximum guest memory is freed.
1251 return libguestfsmod.drop_caches (self._o, whattodrop)
1254 u"""This returns the kernel messages ("dmesg" output) from
1255 the guest kernel. This is sometimes useful for extended
1256 debugging of problems.
1258 Another way to get the same information is to enable
1259 verbose messages with "g.set_verbose" or by setting the
1260 environment variable "LIBGUESTFS_DEBUG=1" before running
1263 return libguestfsmod.dmesg (self._o)
1265 def ping_daemon (self):
1266 u"""This is a test probe into the guestfs daemon running
1267 inside the qemu subprocess. Calling this function checks
1268 that the daemon responds to the ping message, without
1269 affecting the daemon or attached block device(s) in any
1272 return libguestfsmod.ping_daemon (self._o)
1274 def equal (self, file1, file2):
1275 u"""This compares the two files "file1" and "file2" and
1276 returns true if their content is exactly equal, or false
1279 The external cmp(1) program is used for the comparison.
1281 return libguestfsmod.equal (self._o, file1, file2)
1283 def strings (self, path):
1284 u"""This runs the strings(1) command on a file and returns
1285 the list of printable strings found.
1287 This function returns a list of strings.
1289 Because of the message protocol, there is a transfer
1290 limit of somewhere between 2MB and 4MB. To transfer
1291 large files you should use FTP.
1293 return libguestfsmod.strings (self._o, path)
1295 def strings_e (self, encoding, path):
1296 u"""This is like the "g.strings" command, but allows you to
1297 specify the encoding.
1299 See the strings(1) manpage for the full list of
1302 Commonly useful encodings are "l" (lower case L) which
1303 will show strings inside Windows/x86 files.
1305 The returned strings are transcoded to UTF-8.
1307 This function returns a list of strings.
1309 Because of the message protocol, there is a transfer
1310 limit of somewhere between 2MB and 4MB. To transfer
1311 large files you should use FTP.
1313 return libguestfsmod.strings_e (self._o, encoding, path)
1315 def hexdump (self, path):
1316 u"""This runs "hexdump -C" on the given "path". The result
1317 is the human-readable, canonical hex dump of the file.
1319 Because of the message protocol, there is a transfer
1320 limit of somewhere between 2MB and 4MB. To transfer
1321 large files you should use FTP.
1323 return libguestfsmod.hexdump (self._o, path)