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>] [--passthrough on|off] [--bandwidthgroup name|none] [--forceunmount] [--server <name>|<ip>] [--target <target>] [--port <port>] [--lun <lun>] [--encodedlun <lun>] [--username <username>] [--password <password>] [--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:
The VM UUID or VM Name. Mandatory.
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.4, “VBoxManage showvminfo”.
The number of the storage controller's port which is to be modified. Mandatory.
The number of the port's device which is to be modified. Mandatory.
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.
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.
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.3, “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.
Defines how this medium behaves with respect to snapshots and write operations. See Section 5.4, “Special image write modes” for details.
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.
For a virtual DVD drive only, you can enable DVD writing support (currently experimental; see Section 5.9, “CD/DVD support”).
Sets the bandwidth group to use for the given device; see Section 5.8, “Limiting bandwidth for disk images”.
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:
The host name or IP address of the iSCSI target; required.
Target name string. This is determined by the iSCSI target and used to identify the storage resource; required.
TCP/IP port number of the iSCSI service on the target (optional).
Logical Unit Number of the target resource (optional). Often, this value is zero.
Username and password for target authentication, if required (optional).
Currently, username and password are stored without encryption (i.e. in clear text) in the XML machine configuration file.
If specified, connect to the iSCSI target via Internal Networking. This needs further configuration which is described in Section 9.7.3, “Access iSCSI targets via Internal Networking”.