7.17. VBoxManage storageattach

This command attaches, modifies, and removes a storage medium connected to a storage controller that was previously added with the storagectl command. The syntax is as follows:

VBoxManage storageattach    <uuid|vmname>
                            --storagectl <name>
                            [--port <number>]
                            [--device <number>]
                            [--type dvddrive|hdd|fdd]
                            [--medium none|emptydrive|additions|
                                      <uuid>|<filename>|host:<drive>|iscsi]
                            [--mtype normal|writethrough|immutable|shareable
                                     readonly|multiattach]
                            [--comment <text>]
                            [--setuuid <uuid>]
                            [--setparentuuid <uuid>]
                            [--passthrough on|off]
                            [--tempeject on|off]
                            [--nonrotational on|off]
                            [--discard on|off]
                            [--hotpluggable on|off]
                            [--bandwidthgroup name|none]
                            [--forceunmount]
                            [--server <name>|<ip>]
                            [--target <target>]
                            [--tport <port>]
                            [--lun <lun>]
                            [--encodedlun <lun>]
                            [--username <username>]
                            [--password <password>]
                            [--passwordfile <file>]
                            [--initiator <initiator>]
                            [--intnet]

A number of parameters are commonly required. Some parameters are required only for iSCSI targets.

The common parameters are as follows:

uuid|vmname

The VM UUID or VM Name. Mandatory.

--storagectl

Name of the storage controller. Mandatory. The list of the storage controllers currently attached to a VM can be obtained with VBoxManage showvminfo. See Section 7.5, “VBoxManage showvminfo”.

--port

The number of the storage controller's port which is to be modified. Mandatory, unless the storage controller has only a single port.

--device

The number of the port's device which is to be modified. Mandatory, unless the storage controller has only a single device per port.

--type

Define the type of the drive to which the medium is being attached, detached, or modified. This argument can only be omitted if the type of medium can be determined from either the medium given with the --medium argument or from a previous medium attachment.

--medium

Specifies what is to be attached. The following values are supported:

none: Any existing device should be removed from the given slot.
emptydrive: For a virtual DVD or floppy drive only, this makes the device slot behave like a removeable drive into which no media has been inserted.
additions: For a virtual DVD drive only, this attaches the VirtualBox Guest Additions image to the given device slot.
If a UUID is specified, it must be the UUID of a storage medium that is already known to Oracle VM VirtualBox. For example, because it has been attached to another virtual machine. See Section 7.4, “VBoxManage list” for details of how to list known media. This medium is then attached to the given device slot.
If a filename is specified, it must be the full path of an existing disk image in ISO, RAW, VDI, VMDK, or other format. The disk image is then attached to the given device slot.
host:<drive>: For a virtual DVD or floppy drive only, this connects the given device slot to the specified DVD or floppy drive on the host computer.
iscsi: For virtual hard disks only, this is used for specifying an iSCSI target. In this case, additional parameters must be given. These are described below.

Some of the above changes, in particular for removeable media such as floppies and CDs/DVDs, can be effected while a VM is running. Others, such as device changes or changes in hard disk device slots, require the VM to be powered off.

--mtype

Defines how this medium behaves with respect to snapshots and write operations. See Section 5.4, “Special Image Write Modes”.

--comment

An optional description that you want to have stored with this medium. For example, for an iSCSI target, "Big storage server downstairs". This is purely descriptive and not needed for the medium to function correctly.

--setuuid, --setparentuuid

Modifies the UUID or parent UUID of a medium before attaching it to a VM. This is an expert option. Inappropriate use can make the medium unusable or lead to broken VM configurations if any other VM is referring to the same media already. The most frequently used variant is --setuuid "", which assigns a new random UUID to an image. This option is useful for resolving duplicate UUID errors if you duplicated an image using a file copy utility.

--passthrough

For a virtual DVD drive only, you can enable DVD writing support. This feature is currently experimental, see Section 5.9, “CD/DVD Support”.

--tempeject

