8.18. VBoxManage storageattach

Oracle VM VirtualBox

previous page next page

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

--discard

This switch enables the auto-discard feature for the 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 1MB.

  • VirtualBox will only trim whole 1MB blocks. The VDIs themselves are organized into 1MB blocks, so this will only work if the space being TRIM-ed is at least a 1MB contiguous block at a 1MB boundary. On Windows, occasional defrag (with "defrag.exe /D"), or under Linux running "btrfs filesystem defrag" as a background cron job may be beneficial.

Notes: the Guest OS must be configured to issue trim command, and typically this means that the guest OS is made to 'see' the disk as an SSD. Ext4 supports -o discard mount flag; OSX probably requires additional settings. Windows ought to automatically detect and support SSDs - at least in versions 7, 8 and 10. Linux exFAT driver (courtesy of 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 ad hoc methods to issue trim, e.g. Linux fstrim command, part of util-linux package. Earlier solutions required a user to zero out unused areas, e.g. using zerofree, and explicitly compact the disk - 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. 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.

--encodedlun

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

--username, --password, --passwordfile

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. Alternatively to providing the password on the command line, a reference to a file containing the text can be provided instead via the passwordfile option.

--initiator

iSCSI Initiator (optional). Note:

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 pre-existing 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 via Internal Networking. This needs further configuration which is described in Section 9.9.3, “Access iSCSI targets via Internal Networking”.

previous page start next page