Class Session

This function deletes the default POSIX Access Control List (ACL) attached to directory dir.

This function depends on the feature "acl". See also guestfs_session_feature_available().

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

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:

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

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

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 http://libvirt.org/remote.html ) will fail unless those disks are accessible via the same device path locally too.

The optional libvirturi parameter sets the libvirt URI (see http://libvirt.org/uri.html ). 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 controls whether this call will try to connect to a running virtual machine guestfsd process if it sees a suitable <channel> element in the libvirt XML definition. The default (if the flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS" in guestfs(3) for more information.

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.

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

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.

In libguestfs ≥ 1.20 you can also call this function after launch (with some restrictions). This is called "hotplugging". When hotplugging, you must specify a label so that the new disk gets a predictable name. For more information see "HOTPLUGGING" in guestfs(3).

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 "NULL 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 RHBZ#642934 . 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 The name the drive had in the original guest, e.g. /dev/sdb. This is used as a hint to the guest inspection process if it is available.

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: "GLUSTER" in guestfs(3)

"protocol = "iscsi"" Connect to the iSCSI server. The server parameter must also be supplied - see below. The username parameter may be supplied. See below. The secret parameter may be supplied. See below.

See also: "ISCSI" in guestfs(3).

"protocol = "nbd"" Connect to the Network Block Device server. The server parameter must also be supplied - see below.

See also: "NETWORK BLOCK DEVICE" in guestfs(3).

"protocol = "rbd"" Connect to the Ceph (librbd/RBD) server. The server parameter must also be supplied - see below. The username parameter may be supplied. See below. The secret parameter may be supplied. See below.

See also: "CEPH" in guestfs(3).

"protocol = "sheepdog"" Connect to the Sheepdog server. The server parameter may also be supplied - see below.

See also: "SHEEPDOG" in guestfs(3).

"protocol = "ssh"" Connect to the Secure Shell (ssh) server.

The server parameter must be supplied. The username parameter may be supplied. See below.

See also: "SSH" in guestfs(3).

server For protocols which require access to a remote server, this is a list of server(s).

Each list element is a string specifying a server. The string must be in one of the following formats:

If the port number is omitted, then the standard port number for the protocol is used (see /etc/services).

username For the ftp, ftps, http, https, iscsi, rbd, ssh and tftp protocols, this specifies the remote username.

If not given, then the local username is used for ssh, and no authentication is attempted for ceph. But note this sometimes may give unexpected results, for example if using the libvirt backend and if the libvirt backend is configured to start the qemu appliance as a special user such as "qemu.qemu". If in doubt, specify the remote username you want.

secret For the rbd protocol only, this specifies the ‘secret’ to use when connecting to the remote device. It must be base64 encoded.

If not given, then a secret matching the given username will be looked up in the default keychain locations, or if no username is given, then no authentication will be used.

cachemode Choose whether or not libguestfs will obey sync operations (safe but slow) or not (unsafe but fast). The possible values for this string are:

"cachemode = "writeback"" This is the default.

Write operations in the API do not return until a write(2) call has completed in the host [but note this does not imply that anything gets written to disk].

Sync operations in the API, including implicit syncs caused by filesystem journalling, will not return until an fdatasync(2) call has completed in the host, indicating that data has been committed to disk.

"cachemode = "unsafe"" In this mode, there are no guarantees. Libguestfs may cache anything and ignore sync requests. This is suitable only for scratch or temporary disks.

discard Enable or disable discard (a.k.a. trim or unmap) support on this drive. If enabled, operations such as guestfs_session_fstrim() will be able to discard / make thin / punch holes in the underlying host file or device.

Possible discard settings are:

"discard = "disable"" Disable discard support. This is the default.

"discard = "enable"" Enable discard support. Fail if discard is not possible.

"discard = "besteffort"" Enable discard support if possible, but don't fail if it is not supported.

Since not all backends and not all underlying systems support discard, this is a good choice if you want to use discard if possible, but don't mind if it doesn't work.

copyonread The boolean parameter copyonread enables copy-on-read support. This only affects disk formats which have backing files, and causes reads to be stored in the overlay layer, speeding up multiple reads of the same area of disk.

The default is false.

This function is the equivalent of calling guestfs_session_add_drive_opts() with the optional parameter GUESTFS_ADD_DRIVE_OPTS_READONLY set to 1, so the disk is added read-only, with the format being detected automatically.

This is the same as guestfs_session_add_drive_ro() but it allows you to specify the QEMU interface emulation to use at run time.

This command adds a temporary scratch drive to the handle. The size parameter is the virtual size (in bytes). The scratch drive is blank initially (all reads return zeroes until you start writing to it). The drive is deleted when the handle is closed.

The optional arguments name and label are passed through to guestfs_session_add_drive().

This is the same as guestfs_session_add_drive() but it allows you to specify the QEMU interface emulation to use at run time.

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

In the C API we declare "void *dom", but really it has type "virDomainPtr dom". This is so we don't need <libvirt.h>.

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 http://libvirt.org/remote.html ) will fail unless those disks are accessible via the same device path locally too.

The optional live flag controls whether this call will try to connect to a running virtual machine guestfsd process if it sees a suitable <channel> element in the libvirt XML definition. The default (if the flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS" in guestfs(3) for more information.

The optional readonlydisk parameter controls what we do for disks which are marked <readonly/> in the libvirt XML. See guestfs_session_add_domain() for possible values.

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

Set the value associated with path to NULL. This is the same as the augtool(1) clear command.

Close the current Augeas handle and free up any resources used by it. After calling this, you have to call guestfs_session_aug_init() again before you can use any other Augeas functions.

Defines a variable name whose value is the result of evaluating expr.

If expr evaluates to an empty nodeset, a node is created, equivalent to calling guestfs_session_aug_set() expr, value. name will be the nodeset containing that single node.

On success this returns a pair containing the number of nodes in the nodeset, and a boolean flag if a node was created.

Defines an Augeas variable name whose value is the result of evaluating expr. If expr is NULL, then name is undefined.

On success this returns the number of nodes in expr, or 0 if expr evaluates to something which is not a nodeset.

Look up the value associated with path. If path matches exactly one node, the value is returned.

Create a new Augeas handle for editing configuration files. If there was any previous Augeas handle associated with this guestfs session, then it is closed.

You must call this before using any other "guestfs_aug_*" commands.

root is the filesystem root. root must not be NULL, use / instead.

The flags are the same as the flags defined in <augeas.h>, the logical or of the following integers:

AUG_SAVE_BACKUP = 1 Keep the original file with a ".augsave" extension.

AUG_SAVE_NEWFILE = 2 Save changes into a file with extension ".augnew", and do not overwrite original. Overrides AUG_SAVE_BACKUP.

AUG_TYPE_CHECK = 4 Typecheck lenses.

This option is only useful when debugging Augeas lenses. Use of this option may require additional memory for the libguestfs appliance. You may need to set the LIBGUESTFS_MEMSIZE environment variable or call guestfs_session_set_memsize().

AUG_NO_STDINC = 8 Do not use standard load path for modules.

AUG_SAVE_NOOP = 16 Make save a no-op, just record what would have been changed.

AUG_NO_LOAD = 32 Do not load the tree in guestfs_session_aug_init().

To close the handle, you can call guestfs_session_aug_close().

To find out more about Augeas, see http://augeas.net/ .

Create a new sibling label for path, inserting it into the tree before or after path (depending on the boolean flag before).

path must match exactly one existing node in the tree, and label must be a label, ie. not contain /, "*" or end with a bracketed index "[N]".

The label (name of the last element) of the Augeas path expression augpath is returned. augpath must match exactly one node, else this function returns an error.

Load files into the tree.

See aug_load in the Augeas documentation for the full gory details.

This is just a shortcut for listing guestfs_session_aug_match() "path/*" and sorting the resulting nodes into alphabetical order.

Returns a list of paths which match the path expression path. The returned paths are sufficiently qualified so that they match exactly one node in the current tree.

Move the node src to dest. src must match exactly one node. dest is overwritten if it exists.

Remove path and all of its children.

On success this returns the number of entries which were removed.

This writes all pending changes to disk.

The flags which were passed to guestfs_session_aug_init() affect exactly how files are saved.

Set the value associated with path to val.

In the Augeas API, it is possible to clear a node by setting the value to NULL. Due to an oversight in the libguestfs API you cannot do that with this call. Instead you must use the guestfs_session_aug_clear() call.

Change multiple Augeas nodes in a single operation. base is an expression matching multiple nodes. sub is a path expression relative to base. All nodes matching base are found, and then for each node, sub is changed to val. sub may also be NULL in which case the base nodes are modified.

This returns the number of nodes modified.

Add an Augeas transformation for the specified lens so it can handle file.

If remove is true (false by default), then the transformation is removed.

This command is used to check the availability of some groups of functionality in the appliance, which not all builds of the libguestfs appliance will be able to provide.

The libguestfs groups, and the functions that those groups correspond to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch this list at runtime by calling guestfs_session_available_all_groups().

The argument groups is a list of group names, eg: "["inotify", "augeas"]" would check for the availability of the Linux inotify functions and Augeas (configuration file editing) functions.

The command returns no error if all requested groups are available.

It fails with an error if one or more of the requested groups is unavailable in the appliance.

If an unknown group name is included in the list of groups then an error is always returned.

Notes:

• guestfs_session_feature_available() is the same as this call, but with a slightly simpler to use API: that call returns a boolean true/false instead of throwing an error.

• You must call guestfs_session_launch() before calling this function.

The reason is because we don't know what groups are supported by the appliance/daemon until it is running and can be queried.

• If a group of functions is available, this does not necessarily mean that they will work. You still have to check for errors when calling individual API functions even if they are available.

• It is usually the job of distro packagers to build complete functionality into the libguestfs appliance. Upstream libguestfs, if built from source with all requirements satisfied, will support everything.

• This call was added in version 1.0.80. In previous versions of libguestfs all you could do would be to speculatively execute a command to find out if the daemon implemented it. See also guestfs_session_version().

See also guestfs_session_filesystem_available().

This command returns a list of all optional groups that this daemon knows about. Note this returns both supported and unsupported groups. To find out which ones the daemon can actually support you have to call guestfs_session_available() / guestfs_session_feature_available() on each member of the returned list.

See also guestfs_session_available(), guestfs_session_feature_available() and "AVAILABILITY" in guestfs(3).

This command uploads base64-encoded data from base64file to filename.

This command downloads the contents of filename, writing it out to local file base64file encoded as base64.

This discards all blocks on the block device device, giving the free space back to the host.

This operation requires support in libguestfs, 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. You must also set the discard attribute on the underlying drive (see guestfs_session_add_drive_opts()).

This function depends on the feature "blkdiscard". See also guestfs_session_feature_available().

This call returns true if blocks on device that have been discarded by a call to guestfs_session_blkdiscard() are returned as blocks of zero bytes when read the next time.

If it returns false, then it may be that discarded blocks are read as stale or random data.

This function depends on the feature "blkdiscardzeroes". See also guestfs_session_feature_available().

This command returns block device attributes for device. The following fields are usually present in the returned hash. Other fields may also be present.

UUID The uuid of this device.

LABEL The label of this device.

VERSION The version of blkid command.

TYPE The filesystem type or RAID of this device.

USAGE The usage of this device, for example filesystem or raid.

This tells the kernel to flush internal buffers associated with device.

This uses the blockdev(8) command.

This returns the block size of a device.

Note: this is different from both size in blocks and filesystem block size. Also this setting is not really used by anything. You should probably not use it for anything. Filesystems have their own idea about what block size to choose.

This uses the blockdev(8) command.

Returns a boolean indicating if the block device is read-only (true if read-only, false if not).

This uses the blockdev(8) command.

This returns the size of the device in bytes.

See also guestfs_session_blockdev_getsz().

This uses the blockdev(8) command.

This returns the size of sectors on a block device. Usually 512, but can be larger for modern devices.

(Note, this is not the size in sectors, use guestfs_session_blockdev_getsz() for that).

This uses the blockdev(8) command.

This returns the size of the device in units of 512-byte sectors (even if the sectorsize isn't 512 bytes ... weird).

See also guestfs_session_blockdev_getss() for the real sector size of the device, and guestfs_session_blockdev_getsize64() for the more useful size in bytes.

This uses the blockdev(8) command.

Reread the partition table on device.

This uses the blockdev(8) command.

This call does nothing and has never done anything because of a bug in blockdev. Do not use it.

If you need to set the filesystem block size, use the blocksize option of guestfs_session_mkfs().

Set readahead (in 512-byte sectors) for the device.

This uses the blockdev(8) command.

Sets the block device named device to read-only.

This uses the blockdev(8) command.

Sets the block device named device to read-write.

This uses the blockdev(8) command.

Cancel a running balance on a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Pause a running balance on a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Resume a paused balance on a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Show the status of a running or paused balance on a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Add the list of device(s) in devices to the btrfs filesystem mounted at fs. If devices is an empty list, this does nothing.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Remove the devices from the btrfs filesystem mounted at fs. If devices is an empty list, this does nothing.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Balance the chunks in the btrfs filesystem mounted at fs across the underlying devices.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Defragment a file or directory on a btrfs filesystem. compress is one of zlib or lzo.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

This command resizes a btrfs filesystem.

Note that unlike other resize calls, the filesystem has to be mounted and the parameter is the mountpoint not the device (this is a requirement of btrfs itself).

The optional parameters are:

size The new size (in bytes) of the filesystem. If omitted, the filesystem is resized to the maximum size.

See also btrfs(8).

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Show all the devices where the filesystems in device is spanned over.

If not all the devices for the filesystems are present, then this function fails and the errno is set to ENODEV.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Force sync on the btrfs filesystem mounted at fs.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Used to check a btrfs filesystem, device is the device file where the filesystem is stored.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

This is used to create an image of a btrfs filesystem. All data will be zeroed, but metadata and the like is preserved.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Add qgroup src to parent qgroup dst. This command can group several qgroups into a parent qgroup to share common limit.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Create a quota group (qgroup) for subvolume at subvolume.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Destroy a quota group.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Limit the size of the subvolume with path subvolume.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Remove qgroup src from the parent qgroup dst.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Show all subvolume quota groups in a btrfs filesystem, including their usages.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Enable or disable subvolume quota support for filesystem which contains path.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Trash all qgroup numbers and scan the metadata again with the current config.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Replace device of a btrfs filesystem. On a live filesystem, duplicate the data to the target device which is currently stored on the source device. After completion of the operation, the source device is wiped out and removed from the filesystem.

The targetdev needs to be same size or larger than the srcdev. Devices which are currently mounted are never allowed to be used as the targetdev.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Recover the chunk tree of btrfs filesystem by scanning the devices one by one.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Recover bad superblocks from good copies.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Cancel a running scrub on a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Resume a previously canceled or interrupted scrub on a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Reads all the data and metadata on the filesystem, and uses checksums and the duplicate copies from RAID storage to identify and repair any corrupt data.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Show status of running or finished scrub on a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Enable or disable the seeding feature of a device that contains a btrfs filesystem.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Create a btrfs subvolume. The dest argument is the destination directory and the name of the subvolume, in the form /path/to/dest/name. The optional parameter qgroupid represents the qgroup which the newly created subvolume will be added to.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Delete the named btrfs subvolume or snapshot.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Get the default subvolume or snapshot of a filesystem mounted at mountpoint.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

List the btrfs snapshots and subvolumes of the btrfs filesystem which is mounted at fs.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Set the subvolume of the btrfs filesystem fs which will be mounted by default. See guestfs_session_btrfs_subvolume_list() to get a list of subvolumes.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Return detailed information of the subvolume.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Create a snapshot of the btrfs subvolume source. The dest argument is the destination directory and the name of the snapshot, in the form /path/to/dest/name. By default the newly created snapshot is writable, if the value of optional parameter ro is true, then a readonly snapshot is created. The optional parameter qgroupid represents the qgroup which the newly created snapshot will be added to.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

This will Enable extended inode refs.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

This enable skinny metadata extent refs.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

Enable seeding of a btrfs device, this will force a fs readonly so that you can use it to build other filesystems.

This function depends on the feature "btrfs". See also guestfs_session_feature_available().

In non-C language bindings, this allows you to retrieve the underlying C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to allow other libraries to interwork with libguestfs.

This utility function is useful when displaying device names to the user. It takes a number of irregular device names and returns them in a consistent format:

/dev/hdX /dev/vdX These are returned as /dev/sdX. Note this works for device names and partition names. This is approximately the reverse of the algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).

/dev/mapper/VG-LV /dev/dm-N Converted to /dev/VG/LV form using guestfs_session_lvm_canonical_lv_name().

Other strings are returned unmodified.

This function returns the Linux capabilities attached to path. The capabilities set is returned in text form (see cap_to_text(3)).

If no capabilities are attached to a file, an empty string is returned.

This function depends on the feature "linuxcaps". See also guestfs_session_feature_available().

This function sets the Linux capabilities attached to path. The capabilities set cap should be passed in text form (see cap_from_text(3)).

This function depends on the feature "linuxcaps". See also guestfs_session_feature_available().

This can be used to resolve case insensitive paths on a filesystem which is case sensitive. The use case is to resolve paths which you have read from Windows configuration files or the Windows Registry, to the true path.

The command handles a peculiarity of the Linux ntfs-3g filesystem driver (and probably others), which is that although the underlying filesystem is case-insensitive, the driver exports the filesystem to Linux as case-sensitive.

One consequence of this is that special directories such as C:\windows may appear as /WINDOWS or /windows (or other things) depending on the precise details of how they were created. In Windows itself this would not be a problem.

Bug or feature? You decide: http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1

guestfs_session_case_sensitive_path() attempts to resolve the true case of each element in the path. It will return a resolved path if either the full path or its parent directory exists. If the parent directory exists but the full path does not, the case of the parent directory will be correctly resolved, and the remainder appended unmodified. For example, if the file "/Windows/System32/netkvm.sys" exists:

guestfs_session_case_sensitive_path() ("/windows/system32/netkvm.sys") "Windows/System32/netkvm.sys"

guestfs_session_case_sensitive_path() ("/windows/system32/NoSuchFile") "Windows/System32/NoSuchFile"

guestfs_session_case_sensitive_path() ("/windows/system33/netkvm.sys") ERROR

Note: Because of the above behaviour, guestfs_session_case_sensitive_path() cannot be used to check for the existence of a file.

Note: This function does not handle drive names, backslashes etc.

See also guestfs_session_realpath().

Return the contents of the file named path.

Because, in C, this function returns a "char *", there is no way to differentiate between a "\0" character in a file and end of string. To handle binary files, use the guestfs_session_read_file() or guestfs_session_download() functions.

This call computes the MD5, SHAx or CRC checksum of the file named path.

The type of checksum to compute is given by the csumtype parameter which must have one of the following values:

crc Compute the cyclic redundancy check (CRC) specified by POSIX for the cksum command.

md5 Compute the MD5 hash (using the md5sum program).

sha1 Compute the SHA1 hash (using the sha1sum program).

sha224 Compute the SHA224 hash (using the sha224sum program).

sha256 Compute the SHA256 hash (using the sha256sum program).

sha384 Compute the SHA384 hash (using the sha384sum program).

sha512 Compute the SHA512 hash (using the sha512sum program).

The checksum is returned as a printable string.

To get the checksum for a device, use guestfs_session_checksum_device().

To get the checksums for many files, use guestfs_session_checksums_out().

This call computes the MD5, SHAx or CRC checksum of the contents of the device named device. For the types of checksums supported see the guestfs_session_checksum() command.

This command computes the checksums of all regular files in directory and then emits a list of those checksums to the local output file sumsfile.

This can be used for verifying the integrity of a virtual machine. However to be properly secure you should pay attention to the output of the checksum command (it uses the ones from GNU coreutils). In particular when the filename is not printable, coreutils uses a special backslash syntax. For more information, see the GNU coreutils info file.

Change the mode (permissions) of path to mode. Only numeric modes are supported.

Note: When using this command from guestfish, mode by default would be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not 700.

The mode actually set is affected by the umask.

Change the file owner to owner and group to group.

Only numeric uid and gid are supported. If you want to use names, you will need to locate and parse the password file yourself (Augeas support makes this relatively easy).

If there is a backend setting string matching "name" or beginning with "name=", then that string is removed from the backend settings.

This call returns the number of strings which were removed (which may be 0, 1 or greater than 1).

See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).

This call runs a command from the guest filesystem. The filesystem must be mounted, and must contain a compatible operating system (ie. something Linux, with the same or compatible processor architecture).

The single parameter is an argv-style list of arguments. The first element is the name of the program to run. Subsequent elements are parameters. The list must be non-empty (ie. must contain a program name). Note that the command runs directly, and is not invoked via the shell (see guestfs_session_sh()).

The return value is anything printed to stdout by the command.

If the command returns a non-zero exit status, then this function returns an error message. The error message string is the content of stderr from the command.

The $PATH environment variable will contain at least /usr/bin and /bin. If you require a program from another location, you should provide the full path in the first parameter.

Shared libraries and data files required by the program must be available on filesystems which are mounted in the correct places. It is the caller’s responsibility to ensure all filesystems that are needed are mounted at the right locations.

This is the same as guestfs_session_command(), but splits the result into a list of lines.

See also: guestfs_session_sh_lines()

This command compresses device and writes it out to the local file zdevice.

The ctype and optional level parameters have the same meaning as in guestfs_session_compress_out().

This command compresses file and writes it out to the local file zfile.

The compression program used is controlled by the ctype parameter. Currently this includes: compress, gzip, bzip2, xz or lzop. Some compression types may not be supported by particular builds of libguestfs, in which case you will get an error containing the substring "not supported".

The optional level parameter controls compression level. The meaning and default for this parameter depends on the compression program being used.

This can be used to add arbitrary hypervisor parameters of the form -param value. Actually it’s not quite arbitrary - we prevent you from setting some parameters which would interfere with parameters that we use.

The first character of hvparam string must be a - (dash).

hvvalue can be NULL.

Copy the attributes of a path (which can be a file or a directory) to another path.

By default no attribute is copied, so make sure to specify any (or all to copy everything).

The optional arguments specify which attributes can be copied:

mode Copy part of the file mode from source to destination. Only the UNIX permissions and the sticky/setuid/setgid bits can be copied.

xattributes Copy the Linux extended attributes (xattrs) from source to destination. This flag does nothing if the linuxxattrs feature is not available (see guestfs_session_feature_available()).

ownership Copy the owner uid and the group gid of source to destination.

all Copy all the attributes from source to destination. Enabling it enables all the other flags, if they are not specified already.

The four calls guestfs_session_copy_device_to_device(), guestfs_session_copy_device_to_file(), guestfs_session_copy_file_to_device(), and guestfs_session_copy_file_to_file() let you copy from a source (device|file) to a destination (device|file).

Partial copies can be made since you can specify optionally the source offset, destination offset and size to copy. These values are all specified in bytes. If not given, the offsets both default to zero, and the size defaults to copying as much as possible until we hit the end of the source.

The source and destination may be the same object. However overlapping regions may not be copied correctly.

If the destination is a file, it is created if required. If the destination file is not large enough, it is extended.

If the destination is a file and the append flag is not set, then the destination file is truncated. If the append flag is set, then the copy appends to the destination file. The append flag currently cannot be set for devices.

If the sparse flag is true then the call avoids writing blocks that contain only zeroes, which can help in some situations where the backing disk is thin-provisioned. Note that unless the target is already zeroed, using this option will result in incorrect copying.

See guestfs_session_copy_device_to_device() for a general overview of this call.

See guestfs_session_copy_device_to_device() for a general overview of this call.

See guestfs_session_copy_device_to_device() for a general overview of this call.

This is not the function you want for copying files. This is for copying blocks within existing files. See guestfs_session_cp(), guestfs_session_cp_a() and guestfs_session_mv() for general file copying and moving functions.

guestfs_session_copy_in() copies local files or directories recursively into the disk image, placing them in the directory called remotedir (which must exist).

Wildcards cannot be used.

guestfs_session_copy_out() copies remote files or directories recursively out of the disk image, placing them on the host disk in a local directory called localdir (which must exist).

To download to the current directory, use "." as in:

Wildcards cannot be used.

This command copies exactly size bytes from one source device or file src to another destination device or file dest.

Note this will fail if the source is too short or if the destination is not large enough.

This copies a file from src to dest where dest is either a destination filename or destination directory.

This copies a file or directory from src to dest recursively using the "cp -a" command.

This copies a file or directory from src to dest recursively using the "cp -rP" command.

Most users should use guestfs_session_cp_a() instead. This command is useful when you don't want to preserve permissions, because the target filesystem does not support it (primarily when writing to DOS FAT filesystems).

This command packs the contents of directory and downloads it to local file cpiofile.

The optional format parameter can be used to select the format. Only the following formats are currently permitted:

newc New (SVR4) portable format. This format happens to be compatible with the cpio-like format used by the Linux kernel for initramfs.

This is the default format.

crc New (SVR4) portable format with a checksum.