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).
952 The return value is anything printed to *stdout* by the
955 If the command returns a non-zero exit status, then this
956 function returns an error message. The error message
957 string is the content of *stderr* from the command.
959 The $PATH environment variable will contain at least
960 "/usr/bin" and "/bin". If you require a program from
961 another location, you should provide the full path in
964 Shared libraries and data files required by the program
965 must be available on filesystems which are mounted in
966 the correct places. It is the caller's responsibility to
967 ensure all filesystems that are needed are mounted at
970 Because of the message protocol, there is a transfer
971 limit of somewhere between 2MB and 4MB. To transfer
972 large files you should use FTP.
974 return libguestfsmod.command (self._o, arguments)
976 def command_lines (self, arguments):
977 u"""This is the same as "g.command", but splits the result
978 into a list of lines.
980 This function returns a list of strings.
982 Because of the message protocol, there is a transfer
983 limit of somewhere between 2MB and 4MB. To transfer
984 large files you should use FTP.
986 return libguestfsmod.command_lines (self._o, arguments)
988 def stat (self, path):
989 u"""Returns file information for the given "path".
991 This is the same as the stat(2) system call.
993 This function returns a dictionary, with keys matching
994 the various fields in the stat structure.
996 return libguestfsmod.stat (self._o, path)
998 def lstat (self, path):
999 u"""Returns file information for the given "path".
1001 This is the same as "g.stat" except that if "path" is a
1002 symbolic link, then the link is stat-ed, not the file it
1005 This is the same as the lstat(2) system call.
1007 This function returns a dictionary, with keys matching
1008 the various fields in the stat structure.
1010 return libguestfsmod.lstat (self._o, path)
1012 def statvfs (self, path):
1013 u"""Returns file system statistics for any mounted file
1014 system. "path" should be a file or directory in the
1015 mounted file system (typically it is the mount point
1016 itself, but it doesn't need to be).
1018 This is the same as the statvfs(2) system call.
1020 This function returns a dictionary, with keys matching
1021 the various fields in the statvfs structure.
1023 return libguestfsmod.statvfs (self._o, path)
1025 def tune2fs_l (self, device):
1026 u"""This returns the contents of the ext2, ext3 or ext4
1027 filesystem superblock on "device".
1029 It is the same as running "tune2fs -l device". See
1030 tune2fs(8) manpage for more details. The list of fields
1031 returned isn't clearly defined, and depends on both the
1032 version of "tune2fs" that libguestfs was built against,
1033 and the filesystem itself.
1035 This function returns a dictionary.
1037 return libguestfsmod.tune2fs_l (self._o, device)
1039 def blockdev_setro (self, device):
1040 u"""Sets the block device named "device" to read-only.
1042 This uses the blockdev(8) command.
1044 return libguestfsmod.blockdev_setro (self._o, device)
1046 def blockdev_setrw (self, device):
1047 u"""Sets the block device named "device" to read-write.
1049 This uses the blockdev(8) command.
1051 return libguestfsmod.blockdev_setrw (self._o, device)
1053 def blockdev_getro (self, device):
1054 u"""Returns a boolean indicating if the block device is
1055 read-only (true if read-only, false if not).
1057 This uses the blockdev(8) command.
1059 return libguestfsmod.blockdev_getro (self._o, device)
1061 def blockdev_getss (self, device):
1062 u"""This returns the size of sectors on a block device.
1063 Usually 512, but can be larger for modern devices.
1065 (Note, this is not the size in sectors, use
1066 "g.blockdev_getsz" for that).
1068 This uses the blockdev(8) command.
1070 return libguestfsmod.blockdev_getss (self._o, device)
1072 def blockdev_getbsz (self, device):
1073 u"""This returns the block size of a device.
1075 (Note this is different from both *size in blocks* and
1076 *filesystem block size*).
1078 This uses the blockdev(8) command.
1080 return libguestfsmod.blockdev_getbsz (self._o, device)
1082 def blockdev_setbsz (self, device, blocksize):
1083 u"""This sets the block size of a device.
1085 (Note this is different from both *size in blocks* and
1086 *filesystem block size*).
1088 This uses the blockdev(8) command.
1090 return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
1092 def blockdev_getsz (self, device):
1093 u"""This returns the size of the device in units of 512-byte
1094 sectors (even if the sectorsize isn't 512 bytes ...
1097 See also "g.blockdev_getss" for the real sector size of
1098 the device, and "g.blockdev_getsize64" for the more
1099 useful *size in bytes*.
1101 This uses the blockdev(8) command.
1103 return libguestfsmod.blockdev_getsz (self._o, device)
1105 def blockdev_getsize64 (self, device):
1106 u"""This returns the size of the device in bytes.
1108 See also "g.blockdev_getsz".
1110 This uses the blockdev(8) command.
1112 return libguestfsmod.blockdev_getsize64 (self._o, device)
1114 def blockdev_flushbufs (self, device):
1115 u"""This tells the kernel to flush internal buffers
1116 associated with "device".
1118 This uses the blockdev(8) command.
1120 return libguestfsmod.blockdev_flushbufs (self._o, device)
1122 def blockdev_rereadpt (self, device):
1123 u"""Reread the partition table on "device".
1125 This uses the blockdev(8) command.
1127 return libguestfsmod.blockdev_rereadpt (self._o, device)
1129 def upload (self, filename, remotefilename):
1130 u"""Upload local file "filename" to "remotefilename" on the
1133 "filename" can also be a named pipe.
1135 See also "g.download".
1137 return libguestfsmod.upload (self._o, filename, remotefilename)
1139 def download (self, remotefilename, filename):
1140 u"""Download file "remotefilename" and save it as "filename"
1141 on the local machine.
1143 "filename" can also be a named pipe.
1145 See also "g.upload", "g.cat".
1147 return libguestfsmod.download (self._o, remotefilename, filename)
1149 def checksum (self, csumtype, path):
1150 u"""This call computes the MD5, SHAx or CRC checksum of the
1153 The type of checksum to compute is given by the
1154 "csumtype" parameter which must have one of the
1158 Compute the cyclic redundancy check (CRC) specified
1159 by POSIX for the "cksum" command.
1162 Compute the MD5 hash (using the "md5sum" program).
1165 Compute the SHA1 hash (using the "sha1sum" program).
1168 Compute the SHA224 hash (using the "sha224sum"
1172 Compute the SHA256 hash (using the "sha256sum"
1176 Compute the SHA384 hash (using the "sha384sum"
1180 Compute the SHA512 hash (using the "sha512sum"
1183 The checksum is returned as a printable string.
1185 return libguestfsmod.checksum (self._o, csumtype, path)
1187 def tar_in (self, tarfile, directory):
1188 u"""This command uploads and unpacks local file "tarfile"
1189 (an *uncompressed* tar file) into "directory".
1191 To upload a compressed tarball, use "g.tgz_in".
1193 return libguestfsmod.tar_in (self._o, tarfile, directory)
1195 def tar_out (self, directory, tarfile):
1196 u"""This command packs the contents of "directory" and
1197 downloads it to local file "tarfile".
1199 To download a compressed tarball, use "g.tgz_out".
1201 return libguestfsmod.tar_out (self._o, directory, tarfile)
1203 def tgz_in (self, tarball, directory):
1204 u"""This command uploads and unpacks local file "tarball" (a
1205 *gzip compressed* tar file) into "directory".
1207 To upload an uncompressed tarball, use "g.tar_in".
1209 return libguestfsmod.tgz_in (self._o, tarball, directory)
1211 def tgz_out (self, directory, tarball):
1212 u"""This command packs the contents of "directory" and
1213 downloads it to local file "tarball".
1215 To download an uncompressed tarball, use "g.tar_out".
1217 return libguestfsmod.tgz_out (self._o, directory, tarball)
1219 def mount_ro (self, device, mountpoint):
1220 u"""This is the same as the "g.mount" command, but it mounts
1221 the filesystem with the read-only (*-o ro*) flag.
1223 return libguestfsmod.mount_ro (self._o, device, mountpoint)
1225 def mount_options (self, options, device, mountpoint):
1226 u"""This is the same as the "g.mount" command, but it allows
1227 you to set the mount options as for the mount(8) *-o*
1230 return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1232 def mount_vfs (self, options, vfstype, device, mountpoint):
1233 u"""This is the same as the "g.mount" command, but it allows
1234 you to set both the mount options and the vfstype as for
1235 the mount(8) *-o* and *-t* flags.
1237 return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1239 def debug (self, subcmd, extraargs):
1240 u"""The "g.debug" command exposes some internals of
1241 "guestfsd" (the guestfs daemon) that runs inside the
1244 There is no comprehensive help for this command. You
1245 have to look at the file "daemon/debug.c" in the
1246 libguestfs source to find out what you can do.
1248 return libguestfsmod.debug (self._o, subcmd, extraargs)
1250 def lvremove (self, device):
1251 u"""Remove an LVM logical volume "device", where "device" is
1252 the path to the LV, such as "/dev/VG/LV".
1254 You can also remove all LVs in a volume group by
1255 specifying the VG name, "/dev/VG".
1257 return libguestfsmod.lvremove (self._o, device)
1259 def vgremove (self, vgname):
1260 u"""Remove an LVM volume group "vgname", (for example "VG").
1262 This also forcibly removes all logical volumes in the
1263 volume group (if any).
1265 return libguestfsmod.vgremove (self._o, vgname)
1267 def pvremove (self, device):
1268 u"""This wipes a physical volume "device" so that LVM will
1269 no longer recognise it.
1271 The implementation uses the "pvremove" command which
1272 refuses to wipe physical volumes that contain any volume
1273 groups, so you have to remove those first.
1275 return libguestfsmod.pvremove (self._o, device)
1277 def set_e2label (self, device, label):
1278 u"""This sets the ext2/3/4 filesystem label of the
1279 filesystem on "device" to "label". Filesystem labels are
1280 limited to 16 characters.
1282 You can use either "g.tune2fs_l" or "g.get_e2label" to
1283 return the existing label on a filesystem.
1285 return libguestfsmod.set_e2label (self._o, device, label)
1287 def get_e2label (self, device):
1288 u"""This returns the ext2/3/4 filesystem label of the
1289 filesystem on "device".
1291 return libguestfsmod.get_e2label (self._o, device)
1293 def set_e2uuid (self, device, uuid):
1294 u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1295 on "device" to "uuid". The format of the UUID and
1296 alternatives such as "clear", "random" and "time" are
1297 described in the tune2fs(8) manpage.
1299 You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1300 return the existing UUID of a filesystem.
1302 return libguestfsmod.set_e2uuid (self._o, device, uuid)
1304 def get_e2uuid (self, device):
1305 u"""This returns the ext2/3/4 filesystem UUID of the
1306 filesystem on "device".
1308 return libguestfsmod.get_e2uuid (self._o, device)
1310 def fsck (self, fstype, device):
1311 u"""This runs the filesystem checker (fsck) on "device"
1312 which should have filesystem type "fstype".
1314 The returned integer is the status. See fsck(8) for the
1315 list of status codes from "fsck".
1319 * Multiple status codes can be summed together.
1321 * A non-zero return code can mean "success", for
1322 example if errors have been corrected on the
1325 * Checking or repairing NTFS volumes is not supported
1328 This command is entirely equivalent to running "fsck -a
1331 return libguestfsmod.fsck (self._o, fstype, device)
1333 def zero (self, device):
1334 u"""This command writes zeroes over the first few blocks of
1337 How many blocks are zeroed isn't specified (but it's
1338 *not* enough to securely wipe the device). It should be
1339 sufficient to remove any partition tables, filesystem
1340 superblocks and so on.
1342 return libguestfsmod.zero (self._o, device)
1344 def grub_install (self, root, device):
1345 u"""This command installs GRUB (the Grand Unified
1346 Bootloader) on "device", with the root directory being
1349 return libguestfsmod.grub_install (self._o, root, device)
1351 def cp (self, src, dest):
1352 u"""This copies a file from "src" to "dest" where "dest" is
1353 either a destination filename or destination directory.
1355 return libguestfsmod.cp (self._o, src, dest)
1357 def cp_a (self, src, dest):
1358 u"""This copies a file or directory from "src" to "dest"
1359 recursively using the "cp -a" command.
1361 return libguestfsmod.cp_a (self._o, src, dest)
1363 def mv (self, src, dest):
1364 u"""This moves a file from "src" to "dest" where "dest" is
1365 either a destination filename or destination directory.
1367 return libguestfsmod.mv (self._o, src, dest)
1369 def drop_caches (self, whattodrop):
1370 u"""This instructs the guest kernel to drop its page cache,
1371 and/or dentries and inode caches. The parameter
1372 "whattodrop" tells the kernel what precisely to drop,
1373 see <http://linux-mm.org/Drop_Caches>
1375 Setting "whattodrop" to 3 should drop everything.
1377 This automatically calls sync(2) before the operation,
1378 so that the maximum guest memory is freed.
1380 return libguestfsmod.drop_caches (self._o, whattodrop)
1383 u"""This returns the kernel messages ("dmesg" output) from
1384 the guest kernel. This is sometimes useful for extended
1385 debugging of problems.
1387 Another way to get the same information is to enable
1388 verbose messages with "g.set_verbose" or by setting the
1389 environment variable "LIBGUESTFS_DEBUG=1" before running
1392 return libguestfsmod.dmesg (self._o)
1394 def ping_daemon (self):
1395 u"""This is a test probe into the guestfs daemon running
1396 inside the qemu subprocess. Calling this function checks
1397 that the daemon responds to the ping message, without
1398 affecting the daemon or attached block device(s) in any
1401 return libguestfsmod.ping_daemon (self._o)
1403 def equal (self, file1, file2):
1404 u"""This compares the two files "file1" and "file2" and
1405 returns true if their content is exactly equal, or false
1408 The external cmp(1) program is used for the comparison.
1410 return libguestfsmod.equal (self._o, file1, file2)
1412 def strings (self, path):
1413 u"""This runs the strings(1) command on a file and returns
1414 the list of printable strings found.
1416 This function returns a list of strings.
1418 Because of the message protocol, there is a transfer
1419 limit of somewhere between 2MB and 4MB. To transfer
1420 large files you should use FTP.
1422 return libguestfsmod.strings (self._o, path)
1424 def strings_e (self, encoding, path):
1425 u"""This is like the "g.strings" command, but allows you to
1426 specify the encoding.
1428 See the strings(1) manpage for the full list of
1431 Commonly useful encodings are "l" (lower case L) which
1432 will show strings inside Windows/x86 files.
1434 The returned strings are transcoded to UTF-8.
1436 This function returns a list of strings.
1438 Because of the message protocol, there is a transfer
1439 limit of somewhere between 2MB and 4MB. To transfer
1440 large files you should use FTP.
1442 return libguestfsmod.strings_e (self._o, encoding, path)
1444 def hexdump (self, path):
1445 u"""This runs "hexdump -C" on the given "path". The result
1446 is the human-readable, canonical hex dump of the file.
1448 Because of the message protocol, there is a transfer
1449 limit of somewhere between 2MB and 4MB. To transfer
1450 large files you should use FTP.
1452 return libguestfsmod.hexdump (self._o, path)
1454 def zerofree (self, device):
1455 u"""This runs the *zerofree* program on "device". This
1456 program claims to zero unused inodes and disk blocks on
1457 an ext2/3 filesystem, thus making it possible to
1458 compress the filesystem more effectively.
1460 You should not run this program if the filesystem is
1463 It is possible that using this program can damage the
1464 filesystem or data on the filesystem.
1466 return libguestfsmod.zerofree (self._o, device)
1468 def pvresize (self, device):
1469 u"""This resizes (expands or shrinks) an existing LVM
1470 physical volume to match the new size of the underlying
1473 return libguestfsmod.pvresize (self._o, device)
1475 def sfdisk_N (self, device, n, cyls, heads, sectors, line):
1476 u"""This runs sfdisk(8) option to modify just the single
1477 partition "n" (note: "n" counts from 1).
1479 For other parameters, see "g.sfdisk". You should usually
1480 pass 0 for the cyls/heads/sectors parameters.
1482 This command is dangerous. Without careful use you can
1483 easily destroy all your data.
1485 return libguestfsmod.sfdisk_N (self._o, device, n, cyls, heads, sectors, line)
1487 def sfdisk_l (self, device):
1488 u"""This displays the partition table on "device", in the
1489 human-readable output of the sfdisk(8) command. It is
1490 not intended to be parsed.
1492 return libguestfsmod.sfdisk_l (self._o, device)
1494 def sfdisk_kernel_geometry (self, device):
1495 u"""This displays the kernel's idea of the geometry of
1498 The result is in human-readable format, and not designed
1501 return libguestfsmod.sfdisk_kernel_geometry (self._o, device)
1503 def sfdisk_disk_geometry (self, device):
1504 u"""This displays the disk geometry of "device" read from
1505 the partition table. Especially in the case where the
1506 underlying block device has been resized, this can be
1507 different from the kernel's idea of the geometry (see
1508 "g.sfdisk_kernel_geometry").
1510 The result is in human-readable format, and not designed
1513 return libguestfsmod.sfdisk_disk_geometry (self._o, device)
1515 def vg_activate_all (self, activate):
1516 u"""This command activates or (if "activate" is false)
1517 deactivates all logical volumes in all volume groups. If
1518 activated, then they are made known to the kernel, ie.
1519 they appear as "/dev/mapper" devices. If deactivated,
1520 then those devices disappear.
1522 This command is the same as running "vgchange -a y|n"
1524 return libguestfsmod.vg_activate_all (self._o, activate)
1526 def vg_activate (self, activate, volgroups):
1527 u"""This command activates or (if "activate" is false)
1528 deactivates all logical volumes in the listed volume
1529 groups "volgroups". If activated, then they are made
1530 known to the kernel, ie. they appear as "/dev/mapper"
1531 devices. If deactivated, then those devices disappear.
1533 This command is the same as running "vgchange -a y|n
1536 Note that if "volgroups" is an empty list then all
1537 volume groups are activated or deactivated.
1539 return libguestfsmod.vg_activate (self._o, activate, volgroups)
1541 def lvresize (self, device, mbytes):
1542 u"""This resizes (expands or shrinks) an existing LVM
1543 logical volume to "mbytes". When reducing, data in the
1544 reduced part is lost.
1546 return libguestfsmod.lvresize (self._o, device, mbytes)
1548 def resize2fs (self, device):
1549 u"""This resizes an ext2 or ext3 filesystem to match the
1550 size of the underlying device.
1552 *Note:* It is sometimes required that you run
1553 "g.e2fsck_f" on the "device" before calling this
1554 command. For unknown reasons "resize2fs" sometimes gives
1555 an error about this and sometimes not. In any case, it
1556 is always safe to call "g.e2fsck_f" before calling this
1559 return libguestfsmod.resize2fs (self._o, device)
1561 def find (self, directory):
1562 u"""This command lists out all files and directories,
1563 recursively, starting at "directory". It is essentially
1564 equivalent to running the shell command "find directory
1565 -print" but some post-processing happens on the output,
1568 This returns a list of strings *without any prefix*.
1569 Thus if the directory structure was:
1575 then the returned list from "g.find" "/tmp" would be 4
1583 If "directory" is not a directory, then this command
1586 The returned list is sorted.
1588 This function returns a list of strings.
1590 return libguestfsmod.find (self._o, directory)
1592 def e2fsck_f (self, device):
1593 u"""This runs "e2fsck -p -f device", ie. runs the ext2/ext3
1594 filesystem checker on "device", noninteractively ("-p"),
1595 even if the filesystem appears to be clean ("-f").
1597 This command is only needed because of "g.resize2fs"
1598 (q.v.). Normally you should use "g.fsck".
1600 return libguestfsmod.e2fsck_f (self._o, device)