vboxmanage-controlvm

Temporarily stop the execution of a virtual machine

$ VBoxManage controlvm [uuid|vm_name] pause

$ VBoxManage controlvm [uuid|vm_name] resume

$ VBoxManage controlvm [uuid|vm_name] reset

$ VBoxManage controlvm [uuid|vm_name] poweroff

$ VBoxManage controlvm [uuid|vm_name] savestate

$ VBoxManage controlvm [uuid|vm_name] acpipowerbutton

$ VBoxManage controlvm [uuid|vm_name] reboot

$ VBoxManage controlvm [uuid|vm_name] shutdown

VBoxManage controlvm <uuid|vmname> <action> [<action_parameters>]

Examples:
VBoxManage controlvm "MyVM" poweroff
VBoxManage controlvm "UbuntuServer" savestate
VBoxManage controlvm "Win10Dev" keyboardputtext "Hello World"

poweroff
    Immediately powers off the VM, similar to unplugging a physical machine. This can lead to data loss.

reset
    Resets the VM, akin to pressing the reset button on a physical computer.

savestate
    Saves the current running state of the VM to disk, allowing it to be resumed exactly where it left off.

pause
    Temporarily suspends the execution of the VM. The VM's state remains in memory.

resume
    Resumes a previously paused VM from its suspended state.

acpipowerbutton
    Sends an ACPI power button event to the VM. This typically triggers a graceful shutdown if the guest OS supports ACPI.

acpisleepbutton
    Sends an ACPI sleep button event to the VM, initiating a sleep or suspend state if supported by the guest.

keyboardputtext
    Injects the specified text as keyboard input into the guest OS. Useful for automated logins or commands.

guestmemoryballoon
    Adjusts the guest memory balloon size, dynamically allocating or deallocating RAM for the guest VM. Requires Guest Additions.

vrde
    Controls the VirtualBox Remote Desktop Extension (VRDE) for the VM, allowing remote access. Has various sub-options for configuration.

The VBoxManage controlvm command is a crucial utility within the Oracle VirtualBox command-line interface, providing granular control over running virtual machines. It allows users to manage a VM's lifecycle, change its operational state, and interact with the guest system directly from the host command line. This command is indispensable for automating VM operations, scripting complex virtualized environments, and managing headless VMs without direct GUI interaction. It can power on/off, pause, reset, save the state of a VM, or even send specific events like ACPI power signals to facilitate graceful shutdowns. Its versatility makes it a cornerstone for system administrators and developers working with VirtualBox.

Using poweroff can lead to data corruption or loss in the guest OS, as it does not allow for a graceful shutdown. Prefer acpipowerbutton for clean shutdowns.
Many commands require the VirtualBox Guest Additions to be installed in the guest OS for full functionality (e.g., acpipowerbutton, guestmemoryballoon).
The VM must be in an appropriate state for certain commands; for example, you cannot resume a VM that is not paused.

controlvm is foundational for automating VM lifecycle management in scripts, allowing for unattended operations like scheduled shutdowns, reboots, or state saving.

It is crucial for managing "headless" VMs (VMs running without a graphical user interface), common in server environments or CI/CD pipelines, where all interactions are via the command line.

The VBoxManage command, including its controlvm subcommand, has been an integral part of VirtualBox since its early days. VirtualBox was originally developed by Innotek GmbH, then acquired by Sun Microsystems in 2008, and subsequently by Oracle Corporation in 2010. Throughout these transitions, VBoxManage has remained the primary command-line interface for managing and controlling VirtualBox virtual machines, consistently evolving to support new features and functionalities.

VBoxManage(1), VBoxManage startvm(1), VBoxManage showvminfo(1), VBoxManage modifyvm(1), VBoxManage snapshot(1)