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 Note that this call checks for the existence of
203 "filename". This stops you from specifying other types
204 of drive which are supported by qemu such as "nbd:" and
205 "http:" URLs. To specify those, use the general
206 "g.config" call instead.
208 return libguestfsmod.add_drive (self._o, filename)
210 def add_cdrom (self, filename):
211 u"""This function adds a virtual CD-ROM disk image to the
214 This is equivalent to the qemu parameter "-cdrom
217 Note that this call checks for the existence of
218 "filename". This stops you from specifying other types
219 of drive which are supported by qemu such as "nbd:" and
220 "http:" URLs. To specify those, use the general
221 "g.config" call instead.
223 return libguestfsmod.add_cdrom (self._o, filename)
225 def add_drive_ro (self, filename):
226 u"""This adds a drive in snapshot mode, making it
227 effectively read-only.
229 Note that writes to the device are allowed, and will be
230 seen for the duration of the guestfs handle, but they
231 are written to a temporary file which is discarded as
232 soon as the guestfs handle is closed. We don't currently
233 have any method to enable changes to be committed,
234 although qemu can support this.
236 This is equivalent to the qemu parameter "-drive
237 file=filename,snapshot=on".
239 Note that this call checks for the existence of
240 "filename". This stops you from specifying other types
241 of drive which are supported by qemu such as "nbd:" and
242 "http:" URLs. To specify those, use the general
243 "g.config" call instead.
245 return libguestfsmod.add_drive_ro (self._o, filename)
247 def config (self, qemuparam, qemuvalue):
248 u"""This can be used to add arbitrary qemu command line
249 parameters of the form "-param value". Actually it's not
250 quite arbitrary - we prevent you from setting some
251 parameters which would interfere with parameters that we
254 The first character of "param" string must be a "-"
259 return libguestfsmod.config (self._o, qemuparam, qemuvalue)
261 def set_qemu (self, qemu):
262 u"""Set the qemu binary that we will use.
264 The default is chosen when the library was compiled by
265 the configure script.
267 You can also override this by setting the
268 "LIBGUESTFS_QEMU" environment variable.
270 Setting "qemu" to "NULL" restores the default qemu
273 return libguestfsmod.set_qemu (self._o, qemu)
276 u"""Return the current qemu binary.
278 This is always non-NULL. If it wasn't set already, then
279 this will return the default qemu binary name.
281 return libguestfsmod.get_qemu (self._o)
283 def set_path (self, path):
284 u"""Set the path that libguestfs searches for kernel and
287 The default is "$libdir/guestfs" unless overridden by
288 setting "LIBGUESTFS_PATH" environment variable.
290 Setting "path" to "NULL" restores the default path.
292 return libguestfsmod.set_path (self._o, path)
295 u"""Return the current search path.
297 This is always non-NULL. If it wasn't set already, then
298 this will return the default path.
300 return libguestfsmod.get_path (self._o)
302 def set_append (self, append):
303 u"""This function is used to add additional options to the
304 guest kernel command line.
306 The default is "NULL" unless overridden by setting
307 "LIBGUESTFS_APPEND" environment variable.
309 Setting "append" to "NULL" means *no* additional options
310 are passed (libguestfs always adds a few of its own).
312 return libguestfsmod.set_append (self._o, append)
314 def get_append (self):
315 u"""Return the additional kernel options which are added to
316 the guest kernel command line.
318 If "NULL" then no options are added.
320 return libguestfsmod.get_append (self._o)
322 def set_autosync (self, autosync):
323 u"""If "autosync" is true, this enables autosync. Libguestfs
324 will make a best effort attempt to run "g.umount_all"
325 followed by "g.sync" when the handle is closed (also if
326 the program exits without closing handles).
328 This is disabled by default (except in guestfish where
329 it is enabled by default).
331 return libguestfsmod.set_autosync (self._o, autosync)
333 def get_autosync (self):
334 u"""Get the autosync flag.
336 return libguestfsmod.get_autosync (self._o)
338 def set_verbose (self, verbose):
339 u"""If "verbose" is true, this turns on verbose messages (to
342 Verbose messages are disabled unless the environment
343 variable "LIBGUESTFS_DEBUG" is defined and set to 1.
345 return libguestfsmod.set_verbose (self._o, verbose)
347 def get_verbose (self):
348 u"""This returns the verbose messages flag.
350 return libguestfsmod.get_verbose (self._o)
353 u"""This returns true iff this handle is ready to accept
354 commands (in the "READY" state).
356 For more information on states, see guestfs(3).
358 return libguestfsmod.is_ready (self._o)
360 def is_config (self):
361 u"""This returns true iff this handle is being configured
362 (in the "CONFIG" state).
364 For more information on states, see guestfs(3).
366 return libguestfsmod.is_config (self._o)
368 def is_launching (self):
369 u"""This returns true iff this handle is launching the
370 subprocess (in the "LAUNCHING" state).
372 For more information on states, see guestfs(3).
374 return libguestfsmod.is_launching (self._o)
377 u"""This returns true iff this handle is busy processing a
378 command (in the "BUSY" state).
380 For more information on states, see guestfs(3).
382 return libguestfsmod.is_busy (self._o)
384 def get_state (self):
385 u"""This returns the current state as an opaque integer.
386 This is only useful for printing debug and internal
389 For more information on states, see guestfs(3).
391 return libguestfsmod.get_state (self._o)
394 u"""This sets the state to "BUSY". This is only used when
395 implementing actions using the low-level API.
397 For more information on states, see guestfs(3).
399 return libguestfsmod.set_busy (self._o)
401 def set_ready (self):
402 u"""This sets the state to "READY". This is only used when
403 implementing actions using the low-level API.
405 For more information on states, see guestfs(3).
407 return libguestfsmod.set_ready (self._o)
410 u"""This sets the state to "READY", or if in "CONFIG" then
411 it leaves the state as is. This is only used when
412 implementing actions using the low-level API.
414 For more information on states, see guestfs(3).
416 return libguestfsmod.end_busy (self._o)
418 def mount (self, device, mountpoint):
419 u"""Mount a guest disk at a position in the filesystem.
420 Block devices are named "/dev/sda", "/dev/sdb" and so
421 on, as they were added to the guest. If those block
422 devices contain partitions, they will have the usual
423 names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
426 The rules are the same as for mount(2): A filesystem
427 must first be mounted on "/" before others can be
428 mounted. Other filesystems can only be mounted on
429 directories which already exist.
431 The mounted filesystem is writable, if we have
432 sufficient permissions on the underlying device.
434 The filesystem options "sync" and "noatime" are set with
435 this call, in order to improve reliability.
437 return libguestfsmod.mount (self._o, device, mountpoint)
440 u"""This syncs the disk, so that any writes are flushed
441 through to the underlying disk image.
443 You should always call this if you have modified a disk
444 image, before closing the handle.
446 return libguestfsmod.sync (self._o)
448 def touch (self, path):
449 u"""Touch acts like the touch(1) command. It can be used to
450 update the timestamps on a file, or, if the file does
451 not exist, to create a new zero-length file.
453 return libguestfsmod.touch (self._o, path)
455 def cat (self, path):
456 u"""Return the contents of the file named "path".
458 Note that this function cannot correctly handle binary
459 files (specifically, files containing "\\0" character
460 which is treated as end of string). For those you need
461 to use the "g.download" function which has a more
464 Because of the message protocol, there is a transfer
465 limit of somewhere between 2MB and 4MB. To transfer
466 large files you should use FTP.
468 return libguestfsmod.cat (self._o, path)
470 def ll (self, directory):
471 u"""List the files in "directory" (relative to the root
472 directory, there is no cwd) in the format of 'ls -la'.
474 This command is mostly useful for interactive sessions.
475 It is *not* intended that you try to parse the output
478 return libguestfsmod.ll (self._o, directory)
480 def ls (self, directory):
481 u"""List the files in "directory" (relative to the root
482 directory, there is no cwd). The '.' and '..' entries
483 are not returned, but hidden files are shown.
485 This command is mostly useful for interactive sessions.
486 Programs should probably use "g.readdir" instead.
488 This function returns a list of strings.
490 return libguestfsmod.ls (self._o, directory)
492 def list_devices (self):
493 u"""List all the block devices.
495 The full block device names are returned, eg. "/dev/sda"
497 This function returns a list of strings.
499 return libguestfsmod.list_devices (self._o)
501 def list_partitions (self):
502 u"""List all the partitions detected on all block devices.
504 The full partition device names are returned, eg.
507 This does not return logical volumes. For that you will
508 need to call "g.lvs".
510 This function returns a list of strings.
512 return libguestfsmod.list_partitions (self._o)
515 u"""List all the physical volumes detected. This is the
516 equivalent of the pvs(8) command.
518 This returns a list of just the device names that
519 contain PVs (eg. "/dev/sda2").
521 See also "g.pvs_full".
523 This function returns a list of strings.
525 return libguestfsmod.pvs (self._o)
528 u"""List all the volumes groups detected. This is the
529 equivalent of the vgs(8) command.
531 This returns a list of just the volume group names that
532 were detected (eg. "VolGroup00").
534 See also "g.vgs_full".
536 This function returns a list of strings.
538 return libguestfsmod.vgs (self._o)
541 u"""List all the logical volumes detected. This is the
542 equivalent of the lvs(8) command.
544 This returns a list of the logical volume device names
545 (eg. "/dev/VolGroup00/LogVol00").
547 See also "g.lvs_full".
549 This function returns a list of strings.
551 return libguestfsmod.lvs (self._o)
554 u"""List all the physical volumes detected. This is the
555 equivalent of the pvs(8) command. The "full" version
558 This function returns a list of PVs. Each PV is
559 represented as a dictionary.
561 return libguestfsmod.pvs_full (self._o)
564 u"""List all the volumes groups detected. This is the
565 equivalent of the vgs(8) command. The "full" version
568 This function returns a list of VGs. Each VG is
569 represented as a dictionary.
571 return libguestfsmod.vgs_full (self._o)
574 u"""List all the logical volumes detected. This is the
575 equivalent of the lvs(8) command. The "full" version
578 This function returns a list of LVs. Each LV is
579 represented as a dictionary.
581 return libguestfsmod.lvs_full (self._o)
583 def read_lines (self, path):
584 u"""Return the contents of the file named "path".
586 The file contents are returned as a list of lines.
587 Trailing "LF" and "CRLF" character sequences are *not*
590 Note that this function cannot correctly handle binary
591 files (specifically, files containing "\\0" character
592 which is treated as end of line). For those you need to
593 use the "g.read_file" function which has a more complex
596 This function returns a list of strings.
598 return libguestfsmod.read_lines (self._o, path)
600 def aug_init (self, root, flags):
601 u"""Create a new Augeas handle for editing configuration
602 files. If there was any previous Augeas handle
603 associated with this guestfs session, then it is closed.
605 You must call this before using any other "g.aug_*"
608 "root" is the filesystem root. "root" must not be NULL,
611 The flags are the same as the flags defined in
612 <augeas.h>, the logical *or* of the following integers:
614 "AUG_SAVE_BACKUP" = 1
615 Keep the original file with a ".augsave" extension.
617 "AUG_SAVE_NEWFILE" = 2
618 Save changes into a file with extension ".augnew",
619 and do not overwrite original. Overrides
623 Typecheck lenses (can be expensive).
626 Do not use standard load path for modules.
629 Make save a no-op, just record what would have been
633 Do not load the tree in "g.aug_init".
635 To close the handle, you can call "g.aug_close".
637 To find out more about Augeas, see <http://augeas.net/>.
639 return libguestfsmod.aug_init (self._o, root, flags)
641 def aug_close (self):
642 u"""Close the current Augeas handle and free up any
643 resources used by it. After calling this, you have to
644 call "g.aug_init" again before you can use any other
647 return libguestfsmod.aug_close (self._o)
649 def aug_defvar (self, name, expr):
650 u"""Defines an Augeas variable "name" whose value is the
651 result of evaluating "expr". If "expr" is NULL, then
654 On success this returns the number of nodes in "expr",
655 or 0 if "expr" evaluates to something which is not a
658 return libguestfsmod.aug_defvar (self._o, name, expr)
660 def aug_defnode (self, name, expr, val):
661 u"""Defines a variable "name" whose value is the result of
664 If "expr" evaluates to an empty nodeset, a node is
665 created, equivalent to calling "g.aug_set" "expr",
666 "value". "name" will be the nodeset containing that
669 On success this returns a pair containing the number of
670 nodes in the nodeset, and a boolean flag if a node was
673 This function returns a tuple (int, bool).
675 return libguestfsmod.aug_defnode (self._o, name, expr, val)
677 def aug_get (self, path):
678 u"""Look up the value associated with "path". If "path"
679 matches exactly one node, the "value" is returned.
681 return libguestfsmod.aug_get (self._o, path)
683 def aug_set (self, path, val):
684 u"""Set the value associated with "path" to "value".
686 return libguestfsmod.aug_set (self._o, path, val)
688 def aug_insert (self, path, label, before):
689 u"""Create a new sibling "label" for "path", inserting it
690 into the tree before or after "path" (depending on the
691 boolean flag "before").
693 "path" must match exactly one existing node in the tree,
694 and "label" must be a label, ie. not contain "/", "*" or
695 end with a bracketed index "[N]".
697 return libguestfsmod.aug_insert (self._o, path, label, before)
699 def aug_rm (self, path):
700 u"""Remove "path" and all of its children.
702 On success this returns the number of entries which were
705 return libguestfsmod.aug_rm (self._o, path)
707 def aug_mv (self, src, dest):
708 u"""Move the node "src" to "dest". "src" must match exactly
709 one node. "dest" is overwritten if it exists.
711 return libguestfsmod.aug_mv (self._o, src, dest)
713 def aug_match (self, path):
714 u"""Returns a list of paths which match the path expression
715 "path". The returned paths are sufficiently qualified so
716 that they match exactly one node in the current tree.
718 This function returns a list of strings.
720 return libguestfsmod.aug_match (self._o, path)
723 u"""This writes all pending changes to disk.
725 The flags which were passed to "g.aug_init" affect
726 exactly how files are saved.
728 return libguestfsmod.aug_save (self._o)
731 u"""Load files into the tree.
733 See "aug_load" in the Augeas documentation for the full
736 return libguestfsmod.aug_load (self._o)
738 def aug_ls (self, path):
739 u"""This is just a shortcut for listing "g.aug_match"
740 "path/*" and sorting the resulting nodes into
743 This function returns a list of strings.
745 return libguestfsmod.aug_ls (self._o, path)
748 u"""Remove the single file "path".
750 return libguestfsmod.rm (self._o, path)
752 def rmdir (self, path):
753 u"""Remove the single directory "path".
755 return libguestfsmod.rmdir (self._o, path)
757 def rm_rf (self, path):
758 u"""Remove the file or directory "path", recursively
759 removing the contents if its a directory. This is like
760 the "rm -rf" shell command.
762 return libguestfsmod.rm_rf (self._o, path)
764 def mkdir (self, path):
765 u"""Create a directory named "path".
767 return libguestfsmod.mkdir (self._o, path)
769 def mkdir_p (self, path):
770 u"""Create a directory named "path", creating any parent
771 directories as necessary. This is like the "mkdir -p"
774 return libguestfsmod.mkdir_p (self._o, path)
776 def chmod (self, mode, path):
777 u"""Change the mode (permissions) of "path" to "mode". Only
778 numeric modes are supported.
780 return libguestfsmod.chmod (self._o, mode, path)
782 def chown (self, owner, group, path):
783 u"""Change the file owner to "owner" and group to "group".
785 Only numeric uid and gid are supported. If you want to
786 use names, you will need to locate and parse the
787 password file yourself (Augeas support makes this
790 return libguestfsmod.chown (self._o, owner, group, path)
792 def exists (self, path):
793 u"""This returns "true" if and only if there is a file,
794 directory (or anything) with the given "path" name.
796 See also "g.is_file", "g.is_dir", "g.stat".
798 return libguestfsmod.exists (self._o, path)
800 def is_file (self, path):
801 u"""This returns "true" if and only if there is a file with
802 the given "path" name. Note that it returns false for
803 other objects like directories.
807 return libguestfsmod.is_file (self._o, path)
809 def is_dir (self, path):
810 u"""This returns "true" if and only if there is a directory
811 with the given "path" name. Note that it returns false
812 for other objects like files.
816 return libguestfsmod.is_dir (self._o, path)
818 def pvcreate (self, device):
819 u"""This creates an LVM physical volume on the named
820 "device", where "device" should usually be a partition
821 name such as "/dev/sda1".
823 return libguestfsmod.pvcreate (self._o, device)
825 def vgcreate (self, volgroup, physvols):
826 u"""This creates an LVM volume group called "volgroup" from
827 the non-empty list of physical volumes "physvols".
829 return libguestfsmod.vgcreate (self._o, volgroup, physvols)
831 def lvcreate (self, logvol, volgroup, mbytes):
832 u"""This creates an LVM volume group called "logvol" on the
833 volume group "volgroup", with "size" megabytes.
835 return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
837 def mkfs (self, fstype, device):
838 u"""This creates a filesystem on "device" (usually a
839 partition or LVM logical volume). The filesystem type is
840 "fstype", for example "ext3".
842 return libguestfsmod.mkfs (self._o, fstype, device)
844 def sfdisk (self, device, cyls, heads, sectors, lines):
845 u"""This is a direct interface to the sfdisk(8) program for
846 creating partitions on block devices.
848 "device" should be a block device, for example
851 "cyls", "heads" and "sectors" are the number of
852 cylinders, heads and sectors on the device, which are
853 passed directly to sfdisk as the *-C*, *-H* and *-S*
854 parameters. If you pass 0 for any of these, then the
855 corresponding parameter is omitted. Usually for 'large'
856 disks, you can just pass 0 for these, but for small
857 (floppy-sized) disks, sfdisk (or rather, the kernel)
858 cannot work out the right geometry and you will need to
861 "lines" is a list of lines that we feed to "sfdisk". For
862 more information refer to the sfdisk(8) manpage.
864 To create a single partition occupying the whole disk,
865 you would pass "lines" as a single element list, when
866 the single element being the string "," (comma).
868 See also: "g.sfdisk_l", "g.sfdisk_N"
870 This command is dangerous. Without careful use you can
871 easily destroy all your data.
873 return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
875 def write_file (self, path, content, size):
876 u"""This call creates a file called "path". The contents of
877 the file is the string "content" (which can contain any
878 8 bit data), with length "size".
880 As a special case, if "size" is 0 then the length is
881 calculated using "strlen" (so in this case the content
882 cannot contain embedded ASCII NULs).
884 *NB.* Owing to a bug, writing content containing ASCII
885 NUL characters does *not* work, even if the length is
886 specified. We hope to resolve this bug in a future
887 version. In the meantime use "g.upload".
889 Because of the message protocol, there is a transfer
890 limit of somewhere between 2MB and 4MB. To transfer
891 large files you should use FTP.
893 return libguestfsmod.write_file (self._o, path, content, size)
895 def umount (self, pathordevice):
896 u"""This unmounts the given filesystem. The filesystem may
897 be specified either by its mountpoint (path) or the
898 device which contains the filesystem.
900 return libguestfsmod.umount (self._o, pathordevice)
903 u"""This returns the list of currently mounted filesystems.
904 It returns the list of devices (eg. "/dev/sda1",
907 Some internal mounts are not shown.
909 This function returns a list of strings.
911 return libguestfsmod.mounts (self._o)
913 def umount_all (self):
914 u"""This unmounts all mounted filesystems.
916 Some internal mounts are not unmounted by this call.
918 return libguestfsmod.umount_all (self._o)
920 def lvm_remove_all (self):
921 u"""This command removes all LVM logical volumes, volume
922 groups and physical volumes.
924 This command is dangerous. Without careful use you can
925 easily destroy all your data.
927 return libguestfsmod.lvm_remove_all (self._o)
929 def file (self, path):
930 u"""This call uses the standard file(1) command to determine
931 the type or contents of the file. This also works on
932 devices, for example to find out whether a partition
933 contains a filesystem.
935 The exact command which runs is "file -bsL path". Note
936 in particular that the filename is not prepended to the
937 output (the "-b" option).
939 return libguestfsmod.file (self._o, path)
941 def command (self, arguments):
942 u"""This call runs a command from the guest filesystem. The
943 filesystem must be mounted, and must contain a
944 compatible operating system (ie. something Linux, with
945 the same or compatible processor architecture).
947 The single parameter is an argv-style list of arguments.
948 The first element is the name of the program to run.
949 Subsequent elements are parameters. The list must be
950 non-empty (ie. must contain a program name). Note that
951 the command runs directly, and is *not* invoked via the
954 The return value is anything printed to *stdout* by the
957 If the command returns a non-zero exit status, then this
958 function returns an error message. The error message
959 string is the content of *stderr* from the command.
961 The $PATH environment variable will contain at least
962 "/usr/bin" and "/bin". If you require a program from
963 another location, you should provide the full path in
966 Shared libraries and data files required by the program
967 must be available on filesystems which are mounted in
968 the correct places. It is the caller's responsibility to
969 ensure all filesystems that are needed are mounted at
972 Because of the message protocol, there is a transfer
973 limit of somewhere between 2MB and 4MB. To transfer
974 large files you should use FTP.
976 return libguestfsmod.command (self._o, arguments)
978 def command_lines (self, arguments):
979 u"""This is the same as "g.command", but splits the result
980 into a list of lines.
982 See also: "g.sh_lines"
984 This function returns a list of strings.
986 Because of the message protocol, there is a transfer
987 limit of somewhere between 2MB and 4MB. To transfer
988 large files you should use FTP.
990 return libguestfsmod.command_lines (self._o, arguments)
992 def stat (self, path):
993 u"""Returns file information for the given "path".
995 This is the same as the stat(2) system call.
997 This function returns a dictionary, with keys matching
998 the various fields in the stat structure.
1000 return libguestfsmod.stat (self._o, path)
1002 def lstat (self, path):
1003 u"""Returns file information for the given "path".
1005 This is the same as "g.stat" except that if "path" is a
1006 symbolic link, then the link is stat-ed, not the file it
1009 This is the same as the lstat(2) system call.
1011 This function returns a dictionary, with keys matching
1012 the various fields in the stat structure.
1014 return libguestfsmod.lstat (self._o, path)
1016 def statvfs (self, path):
1017 u"""Returns file system statistics for any mounted file
1018 system. "path" should be a file or directory in the
1019 mounted file system (typically it is the mount point
1020 itself, but it doesn't need to be).
1022 This is the same as the statvfs(2) system call.
1024 This function returns a dictionary, with keys matching
1025 the various fields in the statvfs structure.
1027 return libguestfsmod.statvfs (self._o, path)
1029 def tune2fs_l (self, device):
1030 u"""This returns the contents of the ext2, ext3 or ext4
1031 filesystem superblock on "device".
1033 It is the same as running "tune2fs -l device". See
1034 tune2fs(8) manpage for more details. The list of fields
1035 returned isn't clearly defined, and depends on both the
1036 version of "tune2fs" that libguestfs was built against,
1037 and the filesystem itself.
1039 This function returns a dictionary.
1041 return libguestfsmod.tune2fs_l (self._o, device)
1043 def blockdev_setro (self, device):
1044 u"""Sets the block device named "device" to read-only.
1046 This uses the blockdev(8) command.
1048 return libguestfsmod.blockdev_setro (self._o, device)
1050 def blockdev_setrw (self, device):
1051 u"""Sets the block device named "device" to read-write.
1053 This uses the blockdev(8) command.
1055 return libguestfsmod.blockdev_setrw (self._o, device)
1057 def blockdev_getro (self, device):
1058 u"""Returns a boolean indicating if the block device is
1059 read-only (true if read-only, false if not).
1061 This uses the blockdev(8) command.
1063 return libguestfsmod.blockdev_getro (self._o, device)
1065 def blockdev_getss (self, device):
1066 u"""This returns the size of sectors on a block device.
1067 Usually 512, but can be larger for modern devices.
1069 (Note, this is not the size in sectors, use
1070 "g.blockdev_getsz" for that).
1072 This uses the blockdev(8) command.
1074 return libguestfsmod.blockdev_getss (self._o, device)
1076 def blockdev_getbsz (self, device):
1077 u"""This returns the block size of a device.
1079 (Note this is different from both *size in blocks* and
1080 *filesystem block size*).
1082 This uses the blockdev(8) command.
1084 return libguestfsmod.blockdev_getbsz (self._o, device)
1086 def blockdev_setbsz (self, device, blocksize):
1087 u"""This sets the block size of a device.
1089 (Note this is different from both *size in blocks* and
1090 *filesystem block size*).
1092 This uses the blockdev(8) command.
1094 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
1096 def blockdev_getsz (self, device):
1097 u"""This returns the size of the device in units of 512-byte
1098 sectors (even if the sectorsize isn't 512 bytes ...
1101 See also "g.blockdev_getss" for the real sector size of
1102 the device, and "g.blockdev_getsize64" for the more
1103 useful *size in bytes*.
1105 This uses the blockdev(8) command.
1107 return libguestfsmod.blockdev_getsz (self._o, device)
1109 def blockdev_getsize64 (self, device):
1110 u"""This returns the size of the device in bytes.
1112 See also "g.blockdev_getsz".
1114 This uses the blockdev(8) command.
1116 return libguestfsmod.blockdev_getsize64 (self._o, device)
1118 def blockdev_flushbufs (self, device):
1119 u"""This tells the kernel to flush internal buffers
1120 associated with "device".
1122 This uses the blockdev(8) command.
1124 return libguestfsmod.blockdev_flushbufs (self._o, device)
1126 def blockdev_rereadpt (self, device):
1127 u"""Reread the partition table on "device".
1129 This uses the blockdev(8) command.
1131 return libguestfsmod.blockdev_rereadpt (self._o, device)
1133 def upload (self, filename, remotefilename):
1134 u"""Upload local file "filename" to "remotefilename" on the
1137 "filename" can also be a named pipe.
1139 See also "g.download".
1141 return libguestfsmod.upload (self._o, filename, remotefilename)
1143 def download (self, remotefilename, filename):
1144 u"""Download file "remotefilename" and save it as "filename"
1145 on the local machine.
1147 "filename" can also be a named pipe.
1149 See also "g.upload", "g.cat".
1151 return libguestfsmod.download (self._o, remotefilename, filename)
1153 def checksum (self, csumtype, path):
1154 u"""This call computes the MD5, SHAx or CRC checksum of the
1157 The type of checksum to compute is given by the
1158 "csumtype" parameter which must have one of the
1162 Compute the cyclic redundancy check (CRC) specified
1163 by POSIX for the "cksum" command.
1166 Compute the MD5 hash (using the "md5sum" program).
1169 Compute the SHA1 hash (using the "sha1sum" program).
1172 Compute the SHA224 hash (using the "sha224sum"
1176 Compute the SHA256 hash (using the "sha256sum"
1180 Compute the SHA384 hash (using the "sha384sum"
1184 Compute the SHA512 hash (using the "sha512sum"
1187 The checksum is returned as a printable string.
1189 return libguestfsmod.checksum (self._o, csumtype, path)
1191 def tar_in (self, tarfile, directory):
1192 u"""This command uploads and unpacks local file "tarfile"
1193 (an *uncompressed* tar file) into "directory".
1195 To upload a compressed tarball, use "g.tgz_in".
1197 return libguestfsmod.tar_in (self._o, tarfile, directory)
1199 def tar_out (self, directory, tarfile):
1200 u"""This command packs the contents of "directory" and
1201 downloads it to local file "tarfile".
1203 To download a compressed tarball, use "g.tgz_out".
1205 return libguestfsmod.tar_out (self._o, directory, tarfile)
1207 def tgz_in (self, tarball, directory):
1208 u"""This command uploads and unpacks local file "tarball" (a
1209 *gzip compressed* tar file) into "directory".
1211 To upload an uncompressed tarball, use "g.tar_in".
1213 return libguestfsmod.tgz_in (self._o, tarball, directory)
1215 def tgz_out (self, directory, tarball):
1216 u"""This command packs the contents of "directory" and
1217 downloads it to local file "tarball".
1219 To download an uncompressed tarball, use "g.tar_out".
1221 return libguestfsmod.tgz_out (self._o, directory, tarball)
1223 def mount_ro (self, device, mountpoint):
1224 u"""This is the same as the "g.mount" command, but it mounts
1225 the filesystem with the read-only (*-o ro*) flag.
1227 return libguestfsmod.mount_ro (self._o, device, mountpoint)
1229 def mount_options (self, options, device, mountpoint):
1230 u"""This is the same as the "g.mount" command, but it allows
1231 you to set the mount options as for the mount(8) *-o*
1234 return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1236 def mount_vfs (self, options, vfstype, device, mountpoint):
1237 u"""This is the same as the "g.mount" command, but it allows
1238 you to set both the mount options and the vfstype as for
1239 the mount(8) *-o* and *-t* flags.
1241 return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1243 def debug (self, subcmd, extraargs):
1244 u"""The "g.debug" command exposes some internals of
1245 "guestfsd" (the guestfs daemon) that runs inside the
1248 There is no comprehensive help for this command. You
1249 have to look at the file "daemon/debug.c" in the
1250 libguestfs source to find out what you can do.
1252 return libguestfsmod.debug (self._o, subcmd, extraargs)
1254 def lvremove (self, device):
1255 u"""Remove an LVM logical volume "device", where "device" is
1256 the path to the LV, such as "/dev/VG/LV".
1258 You can also remove all LVs in a volume group by
1259 specifying the VG name, "/dev/VG".
1261 return libguestfsmod.lvremove (self._o, device)
1263 def vgremove (self, vgname):
1264 u"""Remove an LVM volume group "vgname", (for example "VG").
1266 This also forcibly removes all logical volumes in the
1267 volume group (if any).
1269 return libguestfsmod.vgremove (self._o, vgname)
1271 def pvremove (self, device):
1272 u"""This wipes a physical volume "device" so that LVM will
1273 no longer recognise it.
1275 The implementation uses the "pvremove" command which
1276 refuses to wipe physical volumes that contain any volume
1277 groups, so you have to remove those first.
1279 return libguestfsmod.pvremove (self._o, device)
1281 def set_e2label (self, device, label):
1282 u"""This sets the ext2/3/4 filesystem label of the
1283 filesystem on "device" to "label". Filesystem labels are
1284 limited to 16 characters.
1286 You can use either "g.tune2fs_l" or "g.get_e2label" to
1287 return the existing label on a filesystem.
1289 return libguestfsmod.set_e2label (self._o, device, label)
1291 def get_e2label (self, device):
1292 u"""This returns the ext2/3/4 filesystem label of the
1293 filesystem on "device".
1295 return libguestfsmod.get_e2label (self._o, device)
1297 def set_e2uuid (self, device, uuid):
1298 u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1299 on "device" to "uuid". The format of the UUID and
1300 alternatives such as "clear", "random" and "time" are
1301 described in the tune2fs(8) manpage.
1303 You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1304 return the existing UUID of a filesystem.
1306 return libguestfsmod.set_e2uuid (self._o, device, uuid)
1308 def get_e2uuid (self, device):
1309 u"""This returns the ext2/3/4 filesystem UUID of the
1310 filesystem on "device".
1312 return libguestfsmod.get_e2uuid (self._o, device)
1314 def fsck (self, fstype, device):
1315 u"""This runs the filesystem checker (fsck) on "device"
1316 which should have filesystem type "fstype".
1318 The returned integer is the status. See fsck(8) for the
1319 list of status codes from "fsck".
1323 * Multiple status codes can be summed together.
1325 * A non-zero return code can mean "success", for
1326 example if errors have been corrected on the
1329 * Checking or repairing NTFS volumes is not supported
1332 This command is entirely equivalent to running "fsck -a
1335 return libguestfsmod.fsck (self._o, fstype, device)
1337 def zero (self, device):
1338 u"""This command writes zeroes over the first few blocks of
1341 How many blocks are zeroed isn't specified (but it's
1342 *not* enough to securely wipe the device). It should be
1343 sufficient to remove any partition tables, filesystem
1344 superblocks and so on.
1346 return libguestfsmod.zero (self._o, device)
1348 def grub_install (self, root, device):
1349 u"""This command installs GRUB (the Grand Unified
1350 Bootloader) on "device", with the root directory being
1353 return libguestfsmod.grub_install (self._o, root, device)
1355 def cp (self, src, dest):
1356 u"""This copies a file from "src" to "dest" where "dest" is
1357 either a destination filename or destination directory.
1359 return libguestfsmod.cp (self._o, src, dest)
1361 def cp_a (self, src, dest):
1362 u"""This copies a file or directory from "src" to "dest"
1363 recursively using the "cp -a" command.
1365 return libguestfsmod.cp_a (self._o, src, dest)
1367 def mv (self, src, dest):
1368 u"""This moves a file from "src" to "dest" where "dest" is
1369 either a destination filename or destination directory.
1371 return libguestfsmod.mv (self._o, src, dest)
1373 def drop_caches (self, whattodrop):
1374 u"""This instructs the guest kernel to drop its page cache,
1375 and/or dentries and inode caches. The parameter
1376 "whattodrop" tells the kernel what precisely to drop,
1377 see <http://linux-mm.org/Drop_Caches>
1379 Setting "whattodrop" to 3 should drop everything.
1381 This automatically calls sync(2) before the operation,
1382 so that the maximum guest memory is freed.
1384 return libguestfsmod.drop_caches (self._o, whattodrop)
1387 u"""This returns the kernel messages ("dmesg" output) from
1388 the guest kernel. This is sometimes useful for extended
1389 debugging of problems.
1391 Another way to get the same information is to enable
1392 verbose messages with "g.set_verbose" or by setting the
1393 environment variable "LIBGUESTFS_DEBUG=1" before running
1396 return libguestfsmod.dmesg (self._o)
1398 def ping_daemon (self):
1399 u"""This is a test probe into the guestfs daemon running
1400 inside the qemu subprocess. Calling this function checks
1401 that the daemon responds to the ping message, without
1402 affecting the daemon or attached block device(s) in any
1405 return libguestfsmod.ping_daemon (self._o)
1407 def equal (self, file1, file2):
1408 u"""This compares the two files "file1" and "file2" and
1409 returns true if their content is exactly equal, or false
1412 The external cmp(1) program is used for the comparison.
1414 return libguestfsmod.equal (self._o, file1, file2)
1416 def strings (self, path):
1417 u"""This runs the strings(1) command on a file and returns
1418 the list of printable strings found.
1420 This function returns a list of strings.
1422 Because of the message protocol, there is a transfer
1423 limit of somewhere between 2MB and 4MB. To transfer
1424 large files you should use FTP.
1426 return libguestfsmod.strings (self._o, path)
1428 def strings_e (self, encoding, path):
1429 u"""This is like the "g.strings" command, but allows you to
1430 specify the encoding.
1432 See the strings(1) manpage for the full list of
1435 Commonly useful encodings are "l" (lower case L) which
1436 will show strings inside Windows/x86 files.
1438 The returned strings are transcoded to UTF-8.
1440 This function returns a list of strings.
1442 Because of the message protocol, there is a transfer
1443 limit of somewhere between 2MB and 4MB. To transfer
1444 large files you should use FTP.
1446 return libguestfsmod.strings_e (self._o, encoding, path)
1448 def hexdump (self, path):
1449 u"""This runs "hexdump -C" on the given "path". The result
1450 is the human-readable, canonical hex dump of the file.
1452 Because of the message protocol, there is a transfer
1453 limit of somewhere between 2MB and 4MB. To transfer
1454 large files you should use FTP.
1456 return libguestfsmod.hexdump (self._o, path)
1458 def zerofree (self, device):
1459 u"""This runs the *zerofree* program on "device". This
1460 program claims to zero unused inodes and disk blocks on
1461 an ext2/3 filesystem, thus making it possible to
1462 compress the filesystem more effectively.
1464 You should not run this program if the filesystem is
1467 It is possible that using this program can damage the
1468 filesystem or data on the filesystem.
1470 return libguestfsmod.zerofree (self._o, device)
1472 def pvresize (self, device):
1473 u"""This resizes (expands or shrinks) an existing LVM
1474 physical volume to match the new size of the underlying
1477 return libguestfsmod.pvresize (self._o, device)
1479 def sfdisk_N (self, device, n, cyls, heads, sectors, line):
1480 u"""This runs sfdisk(8) option to modify just the single
1481 partition "n" (note: "n" counts from 1).
1483 For other parameters, see "g.sfdisk". You should usually
1484 pass 0 for the cyls/heads/sectors parameters.
1486 This command is dangerous. Without careful use you can
1487 easily destroy all your data.
1489 return libguestfsmod.sfdisk_N (self._o, device, n, cyls, heads, sectors, line)
1491 def sfdisk_l (self, device):
1492 u"""This displays the partition table on "device", in the
1493 human-readable output of the sfdisk(8) command. It is
1494 not intended to be parsed.
1496 return libguestfsmod.sfdisk_l (self._o, device)
1498 def sfdisk_kernel_geometry (self, device):
1499 u"""This displays the kernel's idea of the geometry of
1502 The result is in human-readable format, and not designed
1505 return libguestfsmod.sfdisk_kernel_geometry (self._o, device)
1507 def sfdisk_disk_geometry (self, device):
1508 u"""This displays the disk geometry of "device" read from
1509 the partition table. Especially in the case where the
1510 underlying block device has been resized, this can be
1511 different from the kernel's idea of the geometry (see
1512 "g.sfdisk_kernel_geometry").
1514 The result is in human-readable format, and not designed
1517 return libguestfsmod.sfdisk_disk_geometry (self._o, device)
1519 def vg_activate_all (self, activate):
1520 u"""This command activates or (if "activate" is false)
1521 deactivates all logical volumes in all volume groups. If
1522 activated, then they are made known to the kernel, ie.
1523 they appear as "/dev/mapper" devices. If deactivated,
1524 then those devices disappear.
1526 This command is the same as running "vgchange -a y|n"
1528 return libguestfsmod.vg_activate_all (self._o, activate)
1530 def vg_activate (self, activate, volgroups):
1531 u"""This command activates or (if "activate" is false)
1532 deactivates all logical volumes in the listed volume
1533 groups "volgroups". If activated, then they are made
1534 known to the kernel, ie. they appear as "/dev/mapper"
1535 devices. If deactivated, then those devices disappear.
1537 This command is the same as running "vgchange -a y|n
1540 Note that if "volgroups" is an empty list then all
1541 volume groups are activated or deactivated.
1543 return libguestfsmod.vg_activate (self._o, activate, volgroups)
1545 def lvresize (self, device, mbytes):
1546 u"""This resizes (expands or shrinks) an existing LVM
1547 logical volume to "mbytes". When reducing, data in the
1548 reduced part is lost.
1550 return libguestfsmod.lvresize (self._o, device, mbytes)
1552 def resize2fs (self, device):
1553 u"""This resizes an ext2 or ext3 filesystem to match the
1554 size of the underlying device.
1556 *Note:* It is sometimes required that you run
1557 "g.e2fsck_f" on the "device" before calling this
1558 command. For unknown reasons "resize2fs" sometimes gives
1559 an error about this and sometimes not. In any case, it
1560 is always safe to call "g.e2fsck_f" before calling this
1563 return libguestfsmod.resize2fs (self._o, device)
1565 def find (self, directory):
1566 u"""This command lists out all files and directories,
1567 recursively, starting at "directory". It is essentially
1568 equivalent to running the shell command "find directory
1569 -print" but some post-processing happens on the output,
1572 This returns a list of strings *without any prefix*.
1573 Thus if the directory structure was:
1579 then the returned list from "g.find" "/tmp" would be 4
1587 If "directory" is not a directory, then this command
1590 The returned list is sorted.
1592 This function returns a list of strings.
1594 return libguestfsmod.find (self._o, directory)
1596 def e2fsck_f (self, device):
1597 u"""This runs "e2fsck -p -f device", ie. runs the ext2/ext3
1598 filesystem checker on "device", noninteractively ("-p"),
1599 even if the filesystem appears to be clean ("-f").
1601 This command is only needed because of "g.resize2fs"
1602 (q.v.). Normally you should use "g.fsck".
1604 return libguestfsmod.e2fsck_f (self._o, device)
1606 def sleep (self, secs):
1607 u"""Sleep for "secs" seconds.
1609 return libguestfsmod.sleep (self._o, secs)
1611 def ntfs_3g_probe (self, rw, device):
1612 u"""This command runs the ntfs-3g.probe(8) command which
1613 probes an NTFS "device" for mountability. (Not all NTFS
1614 volumes can be mounted read-write, and some cannot be
1617 "rw" is a boolean flag. Set it to true if you want to
1618 test if the volume can be mounted read-write. Set it to
1619 false if you want to test if the volume can be mounted
1622 The return value is an integer which 0 if the operation
1623 would succeed, or some non-zero value documented in the
1624 ntfs-3g.probe(8) manual page.
1626 return libguestfsmod.ntfs_3g_probe (self._o, rw, device)
1628 def sh (self, command):
1629 u"""This call runs a command from the guest filesystem via
1630 the guest's "/bin/sh".
1632 This is like "g.command", but passes the command to:
1634 /bin/sh -c "command"
1636 Depending on the guest's shell, this usually results in
1637 wildcards being expanded, shell expressions being
1638 interpolated and so on.
1640 All the provisos about "g.command" apply to this call.
1642 return libguestfsmod.sh (self._o, command)
1644 def sh_lines (self, command):
1645 u"""This is the same as "g.sh", but splits the result into a
1648 See also: "g.command_lines"
1650 This function returns a list of strings.
1652 return libguestfsmod.sh_lines (self._o, command)