VirtualBox on the command line: VBoxManage and VBoxHeadless

This is the first of many entries I’m hoping to write on using VirtualBox on the command line (i.e. with the server edition of your favorite unix-based OS; in my case Ubuntu) after having about a year’s worth of experience using the GUI version of the software. I’m no expert with VirtualBox, but I’ve found that it’s been a tremendous aid with my work, second only to git’s branching in allowing me to switch rapidly between several projects at once with minimal overhead.

Documenting usage of the software on the command line is great territory for some blog posts too. I keep pulling out the same note-covered, four-page printout of the VBoxManage usage string, because extenuating circumstances keep requiring machine administration. Instead of adding to the mess note-wise, I figured I’d do a little cleanup of my documentation and summarize the commands I’m using the most often.

The two command-line programs I’m using to administer VirtualBox are VBoxManage and VBoxHeadless. VBoxManage is the be-all, end-all program for creating, deleting, and configuring VMs and all their components. VBoxHeadless is the program used to run VMs on a headless server (such as Ubuntu Server Edition, like I’m using). It’s the server-edition equivalent of using the program VirtualBox on the command line, which is the “standard”, GUI version (and what you’ll see in your process list if you’re running a vm on the GUI version). (If you try running VirtualBox on the command line with a headless machine, like I sometimes do when I’m feeling especially tired and not thinking straight, you’ll get X11-related complaints.)

I inherited some pre-configured vms with this server, so the first thing I needed to do was learn how to start and stop my machine. Starting a virtual machine is possible with VBoxHeadless or with VBoxManage; most of the documentation I read recommended VBoxHeadless for my use case.

Here’s how I start a virtual machine called “addie_vm” on the command line:

VBoxHeadless -s addie_vm &

-s is a shortened version of the option –startvm, which is hopefully self-explanatory. You follow it up with either the vm name or its UUID (a unique identifier for the VM that I use in other circumstances but is much less human-readable).

You will want to run the process in the background using the ampersand, or you’ll lose access to your terminal.

Here’s the rough equivalent with VBoxManage (it appears to start up a few additional processes along with VBoxHeadless):

VBoxManage startvm addie_vm --type headless

Running in the background isn’t needed in this case.

I typically power off my virtual machine using the command

VBoxManage controlvm addies_vm poweroff

This is obviously preferrable to killing the VM process, which is the equivalent of manually powering off or unplugging your physical machine. Which is not to say I haven’t had to do either on occasion.

Next entry I will document how I’ve been creating and removing virtual machines and their hard disks, something I’ve had to do a lot of in recent days.

Share in the comments if there’s anything about this documentation that is missing to the detriment of my system; there are so many options within a program like VBoxManage that it’s easy to miss details (or glaze over them when reading documentation).

This entry was posted in Today I Learned... and tagged , , . Bookmark the permalink.

3 Responses to VirtualBox on the command line: VBoxManage and VBoxHeadless

  1. Nate says:

    The poweroff option actually does exactly what you don’t want to do – it powers off the machine the same way that pulling the plug does.

    You want VBoxManage controlvm addies_vm acpipowerbutton

  2. Chris P says:

    Wouldn’t it be preferrable to ssh into the VM and “shutdown -h now” as sudo/root?

  3. sukosevato says:

    sweet, I needed to know the “&” part to run it in the back ground. Thanks.

Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>