8.18. VBoxManage storageattach

This command attaches/modifies/removes a storage medium connected to a storage controller that was previously added with the storagectl command (see the previous section). The syntax is as follows:

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

A number of parameters are commonly required; the ones at the end of the list are required only for iSCSI targets (see below).

The common parameters are:

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 8.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/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 behaves 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 VirtualBox (e.g. because it has been attached to another virtual machine). See Section 8.4, “VBoxManage list” for 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 (ISO, RAW, VDI, VMDK or other), which 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 allows for specifying an iSCSI target. In this case, more parameters must be given; see below.

Some of the above changes, in particular for removeable media (floppies and CDs/DVDs), can be effected while a VM is running. Others (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” for details.

--comment

Any description that you want to have stored with this medium (optional; 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 is useful to resolve the duplicate UUID errors if one duplicated an image using file copy utilities.

--passthrough

For a virtual DVD drive only, you can enable DVD writing support (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 temporary effects. If the VM is powered off and restarted the originally configured medium will be still in the drive.

--nonrotational

This switch allows to enable the non-rotational flag for virtual hard disks. Some guests (i.e. Windows 7+) treat such disks like SSDs and don't perform disk fragmentation on such media.

--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. Again, see Section 5.9, “CD/DVD support” for details.

When "iscsi" is used with the --medium parameter for iSCSI support -- see Section 5.10, “iSCSI servers” --, additional parameters must or can be used:

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

--username, --password

Username and password (initiator secret) for target authentication, if required (optional).

Note

Username and password are stored without encryption (i.e. in clear text) in the XML machine configuration file if no settings password is provided. When a settings password was specified the first time, the password is stored encrypted.

--intnet

If specified, connect to the iSCSI target via Internal Networking. This needs further configuration which is described in Section 9.9.3, “Access iSCSI targets via Internal Networking”.