add_drive

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

<![CDATA[Protocol Number of servers required]]>

<![CDATA[-------- --------------------------]]>

<![CDATA[file List must be empty or param not used at all]]>

<![CDATA[ftp|ftps|http|https|tftp Exactly one]]>

<![CDATA[gluster Exactly one]]>

<![CDATA[iscsi Exactly one]]>

<![CDATA[nbd Exactly one]]>

<![CDATA[rbd Zero or more]]>

<![CDATA[sheepdog Zero or more]]>

<![CDATA[ssh Exactly one]]>

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

<![CDATA[hostname]]>

<![CDATA[hostname:port]]>

<![CDATA[tcp:hostname]]>

<![CDATA[tcp:hostname:port]]>

<![CDATA[unix:/path/to/socket]]>

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

Parameters:

this	A GuestfsSession object
optargs	a GuestfsAddDrive containing optional arguments

Returns:

true on success, false on error