Guestfs.Session ¶

Returns:

the returned string, or None on error

Return type:

str

get the POSIX ACL attached to a file

This function returns the POSIX Access Control List (ACL) attached to path. The ACL is returned in “long text form” (see acl(5)).

The acltype parameter may be:

access Return the ordinary (access) ACL for any file, directory or other filesystem object.

default Return the default ACL. Normally this only makes sense if path is a directory.

This function depends on the feature “acl”. See also Guestfs.Session.feature_available().

New in version 1.19.63.

acl_set_file(path, acltype, acl)¶

Parameters:

path (str) –
acltype (str) –
acl (str) –

Raises:

Returns:

true on success, false on error

Return type:

set the POSIX ACL attached to a file

This function sets the POSIX Access Control List (ACL) attached to path.

The acltype parameter may be:

access Set the ordinary (access) ACL for any file, directory or other filesystem object.

default Set the default ACL. Normally this only makes sense if path is a directory.

The acl parameter is the new ACL in either “long text form” or “short text form” (see acl(5)). The new ACL completely replaces any previous ACL on the file. The ACL must contain the full Unix permissions (eg. “u::rwx,g::rx,o::rx”).

If you are specifying individual users or groups, then the mask field is also required (eg. “m::rwx”), followed by the “u:*ID*:…” and/or “g:*ID*:…” field(s). A full ACL string might therefore look like this:

<![CDATA[u::rwx,g::rwx,o::rwx,m::rwx,u:500:py:data::rwx<Guestfs.Session.props.rwx>,g:500:py:data::rwx<Guestfs.Session.props.rwx>]]>

\ Unix permissions / \mask/ \ ACL /

You should use numeric UIDs and GIDs. To map usernames and groupnames to the correct numeric ID in the context of the guest, use the Augeas functions (see Guestfs.Session.aug_init()).

This function depends on the feature “acl”. See also Guestfs.Session.feature_available().

New in version 1.19.63.

add_cdrom(filename)¶

