Sys::Guestfs - Perl bindings for libguestfs

NAME
SYNOPSIS
DESCRIPTION
ERRORS
METHODS
AVAILABILITY
STORING DATA IN THE HANDLE
COPYRIGHT
LICENSE
SEE ALSO

NAME

Sys::Guestfs - Perl bindings for libguestfs

SYNOPSIS

use Sys::Guestfs;

my $g = Sys::Guestfs->new ();
$g->add_drive_opts ('guest.img', format => 'raw');
$g->launch ();
$g->mount ('/dev/sda1', '/');
$g->touch ('/hello');
$g->shutdown ();
$g->close ();

DESCRIPTION

The Sys::Guestfs module provides a Perl XS binding to the libguestfs API for examining and modifying virtual machine disk images.

Amongst the things this is good for: making batch configuration changes to guests, getting disk used/free statistics (see also: virt-df), migrating between virtualization systems (see also: virt-p2v), performing partial backups, performing partial guest clones, cloning guests and changing registry/UUID/hostname info, and much else besides.

Libguestfs uses Linux kernel and qemu code, and can access any type of guest filesystem that Linux and qemu can, including but not limited to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition schemes, qcow, qcow2, vmdk.

Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, what filesystem is in each LV, etc.). It can also run commands in the context of the guest. Also you can access filesystems over FUSE.

ERRORS

All errors turn into calls to croak (see Carp(3)).

The error string from libguestfs is directly available from $@. Use the last_errno method if you want to get the errno.

METHODS

$g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);

Create a new guestfs handle.

If the optional argument environment is false, then the GUESTFS_CREATE_NO_ENVIRONMENT flag is set.

If the optional argument close_on_exit is false, then the GUESTFS_CREATE_NO_CLOSE_ON_EXIT flag is set.

$g->close ();

Explicitly close the guestfs handle.

Note: You should not usually call this function. The handle will be closed implicitly when its reference count goes to zero (eg. when it goes out of scope or the program ends). This call is only required in some exceptional cases, such as where the program may contain cached references to the handle 'somewhere' and you really have to have the close happen right away. After calling close the program must not call any method (including close) on the handle (but the implicit call to DESTROY that happens when the final reference is cleaned up is OK).

$Sys::Guestfs::EVENT_CLOSE

See "GUESTFS_EVENT_CLOSE" in guestfs(3).

$Sys::Guestfs::EVENT_SUBPROCESS_QUIT

See "GUESTFS_EVENT_SUBPROCESS_QUIT" in guestfs(3).

$Sys::Guestfs::EVENT_LAUNCH_DONE

See "GUESTFS_EVENT_LAUNCH_DONE" in guestfs(3).

$Sys::Guestfs::EVENT_PROGRESS

See "GUESTFS_EVENT_PROGRESS" in guestfs(3).

$Sys::Guestfs::EVENT_APPLIANCE

See "GUESTFS_EVENT_APPLIANCE" in guestfs(3).

$Sys::Guestfs::EVENT_LIBRARY

See "GUESTFS_EVENT_LIBRARY" in guestfs(3).

$Sys::Guestfs::EVENT_TRACE

See "GUESTFS_EVENT_TRACE" in guestfs(3).

$Sys::Guestfs::EVENT_ENTER

See "GUESTFS_EVENT_ENTER" in guestfs(3).

$Sys::Guestfs::EVENT_LIBVIRT_AUTH

See "GUESTFS_EVENT_LIBVIRT_AUTH" in guestfs(3).

$Sys::Guestfs::EVENT_WARNING

See "GUESTFS_EVENT_WARNING" in guestfs(3).

$Sys::Guestfs::EVENT_ALL

See "GUESTFS_EVENT_ALL" in guestfs(3).

$event_handle = $g->set_event_callback (\&cb, $event_bitmask);

Register cb as a callback function for all of the events in $event_bitmask (one or more $Sys::Guestfs::EVENT_* flags logically or'd together).

This function returns an event handle which can be used to delete the callback using delete_event_callback.

The callback function receives 4 parameters:

&cb ($event, $event_handle, $buf, $array)

$event: The event which happened (equal to one of $Sys::Guestfs::EVENT_*).
$event_handle: The event handle.
$buf: For some event types, this is a message buffer (ie. a string).
$array: For some event types (notably progress events), this is an array of integers.

You should carefully read the documentation for "guestfs_set_event_callback" in guestfs(3) before using this function.

$g->delete_event_callback ($event_handle);

This removes the callback which was previously registered using set_event_callback.

$str = Sys::Guestfs::event_to_string ($events);

$events is either a single event or a bitmask of events. This returns a printable string, useful for debugging.

Note that this is a class function, not a method.

$errnum = $g->last_errno ();

This returns the last error number (errno) that happened on the handle $g.

If successful, an errno integer not equal to zero is returned.

If no error number is available, this returns 0. See "guestfs_last_errno" in guestfs(3) for more details of why this can happen.

You can use the standard Perl module Errno(3) to compare the numeric error returned from this call with symbolic errnos:

$g->mkdir ("/foo");
if ($g->last_errno() == Errno::EEXIST()) {
  # mkdir failed because the directory exists already.
}

$g->acl_delete_def_file ($dir);

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

This function depends on the feature acl. See also $g->feature-available.

$acl = $g->acl_get_file ($path, $acltype);

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 $g->feature-available.

$g->acl_set_file ($path, $acltype, $acl);

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:

u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500: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 $g->aug_init).

