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)
81 def test0 (self, str, optstr, strlist, b, integer, filein, fileout):
82 return libguestfsmod.test0 (self._o, str, optstr, strlist, b, integer, filein, fileout)
84 def test0rint (self, val):
85 return libguestfsmod.test0rint (self._o, val)
87 def test0rinterr (self):
88 return libguestfsmod.test0rinterr (self._o)
90 def test0rint64 (self, val):
91 return libguestfsmod.test0rint64 (self._o, val)
93 def test0rint64err (self):
94 return libguestfsmod.test0rint64err (self._o)
96 def test0rbool (self, val):
97 return libguestfsmod.test0rbool (self._o, val)
99 def test0rboolerr (self):
100 return libguestfsmod.test0rboolerr (self._o)
102 def test0rconststring (self, val):
103 return libguestfsmod.test0rconststring (self._o, val)
105 def test0rconststringerr (self):
106 return libguestfsmod.test0rconststringerr (self._o)
108 def test0rstring (self, val):
109 return libguestfsmod.test0rstring (self._o, val)
111 def test0rstringerr (self):
112 return libguestfsmod.test0rstringerr (self._o)
114 def test0rstringlist (self, val):
115 return libguestfsmod.test0rstringlist (self._o, val)
117 def test0rstringlisterr (self):
118 return libguestfsmod.test0rstringlisterr (self._o)
120 def test0rintbool (self, val):
121 return libguestfsmod.test0rintbool (self._o, val)
123 def test0rintboolerr (self):
124 return libguestfsmod.test0rintboolerr (self._o)
126 def test0rpvlist (self, val):
127 return libguestfsmod.test0rpvlist (self._o, val)
129 def test0rpvlisterr (self):
130 return libguestfsmod.test0rpvlisterr (self._o)
132 def test0rvglist (self, val):
133 return libguestfsmod.test0rvglist (self._o, val)
135 def test0rvglisterr (self):
136 return libguestfsmod.test0rvglisterr (self._o)
138 def test0rlvlist (self, val):
139 return libguestfsmod.test0rlvlist (self._o, val)
141 def test0rlvlisterr (self):
142 return libguestfsmod.test0rlvlisterr (self._o)
144 def test0rstat (self, val):
145 return libguestfsmod.test0rstat (self._o, val)
147 def test0rstaterr (self):
148 return libguestfsmod.test0rstaterr (self._o)
150 def test0rstatvfs (self, val):
151 return libguestfsmod.test0rstatvfs (self._o, val)
153 def test0rstatvfserr (self):
154 return libguestfsmod.test0rstatvfserr (self._o)
156 def test0rhashtable (self, val):
157 return libguestfsmod.test0rhashtable (self._o, val)
159 def test0rhashtableerr (self):
160 return libguestfsmod.test0rhashtableerr (self._o)
163 u"""Internally libguestfs is implemented by running a
164 virtual machine using qemu(1).
166 You should call this after configuring the handle (eg.
167 adding drives) but before performing any actions.
169 return libguestfsmod.launch (self._o)
171 def wait_ready (self):
172 u"""Internally libguestfs is implemented by running a
173 virtual machine using qemu(1).
175 You should call this after "g.launch" to wait for the
178 return libguestfsmod.wait_ready (self._o)
180 def kill_subprocess (self):
181 u"""This kills the qemu subprocess. You should never need to
184 return libguestfsmod.kill_subprocess (self._o)
186 def add_drive (self, filename):
187 u"""This function adds a virtual machine disk image
188 "filename" to the guest. The first time you call this
189 function, the disk appears as IDE disk 0 ("/dev/sda") in
190 the guest, the second time as "/dev/sdb", and so on.
192 You don't necessarily need to be root when using
193 libguestfs. However you obviously do need sufficient
194 permissions to access the filename for whatever
195 operations you want to perform (ie. read access if you
196 just want to read the image or write access if you want
197 to modify the image).
199 This is equivalent to the qemu parameter "-drive
202 return libguestfsmod.add_drive (self._o, filename)
204 def add_cdrom (self, filename):
205 u"""This function adds a virtual CD-ROM disk image to the
208 This is equivalent to the qemu parameter "-cdrom
211 return libguestfsmod.add_cdrom (self._o, filename)
213 def config (self, qemuparam, qemuvalue):
214 u"""This can be used to add arbitrary qemu command line
215 parameters of the form "-param value". Actually it's not
216 quite arbitrary - we prevent you from setting some
217 parameters which would interfere with parameters that we
220 The first character of "param" string must be a "-"
225 return libguestfsmod.config (self._o, qemuparam, qemuvalue)
227 def set_qemu (self, qemu):
228 u"""Set the qemu binary that we will use.
230 The default is chosen when the library was compiled by
231 the configure script.
233 You can also override this by setting the
234 "LIBGUESTFS_QEMU" environment variable.
236 Setting "qemu" to "NULL" restores the default qemu
239 return libguestfsmod.set_qemu (self._o, qemu)
242 u"""Return the current qemu binary.
244 This is always non-NULL. If it wasn't set already, then
245 this will return the default qemu binary name.
247 return libguestfsmod.get_qemu (self._o)
249 def set_path (self, path):
250 u"""Set the path that libguestfs searches for kernel and
253 The default is "$libdir/guestfs" unless overridden by
254 setting "LIBGUESTFS_PATH" environment variable.
256 Setting "path" to "NULL" restores the default path.
258 return libguestfsmod.set_path (self._o, path)
261 u"""Return the current search path.
263 This is always non-NULL. If it wasn't set already, then
264 this will return the default path.
266 return libguestfsmod.get_path (self._o)
268 def set_append (self, append):
269 u"""This function is used to add additional options to the
270 guest kernel command line.
272 The default is "NULL" unless overridden by setting
273 "LIBGUESTFS_APPEND" environment variable.
275 Setting "append" to "NULL" means *no* additional options
276 are passed (libguestfs always adds a few of its own).
278 return libguestfsmod.set_append (self._o, append)
280 def get_append (self):
281 u"""Return the additional kernel options which are added to
282 the guest kernel command line.
284 If "NULL" then no options are added.
286 return libguestfsmod.get_append (self._o)
288 def set_autosync (self, autosync):
289 u"""If "autosync" is true, this enables autosync. Libguestfs
290 will make a best effort attempt to run "g.umount_all"
291 followed by "g.sync" when the handle is closed (also if
292 the program exits without closing handles).
294 This is disabled by default (except in guestfish where
295 it is enabled by default).
297 return libguestfsmod.set_autosync (self._o, autosync)
299 def get_autosync (self):
300 u"""Get the autosync flag.
302 return libguestfsmod.get_autosync (self._o)
304 def set_verbose (self, verbose):
305 u"""If "verbose" is true, this turns on verbose messages (to
308 Verbose messages are disabled unless the environment
309 variable "LIBGUESTFS_DEBUG" is defined and set to 1.
311 return libguestfsmod.set_verbose (self._o, verbose)
313 def get_verbose (self):
314 u"""This returns the verbose messages flag.
316 return libguestfsmod.get_verbose (self._o)
319 u"""This returns true iff this handle is ready to accept
320 commands (in the "READY" state).
322 For more information on states, see guestfs(3).
324 return libguestfsmod.is_ready (self._o)
326 def is_config (self):
327 u"""This returns true iff this handle is being configured
328 (in the "CONFIG" state).
330 For more information on states, see guestfs(3).
332 return libguestfsmod.is_config (self._o)
334 def is_launching (self):
335 u"""This returns true iff this handle is launching the
336 subprocess (in the "LAUNCHING" state).
338 For more information on states, see guestfs(3).
340 return libguestfsmod.is_launching (self._o)
343 u"""This returns true iff this handle is busy processing a
344 command (in the "BUSY" state).
346 For more information on states, see guestfs(3).
348 return libguestfsmod.is_busy (self._o)
350 def get_state (self):
351 u"""This returns the current state as an opaque integer.
352 This is only useful for printing debug and internal
355 For more information on states, see guestfs(3).
357 return libguestfsmod.get_state (self._o)
360 u"""This sets the state to "BUSY". This is only used when
361 implementing actions using the low-level API.
363 For more information on states, see guestfs(3).
365 return libguestfsmod.set_busy (self._o)
367 def set_ready (self):
368 u"""This sets the state to "READY". This is only used when
369 implementing actions using the low-level API.
371 For more information on states, see guestfs(3).
373 return libguestfsmod.set_ready (self._o)
376 u"""This sets the state to "READY", or if in "CONFIG" then
377 it leaves the state as is. This is only used when
378 implementing actions using the low-level API.
380 For more information on states, see guestfs(3).
382 return libguestfsmod.end_busy (self._o)
384 def mount (self, device, mountpoint):
385 u"""Mount a guest disk at a position in the filesystem.
386 Block devices are named "/dev/sda", "/dev/sdb" and so
387 on, as they were added to the guest. If those block
388 devices contain partitions, they will have the usual
389 names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
392 The rules are the same as for mount(2): A filesystem
393 must first be mounted on "/" before others can be
394 mounted. Other filesystems can only be mounted on
395 directories which already exist.
397 The mounted filesystem is writable, if we have
398 sufficient permissions on the underlying device.
400 The filesystem options "sync" and "noatime" are set with
401 this call, in order to improve reliability.
403 return libguestfsmod.mount (self._o, device, mountpoint)
406 u"""This syncs the disk, so that any writes are flushed
407 through to the underlying disk image.
409 You should always call this if you have modified a disk
410 image, before closing the handle.
412 return libguestfsmod.sync (self._o)
414 def touch (self, path):
415 u"""Touch acts like the touch(1) command. It can be used to
416 update the timestamps on a file, or, if the file does
417 not exist, to create a new zero-length file.
419 return libguestfsmod.touch (self._o, path)
421 def cat (self, path):
422 u"""Return the contents of the file named "path".
424 Note that this function cannot correctly handle binary
425 files (specifically, files containing "\\0" character
426 which is treated as end of string). For those you need
427 to use the "g.download" function which has a more
430 Because of the message protocol, there is a transfer
431 limit of somewhere between 2MB and 4MB. To transfer
432 large files you should use FTP.
434 return libguestfsmod.cat (self._o, path)
436 def ll (self, directory):
437 u"""List the files in "directory" (relative to the root
438 directory, there is no cwd) in the format of 'ls -la'.
440 This command is mostly useful for interactive sessions.
441 It is *not* intended that you try to parse the output
444 return libguestfsmod.ll (self._o, directory)
446 def ls (self, directory):
447 u"""List the files in "directory" (relative to the root
448 directory, there is no cwd). The '.' and '..' entries
449 are not returned, but hidden files are shown.
451 This command is mostly useful for interactive sessions.
452 Programs should probably use "g.readdir" instead.
454 This function returns a list of strings.
456 return libguestfsmod.ls (self._o, directory)
458 def list_devices (self):
459 u"""List all the block devices.
461 The full block device names are returned, eg. "/dev/sda"
463 This function returns a list of strings.
465 return libguestfsmod.list_devices (self._o)
467 def list_partitions (self):
468 u"""List all the partitions detected on all block devices.
470 The full partition device names are returned, eg.
473 This does not return logical volumes. For that you will
474 need to call "g.lvs".
476 This function returns a list of strings.
478 return libguestfsmod.list_partitions (self._o)
481 u"""List all the physical volumes detected. This is the
482 equivalent of the pvs(8) command.
484 This returns a list of just the device names that
485 contain PVs (eg. "/dev/sda2").
487 See also "g.pvs_full".
489 This function returns a list of strings.
491 return libguestfsmod.pvs (self._o)
494 u"""List all the volumes groups detected. This is the
495 equivalent of the vgs(8) command.
497 This returns a list of just the volume group names that
498 were detected (eg. "VolGroup00").
500 See also "g.vgs_full".
502 This function returns a list of strings.
504 return libguestfsmod.vgs (self._o)
507 u"""List all the logical volumes detected. This is the
508 equivalent of the lvs(8) command.
510 This returns a list of the logical volume device names
511 (eg. "/dev/VolGroup00/LogVol00").
513 See also "g.lvs_full".
515 This function returns a list of strings.
517 return libguestfsmod.lvs (self._o)
520 u"""List all the physical volumes detected. This is the
521 equivalent of the pvs(8) command. The "full" version
524 This function returns a list of PVs. Each PV is
525 represented as a dictionary.
527 return libguestfsmod.pvs_full (self._o)
530 u"""List all the volumes groups detected. This is the
531 equivalent of the vgs(8) command. The "full" version
534 This function returns a list of VGs. Each VG is
535 represented as a dictionary.
537 return libguestfsmod.vgs_full (self._o)
540 u"""List all the logical volumes detected. This is the
541 equivalent of the lvs(8) command. The "full" version
544 This function returns a list of LVs. Each LV is
545 represented as a dictionary.
547 return libguestfsmod.lvs_full (self._o)
549 def read_lines (self, path):
550 u"""Return the contents of the file named "path".
552 The file contents are returned as a list of lines.
553 Trailing "LF" and "CRLF" character sequences are *not*
556 Note that this function cannot correctly handle binary
557 files (specifically, files containing "\\0" character
558 which is treated as end of line). For those you need to
559 use the "g.read_file" function which has a more complex
562 This function returns a list of strings.
564 return libguestfsmod.read_lines (self._o, path)
566 def aug_init (self, root, flags):
567 u"""Create a new Augeas handle for editing configuration
568 files. If there was any previous Augeas handle
569 associated with this guestfs session, then it is closed.
571 You must call this before using any other "g.aug_*"
574 "root" is the filesystem root. "root" must not be NULL,
577 The flags are the same as the flags defined in
578 <augeas.h>, the logical *or* of the following integers:
580 "AUG_SAVE_BACKUP" = 1
581 Keep the original file with a ".augsave" extension.
583 "AUG_SAVE_NEWFILE" = 2
584 Save changes into a file with extension ".augnew",
585 and do not overwrite original. Overrides
589 Typecheck lenses (can be expensive).
592 Do not use standard load path for modules.
595 Make save a no-op, just record what would have been
599 Do not load the tree in "g.aug_init".
601 To close the handle, you can call "g.aug_close".
603 To find out more about Augeas, see <http://augeas.net/>.
605 return libguestfsmod.aug_init (self._o, root, flags)
607 def aug_close (self):
608 u"""Close the current Augeas handle and free up any
609 resources used by it. After calling this, you have to
610 call "g.aug_init" again before you can use any other
613 return libguestfsmod.aug_close (self._o)
615 def aug_defvar (self, name, expr):
616 u"""Defines an Augeas variable "name" whose value is the
617 result of evaluating "expr". If "expr" is NULL, then
620 On success this returns the number of nodes in "expr",
621 or 0 if "expr" evaluates to something which is not a
624 return libguestfsmod.aug_defvar (self._o, name, expr)
626 def aug_defnode (self, name, expr, val):
627 u"""Defines a variable "name" whose value is the result of
630 If "expr" evaluates to an empty nodeset, a node is
631 created, equivalent to calling "g.aug_set" "expr",
632 "value". "name" will be the nodeset containing that
635 On success this returns a pair containing the number of
636 nodes in the nodeset, and a boolean flag if a node was
639 This function returns a tuple (int, bool).
641 return libguestfsmod.aug_defnode (self._o, name, expr, val)
643 def aug_get (self, path):
644 u"""Look up the value associated with "path". If "path"
645 matches exactly one node, the "value" is returned.
647 return libguestfsmod.aug_get (self._o, path)
649 def aug_set (self, path, val):
650 u"""Set the value associated with "path" to "value".
652 return libguestfsmod.aug_set (self._o, path, val)
654 def aug_insert (self, path, label, before):
655 u"""Create a new sibling "label" for "path", inserting it
656 into the tree before or after "path" (depending on the
657 boolean flag "before").
659 "path" must match exactly one existing node in the tree,
660 and "label" must be a label, ie. not contain "/", "*" or
661 end with a bracketed index "[N]".
663 return libguestfsmod.aug_insert (self._o, path, label, before)
665 def aug_rm (self, path):
666 u"""Remove "path" and all of its children.
668 On success this returns the number of entries which were
671 return libguestfsmod.aug_rm (self._o, path)
673 def aug_mv (self, src, dest):
674 u"""Move the node "src" to "dest". "src" must match exactly
675 one node. "dest" is overwritten if it exists.
677 return libguestfsmod.aug_mv (self._o, src, dest)
679 def aug_match (self, path):
680 u"""Returns a list of paths which match the path expression
681 "path". The returned paths are sufficiently qualified so
682 that they match exactly one node in the current tree.
684 This function returns a list of strings.
686 return libguestfsmod.aug_match (self._o, path)
689 u"""This writes all pending changes to disk.
691 The flags which were passed to "g.aug_init" affect
692 exactly how files are saved.
694 return libguestfsmod.aug_save (self._o)
697 u"""Load files into the tree.
699 See "aug_load" in the Augeas documentation for the full
702 return libguestfsmod.aug_load (self._o)
704 def aug_ls (self, path):
705 u"""This is just a shortcut for listing "g.aug_match"
706 "path/*" and sorting the resulting nodes into
709 This function returns a list of strings.
711 return libguestfsmod.aug_ls (self._o, path)
714 u"""Remove the single file "path".
716 return libguestfsmod.rm (self._o, path)
718 def rmdir (self, path):
719 u"""Remove the single directory "path".
721 return libguestfsmod.rmdir (self._o, path)
723 def rm_rf (self, path):
724 u"""Remove the file or directory "path", recursively
725 removing the contents if its a directory. This is like
726 the "rm -rf" shell command.
728 return libguestfsmod.rm_rf (self._o, path)
730 def mkdir (self, path):
731 u"""Create a directory named "path".
733 return libguestfsmod.mkdir (self._o, path)
735 def mkdir_p (self, path):
736 u"""Create a directory named "path", creating any parent
737 directories as necessary. This is like the "mkdir -p"
740 return libguestfsmod.mkdir_p (self._o, path)
742 def chmod (self, mode, path):
743 u"""Change the mode (permissions) of "path" to "mode". Only
744 numeric modes are supported.
746 return libguestfsmod.chmod (self._o, mode, path)
748 def chown (self, owner, group, path):
749 u"""Change the file owner to "owner" and group to "group".
751 Only numeric uid and gid are supported. If you want to
752 use names, you will need to locate and parse the
753 password file yourself (Augeas support makes this
756 return libguestfsmod.chown (self._o, owner, group, path)
758 def exists (self, path):
759 u"""This returns "true" if and only if there is a file,
760 directory (or anything) with the given "path" name.
762 See also "g.is_file", "g.is_dir", "g.stat".
764 return libguestfsmod.exists (self._o, path)
766 def is_file (self, path):
767 u"""This returns "true" if and only if there is a file with
768 the given "path" name. Note that it returns false for
769 other objects like directories.
773 return libguestfsmod.is_file (self._o, path)
775 def is_dir (self, path):
776 u"""This returns "true" if and only if there is a directory
777 with the given "path" name. Note that it returns false
778 for other objects like files.
782 return libguestfsmod.is_dir (self._o, path)
784 def pvcreate (self, device):
785 u"""This creates an LVM physical volume on the named
786 "device", where "device" should usually be a partition
787 name such as "/dev/sda1".
789 return libguestfsmod.pvcreate (self._o, device)
791 def vgcreate (self, volgroup, physvols):
792 u"""This creates an LVM volume group called "volgroup" from
793 the non-empty list of physical volumes "physvols".
795 return libguestfsmod.vgcreate (self._o, volgroup, physvols)
797 def lvcreate (self, logvol, volgroup, mbytes):
798 u"""This creates an LVM volume group called "logvol" on the
799 volume group "volgroup", with "size" megabytes.
801 return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
803 def mkfs (self, fstype, device):
804 u"""This creates a filesystem on "device" (usually a
805 partition or LVM logical volume). The filesystem type is
806 "fstype", for example "ext3".
808 return libguestfsmod.mkfs (self._o, fstype, device)
810 def sfdisk (self, device, cyls, heads, sectors, lines):
811 u"""This is a direct interface to the sfdisk(8) program for
812 creating partitions on block devices.
814 "device" should be a block device, for example
817 "cyls", "heads" and "sectors" are the number of
818 cylinders, heads and sectors on the device, which are
819 passed directly to sfdisk as the *-C*, *-H* and *-S*
820 parameters. If you pass 0 for any of these, then the
821 corresponding parameter is omitted. Usually for 'large'
822 disks, you can just pass 0 for these, but for small
823 (floppy-sized) disks, sfdisk (or rather, the kernel)
824 cannot work out the right geometry and you will need to
827 "lines" is a list of lines that we feed to "sfdisk". For
828 more information refer to the sfdisk(8) manpage.
830 To create a single partition occupying the whole disk,
831 you would pass "lines" as a single element list, when
832 the single element being the string "," (comma).
834 See also: "g.sfdisk_l", "g.sfdisk_N"
836 This command is dangerous. Without careful use you can
837 easily destroy all your data.
839 return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
841 def write_file (self, path, content, size):
842 u"""This call creates a file called "path". The contents of
843 the file is the string "content" (which can contain any
844 8 bit data), with length "size".
846 As a special case, if "size" is 0 then the length is
847 calculated using "strlen" (so in this case the content
848 cannot contain embedded ASCII NULs).
850 *NB.* Owing to a bug, writing content containing ASCII
851 NUL characters does *not* work, even if the length is
852 specified. We hope to resolve this bug in a future
853 version. In the meantime use "g.upload".
855 Because of the message protocol, there is a transfer
856 limit of somewhere between 2MB and 4MB. To transfer
857 large files you should use FTP.
859 return libguestfsmod.write_file (self._o, path, content, size)
861 def umount (self, pathordevice):
862 u"""This unmounts the given filesystem. The filesystem may
863 be specified either by its mountpoint (path) or the
864 device which contains the filesystem.
866 return libguestfsmod.umount (self._o, pathordevice)
869 u"""This returns the list of currently mounted filesystems.
870 It returns the list of devices (eg. "/dev/sda1",
873 Some internal mounts are not shown.
875 This function returns a list of strings.
877 return libguestfsmod.mounts (self._o)
879 def umount_all (self):
880 u"""This unmounts all mounted filesystems.
882 Some internal mounts are not unmounted by this call.
884 return libguestfsmod.umount_all (self._o)
886 def lvm_remove_all (self):
887 u"""This command removes all LVM logical volumes, volume
888 groups and physical volumes.
890 This command is dangerous. Without careful use you can
891 easily destroy all your data.
893 return libguestfsmod.lvm_remove_all (self._o)
895 def file (self, path):
896 u"""This call uses the standard file(1) command to determine
897 the type or contents of the file. This also works on
898 devices, for example to find out whether a partition
899 contains a filesystem.
901 The exact command which runs is "file -bsL path". Note
902 in particular that the filename is not prepended to the
903 output (the "-b" option).
905 return libguestfsmod.file (self._o, path)
907 def command (self, arguments):
908 u"""This call runs a command from the guest filesystem. The
909 filesystem must be mounted, and must contain a
910 compatible operating system (ie. something Linux, with
911 the same or compatible processor architecture).
913 The single parameter is an argv-style list of arguments.
914 The first element is the name of the program to run.
915 Subsequent elements are parameters. The list must be
916 non-empty (ie. must contain a program name).
918 The return value is anything printed to *stdout* by the
921 If the command returns a non-zero exit status, then this
922 function returns an error message. The error message
923 string is the content of *stderr* from the command.
925 The $PATH environment variable will contain at least
926 "/usr/bin" and "/bin". If you require a program from
927 another location, you should provide the full path in
930 Shared libraries and data files required by the program
931 must be available on filesystems which are mounted in
932 the correct places. It is the caller's responsibility to
933 ensure all filesystems that are needed are mounted at
936 Because of the message protocol, there is a transfer
937 limit of somewhere between 2MB and 4MB. To transfer
938 large files you should use FTP.
940 return libguestfsmod.command (self._o, arguments)
942 def command_lines (self, arguments):
943 u"""This is the same as "g.command", but splits the result
944 into a list of lines.
946 This function returns a list of strings.
948 Because of the message protocol, there is a transfer
949 limit of somewhere between 2MB and 4MB. To transfer
950 large files you should use FTP.
952 return libguestfsmod.command_lines (self._o, arguments)
954 def stat (self, path):
955 u"""Returns file information for the given "path".
957 This is the same as the stat(2) system call.
959 This function returns a dictionary, with keys matching
960 the various fields in the stat structure.
962 return libguestfsmod.stat (self._o, path)
964 def lstat (self, path):
965 u"""Returns file information for the given "path".
967 This is the same as "g.stat" except that if "path" is a
968 symbolic link, then the link is stat-ed, not the file it
971 This is the same as the lstat(2) system call.
973 This function returns a dictionary, with keys matching
974 the various fields in the stat structure.
976 return libguestfsmod.lstat (self._o, path)
978 def statvfs (self, path):
979 u"""Returns file system statistics for any mounted file
980 system. "path" should be a file or directory in the
981 mounted file system (typically it is the mount point
982 itself, but it doesn't need to be).
984 This is the same as the statvfs(2) system call.
986 This function returns a dictionary, with keys matching
987 the various fields in the statvfs structure.
989 return libguestfsmod.statvfs (self._o, path)
991 def tune2fs_l (self, device):
992 u"""This returns the contents of the ext2, ext3 or ext4
993 filesystem superblock on "device".
995 It is the same as running "tune2fs -l device". See
996 tune2fs(8) manpage for more details. The list of fields
997 returned isn't clearly defined, and depends on both the
998 version of "tune2fs" that libguestfs was built against,
999 and the filesystem itself.
1001 This function returns a dictionary.
1003 return libguestfsmod.tune2fs_l (self._o, device)
1005 def blockdev_setro (self, device):
1006 u"""Sets the block device named "device" to read-only.
1008 This uses the blockdev(8) command.
1010 return libguestfsmod.blockdev_setro (self._o, device)
1012 def blockdev_setrw (self, device):
1013 u"""Sets the block device named "device" to read-write.
1015 This uses the blockdev(8) command.
1017 return libguestfsmod.blockdev_setrw (self._o, device)
1019 def blockdev_getro (self, device):
1020 u"""Returns a boolean indicating if the block device is
1021 read-only (true if read-only, false if not).
1023 This uses the blockdev(8) command.
1025 return libguestfsmod.blockdev_getro (self._o, device)
1027 def blockdev_getss (self, device):
1028 u"""This returns the size of sectors on a block device.
1029 Usually 512, but can be larger for modern devices.
1031 (Note, this is not the size in sectors, use
1032 "g.blockdev_getsz" for that).
1034 This uses the blockdev(8) command.
1036 return libguestfsmod.blockdev_getss (self._o, device)
1038 def blockdev_getbsz (self, device):
1039 u"""This returns the block size of a device.
1041 (Note this is different from both *size in blocks* and
1042 *filesystem block size*).
1044 This uses the blockdev(8) command.
1046 return libguestfsmod.blockdev_getbsz (self._o, device)
1048 def blockdev_setbsz (self, device, blocksize):
1049 u"""This sets the block size of a device.
1051 (Note this is different from both *size in blocks* and
1052 *filesystem block size*).
1054 This uses the blockdev(8) command.
1056 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
1058 def blockdev_getsz (self, device):
1059 u"""This returns the size of the device in units of 512-byte
1060 sectors (even if the sectorsize isn't 512 bytes ...
1063 See also "g.blockdev_getss" for the real sector size of
1064 the device, and "g.blockdev_getsize64" for the more
1065 useful *size in bytes*.
1067 This uses the blockdev(8) command.
1069 return libguestfsmod.blockdev_getsz (self._o, device)
1071 def blockdev_getsize64 (self, device):
1072 u"""This returns the size of the device in bytes.
1074 See also "g.blockdev_getsz".
1076 This uses the blockdev(8) command.
1078 return libguestfsmod.blockdev_getsize64 (self._o, device)
1080 def blockdev_flushbufs (self, device):
1081 u"""This tells the kernel to flush internal buffers
1082 associated with "device".
1084 This uses the blockdev(8) command.
1086 return libguestfsmod.blockdev_flushbufs (self._o, device)
1088 def blockdev_rereadpt (self, device):
1089 u"""Reread the partition table on "device".
1091 This uses the blockdev(8) command.
1093 return libguestfsmod.blockdev_rereadpt (self._o, device)
1095 def upload (self, filename, remotefilename):
1096 u"""Upload local file "filename" to "remotefilename" on the
1099 "filename" can also be a named pipe.
1101 See also "g.download".
1103 return libguestfsmod.upload (self._o, filename, remotefilename)
1105 def download (self, remotefilename, filename):
1106 u"""Download file "remotefilename" and save it as "filename"
1107 on the local machine.
1109 "filename" can also be a named pipe.
1111 See also "g.upload", "g.cat".
1113 return libguestfsmod.download (self._o, remotefilename, filename)
1115 def checksum (self, csumtype, path):
1116 u"""This call computes the MD5, SHAx or CRC checksum of the
1119 The type of checksum to compute is given by the
1120 "csumtype" parameter which must have one of the
1124 Compute the cyclic redundancy check (CRC) specified
1125 by POSIX for the "cksum" command.
1128 Compute the MD5 hash (using the "md5sum" program).
1131 Compute the SHA1 hash (using the "sha1sum" program).
1134 Compute the SHA224 hash (using the "sha224sum"
1138 Compute the SHA256 hash (using the "sha256sum"
1142 Compute the SHA384 hash (using the "sha384sum"
1146 Compute the SHA512 hash (using the "sha512sum"
1149 The checksum is returned as a printable string.
1151 return libguestfsmod.checksum (self._o, csumtype, path)
1153 def tar_in (self, tarfile, directory):
1154 u"""This command uploads and unpacks local file "tarfile"
1155 (an *uncompressed* tar file) into "directory".
1157 To upload a compressed tarball, use "g.tgz_in".
1159 return libguestfsmod.tar_in (self._o, tarfile, directory)
1161 def tar_out (self, directory, tarfile):
1162 u"""This command packs the contents of "directory" and
1163 downloads it to local file "tarfile".
1165 To download a compressed tarball, use "g.tgz_out".
1167 return libguestfsmod.tar_out (self._o, directory, tarfile)
1169 def tgz_in (self, tarball, directory):
1170 u"""This command uploads and unpacks local file "tarball" (a
1171 *gzip compressed* tar file) into "directory".
1173 To upload an uncompressed tarball, use "g.tar_in".
1175 return libguestfsmod.tgz_in (self._o, tarball, directory)
1177 def tgz_out (self, directory, tarball):
1178 u"""This command packs the contents of "directory" and
1179 downloads it to local file "tarball".
1181 To download an uncompressed tarball, use "g.tar_out".
1183 return libguestfsmod.tgz_out (self._o, directory, tarball)
1185 def mount_ro (self, device, mountpoint):
1186 u"""This is the same as the "g.mount" command, but it mounts
1187 the filesystem with the read-only (*-o ro*) flag.
1189 return libguestfsmod.mount_ro (self._o, device, mountpoint)
1191 def mount_options (self, options, device, mountpoint):
1192 u"""This is the same as the "g.mount" command, but it allows
1193 you to set the mount options as for the mount(8) *-o*
1196 return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1198 def mount_vfs (self, options, vfstype, device, mountpoint):
1199 u"""This is the same as the "g.mount" command, but it allows
1200 you to set both the mount options and the vfstype as for
1201 the mount(8) *-o* and *-t* flags.
1203 return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1205 def debug (self, subcmd, extraargs):
1206 u"""The "g.debug" command exposes some internals of
1207 "guestfsd" (the guestfs daemon) that runs inside the
1210 There is no comprehensive help for this command. You
1211 have to look at the file "daemon/debug.c" in the
1212 libguestfs source to find out what you can do.
1214 return libguestfsmod.debug (self._o, subcmd, extraargs)
1216 def lvremove (self, device):
1217 u"""Remove an LVM logical volume "device", where "device" is
1218 the path to the LV, such as "/dev/VG/LV".
1220 You can also remove all LVs in a volume group by
1221 specifying the VG name, "/dev/VG".
1223 return libguestfsmod.lvremove (self._o, device)
1225 def vgremove (self, vgname):
1226 u"""Remove an LVM volume group "vgname", (for example "VG").
1228 This also forcibly removes all logical volumes in the
1229 volume group (if any).
1231 return libguestfsmod.vgremove (self._o, vgname)
1233 def pvremove (self, device):
1234 u"""This wipes a physical volume "device" so that LVM will
1235 no longer recognise it.
1237 The implementation uses the "pvremove" command which
1238 refuses to wipe physical volumes that contain any volume
1239 groups, so you have to remove those first.
1241 return libguestfsmod.pvremove (self._o, device)
1243 def set_e2label (self, device, label):
1244 u"""This sets the ext2/3/4 filesystem label of the
1245 filesystem on "device" to "label". Filesystem labels are
1246 limited to 16 characters.
1248 You can use either "g.tune2fs_l" or "g.get_e2label" to
1249 return the existing label on a filesystem.
1251 return libguestfsmod.set_e2label (self._o, device, label)
1253 def get_e2label (self, device):
1254 u"""This returns the ext2/3/4 filesystem label of the
1255 filesystem on "device".
1257 return libguestfsmod.get_e2label (self._o, device)
1259 def set_e2uuid (self, device, uuid):
1260 u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1261 on "device" to "uuid". The format of the UUID and
1262 alternatives such as "clear", "random" and "time" are
1263 described in the tune2fs(8) manpage.
1265 You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1266 return the existing UUID of a filesystem.
1268 return libguestfsmod.set_e2uuid (self._o, device, uuid)
1270 def get_e2uuid (self, device):
1271 u"""This returns the ext2/3/4 filesystem UUID of the
1272 filesystem on "device".
1274 return libguestfsmod.get_e2uuid (self._o, device)
1276 def fsck (self, fstype, device):
1277 u"""This runs the filesystem checker (fsck) on "device"
1278 which should have filesystem type "fstype".
1280 The returned integer is the status. See fsck(8) for the
1281 list of status codes from "fsck".
1285 * Multiple status codes can be summed together.
1287 * A non-zero return code can mean "success", for
1288 example if errors have been corrected on the
1291 * Checking or repairing NTFS volumes is not supported
1294 This command is entirely equivalent to running "fsck -a
1297 return libguestfsmod.fsck (self._o, fstype, device)
1299 def zero (self, device):
1300 u"""This command writes zeroes over the first few blocks of
1303 How many blocks are zeroed isn't specified (but it's
1304 *not* enough to securely wipe the device). It should be
1305 sufficient to remove any partition tables, filesystem
1306 superblocks and so on.
1308 return libguestfsmod.zero (self._o, device)
1310 def grub_install (self, root, device):
1311 u"""This command installs GRUB (the Grand Unified
1312 Bootloader) on "device", with the root directory being
1315 return libguestfsmod.grub_install (self._o, root, device)
1317 def cp (self, src, dest):
1318 u"""This copies a file from "src" to "dest" where "dest" is
1319 either a destination filename or destination directory.
1321 return libguestfsmod.cp (self._o, src, dest)
1323 def cp_a (self, src, dest):
1324 u"""This copies a file or directory from "src" to "dest"
1325 recursively using the "cp -a" command.
1327 return libguestfsmod.cp_a (self._o, src, dest)
1329 def mv (self, src, dest):
1330 u"""This moves a file from "src" to "dest" where "dest" is
1331 either a destination filename or destination directory.
1333 return libguestfsmod.mv (self._o, src, dest)
1335 def drop_caches (self, whattodrop):
1336 u"""This instructs the guest kernel to drop its page cache,
1337 and/or dentries and inode caches. The parameter
1338 "whattodrop" tells the kernel what precisely to drop,
1339 see <http://linux-mm.org/Drop_Caches>
1341 Setting "whattodrop" to 3 should drop everything.
1343 This automatically calls sync(2) before the operation,
1344 so that the maximum guest memory is freed.
1346 return libguestfsmod.drop_caches (self._o, whattodrop)
1349 u"""This returns the kernel messages ("dmesg" output) from
1350 the guest kernel. This is sometimes useful for extended
1351 debugging of problems.
1353 Another way to get the same information is to enable
1354 verbose messages with "g.set_verbose" or by setting the
1355 environment variable "LIBGUESTFS_DEBUG=1" before running
1358 return libguestfsmod.dmesg (self._o)
1360 def ping_daemon (self):
1361 u"""This is a test probe into the guestfs daemon running
1362 inside the qemu subprocess. Calling this function checks
1363 that the daemon responds to the ping message, without
1364 affecting the daemon or attached block device(s) in any
1367 return libguestfsmod.ping_daemon (self._o)
1369 def equal (self, file1, file2):
1370 u"""This compares the two files "file1" and "file2" and
1371 returns true if their content is exactly equal, or false
1374 The external cmp(1) program is used for the comparison.
1376 return libguestfsmod.equal (self._o, file1, file2)
1378 def strings (self, path):
1379 u"""This runs the strings(1) command on a file and returns
1380 the list of printable strings found.
1382 This function returns a list of strings.
1384 Because of the message protocol, there is a transfer
1385 limit of somewhere between 2MB and 4MB. To transfer
1386 large files you should use FTP.
1388 return libguestfsmod.strings (self._o, path)
1390 def strings_e (self, encoding, path):
1391 u"""This is like the "g.strings" command, but allows you to
1392 specify the encoding.
1394 See the strings(1) manpage for the full list of
1397 Commonly useful encodings are "l" (lower case L) which
1398 will show strings inside Windows/x86 files.
1400 The returned strings are transcoded to UTF-8.
1402 This function returns a list of strings.
1404 Because of the message protocol, there is a transfer
1405 limit of somewhere between 2MB and 4MB. To transfer
1406 large files you should use FTP.
1408 return libguestfsmod.strings_e (self._o, encoding, path)
1410 def hexdump (self, path):
1411 u"""This runs "hexdump -C" on the given "path". The result
1412 is the human-readable, canonical hex dump of the file.
1414 Because of the message protocol, there is a transfer
1415 limit of somewhere between 2MB and 4MB. To transfer
1416 large files you should use FTP.
1418 return libguestfsmod.hexdump (self._o, path)
1420 def zerofree (self, device):
1421 u"""This runs the *zerofree* program on "device". This
1422 program claims to zero unused inodes and disk blocks on
1423 an ext2/3 filesystem, thus making it possible to
1424 compress the filesystem more effectively.
1426 You should not run this program if the filesystem is
1429 It is possible that using this program can damage the
1430 filesystem or data on the filesystem.
1432 return libguestfsmod.zerofree (self._o, device)
1434 def pvresize (self, device):
1435 u"""This resizes (expands or shrinks) an existing LVM
1436 physical volume to match the new size of the underlying
1439 return libguestfsmod.pvresize (self._o, device)
1441 def sfdisk_N (self, device, n, cyls, heads, sectors, line):
1442 u"""This runs sfdisk(8) option to modify just the single
1443 partition "n" (note: "n" counts from 1).
1445 For other parameters, see "g.sfdisk". You should usually
1446 pass 0 for the cyls/heads/sectors parameters.
1448 This command is dangerous. Without careful use you can
1449 easily destroy all your data.
1451 return libguestfsmod.sfdisk_N (self._o, device, n, cyls, heads, sectors, line)
1453 def sfdisk_l (self, device):
1454 u"""This displays the partition table on "device", in the
1455 human-readable output of the sfdisk(8) command. It is
1456 not intended to be parsed.
1458 return libguestfsmod.sfdisk_l (self._o, device)
1460 def sfdisk_kernel_geometry (self, device):
1461 u"""This displays the kernel's idea of the geometry of
1464 The result is in human-readable format, and not designed
1467 return libguestfsmod.sfdisk_kernel_geometry (self._o, device)
1469 def sfdisk_disk_geometry (self, device):
1470 u"""This displays the disk geometry of "device" read from
1471 the partition table. Especially in the case where the
1472 underlying block device has been resized, this can be
1473 different from the kernel's idea of the geometry (see
1474 "g.sfdisk_kernel_geometry").
1476 The result is in human-readable format, and not designed
1479 return libguestfsmod.sfdisk_disk_geometry (self._o, device)
1481 def vg_activate_all (self, activate):
1482 u"""This command activates or (if "activate" is false)
1483 deactivates all logical volumes in all volume groups. If
1484 activated, then they are made known to the kernel, ie.
1485 they appear as "/dev/mapper" devices. If deactivated,
1486 then those devices disappear.
1488 This command is the same as running "vgchange -a y|n"
1490 return libguestfsmod.vg_activate_all (self._o, activate)
1492 def vg_activate (self, activate, volgroups):
1493 u"""This command activates or (if "activate" is false)
1494 deactivates all logical volumes in the listed volume
1495 groups "volgroups". If activated, then they are made
1496 known to the kernel, ie. they appear as "/dev/mapper"
1497 devices. If deactivated, then those devices disappear.
1499 This command is the same as running "vgchange -a y|n
1502 Note that if "volgroups" is an empty list then all
1503 volume groups are activated or deactivated.
1505 return libguestfsmod.vg_activate (self._o, activate, volgroups)
1507 def lvresize (self, device, mbytes):
1508 u"""This resizes (expands or shrinks) an existing LVM
1509 logical volume to "mbytes". When reducing, data in the
1510 reduced part is lost.
1512 return libguestfsmod.lvresize (self._o, device, mbytes)
1514 def resize2fs (self, device):
1515 u"""This resizes an ext2 or ext3 filesystem to match the
1516 size of the underlying device.
1518 *Note:* It is sometimes required that you run
1519 "g.e2fsck_f" on the "device" before calling this
1520 command. For unknown reasons "resize2fs" sometimes gives
1521 an error about this and sometimes not. In any case, it
1522 is always safe to call "g.e2fsck_f" before calling this
1525 return libguestfsmod.resize2fs (self._o, device)
1527 def find (self, directory):
1528 u"""This command lists out all files and directories,
1529 recursively, starting at "directory". It is essentially
1530 equivalent to running the shell command "find directory
1531 -print" but some post-processing happens on the output,
1534 This returns a list of strings *without any prefix*.
1535 Thus if the directory structure was:
1541 then the returned list from "g.find" "/tmp" would be 4
1549 If "directory" is not a directory, then this command
1552 The returned list is sorted.
1554 This function returns a list of strings.
1556 return libguestfsmod.find (self._o, directory)
1558 def e2fsck_f (self, device):
1559 u"""This runs "e2fsck -p -f device", ie. runs the ext2/ext3
1560 filesystem checker on "device", noninteractively ("-p"),
1561 even if the filesystem appears to be clean ("-f").
1563 This command is only needed because of "g.resize2fs"
1564 (q.v.). Normally you should use "g.fsck".
1566 return libguestfsmod.e2fsck_f (self._o, device)