Installing VirtualBox Guest Additions in a Debian Vagrant box on Windows 10

Short answer: Use the vagrant-vbguest plugin to make things easy!

This is the second post in a series of three that describe how I set up my Debian development environment in Vagrant on Windows 10, using VirtualBox as the provider.  The first post shows how to set up a basic, command-line only, Debian box. The third describes how to install a GUI. In this post, I describe how to install the VirtualBox Guest Additions.

If you know what you’re doing, and you want to skip all the explanations and just see the steps involved, feel free to look at my summary!

Note: this blog post was written with Debian 9 Stretch, but I’ve tested it with 10 Buster, and everything works the same.  The screenshots will vary slightly, but everything works good!

What does the VirtualBox Guest Additions offer?

According to the VirtualBox User Manual, installing the Guest Additions provides the following advantages (read the User Manual for more details):

• Mouse pointer integration: makes it easier to use the mouse between the virtual machine and your Windows host)
• Shared folders: makes accessing files between your VM and your Windows host easier
• Better video support: not a big deal if you’re doing command-line only work, but if you’re using a GUI, it makes a huge difference.  For me, I like to resize the GUI, and when I do that, the screen in Debian automatically resizes. Very nice.
• Seamless windows: I’ve never actually used this.  Read the manual for what it is (as I should do!).
• Generic host/guest communication channels: Something else I’ve never used….
• Time synchronization: synchronizes the time between your VM and the Windows host.  If you ever pause your VM, this is really nice because it automatically updates the time in the VM when you unpause.  Not something you’ll ever notice when you’re using it, but you will notice if you don’t have this feature!
• Shared clipboard: Easy cut-and-paste between your VM and the Windows host.
• Automated logons (credentials passing): Never used this, so I can’t really comment.

What’s involved in installing the VirtualBox Guest Additions?

You’re probably convinced now that having the VirtualBox Guest Additions installed is a good thing.  Unfortunately, getting them installed is normally a bit of a pain. They are distributed within VirtualBox as an ISO file, which you can mount as a CD-ROM on your VM.  Then, you run the install script, and everything happens nice (hopefully): installing new device drivers, adding kernel modules, etc., etc. But, the problem I had, is that I need to have a bunch of software installed in my VM before I can install the Guest Additions.  I suppose that’s not that hard, I just need to figure out what I need first. I could even record the list of required software in a blog post!

Another problem is that every time you upgrade your version of VirtualBox, or the kernel in the virtual machine, you need to re-install the Guest Additions.  If you don’t, things likely still will work, but it’s better to be safe than sorry. VirtualBox will warn you if you’re running a different version of the Guest Additions, but you’ll need to update them yourself.

But, there’s a better way!

Using the vagrant-vbguest plugin

Vagrant allows you to extend its functionality using plugins.  There is a plugin, called vagrant-vbguest, that does all of the hard work for you involved in setting up the Guest Additions.  Once you’ve got it installed, every time you run vagrant, it will check to see if the Guest Additions are installed, and at the correct version; if not, it will automatically install them (or upgrade them) for you.  It will even automatically install the software required to do the installation!

I ALWAYS use the vagrant-vbguest plugin.  It’s possible to use plugins on a per-VM basis (I’ve read, anyways, but I’ve never tried it), but it makes things so much simpler, why would you not want to do it?

Installing the vagrant-vbguest plugin

Installing the vagrant-vbguest plugin is VERY easy.  Just execute:

vagrant plugin install vagrant-vbguest

This will go out to the Internet, download the plugin, and install it in Vagrant.

And that’s all there is to it!

Installing the VirtualBox Guest Additions with the vagrant-vbguest plugin

The wonderful thing about this plugin is, once it’s installed, you don’t have to do anything else!  Every time you start up a Vagrant box with “vagrant up”, the plugin will ensure that the Guest Additions are installed; if they’re not, it will install it for you.  Here we go:

vagrant up

And here’s some screenshots of the plugin in action.  First, the VM boots as usual:

Then, Vagrant checks to see if the Guest Additions are installed:

Next, it checks to see if the packages required to install the Guest Additions are installed in the VM; if they’re not, it installs them:

I’m not going to bother showing the installation of these 34 packages.  After they are installed, Vagrant mounts the Guest Additions ISO from VirtualBox into our VM:

Then, it actually installs the Guest Additions:

And finally, it starts up the Guest Additions, unmounts the ISO, and finishes the “vagrant up”:

Because we’ve made changes to the kernel, I always like to reboot the system after installing the Guest Additions.  Maybe it’s not necessary, but I prefer to be safe. Just shut it down and restart:

vagrant halt
vagrant up

You’ll now see, as part of the bootup sequence, that Vagrant checks to ensure that the Guest Additions are installed and running:

Setting up shared folders in your VM

Now that we’ve got the Guest Additions installed in the VM, let’s set up shared folders, so that we can easily access our Windows files in our VM, and vice-versa.  What we’ll do is set up a single folder that will be shared between the VM and the Windows host. First, shut down the VM:

vagrant halt

Now, use your favourite text editor to edit the “Vagrantfile” configuration file.  Within that file, you’ll find some lines like:

We’re going to add a new line after this to specify how we want to set up our shared folder.  What I’m going to do is have the current folder (the one with Vagrantfile in it) show up in my VM in the location /vagrant.  To do this, add the following line after the lines above:

config.vm.synced_folder ".", "/vagrant", type: "virtualbox"

This tells Vagrant to mount the current folder (“.”) on the Windows host into the VM at location “/vagrant”, and to use a VirtualBox shared folder.  There is also an “rsync” way of sharing folders, but that requires installing additional software on both Windows and the VM, and it doesn’t automatically sync the files.  I much prefer the VirtualBox shared folders. Anyways, that section of my Vagrantfile now looks like:

Start Vagrant back up:

vagrant up

You’ll notice in the bootup sequence a message indicating the shared folder:

Using the shared folders

Let’s actually try out the shared folders.  First, ssh into the VM:

vagrant ssh

If, from within the VM, you look at the contents of the /vagrant directory, you’ll see:

which is the same as what you see in File Explorer in Windows (not counting the hidden .vagrant folder!):

If you look at the contents of the Vagrantfile in the VM, you’ll see that it is the same as the file on Windows — they are the same file!

Next, try creating a file in the VM:

And you’ll see it’s also visible in Windows:

So, if you ever want to move files between the VM and the Windows host, just drop them in the appropriate folder, and you’re good to go!

Cleaning up

If you want to remove the plugin from Vagrant, it’s pretty easy to do:

vagrant plugin uninstall vagrant-vbguest

Note that this only uninstalls the plugin, it does not uninstall the VirtualBox Guest Additions.  If you do want to uninstall the Guest Additions, I’d suggest destroying the box, and recreating:

vagrant destroy
vagrant up

I personally prefer having the Guest Additions installed, so I always have the plugin installed.

What’s next?

In the first post, I looked at how you can set up a basic Debian box in Vagrant.  But, it’s command-line only. That’s OK for an old Unix hacker like me, but if you prefer a GUI, the next post talks about how to do that.