This function depends on the feature acl. See also $g->feature-available.

$g->add_cdrom ($filename);

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 $g->add_drive_ro.

This function is deprecated. In new code, use the "add_drive_ro" call instead.

Deprecated functions will not be removed from the API, but the fact that they are deprecated indicates that there are problems with correct use of these functions.

$nrdisks = $g->add_domain ($dom [, libvirturi => $libvirturi] [, readonly => $readonly] [, iface => $iface] [, live => $live] [, allowuuid => $allowuuid] [, readonlydisk => $readonlydisk] [, cachemode => $cachemode] [, discard => $discard] [, copyonread => $copyonread]);

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 $g->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 https://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 https://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 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 $g->add_drive_opts.

The other optional parameters are passed directly through to $g->add_drive_opts.

$g->add_drive ($filename [, readonly => $readonly] [, format => $format] [, iface => $iface] [, name => $name] [, label => $label] [, protocol => $protocol] [, server => $server] [, username => $username] [, secret => $secret] [, cachemode => $cachemode] [, discard => $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);

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 $g->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 "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 $g->add_drive or $g->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 $g->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.

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.

protocol = "gluster"

Connect to the GlusterFS server. The server parameter must also be supplied - see below.

See also $g->stat.

$flag = $g->is_blockdev_opts ($path [, followsymlinks => $followsymlinks]);

This is an alias of "is_blockdev".

$busy = $g->is_busy ();

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

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

$flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);

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 $g->stat.

$flag = $g->is_chardev_opts ($path [, followsymlinks => $followsymlinks]);

This is an alias of "is_chardev".

$config = $g->is_config ();

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

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

$dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);

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 $g->stat.

$dirflag = $g->is_dir_opts ($path [, followsymlinks => $followsymlinks]);

This is an alias of "is_dir".

$flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);

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 $g->stat.

$flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);

This is an alias of "is_fifo".

$fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);

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 $g->stat.

$fileflag = $g->is_file_opts ($path [, followsymlinks => $followsymlinks]);

This is an alias of "is_file".

$launching = $g->is_launching ();

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

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

$lvflag = $g->is_lv ($mountable);

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

$ready = $g->is_ready ();

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

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

$flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);

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 $g->stat.

$flag = $g->is_socket_opts ($path [, followsymlinks => $followsymlinks]);

This is an alias of "is_socket".

$flag = $g->is_symlink ($path);

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

See also $g->stat.

$flag = $g->is_whole_device ($device);

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

$zeroflag = $g->is_zero ($path);

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

$zeroflag = $g->is_zero_device ($device);

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.

%isodata = $g->isoinfo ($isofile);

This is the same as $g->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 $g->isoinfo_device.

%isodata = $g->isoinfo_device ($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 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor

$g->journal_close ();

Close the journal handle.

This function depends on the feature journal. See also $g->feature-available.

@fields = $g->journal_get ();

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: $g->journal_set_data_threshold, $g->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 $g->feature-available.

$threshold = $g->journal_get_data_threshold ();

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.

See also $g->journal_set_data_threshold.

This function depends on the feature journal. See also $g->feature-available.

$usec = $g->journal_get_realtime_usec ();

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

This function depends on the feature journal. See also $g->feature-available.

$more = $g->journal_next ();

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 $g->journal_get), and false means you have reached the end of the journal.

This function depends on the feature journal. See also $g->feature-available.

$g->journal_open ($directory);

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

The contents of the journal can be read using $g->journal_next and $g->journal_get.

After you have finished using the journal, you should close the handle by calling $g->journal_close.

This function depends on the feature journal. See also $g->feature-available.

$g->journal_set_data_threshold ($threshold);

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.

See also $g->journal_get_data_threshold.

This function depends on the feature journal. See also $g->feature-available.

$rskip = $g->journal_skip ($skip);

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 $g->feature-available.

$g->kill_subprocess ();

This kills the hypervisor.

Do not call this. See: $g->shutdown instead.

This function is deprecated. In new code, use the "shutdown" call instead.

Deprecated functions will not be removed from the API, but the fact that they are deprecated indicates that there are problems with correct use of these functions.

$g->launch ();

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

Do not call $g->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.

$g->lchown ($owner, $group, $path);

Change the file owner to owner and group to group. This is like $g->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).

$g->ldmtool_create_all ();

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

Call $g->list_ldm_volumes and $g->list_ldm_partitions to return all devices.

Note that you don't normally need to call this explicitly, since it is done automatically at $g->launch time.