VBoxControl

VBoxControl <vmname|uuid> <command> [arguments]

VBoxControl <vmname|uuid> poweroff

VBoxControl <vmname|uuid> reset

VBoxControl <vmname|uuid> pause

VBoxControl <vmname|uuid> resume

VBoxControl <vmname|uuid> savestate

VBoxControl <vmname|uuid> acpipowerbutton

VBoxControl <vmname|uuid> acpisleepbutton

<vmname|uuid>
    Specifies the name or UUID of the virtual machine to control. The VM must be registered with VirtualBox.

poweroff
    Immediately powers off the virtual machine. This is equivalent to pulling the plug and can lead to data loss if the guest OS is not properly shut down.

reset
    Performs a hard reset of the virtual machine, similar to pressing the reset button on a physical computer.

pause
    Pauses the execution of the virtual machine, freezing its current state.

resume
    Resumes the execution of a previously paused virtual machine from its frozen state.

savestate
    Saves the current state of the virtual machine to disk, allowing it to be restored later exactly where it left off.

acpipowerbutton
    Sends an ACPI power button signal to the guest operating system. This allows for a graceful shutdown if the guest OS supports ACPI and VirtualBox Guest Additions are installed.

acpisleepbutton
    Sends an ACPI sleep button signal to the guest operating system, prompting it to enter a sleep or suspend state. Requires Guest Additions.

VBoxControl is a command-line utility provided with Oracle VirtualBox that allows users to manage the operational state of VirtualBox virtual machines. Unlike the broader VBoxManage command, VBoxControl primarily focuses on runtime control actions such as powering off, resetting, pausing, resuming, or saving the state of a VM. It is an essential tool for scripting and automating VirtualBox environments, enabling unattended management of VMs for tasks like testing, server management, or continuous integration pipelines. This command provides a direct interface to manipulate a VM's lifecycle without needing the VirtualBox GUI.

• VBoxControl requires Oracle VirtualBox to be installed on the system.
• For graceful shutdown (acpipowerbutton) and sleep (acpisleepbutton) commands to function correctly, VirtualBox Guest Additions must be installed within the guest operating system.
• Using poweroff can lead to data corruption or loss within the guest OS if the system is not properly shut down before the command is issued. Use with caution.
• The command expects the VM name or UUID to uniquely identify the target virtual machine. If multiple VMs have the same name, it is advisable to use the UUID.

VBoxControl is frequently used in shell scripts for automating VM operations. For instance, it can be integrated into CI/CD pipelines to start, test, and then shut down virtual environments, or used in system administration tasks for scheduled backups or maintenance. Its simple syntax makes it ideal for quick command-line invocations.

While VBoxControl manipulates the VM from the host, VirtualBox also offers VBoxManage guestcontrol which allows execution of commands within the guest OS (if Guest Additions are running) and file transfer. VBoxControl operates at a lower level, managing the VM's hardware-level state.

VBoxControl has been an integral part of the VirtualBox command-line toolkit since early versions. While VBoxManage provides a comprehensive suite of management functions, VBoxControl specifically addresses the need for straightforward, direct control over a VM's power and runtime state. Its consistent availability across VirtualBox versions underscores its utility in scripting and automation workflows, reflecting VirtualBox's commitment to providing robust command-line interfaces for all core operations.

VBoxManage(1): The primary command-line tool for managing all aspects of VirtualBox, including VM creation, modification, network settings, and broader control. VBoxControl's functions are a subset of VBoxManage's capabilities, specifically focused on VM runtime state., VBoxSDL(1): A utility to run VirtualBox VMs in an SDL window.