Parameters:: filename (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

add a CD-ROM disk image to examine

This function adds a virtual CD-ROM disk image to the guest.

The image is added as read-only drive, so this function is equivalent of Guestfs.Session.add_drive_ro().

New in version 0.3.

Deprecated since version ???: In new code, use Guestfs.Session.add_drive_ro() instead

add_domain(dom, optargs)¶

Parameters:

dom (str) –
optargs (Guestfs.AddDomain or None) – a Guestfs.AddDomain containing optional arguments

Raises:

Returns:

the returned value, or -1 on error

Return type:

add the disk(s) from a named libvirt domain

This function adds the disk(s) attached to the named libvirt domain dom. It works by connecting to libvirt, requesting the domain and domain XML from libvirt, parsing it for disks, and calling guestfs_session_add_drive_opts() on each one.

The number of disks added is returned. This operation is atomic: if an error is returned, then no disks are added.

This function does some minimal checks to make sure the libvirt domain is not running (unless readonly is true). In a future version we will try to acquire the libvirt lock on each disk.

Disks must be accessible locally. This often means that adding disks from a remote libvirt connection (see <ulink url=’https://libvirt.org/remote.html’> http://libvirt.org/remote.html </ulink>) will fail unless those disks are accessible via the same device path locally too.

The optional libvirturi parameter sets the libvirt URI (see <ulink url=’https://libvirt.org/uri.html’> http://libvirt.org/uri.html </ulink>). If this is not set then we connect to the default libvirt URI (or one set through an environment variable, see the libvirt documentation for full details).

The optional live flag is ignored in libguestfs ≥ 1.48.

If the allowuuid flag is true (default is false) then a UUID *may* be passed instead of the domain name. The dom string is treated as a UUID first and looked up, and if that lookup fails then we treat dom as a name as usual.

The optional readonlydisk parameter controls what we do for disks which are marked <readonly/> in the libvirt XML. Possible values are:

readonlydisk = “error” If readonly is false:

The whole call is aborted with an error if any disk with the <readonly/> flag is found.

If readonly is true:

Disks with the <readonly/> flag are added read-only.

readonlydisk = “read” If readonly is false:

Disks with the <readonly/> flag are added read-only. Other disks are added read/write.

If readonly is true:

Disks with the <readonly/> flag are added read-only.

readonlydisk = “write” (default) If readonly is false:

Disks with the <readonly/> flag are added read/write.

If readonly is true:

Disks with the <readonly/> flag are added read-only.

readonlydisk = “ignore” If readonly is true or false:

Disks with the <readonly/> flag are skipped.

If present, the value of logical_block_size attribute of <blockio/> tag in libvirt XML will be passed as blocksize parameter to guestfs_session_add_drive_opts().

The other optional parameters are passed directly through to guestfs_session_add_drive_opts().

New in version 1.7.4.

add_drive(filename, optargs)¶

Parameters:

filename (str) –
optargs (Guestfs.AddDrive or None) – a Guestfs.AddDrive containing optional arguments

Raises:

Returns:

true on success, false on error

Return type:

add an image to examine or modify

This function adds a disk image called filename to the handle. filename may be a regular host file or a host device.

When this function is called before Guestfs.Session.launch() (the usual case) then the first time you call this function, the disk appears in the API as /dev/sda, 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 call checks that filename exists.

filename may be the special string “/dev/null”. See “None DISKS” in guestfs(3).

The optional arguments are:

readonly If true then the image is treated as read-only. Writes are still allowed, but they are stored in a temporary snapshot overlay which is discarded at the end. The disk that you add is not modified.

format This forces the image format. If you omit this (or use Guestfs.Session.add_drive() or Guestfs.Session.add_drive_ro()) then the format is automatically detected. Possible formats include raw and qcow2.

Automatic detection of the format opens you up to a potential security hole when dealing with untrusted raw-format images. See CVE-2010-3851 and <ulink url=’https://bugzilla.redhat.com/show_bug.cgi?id=642934’> RHBZ&num;642934 </ulink>. Specifying the format closes this security hole.

iface This rarely-used option lets you emulate the behaviour of the deprecated Guestfs.Session.add_drive_with_if() call (q.v.)

name This field used to be passed as a hint for guest inspection, but it is no longer used.

label Give the disk a label. The label should be a unique, short string using *only* ASCII characters “[a-zA-Z]”. As well as its usual name in the API (such as /dev/sda), the drive will also be named /dev/disk/guestfs/*label*.

See “DISK LABELS” in guestfs(3).

protocol The optional protocol argument can be used to select an alternate source protocol.

See also: “REMOTE STORAGE” in guestfs(3).

“protocol = “file”” filename is interpreted as a local file or device. This is the default if the optional protocol parameter is omitted.

“protocol = “ftp”|”ftps”|”http”|”https”|”tftp”” Connect to a remote FTP, HTTP or TFTP server. The server parameter must also be supplied - see below.

See also: “FTP, HTTP AND TFTP” in guestfs(3)

“protocol = “gluster”” Connect to the GlusterFS server. The server parameter must also be supplied - see below.

See also Guestfs.Session.syslinux().

This function depends on the feature “extlinux”. See also Guestfs.Session.feature_available().

New in version 1.21.27.

f2fs_expand(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

expand a f2fs filesystem

This expands a f2fs filesystem to match the size of the underlying device.

This function depends on the feature “f2fs”. See also Guestfs.Session.feature_available().

New in version 1.39.3.

fallocate(path, len)¶

Parameters:

path (str) –
len (int) –

Raises:

Returns:

true on success, false on error

Return type:

preallocate a file in the guest filesystem

This command preallocates a file (containing zero bytes) named path of size len bytes. If the file exists already, it is overwritten.

Do not confuse this with the guestfish-specific alloc command which allocates a file in the host and attaches it as a device.

New in version 1.0.66.

Deprecated since version ???: In new code, use Guestfs.Session.fallocate64() instead

fallocate64(path, len)¶

Parameters:

path (str) –
len (int) –

Raises:

Returns:

true on success, false on error

Return type:

preallocate a file in the guest filesystem

This command preallocates a file (containing zero bytes) named path of size len bytes. If the file exists already, it is overwritten.

Note that this call allocates disk blocks for the file. To create a sparse file use Guestfs.Session.truncate_size() instead.

The deprecated call Guestfs.Session.fallocate() does the same, but owing to an oversight it only allowed 30 bit lengths to be specified, effectively limiting the maximum size of files created through that call to 1GB.

Do not confuse this with the guestfish-specific alloc and sparse commands which create a file in the host and attach it as a device.

New in version 1.3.17.

feature_available(groups)¶

Parameters:: groups ([str]) – an array of strings
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

test availability of some parts of the API

This is the same as Guestfs.Session.available(), but unlike that call it returns a simple true/false boolean result, instead of throwing an exception if a feature is not found. For other documentation see Guestfs.Session.available().

New in version 1.21.26.

fgrep(pattern, path)¶

Parameters:

pattern (str) –
path (str) –

Raises:

Returns:

an array of returned strings, or None on error

Return type:

return lines matching a pattern

This calls the external fgrep(1) program and returns the matching lines.

New in version 1.0.66.

Deprecated since version ???: In new code, use Guestfs.Session.grep() instead

fgrepi(pattern, path)¶

Parameters:

pattern (str) –
path (str) –

Raises:

Returns:

an array of returned strings, or None on error

Return type:

return lines matching a pattern

This calls the external “fgrep -i” program and returns the matching lines.

New in version 1.0.66.

Deprecated since version ???: In new code, use Guestfs.Session.grep() instead

file(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

determine file type

This call uses the standard file(1) command to determine the type or contents of the file.

This call will also transparently look inside various types of compressed file.

The filename is not prepended to the output (like the file command *-b* option).

The output depends on the output of the underlying file(1) command and it can change in future in ways beyond our control. In other words, the output is not guaranteed by the ABI.

New in version 1.9.1.

file_architecture(filename)¶

Parameters:: filename (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

detect the architecture of a binary file

This detects the architecture of the binary filename, and returns it if known.

Currently defined architectures are:

“aarch64” 64 bit ARM.

“arm” 32 bit ARM.

“i386” This string is returned for all 32 bit i386, i486, i586, i686 binaries irrespective of the precise processor requirements of the binary.

“ia64” Intel Itanium.

“ppc” 32 bit Power PC.

“ppc64” 64 bit Power PC (big endian).

“ppc64le” 64 bit Power PC (little endian).

“riscv32” “riscv64” “riscv128” RISC-V 32-, 64- or 128-bit variants.

“s390” 31 bit IBM S/390.

“s390x” 64 bit IBM S/390.

“sparc” 32 bit SPARC.

“sparc64” 64 bit SPARC V9 and above.

“x86_64” 64 bit x86-64.

Libguestfs may return other architecture strings in future.

The function works on at least the following types of files:

many types of Un*x and Linux binary
many types of Un*x and Linux shared library
Windows Win32 and Win64 binaries
Windows Win32 and Win64 DLLs

Win32 binaries and DLLs return i386.

Win64 binaries and DLLs return x86_64.

Linux kernel modules
Linux new-style initrd images
some non-x86 Linux vmlinuz kernels

What it can’t do currently:

static libraries (libfoo.a)
Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
x86 Linux vmlinuz kernels

x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and compressed code, and are horribly hard to unpack. If you want to find the architecture of a kernel, use the architecture of the associated initrd or kernel module(s) instead.

New in version 1.5.3.

filesize(file)¶

Parameters:: file (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

return the size of the file in bytes

This command returns the size of file in bytes.

To get other stats about a file, use Guestfs.Session.stat(), Guestfs.Session.lstat(), Guestfs.Session.is_dir(), Guestfs.Session.is_file() etc. To get the size of block devices, use Guestfs.Session.blockdev_getsize64().

New in version 1.0.82.

filesystem_available(filesystem)¶

Parameters:: filesystem (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

check if filesystem is available

Check whether libguestfs supports the named filesystem. The argument filesystem is a filesystem name, such as ext3.

You must call Guestfs.Session.launch() before using this command.

This is mainly useful as a negative test. If this returns true, it doesn’t mean that a particular filesystem can be created or mounted, since filesystems can fail for other reasons such as it being a later version of the filesystem, or having incompatible features, or lacking the right mkfs.<*fs*> tool.

See also Guestfs.Session.available(), Guestfs.Session.feature_available(), “AVAILABILITY” in guestfs(3).

New in version 1.19.5.

filesystem_walk(device, cancellable)¶

Parameters:

device (str) –
cancellable (Gio.Cancellable or None) – A Gio.Cancellable object

Raises:

Returns:

an array of TSKDirent objects, or None on error

Return type:

[Guestfs.TSKDirent]

walk through the filesystem content

Walk through the internal structures of a disk partition (eg. /dev/sda1) in order to return a list of all the files and directories stored within.

It is not necessary to mount the disk partition to run this command.

All entries in the filesystem are returned. This function can list deleted or unaccessible files. The entries are *not* sorted.

The tsk_dirent structure contains the following fields.

tsk_inode Filesystem reference number of the node. It might be 0 if the node has been deleted.

tsk_type Basic file type information. See below for a detailed list of values.

tsk_size File size in bytes. It might be @-1 if the node has been deleted.

tsk_name The file path relative to its directory.

tsk_flags Bitfield containing extra information regarding the entry. It contains the logical OR of the following values:

0x0001 If set to 1, the file is allocated and visible within the filesystem. Otherwise, the file has been deleted. Under certain circumstances, the function download_inode can be used to recover deleted files.

0x0002 Filesystem such as NTFS and Ext2 or greater, separate the file name from the metadata structure. The bit is set to 1 when the file name is in an unallocated state and the metadata structure is in an allocated one. This generally implies the metadata has been reallocated to a new file. Therefore, information such as file type, file size, timestamps, number of links and symlink target might not correspond with the ones of the original deleted entry.

0x0004 The bit is set to 1 when the file is compressed using filesystem native compression support (NTFS). The API is not able to detect application level compression.

tsk_atime_sec tsk_atime_nsec tsk_mtime_sec tsk_mtime_nsec tsk_ctime_sec tsk_ctime_nsec tsk_crtime_sec tsk_crtime_nsec Respectively, access, modification, last status change and creation time in Unix format in seconds and nanoseconds.

tsk_nlink Number of file names pointing to this entry.

tsk_link If the entry is a symbolic link, this field will contain the path to the target file.

The tsk_type field will contain one of the following characters:

‘b’ Block special

‘c’ Char special

‘d’ Directory

‘f’ FIFO (named pipe)

‘l’ Symbolic link

‘r’ Regular file

‘s’ Socket

‘h’ Shadow inode (Solaris)

‘w’ Whiteout inode (BSD)

‘u’ Unknown file type

This function depends on the feature “libtsk”. See also Guestfs.Session.feature_available().

New in version 1.33.39.

fill(c, len, path)¶

Parameters:

c (int) –
len (int) –
path (str) –

Raises:

Returns:

true on success, false on error

Return type:

fill a file with octets

This command creates a new file called path. The initial content of the file is len octets of c, where c must be a number in the range “[0..255]”.

To fill a file with zero bytes (sparsely), it is much more efficient to use Guestfs.Session.truncate_size(). To create a file with a pattern of repeating bytes use Guestfs.Session.fill_pattern().

New in version 1.0.79.

fill_dir(dir, nr)¶

Parameters:

dir (str) –
nr (int) –

Raises:

Returns:

true on success, false on error

Return type:

fill a directory with empty files

This function, useful for testing filesystems, creates nr empty files in the directory dir with names 00000000 through nr-1 (ie. each file name is 8 digits long padded with zeroes).

New in version 1.19.32.

fill_pattern(pattern, len, path)¶

Parameters:

pattern (str) –
len (int) –
path (str) –

Raises:

Returns:

true on success, false on error

Return type:

fill a file with a repeating pattern of bytes

This function is like Guestfs.Session.fill() except that it creates a new file of length len containing the repeating pattern of bytes in pattern. The pattern is truncated if necessary to ensure the length of the file is exactly len bytes.

New in version 1.3.12.

find(directory)¶

Parameters:: directory (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

find all files and directories

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:

<![CDATA[/tmp/a]]>

<![CDATA[/tmp/b]]>

<![CDATA[/tmp/c/d]]>

then the returned list from Guestfs.Session.find() /tmp would be 4 elements:

<![CDATA[a]]>

<![CDATA[b]]>

<![CDATA[c]]>

<![CDATA[c/d]]>

If directory is not a directory, then this command returns an error.

The returned list is sorted.

New in version 1.0.27.

find0(directory, files, cancellable)¶

Parameters:

directory (str) –
files (str) –
cancellable (Gio.Cancellable or None) – A Gio.Cancellable object

Raises:

Returns:

true on success, false on error

Return type:

find all files and directories, returning NUL-separated list

This command lists out all files and directories, recursively, starting at directory, placing the resulting list in the external file called files.

This command works the same way as Guestfs.Session.find() with the following exceptions:

The resulting list is written to an external file.
Items (filenames) in the result are separated by “\0” characters. See find(1) option *-print0*.
The result list is not sorted.

New in version 1.0.74.

find_inode(device, inode, cancellable)¶

Parameters:

device (str) –
inode (int) –
cancellable (Gio.Cancellable or None) – A Gio.Cancellable object

Raises:

Returns:

an array of TSKDirent objects, or None on error

Return type:

[Guestfs.TSKDirent]

search the entries associated to the given inode

Searches all the entries associated with the given inode.

For each entry, a tsk_dirent structure is returned. See filesystem_walk for more information about tsk_dirent structures.

This function depends on the feature “libtsk”. See also Guestfs.Session.feature_available().

New in version 1.35.6.

findfs_label(label)¶

Parameters:: label (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

find a filesystem by label

This command searches the filesystems and returns the one which has the given label. An error is returned if no such filesystem can be found.

To find the label of a filesystem, use Guestfs.Session.vfs_label().

New in version 1.5.3.

findfs_uuid(uuid)¶

Parameters:: uuid (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

find a filesystem by UUID

This command searches the filesystems and returns the one which has the given UUID. An error is returned if no such filesystem can be found.

To find the UUID of a filesystem, use Guestfs.Session.vfs_uuid().

New in version 1.5.3.

fsck(fstype, device)¶

Parameters:

fstype (str) –
device (str) –

Raises:

Returns:

the returned value, or -1 on error

Return type:

run the filesystem checker

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”.

New in version 1.0.16.

fstrim(mountpoint, optargs)¶

Parameters:

mountpoint (str) –
optargs (Guestfs.Fstrim or None) – a Guestfs.Fstrim containing optional arguments

Raises:

Returns:

true on success, false on error

Return type:

trim free space in a filesystem

Trim the free space in the filesystem mounted on mountpoint. The filesystem must be mounted read-write.

The filesystem contents are not affected, but any free space in the filesystem is “trimmed”, that is, given back to the host device, thus making disk images more sparse, allowing unused space in qcow2 files to be reused, etc.

This operation requires support in libguestfs, the mounted filesystem, the host filesystem, qemu and the host kernel. If this support isn’t present it may give an error or even appear to run but do nothing.

In the case where the kernel vfs driver does not support trimming, this call will fail with errno set to ENOTSUP. Currently this happens when trying to trim FAT filesystems.

See also Guestfs.Session.zero_free_space(). That is a slightly different operation that turns free space in the filesystem into zeroes. It is valid to call Guestfs.Session.fstrim() either instead of, or after calling Guestfs.Session.zero_free_space().

This function depends on the feature “fstrim”. See also Guestfs.Session.feature_available().

New in version 1.19.6.

get_append()¶

Raises:: GLib.Error
Returns:: the returned string. Note that None does not indicate error
Return type:: str

get the additional kernel options

Return the additional kernel options which are added to the libguestfs appliance kernel command line.

If None then no options are added.

New in version 1.0.26.

get_attach_method()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the backend

Return the current backend.

See Guestfs.Session.set_backend() and “BACKEND” in guestfs(3).

New in version 1.9.8.

Deprecated since version ???: In new code, use Guestfs.Session.get_backend() instead

get_autosync()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get autosync mode

Get the autosync flag.

New in version 0.3.

get_backend()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the backend

Return the current backend.

This handle property was previously called the “attach method”.

See Guestfs.Session.set_backend() and “BACKEND” in guestfs(3).

New in version 1.21.26.

get_backend_setting(name)¶

Parameters:: name (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get a single per-backend settings string

Find a backend setting string which is either “name” or begins with “name=”. If “name”, this returns the string “1”. If “name=”, this returns the part after the equals sign (which may be an empty string).

If no such setting is found, this function throws an error. The errno (see guestfs_session_last_errno()) will be ESRCH in this case.

See “BACKEND” in guestfs(3), “BACKEND SETTINGS” in guestfs(3).

New in version 1.27.2.

get_backend_settings()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

get per-backend settings

Return the current backend settings.

This call returns all backend settings strings. If you want to find a single backend setting, see Guestfs.Session.get_backend_setting().

See “BACKEND” in guestfs(3), “BACKEND SETTINGS” in guestfs(3).

New in version 1.25.24.

get_cachedir()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the appliance cache directory

Get the directory used by the handle to store the appliance cache.

New in version 1.19.58.

get_direct()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get direct appliance mode flag

Return the direct appliance mode flag.

New in version 1.0.72.

Deprecated since version ???: In new code, use guestfs_session_internal_get_console_socket() instead

get_e2attrs(file)¶

Parameters:: file (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get ext2 file attributes of a file

This returns the file attributes associated with file.

The attributes are a set of bits associated with each inode which affect the behaviour of the file. The attributes are returned as a string of letters (described below). The string may be empty, indicating that no file attributes are set for this file.

These attributes are only present when the file is located on an ext2/3/4 filesystem. Using this call on other filesystem types will result in an error.

The characters (file attributes) in the returned string are currently:

‘A’ When the file is accessed, its atime is not modified.

‘a’ The file is append-only.

‘c’ The file is compressed on-disk.

‘D’ (Directories only.) Changes to this directory are written synchronously to disk.

‘d’ The file is not a candidate for backup (see dump(8)).

‘E’ The file has compression errors.

‘e’ The file is using extents.

‘h’ The file is storing its blocks in units of the filesystem blocksize instead of sectors.

‘I’ (Directories only.) The directory is using hashed trees.

‘i’ The file is immutable. It cannot be modified, deleted or renamed. No link can be created to this file.

‘j’ The file is data-journaled.

‘s’ When the file is deleted, all its blocks will be zeroed.

‘S’ Changes to this file are written synchronously to disk.

‘T’ (Directories only.) This is a hint to the block allocator that subdirectories contained in this directory should be spread across blocks. If not present, the block allocator will try to group subdirectories together.

‘t’ For a file, this disables tail-merging. (Not used by upstream implementations of ext2.)

‘u’ When the file is deleted, its blocks will be saved, allowing the file to be undeleted.

‘X’ The raw contents of the compressed file may be accessed.

‘Z’ The compressed file is dirty.

More file attributes may be added to this list later. Not all file attributes may be set for all kinds of files. For detailed information, consult the chattr(1) man page.

Don’t confuse these attributes with extended attributes (see Guestfs.Session.getxattr()).

New in version 1.17.31.

get_e2generation(file)¶

Parameters:: file (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get ext2 file generation of a file

This returns the ext2 file generation of a file. The generation (which used to be called the “version”) is a number associated with an inode. This is most commonly used by NFS servers.

The generation is only present when the file is located on an ext2/3/4 filesystem. Using this call on other filesystem types will result in an error.

See Guestfs.Session.set_e2generation().

New in version 1.17.31.

get_e2label(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the ext2/3/4 filesystem label

This returns the ext2/3/4 filesystem label of the filesystem on device.

New in version 1.0.15.

Deprecated since version ???: In new code, use Guestfs.Session.vfs_label() instead

get_e2uuid(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the ext2/3/4 filesystem UUID

This returns the ext2/3/4 filesystem UUID of the filesystem on device.

New in version 1.0.15.

Deprecated since version ???: In new code, use Guestfs.Session.vfs_uuid() instead

get_hv()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the hypervisor binary

Return the current hypervisor binary.

This is always non-None. If it wasn’t set already, then this will return the default qemu binary name.

New in version 1.23.17.

get_identifier()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the handle identifier

Get the handle identifier. See Guestfs.Session.set_identifier().

New in version 1.31.14.

get_libvirt_requested_credential_challenge(index)¶

Parameters:: index (int) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

challenge of i’th requested credential

Get the challenge (provided by libvirt) for the index'th requested credential. If libvirt did not provide a challenge, this returns the empty string “”.

See “LIBVIRT AUTHENTICATION” in guestfs(3) for documentation and example code.

New in version 1.19.52.

get_libvirt_requested_credential_defresult(index)¶

Parameters:: index (int) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

default result of i’th requested credential

Get the default result (provided by libvirt) for the index'th requested credential. If libvirt did not provide a default result, this returns the empty string “”.

See “LIBVIRT AUTHENTICATION” in guestfs(3) for documentation and example code.

New in version 1.19.52.

get_libvirt_requested_credential_prompt(index)¶

Parameters:: index (int) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

prompt of i’th requested credential

Get the prompt (provided by libvirt) for the index'th requested credential. If libvirt did not provide a prompt, this returns the empty string “”.

See “LIBVIRT AUTHENTICATION” in guestfs(3) for documentation and example code.

New in version 1.19.52.

get_libvirt_requested_credentials()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

get list of credentials requested by libvirt

This should only be called during the event callback for events of type GUESTFS_EVENT_LIBVIRT_AUTH.

Return the list of credentials requested by libvirt. Possible values are a subset of the strings provided when you called Guestfs.Session.set_libvirt_supported_credentials().

See “LIBVIRT AUTHENTICATION” in guestfs(3) for documentation and example code.

New in version 1.19.52.

get_memsize()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get memory allocated to the hypervisor

This gets the memory size in megabytes allocated to the hypervisor.

If Guestfs.Session.set_memsize() was not called on this handle, and if LIBGUESTFS_MEMSIZE was not set, then this returns the compiled-in default value for memsize.

For more information on the architecture of libguestfs, see guestfs(3).

New in version 1.0.55.

get_network()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get enable network flag

This returns the enable network flag.

New in version 1.5.4.

get_path()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the search path

Return the current search path.

This is always non-None. If it wasn’t set already, then this will return the default path.

New in version 0.3.

get_pgroup()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get process group flag

This returns the process group flag.

New in version 1.11.18.

get_pid()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get PID of hypervisor

Return the process ID of the hypervisor. If there is no hypervisor running, then this will return an error.

This is an internal call used for debugging and testing.

New in version 1.0.56.

get_program()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the program name

Get the program name. See Guestfs.Session.set_program().

New in version 1.21.29.

get_qemu()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the hypervisor binary (usually qemu)

Return the current hypervisor binary (usually qemu).

This is always non-None. If it wasn’t set already, then this will return the default qemu binary name.

New in version 1.0.6.

Deprecated since version ???: In new code, use Guestfs.Session.get_hv() instead

get_recovery_proc()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get recovery process enabled flag

Return the recovery process enabled flag.

New in version 1.0.77.

get_selinux()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get SELinux enabled flag

This returns the current setting of the selinux flag which is passed to the appliance at boot time. See Guestfs.Session.set_selinux().

For more information on the architecture of libguestfs, see guestfs(3).

New in version 1.0.67.

Deprecated since version ???: In new code, use Guestfs.Session.selinux_relabel() instead

get_smp()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get number of virtual CPUs in appliance

This returns the number of virtual CPUs assigned to the appliance.

New in version 1.13.15.

get_sockdir()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the temporary directory for sockets and PID files

Get the directory used by the handle to store temporary socket and PID files.

This is different from Guestfs.Session.get_tmpdir(), as we need shorter paths for sockets (due to the limited buffers of filenames for UNIX sockets), and Guestfs.Session.get_tmpdir() may be too long for them. Furthermore, sockets and PID files must be accessible to such background services started by libguestfs that may not have permission to access the temporary directory returned by Guestfs.Session.get_tmpdir().

The environment variable XDG_RUNTIME_DIR controls the default value: If XDG_RUNTIME_DIR is set, then that is the default. Else /tmp is the default.

New in version 1.33.8.

get_state()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get the current state

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).

New in version 1.0.2.

get_tmpdir()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the temporary directory

Get the directory used by the handle to store temporary files.

New in version 1.19.58.

get_trace()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get command trace enabled flag

Return the command trace flag.

New in version 1.0.69.

get_umask()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get the current umask

Return the current umask. By default the umask is 022 unless it has been set by calling Guestfs.Session.umask().

New in version 1.3.4.

get_verbose()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get verbose mode

This returns the verbose messages flag.

New in version 0.3.

getcon()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get SELinux security context

This gets the SELinux security context of the daemon.

See the documentation about SELINUX in guestfs(3), and Guestfs.Session.setcon()

This function depends on the feature “selinux”. See also Guestfs.Session.feature_available().

New in version 1.0.67.

Deprecated since version ???: In new code, use Guestfs.Session.selinux_relabel() instead

getxattr(path, name)¶

Parameters:

path (str) –
name (str) –

Raises:

Returns:

an array of binary data, or None on error

Return type:

get a single extended attribute

Get a single extended attribute from file path named name. This call follows symlinks. If you want to lookup an extended attribute for the symlink itself, use Guestfs.Session.lgetxattr().

Normally it is better to get all extended attributes from a file in one go by calling Guestfs.Session.getxattrs(). However some Linux filesystem implementations are buggy and do not provide a way to list out attributes. For these filesystems (notably ntfs-3g) you have to know the names of the extended attributes you want in advance and call this function.

Extended attribute values are blobs of binary data. If there is no extended attribute named name, this returns an error.

See also: Guestfs.Session.getxattrs(), Guestfs.Session.lgetxattr(), attr(5).

This function depends on the feature “linuxxattrs”. See also Guestfs.Session.feature_available().

New in version 1.7.24.

getxattrs(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: an array of XAttr objects, or None on error
Return type:: [Guestfs.XAttr]

list extended attributes of a file or directory

This call lists the extended attributes of the file or directory path.

At the system call level, this is a combination of the listxattr(2) and getxattr(2) calls.

See also: Guestfs.Session.lgetxattrs(), attr(5).

This function depends on the feature “linuxxattrs”. See also Guestfs.Session.feature_available().

New in version 1.0.59.

glob_expand(pattern, optargs)¶

Parameters:

pattern (str) –
optargs (Guestfs.GlobExpand or None) – a Guestfs.GlobExpand containing optional arguments

Raises:

Returns:

an array of returned strings, or None on error

Return type:

expand a wildcard path

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.

directoryslash controls whether use the GLOB_MARK flag for glob(3), and it defaults to true. It can be explicitly set as off to return no trailing slashes in filenames of directories.

Notice that there is no equivalent command for expanding a device name (eg. /dev/sd*). Use Guestfs.Session.list_devices(), Guestfs.Session.list_partitions() etc functions instead.

New in version 1.0.50.

grep(regex, path, optargs)¶

Parameters:

regex (str) –
path (str) –
optargs (Guestfs.Grep or None) – a Guestfs.Grep containing optional arguments

Raises:

Returns:

an array of returned strings, or None on error

Return type:

return lines matching a pattern

This calls the external grep(1) program and returns the matching lines.

The optional flags are:

extended Use extended regular expressions. This is the same as using the *-E* flag.

fixed Match fixed (don’t use regular expressions). This is the same as using the *-F* flag.

insensitive Match case-insensitive. This is the same as using the *-i* flag.

compressed Use zgrep(1) instead of grep(1). This allows the input to be compress- or gzip-compressed.

New in version 1.0.66.

grepi(regex, path)¶

Parameters:

regex (str) –
path (str) –

Raises:

Returns:

an array of returned strings, or None on error

Return type:

return lines matching a pattern

This calls the external “grep -i” program and returns the matching lines.

New in version 1.0.66.

Deprecated since version ???: In new code, use Guestfs.Session.grep() instead

grub_install(root, device)¶

Parameters:

root (str) –
device (str) –

Raises:

Returns:

true on success, false on error

Return type:

install GRUB 1

This command installs GRUB 1 (the Grand Unified Bootloader) on device, with the root directory being root.

Notes:

There is currently no way in the API to install grub2, which is used by most modern Linux guests. It is possible to run the grub2 command from the guest, although see the caveats in “RUNNING COMMANDS” in guestfs(3).
This uses grub-install(8) from the host. Unfortunately grub is not always compatible with itself, so this only works in rather narrow circumstances. Careful testing with each guest version is advisable.
If grub-install reports the error “No suitable drive was found in the generated device map.” it may be that you need to create a /boot/grub/device.map file first that contains the mapping between grub device names and Linux device names. It is usually sufficient to create a file containing:

(hd0) /dev/vda

replacing /dev/vda with the name of the installation device.

This function depends on the feature “grub”. See also Guestfs.Session.feature_available().

New in version 1.0.17.

head(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

return first 10 lines of a file

This command returns up to the first 10 lines of a file as a list of strings.

New in version 1.0.54.

head_n(nrlines, path)¶

Parameters:

nrlines (int) –
path (str) –

Raises:

Returns:

an array of returned strings, or None on error

Return type:

return first N lines of a file

If the parameter nrlines is a positive number, this returns the first nrlines lines of the file path.

If the parameter nrlines is a negative number, this returns lines from the file path, excluding the last nrlines lines.

If the parameter nrlines is zero, this returns an empty list.

New in version 1.0.54.

hexdump(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

dump a file in hexadecimal

This runs “hexdump -C” on the given path. The result is the human-readable, canonical hex dump of the file.

New in version 1.0.22.

hivex_close()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

close the current hivex handle

Close the current hivex handle.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_commit(filename)¶

Parameters:: filename (str or None) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

commit (write) changes back to the hive

Commit (write) changes to the hive.

If the optional filename parameter is null, then the changes are written back to the same hive that was opened. If this is not null then they are written to the alternate filename given and the original hive is left untouched.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_add_child(parent, name)¶

Parameters:

parent (int) –
name (str) –

Raises:

Returns:

the returned value, or -1 on error

Return type:

add a child node

Add a child node to parent named name.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_children(nodeh)¶

Parameters:: nodeh (int) –
Raises:: GLib.Error
Returns:: an array of HivexNode objects, or None on error
Return type:: [Guestfs.HivexNode]

return list of nodes which are subkeys of node

Return the list of nodes which are subkeys of nodeh.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_delete_child(nodeh)¶

Parameters:: nodeh (int) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

delete a node (recursively)

Delete nodeh, recursively if necessary.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_get_child(nodeh, name)¶

Parameters:

nodeh (int) –
name (str) –

Raises:

Returns:

the returned value, or -1 on error

Return type:

return the named child of node

Return the child of nodeh with the name name, if it exists. This can return 0 meaning the name was not found.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_get_value(nodeh, key)¶

Parameters:

nodeh (int) –
key (str) –

Raises:

Returns:

the returned value, or -1 on error

Return type:

return the named value

Return the value attached to nodeh which has the name key, if it exists. This can return 0 meaning the key was not found.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_name(nodeh)¶

Parameters:: nodeh (int) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

return the name of the node

Return the name of nodeh.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_parent(nodeh)¶

Parameters:: nodeh (int) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

return the parent of node

Return the parent node of nodeh.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_set_value(nodeh, key, t, val)¶

Parameters:

nodeh (int) –
key (str) –
t (int) –
val (bytes) – an array of binary data

Raises:

Returns:

true on success, false on error

Return type:

set or replace a single value in a node

Set or replace a single value under the node nodeh. The key is the name, t is the type, and val is the data.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_node_values(nodeh)¶

Parameters:: nodeh (int) –
Raises:: GLib.Error
Returns:: an array of HivexValue objects, or None on error
Return type:: [Guestfs.HivexValue]

return list of values attached to node

Return the array of (key, datatype, data) tuples attached to nodeh.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_open(filename, optargs)¶

Parameters:

filename (str) –
optargs (Guestfs.HivexOpen or None) – a Guestfs.HivexOpen containing optional arguments

Raises:

Returns:

true on success, false on error

Return type:

open a Windows Registry hive file

Open the Windows Registry hive file named filename. If there was any previous hivex handle associated with this guestfs session, then it is closed.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_root()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

return the root node of the hive

Return the root node of the hive.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_value_key(valueh)¶

Parameters:: valueh (int) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

return the key field from the (key, datatype, data) tuple

Return the key (name) field of a (key, datatype, data) tuple.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_value_string(valueh)¶

Parameters:: valueh (int) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

return the data field as a UTF-8 string

This calls Guestfs.Session.hivex_value_value() (which returns the data field from a hivex value tuple). It then assumes that the field is a UTF-16LE string and converts the result to UTF-8 (or if this is not possible, it returns an error).

This is useful for reading strings out of the Windows registry. However it is not foolproof because the registry is not strongly-typed and fields can contain arbitrary or unexpected data.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.37.22.

hivex_value_type(valueh)¶

Parameters:: valueh (int) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

return the data type from the (key, datatype, data) tuple

Return the data type field from a (key, datatype, data) tuple.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

hivex_value_utf8(valueh)¶

Parameters:: valueh (int) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

return the data field as a UTF-8 string

This calls Guestfs.Session.hivex_value_value() (which returns the data field from a hivex value tuple). It then assumes that the field is a UTF-16LE string and converts the result to UTF-8 (or if this is not possible, it returns an error).

This is useful for reading strings out of the Windows registry. However it is not foolproof because the registry is not strongly-typed and fields can contain arbitrary or unexpected data.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

Deprecated since version ???: In new code, use Guestfs.Session.hivex_value_string() instead

hivex_value_value(valueh)¶

Parameters:: valueh (int) –
Raises:: GLib.Error
Returns:: an array of binary data, or None on error
Return type:: bytes

return the data field from the (key, datatype, data) tuple

Return the data field of a (key, datatype, data) tuple.

This is a wrapper around the hivex(3) call of the same name.

This function depends on the feature “hivex”. See also Guestfs.Session.feature_available().

New in version 1.19.35.

initrd_cat(initrdpath, filename)¶

Parameters:

initrdpath (str) –
filename (str) –

Raises:

Returns:

an array of binary data, or None on error

Return type:

list the contents of a single file in an initrd

This command unpacks the file filename from the initrd file called initrdpath. The filename must be given *without* the initial / character.

For example, in guestfish you could use the following command to examine the boot script (usually called /init) contained in a Linux initrd or initramfs image:

initrd-cat /boot/initrd-<version>.img init

New in version 1.0.84.

initrd_list(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list files in an initrd

This command lists out files contained in an initrd.

The files are listed without any initial / character. The files are listed in the order they appear (not necessarily alphabetical). Directory names are listed as separate items.

Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem as initrd. We *only* support the newer initramfs format (compressed cpio files).

New in version 1.0.54.

inotify_add_watch(path, mask)¶

Parameters:

path (str) –
mask (int) –

Raises:

Returns:

the returned value, or -1 on error

Return type:

add an inotify watch

Watch path for the events listed in mask.

Note that if path is a directory then events within that directory are watched, but this does *not* happen recursively (in subdirectories).

Note for non-C or non-Linux callers: the inotify events are defined by the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.

This function depends on the feature “inotify”. See also Guestfs.Session.feature_available().

New in version 1.0.66.

inotify_close()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

close the inotify handle

This closes the inotify handle which was previously opened by inotify_init. It removes all watches, throws away any pending events, and deallocates all resources.

This function depends on the feature “inotify”. See also Guestfs.Session.feature_available().

New in version 1.0.66.

inotify_files()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

return list of watched files that had events

This function is a helpful wrapper around Guestfs.Session.inotify_read() which just returns a list of pathnames of objects that were touched. The returned pathnames are sorted and deduplicated.

This function depends on the feature “inotify”. See also Guestfs.Session.feature_available().

New in version 1.0.66.

inotify_init(maxevents)¶

Parameters:: maxevents (int) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

create an inotify handle

This command creates a new inotify handle. The inotify subsystem can be used to notify events which happen to objects in the guest filesystem.

maxevents is the maximum number of events which will be queued up between calls to Guestfs.Session.inotify_read() or Guestfs.Session.inotify_files(). If this is passed as 0, then the kernel (or previously set) default is used. For Linux 2.6.29 the default was 16384 events. Beyond this limit, the kernel throws away events, but records the fact that it threw them away by setting a flag IN_Q_OVERFLOW in the returned structure list (see Guestfs.Session.inotify_read()).

Before any events are generated, you have to add some watches to the internal watch list. See: Guestfs.Session.inotify_add_watch() and Guestfs.Session.inotify_rm_watch().

Queued up events should be read periodically by calling Guestfs.Session.inotify_read() (or Guestfs.Session.inotify_files() which is just a helpful wrapper around Guestfs.Session.inotify_read()). If you don’t read the events out often enough then you risk the internal queue overflowing.

The handle should be closed after use by calling Guestfs.Session.inotify_close(). This also removes any watches automatically.

See also inotify(7) for an overview of the inotify interface as exposed by the Linux kernel, which is roughly what we expose via libguestfs. Note that there is one global inotify handle per libguestfs instance.

This function depends on the feature “inotify”. See also Guestfs.Session.feature_available().

New in version 1.0.66.

inotify_read()¶

Raises:: GLib.Error
Returns:: an array of INotifyEvent objects, or None on error
Return type:: [Guestfs.INotifyEvent]

return list of inotify events

Return the complete queue of events that have happened since the previous read call.

If no events have happened, this returns an empty list.

*Note*: In order to make sure that all events have been read, you must call this function repeatedly until it returns an empty list. The reason is that the call will read events up to the maximum appliance-to-host message size and leave remaining events in the queue.

This function depends on the feature “inotify”. See also Guestfs.Session.feature_available().

New in version 1.0.66.

inotify_rm_watch(wd)¶

Parameters:: wd (int) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

remove an inotify watch

Remove a previously defined inotify watch. See Guestfs.Session.inotify_add_watch().

This function depends on the feature “inotify”. See also Guestfs.Session.feature_available().

New in version 1.0.66.

inspect_get_arch(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get architecture of inspected operating system

This returns the architecture of the inspected operating system. The possible return values are listed under Guestfs.Session.file_architecture().

If the architecture could not be determined, then the string unknown is returned.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.5.3.

inspect_get_build_id(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the system build ID

This returns the build ID of the system, or the string “unknown” if the system does not have a build ID.

For Windows, this gets the build number. Although it is returned as a string, it is (so far) always a number. See http://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions for some possible values.

For Linux, this returns the BUILD_ID string from /etc/os-release, although this is not often used.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.49.8.

inspect_get_distro(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get distro of inspected operating system

This returns the distro (distribution) of the inspected operating system.

Currently defined distros are:

“alpinelinux” Alpine Linux.

“altlinux” ALT Linux.

“archlinux” Arch Linux.

“buildroot” Buildroot-derived distro, but not one we specifically recognize.

“centos” CentOS.

“cirros” Cirros.

“coreos” CoreOS.

“debian” Debian.

“fedora” Fedora.

“freebsd” FreeBSD.

“freedos” FreeDOS.

“frugalware” Frugalware.

“gentoo” Gentoo.

“kalilinux” Kali Linux.

“kylin” Kylin.

“linuxmint” Linux Mint.

“mageia” Mageia.

“mandriva” Mandriva.

“meego” MeeGo.

“msdos” Microsoft DOS.

“neokylin” NeoKylin.

“netbsd” NetBSD.

“openbsd” OpenBSD.

“openmandriva” OpenMandriva Lx.

“opensuse” OpenSUSE.

“oraclelinux” Oracle Linux.

“pardus” Pardus.

“pldlinux” PLD Linux.

“redhat-based” Some Red Hat-derived distro.

“rhel” Red Hat Enterprise Linux.

“rocky” Rocky Linux.

“scientificlinux” Scientific Linux.

“slackware” Slackware.

“sles” SuSE Linux Enterprise Server or Desktop.

“suse-based” Some openSuSE-derived distro.

“ttylinux” ttylinux.

“ubuntu” Ubuntu.

“unknown” The distro could not be determined.

“voidlinux” Void Linux.

“windows” Windows does not have distributions. This string is returned if the OS type is Windows.

Future versions of libguestfs may return other strings here. The caller should be prepared to handle any string.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.5.3.

inspect_get_drive_mappings(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: a GLib.HashTable of results, or None on error
Return type:: {str: str}

get drive letter mappings

This call is useful for Windows which uses a primitive system of assigning drive letters (like C:\) to partitions. This inspection API examines the Windows Registry to find out how disks/partitions are mapped to drive letters, and returns a hash table as in the example below:

C => /dev/vda2

E => /dev/vdb1

F => /dev/vdc1

Note that keys are drive letters. For Windows, the key is case insensitive and just contains the drive letter, without the customary colon separator character.

In future we may support other operating systems that also used drive letters, but the keys for those might not be case insensitive and might be longer than 1 character. For example in OS-9, hard drives were named h0, h1 etc.

For Windows guests, currently only hard drive mappings are returned. Removable disks (eg. DVD-ROMs) are ignored.

For guests that do not use drive mappings, or if the drive mappings could not be determined, this returns an empty hash table.

Please read “INSPECTION” in guestfs(3) for more details. See also Guestfs.Session.inspect_get_mountpoints(), Guestfs.Session.inspect_get_filesystems().

New in version 1.9.17.

inspect_get_filesystems(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

get filesystems associated with inspected operating system

This returns a list of all the filesystems that we think are associated with this operating system. This includes the root filesystem, other ordinary filesystems, and non-mounted devices like swap partitions.

In the case of a multi-boot virtual machine, it is possible for a filesystem to be shared between operating systems.

Please read “INSPECTION” in guestfs(3) for more details. See also Guestfs.Session.inspect_get_mountpoints().

New in version 1.5.3.

inspect_get_format(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get format of inspected operating system

Before libguestfs 1.38, there was some unreliable support for detecting installer CDs. This API would return:

installed This is an installed operating system.

installer The disk image being inspected is not an installed operating system, but a *bootable* install disk, live CD, or similar.

unknown The format of this disk image is not known.

In libguestfs ≥ 1.38, this only returns installed. Use libosinfo directly to detect installer CDs.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.9.4.

Deprecated since version ???: There is no documented replacement

inspect_get_hostname(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get hostname of the operating system

This function returns the hostname of the operating system as found by inspection of the guest’s configuration files.

If the hostname could not be determined, then the string unknown is returned.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.7.9.

inspect_get_icon(root, optargs)¶

Parameters:

root (str) –
optargs (Guestfs.InspectGetIcon or None) – a Guestfs.InspectGetIcon containing optional arguments

Raises:

Returns:

an array of binary data, or None on error

Return type:

get the icon corresponding to this operating system

This function returns an icon corresponding to the inspected operating system. The icon is returned as a buffer containing a PNG image (re-encoded to PNG if necessary).

If it was not possible to get an icon this function returns a zero-length (non-None) buffer. *Callers must check for this case*.

Libguestfs will start by looking for a file called /etc/favicon.png or C:\etc\favicon.png and if it has the correct format, the contents of this file will be returned. You can disable favicons by passing the optional favicon boolean as false (default is true).

If finding the favicon fails, then we look in other places in the guest for a suitable icon.

If the optional highquality boolean is true then only high quality icons are returned, which means only icons of high resolution with an alpha channel. The default (false) is to return any icon we can, even if it is of substandard quality.

Notes:

Unlike most other inspection API calls, the guest’s disks must be mounted up before you call this, since it needs to read information from the guest filesystem during the call.
Security: The icon data comes from the untrusted guest, and should be treated with caution. PNG files have been known to contain exploits. Ensure that libpng (or other relevant libraries) are fully up to date before trying to process or display the icon.
The PNG image returned can be any size. It might not be square. Libguestfs tries to return the largest, highest quality icon available. The application must scale the icon to the required size.
Extracting icons from Windows guests requires the external wrestool(1) program from the icoutils package, and several programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the netpbm package. These must be installed separately.
Operating system icons are usually trademarks. Seek legal advice before using trademarks in applications.

New in version 1.11.12.

inspect_get_major_version(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get major version of inspected operating system

This returns the major version number of the inspected operating system.

Windows uses a consistent versioning scheme which is *not* reflected in the popular public names used by the operating system. Notably the operating system known as “Windows 7” is really version 6.1 (ie. major = 6, minor = 1). You can find out the real versions corresponding to releases of Windows by consulting Wikipedia or MSDN.

If the version could not be determined, then 0 is returned.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.5.3.

inspect_get_minor_version(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get minor version of inspected operating system

This returns the minor version number of the inspected operating system.

If the version could not be determined, then 0 is returned.

Please read “INSPECTION” in guestfs(3) for more details. See also Guestfs.Session.inspect_get_major_version().

New in version 1.5.3.

inspect_get_mountpoints(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: a GLib.HashTable of results, or None on error
Return type:: {str: str}

get mountpoints of inspected operating system

This returns a hash of where we think the filesystems associated with this operating system should be mounted. Callers should note that this is at best an educated guess made by reading configuration files such as /etc/fstab. *In particular note* that this may return filesystems which are non-existent or not mountable and callers should be prepared to handle or ignore failures if they try to mount them.

Each element in the returned hashtable has a key which is the path of the mountpoint (eg. /boot) and a value which is the filesystem that would be mounted there (eg. /dev/sda1).

Non-mounted devices such as swap devices are *not* returned in this list.

For operating systems like Windows which still use drive letters, this call will only return an entry for the first drive “mounted on” /. For information about the mapping of drive letters to partitions, see Guestfs.Session.inspect_get_drive_mappings().

Please read “INSPECTION” in guestfs(3) for more details. See also Guestfs.Session.inspect_get_filesystems().

New in version 1.5.3.

inspect_get_osinfo(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get a possible osinfo short ID corresponding to this operating system

This function returns a possible short ID for libosinfo corresponding to the guest.

*Note:* The returned ID is only a guess by libguestfs, and nothing ensures that it actually exists in osinfo-db.

If no ID could not be determined, then the string unknown is returned.

New in version 1.39.1.

inspect_get_package_format(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get package format used by the operating system

This function and Guestfs.Session.inspect_get_package_management() return the package format and package management tool used by the inspected operating system. For example for Fedora these functions would return rpm (package format), and yum or dnf (package management).

This returns the string unknown if we could not determine the package format *or* if the operating system does not have a real packaging system (eg. Windows).

Possible strings include: rpm, deb, ebuild, pisi, pacman, pkgsrc, apk, xbps. Future versions of libguestfs may return other strings.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.7.5.

inspect_get_package_management(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get package management tool used by the operating system

Guestfs.Session.inspect_get_package_format() and this function return the package format and package management tool used by the inspected operating system. For example for Fedora these functions would return rpm (package format), and yum or dnf (package management).

This returns the string unknown if we could not determine the package management tool *or* if the operating system does not have a real packaging system (eg. Windows).

Possible strings include: yum, dnf, up2date, apt (for all Debian derivatives), portage, pisi, pacman, urpmi, zypper, apk, xbps. Future versions of libguestfs may return other strings.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.7.5.

inspect_get_product_name(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get product name of inspected operating system

This returns the product name of the inspected operating system. The product name is generally some freeform string which can be displayed to the user, but should not be parsed by programs.

If the product name could not be determined, then the string unknown is returned.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.5.3.

inspect_get_product_variant(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get product variant of inspected operating system

This returns the product variant of the inspected operating system.

For Windows guests, this returns the contents of the Registry key “HKLM\Software\Microsoft\Windows NT\CurrentVersion” InstallationType which is usually a string such as Client or Server (other values are possible). This can be used to distinguish consumer and enterprise versions of Windows that have the same version number (for example, Windows 7 and Windows 2008 Server are both version 6.1, but the former is Client and the latter is Server).

For enterprise Linux guests, in future we intend this to return the product variant such as Desktop, Server and so on. But this is not implemented at present.

If the product variant could not be determined, then the string unknown is returned.

Please read “INSPECTION” in guestfs(3) for more details. See also Guestfs.Session.inspect_get_product_name(), Guestfs.Session.inspect_get_major_version().

New in version 1.9.13.

inspect_get_roots()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

return list of operating systems found by last inspection

This function is a convenient way to get the list of root devices, as returned from a previous call to Guestfs.Session.inspect_os(), but without redoing the whole inspection process.

This returns an empty list if either no root devices were found or the caller has not called Guestfs.Session.inspect_os().

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.7.3.

inspect_get_type(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get type of inspected operating system

This returns the type of the inspected operating system. Currently defined types are:

“linux” Any Linux-based operating system.

“windows” Any Microsoft Windows operating system.

“freebsd” FreeBSD.

“netbsd” NetBSD.

“openbsd” OpenBSD.

“hurd” GNU/Hurd.

“dos” MS-DOS, FreeDOS and others.

“minix” MINIX.

“unknown” The operating system type could not be determined.

Future versions of libguestfs may return other strings here. The caller should be prepared to handle any string.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.5.3.

inspect_get_windows_current_control_set(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get Windows CurrentControlSet of inspected operating system

This returns the Windows CurrentControlSet of the inspected guest. The CurrentControlSet is a registry key name such as ControlSet001.

This call assumes that the guest is Windows and that the Registry could be examined by inspection. If this is not the case then an error is returned.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.9.17.

inspect_get_windows_software_hive(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the path of the Windows software hive

This returns the path to the hive (binary Windows Registry file) corresponding to HKLM\SOFTWARE.

This call assumes that the guest is Windows and that the guest has a software hive file with the right name. If this is not the case then an error is returned. This call does not check that the hive is a valid Windows Registry hive.

You can use Guestfs.Session.hivex_open() to read or write to the hive.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.35.26.

inspect_get_windows_system_hive(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the path of the Windows system hive

This returns the path to the hive (binary Windows Registry file) corresponding to HKLM\SYSTEM.

This call assumes that the guest is Windows and that the guest has a system hive file with the right name. If this is not the case then an error is returned. This call does not check that the hive is a valid Windows Registry hive.

You can use Guestfs.Session.hivex_open() to read or write to the hive.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.35.26.

inspect_get_windows_systemroot(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get Windows systemroot of inspected operating system

This returns the Windows systemroot of the inspected guest. The systemroot is a directory path such as /WINDOWS.

This call assumes that the guest is Windows and that the systemroot could be determined by inspection. If this is not the case then an error is returned.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.5.25.

inspect_is_live(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get live flag for install disk

This is deprecated and always returns false.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.9.4.

Deprecated since version ???: There is no documented replacement

inspect_is_multipart(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get multipart flag for install disk

This is deprecated and always returns false.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.9.4.

Deprecated since version ???: There is no documented replacement

inspect_is_netinst(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get netinst (network installer) flag for install disk

This is deprecated and always returns false.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.9.4.

Deprecated since version ???: There is no documented replacement

inspect_list_applications(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: an array of Application objects, or None on error
Return type:: [Guestfs.Application]

get list of applications installed in the operating system

Return the list of applications installed in the operating system.

*Note:* This call works differently from other parts of the inspection API. You have to call Guestfs.Session.inspect_os(), then Guestfs.Session.inspect_get_mountpoints(), then mount up the disks, before calling this. Listing applications is a significantly more difficult operation which requires access to the full filesystem. Also note that unlike the other “guestfs_inspect_get_*” calls which are just returning data cached in the libguestfs handle, this call actually reads parts of the mounted filesystems during the call.

This returns an empty list if the inspection code was not able to determine the list of applications.

The application structure contains the following fields:

app_name The name of the application. For Linux guests, this is the package name.

app_display_name The display name of the application, sometimes localized to the install language of the guest operating system.

If unavailable this is returned as an empty string “”. Callers needing to display something can use app_name instead.

app_epoch For package managers which use epochs, this contains the epoch of the package (an integer). If unavailable, this is returned as 0.

app_version The version string of the application or package. If unavailable this is returned as an empty string “”.

app_release The release string of the application or package, for package managers that use this. If unavailable this is returned as an empty string “”.

app_install_path The installation path of the application (on operating systems such as Windows which use installation paths). This path is in the format used by the guest operating system, it is not a libguestfs path.

If unavailable this is returned as an empty string “”.

app_trans_path The install path translated into a libguestfs path. If unavailable this is returned as an empty string “”.

app_publisher The name of the publisher of the application, for package managers that use this. If unavailable this is returned as an empty string “”.

app_url The URL (eg. upstream URL) of the application. If unavailable this is returned as an empty string “”.

app_source_package For packaging systems which support this, the name of the source package. If unavailable this is returned as an empty string “”.

app_summary A short (usually one line) description of the application or package. If unavailable this is returned as an empty string “”.

app_description A longer description of the application or package. If unavailable this is returned as an empty string “”.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.7.8.

Deprecated since version ???: In new code, use Guestfs.Session.inspect_list_applications2() instead

inspect_list_applications2(root)¶

Parameters:: root (str) –
Raises:: GLib.Error
Returns:: an array of Application2 objects, or None on error
Return type:: [Guestfs.Application2]

get list of applications installed in the operating system

Return the list of applications installed in the operating system.

*Note:* This call works differently from other parts of the inspection API. You have to call Guestfs.Session.inspect_os(), then Guestfs.Session.inspect_get_mountpoints(), then mount up the disks, before calling this. Listing applications is a significantly more difficult operation which requires access to the full filesystem. Also note that unlike the other “guestfs_inspect_get_*” calls which are just returning data cached in the libguestfs handle, this call actually reads parts of the mounted filesystems during the call.

This returns an empty list if the inspection code was not able to determine the list of applications.

The application structure contains the following fields:

app2_name The name of the application. For Linux guests, this is the package name.

app2_display_name The display name of the application, sometimes localized to the install language of the guest operating system.

If unavailable this is returned as an empty string “”. Callers needing to display something can use app2_name instead.

app2_epoch For package managers which use epochs, this contains the epoch of the package (an integer). If unavailable, this is returned as 0.

app2_version The version string of the application or package. If unavailable this is returned as an empty string “”.

app2_release The release string of the application or package, for package managers that use this. If unavailable this is returned as an empty string “”.

app2_arch The architecture string of the application or package, for package managers that use this. If unavailable this is returned as an empty string “”.

app2_install_path The installation path of the application (on operating systems such as Windows which use installation paths). This path is in the format used by the guest operating system, it is not a libguestfs path.

If unavailable this is returned as an empty string “”.

app2_trans_path The install path translated into a libguestfs path. If unavailable this is returned as an empty string “”.

app2_publisher The name of the publisher of the application, for package managers that use this. If unavailable this is returned as an empty string “”.

app2_url The URL (eg. upstream URL) of the application. If unavailable this is returned as an empty string “”.

app2_source_package For packaging systems which support this, the name of the source package. If unavailable this is returned as an empty string “”.

app2_summary A short (usually one line) description of the application or package. If unavailable this is returned as an empty string “”.

app2_description A longer description of the application or package. If unavailable this is returned as an empty string “”.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.19.56.

inspect_os()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

inspect disk and return list of operating systems found

This function uses other libguestfs functions and certain heuristics to inspect the disk(s) (usually disks belonging to a virtual machine), looking for operating systems.

The list returned is empty if no operating systems were found.

If one operating system was found, then this returns a list with a single element, which is the name of the root filesystem of this operating system. It is also possible for this function to return a list containing more than one element, indicating a dual-boot or multi-boot virtual machine, with each element being the root filesystem of one of the operating systems.

You can pass the root string(s) returned to other “guestfs_inspect_get_*” functions in order to query further information about each operating system, such as the name and version.

This function uses other libguestfs features such as Guestfs.Session.mount_ro() and Guestfs.Session.umount_all() in order to mount and unmount filesystems and look at the contents. This should be called with no disks currently mounted. The function may also use Augeas, so any existing Augeas handle will be closed.

This function cannot decrypt encrypted disks. The caller must do that first (supplying the necessary keys) if the disk is encrypted.

Please read “INSPECTION” in guestfs(3) for more details.

New in version 1.5.3.

internal_exit(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – A Gio.Cancellable object
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

cause the daemon to exit (internal use only)

This function is used internally when testing the appliance.

New in version 1.23.30.

internal_test(str, optstr, strlist, b, integer, integer64, filein, fileout, bufferin, optargs, cancellable)¶

Parameters:

str (str) –
optstr (str or None) –
strlist ([str]) – an array of strings
b (bool) –
integer (int) –
integer64 (int) –
filein (str) –
fileout (str) –
bufferin (bytes) – an array of binary data
optargs (Guestfs.InternalTest or None) – a Guestfs.InternalTest containing optional arguments
cancellable (Gio.Cancellable or None) – A Gio.Cancellable object

Raises:

Returns:

true on success, false on error

Return type:

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible parameter type correctly.

It echos the contents of each parameter to stdout (by default) or to a file (if Guestfs.Session.internal_test_set_output() was called).

You probably don’t want to call this function.

internal_test_63_optargs(optargs, cancellable)¶

Parameters:

optargs (Guestfs.InternalTest63Optargs or None) – a Guestfs.InternalTest63Optargs containing optional arguments
cancellable (Gio.Cancellable or None) – A Gio.Cancellable object

Raises:

Returns:

true on success, false on error

Return type:

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle the full range of 63 optargs correctly. (Note that 63 is not an absolute limit and it could be raised by changing the XDR protocol).

It echos the contents of each parameter to stdout (by default) or to a file (if Guestfs.Session.internal_test_set_output() was called).

You probably don’t want to call this function.

internal_test_close_output()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible parameter type correctly.

It closes the output file previously opened by Guestfs.Session.internal_test_set_output().

You probably don’t want to call this function.

internal_test_only_optargs(optargs, cancellable)¶

Parameters:

optargs (Guestfs.InternalTestOnlyOptargs or None) – a Guestfs.InternalTestOnlyOptargs containing optional arguments
cancellable (Gio.Cancellable or None) – A Gio.Cancellable object

Raises:

Returns:

true on success, false on error

Return type:

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle no args, some optargs correctly.

It echos the contents of each parameter to stdout (by default) or to a file (if Guestfs.Session.internal_test_set_output() was called).

You probably don’t want to call this function.

internal_test_rbool(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rboolerr()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rbufferout(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: an array of binary data, or None on error
Return type:: bytes

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rbufferouterr()¶

Raises:: GLib.Error
Returns:: an array of binary data, or None on error
Return type:: bytes

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rconstoptstring(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: the returned string. Note that None does not indicate error
Return type:: str

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rconstoptstringerr()¶

Raises:: GLib.Error
Returns:: the returned string. Note that None does not indicate error
Return type:: str

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rconststring(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rconststringerr()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rhashtable(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: a GLib.HashTable of results, or None on error
Return type:: {str: str}

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rhashtableerr()¶

Raises:: GLib.Error
Returns:: a GLib.HashTable of results, or None on error
Return type:: {str: str}

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rint(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rint64(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rint64err()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rinterr()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rstring(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rstringerr()¶

Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rstringlist(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rstringlisterr()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rstruct(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: a PV object, or None on error
Return type:: Guestfs.PV

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rstructerr()¶

Raises:: GLib.Error
Returns:: a PV object, or None on error
Return type:: Guestfs.PV

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_rstructlist(val)¶

Parameters:: val (str) –
Raises:: GLib.Error
Returns:: an array of PV objects, or None on error
Return type:: [Guestfs.PV]

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

It converts string val to the return type.

You probably don’t want to call this function.

internal_test_rstructlisterr()¶

Raises:: GLib.Error
Returns:: an array of PV objects, or None on error
Return type:: [Guestfs.PV]

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly.

This function always returns an error.

You probably don’t want to call this function.

internal_test_set_output(filename)¶

Parameters:: filename (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

internal test function - do not use

This is an internal test function which is used to test whether the automatically generated bindings can handle every possible parameter type correctly.

It sets the output file used by Guestfs.Session.internal_test().

You probably don’t want to call this function.

is_blockdev(path, optargs)¶

Parameters:

path (str) –
optargs (Guestfs.IsBlockdev or None) – a Guestfs.IsBlockdev containing optional arguments

Raises:

Returns:

the returned value, or -1 on error

Return type:

test if block device

This returns true if and only if there is a block device with the given path name.

If the optional flag followsymlinks is true, then a symlink (or chain of symlinks) that ends with a block device also causes the function to return true.

This call only looks at files within the guest filesystem. Libguestfs partitions and block devices (eg. /dev/sda) cannot be used as the path parameter of this call.

See also Guestfs.Session.stat().

New in version 1.5.10.

is_busy()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

is busy processing a command

This always returns false. This function is deprecated with no replacement. Do not use this function.

For more information on states, see guestfs(3).

New in version 1.0.2.

is_chardev(path, optargs)¶

Parameters:

path (str) –
optargs (Guestfs.IsChardev or None) – a Guestfs.IsChardev containing optional arguments

Raises:

Returns:

the returned value, or -1 on error

Return type:

test if character device

This returns true if and only if there is a character device with the given path name.

If the optional flag followsymlinks is true, then a symlink (or chain of symlinks) that ends with a chardev also causes the function to return true.

See also Guestfs.Session.stat().

New in version 1.5.10.

is_config()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

is in configuration state

This returns true iff this handle is being configured (in the CONFIG state).

For more information on states, see guestfs(3).

New in version 1.0.2.

is_dir(path, optargs)¶

Parameters:

path (str) –
optargs (Guestfs.IsDir or None) – a Guestfs.IsDir containing optional arguments

Raises:

Returns:

the returned value, or -1 on error

Return type:

test if a directory

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.

If the optional flag followsymlinks is true, then a symlink (or chain of symlinks) that ends with a directory also causes the function to return true.

See also Guestfs.Session.stat().

New in version 0.8.

is_fifo(path, optargs)¶

Parameters:

path (str) –
optargs (Guestfs.IsFifo or None) – a Guestfs.IsFifo containing optional arguments

Raises:

Returns:

the returned value, or -1 on error

Return type:

test if FIFO (named pipe)

This returns true if and only if there is a FIFO (named pipe) with the given path name.

If the optional flag followsymlinks is true, then a symlink (or chain of symlinks) that ends with a FIFO also causes the function to return true.

See also Guestfs.Session.stat().

New in version 1.5.10.

is_file(path, optargs)¶

Parameters:

path (str) –
optargs (Guestfs.IsFile or None) – a Guestfs.IsFile containing optional arguments

Raises:

Returns:

the returned value, or -1 on error

Return type:

test if a regular file

This returns true if and only if there is a regular file with the given path name. Note that it returns false for other objects like directories.

If the optional flag followsymlinks is true, then a symlink (or chain of symlinks) that ends with a file also causes the function to return true.

See also Guestfs.Session.stat().

New in version 0.8.

is_launching()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

is launching subprocess

This returns true iff this handle is launching the subprocess (in the LAUNCHING state).

For more information on states, see guestfs(3).

New in version 1.0.2.

is_lv(mountable)¶

Parameters:: mountable (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

test if mountable is a logical volume

This command tests whether mountable is a logical volume, and returns true iff this is the case.

New in version 1.5.3.

is_ready()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

is ready to accept commands

This returns true iff this handle is ready to accept commands (in the READY state).

For more information on states, see guestfs(3).

New in version 1.0.2.

is_socket(path, optargs)¶

Parameters:

path (str) –
optargs (Guestfs.IsSocket or None) – a Guestfs.IsSocket containing optional arguments

Raises:

Returns:

the returned value, or -1 on error

Return type:

test if socket

This returns true if and only if there is a Unix domain socket with the given path name.

If the optional flag followsymlinks is true, then a symlink (or chain of symlinks) that ends with a socket also causes the function to return true.

See also Guestfs.Session.stat().

New in version 1.5.10.

is_symlink(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

test if symbolic link

This returns true if and only if there is a symbolic link with the given path name.

See also Guestfs.Session.stat().

New in version 1.5.10.

is_whole_device(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

test if a device is a whole device

This returns true if and only if device refers to a whole block device. That is, not a partition or a logical device.

New in version 1.21.9.

is_zero(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

test if a file contains all zero bytes

This returns true iff the file exists and the file is empty or it contains all zero bytes.

New in version 1.11.8.

is_zero_device(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

test if a device contains all zero bytes

This returns true iff the device exists and contains all zero bytes.

Note that for large devices this can take a long time to run.

New in version 1.11.8.

isoinfo(isofile)¶

Parameters:: isofile (str) –
Raises:: GLib.Error
Returns:: a ISOInfo object, or None on error
Return type:: Guestfs.ISOInfo

get ISO information from primary volume descriptor of ISO file

This is the same as Guestfs.Session.isoinfo_device() except that it works for an ISO file located inside some other mounted filesystem. Note that in the common case where you have added an ISO file as a libguestfs device, you would *not* call this. Instead you would call Guestfs.Session.isoinfo_device().

New in version 1.17.19.

isoinfo_device(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: a ISOInfo object, or None on error
Return type:: Guestfs.ISOInfo

get ISO information from primary volume descriptor of device

device is an ISO device. This returns a struct of information read from the primary volume descriptor (the ISO equivalent of the superblock) of the device.

Usually it is more efficient to use the isoinfo(1) command with the *-d* option on the host to analyze ISO files, instead of going through libguestfs.

For information on the primary volume descriptor fields, see http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor

New in version 1.17.19.

journal_close()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

close the systemd journal

Close the journal handle.

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.23.11.

journal_get()¶

Raises:: GLib.Error
Returns:: an array of XAttr objects, or None on error
Return type:: [Guestfs.XAttr]

read the current journal entry

Read the current journal entry. This returns all the fields in the journal as a set of “(attrname, attrval)” pairs. The attrname is the field name (a string).

The attrval is the field value (a binary blob, often but not always a string). Please note that attrval is a byte array, *not* a \0-terminated C string.

The length of data may be truncated to the data threshold (see: Guestfs.Session.journal_set_data_threshold(), Guestfs.Session.journal_get_data_threshold()).

If you set the data threshold to unlimited (0) then this call can read a journal entry of any size, ie. it is not limited by the libguestfs protocol.

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.23.11.

journal_get_data_threshold()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get the data threshold for reading journal entries

Get the current data threshold for reading journal entries. This is a hint to the journal that it may truncate data fields to this size when reading them (note also that it may not truncate them). If this returns 0, then the threshold is unlimited.

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.23.11.

journal_get_realtime_usec()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

get the timestamp of the current journal entry

Get the realtime (wallclock) timestamp of the current journal entry.

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.27.18.

journal_next()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

move to the next journal entry

Move to the next journal entry. You have to call this at least once after opening the handle before you are able to read data.

The returned boolean tells you if there are any more journal records to read. true means you can read the next record (eg. using Guestfs.Session.journal_get()), and false means you have reached the end of the journal.

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.23.11.

journal_open(directory)¶

Parameters:: directory (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

open the systemd journal

Open the systemd journal located in directory. Any previously opened journal handle is closed.

The contents of the journal can be read using Guestfs.Session.journal_next() and Guestfs.Session.journal_get().

After you have finished using the journal, you should close the handle by calling Guestfs.Session.journal_close().

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.23.11.

journal_set_data_threshold(threshold)¶

Parameters:: threshold (int) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

set the data threshold for reading journal entries

Set the data threshold for reading journal entries. This is a hint to the journal that it may truncate data fields to this size when reading them (note also that it may not truncate them). If you set this to 0, then the threshold is unlimited.

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.23.11.

journal_skip(skip)¶

Parameters:: skip (int) –
Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

skip forwards or backwards in the journal

Skip forwards (“skip ≥ 0”) or backwards (“skip < 0”) in the journal.

The number of entries actually skipped is returned (note “rskip ≥ 0”). If this is not the same as the absolute value of the skip parameter (”|skip|”) you passed in then it means you have reached the end or the start of the journal.

This function depends on the feature “journal”. See also Guestfs.Session.feature_available().

New in version 1.23.11.

kill_subprocess()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

kill the hypervisor

This kills the hypervisor.

Do not call this. See: Guestfs.Session.shutdown() instead.

New in version 0.3.

Deprecated since version ???: In new code, use Guestfs.Session.shutdown() instead

launch()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

launch the backend

You should call this after configuring the handle (eg. adding drives) but before performing any actions.

Do not call Guestfs.Session.launch() twice on the same handle. Although it will not give an error (for historical reasons), the precise behaviour when you do this is not well defined. Handles are very cheap to create, so create a new one for each launch.

New in version 0.3.

lchown(owner, group, path)¶

Parameters:

owner (int) –
group (int) –
path (str) –

Raises:

Returns:

true on success, false on error

Return type:

change file owner and group

Change the file owner to owner and group to group. This is like Guestfs.Session.chown() but if path is a symlink then the link itself is changed, not the target.

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).

New in version 1.0.77.

ldmtool_create_all()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

scan and create Windows dynamic disk volumes

This function scans all block devices looking for Windows dynamic disk volumes and partitions, and creates devices for any that were found.

Call Guestfs.Session.list_ldm_volumes() and Guestfs.Session.list_ldm_partitions() to return all devices.

Note that you don’t normally need to call this explicitly, since it is done automatically at Guestfs.Session.launch() time.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_diskgroup_disks(diskgroup)¶

Parameters:: diskgroup (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

return the disks in a Windows dynamic disk group

Return the disks in a Windows dynamic disk group. The diskgroup parameter should be the GUID of a disk group, one element from the list returned by Guestfs.Session.ldmtool_scan().

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_diskgroup_name(diskgroup)¶

Parameters:: diskgroup (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

return the name of a Windows dynamic disk group

Return the name of a Windows dynamic disk group. The diskgroup parameter should be the GUID of a disk group, one element from the list returned by Guestfs.Session.ldmtool_scan().

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_diskgroup_volumes(diskgroup)¶

Parameters:: diskgroup (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

return the volumes in a Windows dynamic disk group

Return the volumes in a Windows dynamic disk group. The diskgroup parameter should be the GUID of a disk group, one element from the list returned by Guestfs.Session.ldmtool_scan().

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_remove_all()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

remove all Windows dynamic disk volumes

This is essentially the opposite of Guestfs.Session.ldmtool_create_all(). It removes the device mapper mappings for all Windows dynamic disk volumes

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_scan()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

scan for Windows dynamic disks

This function scans for Windows dynamic disks. It returns a list of identifiers (GUIDs) for all disk groups that were found. These identifiers can be passed to other “guestfs_ldmtool_*” functions.

This function scans all block devices. To scan a subset of block devices, call Guestfs.Session.ldmtool_scan_devices() instead.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_scan_devices(devices)¶

Parameters:: devices ([str]) – an array of strings
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

scan for Windows dynamic disks

This function scans for Windows dynamic disks. It returns a list of identifiers (GUIDs) for all disk groups that were found. These identifiers can be passed to other “guestfs_ldmtool_*” functions.

The parameter devices is a list of block devices which are scanned. If this list is empty, all block devices are scanned.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_volume_hint(diskgroup, volume)¶

Parameters:

diskgroup (str) –
volume (str) –

Raises:

Returns:

the returned string, or None on error

Return type:

str

return the hint field of a Windows dynamic disk volume

Return the hint field of the volume named volume in the disk group with GUID diskgroup. This may not be defined, in which case the empty string is returned. The hint field is often, though not always, the name of a Windows drive, eg. “E:”.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_volume_partitions(diskgroup, volume)¶

Parameters:

diskgroup (str) –
volume (str) –

Raises:

Returns:

an array of returned strings, or None on error

Return type:

return the partitions in a Windows dynamic disk volume

Return the list of partitions in the volume named volume in the disk group with GUID diskgroup.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

ldmtool_volume_type(diskgroup, volume)¶

Parameters:

diskgroup (str) –
volume (str) –

Raises:

Returns:

the returned string, or None on error

Return type:

str

return the type of a Windows dynamic disk volume

Return the type of the volume named volume in the disk group with GUID diskgroup.

Possible volume types that can be returned here include: simple, spanned, striped, mirrored, raid5. Other types may also be returned.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

lgetxattr(path, name)¶

Parameters:

path (str) –
name (str) –

Raises:

Returns:

an array of binary data, or None on error

Return type:

get a single extended attribute

Get a single extended attribute from file path named name. If path is a symlink, then this call returns an extended attribute from the symlink.

Normally it is better to get all extended attributes from a file in one go by calling Guestfs.Session.getxattrs(). However some Linux filesystem implementations are buggy and do not provide a way to list out attributes. For these filesystems (notably ntfs-3g) you have to know the names of the extended attributes you want in advance and call this function.

Extended attribute values are blobs of binary data. If there is no extended attribute named name, this returns an error.

See also: Guestfs.Session.lgetxattrs(), Guestfs.Session.getxattr(), attr(5).

This function depends on the feature “linuxxattrs”. See also Guestfs.Session.feature_available().

New in version 1.7.24.

lgetxattrs(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: an array of XAttr objects, or None on error
Return type:: [Guestfs.XAttr]

list extended attributes of a file or directory

This is the same as Guestfs.Session.getxattrs(), but if path is a symbolic link, then it returns the extended attributes of the link itself.

This function depends on the feature “linuxxattrs”. See also Guestfs.Session.feature_available().

New in version 1.0.59.

list_9p()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list 9p filesystems

This call does nothing and returns an error.

New in version 1.11.12.

Deprecated since version ???: There is no documented replacement

list_devices()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list the block devices

List all the block devices.

The full block device names are returned, eg. /dev/sda.

New in version 0.4.

list_disk_labels()¶

Raises:: GLib.Error
Returns:: a GLib.HashTable of results, or None on error
Return type:: {str: str}

mapping of disk labels to devices

If you add drives using the optional label parameter of guestfs_session_add_drive_opts(), you can use this call to map between disk labels, and raw block device and partition names (like /dev/sda and /dev/sda1).

This returns a hashtable, where keys are the disk labels (*without* the /dev/disk/guestfs prefix), and the values are the full raw block device and partition names (eg. /dev/sda and /dev/sda1).

New in version 1.19.49.

list_dm_devices()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list device mapper devices

List all device mapper devices.

The returned list contains /dev/mapper/* devices, eg. ones created by a previous call to Guestfs.Session.luks_open().

Device mapper devices which correspond to logical volumes are *not* returned in this list. Call Guestfs.Session.lvs() if you want to list logical volumes.

New in version 1.11.15.

list_filesystems()¶

Raises:: GLib.Error
Returns:: a GLib.HashTable of results, or None on error
Return type:: {str: str}

list filesystems

This inspection command looks for filesystems on partitions, block devices and logical volumes, returning a list of mountables containing filesystems and their type.

The return value is a hash, where the keys are the devices containing filesystems, and the values are the filesystem types. For example:

<![CDATA[“/dev/sda1” => “ntfs”]]>

<![CDATA[“/dev/sda2” => “ext2”]]>

<![CDATA[“/dev/vg_guest/lv_root” => “ext4”]]>

<![CDATA[“/dev/vg_guest/lv_swap” => “swap”]]>

The key is not necessarily a block device. It may also be an opaque ‘mountable’ string which can be passed to Guestfs.Session.mount().

The value can have the special value “unknown”, meaning the content of the device is undetermined or empty. “swap” means a Linux swap partition.

In libguestfs ≤ 1.36 this command ran other libguestfs commands, which might have included Guestfs.Session.mount() and Guestfs.Session.umount(), and therefore you had to use this soon after launch and only when nothing else was mounted. This restriction is removed in libguestfs ≥ 1.38.

Not all of the filesystems returned will be mountable. In particular, swap partitions are returned in the list. Also this command does not check that each filesystem found is valid and mountable, and some filesystems might be mountable but require special options. Filesystems may not all belong to a single logical operating system (use Guestfs.Session.inspect_os() to look for OSes).

New in version 1.5.15.

list_ldm_partitions()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list all Windows dynamic disk partitions

This function returns all Windows dynamic disk partitions that were found at launch time. It returns a list of device names.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

list_ldm_volumes()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list all Windows dynamic disk volumes

This function returns all Windows dynamic disk volumes that were found at launch time. It returns a list of device names.

This function depends on the feature “ldm”. See also Guestfs.Session.feature_available().

New in version 1.20.0.

list_md_devices()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list Linux md (RAID) devices

List all Linux md devices.

New in version 1.15.4.

list_partitions()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list the partitions

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 Guestfs.Session.lvs().

New in version 0.4.

ll(directory)¶

Parameters:: directory (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

list the files in a directory (long format)

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.

New in version 0.4.

llz(directory)¶

Parameters:: directory (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

list the files in a directory (long format with SELinux contexts)

List the files in directory in the format of “ls -laZ”.

This command is mostly useful for interactive sessions. It is *not* intended that you try to parse the output string.

New in version 1.17.6.

Deprecated since version ???: In new code, use Guestfs.Session.lgetxattrs() instead

ln(target, linkname)¶

Parameters:

target (str) –
linkname (str) –

Raises:

Returns:

true on success, false on error

Return type:

create a hard link

This command creates a hard link.

New in version 1.0.66.

ln_f(target, linkname)¶

Parameters:

target (str) –
linkname (str) –

Raises:

Returns:

true on success, false on error

Return type:

create a hard link

This command creates a hard link, removing the link linkname if it exists already.

New in version 1.0.66.

ln_s(target, linkname)¶

Parameters:

target (str) –
linkname (str) –

Raises:

Returns:

true on success, false on error

Return type:

create a symbolic link

This command creates a symbolic link using the “ln -s” command.

New in version 1.0.66.

ln_sf(target, linkname)¶

Parameters:

target (str) –
linkname (str) –

Raises:

Returns:

true on success, false on error

Return type:

create a symbolic link

This command creates a symbolic link using the “ln -sf” command, The *-f* option removes the link (linkname) if it exists already.

New in version 1.0.66.

lremovexattr(xattr, path)¶

Parameters:

xattr (str) –
path (str) –

Raises:

Returns:

true on success, false on error

Return type:

remove extended attribute of a file or directory

This is the same as Guestfs.Session.removexattr(), but if path is a symbolic link, then it removes an extended attribute of the link itself.

This function depends on the feature “linuxxattrs”. See also Guestfs.Session.feature_available().

New in version 1.0.59.

ls(directory)¶

Parameters:: directory (str) –
Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list the files in a directory

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.

New in version 0.4.

ls0(dir, filenames)¶

Parameters:

dir (str) –
filenames (str) –

Raises:

Returns:

true on success, false on error

Return type:

get list of files in a directory

This specialized command is used to get a listing of the filenames in the directory dir. The list of filenames is written to the local file filenames (on the host).

In the output file, the filenames are separated by “\0” characters.

“.” and “..” are not returned. The filenames are not sorted.

New in version 1.19.32.

lsetxattr(xattr, val, vallen, path)¶

Parameters:

xattr (str) –
val (str) –
vallen (int) –
path (str) –

Raises:

Returns:

true on success, false on error

Return type:

set extended attribute of a file or directory

This is the same as Guestfs.Session.setxattr(), but if path is a symbolic link, then it sets an extended attribute of the link itself.

This function depends on the feature “linuxxattrs”. See also Guestfs.Session.feature_available().

New in version 1.0.59.

lstat(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: a Stat object, or None on error
Return type:: Guestfs.Stat

get file information for a symbolic link

Returns file information for the given path.

This is the same as Guestfs.Session.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.

New in version 1.9.2.

Deprecated since version ???: In new code, use Guestfs.Session.lstatns() instead

lstatlist(path, names)¶

Parameters:

path (str) –
names ([str]) – an array of strings

Raises:

Returns:

an array of Stat objects, or None on error

Return type:

[Guestfs.Stat]

lstat on multiple files

This call allows you to perform the Guestfs.Session.lstat() operation on multiple files, where all files are in the directory path. names is the list of files from this directory.

On return you get a list of stat structs, with a one-to-one correspondence to the names list. If any name did not exist or could not be lstat’d, then the st_ino field of that structure is set to @-1.

This call is intended for programs that want to efficiently list a directory contents without making many round-trips. See also Guestfs.Session.lxattrlist() for a similarly efficient call for getting extended attributes.

New in version 1.0.77.

Deprecated since version ???: In new code, use Guestfs.Session.lstatnslist() instead

lstatns(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: a StatNS object, or None on error
Return type:: Guestfs.StatNS

get file information for a symbolic link

Returns file information for the given path.

This is the same as Guestfs.Session.statns() 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.

New in version 1.27.53.

lstatnslist(path, names)¶

Parameters:

path (str) –
names ([str]) – an array of strings

Raises:

Returns:

an array of StatNS objects, or None on error

Return type:

[Guestfs.StatNS]

lstat on multiple files

This call allows you to perform the Guestfs.Session.lstatns() operation on multiple files, where all files are in the directory path. names is the list of files from this directory.

On return you get a list of stat structs, with a one-to-one correspondence to the names list. If any name did not exist or could not be lstat’d, then the st_ino field of that structure is set to @-1.

This call is intended for programs that want to efficiently list a directory contents without making many round-trips. See also Guestfs.Session.lxattrlist() for a similarly efficient call for getting extended attributes.

New in version 1.27.53.

luks_add_key(device, key, newkey, keyslot)¶

Parameters:

device (str) –
key (str) –
newkey (str) –
keyslot (int) –

Raises:

Returns:

true on success, false on error

Return type:

add a key on a LUKS encrypted device

This command adds a new key on LUKS device device. key is any existing key, and is used to access the device. newkey is the new key to add. keyslot is the key slot that will be replaced.

Note that if keyslot already contains a key, then this command will fail. You have to use Guestfs.Session.luks_kill_slot() first to remove that key.

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.5.2.

luks_close(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

close a LUKS device

This closes a LUKS device that was created earlier by Guestfs.Session.luks_open() or Guestfs.Session.luks_open_ro(). The device parameter must be the name of the LUKS mapping device (ie. /dev/mapper/mapname) and *not* the name of the underlying block device.

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.5.1.

Deprecated since version ???: In new code, use Guestfs.Session.cryptsetup_close() instead

luks_format(device, key, keyslot)¶

Parameters:

device (str) –
key (str) –
keyslot (int) –

Raises:

Returns:

true on success, false on error

Return type:

format a block device as a LUKS encrypted device

This command erases existing data on device and formats the device as a LUKS encrypted device. key is the initial key, which is added to key slot keyslot. (LUKS supports 8 key slots, numbered 0-7).

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.5.2.

luks_format_cipher(device, key, keyslot, cipher)¶

Parameters:

device (str) –
key (str) –
keyslot (int) –
cipher (str) –

Raises:

Returns:

true on success, false on error

Return type:

format a block device as a LUKS encrypted device

This command is the same as Guestfs.Session.luks_format() but it also allows you to set the cipher used.

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.5.2.

luks_kill_slot(device, key, keyslot)¶

Parameters:

device (str) –
key (str) –
keyslot (int) –

Raises:

Returns:

true on success, false on error

Return type:

remove a key from a LUKS encrypted device

This command deletes the key in key slot keyslot from the encrypted LUKS device device. key must be one of the *other* keys.

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.5.2.

luks_open(device, key, mapname)¶

Parameters:

device (str) –
key (str) –
mapname (str) –

Raises:

Returns:

true on success, false on error

Return type:

open a LUKS-encrypted block device

This command opens a block device which has been encrypted according to the Linux Unified Key Setup (LUKS) standard.

device is the encrypted block device or partition.

The caller must supply one of the keys associated with the LUKS block device, in the key parameter.

This creates a new block device called /dev/mapper/mapname. Reads and writes to this block device are decrypted from and encrypted to the underlying device respectively.

If this block device contains LVM volume groups, then calling Guestfs.Session.lvm_scan() with the activate parameter true will make them visible.

Use Guestfs.Session.list_dm_devices() to list all device mapper devices.

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.5.1.

Deprecated since version ???: In new code, use Guestfs.Session.cryptsetup_open() instead

luks_open_ro(device, key, mapname)¶

Parameters:

device (str) –
key (str) –
mapname (str) –

Raises:

Returns:

true on success, false on error

Return type:

open a LUKS-encrypted block device read-only

This is the same as Guestfs.Session.luks_open() except that a read-only mapping is created.

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.5.1.

Deprecated since version ???: In new code, use Guestfs.Session.cryptsetup_open() instead

luks_uuid(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the UUID of a LUKS device

This returns the UUID of the LUKS device device.

This function depends on the feature “luks”. See also Guestfs.Session.feature_available().

New in version 1.41.9.

lvcreate(logvol, volgroup, mbytes)¶

Parameters:

logvol (str) –
volgroup (str) –
mbytes (int) –

Raises:

Returns:

true on success, false on error

Return type:

create an LVM logical volume

This creates an LVM logical volume called logvol on the volume group volgroup, with size megabytes.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 0.8.

lvcreate_free(logvol, volgroup, percent)¶

Parameters:

logvol (str) –
volgroup (str) –
percent (int) –

Raises:

Returns:

true on success, false on error

Return type:

create an LVM logical volume in % remaining free space

Create an LVM logical volume called /dev/volgroup/logvol, using approximately percent % of the free space remaining in the volume group. Most usefully, when percent is 100 this will create the largest possible LV.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 1.17.18.

lvm_canonical_lv_name(lvname)¶

Parameters:: lvname (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get canonical name of an LV

This converts alternative naming schemes for LVs that you might find to the canonical name. For example, /dev/mapper/VG-LV is converted to /dev/VG/LV.

This command returns an error if the lvname parameter does not refer to a logical volume. In this case errno will be set to EINVAL.

New in version 1.5.24.

lvm_clear_filter()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

clear LVM device filter

This undoes the effect of Guestfs.Session.lvm_set_filter(). LVM will be able to see every block device.

This command also clears the LVM cache and performs a volume group scan.

New in version 1.5.1.

lvm_remove_all()¶

Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

remove all LVM LVs, VGs and PVs

This command removes all LVM logical volumes, volume groups and physical volumes.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 0.8.

lvm_scan(activate)¶

Parameters:: activate (bool) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

scan for LVM physical volumes, volume groups and logical volumes

This scans all block devices and rebuilds the list of LVM physical volumes, volume groups and logical volumes.

If the activate parameter is true then newly found volume groups and logical volumes are activated, meaning the LV /dev/VG/LV devices become visible.

When a libguestfs handle is launched it scans for existing devices, so you do not normally need to use this API. However it is useful when you have added a new device or deleted an existing device (such as when the Guestfs.Session.luks_open() API is used).

New in version 1.39.8.

lvm_set_filter(devices)¶

Parameters:: devices ([str]) – an array of strings
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

set LVM device filter

This sets the LVM device filter so that LVM will only be able to “see” the block devices in the list devices, and will ignore all other attached block devices.

Where disk image(s) contain duplicate PVs or VGs, this command is useful to get LVM to ignore the duplicates, otherwise LVM can get confused. Note also there are two types of duplication possible: either cloned PVs/VGs which have identical UUIDs; or VGs that are not cloned but just happen to have the same name. In normal operation you cannot create this situation, but you can do it outside LVM, eg. by cloning disk images or by bit twiddling inside the LVM metadata.

This command also clears the LVM cache and performs a volume group scan.

You can filter whole block devices or individual partitions.

You cannot use this if any VG is currently in use (eg. contains a mounted filesystem), even if you are not filtering out that VG.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 1.5.1.

lvremove(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

remove an LVM logical volume

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.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 1.0.13.

lvrename(logvol, newlogvol)¶

Parameters:

logvol (str) –
newlogvol (str) –

Raises:

Returns:

true on success, false on error

Return type:

rename an LVM logical volume

Rename a logical volume logvol with the new name newlogvol.

New in version 1.0.83.

lvresize(device, mbytes)¶

Parameters:

device (str) –
mbytes (int) –

Raises:

Returns:

true on success, false on error

Return type:

resize an LVM logical volume

This resizes (expands or shrinks) an existing LVM logical volume to mbytes. When reducing, data in the reduced part is lost.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 1.0.27.

lvresize_free(lv, percent)¶

Parameters:

lv (str) –
percent (int) –

Raises:

Returns:

true on success, false on error

Return type:

expand an LV to fill free space

This expands an existing logical volume lv so that it fills pc % of the remaining free space in the volume group. Commonly you would call this with pc = 100 which expands the logical volume as much as possible, using all remaining free space in the volume group.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 1.3.3.

lvs()¶

Raises:: GLib.Error
Returns:: an array of returned strings, or None on error
Return type:: [str]

list the LVM logical volumes (LVs)

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).

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 0.4.

lvs_full()¶

Raises:: GLib.Error
Returns:: an array of LV objects, or None on error
Return type:: [Guestfs.LV]

list the LVM logical volumes (LVs)

List all the logical volumes detected. This is the equivalent of the lvs(8) command. The “full” version includes all fields.

This function depends on the feature “lvm2”. See also Guestfs.Session.feature_available().

New in version 0.4.

lvuuid(device)¶

Parameters:: device (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

get the UUID of a logical volume

This command returns the UUID of the LVM LV device.

New in version 1.0.87.

lxattrlist(path, names)¶

Parameters:

path (str) –
names ([str]) – an array of strings

Raises:

Returns:

an array of XAttr objects, or None on error

Return type:

[Guestfs.XAttr]

lgetxattr on multiple files

This call allows you to get the extended attributes of multiple files, where all files are in the directory path. names is the list of files from this directory.

On return you get a flat list of xattr structs which must be interpreted sequentially. The first xattr struct always has a zero-length attrname. attrval in this struct is zero-length to indicate there was an error doing Guestfs.Session.lgetxattr() for this file, *or* is a C string which is a decimal number (the number of following attributes for this file, which could be “0”). Then after the first xattr struct are the zero or more attributes for the first named file. This repeats for the second and subsequent files.

This call is intended for programs that want to efficiently list a directory contents without making many round-trips. See also Guestfs.Session.lstatlist() for a similarly efficient call for getting standard stats.

This function depends on the feature “linuxxattrs”. See also Guestfs.Session.feature_available().

New in version 1.0.77.

max_disks()¶

Raises:: GLib.Error
Returns:: the returned value, or -1 on error
Return type:: int

maximum number of disks that may be added

Return the maximum number of disks that may be added to a handle (eg. by guestfs_session_add_drive_opts() and similar calls).

This function was added in libguestfs 1.19.7. In previous versions of libguestfs the limit was 25.

See “MAXIMUM NUMBER OF DISKS” in guestfs(3) for additional information on this topic.

New in version 1.19.7.

md_create(name, devices, optargs)¶

Parameters:

name (str) –
devices ([str]) – an array of strings
optargs (Guestfs.MDCreate or None) – a Guestfs.MDCreate containing optional arguments

Raises:

Returns:

true on success, false on error

Return type:

create a Linux md (RAID) device

Create a Linux md (RAID) device named name on the devices in the list devices.

The optional parameters are:

missingbitmap A bitmap of missing devices. If a bit is set it means that a missing device is added to the array. The least significant bit corresponds to the first device in the array.

As examples:

If “devices = [“/dev/sda”]” and “missingbitmap = 0x1” then the resulting array would be “[<missing>, “/dev/sda”]”.

If “devices = [“/dev/sda”]” and “missingbitmap = 0x2” then the resulting array would be “[“/dev/sda”, <missing>]”.

This defaults to 0 (no missing devices).

The length of devices + the number of bits set in missingbitmap must equal nrdevices + spare.

nrdevices The number of active RAID devices.

If not set, this defaults to the length of devices plus the number of bits set in missingbitmap.

spare The number of spare devices.

If not set, this defaults to 0.

chunk The chunk size in bytes.

The chunk parameter does not make sense, and should not be specified, when level is raid1 (which is the default; see below).

level The RAID level, which can be one of: linear, raid0, 0, stripe, raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10. Some of these are synonymous, and more levels may be added in future.

If not set, this defaults to raid1.

This function depends on the feature “mdadm”. See also Guestfs.Session.feature_available().

New in version 1.15.6.

md_detail(md)¶

Parameters:: md (str) –
Raises:: GLib.Error
Returns:: a GLib.HashTable of results, or None on error
Return type:: {str: str}

obtain metadata for an MD device

This command exposes the output of “mdadm -DY <md>”. The following fields are usually present in the returned hash. Other fields may also be present.

level The raid level of the MD device.

devices The number of underlying devices in the MD device.

metadata The metadata version used.

uuid The UUID of the MD device.

name The name of the MD device.

This function depends on the feature “mdadm”. See also Guestfs.Session.feature_available().

New in version 1.15.6.

md_stat(md)¶

Parameters:: md (str) –
Raises:: GLib.Error
Returns:: an array of MDStat objects, or None on error
Return type:: [Guestfs.MDStat]

get underlying devices from an MD device

This call returns a list of the underlying devices which make up the single software RAID array device md.

To get a list of software RAID devices, call Guestfs.Session.list_md_devices().

Each structure returned corresponds to one device along with additional status information:

mdstat_device The name of the underlying device.

mdstat_index The index of this device within the array.

mdstat_flags Flags associated with this device. This is a string containing (in no specific order) zero or more of the following flags:

W write-mostly

F device is faulty

S device is a RAID spare

R replacement

This function depends on the feature “mdadm”. See also Guestfs.Session.feature_available().

New in version 1.17.21.

md_stop(md)¶

Parameters:: md (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

stop a Linux md (RAID) device

This command deactivates the MD array named md. The device is stopped, but it is not destroyed or zeroed.

This function depends on the feature “mdadm”. See also Guestfs.Session.feature_available().

New in version 1.15.6.

mkdir(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

create a directory

Create a directory named path.

New in version 0.8.

mkdir_mode(path, mode)¶

Parameters:

path (str) –
mode (int) –

Raises:

Returns:

true on success, false on error

Return type:

create a directory with a particular mode

This command creates a directory, setting the initial permissions of the directory to mode.

For common Linux filesystems, the actual mode which is set will be “mode & ~umask & 01777”. Non-native-Linux filesystems may interpret the mode in other ways.

New in version 1.0.77.

mkdir_p(path)¶

Parameters:: path (str) –
Raises:: GLib.Error
Returns:: true on success, false on error
Return type:: bool

create a directory and parents

Create a directory named path, creating any parent directories as necessary. This is like the “mkdir -p” shell command.

New in version 0.8.

mkdtemp(tmpl)¶

Parameters:: tmpl (str) –
Raises:: GLib.Error
Returns:: the returned string, or None on error
Return type:: str

create a temporary directory

This command creates a temporary directory. The tmpl parameter should be a full pathname for the temporary directory name with the final six characters being “XXXXXX”.

For example: “/tmp/myprogXXXXXX” or “/Temp/myprogXXXXXX”, the second one being suitable for Windows filesystems.

The name of the temporary directory that was created is returned.

The temporary directory is created with mode 0700 and is owned by root.

The caller is responsible for deleting the temporary directory and its contents after use.

Signal Details¶

Guestfs.Session.signals.appliance(session, params)¶

Signal Name:

appliance

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
params (Guestfs.SessionEventParams) – An object containing event parameters

See “SETTING CALLBACKS TO HANDLE EVENTS” in guestfs(3) for more details about this event.

Guestfs.Session.signals.close(session, params)¶

Signal Name:

close

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
params (Guestfs.SessionEventParams) – An object containing event parameters

See “SETTING CALLBACKS TO HANDLE EVENTS” in guestfs(3) for more details about this event.

Guestfs.Session.signals.enter(session, params)¶

Signal Name:

enter

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
params (Guestfs.SessionEventParams) – An object containing event parameters

See “SETTING CALLBACKS TO HANDLE EVENTS” in guestfs(3) for more details about this event.

Guestfs.Session.signals.launch_done(session, object)¶

Signal Name:

launch-done

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
object (Guestfs.SessionEventParams) –

Guestfs.Session.signals.library(session, params)¶

Signal Name:

library

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
params (Guestfs.SessionEventParams) – An object containing event parameters

See “SETTING CALLBACKS TO HANDLE EVENTS” in guestfs(3) for more details about this event.

Guestfs.Session.signals.libvirt_auth(session, object)¶

Signal Name:

libvirt-auth

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
object (Guestfs.SessionEventParams) –

Guestfs.Session.signals.progress(session, params)¶

Signal Name:

progress

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
params (Guestfs.SessionEventParams) – An object containing event parameters

See “SETTING CALLBACKS TO HANDLE EVENTS” in guestfs(3) for more details about this event.

Guestfs.Session.signals.subprocess_quit(session, object)¶

Signal Name:

subprocess-quit

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
object (Guestfs.SessionEventParams) –

Guestfs.Session.signals.trace(session, params)¶

Signal Name:

trace

Flags:

Parameters:

session (Guestfs.Session) – The object which received the signal
params (Guestfs.SessionEventParams) – An object containing event parameters

See “SETTING CALLBACKS TO HANDLE EVENTS” in guestfs(3) for more details about this event.

Guestfs.Session.signals.warning(session, params)¶

Signal Name:

warning

Flags: