%all.entities; ]> August 2019 VBoxManage-storageattach 1 VBoxManage-storageattach attach, remove, and modify storage media used by a virtual machine &product-name; VBoxManage storageattach uuid vmname --storagectl=name --bandwidthgroup= name none --comment=text --device=number --discard= on off --encodedlun=lun --forceunmount --hotpluggable= on off --initiator=initiator --intnet --lun=lun --medium= none emptydrive additions uuid filename host:drive iscsi --mtype= normal writethrough immutable shareable readonly multiattach --nonrotational= on off --passthrough= on off --passwordfile=file --password=password --port=number --server= name ip --setparentuuid=uuid --setuuid=uuid --target=target --tempeject= on off --tport=port --type= dvddrive fdd hdd --username=username The VBoxManage storageattach command enables you to manage a storage medium that you connected to a storage controller by using the VBoxManage storagectl command. uuid | vmname Specifies the Universally Unique Identifier (UUID) or the name of the virtual machine (VM). --storagectl=name Specifies the name of the storage controller. Use the VBoxManage showvminfo command to list the storage controllers that are attached to the VM. --port=number Specifies the port number of the storage controller to modify. You must specify this option unless the storage controller has only a single port. --device=number Specifies the port's device number to modify. You must specify this option unless the storage controller has only one device per port. --type=dvddrive | fdd | hdd Specifies the drive type to which the medium is associated. Only omit this option if the medium type can be determined by using the --medium option or by information provided by an earlier medium attachment command. --medium=none | emptydrive | additions | uuid | filename | host:drive | iscsi Specifies one of the following values: none Removes any existing device from the specified slot. emptydrive For a virtual DVD or floppy drive only. Makes the device slot behave like a removeable drive into which no media has been inserted. additions For a virtual DVD drive only. Attaches the VirtualBox Guest Additions image to the specified device slot. uuid Specifies the UUID of a storage medium to attach to the specified device slot. The storage medium must already be known to &product-name;, such as a storage medium that is attached to another VM. Use the VBoxManage list command to list media. filename Specifies the full path of an existing disk image to attach to the specified device slot. The disk image can be in ISO, RAW, VDI, VMDK, or other format. host:drive For a virtual DVD or floppy drive only. Connects the specified device slot to the specified DVD or floppy drive on the host computer. iscsi For virtual hard disks only. Specifies an iSCSI target for which you must specify additional information. See . For removeable media such as floppies and DVDs, you can make configuration changes while a VM is running. Changes to devices or hard disk device slots require that the VM be powered off. --mtype=normal | writethrough | immutable | shareable | readonly | multiattach Specifies how this medium behaves with respect to snapshots and write operations. See . --comment=text Specifies an optional description to store with the medium. --setuuid=uuid Modifies the UUID of a medium before attaching it to a VM. This is an expert option. Inappropriate values might make the medium unusable or lead to broken VM configurations if another VM already refers to the same medium. Using the --setuuid="" option assigns a new random UUID to an image, which can resolve duplicate UUID errors if you used a file copy utility to duplicate an image. --setparentuuid=uuid Modifies the parent UUID of a medium before attaching it to a VM. This is an expert option. Inappropriate values might make the medium unusable or lead to broken VM configurations if another VM already refers to the same medium. --passthrough=on | off For a virtual DVD drive only. Enables writing to a DVD. This feature is experimental, see . --tempeject=on | off For a virtual DVD drive only. Specifies whether to permit a temporary guest-triggered medium eject operation. When set to on, you can eject a medium. The ability for a guest-triggered eject operation does not persist if the VM is powered off and restarted. So, when you set this option to on and the VM is restarted, the originally configured medium is still in the drive. --nonrotational=on | off Enables you to specify that the virtual hard disk is non-rotational. Some guest OSes, such as Windows 7 or later, treat such disks as solid state drives (SSDs) and do not perform disk fragmentation on them. --discard=on | off Specifies whether to enable the auto-discard feature for a virtual hard disk. When set to on, a VDI image is shrunk in response to a trim command from the guest OS. The virtual hard disk must meet the following requirements: The disk format must be VDI. The size of the cleared area of the disk must be at least 1 MB. Ensure that the space being trimmed is at least a 1 MB contiguous block at a 1 MB boundary. Consider running defragmentation commands as background cron jobs to save space. On Windows, run the defrag.exe /D command. On Linux, run the btrfs filesystem defrag command. When you configure the guest OS to issue the trim command, the guest OS typically sees the disk as an SSD. Ext4 supports the -o discard mount option. Mac OS X might require additional settings. Windows 7, 8, and 10 automatically detect and support SSDs. The Linux exFAT driver from Samsung supports the trim command. The Microsoft implementation of exFAT might not support this feature. You can use other methods to issue trim commands. The Linux fstrim command is part of the util-linux package. Earlier solutions required you to zero out unused areas by using the zerofree or a similar command, and then to compact the disk. You can only perform these steps when the VM is offline. --bandwidthgroup=name Specifies the bandwidth group to use for the device. See . --forceunmount For a virtual DVD or floppy drive only. Forcibly unmounts the DVD, CD, or floppy or mounts a new DVD, CD, or floppy even if the previous removable storage is locked by the guest for reading. See . The following options are applicable when you specify the --medium=iscsi option: --server=hostname | IP-address Specifies the host name or IP address of the iSCSI target. --target=target Specifies the target name string, which is determined by the iSCSI target and is used to identify the storage resource. --tport=port Specifies the TCP/IP port number of the iSCSI service on the target. --lun=LUN Specifies the logical unit number (LUN) of the target resource. For a single disk drive, the value is zero. --encodedlun=LUN Specifies the hexadecimal-encoded of the target resource. For a single disk drive, the value is zero. --username=username Specifies the user name to use for target authentication. Unless you provide a settings password, the user name is stored as clear text in the XML machine configuration file. --password=password Specifies the password used for target authentication. Unless you provide a settings password, this password is stored as clear text in the XML machine configuration file. When you specify a settings password for the first time, the target authentication password is stored in encrypted form. This design does not conform to Oracle's security guidelines. You should not be able to specify a password on the command line because the password can be seen in a process listing. --passwordfile=password-filename Specifies a file that contains the target authentication password as clear text. Use permission and ownership settings to ensure that the contents of this file cannot be read by unauthorized users. --initiator=initiator Specifies the iSCSI initiator. The 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 the iSCSI initiator are largely analogous to Fibre Channel SAN components, and they include the following: iSCSI driver. Transports blocks of iSCSI commands over the IP network. This iSCSI driver is installed on the iSCSI host and is included with the Microsoft iSCSI Initiator. Gigabit Ethernet adapter. Connects to an iSCSI target. Use an Ethernet adapter that can transmit 1000 megabits per second (Mbps). 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. 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 Specifies whether to connect to the iSCSI target that uses internal networking. This configuration requires further configuration. See . The following command attaches the o7.vdi disk image to the specified SATA storage controller on the ol7 VM. $ storageattach ol7 --storagectl "SATA Controller" --port 0 --device 0 \ --type hdd --medium /VirtualBox/ol7/ol7.vdi The following command attaches the o7-r6-dvd.iso DVD image to the specified IDE storage controller on the ol7 VM. $ VBoxManage storageattach ol7 --storagectl "IDE Controller" --port 0 --device 0 \ --type dvddrive --medium ol7-r6-dvd.iso , ,