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 $PATH environment variable will contain at least
824 "/usr/bin" and "/bin". If you require a program from
825 another location, you should provide the full path in
828 Shared libraries and data files required by the program
829 must be available on filesystems which are mounted in
830 the correct places. It is the caller's responsibility to
831 ensure all filesystems that are needed are mounted at
834 return libguestfsmod.command (self._o, arguments)
836 def command_lines (self, arguments):
837 u"""This is the same as "g.command", but splits the result
838 into a list of lines.
840 This function returns a list of strings.
842 return libguestfsmod.command_lines (self._o, arguments)
844 def stat (self, path):
845 u"""Returns file information for the given "path".
847 This is the same as the stat(2) system call.
849 This function returns a dictionary, with keys matching
850 the various fields in the stat structure.
852 return libguestfsmod.stat (self._o, path)
854 def lstat (self, path):
855 u"""Returns file information for the given "path".
857 This is the same as "g.stat" except that if "path" is a
858 symbolic link, then the link is stat-ed, not the file it
861 This is the same as the lstat(2) system call.
863 This function returns a dictionary, with keys matching
864 the various fields in the stat structure.
866 return libguestfsmod.lstat (self._o, path)
868 def statvfs (self, path):
869 u"""Returns file system statistics for any mounted file
870 system. "path" should be a file or directory in the
871 mounted file system (typically it is the mount point
872 itself, but it doesn't need to be).
874 This is the same as the statvfs(2) system call.
876 This function returns a dictionary, with keys matching
877 the various fields in the statvfs structure.
879 return libguestfsmod.statvfs (self._o, path)
881 def tune2fs_l (self, device):
882 u"""This returns the contents of the ext2, ext3 or ext4
883 filesystem superblock on "device".
885 It is the same as running "tune2fs -l device". See
886 tune2fs(8) manpage for more details. The list of fields
887 returned isn't clearly defined, and depends on both the
888 version of "tune2fs" that libguestfs was built against,
889 and the filesystem itself.
891 This function returns a dictionary.
893 return libguestfsmod.tune2fs_l (self._o, device)
895 def blockdev_setro (self, device):
896 u"""Sets the block device named "device" to read-only.
898 This uses the blockdev(8) command.
900 return libguestfsmod.blockdev_setro (self._o, device)
902 def blockdev_setrw (self, device):
903 u"""Sets the block device named "device" to read-write.
905 This uses the blockdev(8) command.
907 return libguestfsmod.blockdev_setrw (self._o, device)
909 def blockdev_getro (self, device):
910 u"""Returns a boolean indicating if the block device is
911 read-only (true if read-only, false if not).
913 This uses the blockdev(8) command.
915 return libguestfsmod.blockdev_getro (self._o, device)
917 def blockdev_getss (self, device):
918 u"""This returns the size of sectors on a block device.
919 Usually 512, but can be larger for modern devices.
921 (Note, this is not the size in sectors, use
922 "g.blockdev_getsz" for that).
924 This uses the blockdev(8) command.
926 return libguestfsmod.blockdev_getss (self._o, device)
928 def blockdev_getbsz (self, device):
929 u"""This returns the block size of a device.
931 (Note this is different from both *size in blocks* and
932 *filesystem block size*).
934 This uses the blockdev(8) command.
936 return libguestfsmod.blockdev_getbsz (self._o, device)
938 def blockdev_setbsz (self, device, blocksize):
939 u"""This sets the block size of a device.
941 (Note this is different from both *size in blocks* and
942 *filesystem block size*).
944 This uses the blockdev(8) command.
946 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
948 def blockdev_getsz (self, device):
949 u"""This returns the size of the device in units of 512-byte
950 sectors (even if the sectorsize isn't 512 bytes ...
953 See also "g.blockdev_getss" for the real sector size of
954 the device, and "g.blockdev_getsize64" for the more
955 useful *size in bytes*.
957 This uses the blockdev(8) command.
959 return libguestfsmod.blockdev_getsz (self._o, device)
961 def blockdev_getsize64 (self, device):
962 u"""This returns the size of the device in bytes.
964 See also "g.blockdev_getsz".
966 This uses the blockdev(8) command.
968 return libguestfsmod.blockdev_getsize64 (self._o, device)
970 def blockdev_flushbufs (self, device):
971 u"""This tells the kernel to flush internal buffers
972 associated with "device".
974 This uses the blockdev(8) command.
976 return libguestfsmod.blockdev_flushbufs (self._o, device)
978 def blockdev_rereadpt (self, device):
979 u"""Reread the partition table on "device".
981 This uses the blockdev(8) command.
983 return libguestfsmod.blockdev_rereadpt (self._o, device)
985 def upload (self, filename, remotefilename):
986 u"""Upload local file "filename" to "remotefilename" on the
989 "filename" can also be a named pipe.
991 See also "g.download".
993 return libguestfsmod.upload (self._o, filename, remotefilename)
995 def download (self, remotefilename, filename):
996 u"""Download file "remotefilename" and save it as "filename"
997 on the local machine.
999 "filename" can also be a named pipe.
1001 See also "g.upload", "g.cat".
1003 return libguestfsmod.download (self._o, remotefilename, filename)
1005 def checksum (self, csumtype, path):
1006 u"""This call computes the MD5, SHAx or CRC checksum of the
1009 The type of checksum to compute is given by the
1010 "csumtype" parameter which must have one of the
1014 Compute the cyclic redundancy check (CRC) specified
1015 by POSIX for the "cksum" command.
1018 Compute the MD5 hash (using the "md5sum" program).
1021 Compute the SHA1 hash (using the "sha1sum" program).
1024 Compute the SHA224 hash (using the "sha224sum"
1028 Compute the SHA256 hash (using the "sha256sum"
1032 Compute the SHA384 hash (using the "sha384sum"
1036 Compute the SHA512 hash (using the "sha512sum"
1039 The checksum is returned as a printable string.
1041 return libguestfsmod.checksum (self._o, csumtype, path)
1043 def tar_in (self, tarfile, directory):
1044 u"""This command uploads and unpacks local file "tarfile"
1045 (an *uncompressed* tar file) into "directory".
1047 To upload a compressed tarball, use "g.tgz_in".
1049 return libguestfsmod.tar_in (self._o, tarfile, directory)
1051 def tar_out (self, directory, tarfile):
1052 u"""This command packs the contents of "directory" and
1053 downloads it to local file "tarfile".
1055 To download a compressed tarball, use "g.tgz_out".
1057 return libguestfsmod.tar_out (self._o, directory, tarfile)
1059 def tgz_in (self, tarball, directory):
1060 u"""This command uploads and unpacks local file "tarball" (a
1061 *gzip compressed* tar file) into "directory".
1063 To upload an uncompressed tarball, use "g.tar_in".
1065 return libguestfsmod.tgz_in (self._o, tarball, directory)
1067 def tgz_out (self, directory, tarball):
1068 u"""This command packs the contents of "directory" and
1069 downloads it to local file "tarball".
1071 To download an uncompressed tarball, use "g.tar_out".
1073 return libguestfsmod.tgz_out (self._o, directory, tarball)
1075 def mount_ro (self, device, mountpoint):
1076 u"""This is the same as the "g.mount" command, but it mounts
1077 the filesystem with the read-only (*-o ro*) flag.
1079 return libguestfsmod.mount_ro (self._o, device, mountpoint)
1081 def mount_options (self, options, device, mountpoint):
1082 u"""This is the same as the "g.mount" command, but it allows
1083 you to set the mount options as for the mount(8) *-o*
1086 return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1088 def mount_vfs (self, options, vfstype, device, mountpoint):
1089 u"""This is the same as the "g.mount" command, but it allows
1090 you to set both the mount options and the vfstype as for
1091 the mount(8) *-o* and *-t* flags.
1093 return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1095 def debug (self, subcmd, extraargs):
1096 u"""The "g.debug" command exposes some internals of
1097 "guestfsd" (the guestfs daemon) that runs inside the
1100 There is no comprehensive help for this command. You
1101 have to look at the file "daemon/debug.c" in the
1102 libguestfs source to find out what you can do.
1104 return libguestfsmod.debug (self._o, subcmd, extraargs)
1106 def lvremove (self, device):
1107 u"""Remove an LVM logical volume "device", where "device" is
1108 the path to the LV, such as "/dev/VG/LV".
1110 You can also remove all LVs in a volume group by
1111 specifying the VG name, "/dev/VG".
1113 return libguestfsmod.lvremove (self._o, device)
1115 def vgremove (self, vgname):
1116 u"""Remove an LVM volume group "vgname", (for example "VG").
1118 This also forcibly removes all logical volumes in the
1119 volume group (if any).
1121 return libguestfsmod.vgremove (self._o, vgname)
1123 def pvremove (self, device):
1124 u"""This wipes a physical volume "device" so that LVM will
1125 no longer recognise it.
1127 The implementation uses the "pvremove" command which
1128 refuses to wipe physical volumes that contain any volume
1129 groups, so you have to remove those first.
1131 return libguestfsmod.pvremove (self._o, device)
1133 def set_e2label (self, device, label):
1134 u"""This sets the ext2/3/4 filesystem label of the
1135 filesystem on "device" to "label". Filesystem labels are
1136 limited to 16 characters.
1138 You can use either "g.tune2fs_l" or "g.get_e2label" to
1139 return the existing label on a filesystem.
1141 return libguestfsmod.set_e2label (self._o, device, label)
1143 def get_e2label (self, device):
1144 u"""This returns the ext2/3/4 filesystem label of the
1145 filesystem on "device".
1147 return libguestfsmod.get_e2label (self._o, device)
1149 def set_e2uuid (self, device, uuid):
1150 u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1151 on "device" to "uuid". The format of the UUID and
1152 alternatives such as "clear", "random" and "time" are
1153 described in the tune2fs(8) manpage.
1155 You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1156 return the existing UUID of a filesystem.
1158 return libguestfsmod.set_e2uuid (self._o, device, uuid)
1160 def get_e2uuid (self, device):
1161 u"""This returns the ext2/3/4 filesystem UUID of the
1162 filesystem on "device".
1164 return libguestfsmod.get_e2uuid (self._o, device)
1166 def fsck (self, fstype, device):
1167 u"""This runs the filesystem checker (fsck) on "device"
1168 which should have filesystem type "fstype".
1170 The returned integer is the status. See fsck(8) for the
1171 list of status codes from "fsck".
1175 * Multiple status codes can be summed together.
1177 * A non-zero return code can mean "success", for
1178 example if errors have been corrected on the
1181 * Checking or repairing NTFS volumes is not supported
1184 This command is entirely equivalent to running "fsck -a
1187 return libguestfsmod.fsck (self._o, fstype, device)
1189 def zero (self, device):
1190 u"""This command writes zeroes over the first few blocks of
1193 How many blocks are zeroed isn't specified (but it's
1194 *not* enough to securely wipe the device). It should be
1195 sufficient to remove any partition tables, filesystem
1196 superblocks and so on.
1198 return libguestfsmod.zero (self._o, device)
1200 def grub_install (self, root, device):
1201 u"""This command installs GRUB (the Grand Unified
1202 Bootloader) on "device", with the root directory being
1205 return libguestfsmod.grub_install (self._o, root, device)
1207 def cp (self, src, dest):
1208 u"""This copies a file from "src" to "dest" where "dest" is
1209 either a destination filename or destination directory.
1211 return libguestfsmod.cp (self._o, src, dest)
1213 def cp_a (self, src, dest):
1214 u"""This copies a file or directory from "src" to "dest"
1215 recursively using the "cp -a" command.
1217 return libguestfsmod.cp_a (self._o, src, dest)
1219 def mv (self, src, dest):
1220 u"""This moves a file from "src" to "dest" where "dest" is
1221 either a destination filename or destination directory.
1223 return libguestfsmod.mv (self._o, src, dest)
1225 def drop_caches (self, whattodrop):
1226 u"""This instructs the guest kernel to drop its page cache,
1227 and/or dentries and inode caches. The parameter
1228 "whattodrop" tells the kernel what precisely to drop,
1229 see <http://linux-mm.org/Drop_Caches>
1231 Setting "whattodrop" to 3 should drop everything.
1233 This automatically calls sync(2) before the operation,
1234 so that the maximum guest memory is freed.
1236 return libguestfsmod.drop_caches (self._o, whattodrop)
1239 u"""This returns the kernel messages ("dmesg" output) from
1240 the guest kernel. This is sometimes useful for extended
1241 debugging of problems.
1243 Another way to get the same information is to enable
1244 verbose messages with "g.set_verbose" or by setting the
1245 environment variable "LIBGUESTFS_DEBUG=1" before running
1248 return libguestfsmod.dmesg (self._o)
1250 def ping_daemon (self):
1251 u"""This is a test probe into the guestfs daemon running
1252 inside the qemu subprocess. Calling this function checks
1253 that the daemon responds to the ping message, without
1254 affecting the daemon or attached block device(s) in any
1257 return libguestfsmod.ping_daemon (self._o)
1259 def equal (self, file1, file2):
1260 u"""This compares the two files "file1" and "file2" and
1261 returns true if their content is exactly equal, or false
1264 The external cmp(1) program is used for the comparison.
1266 return libguestfsmod.equal (self._o, file1, file2)
1268 def strings (self, path):
1269 u"""This runs the strings(1) command on a file and returns
1270 the list of printable strings found.
1272 This function returns a list of strings.
1274 Because of the message protocol, there is a transfer
1275 limit of somewhere between 2MB and 4MB. To transfer
1276 large files you should use FTP.
1278 return libguestfsmod.strings (self._o, path)
1280 def strings_e (self, encoding, path):
1281 u"""This is like the "g.strings" command, but allows you to
1282 specify the encoding.
1284 See the strings(1) manpage for the full list of
1287 Commonly useful encodings are "l" (lower case L) which
1288 will show strings inside Windows/x86 files.
1290 The returned strings are transcoded to UTF-8.
1292 This function returns a list of strings.
1294 Because of the message protocol, there is a transfer
1295 limit of somewhere between 2MB and 4MB. To transfer
1296 large files you should use FTP.
1298 return libguestfsmod.strings_e (self._o, encoding, path)
1300 def hexdump (self, path):
1301 u"""This runs "hexdump -C" on the given "path". The result
1302 is the human-readable, canonical hex dump of the file.
1304 Because of the message protocol, there is a transfer
1305 limit of somewhere between 2MB and 4MB. To transfer
1306 large files you should use FTP.
1308 return libguestfsmod.hexdump (self._o, path)