When managing VirtualBox VMs through the command line, one common task is replacing the primary boot disk. This becomes slightly more complex when dealing with differencing disks (child VDI files) in snapshot chains.
For a standard VDI file, the command structure is straightforward:
VBoxManage storageattach "VM Name" \ --storagectl "SATA Controller" \ --port 0 \ --device 0 \ --type hdd \ --medium "new_disk.vdi"
Key parameters to note:
- --storagectl specifies the controller name (check with VBoxManage showvminfo "VM Name")
- --port and --device identify the storage slot
- --medium points to the new disk image
When working with snapshot chains, you'll need to attach both parent and child disks while maintaining their relationship:
# First attach the parent disk VBoxManage storageattach "VM Name" \ --storagectl "SATA" \ --port 0 \ --device 0 \ --type hdd \ --medium "parent.vdi" # Then attach the child differencing disk VBoxManage storageattach "VM Name" \ --storagectl "SATA" \ --port 1 \ --device 0 \ --type hdd \ --medium "child.vdi" \ --mtype multiattach
The --mtype multiattach parameter is crucial for maintaining the parent-child relationship between the disks.
Here's a complete workflow to replace a VM's primary boot disk:
# Power off the VM if running VBoxManage controlvm "MyVM" poweroff # Detach the existing disk VBoxManage storageattach "MyVM" \ --storagectl "SATA Controller" \ --port 0 \ --device 0 \ --type hdd \ --medium none # Attach the new disk (standard VDI case) VBoxManage storageattach "MyVM" \ --storagectl "SATA Controller" \ --port 0 \ --device 0 \ --type hdd \ --medium "new_boot.vdi" # For differencing disk scenario: VBoxManage storageattach "MyVM" \ --storagectl "SATA Controller" \ --port 0 \ --device 0 \ --type hdd \ --medium "base.vdi" VBoxManage storageattach "MyVM" \ --storagectl "SATA Controller" \ --port 1 \ --device 0 \ --type hdd \ --medium "diff.vdi" \ --mtype multiattach
After making changes, verify the storage configuration:
VBoxManage showvminfo "MyVM" --details
Common issues to watch for:
- Mismatched controller names (case-sensitive)
- Incorrect port/device assignments
- Missing --mtype multiattach for differencing disks
- File permission issues on the VDI files
To modify an existing disk attachment without complete detachment:
VBoxManage modifyvm "MyVM" \ --hda "new_disk.vdi"
This provides a shortcut for primary disk replacement when you don't need to specify the controller details explicitly.
When working with VirtualBox VMs, the VBoxManage storageattach command is your primary tool for managing virtual disks. The basic syntax for attaching a normal VDI is:
VBoxManage storageattach "VM Name" \ --storagectl "Controller Name" \ --port 0 \ --device 0 \ --type hdd \ --medium "path/to/disk.vdi"
For differencing disks (child VDI), the process is similar but requires proper parent-child chain handling:
# First attach the parent disk (read-only) VBoxManage storageattach "MyVM" \ --storagectl "SATA Controller" \ --port 0 \ --device 0 \ --type hdd \ --medium "BaseDisk.vdi" \ --mtype readonly # Then attach the child differencing disk VBoxManage storageattach "MyVM" \ --storagectl "SATA Controller" \ --port 0 \ --device 0 \ --type hdd \ --medium "DiffDisk.vdi"
To replace the primary boot disk of an existing VM:
- First detach the current disk:
- Then attach the new disk (normal or differencing):
VBoxManage storageattach "ExistingVM" \ --storagectl "SATA" \ --port 0 \ --device 0 \ --medium none
VBoxManage storageattach "ExistingVM" \ --storagectl "SATA" \ --port 0 \ --device 0 \ --type hdd \ --medium "NewBootDisk.vdi"
Here's a complete workflow for creating and attaching a differencing disk as boot drive:
# Create base disk VBoxManage createmedium disk --filename BaseDisk.vdi --size 20480 # Create differencing disk VBoxManage createmedium disk --filename DiffDisk.vdi \ --diffparent BaseDisk.vdi # Attach to VM VBoxManage storageattach "TestVM" \ --storagectl "SATA" \ --port 0 \ --device 0 \ --type hdd \ --medium BaseDisk.vdi \ --mtype readonly VBoxManage storageattach "TestVM" \ --storagectl "SATA" \ --port 0 \ --device 0 \ --type hdd \ --medium DiffDisk.vdi
After attachment, verify the configuration:
VBoxManage showvminfo "VM Name" --details
Common issues to check:
- Parent disk must be attached before child with
--mtype readonly - Controller name must match exactly (case-sensitive)
- Port/device numbers must be available