# libguestfs generated file # WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'. # ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST. # # Copyright (C) 2009 Red Hat Inc. # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Lesser General Public # License as published by the Free Software Foundation; either # version 2 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public # License along with this library; if not, write to the Free Software # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA u"""Python bindings for libguestfs import guestfs g = guestfs.GuestFS () g.add_drive ("guest.img") g.launch () g.wait_ready () parts = g.list_partitions () The guestfs module provides a Python binding to the libguestfs API for examining and modifying virtual machine disk images. Amongst the things this is good for: making batch configuration changes to guests, getting disk used/free statistics (see also: virt-df), migrating between virtualization systems (see also: virt-p2v), performing partial backups, performing partial guest clones, cloning guests and changing registry/UUID/hostname info, and much else besides. Libguestfs uses Linux kernel and qemu code, and can access any type of guest filesystem that Linux and qemu can, including but not limited to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition schemes, qcow, qcow2, vmdk. Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, what filesystem is in each LV, etc.). It can also run commands in the context of the guest. Also you can access filesystems over FTP. Errors which happen while using the API are turned into Python RuntimeError exceptions. To create a guestfs handle you usually have to perform the following sequence of calls: # Create the handle, call add_drive at least once, and possibly # several times if the guest has multiple block devices: g = guestfs.GuestFS () g.add_drive ("guest.img") # Launch the qemu subprocess and wait for it to become ready: g.launch () g.wait_ready () # Now you can issue commands, for example: logvols = g.lvs () """ import libguestfsmod class GuestFS: """Instances of this class are libguestfs API handles.""" def __init__ (self): """Create a new libguestfs handle.""" self._o = libguestfsmod.create () def __del__ (self): libguestfsmod.close (self._o) def test0 (self, str, optstr, strlist, b, integer, filein, fileout): return libguestfsmod.test0 (self._o, str, optstr, strlist, b, integer, filein, fileout) def test0rint (self, val): return libguestfsmod.test0rint (self._o, val) def test0rinterr (self): return libguestfsmod.test0rinterr (self._o) def test0rint64 (self, val): return libguestfsmod.test0rint64 (self._o, val) def test0rint64err (self): return libguestfsmod.test0rint64err (self._o) def test0rbool (self, val): return libguestfsmod.test0rbool (self._o, val) def test0rboolerr (self): return libguestfsmod.test0rboolerr (self._o) def test0rconststring (self, val): return libguestfsmod.test0rconststring (self._o, val) def test0rconststringerr (self): return libguestfsmod.test0rconststringerr (self._o) def test0rstring (self, val): return libguestfsmod.test0rstring (self._o, val) def test0rstringerr (self): return libguestfsmod.test0rstringerr (self._o) def test0rstringlist (self, val): return libguestfsmod.test0rstringlist (self._o, val) def test0rstringlisterr (self): return libguestfsmod.test0rstringlisterr (self._o) def test0rintbool (self, val): return libguestfsmod.test0rintbool (self._o, val) def test0rintboolerr (self): return libguestfsmod.test0rintboolerr (self._o) def test0rpvlist (self, val): return libguestfsmod.test0rpvlist (self._o, val) def test0rpvlisterr (self): return libguestfsmod.test0rpvlisterr (self._o) def test0rvglist (self, val): return libguestfsmod.test0rvglist (self._o, val) def test0rvglisterr (self): return libguestfsmod.test0rvglisterr (self._o) def test0rlvlist (self, val): return libguestfsmod.test0rlvlist (self._o, val) def test0rlvlisterr (self): return libguestfsmod.test0rlvlisterr (self._o) def test0rstat (self, val): return libguestfsmod.test0rstat (self._o, val) def test0rstaterr (self): return libguestfsmod.test0rstaterr (self._o) def test0rstatvfs (self, val): return libguestfsmod.test0rstatvfs (self._o, val) def test0rstatvfserr (self): return libguestfsmod.test0rstatvfserr (self._o) def test0rhashtable (self, val): return libguestfsmod.test0rhashtable (self._o, val) def test0rhashtableerr (self): return libguestfsmod.test0rhashtableerr (self._o) def launch (self): u"""Internally libguestfs is implemented by running a virtual machine using qemu(1). You should call this after configuring the handle (eg. adding drives) but before performing any actions. """ return libguestfsmod.launch (self._o) def wait_ready (self): u"""Internally libguestfs is implemented by running a virtual machine using qemu(1). You should call this after "g.launch" to wait for the launch to complete. """ return libguestfsmod.wait_ready (self._o) def kill_subprocess (self): u"""This kills the qemu subprocess. You should never need to call this. """ return libguestfsmod.kill_subprocess (self._o) def add_drive (self, filename): u"""This function adds a virtual machine disk image "filename" to the guest. The first time you call this function, the disk appears as IDE disk 0 ("/dev/sda") in the guest, the second time as "/dev/sdb", and so on. You don't necessarily need to be root when using libguestfs. However you obviously do need sufficient permissions to access the filename for whatever operations you want to perform (ie. read access if you just want to read the image or write access if you want to modify the image). This is equivalent to the qemu parameter "-drive file=filename,cache=off". Note that this call checks for the existence of "filename". This stops you from specifying other types of drive which are supported by qemu such as "nbd:" and "http:" URLs. To specify those, use the general "g.config" call instead. """ return libguestfsmod.add_drive (self._o, filename) def add_cdrom (self, filename): u"""This function adds a virtual CD-ROM disk image to the guest. This is equivalent to the qemu parameter "-cdrom filename". Note that this call checks for the existence of "filename". This stops you from specifying other types of drive which are supported by qemu such as "nbd:" and "http:" URLs. To specify those, use the general "g.config" call instead. """ return libguestfsmod.add_cdrom (self._o, filename) def add_drive_ro (self, filename): u"""This adds a drive in snapshot mode, making it effectively read-only. Note that writes to the device are allowed, and will be seen for the duration of the guestfs handle, but they are written to a temporary file which is discarded as soon as the guestfs handle is closed. We don't currently have any method to enable changes to be committed, although qemu can support this. This is equivalent to the qemu parameter "-drive file=filename,snapshot=on". Note that this call checks for the existence of "filename". This stops you from specifying other types of drive which are supported by qemu such as "nbd:" and "http:" URLs. To specify those, use the general "g.config" call instead. """ return libguestfsmod.add_drive_ro (self._o, filename) def config (self, qemuparam, qemuvalue): u"""This can be used to add arbitrary qemu command line parameters of the form "-param value". Actually it's not quite arbitrary - we prevent you from setting some parameters which would interfere with parameters that we use. The first character of "param" string must be a "-" (dash). "value" can be NULL. """ return libguestfsmod.config (self._o, qemuparam, qemuvalue) def set_qemu (self, qemu): u"""Set the qemu binary that we will use. The default is chosen when the library was compiled by the configure script. You can also override this by setting the "LIBGUESTFS_QEMU" environment variable. Setting "qemu" to "NULL" restores the default qemu binary. """ return libguestfsmod.set_qemu (self._o, qemu) def get_qemu (self): u"""Return the current qemu binary. This is always non-NULL. If it wasn't set already, then this will return the default qemu binary name. """ return libguestfsmod.get_qemu (self._o) def set_path (self, path): u"""Set the path that libguestfs searches for kernel and initrd.img. The default is "$libdir/guestfs" unless overridden by setting "LIBGUESTFS_PATH" environment variable. Setting "path" to "NULL" restores the default path. """ return libguestfsmod.set_path (self._o, path) def get_path (self): u"""Return the current search path. This is always non-NULL. If it wasn't set already, then this will return the default path. """ return libguestfsmod.get_path (self._o) def set_append (self, append): u"""This function is used to add additional options to the guest kernel command line. The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND" environment variable. Setting "append" to "NULL" means *no* additional options are passed (libguestfs always adds a few of its own). """ return libguestfsmod.set_append (self._o, append) def get_append (self): u"""Return the additional kernel options which are added to the guest kernel command line. If "NULL" then no options are added. """ return libguestfsmod.get_append (self._o) def set_autosync (self, autosync): u"""If "autosync" is true, this enables autosync. Libguestfs will make a best effort attempt to run "g.umount_all" followed by "g.sync" when the handle is closed (also if the program exits without closing handles). This is disabled by default (except in guestfish where it is enabled by default). """ return libguestfsmod.set_autosync (self._o, autosync) def get_autosync (self): u"""Get the autosync flag. """ return libguestfsmod.get_autosync (self._o) def set_verbose (self, verbose): u"""If "verbose" is true, this turns on verbose messages (to "stderr"). Verbose messages are disabled unless the environment variable "LIBGUESTFS_DEBUG" is defined and set to 1. """ return libguestfsmod.set_verbose (self._o, verbose) def get_verbose (self): u"""This returns the verbose messages flag. """ return libguestfsmod.get_verbose (self._o) def is_ready (self): u"""This returns true iff this handle is ready to accept commands (in the "READY" state). For more information on states, see guestfs(3). """ return libguestfsmod.is_ready (self._o) def is_config (self): u"""This returns true iff this handle is being configured (in the "CONFIG" state). For more information on states, see guestfs(3). """ return libguestfsmod.is_config (self._o) def is_launching (self): u"""This returns true iff this handle is launching the subprocess (in the "LAUNCHING" state). For more information on states, see guestfs(3). """ return libguestfsmod.is_launching (self._o) def is_busy (self): u"""This returns true iff this handle is busy processing a command (in the "BUSY" state). For more information on states, see guestfs(3). """ return libguestfsmod.is_busy (self._o) def get_state (self): u"""This returns the current state as an opaque integer. This is only useful for printing debug and internal error messages. For more information on states, see guestfs(3). """ return libguestfsmod.get_state (self._o) def set_busy (self): u"""This sets the state to "BUSY". This is only used when implementing actions using the low-level API. For more information on states, see guestfs(3). """ return libguestfsmod.set_busy (self._o) def set_ready (self): u"""This sets the state to "READY". This is only used when implementing actions using the low-level API. For more information on states, see guestfs(3). """ return libguestfsmod.set_ready (self._o) def end_busy (self): u"""This sets the state to "READY", or if in "CONFIG" then it leaves the state as is. This is only used when implementing actions using the low-level API. For more information on states, see guestfs(3). """ return libguestfsmod.end_busy (self._o) def mount (self, device, mountpoint): u"""Mount a guest disk at a position in the filesystem. Block devices are named "/dev/sda", "/dev/sdb" and so on, as they were added to the guest. If those block devices contain partitions, they will have the usual names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style names can be used. The rules are the same as for mount(2): A filesystem must first be mounted on "/" before others can be mounted. Other filesystems can only be mounted on directories which already exist. The mounted filesystem is writable, if we have sufficient permissions on the underlying device. The filesystem options "sync" and "noatime" are set with this call, in order to improve reliability. """ return libguestfsmod.mount (self._o, device, mountpoint) def sync (self): u"""This syncs the disk, so that any writes are flushed through to the underlying disk image. You should always call this if you have modified a disk image, before closing the handle. """ return libguestfsmod.sync (self._o) def touch (self, path): u"""Touch acts like the touch(1) command. It can be used to update the timestamps on a file, or, if the file does not exist, to create a new zero-length file. """ return libguestfsmod.touch (self._o, path) def cat (self, path): u"""Return the contents of the file named "path". Note that this function cannot correctly handle binary files (specifically, files containing "\\0" character which is treated as end of string). For those you need to use the "g.download" function which has a more complex interface. Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP. """ return libguestfsmod.cat (self._o, path) def ll (self, directory): u"""List the files in "directory" (relative to the root directory, there is no cwd) in the format of 'ls -la'. This command is mostly useful for interactive sessions. It is *not* intended that you try to parse the output string. """ return libguestfsmod.ll (self._o, directory) def ls (self, directory): u"""List the files in "directory" (relative to the root directory, there is no cwd). The '.' and '..' entries are not returned, but hidden files are shown. This command is mostly useful for interactive sessions. Programs should probably use "g.readdir" instead. This function returns a list of strings. """ return libguestfsmod.ls (self._o, directory) def list_devices (self): u"""List all the block devices. The full block device names are returned, eg. "/dev/sda" This function returns a list of strings. """ return libguestfsmod.list_devices (self._o) def list_partitions (self): u"""List all the partitions detected on all block devices. The full partition device names are returned, eg. "/dev/sda1" This does not return logical volumes. For that you will need to call "g.lvs". This function returns a list of strings. """ return libguestfsmod.list_partitions (self._o) def pvs (self): u"""List all the physical volumes detected. This is the equivalent of the pvs(8) command. This returns a list of just the device names that contain PVs (eg. "/dev/sda2"). See also "g.pvs_full". This function returns a list of strings. """ return libguestfsmod.pvs (self._o) def vgs (self): u"""List all the volumes groups detected. This is the equivalent of the vgs(8) command. This returns a list of just the volume group names that were detected (eg. "VolGroup00"). See also "g.vgs_full". This function returns a list of strings. """ return libguestfsmod.vgs (self._o) def lvs (self): u"""List all the logical volumes detected. This is the equivalent of the lvs(8) command. This returns a list of the logical volume device names (eg. "/dev/VolGroup00/LogVol00"). See also "g.lvs_full". This function returns a list of strings. """ return libguestfsmod.lvs (self._o) def pvs_full (self): u"""List all the physical volumes detected. This is the equivalent of the pvs(8) command. The "full" version includes all fields. This function returns a list of PVs. Each PV is represented as a dictionary. """ return libguestfsmod.pvs_full (self._o) def vgs_full (self): u"""List all the volumes groups detected. This is the equivalent of the vgs(8) command. The "full" version includes all fields. This function returns a list of VGs. Each VG is represented as a dictionary. """ return libguestfsmod.vgs_full (self._o) def lvs_full (self): u"""List all the logical volumes detected. This is the equivalent of the lvs(8) command. The "full" version includes all fields. This function returns a list of LVs. Each LV is represented as a dictionary. """ return libguestfsmod.lvs_full (self._o) def read_lines (self, path): u"""Return the contents of the file named "path". The file contents are returned as a list of lines. Trailing "LF" and "CRLF" character sequences are *not* returned. Note that this function cannot correctly handle binary files (specifically, files containing "\\0" character which is treated as end of line). For those you need to use the "g.read_file" function which has a more complex interface. This function returns a list of strings. """ return libguestfsmod.read_lines (self._o, path) def aug_init (self, root, flags): u"""Create a new Augeas handle for editing configuration files. If there was any previous Augeas handle associated with this guestfs session, then it is closed. You must call this before using any other "g.aug_*" commands. "root" is the filesystem root. "root" must not be NULL, use "/" instead. The flags are the same as the flags defined in , the logical *or* of the following integers: "AUG_SAVE_BACKUP" = 1 Keep the original file with a ".augsave" extension. "AUG_SAVE_NEWFILE" = 2 Save changes into a file with extension ".augnew", and do not overwrite original. Overrides "AUG_SAVE_BACKUP". "AUG_TYPE_CHECK" = 4 Typecheck lenses (can be expensive). "AUG_NO_STDINC" = 8 Do not use standard load path for modules. "AUG_SAVE_NOOP" = 16 Make save a no-op, just record what would have been changed. "AUG_NO_LOAD" = 32 Do not load the tree in "g.aug_init". To close the handle, you can call "g.aug_close". To find out more about Augeas, see . """ return libguestfsmod.aug_init (self._o, root, flags) def aug_close (self): u"""Close the current Augeas handle and free up any resources used by it. After calling this, you have to call "g.aug_init" again before you can use any other Augeas functions. """ return libguestfsmod.aug_close (self._o) def aug_defvar (self, name, expr): u"""Defines an Augeas variable "name" whose value is the result of evaluating "expr". If "expr" is NULL, then "name" is undefined. On success this returns the number of nodes in "expr", or 0 if "expr" evaluates to something which is not a nodeset. """ return libguestfsmod.aug_defvar (self._o, name, expr) def aug_defnode (self, name, expr, val): u"""Defines a variable "name" whose value is the result of evaluating "expr". If "expr" evaluates to an empty nodeset, a node is created, equivalent to calling "g.aug_set" "expr", "value". "name" will be the nodeset containing that single node. On success this returns a pair containing the number of nodes in the nodeset, and a boolean flag if a node was created. This function returns a tuple (int, bool). """ return libguestfsmod.aug_defnode (self._o, name, expr, val) def aug_get (self, path): u"""Look up the value associated with "path". If "path" matches exactly one node, the "value" is returned. """ return libguestfsmod.aug_get (self._o, path) def aug_set (self, path, val): u"""Set the value associated with "path" to "value". """ return libguestfsmod.aug_set (self._o, path, val) def aug_insert (self, path, label, before): u"""Create a new sibling "label" for "path", inserting it into the tree before or after "path" (depending on the boolean flag "before"). "path" must match exactly one existing node in the tree, and "label" must be a label, ie. not contain "/", "*" or end with a bracketed index "[N]". """ return libguestfsmod.aug_insert (self._o, path, label, before) def aug_rm (self, path): u"""Remove "path" and all of its children. On success this returns the number of entries which were removed. """ return libguestfsmod.aug_rm (self._o, path) def aug_mv (self, src, dest): u"""Move the node "src" to "dest". "src" must match exactly one node. "dest" is overwritten if it exists. """ return libguestfsmod.aug_mv (self._o, src, dest) def aug_match (self, path): u"""Returns a list of paths which match the path expression "path". The returned paths are sufficiently qualified so that they match exactly one node in the current tree. This function returns a list of strings. """ return libguestfsmod.aug_match (self._o, path) def aug_save (self): u"""This writes all pending changes to disk. The flags which were passed to "g.aug_init" affect exactly how files are saved. """ return libguestfsmod.aug_save (self._o) def aug_load (self): u"""Load files into the tree. See "aug_load" in the Augeas documentation for the full gory details. """ return libguestfsmod.aug_load (self._o) def aug_ls (self, path): u"""This is just a shortcut for listing "g.aug_match" "path/*" and sorting the resulting nodes into alphabetical order. This function returns a list of strings. """ return libguestfsmod.aug_ls (self._o, path) def rm (self, path): u"""Remove the single file "path". """ return libguestfsmod.rm (self._o, path) def rmdir (self, path): u"""Remove the single directory "path". """ return libguestfsmod.rmdir (self._o, path) def rm_rf (self, path): u"""Remove the file or directory "path", recursively removing the contents if its a directory. This is like the "rm -rf" shell command. """ return libguestfsmod.rm_rf (self._o, path) def mkdir (self, path): u"""Create a directory named "path". """ return libguestfsmod.mkdir (self._o, path) def mkdir_p (self, path): u"""Create a directory named "path", creating any parent directories as necessary. This is like the "mkdir -p" shell command. """ return libguestfsmod.mkdir_p (self._o, path) def chmod (self, mode, path): u"""Change the mode (permissions) of "path" to "mode". Only numeric modes are supported. """ return libguestfsmod.chmod (self._o, mode, path) def chown (self, owner, group, path): u"""Change the file owner to "owner" and group to "group". Only numeric uid and gid are supported. If you want to use names, you will need to locate and parse the password file yourself (Augeas support makes this relatively easy). """ return libguestfsmod.chown (self._o, owner, group, path) def exists (self, path): u"""This returns "true" if and only if there is a file, directory (or anything) with the given "path" name. See also "g.is_file", "g.is_dir", "g.stat". """ return libguestfsmod.exists (self._o, path) def is_file (self, path): u"""This returns "true" if and only if there is a file with the given "path" name. Note that it returns false for other objects like directories. See also "g.stat". """ return libguestfsmod.is_file (self._o, path) def is_dir (self, path): u"""This returns "true" if and only if there is a directory with the given "path" name. Note that it returns false for other objects like files. See also "g.stat". """ return libguestfsmod.is_dir (self._o, path) def pvcreate (self, device): u"""This creates an LVM physical volume on the named "device", where "device" should usually be a partition name such as "/dev/sda1". """ return libguestfsmod.pvcreate (self._o, device) def vgcreate (self, volgroup, physvols): u"""This creates an LVM volume group called "volgroup" from the non-empty list of physical volumes "physvols". """ return libguestfsmod.vgcreate (self._o, volgroup, physvols) def lvcreate (self, logvol, volgroup, mbytes): u"""This creates an LVM volume group called "logvol" on the volume group "volgroup", with "size" megabytes. """ return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes) def mkfs (self, fstype, device): u"""This creates a filesystem on "device" (usually a partition or LVM logical volume). The filesystem type is "fstype", for example "ext3". """ return libguestfsmod.mkfs (self._o, fstype, device) def sfdisk (self, device, cyls, heads, sectors, lines): u"""This is a direct interface to the sfdisk(8) program for creating partitions on block devices. "device" should be a block device, for example "/dev/sda". "cyls", "heads" and "sectors" are the number of cylinders, heads and sectors on the device, which are passed directly to sfdisk as the *-C*, *-H* and *-S* parameters. If you pass 0 for any of these, then the corresponding parameter is omitted. Usually for 'large' disks, you can just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work out the right geometry and you will need to tell it. "lines" is a list of lines that we feed to "sfdisk". For more information refer to the sfdisk(8) manpage. To create a single partition occupying the whole disk, you would pass "lines" as a single element list, when the single element being the string "," (comma). See also: "g.sfdisk_l", "g.sfdisk_N" This command is dangerous. Without careful use you can easily destroy all your data. """ return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines) def write_file (self, path, content, size): u"""This call creates a file called "path". The contents of the file is the string "content" (which can contain any 8 bit data), with length "size". As a special case, if "size" is 0 then the length is calculated using "strlen" (so in this case the content cannot contain embedded ASCII NULs). *NB.* Owing to a bug, writing content containing ASCII NUL characters does *not* work, even if the length is specified. We hope to resolve this bug in a future version. In the meantime use "g.upload". Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP. """ return libguestfsmod.write_file (self._o, path, content, size) def umount (self, pathordevice): u"""This unmounts the given filesystem. The filesystem may be specified either by its mountpoint (path) or the device which contains the filesystem. """ return libguestfsmod.umount (self._o, pathordevice) def mounts (self): u"""This returns the list of currently mounted filesystems. It returns the list of devices (eg. "/dev/sda1", "/dev/VG/LV"). Some internal mounts are not shown. This function returns a list of strings. """ return libguestfsmod.mounts (self._o) def umount_all (self): u"""This unmounts all mounted filesystems. Some internal mounts are not unmounted by this call. """ return libguestfsmod.umount_all (self._o) def lvm_remove_all (self): u"""This command removes all LVM logical volumes, volume groups and physical volumes. This command is dangerous. Without careful use you can easily destroy all your data. """ return libguestfsmod.lvm_remove_all (self._o) def file (self, path): u"""This call uses the standard file(1) command to determine the type or contents of the file. This also works on devices, for example to find out whether a partition contains a filesystem. The exact command which runs is "file -bsL path". Note in particular that the filename is not prepended to the output (the "-b" option). """ return libguestfsmod.file (self._o, path) def command (self, arguments): u"""This call runs a command from the guest filesystem. The filesystem must be mounted, and must contain a compatible operating system (ie. something Linux, with the same or compatible processor architecture). The single parameter is an argv-style list of arguments. The first element is the name of the program to run. Subsequent elements are parameters. The list must be non-empty (ie. must contain a program name). Note that the command runs directly, and is *not* invoked via the shell (see "g.sh"). The return value is anything printed to *stdout* by the command. If the command returns a non-zero exit status, then this function returns an error message. The error message string is the content of *stderr* from the command. The $PATH environment variable will contain at least "/usr/bin" and "/bin". If you require a program from another location, you should provide the full path in the first parameter. Shared libraries and data files required by the program must be available on filesystems which are mounted in the correct places. It is the caller's responsibility to ensure all filesystems that are needed are mounted at the right locations. Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP. """ return libguestfsmod.command (self._o, arguments) def command_lines (self, arguments): u"""This is the same as "g.command", but splits the result into a list of lines. See also: "g.sh_lines" This function returns a list of strings. Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP. """ return libguestfsmod.command_lines (self._o, arguments) def stat (self, path): u"""Returns file information for the given "path". This is the same as the stat(2) system call. This function returns a dictionary, with keys matching the various fields in the stat structure. """ return libguestfsmod.stat (self._o, path) def lstat (self, path): u"""Returns file information for the given "path". This is the same as "g.stat" except that if "path" is a symbolic link, then the link is stat-ed, not the file it refers to. This is the same as the lstat(2) system call. This function returns a dictionary, with keys matching the various fields in the stat structure. """ return libguestfsmod.lstat (self._o, path) def statvfs (self, path): u"""Returns file system statistics for any mounted file system. "path" should be a file or directory in the mounted file system (typically it is the mount point itself, but it doesn't need to be). This is the same as the statvfs(2) system call. This function returns a dictionary, with keys matching the various fields in the statvfs structure. """ return libguestfsmod.statvfs (self._o, path) def tune2fs_l (self, device): u"""This returns the contents of the ext2, ext3 or ext4 filesystem superblock on "device". It is the same as running "tune2fs -l device". See tune2fs(8) manpage for more details. The list of fields returned isn't clearly defined, and depends on both the version of "tune2fs" that libguestfs was built against, and the filesystem itself. This function returns a dictionary. """ return libguestfsmod.tune2fs_l (self._o, device) def blockdev_setro (self, device): u"""Sets the block device named "device" to read-only. This uses the blockdev(8) command. """ return libguestfsmod.blockdev_setro (self._o, device) def blockdev_setrw (self, device): u"""Sets the block device named "device" to read-write. This uses the blockdev(8) command. """ return libguestfsmod.blockdev_setrw (self._o, device) def blockdev_getro (self, device): u"""Returns a boolean indicating if the block device is read-only (true if read-only, false if not). This uses the blockdev(8) command. """ return libguestfsmod.blockdev_getro (self._o, device) def blockdev_getss (self, device): u"""This returns the size of sectors on a block device. Usually 512, but can be larger for modern devices. (Note, this is not the size in sectors, use "g.blockdev_getsz" for that). This uses the blockdev(8) command. """ return libguestfsmod.blockdev_getss (self._o, device) def blockdev_getbsz (self, device): u"""This returns the block size of a device. (Note this is different from both *size in blocks* and *filesystem block size*). This uses the blockdev(8) command. """ return libguestfsmod.blockdev_getbsz (self._o, device) def blockdev_setbsz (self, device, blocksize): u"""This sets the block size of a device. (Note this is different from both *size in blocks* and *filesystem block size*). This uses the blockdev(8) command. """ return libguestfsmod.blockdev_setbsz (self._o, device, blocksize) def blockdev_getsz (self, device): u"""This returns the size of the device in units of 512-byte sectors (even if the sectorsize isn't 512 bytes ... weird). See also "g.blockdev_getss" for the real sector size of the device, and "g.blockdev_getsize64" for the more useful *size in bytes*. This uses the blockdev(8) command. """ return libguestfsmod.blockdev_getsz (self._o, device) def blockdev_getsize64 (self, device): u"""This returns the size of the device in bytes. See also "g.blockdev_getsz". This uses the blockdev(8) command. """ return libguestfsmod.blockdev_getsize64 (self._o, device) def blockdev_flushbufs (self, device): u"""This tells the kernel to flush internal buffers associated with "device". This uses the blockdev(8) command. """ return libguestfsmod.blockdev_flushbufs (self._o, device) def blockdev_rereadpt (self, device): u"""Reread the partition table on "device". This uses the blockdev(8) command. """ return libguestfsmod.blockdev_rereadpt (self._o, device) def upload (self, filename, remotefilename): u"""Upload local file "filename" to "remotefilename" on the filesystem. "filename" can also be a named pipe. See also "g.download". """ return libguestfsmod.upload (self._o, filename, remotefilename) def download (self, remotefilename, filename): u"""Download file "remotefilename" and save it as "filename" on the local machine. "filename" can also be a named pipe. See also "g.upload", "g.cat". """ return libguestfsmod.download (self._o, remotefilename, filename) def checksum (self, csumtype, path): u"""This call computes the MD5, SHAx or CRC checksum of the file named "path". The type of checksum to compute is given by the "csumtype" parameter which must have one of the following values: "crc" Compute the cyclic redundancy check (CRC) specified by POSIX for the "cksum" command. "md5" Compute the MD5 hash (using the "md5sum" program). "sha1" Compute the SHA1 hash (using the "sha1sum" program). "sha224" Compute the SHA224 hash (using the "sha224sum" program). "sha256" Compute the SHA256 hash (using the "sha256sum" program). "sha384" Compute the SHA384 hash (using the "sha384sum" program). "sha512" Compute the SHA512 hash (using the "sha512sum" program). The checksum is returned as a printable string. """ return libguestfsmod.checksum (self._o, csumtype, path) def tar_in (self, tarfile, directory): u"""This command uploads and unpacks local file "tarfile" (an *uncompressed* tar file) into "directory". To upload a compressed tarball, use "g.tgz_in". """ return libguestfsmod.tar_in (self._o, tarfile, directory) def tar_out (self, directory, tarfile): u"""This command packs the contents of "directory" and downloads it to local file "tarfile". To download a compressed tarball, use "g.tgz_out". """ return libguestfsmod.tar_out (self._o, directory, tarfile) def tgz_in (self, tarball, directory): u"""This command uploads and unpacks local file "tarball" (a *gzip compressed* tar file) into "directory". To upload an uncompressed tarball, use "g.tar_in". """ return libguestfsmod.tgz_in (self._o, tarball, directory) def tgz_out (self, directory, tarball): u"""This command packs the contents of "directory" and downloads it to local file "tarball". To download an uncompressed tarball, use "g.tar_out". """ return libguestfsmod.tgz_out (self._o, directory, tarball) def mount_ro (self, device, mountpoint): u"""This is the same as the "g.mount" command, but it mounts the filesystem with the read-only (*-o ro*) flag. """ return libguestfsmod.mount_ro (self._o, device, mountpoint) def mount_options (self, options, device, mountpoint): u"""This is the same as the "g.mount" command, but it allows you to set the mount options as for the mount(8) *-o* flag. """ return libguestfsmod.mount_options (self._o, options, device, mountpoint) def mount_vfs (self, options, vfstype, device, mountpoint): u"""This is the same as the "g.mount" command, but it allows you to set both the mount options and the vfstype as for the mount(8) *-o* and *-t* flags. """ return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint) def debug (self, subcmd, extraargs): u"""The "g.debug" command exposes some internals of "guestfsd" (the guestfs daemon) that runs inside the qemu subprocess. There is no comprehensive help for this command. You have to look at the file "daemon/debug.c" in the libguestfs source to find out what you can do. """ return libguestfsmod.debug (self._o, subcmd, extraargs) def lvremove (self, device): u"""Remove an LVM logical volume "device", where "device" is the path to the LV, such as "/dev/VG/LV". You can also remove all LVs in a volume group by specifying the VG name, "/dev/VG". """ return libguestfsmod.lvremove (self._o, device) def vgremove (self, vgname): u"""Remove an LVM volume group "vgname", (for example "VG"). This also forcibly removes all logical volumes in the volume group (if any). """ return libguestfsmod.vgremove (self._o, vgname) def pvremove (self, device): u"""This wipes a physical volume "device" so that LVM will no longer recognise it. The implementation uses the "pvremove" command which refuses to wipe physical volumes that contain any volume groups, so you have to remove those first. """ return libguestfsmod.pvremove (self._o, device) def set_e2label (self, device, label): u"""This sets the ext2/3/4 filesystem label of the filesystem on "device" to "label". Filesystem labels are limited to 16 characters. You can use either "g.tune2fs_l" or "g.get_e2label" to return the existing label on a filesystem. """ return libguestfsmod.set_e2label (self._o, device, label) def get_e2label (self, device): u"""This returns the ext2/3/4 filesystem label of the filesystem on "device". """ return libguestfsmod.get_e2label (self._o, device) def set_e2uuid (self, device, uuid): u"""This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to "uuid". The format of the UUID and alternatives such as "clear", "random" and "time" are described in the tune2fs(8) manpage. You can use either "g.tune2fs_l" or "g.get_e2uuid" to return the existing UUID of a filesystem. """ return libguestfsmod.set_e2uuid (self._o, device, uuid) def get_e2uuid (self, device): u"""This returns the ext2/3/4 filesystem UUID of the filesystem on "device". """ return libguestfsmod.get_e2uuid (self._o, device) def fsck (self, fstype, device): u"""This runs the filesystem checker (fsck) on "device" which should have filesystem type "fstype". The returned integer is the status. See fsck(8) for the list of status codes from "fsck". Notes: * Multiple status codes can be summed together. * A non-zero return code can mean "success", for example if errors have been corrected on the filesystem. * Checking or repairing NTFS volumes is not supported (by linux-ntfs). This command is entirely equivalent to running "fsck -a -t fstype device". """ return libguestfsmod.fsck (self._o, fstype, device) def zero (self, device): u"""This command writes zeroes over the first few blocks of "device". How many blocks are zeroed isn't specified (but it's *not* enough to securely wipe the device). It should be sufficient to remove any partition tables, filesystem superblocks and so on. See also: "g.scrub_device". """ return libguestfsmod.zero (self._o, device) def grub_install (self, root, device): u"""This command installs GRUB (the Grand Unified Bootloader) on "device", with the root directory being "root". """ return libguestfsmod.grub_install (self._o, root, device) def cp (self, src, dest): u"""This copies a file from "src" to "dest" where "dest" is either a destination filename or destination directory. """ return libguestfsmod.cp (self._o, src, dest) def cp_a (self, src, dest): u"""This copies a file or directory from "src" to "dest" recursively using the "cp -a" command. """ return libguestfsmod.cp_a (self._o, src, dest) def mv (self, src, dest): u"""This moves a file from "src" to "dest" where "dest" is either a destination filename or destination directory. """ return libguestfsmod.mv (self._o, src, dest) def drop_caches (self, whattodrop): u"""This instructs the guest kernel to drop its page cache, and/or dentries and inode caches. The parameter "whattodrop" tells the kernel what precisely to drop, see Setting "whattodrop" to 3 should drop everything. This automatically calls sync(2) before the operation, so that the maximum guest memory is freed. """ return libguestfsmod.drop_caches (self._o, whattodrop) def dmesg (self): u"""This returns the kernel messages ("dmesg" output) from the guest kernel. This is sometimes useful for extended debugging of problems. Another way to get the same information is to enable verbose messages with "g.set_verbose" or by setting the environment variable "LIBGUESTFS_DEBUG=1" before running the program. """ return libguestfsmod.dmesg (self._o) def ping_daemon (self): u"""This is a test probe into the guestfs daemon running inside the qemu subprocess. Calling this function checks that the daemon responds to the ping message, without affecting the daemon or attached block device(s) in any other way. """ return libguestfsmod.ping_daemon (self._o) def equal (self, file1, file2): u"""This compares the two files "file1" and "file2" and returns true if their content is exactly equal, or false otherwise. The external cmp(1) program is used for the comparison. """ return libguestfsmod.equal (self._o, file1, file2) def strings (self, path): u"""This runs the strings(1) command on a file and returns the list of printable strings found. This function returns a list of strings. Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP. """ return libguestfsmod.strings (self._o, path) def strings_e (self, encoding, path): u"""This is like the "g.strings" command, but allows you to specify the encoding. See the strings(1) manpage for the full list of encodings. Commonly useful encodings are "l" (lower case L) which will show strings inside Windows/x86 files. The returned strings are transcoded to UTF-8. This function returns a list of strings. Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP. """ return libguestfsmod.strings_e (self._o, encoding, path) def hexdump (self, path): u"""This runs "hexdump -C" on the given "path". The result is the human-readable, canonical hex dump of the file. Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP. """ return libguestfsmod.hexdump (self._o, path) def zerofree (self, device): u"""This runs the *zerofree* program on "device". This program claims to zero unused inodes and disk blocks on an ext2/3 filesystem, thus making it possible to compress the filesystem more effectively. You should not run this program if the filesystem is mounted. It is possible that using this program can damage the filesystem or data on the filesystem. """ return libguestfsmod.zerofree (self._o, device) def pvresize (self, device): u"""This resizes (expands or shrinks) an existing LVM physical volume to match the new size of the underlying device. """ return libguestfsmod.pvresize (self._o, device) def sfdisk_N (self, device, n, cyls, heads, sectors, line): u"""This runs sfdisk(8) option to modify just the single partition "n" (note: "n" counts from 1). For other parameters, see "g.sfdisk". You should usually pass 0 for the cyls/heads/sectors parameters. This command is dangerous. Without careful use you can easily destroy all your data. """ return libguestfsmod.sfdisk_N (self._o, device, n, cyls, heads, sectors, line) def sfdisk_l (self, device): u"""This displays the partition table on "device", in the human-readable output of the sfdisk(8) command. It is not intended to be parsed. """ return libguestfsmod.sfdisk_l (self._o, device) def sfdisk_kernel_geometry (self, device): u"""This displays the kernel's idea of the geometry of "device". The result is in human-readable format, and not designed to be parsed. """ return libguestfsmod.sfdisk_kernel_geometry (self._o, device) def sfdisk_disk_geometry (self, device): u"""This displays the disk geometry of "device" read from the partition table. Especially in the case where the underlying block device has been resized, this can be different from the kernel's idea of the geometry (see "g.sfdisk_kernel_geometry"). The result is in human-readable format, and not designed to be parsed. """ return libguestfsmod.sfdisk_disk_geometry (self._o, device) def vg_activate_all (self, activate): u"""This command activates or (if "activate" is false) deactivates all logical volumes in all volume groups. If activated, then they are made known to the kernel, ie. they appear as "/dev/mapper" devices. If deactivated, then those devices disappear. This command is the same as running "vgchange -a y|n" """ return libguestfsmod.vg_activate_all (self._o, activate) def vg_activate (self, activate, volgroups): u"""This command activates or (if "activate" is false) deactivates all logical volumes in the listed volume groups "volgroups". If activated, then they are made known to the kernel, ie. they appear as "/dev/mapper" devices. If deactivated, then those devices disappear. This command is the same as running "vgchange -a y|n volgroups..." Note that if "volgroups" is an empty list then all volume groups are activated or deactivated. """ return libguestfsmod.vg_activate (self._o, activate, volgroups) def lvresize (self, device, mbytes): u"""This resizes (expands or shrinks) an existing LVM logical volume to "mbytes". When reducing, data in the reduced part is lost. """ return libguestfsmod.lvresize (self._o, device, mbytes) def resize2fs (self, device): u"""This resizes an ext2 or ext3 filesystem to match the size of the underlying device. *Note:* It is sometimes required that you run "g.e2fsck_f" on the "device" before calling this command. For unknown reasons "resize2fs" sometimes gives an error about this and sometimes not. In any case, it is always safe to call "g.e2fsck_f" before calling this function. """ return libguestfsmod.resize2fs (self._o, device) def find (self, directory): u"""This command lists out all files and directories, recursively, starting at "directory". It is essentially equivalent to running the shell command "find directory -print" but some post-processing happens on the output, described below. This returns a list of strings *without any prefix*. Thus if the directory structure was: /tmp/a /tmp/b /tmp/c/d then the returned list from "g.find" "/tmp" would be 4 elements: a b c c/d If "directory" is not a directory, then this command returns an error. The returned list is sorted. This function returns a list of strings. """ return libguestfsmod.find (self._o, directory) def e2fsck_f (self, device): u"""This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem checker on "device", noninteractively ("-p"), even if the filesystem appears to be clean ("-f"). This command is only needed because of "g.resize2fs" (q.v.). Normally you should use "g.fsck". """ return libguestfsmod.e2fsck_f (self._o, device) def sleep (self, secs): u"""Sleep for "secs" seconds. """ return libguestfsmod.sleep (self._o, secs) def ntfs_3g_probe (self, rw, device): u"""This command runs the ntfs-3g.probe(8) command which probes an NTFS "device" for mountability. (Not all NTFS volumes can be mounted read-write, and some cannot be mounted at all). "rw" is a boolean flag. Set it to true if you want to test if the volume can be mounted read-write. Set it to false if you want to test if the volume can be mounted read-only. The return value is an integer which 0 if the operation would succeed, or some non-zero value documented in the ntfs-3g.probe(8) manual page. """ return libguestfsmod.ntfs_3g_probe (self._o, rw, device) def sh (self, command): u"""This call runs a command from the guest filesystem via the guest's "/bin/sh". This is like "g.command", but passes the command to: /bin/sh -c "command" Depending on the guest's shell, this usually results in wildcards being expanded, shell expressions being interpolated and so on. All the provisos about "g.command" apply to this call. """ return libguestfsmod.sh (self._o, command) def sh_lines (self, command): u"""This is the same as "g.sh", but splits the result into a list of lines. See also: "g.command_lines" This function returns a list of strings. """ return libguestfsmod.sh_lines (self._o, command) def glob_expand (self, pattern): u"""This command searches for all the pathnames matching "pattern" according to the wildcard expansion rules used by the shell. If no paths match, then this returns an empty list (note: not an error). It is just a wrapper around the C glob(3) function with flags "GLOB_MARK|GLOB_BRACE". See that manual page for more details. This function returns a list of strings. """ return libguestfsmod.glob_expand (self._o, pattern) def scrub_device (self, device): u"""This command writes patterns over "device" to make data retrieval more difficult. It is an interface to the scrub(1) program. See that manual page for more details. This command is dangerous. Without careful use you can easily destroy all your data. """ return libguestfsmod.scrub_device (self._o, device) def scrub_file (self, file): u"""This command writes patterns over a file to make data retrieval more difficult. The file is *removed* after scrubbing. It is an interface to the scrub(1) program. See that manual page for more details. """ return libguestfsmod.scrub_file (self._o, file) def scrub_freespace (self, dir): u"""This command creates the directory "dir" and then fills it with files until the filesystem is full, and scrubs the files as for "g.scrub_file", and deletes them. The intention is to scrub any free space on the partition containing "dir". It is an interface to the scrub(1) program. See that manual page for more details. """ return libguestfsmod.scrub_freespace (self._o, dir)