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 Setting "qemu" to "NULL" restores the default qemu
158 return libguestfsmod.set_qemu (self._o, qemu)
161 u"""Return the current qemu binary.
163 This is always non-NULL. If it wasn't set already, then
164 this will return the default qemu binary name.
166 return libguestfsmod.get_qemu (self._o)
168 def set_path (self, path):
169 u"""Set the path that libguestfs searches for kernel and
172 The default is "$libdir/guestfs" unless overridden by
173 setting "LIBGUESTFS_PATH" environment variable.
175 Setting "path" to "NULL" restores the default path.
177 return libguestfsmod.set_path (self._o, path)
180 u"""Return the current search path.
182 This is always non-NULL. If it wasn't set already, then
183 this will return the default path.
185 return libguestfsmod.get_path (self._o)
187 def set_append (self, append):
188 u"""This function is used to add additional options to the
189 guest kernel command line.
191 The default is "NULL" unless overridden by setting
192 "LIBGUESTFS_APPEND" environment variable.
194 Setting "append" to "NULL" means *no* additional options
195 are passed (libguestfs always adds a few of its own).
197 return libguestfsmod.set_append (self._o, append)
199 def get_append (self):
200 u"""Return the additional kernel options which are added to
201 the guest kernel command line.
203 If "NULL" then no options are added.
205 return libguestfsmod.get_append (self._o)
207 def set_autosync (self, autosync):
208 u"""If "autosync" is true, this enables autosync. Libguestfs
209 will make a best effort attempt to run "g.umount_all"
210 followed by "g.sync" when the handle is closed (also if
211 the program exits without closing handles).
213 This is disabled by default (except in guestfish where
214 it is enabled by default).
216 return libguestfsmod.set_autosync (self._o, autosync)
218 def get_autosync (self):
219 u"""Get the autosync flag.
221 return libguestfsmod.get_autosync (self._o)
223 def set_verbose (self, verbose):
224 u"""If "verbose" is true, this turns on verbose messages (to
227 Verbose messages are disabled unless the environment
228 variable "LIBGUESTFS_DEBUG" is defined and set to 1.
230 return libguestfsmod.set_verbose (self._o, verbose)
232 def get_verbose (self):
233 u"""This returns the verbose messages flag.
235 return libguestfsmod.get_verbose (self._o)
238 u"""This returns true iff this handle is ready to accept
239 commands (in the "READY" state).
241 For more information on states, see guestfs(3).
243 return libguestfsmod.is_ready (self._o)
245 def is_config (self):
246 u"""This returns true iff this handle is being configured
247 (in the "CONFIG" state).
249 For more information on states, see guestfs(3).
251 return libguestfsmod.is_config (self._o)
253 def is_launching (self):
254 u"""This returns true iff this handle is launching the
255 subprocess (in the "LAUNCHING" state).
257 For more information on states, see guestfs(3).
259 return libguestfsmod.is_launching (self._o)
262 u"""This returns true iff this handle is busy processing a
263 command (in the "BUSY" state).
265 For more information on states, see guestfs(3).
267 return libguestfsmod.is_busy (self._o)
269 def get_state (self):
270 u"""This returns the current state as an opaque integer.
271 This is only useful for printing debug and internal
274 For more information on states, see guestfs(3).
276 return libguestfsmod.get_state (self._o)
279 u"""This sets the state to "BUSY". This is only used when
280 implementing actions using the low-level API.
282 For more information on states, see guestfs(3).
284 return libguestfsmod.set_busy (self._o)
286 def set_ready (self):
287 u"""This sets the state to "READY". This is only used when
288 implementing actions using the low-level API.
290 For more information on states, see guestfs(3).
292 return libguestfsmod.set_ready (self._o)
295 u"""This sets the state to "READY", or if in "CONFIG" then
296 it leaves the state as is. This is only used when
297 implementing actions using the low-level API.
299 For more information on states, see guestfs(3).
301 return libguestfsmod.end_busy (self._o)
303 def mount (self, device, mountpoint):
304 u"""Mount a guest disk at a position in the filesystem.
305 Block devices are named "/dev/sda", "/dev/sdb" and so
306 on, as they were added to the guest. If those block
307 devices contain partitions, they will have the usual
308 names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
311 The rules are the same as for mount(2): A filesystem
312 must first be mounted on "/" before others can be
313 mounted. Other filesystems can only be mounted on
314 directories which already exist.
316 The mounted filesystem is writable, if we have
317 sufficient permissions on the underlying device.
319 The filesystem options "sync" and "noatime" are set with
320 this call, in order to improve reliability.
322 return libguestfsmod.mount (self._o, device, mountpoint)
325 u"""This syncs the disk, so that any writes are flushed
326 through to the underlying disk image.
328 You should always call this if you have modified a disk
329 image, before closing the handle.
331 return libguestfsmod.sync (self._o)
333 def touch (self, path):
334 u"""Touch acts like the touch(1) command. It can be used to
335 update the timestamps on a file, or, if the file does
336 not exist, to create a new zero-length file.
338 return libguestfsmod.touch (self._o, path)
340 def cat (self, path):
341 u"""Return the contents of the file named "path".
343 Note that this function cannot correctly handle binary
344 files (specifically, files containing "\\0" character
345 which is treated as end of string). For those you need
346 to use the "g.download" function which has a more
349 Because of the message protocol, there is a transfer
350 limit of somewhere between 2MB and 4MB. To transfer
351 large files you should use FTP.
353 return libguestfsmod.cat (self._o, path)
355 def ll (self, directory):
356 u"""List the files in "directory" (relative to the root
357 directory, there is no cwd) in the format of 'ls -la'.
359 This command is mostly useful for interactive sessions.
360 It is *not* intended that you try to parse the output
363 return libguestfsmod.ll (self._o, directory)
365 def ls (self, directory):
366 u"""List the files in "directory" (relative to the root
367 directory, there is no cwd). The '.' and '..' entries
368 are not returned, but hidden files are shown.
370 This command is mostly useful for interactive sessions.
371 Programs should probably use "g.readdir" instead.
373 This function returns a list of strings.
375 return libguestfsmod.ls (self._o, directory)
377 def list_devices (self):
378 u"""List all the block devices.
380 The full block device names are returned, eg. "/dev/sda"
382 This function returns a list of strings.
384 return libguestfsmod.list_devices (self._o)
386 def list_partitions (self):
387 u"""List all the partitions detected on all block devices.
389 The full partition device names are returned, eg.
392 This does not return logical volumes. For that you will
393 need to call "g.lvs".
395 This function returns a list of strings.
397 return libguestfsmod.list_partitions (self._o)
400 u"""List all the physical volumes detected. This is the
401 equivalent of the pvs(8) command.
403 This returns a list of just the device names that
404 contain PVs (eg. "/dev/sda2").
406 See also "g.pvs_full".
408 This function returns a list of strings.
410 return libguestfsmod.pvs (self._o)
413 u"""List all the volumes groups detected. This is the
414 equivalent of the vgs(8) command.
416 This returns a list of just the volume group names that
417 were detected (eg. "VolGroup00").
419 See also "g.vgs_full".
421 This function returns a list of strings.
423 return libguestfsmod.vgs (self._o)
426 u"""List all the logical volumes detected. This is the
427 equivalent of the lvs(8) command.
429 This returns a list of the logical volume device names
430 (eg. "/dev/VolGroup00/LogVol00").
432 See also "g.lvs_full".
434 This function returns a list of strings.
436 return libguestfsmod.lvs (self._o)
439 u"""List all the physical volumes detected. This is the
440 equivalent of the pvs(8) command. The "full" version
443 This function returns a list of PVs. Each PV is
444 represented as a dictionary.
446 return libguestfsmod.pvs_full (self._o)
449 u"""List all the volumes groups detected. This is the
450 equivalent of the vgs(8) command. The "full" version
453 This function returns a list of VGs. Each VG is
454 represented as a dictionary.
456 return libguestfsmod.vgs_full (self._o)
459 u"""List all the logical volumes detected. This is the
460 equivalent of the lvs(8) command. The "full" version
463 This function returns a list of LVs. Each LV is
464 represented as a dictionary.
466 return libguestfsmod.lvs_full (self._o)
468 def read_lines (self, path):
469 u"""Return the contents of the file named "path".
471 The file contents are returned as a list of lines.
472 Trailing "LF" and "CRLF" character sequences are *not*
475 Note that this function cannot correctly handle binary
476 files (specifically, files containing "\\0" character
477 which is treated as end of line). For those you need to
478 use the "g.read_file" function which has a more complex
481 This function returns a list of strings.
483 return libguestfsmod.read_lines (self._o, path)
485 def aug_init (self, root, flags):
486 u"""Create a new Augeas handle for editing configuration
487 files. If there was any previous Augeas handle
488 associated with this guestfs session, then it is closed.
490 You must call this before using any other "g.aug_*"
493 "root" is the filesystem root. "root" must not be NULL,
496 The flags are the same as the flags defined in
497 <augeas.h>, the logical *or* of the following integers:
499 "AUG_SAVE_BACKUP" = 1
500 Keep the original file with a ".augsave" extension.
502 "AUG_SAVE_NEWFILE" = 2
503 Save changes into a file with extension ".augnew",
504 and do not overwrite original. Overrides
508 Typecheck lenses (can be expensive).
511 Do not use standard load path for modules.
514 Make save a no-op, just record what would have been
518 Do not load the tree in "g.aug_init".
520 To close the handle, you can call "g.aug_close".
522 To find out more about Augeas, see <http://augeas.net/>.
524 return libguestfsmod.aug_init (self._o, root, flags)
526 def aug_close (self):
527 u"""Close the current Augeas handle and free up any
528 resources used by it. After calling this, you have to
529 call "g.aug_init" again before you can use any other
532 return libguestfsmod.aug_close (self._o)
534 def aug_defvar (self, name, expr):
535 u"""Defines an Augeas variable "name" whose value is the
536 result of evaluating "expr". If "expr" is NULL, then
539 On success this returns the number of nodes in "expr",
540 or 0 if "expr" evaluates to something which is not a
543 return libguestfsmod.aug_defvar (self._o, name, expr)
545 def aug_defnode (self, name, expr, val):
546 u"""Defines a variable "name" whose value is the result of
549 If "expr" evaluates to an empty nodeset, a node is
550 created, equivalent to calling "g.aug_set" "expr",
551 "value". "name" will be the nodeset containing that
554 On success this returns a pair containing the number of
555 nodes in the nodeset, and a boolean flag if a node was
558 This function returns a tuple (int, bool).
560 return libguestfsmod.aug_defnode (self._o, name, expr, val)
562 def aug_get (self, path):
563 u"""Look up the value associated with "path". If "path"
564 matches exactly one node, the "value" is returned.
566 return libguestfsmod.aug_get (self._o, path)
568 def aug_set (self, path, val):
569 u"""Set the value associated with "path" to "value".
571 return libguestfsmod.aug_set (self._o, path, val)
573 def aug_insert (self, path, label, before):
574 u"""Create a new sibling "label" for "path", inserting it
575 into the tree before or after "path" (depending on the
576 boolean flag "before").
578 "path" must match exactly one existing node in the tree,
579 and "label" must be a label, ie. not contain "/", "*" or
580 end with a bracketed index "[N]".
582 return libguestfsmod.aug_insert (self._o, path, label, before)
584 def aug_rm (self, path):
585 u"""Remove "path" and all of its children.
587 On success this returns the number of entries which were
590 return libguestfsmod.aug_rm (self._o, path)
592 def aug_mv (self, src, dest):
593 u"""Move the node "src" to "dest". "src" must match exactly
594 one node. "dest" is overwritten if it exists.
596 return libguestfsmod.aug_mv (self._o, src, dest)
598 def aug_match (self, path):
599 u"""Returns a list of paths which match the path expression
600 "path". The returned paths are sufficiently qualified so
601 that they match exactly one node in the current tree.
603 This function returns a list of strings.
605 return libguestfsmod.aug_match (self._o, path)
608 u"""This writes all pending changes to disk.
610 The flags which were passed to "g.aug_init" affect
611 exactly how files are saved.
613 return libguestfsmod.aug_save (self._o)
616 u"""Load files into the tree.
618 See "aug_load" in the Augeas documentation for the full
621 return libguestfsmod.aug_load (self._o)
623 def aug_ls (self, path):
624 u"""This is just a shortcut for listing "g.aug_match"
625 "path/*" and sorting the resulting nodes into
628 This function returns a list of strings.
630 return libguestfsmod.aug_ls (self._o, path)
633 u"""Remove the single file "path".
635 return libguestfsmod.rm (self._o, path)
637 def rmdir (self, path):
638 u"""Remove the single directory "path".
640 return libguestfsmod.rmdir (self._o, path)
642 def rm_rf (self, path):
643 u"""Remove the file or directory "path", recursively
644 removing the contents if its a directory. This is like
645 the "rm -rf" shell command.
647 return libguestfsmod.rm_rf (self._o, path)
649 def mkdir (self, path):
650 u"""Create a directory named "path".
652 return libguestfsmod.mkdir (self._o, path)
654 def mkdir_p (self, path):
655 u"""Create a directory named "path", creating any parent
656 directories as necessary. This is like the "mkdir -p"
659 return libguestfsmod.mkdir_p (self._o, path)
661 def chmod (self, mode, path):
662 u"""Change the mode (permissions) of "path" to "mode". Only
663 numeric modes are supported.
665 return libguestfsmod.chmod (self._o, mode, path)
667 def chown (self, owner, group, path):
668 u"""Change the file owner to "owner" and group to "group".
670 Only numeric uid and gid are supported. If you want to
671 use names, you will need to locate and parse the
672 password file yourself (Augeas support makes this
675 return libguestfsmod.chown (self._o, owner, group, path)
677 def exists (self, path):
678 u"""This returns "true" if and only if there is a file,
679 directory (or anything) with the given "path" name.
681 See also "g.is_file", "g.is_dir", "g.stat".
683 return libguestfsmod.exists (self._o, path)
685 def is_file (self, path):
686 u"""This returns "true" if and only if there is a file with
687 the given "path" name. Note that it returns false for
688 other objects like directories.
692 return libguestfsmod.is_file (self._o, path)
694 def is_dir (self, path):
695 u"""This returns "true" if and only if there is a directory
696 with the given "path" name. Note that it returns false
697 for other objects like files.
701 return libguestfsmod.is_dir (self._o, path)
703 def pvcreate (self, device):
704 u"""This creates an LVM physical volume on the named
705 "device", where "device" should usually be a partition
706 name such as "/dev/sda1".
708 return libguestfsmod.pvcreate (self._o, device)
710 def vgcreate (self, volgroup, physvols):
711 u"""This creates an LVM volume group called "volgroup" from
712 the non-empty list of physical volumes "physvols".
714 return libguestfsmod.vgcreate (self._o, volgroup, physvols)
716 def lvcreate (self, logvol, volgroup, mbytes):
717 u"""This creates an LVM volume group called "logvol" on the
718 volume group "volgroup", with "size" megabytes.
720 return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
722 def mkfs (self, fstype, device):
723 u"""This creates a filesystem on "device" (usually a
724 partition or LVM logical volume). The filesystem type is
725 "fstype", for example "ext3".
727 return libguestfsmod.mkfs (self._o, fstype, device)
729 def sfdisk (self, device, cyls, heads, sectors, lines):
730 u"""This is a direct interface to the sfdisk(8) program for
731 creating partitions on block devices.
733 "device" should be a block device, for example
736 "cyls", "heads" and "sectors" are the number of
737 cylinders, heads and sectors on the device, which are
738 passed directly to sfdisk as the *-C*, *-H* and *-S*
739 parameters. If you pass 0 for any of these, then the
740 corresponding parameter is omitted. Usually for 'large'
741 disks, you can just pass 0 for these, but for small
742 (floppy-sized) disks, sfdisk (or rather, the kernel)
743 cannot work out the right geometry and you will need to
746 "lines" is a list of lines that we feed to "sfdisk". For
747 more information refer to the sfdisk(8) manpage.
749 To create a single partition occupying the whole disk,
750 you would pass "lines" as a single element list, when
751 the single element being the string "," (comma).
753 This command is dangerous. Without careful use you can
754 easily destroy all your data.
756 return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
758 def write_file (self, path, content, size):
759 u"""This call creates a file called "path". The contents of
760 the file is the string "content" (which can contain any
761 8 bit data), with length "size".
763 As a special case, if "size" is 0 then the length is
764 calculated using "strlen" (so in this case the content
765 cannot contain embedded ASCII NULs).
767 *NB.* Owing to a bug, writing content containing ASCII
768 NUL characters does *not* work, even if the length is
769 specified. We hope to resolve this bug in a future
770 version. In the meantime use "g.upload".
772 Because of the message protocol, there is a transfer
773 limit of somewhere between 2MB and 4MB. To transfer
774 large files you should use FTP.
776 return libguestfsmod.write_file (self._o, path, content, size)
778 def umount (self, pathordevice):
779 u"""This unmounts the given filesystem. The filesystem may
780 be specified either by its mountpoint (path) or the
781 device which contains the filesystem.
783 return libguestfsmod.umount (self._o, pathordevice)
786 u"""This returns the list of currently mounted filesystems.
787 It returns the list of devices (eg. "/dev/sda1",
790 Some internal mounts are not shown.
792 This function returns a list of strings.
794 return libguestfsmod.mounts (self._o)
796 def umount_all (self):
797 u"""This unmounts all mounted filesystems.
799 Some internal mounts are not unmounted by this call.
801 return libguestfsmod.umount_all (self._o)
803 def lvm_remove_all (self):
804 u"""This command removes all LVM logical volumes, volume
805 groups and physical volumes.
807 This command is dangerous. Without careful use you can
808 easily destroy all your data.
810 return libguestfsmod.lvm_remove_all (self._o)
812 def file (self, path):
813 u"""This call uses the standard file(1) command to determine
814 the type or contents of the file. This also works on
815 devices, for example to find out whether a partition
816 contains a filesystem.
818 The exact command which runs is "file -bsL path". Note
819 in particular that the filename is not prepended to the
820 output (the "-b" option).
822 return libguestfsmod.file (self._o, path)
824 def command (self, arguments):
825 u"""This call runs a command from the guest filesystem. The
826 filesystem must be mounted, and must contain a
827 compatible operating system (ie. something Linux, with
828 the same or compatible processor architecture).
830 The single parameter is an argv-style list of arguments.
831 The first element is the name of the program to run.
832 Subsequent elements are parameters. The list must be
833 non-empty (ie. must contain a program name).
835 The return value is anything printed to *stdout* by the
838 If the command returns a non-zero exit status, then this
839 function returns an error message. The error message
840 string is the content of *stderr* from the command.
842 The $PATH environment variable will contain at least
843 "/usr/bin" and "/bin". If you require a program from
844 another location, you should provide the full path in
847 Shared libraries and data files required by the program
848 must be available on filesystems which are mounted in
849 the correct places. It is the caller's responsibility to
850 ensure all filesystems that are needed are mounted at
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 (self._o, arguments)
859 def command_lines (self, arguments):
860 u"""This is the same as "g.command", but splits the result
861 into a list of lines.
863 This function returns a list of strings.
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_lines (self._o, arguments)
871 def stat (self, path):
872 u"""Returns file information for the given "path".
874 This is the same as the stat(2) system call.
876 This function returns a dictionary, with keys matching
877 the various fields in the stat structure.
879 return libguestfsmod.stat (self._o, path)
881 def lstat (self, path):
882 u"""Returns file information for the given "path".
884 This is the same as "g.stat" except that if "path" is a
885 symbolic link, then the link is stat-ed, not the file it
888 This is the same as the lstat(2) system call.
890 This function returns a dictionary, with keys matching
891 the various fields in the stat structure.
893 return libguestfsmod.lstat (self._o, path)
895 def statvfs (self, path):
896 u"""Returns file system statistics for any mounted file
897 system. "path" should be a file or directory in the
898 mounted file system (typically it is the mount point
899 itself, but it doesn't need to be).
901 This is the same as the statvfs(2) system call.
903 This function returns a dictionary, with keys matching
904 the various fields in the statvfs structure.
906 return libguestfsmod.statvfs (self._o, path)
908 def tune2fs_l (self, device):
909 u"""This returns the contents of the ext2, ext3 or ext4
910 filesystem superblock on "device".
912 It is the same as running "tune2fs -l device". See
913 tune2fs(8) manpage for more details. The list of fields
914 returned isn't clearly defined, and depends on both the
915 version of "tune2fs" that libguestfs was built against,
916 and the filesystem itself.
918 This function returns a dictionary.
920 return libguestfsmod.tune2fs_l (self._o, device)
922 def blockdev_setro (self, device):
923 u"""Sets the block device named "device" to read-only.
925 This uses the blockdev(8) command.
927 return libguestfsmod.blockdev_setro (self._o, device)
929 def blockdev_setrw (self, device):
930 u"""Sets the block device named "device" to read-write.
932 This uses the blockdev(8) command.
934 return libguestfsmod.blockdev_setrw (self._o, device)
936 def blockdev_getro (self, device):
937 u"""Returns a boolean indicating if the block device is
938 read-only (true if read-only, false if not).
940 This uses the blockdev(8) command.
942 return libguestfsmod.blockdev_getro (self._o, device)
944 def blockdev_getss (self, device):
945 u"""This returns the size of sectors on a block device.
946 Usually 512, but can be larger for modern devices.
948 (Note, this is not the size in sectors, use
949 "g.blockdev_getsz" for that).
951 This uses the blockdev(8) command.
953 return libguestfsmod.blockdev_getss (self._o, device)
955 def blockdev_getbsz (self, device):
956 u"""This returns the block size of a device.
958 (Note this is different from both *size in blocks* and
959 *filesystem block size*).
961 This uses the blockdev(8) command.
963 return libguestfsmod.blockdev_getbsz (self._o, device)
965 def blockdev_setbsz (self, device, blocksize):
966 u"""This sets the block size of a device.
968 (Note this is different from both *size in blocks* and
969 *filesystem block size*).
971 This uses the blockdev(8) command.
973 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
975 def blockdev_getsz (self, device):
976 u"""This returns the size of the device in units of 512-byte
977 sectors (even if the sectorsize isn't 512 bytes ...
980 See also "g.blockdev_getss" for the real sector size of
981 the device, and "g.blockdev_getsize64" for the more
982 useful *size in bytes*.
984 This uses the blockdev(8) command.
986 return libguestfsmod.blockdev_getsz (self._o, device)
988 def blockdev_getsize64 (self, device):
989 u"""This returns the size of the device in bytes.
991 See also "g.blockdev_getsz".
993 This uses the blockdev(8) command.
995 return libguestfsmod.blockdev_getsize64 (self._o, device)
997 def blockdev_flushbufs (self, device):
998 u"""This tells the kernel to flush internal buffers
999 associated with "device".
1001 This uses the blockdev(8) command.
1003 return libguestfsmod.blockdev_flushbufs (self._o, device)
1005 def blockdev_rereadpt (self, device):
1006 u"""Reread the partition table on "device".
1008 This uses the blockdev(8) command.
1010 return libguestfsmod.blockdev_rereadpt (self._o, device)
1012 def upload (self, filename, remotefilename):
1013 u"""Upload local file "filename" to "remotefilename" on the
1016 "filename" can also be a named pipe.
1018 See also "g.download".
1020 return libguestfsmod.upload (self._o, filename, remotefilename)
1022 def download (self, remotefilename, filename):
1023 u"""Download file "remotefilename" and save it as "filename"
1024 on the local machine.
1026 "filename" can also be a named pipe.
1028 See also "g.upload", "g.cat".
1030 return libguestfsmod.download (self._o, remotefilename, filename)
1032 def checksum (self, csumtype, path):
1033 u"""This call computes the MD5, SHAx or CRC checksum of the
1036 The type of checksum to compute is given by the
1037 "csumtype" parameter which must have one of the
1041 Compute the cyclic redundancy check (CRC) specified
1042 by POSIX for the "cksum" command.
1045 Compute the MD5 hash (using the "md5sum" program).
1048 Compute the SHA1 hash (using the "sha1sum" program).
1051 Compute the SHA224 hash (using the "sha224sum"
1055 Compute the SHA256 hash (using the "sha256sum"
1059 Compute the SHA384 hash (using the "sha384sum"
1063 Compute the SHA512 hash (using the "sha512sum"
1066 The checksum is returned as a printable string.
1068 return libguestfsmod.checksum (self._o, csumtype, path)
1070 def tar_in (self, tarfile, directory):
1071 u"""This command uploads and unpacks local file "tarfile"
1072 (an *uncompressed* tar file) into "directory".
1074 To upload a compressed tarball, use "g.tgz_in".
1076 return libguestfsmod.tar_in (self._o, tarfile, directory)
1078 def tar_out (self, directory, tarfile):
1079 u"""This command packs the contents of "directory" and
1080 downloads it to local file "tarfile".
1082 To download a compressed tarball, use "g.tgz_out".
1084 return libguestfsmod.tar_out (self._o, directory, tarfile)
1086 def tgz_in (self, tarball, directory):
1087 u"""This command uploads and unpacks local file "tarball" (a
1088 *gzip compressed* tar file) into "directory".
1090 To upload an uncompressed tarball, use "g.tar_in".
1092 return libguestfsmod.tgz_in (self._o, tarball, directory)
1094 def tgz_out (self, directory, tarball):
1095 u"""This command packs the contents of "directory" and
1096 downloads it to local file "tarball".
1098 To download an uncompressed tarball, use "g.tar_out".
1100 return libguestfsmod.tgz_out (self._o, directory, tarball)
1102 def mount_ro (self, device, mountpoint):
1103 u"""This is the same as the "g.mount" command, but it mounts
1104 the filesystem with the read-only (*-o ro*) flag.
1106 return libguestfsmod.mount_ro (self._o, device, mountpoint)
1108 def mount_options (self, options, device, mountpoint):
1109 u"""This is the same as the "g.mount" command, but it allows
1110 you to set the mount options as for the mount(8) *-o*
1113 return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1115 def mount_vfs (self, options, vfstype, device, mountpoint):
1116 u"""This is the same as the "g.mount" command, but it allows
1117 you to set both the mount options and the vfstype as for
1118 the mount(8) *-o* and *-t* flags.
1120 return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1122 def debug (self, subcmd, extraargs):
1123 u"""The "g.debug" command exposes some internals of
1124 "guestfsd" (the guestfs daemon) that runs inside the
1127 There is no comprehensive help for this command. You
1128 have to look at the file "daemon/debug.c" in the
1129 libguestfs source to find out what you can do.
1131 return libguestfsmod.debug (self._o, subcmd, extraargs)
1133 def lvremove (self, device):
1134 u"""Remove an LVM logical volume "device", where "device" is
1135 the path to the LV, such as "/dev/VG/LV".
1137 You can also remove all LVs in a volume group by
1138 specifying the VG name, "/dev/VG".
1140 return libguestfsmod.lvremove (self._o, device)
1142 def vgremove (self, vgname):
1143 u"""Remove an LVM volume group "vgname", (for example "VG").
1145 This also forcibly removes all logical volumes in the
1146 volume group (if any).
1148 return libguestfsmod.vgremove (self._o, vgname)
1150 def pvremove (self, device):
1151 u"""This wipes a physical volume "device" so that LVM will
1152 no longer recognise it.
1154 The implementation uses the "pvremove" command which
1155 refuses to wipe physical volumes that contain any volume
1156 groups, so you have to remove those first.
1158 return libguestfsmod.pvremove (self._o, device)
1160 def set_e2label (self, device, label):
1161 u"""This sets the ext2/3/4 filesystem label of the
1162 filesystem on "device" to "label". Filesystem labels are
1163 limited to 16 characters.
1165 You can use either "g.tune2fs_l" or "g.get_e2label" to
1166 return the existing label on a filesystem.
1168 return libguestfsmod.set_e2label (self._o, device, label)
1170 def get_e2label (self, device):
1171 u"""This returns the ext2/3/4 filesystem label of the
1172 filesystem on "device".
1174 return libguestfsmod.get_e2label (self._o, device)
1176 def set_e2uuid (self, device, uuid):
1177 u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1178 on "device" to "uuid". The format of the UUID and
1179 alternatives such as "clear", "random" and "time" are
1180 described in the tune2fs(8) manpage.
1182 You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1183 return the existing UUID of a filesystem.
1185 return libguestfsmod.set_e2uuid (self._o, device, uuid)
1187 def get_e2uuid (self, device):
1188 u"""This returns the ext2/3/4 filesystem UUID of the
1189 filesystem on "device".
1191 return libguestfsmod.get_e2uuid (self._o, device)
1193 def fsck (self, fstype, device):
1194 u"""This runs the filesystem checker (fsck) on "device"
1195 which should have filesystem type "fstype".
1197 The returned integer is the status. See fsck(8) for the
1198 list of status codes from "fsck".
1202 * Multiple status codes can be summed together.
1204 * A non-zero return code can mean "success", for
1205 example if errors have been corrected on the
1208 * Checking or repairing NTFS volumes is not supported
1211 This command is entirely equivalent to running "fsck -a
1214 return libguestfsmod.fsck (self._o, fstype, device)
1216 def zero (self, device):
1217 u"""This command writes zeroes over the first few blocks of
1220 How many blocks are zeroed isn't specified (but it's
1221 *not* enough to securely wipe the device). It should be
1222 sufficient to remove any partition tables, filesystem
1223 superblocks and so on.
1225 return libguestfsmod.zero (self._o, device)
1227 def grub_install (self, root, device):
1228 u"""This command installs GRUB (the Grand Unified
1229 Bootloader) on "device", with the root directory being
1232 return libguestfsmod.grub_install (self._o, root, device)
1234 def cp (self, src, dest):
1235 u"""This copies a file from "src" to "dest" where "dest" is
1236 either a destination filename or destination directory.
1238 return libguestfsmod.cp (self._o, src, dest)
1240 def cp_a (self, src, dest):
1241 u"""This copies a file or directory from "src" to "dest"
1242 recursively using the "cp -a" command.
1244 return libguestfsmod.cp_a (self._o, src, dest)
1246 def mv (self, src, dest):
1247 u"""This moves a file from "src" to "dest" where "dest" is
1248 either a destination filename or destination directory.
1250 return libguestfsmod.mv (self._o, src, dest)
1252 def drop_caches (self, whattodrop):
1253 u"""This instructs the guest kernel to drop its page cache,
1254 and/or dentries and inode caches. The parameter
1255 "whattodrop" tells the kernel what precisely to drop,
1256 see <http://linux-mm.org/Drop_Caches>
1258 Setting "whattodrop" to 3 should drop everything.
1260 This automatically calls sync(2) before the operation,
1261 so that the maximum guest memory is freed.
1263 return libguestfsmod.drop_caches (self._o, whattodrop)
1266 u"""This returns the kernel messages ("dmesg" output) from
1267 the guest kernel. This is sometimes useful for extended
1268 debugging of problems.
1270 Another way to get the same information is to enable
1271 verbose messages with "g.set_verbose" or by setting the
1272 environment variable "LIBGUESTFS_DEBUG=1" before running
1275 return libguestfsmod.dmesg (self._o)
1277 def ping_daemon (self):
1278 u"""This is a test probe into the guestfs daemon running
1279 inside the qemu subprocess. Calling this function checks
1280 that the daemon responds to the ping message, without
1281 affecting the daemon or attached block device(s) in any
1284 return libguestfsmod.ping_daemon (self._o)
1286 def equal (self, file1, file2):
1287 u"""This compares the two files "file1" and "file2" and
1288 returns true if their content is exactly equal, or false
1291 The external cmp(1) program is used for the comparison.
1293 return libguestfsmod.equal (self._o, file1, file2)
1295 def strings (self, path):
1296 u"""This runs the strings(1) command on a file and returns
1297 the list of printable strings found.
1299 This function returns a list of strings.
1301 Because of the message protocol, there is a transfer
1302 limit of somewhere between 2MB and 4MB. To transfer
1303 large files you should use FTP.
1305 return libguestfsmod.strings (self._o, path)
1307 def strings_e (self, encoding, path):
1308 u"""This is like the "g.strings" command, but allows you to
1309 specify the encoding.
1311 See the strings(1) manpage for the full list of
1314 Commonly useful encodings are "l" (lower case L) which
1315 will show strings inside Windows/x86 files.
1317 The returned strings are transcoded to UTF-8.
1319 This function returns a list of strings.
1321 Because of the message protocol, there is a transfer
1322 limit of somewhere between 2MB and 4MB. To transfer
1323 large files you should use FTP.
1325 return libguestfsmod.strings_e (self._o, encoding, path)
1327 def hexdump (self, path):
1328 u"""This runs "hexdump -C" on the given "path". The result
1329 is the human-readable, canonical hex dump of the file.
1331 Because of the message protocol, there is a transfer
1332 limit of somewhere between 2MB and 4MB. To transfer
1333 large files you should use FTP.
1335 return libguestfsmod.hexdump (self._o, path)