For a virtual DVD drive only, you can configure the behavior for guest-triggered medium eject. If this is set to on, the eject has only a temporary effect. If the VM is powered off and restarted the originally configured medium will be still in the drive.

--nonrotational

Enables you to enable the non-rotational flag for virtual hard disks. Some guests, such as Windows 7 or later, treat such disks like SSDs and do not perform disk fragmentation on such media.

--discard

Enables the auto-discard feature for a virtual hard disks. This specifies that a VDI image will be shrunk in response to the trim command from the guest OS. The following requirements must be met:

The disk format must be VDI.
The size of the cleared area must be at least 1 MB.
Oracle VM VirtualBox will only trim whole 1 MB blocks. The VDIs themselves are organized into 1 MB blocks, so this will only work if the space being trimmed is at least a 1 MB contiguous block at a 1 MB boundary. On Windows, occasional defragmentation with defrag.exe /D, or on Linux running btrfs filesystem defrag as a background cron job may be beneficial.

Note

The Guest OS must be configured to issue the trim command, and typically this means that the guest OS is made to see the disk as an SSD. Ext4 supports the -o discard mount flag. Mac OS X probably requires additional settings. Windows should automatically detect and support SSDs, at least in versions 7, 8, and 10. The Linux exFAT driver from Samsung supports the trim command.

It is unclear whether Microsoft's implementation of exFAT supports this feature, even though that file system was originally designed for flash.

Alternatively, there are other methods to issue trim. For example, the Linux fstrim command, part of the util-linux package. Earlier solutions required a user to zero out unused areas, using zerofree or similar, and to compact the disk. This is only possible when the VM is offline.

--bandwidthgroup

Sets the bandwidth group to use for the given device. See Section 5.8, “Limiting Bandwidth for Disk Images”.

--forceunmount

For a virtual DVD or floppy drive only, this forcibly unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy even if the previous one is locked down by the guest for reading. See Section 5.9, “CD/DVD Support”.

When iscsi is used with the --medium parameter for iSCSI support, additional parameters must or can be used. See also Section 5.10, “iSCSI Servers”.

--server

The host name or IP address of the iSCSI target. Required.

--target

Target name string. This is determined by the iSCSI target and used to identify the storage resource. Required.

--tport

TCP/IP port number of the iSCSI service on the target. Optional.

--lun

Logical Unit Number of the target resource. Optional. Often, this value is zero.

--encodedlun

Hex-encoded Logical Unit Number of the target resource. Optional. Often, this value is zero.

--username, --password, --passwordfile

Username and password, called the initiator secret, for target authentication, if required. Optional.

Note

Username and password are stored without encryption, in clear text, in the XML machine configuration file if no settings password is provided. When a settings password is specified for the first time, the password is stored in encrypted form. As an alternative to providing the password on the command line, a reference to a file containing the text can be provided using the passwordfile option.

--initiator

iSCSI Initiator. Optional.

Microsoft iSCSI Initiator is a system, such as a server that attaches to an IP network and initiates requests and receives responses from an iSCSI target. The SAN components in Microsoft iSCSI Initiator are largely analogous to Fibre Channel SAN components, and they include the following:

To transport blocks of iSCSI commands over the IP network, an iSCSI driver must be installed on the iSCSI host. An iSCSI driver is included with Microsoft iSCSI Initiator.
A gigabit Ethernet adapter that transmits 1000 megabits per second (Mbps) is recommended for the connection to an iSCSI target. Like standard 10/100 adapters, most gigabit adapters use a preexisting Category 5 or Category 6E cable. Each port on the adapter is identified by a unique IP address.
An iSCSI target is any device that receives iSCSI commands. The device can be an end node, such as a storage device, or it can be an intermediate device, such as a network bridge between IP and Fibre Channel devices. Each port on the storage array controller or network bridge is identified by one or more IP addresses

--intnet

If specified, connect to the iSCSI target using Internal Networking. This needs further configuration, see Access iSCSI Targets Using Internal Networking.