VirtualBox: thorny path from GUI to headless command-line interface

In this post I am telling my story about moving from Windows-hosted Oracle VirtualBox machines to the headless linux-hosted way

VirtualBox: thorny path from GUI to headless command-line interface

This post, as I already promised on Twitter, is going to be a story behind bash scripts, which I recently shared on GitHub. Their purpose is to simplify management of headless Oracle VirtualBox virtual machines on linux-based host systems. So, in case you would like to know how I ended up with them, carry on reading!

Low start

It happened that I use virtual machines on my Windows desktop PC as development and testing environments for some of my projects. This is very convenient, because first - I sandbox my working environment from my personal stuff and have an ability to save states of the machines when needed. In example, when I'm not sure with some process or feature, I like testing them, but I'd rather create a snapshot before I begin - I find this function really useful. And this is very easy since VirtualBox has simple and clean graphical interface.

But, as you know, sometimes things change. My customer demanded to be able to look at and test the application, I develop for them, before I deploy it to production. And, this wasn't suitable for me to keep my laptop switched on for the whole day long to enable customer's employees to estimate the application. So, I decided to move my virtual machines to my tiny home server.

However, that wasn't that easy, since the operation system, which I have on the server, is CentOS Linux without any X Window System (only the command line with bash is available). And, I didn't want to lose in convenience.

Setting up VirtualBox

So, the first thing which I faced was installation of VirtualBox itself. There're several options to do this. In example, it's possible to download Linux packages for a vast majority of distributions right from official website. But, I'd have needed to resolve all the dependencies manually in this case.

That's why I preferred the most recommended way on the web - to install it from official repository. Luckily, there're a number of good instructions on how to do it, which makes the installation process as easy as a pie.

And, ten minutes later, VirtualBox was succesfully installed on my Linux system. The issue was that I still didn't have graphical interface on my server and wasn't going to start using it, so, I started the research on alternatives to it.

Overview of VirtualBox alternative front-ends

In fact, there're a few additional options to the standard and well-known Qt-based VirtualBox interface as it is given in the documentation:

  • VBoxSDL is an alternative, simple graphical front-end with an intentionally limited feature set, designed to only display virtual machines. It's here just for mention since this option is another type of graphical interface, which wasn't suitable for me.
  • VBoxManage is a command-line interface tool for automated and very detailed control of every aspect of VirtualBox. This sounded exactly like something I looked for.
  • Finally, VBoxHeadless is yet another front-end that produces no visible output on the host at all. As opposed to the other graphical interfaces, the headless front-end requires no graphics support.

Actually, as I found out a bit later, on a server without any GUI, the one needs to combine leveraging of vboxmanage and vboxheadless. In such a case the first one is used to control the virtual machines, their settings and states, when the second is used to run headless instances of them.

I want it easy

I can't put this in words what I felt when saw vboxmanage docs for the first time. This command-line tool is very powerful and have a lot of options, hence not that easy for a newcomer. Especially when you are used to the convinience of the standard GUI.

So, what I wanted is a set of scripts which would be very easy to use and kind of repeat the GUI functionality for the features, mostly used by me. Basically, I needed scripts for starting, stopping, powering off specified virtual machines and for managing of machines snapshots, since I'm an active user of them.

That's where I came up with an idea to write a set of scripts which would be able to take command line arguments on the one hand and user input on the other, when the argument is not provided. And you already know what I had as a result of my efforts.

Usage of the scripts is very easy - just give them the execute permission and hit the enter button on a desired script. Optionally, it's possible to specify a command line argument, in example, when you want to automate powering on of a particular virtual machine on system startup.

To put it simple, the main purpose of the scripts is to enable the user to control their headless virtual machines with a hit on a button instead of leveraging of the complex command-line utility vboxmanage, which is almost as convinient as using the GUI.

Moving the VMs

It wasn't hard for me to move the virtual machines, I even didn't have to export/import them. Everything which I did was copying virtual machines files from my laptop to the server. Then, using the prepared register script, I just registered them with the new environment and that's it.

Though, things weren't that easy, because my machines didn't start after moving. There were two reasons why. First - I use bridged network on my VMs, and they didn't see the bridging interface anymore (since it was from my desktop), second - 3d-acceleration feature was not supported on the headless environment and I needed to switch it off before running the VMs.

To fix this, I had to run these two commands for each VM:

vboxmanage modifyvm <VM_NAME> --nic1 bridged --bridgeadapter1 <INTERFACE_NAME>
vboxmanage modifyvm <VM_NAME> --accelerate3d off

Where <VM_NAME> is the name of a VM and <INTERFACE_NAME> is the name of the bridging network interface (determined by ifconfig, for instance).

After doing so, I succesfully powered on all my virtual machines with my brand new script.

What do I do with the VM without interface?

I think some of you would ask me what to do with a headless VM? The answer is to use it remotely. Since I still prefer setting up my machines on my laptop, I always enable some way of remote control of the VM. If guest operation system is a unix-based one, it's usually enough for me to have the SSH daemon enabled. If it's a VM with Windows, then you can always set up Remote Desktop. Then I move them to the server for the further exploitation.

Alternatively, it's possible to intall VirtualBox extention pack and set up VRPD, which is kind of extention of standard remote desktop protocol. This is very useful if you want to create a VM on your server from scratch, though this is a totally different story.


As it appeared, it's more than possible to manage VirtualBox machines using only command line. Maybe that's not as convenient as usage of GUI, but I hope my scripts will simplify the most common tasks not only for me, but for somebody else.

To make it short, you need to perform these steps to complete movement of your VMs from GUI to headless CLI:

  1. Set up and configure your VMs on your desktop system, in example on your laptop, using convenient GUI.
  2. Install VirtualBox on your Linux server system.
  3. Move all VMs files to the server.
  4. Register your VMs using vboxmanage or my script.
  5. (Optional) Fix the bridging network interface and 3D acceleration issues.
  6. Manage you VMs using my bunch of scripts or vboxmanage and vboxheadless utilities directly.
  7. Use your VMs remotely through SSH or RDP.
  8. ...
  9. PROFIT!

Do not hesitate to comment on them and on the approach in general. I'm sure there're many other good options of how to do the same things. I didn't pay much attention to the teleporting feature of VirtualBox environment, for example, though it might be quite suitable for a similar case to the one I was talking about in this article.