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_append (self, append):
196 u"""This function is used to add additional options to the
197 guest kernel command line.
199 The default is "NULL" unless overridden by setting
200 "LIBGUESTFS_APPEND" environment variable.
202 The string "append" is stashed in the libguestfs handle,
203 so the caller must make sure it remains valid for the
204 lifetime of the handle.
206 Setting "append" to "NULL" means *no* additional options
207 are passed (libguestfs always adds a few of its own).
209 return libguestfsmod.set_append (self._o, append)
211 def get_append (self):
212 u"""Return the additional kernel options which are added to
213 the guest kernel command line.
215 If "NULL" then no options are added.
217 return libguestfsmod.get_append (self._o)
219 def set_autosync (self, autosync):
220 u"""If "autosync" is true, this enables autosync. Libguestfs
221 will make a best effort attempt to run "g.umount_all"
222 followed by "g.sync" when the handle is closed (also if
223 the program exits without closing handles).
225 This is disabled by default (except in guestfish where
226 it is enabled by default).
228 return libguestfsmod.set_autosync (self._o, autosync)
230 def get_autosync (self):
231 u"""Get the autosync flag.
233 return libguestfsmod.get_autosync (self._o)
235 def set_verbose (self, verbose):
236 u"""If "verbose" is true, this turns on verbose messages (to
239 Verbose messages are disabled unless the environment
240 variable "LIBGUESTFS_DEBUG" is defined and set to 1.
242 return libguestfsmod.set_verbose (self._o, verbose)
244 def get_verbose (self):
245 u"""This returns the verbose messages flag.
247 return libguestfsmod.get_verbose (self._o)
250 u"""This returns true iff this handle is ready to accept
251 commands (in the "READY" state).
253 For more information on states, see guestfs(3).
255 return libguestfsmod.is_ready (self._o)
257 def is_config (self):
258 u"""This returns true iff this handle is being configured
259 (in the "CONFIG" state).
261 For more information on states, see guestfs(3).
263 return libguestfsmod.is_config (self._o)
265 def is_launching (self):
266 u"""This returns true iff this handle is launching the
267 subprocess (in the "LAUNCHING" state).
269 For more information on states, see guestfs(3).
271 return libguestfsmod.is_launching (self._o)
274 u"""This returns true iff this handle is busy processing a
275 command (in the "BUSY" state).
277 For more information on states, see guestfs(3).
279 return libguestfsmod.is_busy (self._o)
281 def get_state (self):
282 u"""This returns the current state as an opaque integer.
283 This is only useful for printing debug and internal
286 For more information on states, see guestfs(3).
288 return libguestfsmod.get_state (self._o)
291 u"""This sets the state to "BUSY". This is only used when
292 implementing actions using the low-level API.
294 For more information on states, see guestfs(3).
296 return libguestfsmod.set_busy (self._o)
298 def set_ready (self):
299 u"""This sets the state to "READY". This is only used when
300 implementing actions using the low-level API.
302 For more information on states, see guestfs(3).
304 return libguestfsmod.set_ready (self._o)
307 u"""This sets the state to "READY", or if in "CONFIG" then
308 it leaves the state as is. This is only used when
309 implementing actions using the low-level API.
311 For more information on states, see guestfs(3).
313 return libguestfsmod.end_busy (self._o)
315 def mount (self, device, mountpoint):
316 u"""Mount a guest disk at a position in the filesystem.
317 Block devices are named "/dev/sda", "/dev/sdb" and so
318 on, as they were added to the guest. If those block
319 devices contain partitions, they will have the usual
320 names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
323 The rules are the same as for mount(2): A filesystem
324 must first be mounted on "/" before others can be
325 mounted. Other filesystems can only be mounted on
326 directories which already exist.
328 The mounted filesystem is writable, if we have
329 sufficient permissions on the underlying device.
331 The filesystem options "sync" and "noatime" are set with
332 this call, in order to improve reliability.
334 return libguestfsmod.mount (self._o, device, mountpoint)
337 u"""This syncs the disk, so that any writes are flushed
338 through to the underlying disk image.
340 You should always call this if you have modified a disk
341 image, before closing the handle.
343 return libguestfsmod.sync (self._o)
345 def touch (self, path):
346 u"""Touch acts like the touch(1) command. It can be used to
347 update the timestamps on a file, or, if the file does
348 not exist, to create a new zero-length file.
350 return libguestfsmod.touch (self._o, path)
352 def cat (self, path):
353 u"""Return the contents of the file named "path".
355 Note that this function cannot correctly handle binary
356 files (specifically, files containing "\\0" character
357 which is treated as end of string). For those you need
358 to use the "g.download" function which has a more
361 Because of the message protocol, there is a transfer
362 limit of somewhere between 2MB and 4MB. To transfer
363 large files you should use FTP.
365 return libguestfsmod.cat (self._o, path)
367 def ll (self, directory):
368 u"""List the files in "directory" (relative to the root
369 directory, there is no cwd) in the format of 'ls -la'.
371 This command is mostly useful for interactive sessions.
372 It is *not* intended that you try to parse the output
375 return libguestfsmod.ll (self._o, directory)
377 def ls (self, directory):
378 u"""List the files in "directory" (relative to the root
379 directory, there is no cwd). The '.' and '..' entries
380 are not returned, but hidden files are shown.
382 This command is mostly useful for interactive sessions.
383 Programs should probably use "g.readdir" instead.
385 This function returns a list of strings.
387 return libguestfsmod.ls (self._o, directory)
389 def list_devices (self):
390 u"""List all the block devices.
392 The full block device names are returned, eg. "/dev/sda"
394 This function returns a list of strings.
396 return libguestfsmod.list_devices (self._o)
398 def list_partitions (self):
399 u"""List all the partitions detected on all block devices.
401 The full partition device names are returned, eg.
404 This does not return logical volumes. For that you will
405 need to call "g.lvs".
407 This function returns a list of strings.
409 return libguestfsmod.list_partitions (self._o)
412 u"""List all the physical volumes detected. This is the
413 equivalent of the pvs(8) command.
415 This returns a list of just the device names that
416 contain PVs (eg. "/dev/sda2").
418 See also "g.pvs_full".
420 This function returns a list of strings.
422 return libguestfsmod.pvs (self._o)
425 u"""List all the volumes groups detected. This is the
426 equivalent of the vgs(8) command.
428 This returns a list of just the volume group names that
429 were detected (eg. "VolGroup00").
431 See also "g.vgs_full".
433 This function returns a list of strings.
435 return libguestfsmod.vgs (self._o)
438 u"""List all the logical volumes detected. This is the
439 equivalent of the lvs(8) command.
441 This returns a list of the logical volume device names
442 (eg. "/dev/VolGroup00/LogVol00").
444 See also "g.lvs_full".
446 This function returns a list of strings.
448 return libguestfsmod.lvs (self._o)
451 u"""List all the physical volumes detected. This is the
452 equivalent of the pvs(8) command. The "full" version
455 This function returns a list of PVs. Each PV is
456 represented as a dictionary.
458 return libguestfsmod.pvs_full (self._o)
461 u"""List all the volumes groups detected. This is the
462 equivalent of the vgs(8) command. The "full" version
465 This function returns a list of VGs. Each VG is
466 represented as a dictionary.
468 return libguestfsmod.vgs_full (self._o)
471 u"""List all the logical volumes detected. This is the
472 equivalent of the lvs(8) command. The "full" version
475 This function returns a list of LVs. Each LV is
476 represented as a dictionary.
478 return libguestfsmod.lvs_full (self._o)
480 def read_lines (self, path):
481 u"""Return the contents of the file named "path".
483 The file contents are returned as a list of lines.
484 Trailing "LF" and "CRLF" character sequences are *not*
487 Note that this function cannot correctly handle binary
488 files (specifically, files containing "\\0" character
489 which is treated as end of line). For those you need to
490 use the "g.read_file" function which has a more complex
493 This function returns a list of strings.
495 return libguestfsmod.read_lines (self._o, path)
497 def aug_init (self, root, flags):
498 u"""Create a new Augeas handle for editing configuration
499 files. If there was any previous Augeas handle
500 associated with this guestfs session, then it is closed.
502 You must call this before using any other "g.aug_*"
505 "root" is the filesystem root. "root" must not be NULL,
508 The flags are the same as the flags defined in
509 <augeas.h>, the logical *or* of the following integers:
511 "AUG_SAVE_BACKUP" = 1
512 Keep the original file with a ".augsave" extension.
514 "AUG_SAVE_NEWFILE" = 2
515 Save changes into a file with extension ".augnew",
516 and do not overwrite original. Overrides
520 Typecheck lenses (can be expensive).
523 Do not use standard load path for modules.
526 Make save a no-op, just record what would have been
530 Do not load the tree in "g.aug_init".
532 To close the handle, you can call "g.aug_close".
534 To find out more about Augeas, see <http://augeas.net/>.
536 return libguestfsmod.aug_init (self._o, root, flags)
538 def aug_close (self):
539 u"""Close the current Augeas handle and free up any
540 resources used by it. After calling this, you have to
541 call "g.aug_init" again before you can use any other
544 return libguestfsmod.aug_close (self._o)
546 def aug_defvar (self, name, expr):
547 u"""Defines an Augeas variable "name" whose value is the
548 result of evaluating "expr". If "expr" is NULL, then
551 On success this returns the number of nodes in "expr",
552 or 0 if "expr" evaluates to something which is not a
555 return libguestfsmod.aug_defvar (self._o, name, expr)
557 def aug_defnode (self, name, expr, val):
558 u"""Defines a variable "name" whose value is the result of
561 If "expr" evaluates to an empty nodeset, a node is
562 created, equivalent to calling "g.aug_set" "expr",
563 "value". "name" will be the nodeset containing that
566 On success this returns a pair containing the number of
567 nodes in the nodeset, and a boolean flag if a node was
570 This function returns a tuple (int, bool).
572 return libguestfsmod.aug_defnode (self._o, name, expr, val)
574 def aug_get (self, path):
575 u"""Look up the value associated with "path". If "path"
576 matches exactly one node, the "value" is returned.
578 return libguestfsmod.aug_get (self._o, path)
580 def aug_set (self, path, val):
581 u"""Set the value associated with "path" to "value".
583 return libguestfsmod.aug_set (self._o, path, val)
585 def aug_insert (self, path, label, before):
586 u"""Create a new sibling "label" for "path", inserting it
587 into the tree before or after "path" (depending on the
588 boolean flag "before").
590 "path" must match exactly one existing node in the tree,
591 and "label" must be a label, ie. not contain "/", "*" or
592 end with a bracketed index "[N]".
594 return libguestfsmod.aug_insert (self._o, path, label, before)
596 def aug_rm (self, path):
597 u"""Remove "path" and all of its children.
599 On success this returns the number of entries which were
602 return libguestfsmod.aug_rm (self._o, path)
604 def aug_mv (self, src, dest):
605 u"""Move the node "src" to "dest". "src" must match exactly
606 one node. "dest" is overwritten if it exists.
608 return libguestfsmod.aug_mv (self._o, src, dest)
610 def aug_match (self, path):
611 u"""Returns a list of paths which match the path expression
612 "path". The returned paths are sufficiently qualified so
613 that they match exactly one node in the current tree.
615 This function returns a list of strings.
617 return libguestfsmod.aug_match (self._o, path)
620 u"""This writes all pending changes to disk.
622 The flags which were passed to "g.aug_init" affect
623 exactly how files are saved.
625 return libguestfsmod.aug_save (self._o)
628 u"""Load files into the tree.
630 See "aug_load" in the Augeas documentation for the full
633 return libguestfsmod.aug_load (self._o)
635 def aug_ls (self, path):
636 u"""This is just a shortcut for listing "g.aug_match"
637 "path/*" and sorting the resulting nodes into
640 This function returns a list of strings.
642 return libguestfsmod.aug_ls (self._o, path)
645 u"""Remove the single file "path".
647 return libguestfsmod.rm (self._o, path)
649 def rmdir (self, path):
650 u"""Remove the single directory "path".
652 return libguestfsmod.rmdir (self._o, path)
654 def rm_rf (self, path):
655 u"""Remove the file or directory "path", recursively
656 removing the contents if its a directory. This is like
657 the "rm -rf" shell command.
659 return libguestfsmod.rm_rf (self._o, path)
661 def mkdir (self, path):
662 u"""Create a directory named "path".
664 return libguestfsmod.mkdir (self._o, path)
666 def mkdir_p (self, path):
667 u"""Create a directory named "path", creating any parent
668 directories as necessary. This is like the "mkdir -p"
671 return libguestfsmod.mkdir_p (self._o, path)
673 def chmod (self, mode, path):
674 u"""Change the mode (permissions) of "path" to "mode". Only
675 numeric modes are supported.
677 return libguestfsmod.chmod (self._o, mode, path)
679 def chown (self, owner, group, path):
680 u"""Change the file owner to "owner" and group to "group".
682 Only numeric uid and gid are supported. If you want to
683 use names, you will need to locate and parse the
684 password file yourself (Augeas support makes this
687 return libguestfsmod.chown (self._o, owner, group, path)
689 def exists (self, path):
690 u"""This returns "true" if and only if there is a file,
691 directory (or anything) with the given "path" name.
693 See also "g.is_file", "g.is_dir", "g.stat".
695 return libguestfsmod.exists (self._o, path)
697 def is_file (self, path):
698 u"""This returns "true" if and only if there is a file with
699 the given "path" name. Note that it returns false for
700 other objects like directories.
704 return libguestfsmod.is_file (self._o, path)
706 def is_dir (self, path):
707 u"""This returns "true" if and only if there is a directory
708 with the given "path" name. Note that it returns false
709 for other objects like files.
713 return libguestfsmod.is_dir (self._o, path)
715 def pvcreate (self, device):
716 u"""This creates an LVM physical volume on the named
717 "device", where "device" should usually be a partition
718 name such as "/dev/sda1".
720 return libguestfsmod.pvcreate (self._o, device)
722 def vgcreate (self, volgroup, physvols):
723 u"""This creates an LVM volume group called "volgroup" from
724 the non-empty list of physical volumes "physvols".
726 return libguestfsmod.vgcreate (self._o, volgroup, physvols)
728 def lvcreate (self, logvol, volgroup, mbytes):
729 u"""This creates an LVM volume group called "logvol" on the
730 volume group "volgroup", with "size" megabytes.
732 return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
734 def mkfs (self, fstype, device):
735 u"""This creates a filesystem on "device" (usually a
736 partition or LVM logical volume). The filesystem type is
737 "fstype", for example "ext3".
739 return libguestfsmod.mkfs (self._o, fstype, device)
741 def sfdisk (self, device, cyls, heads, sectors, lines):
742 u"""This is a direct interface to the sfdisk(8) program for
743 creating partitions on block devices.
745 "device" should be a block device, for example
748 "cyls", "heads" and "sectors" are the number of
749 cylinders, heads and sectors on the device, which are
750 passed directly to sfdisk as the *-C*, *-H* and *-S*
751 parameters. If you pass 0 for any of these, then the
752 corresponding parameter is omitted. Usually for 'large'
753 disks, you can just pass 0 for these, but for small
754 (floppy-sized) disks, sfdisk (or rather, the kernel)
755 cannot work out the right geometry and you will need to
758 "lines" is a list of lines that we feed to "sfdisk". For
759 more information refer to the sfdisk(8) manpage.
761 To create a single partition occupying the whole disk,
762 you would pass "lines" as a single element list, when
763 the single element being the string "," (comma).
765 This command is dangerous. Without careful use you can
766 easily destroy all your data.
768 return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
770 def write_file (self, path, content, size):
771 u"""This call creates a file called "path". The contents of
772 the file is the string "content" (which can contain any
773 8 bit data), with length "size".
775 As a special case, if "size" is 0 then the length is
776 calculated using "strlen" (so in this case the content
777 cannot contain embedded ASCII NULs).
779 *NB.* Owing to a bug, writing content containing ASCII
780 NUL characters does *not* work, even if the length is
781 specified. We hope to resolve this bug in a future
782 version. In the meantime use "g.upload".
784 Because of the message protocol, there is a transfer
785 limit of somewhere between 2MB and 4MB. To transfer
786 large files you should use FTP.
788 return libguestfsmod.write_file (self._o, path, content, size)
790 def umount (self, pathordevice):
791 u"""This unmounts the given filesystem. The filesystem may
792 be specified either by its mountpoint (path) or the
793 device which contains the filesystem.
795 return libguestfsmod.umount (self._o, pathordevice)
798 u"""This returns the list of currently mounted filesystems.
799 It returns the list of devices (eg. "/dev/sda1",
802 Some internal mounts are not shown.
804 This function returns a list of strings.
806 return libguestfsmod.mounts (self._o)
808 def umount_all (self):
809 u"""This unmounts all mounted filesystems.
811 Some internal mounts are not unmounted by this call.
813 return libguestfsmod.umount_all (self._o)
815 def lvm_remove_all (self):
816 u"""This command removes all LVM logical volumes, volume
817 groups and physical volumes.
819 This command is dangerous. Without careful use you can
820 easily destroy all your data.
822 return libguestfsmod.lvm_remove_all (self._o)
824 def file (self, path):
825 u"""This call uses the standard file(1) command to determine
826 the type or contents of the file. This also works on
827 devices, for example to find out whether a partition
828 contains a filesystem.
830 The exact command which runs is "file -bsL path". Note
831 in particular that the filename is not prepended to the
832 output (the "-b" option).
834 return libguestfsmod.file (self._o, path)
836 def command (self, arguments):
837 u"""This call runs a command from the guest filesystem. The
838 filesystem must be mounted, and must contain a
839 compatible operating system (ie. something Linux, with
840 the same or compatible processor architecture).
842 The single parameter is an argv-style list of arguments.
843 The first element is the name of the program to run.
844 Subsequent elements are parameters. The list must be
845 non-empty (ie. must contain a program name).
847 The return value is anything printed to *stdout* by the
850 If the command returns a non-zero exit status, then this
851 function returns an error message. The error message
852 string is the content of *stderr* from the command.
854 The $PATH environment variable will contain at least
855 "/usr/bin" and "/bin". If you require a program from
856 another location, you should provide the full path in
859 Shared libraries and data files required by the program
860 must be available on filesystems which are mounted in
861 the correct places. It is the caller's responsibility to
862 ensure all filesystems that are needed are mounted at
865 Because of the message protocol, there is a transfer
866 limit of somewhere between 2MB and 4MB. To transfer
867 large files you should use FTP.
869 return libguestfsmod.command (self._o, arguments)
871 def command_lines (self, arguments):
872 u"""This is the same as "g.command", but splits the result
873 into a list of lines.
875 This function returns a list of strings.
877 Because of the message protocol, there is a transfer
878 limit of somewhere between 2MB and 4MB. To transfer
879 large files you should use FTP.
881 return libguestfsmod.command_lines (self._o, arguments)
883 def stat (self, path):
884 u"""Returns file information for the given "path".
886 This is the same as the stat(2) system call.
888 This function returns a dictionary, with keys matching
889 the various fields in the stat structure.
891 return libguestfsmod.stat (self._o, path)
893 def lstat (self, path):
894 u"""Returns file information for the given "path".
896 This is the same as "g.stat" except that if "path" is a
897 symbolic link, then the link is stat-ed, not the file it
900 This is the same as the lstat(2) system call.
902 This function returns a dictionary, with keys matching
903 the various fields in the stat structure.
905 return libguestfsmod.lstat (self._o, path)
907 def statvfs (self, path):
908 u"""Returns file system statistics for any mounted file
909 system. "path" should be a file or directory in the
910 mounted file system (typically it is the mount point
911 itself, but it doesn't need to be).
913 This is the same as the statvfs(2) system call.
915 This function returns a dictionary, with keys matching
916 the various fields in the statvfs structure.
918 return libguestfsmod.statvfs (self._o, path)
920 def tune2fs_l (self, device):
921 u"""This returns the contents of the ext2, ext3 or ext4
922 filesystem superblock on "device".
924 It is the same as running "tune2fs -l device". See
925 tune2fs(8) manpage for more details. The list of fields
926 returned isn't clearly defined, and depends on both the
927 version of "tune2fs" that libguestfs was built against,
928 and the filesystem itself.
930 This function returns a dictionary.
932 return libguestfsmod.tune2fs_l (self._o, device)
934 def blockdev_setro (self, device):
935 u"""Sets the block device named "device" to read-only.
937 This uses the blockdev(8) command.
939 return libguestfsmod.blockdev_setro (self._o, device)
941 def blockdev_setrw (self, device):
942 u"""Sets the block device named "device" to read-write.
944 This uses the blockdev(8) command.
946 return libguestfsmod.blockdev_setrw (self._o, device)
948 def blockdev_getro (self, device):
949 u"""Returns a boolean indicating if the block device is
950 read-only (true if read-only, false if not).
952 This uses the blockdev(8) command.
954 return libguestfsmod.blockdev_getro (self._o, device)
956 def blockdev_getss (self, device):
957 u"""This returns the size of sectors on a block device.
958 Usually 512, but can be larger for modern devices.
960 (Note, this is not the size in sectors, use
961 "g.blockdev_getsz" for that).
963 This uses the blockdev(8) command.
965 return libguestfsmod.blockdev_getss (self._o, device)
967 def blockdev_getbsz (self, device):
968 u"""This returns the block size of a device.
970 (Note this is different from both *size in blocks* and
971 *filesystem block size*).
973 This uses the blockdev(8) command.
975 return libguestfsmod.blockdev_getbsz (self._o, device)
977 def blockdev_setbsz (self, device, blocksize):
978 u"""This sets the block size of a device.
980 (Note this is different from both *size in blocks* and
981 *filesystem block size*).
983 This uses the blockdev(8) command.
985 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
987 def blockdev_getsz (self, device):
988 u"""This returns the size of the device in units of 512-byte
989 sectors (even if the sectorsize isn't 512 bytes ...
992 See also "g.blockdev_getss" for the real sector size of
993 the device, and "g.blockdev_getsize64" for the more
994 useful *size in bytes*.
996 This uses the blockdev(8) command.
998 return libguestfsmod.blockdev_getsz (self._o, device)
1000 def blockdev_getsize64 (self, device):
1001 u"""This returns the size of the device in bytes.
1003 See also "g.blockdev_getsz".
1005 This uses the blockdev(8) command.
1007 return libguestfsmod.blockdev_getsize64 (self._o, device)
1009 def blockdev_flushbufs (self, device):
1010 u"""This tells the kernel to flush internal buffers
1011 associated with "device".
1013 This uses the blockdev(8) command.
1015 return libguestfsmod.blockdev_flushbufs (self._o, device)
1017 def blockdev_rereadpt (self, device):
1018 u"""Reread the partition table on "device".
1020 This uses the blockdev(8) command.
1022 return libguestfsmod.blockdev_rereadpt (self._o, device)
1024 def upload (self, filename, remotefilename):
1025 u"""Upload local file "filename" to "remotefilename" on the
1028 "filename" can also be a named pipe.
1030 See also "g.download".
1032 return libguestfsmod.upload (self._o, filename, remotefilename)
1034 def download (self, remotefilename, filename):
1035 u"""Download file "remotefilename" and save it as "filename"
1036 on the local machine.
1038 "filename" can also be a named pipe.
1040 See also "g.upload", "g.cat".
1042 return libguestfsmod.download (self._o, remotefilename, filename)
1044 def checksum (self, csumtype, path):
1045 u"""This call computes the MD5, SHAx or CRC checksum of the
1048 The type of checksum to compute is given by the
1049 "csumtype" parameter which must have one of the
1053 Compute the cyclic redundancy check (CRC) specified
1054 by POSIX for the "cksum" command.
1057 Compute the MD5 hash (using the "md5sum" program).
1060 Compute the SHA1 hash (using the "sha1sum" program).
1063 Compute the SHA224 hash (using the "sha224sum"
1067 Compute the SHA256 hash (using the "sha256sum"
1071 Compute the SHA384 hash (using the "sha384sum"
1075 Compute the SHA512 hash (using the "sha512sum"
1078 The checksum is returned as a printable string.
1080 return libguestfsmod.checksum (self._o, csumtype, path)
1082 def tar_in (self, tarfile, directory):
1083 u"""This command uploads and unpacks local file "tarfile"
1084 (an *uncompressed* tar file) into "directory".
1086 To upload a compressed tarball, use "g.tgz_in".
1088 return libguestfsmod.tar_in (self._o, tarfile, directory)
1090 def tar_out (self, directory, tarfile):
1091 u"""This command packs the contents of "directory" and
1092 downloads it to local file "tarfile".
1094 To download a compressed tarball, use "g.tgz_out".
1096 return libguestfsmod.tar_out (self._o, directory, tarfile)
1098 def tgz_in (self, tarball, directory):
1099 u"""This command uploads and unpacks local file "tarball" (a
1100 *gzip compressed* tar file) into "directory".
1102 To upload an uncompressed tarball, use "g.tar_in".
1104 return libguestfsmod.tgz_in (self._o, tarball, directory)
1106 def tgz_out (self, directory, tarball):
1107 u"""This command packs the contents of "directory" and
1108 downloads it to local file "tarball".
1110 To download an uncompressed tarball, use "g.tar_out".
1112 return libguestfsmod.tgz_out (self._o, directory, tarball)
1114 def mount_ro (self, device, mountpoint):
1115 u"""This is the same as the "g.mount" command, but it mounts
1116 the filesystem with the read-only (*-o ro*) flag.
1118 return libguestfsmod.mount_ro (self._o, device, mountpoint)
1120 def mount_options (self, options, device, mountpoint):
1121 u"""This is the same as the "g.mount" command, but it allows
1122 you to set the mount options as for the mount(8) *-o*
1125 return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1127 def mount_vfs (self, options, vfstype, device, mountpoint):
1128 u"""This is the same as the "g.mount" command, but it allows
1129 you to set both the mount options and the vfstype as for
1130 the mount(8) *-o* and *-t* flags.
1132 return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1134 def debug (self, subcmd, extraargs):
1135 u"""The "g.debug" command exposes some internals of
1136 "guestfsd" (the guestfs daemon) that runs inside the
1139 There is no comprehensive help for this command. You
1140 have to look at the file "daemon/debug.c" in the
1141 libguestfs source to find out what you can do.
1143 return libguestfsmod.debug (self._o, subcmd, extraargs)
1145 def lvremove (self, device):
1146 u"""Remove an LVM logical volume "device", where "device" is
1147 the path to the LV, such as "/dev/VG/LV".
1149 You can also remove all LVs in a volume group by
1150 specifying the VG name, "/dev/VG".
1152 return libguestfsmod.lvremove (self._o, device)
1154 def vgremove (self, vgname):
1155 u"""Remove an LVM volume group "vgname", (for example "VG").
1157 This also forcibly removes all logical volumes in the
1158 volume group (if any).
1160 return libguestfsmod.vgremove (self._o, vgname)
1162 def pvremove (self, device):
1163 u"""This wipes a physical volume "device" so that LVM will
1164 no longer recognise it.
1166 The implementation uses the "pvremove" command which
1167 refuses to wipe physical volumes that contain any volume
1168 groups, so you have to remove those first.
1170 return libguestfsmod.pvremove (self._o, device)
1172 def set_e2label (self, device, label):
1173 u"""This sets the ext2/3/4 filesystem label of the
1174 filesystem on "device" to "label". Filesystem labels are
1175 limited to 16 characters.
1177 You can use either "g.tune2fs_l" or "g.get_e2label" to
1178 return the existing label on a filesystem.
1180 return libguestfsmod.set_e2label (self._o, device, label)
1182 def get_e2label (self, device):
1183 u"""This returns the ext2/3/4 filesystem label of the
1184 filesystem on "device".
1186 return libguestfsmod.get_e2label (self._o, device)
1188 def set_e2uuid (self, device, uuid):
1189 u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1190 on "device" to "uuid". The format of the UUID and
1191 alternatives such as "clear", "random" and "time" are
1192 described in the tune2fs(8) manpage.
1194 You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1195 return the existing UUID of a filesystem.
1197 return libguestfsmod.set_e2uuid (self._o, device, uuid)
1199 def get_e2uuid (self, device):
1200 u"""This returns the ext2/3/4 filesystem UUID of the
1201 filesystem on "device".
1203 return libguestfsmod.get_e2uuid (self._o, device)
1205 def fsck (self, fstype, device):
1206 u"""This runs the filesystem checker (fsck) on "device"
1207 which should have filesystem type "fstype".
1209 The returned integer is the status. See fsck(8) for the
1210 list of status codes from "fsck".
1214 * Multiple status codes can be summed together.
1216 * A non-zero return code can mean "success", for
1217 example if errors have been corrected on the
1220 * Checking or repairing NTFS volumes is not supported
1223 This command is entirely equivalent to running "fsck -a
1226 return libguestfsmod.fsck (self._o, fstype, device)
1228 def zero (self, device):
1229 u"""This command writes zeroes over the first few blocks of
1232 How many blocks are zeroed isn't specified (but it's
1233 *not* enough to securely wipe the device). It should be
1234 sufficient to remove any partition tables, filesystem
1235 superblocks and so on.
1237 return libguestfsmod.zero (self._o, device)
1239 def grub_install (self, root, device):
1240 u"""This command installs GRUB (the Grand Unified
1241 Bootloader) on "device", with the root directory being
1244 return libguestfsmod.grub_install (self._o, root, device)
1246 def cp (self, src, dest):
1247 u"""This copies a file from "src" to "dest" where "dest" is
1248 either a destination filename or destination directory.
1250 return libguestfsmod.cp (self._o, src, dest)
1252 def cp_a (self, src, dest):
1253 u"""This copies a file or directory from "src" to "dest"
1254 recursively using the "cp -a" command.
1256 return libguestfsmod.cp_a (self._o, src, dest)
1258 def mv (self, src, dest):
1259 u"""This moves a file from "src" to "dest" where "dest" is
1260 either a destination filename or destination directory.
1262 return libguestfsmod.mv (self._o, src, dest)
1264 def drop_caches (self, whattodrop):
1265 u"""This instructs the guest kernel to drop its page cache,
1266 and/or dentries and inode caches. The parameter
1267 "whattodrop" tells the kernel what precisely to drop,
1268 see <http://linux-mm.org/Drop_Caches>
1270 Setting "whattodrop" to 3 should drop everything.
1272 This automatically calls sync(2) before the operation,
1273 so that the maximum guest memory is freed.
1275 return libguestfsmod.drop_caches (self._o, whattodrop)
1278 u"""This returns the kernel messages ("dmesg" output) from
1279 the guest kernel. This is sometimes useful for extended
1280 debugging of problems.
1282 Another way to get the same information is to enable
1283 verbose messages with "g.set_verbose" or by setting the
1284 environment variable "LIBGUESTFS_DEBUG=1" before running
1287 return libguestfsmod.dmesg (self._o)
1289 def ping_daemon (self):
1290 u"""This is a test probe into the guestfs daemon running
1291 inside the qemu subprocess. Calling this function checks
1292 that the daemon responds to the ping message, without
1293 affecting the daemon or attached block device(s) in any
1296 return libguestfsmod.ping_daemon (self._o)
1298 def equal (self, file1, file2):
1299 u"""This compares the two files "file1" and "file2" and
1300 returns true if their content is exactly equal, or false
1303 The external cmp(1) program is used for the comparison.
1305 return libguestfsmod.equal (self._o, file1, file2)
1307 def strings (self, path):
1308 u"""This runs the strings(1) command on a file and returns
1309 the list of printable strings found.
1311 This function returns a list of strings.
1313 Because of the message protocol, there is a transfer
1314 limit of somewhere between 2MB and 4MB. To transfer
1315 large files you should use FTP.
1317 return libguestfsmod.strings (self._o, path)
1319 def strings_e (self, encoding, path):
1320 u"""This is like the "g.strings" command, but allows you to
1321 specify the encoding.
1323 See the strings(1) manpage for the full list of
1326 Commonly useful encodings are "l" (lower case L) which
1327 will show strings inside Windows/x86 files.
1329 The returned strings are transcoded to UTF-8.
1331 This function returns a list of strings.
1333 Because of the message protocol, there is a transfer
1334 limit of somewhere between 2MB and 4MB. To transfer
1335 large files you should use FTP.
1337 return libguestfsmod.strings_e (self._o, encoding, path)
1339 def hexdump (self, path):
1340 u"""This runs "hexdump -C" on the given "path". The result
1341 is the human-readable, canonical hex dump of the file.
1343 Because of the message protocol, there is a transfer
1344 limit of somewhere between 2MB and 4MB. To transfer
1345 large files you should use FTP.
1347 return libguestfsmod.hexdump (self._o, path)