Category: linux

In my three previous posts (Post 1, Post 2, Post 3), I detailed the steps involved in setting up a Debian Vagrant box on Windows 10.  It contains lots of explanations and screenshots; if you know what you’re doing, and you just want to see the steps, this is the post for you!

Install the vagrant-vbguest plugin, if you don’t have it installed already:

vagrant plugin install vagrant-vbguest

Create the Vagrantfile:

vagrant init debian/buster64

Update the Vagrantfile by adding the following lines to the appropriate locations:

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

config.vm.provider "virtualbox" do |vb|
  vb.gui = true
  vb.memory = "2048"
  vb.customize ["modifyvm", :id, "--vram", "12"]
end

Start up the VM.  This will download the Vagrant box if required, then create the VM, start it up, and install the VirtualBox Guest Additions:

vagrant up

SSH in to the VM, update the software, and install the GUI software:

vagrant ssh
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get autoremove
sudo tasksel install xfce-desktop

Reboot the system, and maximize the GUI window after the system has booted:

logout
vagrant halt
vagrant up

Log in to the GUI (username vagrant, password vagrant).

And, you’re done!

This is the third post in a series explaining how to set up a Debian Vagrant box on a Windows 10 machine.  In the first post, I talk about how to download a Debian base box from the Hashicorp atlas repository of base boxes, and how to create a Virtual Machine from that base box.  In the second post, I describe how to install the VirtualBox Guest Additions into your Debian box, and how to configure a shared folder between the VM and your Windows host machine.  In this post, I describe how to install a GUI.

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!

Setting up your Vagrantfile

We’re going to make some configuration changes to our Vagrantfile, so if your VM is currently running, shut it down:

vagrant halt

The first thing we’re going to want to do is to set up our Vagrantfile to configure VirtualBox with our Vagrant box.  There are some minor changes we need if we’re going to run a GUI on our VM. Open up your Vagrantfile in your favourite text editor.  Find the section of commented out lines that begin with “Provider-specific configuration”:

Add the following lines after that section:

config.vm.provider "virtualbox" do |vb|
  vb.gui = true
  vb.memory = "2048"
  vb.customize ["modifyvm", :id, "--vram", "12"]
end

This part of my file now looks like:

What this does is configures VirtualBox.  If you are using a different provider, say VMware, you’ll need to do something different; that’s outside the scope of this post.

What these lines do is as follows:

• “vb.gui = true”: configures VirtualBox to appear when it is run.  Up until now, when we start up our VM, we don’t actually see it. This line changes that.
• “vb.memory = “2048””: assigns 2GB to your virtual machine.  This isn’t necessary for running a GUI, but the default of 512MB isn’t enough for the development work I do.  If you don’t have a lot of memory on your Windows host machine, leave this line out.
• “vb.customize [“modifyvm”, :id, “–vram”, “12”]”: assigns 12MB of video RAM to the virtual video card.  The default is 8MB, and that’s not quite enough to run full-screen on my 1920×1080 display. The minimum is 9MB, but I like to give myself a bit of wiggle room.

Installing the GUI

Now that we’ve got the Vagrantfile set up, start up the VM:

vagrant up

The VM will start as normal, but what will be different is that you’ll see the VirtualBox GUI running.  We’ll just ignore it for now, and continue to ssh into our VM.

vagrant ssh

If it’s been a while since you set up your VM, you may want to make sure you’ve got all the latest packages, although this isn’t always necessary.  I do it for completeness. Execute these commands inside your SSH session:

sudo apt-get update
sudo apt-get upgrade

Now, there’s a single command that we need to execute to install the GUI.  I’m installing the XFCE desktop; it’s nice and simple and easy to use.

sudo tasksel install xfce-desktop

This command now goes out and downloads all the required packages, then installs them.  Be warned that this is a slow process; when I did this as I was writing this post, it required downloading 944 packages!  Also, know that if you want to wipe out your VM and recreate it with “vagrant destroy / vagrant up”, you’re going to have to download all these packages again.  But, sometimes that can’t be helped…

Once the download and install completes, log out of your SSH session, reboot the VM, and it will start up with the GUI!

logout
vagrant halt
vagrant up

Using the GUI

Once your VM boots, you’ll have a GUI window:

You can use this window as-is, but it’s kind of small.  I always maximize it. The first time you do this it’s going to look kind of strange:

Not a concern, as it will fix itself when we log in.  Now, log in on the GUI, using the username of vagrant and the password of vagrant.  The GUI will log you in, and resize to use the full screen:

And, you’re done!  You’ve now got a Debian box with a GUI running in Vagrant!

Shutting down the VM

When I’m done working with the GUI, I always first log out of the GUI (Applications / Log Out from the XFCE menu, then choose Log Out), then I switch to my Windows command prompt window and do a “vagrant halt”.  I don’t know if this is necessary, but it’s probably good practice: it lets the Debian GUI cleanly shut down, and then lets Vagrant cleanly shut down. It’s probably not a problem to just shut down the VM from the GUI, but I’m a little anal-retentive that way….

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.

Update on July 23, 2019: Since the time I originally made this post, Debian has moved from version 9.6 Stretch to 10.0 Buster.  I’ve updated the post accordingly.  Thankfully, nothing changed but the name of the Vagrant box to use!  If you still want to use Stretch, replace everywhere that it says stretch64 with buster64.  Some of your error messages may be different, though…

Lately, for my Linux development, I’ve been using Vagrant, using VirtualBox as a provider.  In Vagrant, I set up a Debian box and do my development on that. It’s nice and easy to set up, and if I want to restart with a clean installation of Debian, it’s very easy to do.

I’ll write three posts about how I set it up.  In this first post, I detail the steps that I use to create a basic Debian box, with no GUI.  In my second post, I describe the steps I use to set up VirtualBox’s Guest Additions, so that I can share files between my host Windows system and my Debian Vagrant box.  In the third post, I give the steps that I use to set up a GUI.

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!

Debian’s Vagrant Box

The Debian project provides standard Vagrant boxes in the Vagrant Cloud box catalog.  You can read about them on the Debian wiki, and look at the provided boxes on https://app.vagrantup.com/debian/.  The latest version of Debian is version 10, codenamed Buster.  At the time of writing this post, the latest point release was 10.0, and I’m using the 64-bit version of Debian.  So, the Vagrant box I’m using is debian/buster64.

The Debian Vagrant box provides a standard basic Debian system, containing all packages with priority required, important, and standard.  Note that it does NOT include a GUI; you’re just going to get a command-line version. We’ll look at how to set up a GUI in the third post.

Prerequisites

To set this up, you need to have both VirtualBox and Vagrant installed.  You can download VirtualBox from the website https://www.virtualbox.org.  The download page is https://www.virtualbox.org/wiki/Downloads, and the installation instructions are in Chapter 2 of the User Manual. You can download Vagrant from the website https://www.vagrantup.com, where the download page is at https://www.vagrantup.com/downloads.html, and the installation instructions are at https://www.vagrantup.com/intro/getting-started/install.html.  I installed VirtualBox first, then Vagrant.  I don’t know if the order matters, but it made sense to me, and I know that works!

Creating the Vagrantfile

Once you’ve got Vagrant and VirtualBox installed, you’re going to want to create the configuration file for your box.  This file is called Vagrantfile. I’ve created a folder under my home directory called vagrant-VMs, and underneath that, another folder called buster.  I’ve created multiple folders under vagrant-VMs, one for each Vagrant configuration, but in this post, I’m only discussing my Buster installation.

Here’s looking at my folder in File Explorer:

Open a command prompt, then change to the vagrant-VMs\buster folder:

cd vagrant-VMs\buster

Next, use Vagrant to create the Vagrantfile for us:

vagrant init debian/buster64

This will create the Vagrantfile that configures the usage of the Vagrant box.  The box won’t actually be downloaded until you try to bring the box up for the first time.

Here’s a screenshot.

You might want to take a look at the Vagrantfile; it’s just a text file (actually, a Ruby program file), so you can look at it in your favourite text editor, such as Notepad, Notepad++, or Vim.  There’s actually very little in the file; most of it is commented-out configuration, giving examples of things you may want to configure. But, for now, we’ll just leave things as they are.

Here’s a screenshot of the complete file (click to view it larger):

Creating the Virtual Machine

The next step is to create and start up the virtual machine.  We’ll use the “vagrant up” command to do that.  The first time you run this, it will connect to the Hashicorp atlas (a repository of Vagrant boxes, maintained by the developers of Vagrant) and download a copy of the box (called the “base box”).  Then, it will create a virtual machine as a copy of the downloaded base box; subsequent executions will just use the virtual machine you’ve already created.

Note: Vagrant creates a folder to hold all its configuration data under your home directory, with the name .vagrant.d.  If you’re curious where the downloaded base box goes, it goes underneath that folder, in a subfolder named boxes. On Windows, I use File History to back up my files; because these boxes are so big, and because I can easily re-download them, I don’t want to back them up, so I configure File History to not backup the .vagrant.d\boxes folder.  There’s another folder that I also don’t back up, but I’ll mention that next…

Second note: the virtual machine gets created in a folder in your home directory called “VirtualBox VMs”.  Once again, I don’t want to back these up, so I add this folder to my list of excluded folders in File History.  You may want to back them up, but as I said before, you can easily recreate these VMs, so it’s a waste of backup space to back them up.

OK, so let’s create our Virtual Machine:

vagrant up

You’ll see a whole bunch of messages.  Vagrant goes through the following steps when it creates the VM:

• Imports the debian/buster64 base box and uses it to create a new VM
• Configures the networking of the new VM
• Boots the VM, and waits for the booting to complete
• Uses SSH to connect to the VM, and replaces the SSH key in the VM (more on that later)
• Checks to see if the VirtualBox guest additions are installed.

You’ll now see one of two messages about the VirtualBox guest additions.  If they are not installed in the Vagrant box (they shouldn’t be, but version 10.0.0 of the box seems to include them), you’ll get a scary error message telling you that you should install them, and that a lot of things won’t work until you install them.  Ignore that for now; I’ll look at installing the guest additions in my next post.  If they are installed (version 10.0.0, I’m looking at you!), you may get a slightly less scary message that the guest additions on the VM don’t match the installed version of VirtualBox.  Don’t worry about that, as we’ll install the proper version in the next post.

At the time of writing, I also get a VERY scary error message about attempting to rsync a shared folder.  Once again, don’t worry about that; we’ll resolve that in the next post as well.

With regards to SSH: the buster64 box that was downloaded from the Hashicorp atlas has a well-known SSH key, but you really want that to be secret.  But, if it was secret, we wouldn’t be able to connect to the VM. So, when we first bring up the VM, Vagrant connects to the VM using the well-known key, then generates a secret key, and replaces the well-known key with our new secret key.  Finally, it disconnects and reconnects using the new key, just to make sure everything is working OK.

Here’s a screenshot of all the output (click to enlarge):

You’ll notice that it doesn’t appear that the VM is running.  The “vagrant up” command completes and returns us to the command prompt, and there isn’t a VirtualBox GUI.  But, don’t worry, VirtualBox is running; you just can’t see it! If you really want, you can start up Windows’ Task Manager, and see the VBoxHeadless process listed under Background Processes.  Or, you can start up VirtualBox, and you’ll see that you’ve got a running VM!

Bringing Debian Up-to-date

There may be security patches issued by Debian that aren’t incorporated into your imported box.  The next thing we’re going to do is to bring all the software up-to-date.

Log in to the VM using the “vagrant ssh” command:

vagrant ssh

This will connect to the VM using SSH, and will log you in to an account named “vagrant”.  This account was present in the Vagrant box you downloaded; it’s a standard convention used by Vagrant boxes.  If you ever need to log in without using the “vagrant ssh” command, the password is also “vagrant”.

Here’s a screenshot:

Once you’re logged in, you’ll be at the Debian command prompt.  We’ll want to execute the following commands:

sudo apt-get update
sudo apt-get upgrade

The first command will connect to the Debian package repository, and download a list of all of the latest versions of Debian packages.  The second command will download and install any packages that have been updated in the repository since the Vagrant base box was created.

Here’s a screenshot of executing the update:

and another of executing the upgrade (click to enlarge).  Note that your packages being updated almost certainly will be different from mine.

Depending on which packages have been updated, there are two other possible commands you may need to execute.  If you get a message about some packages being held back, execute this command:

sudo apt-get dist-upgrade

And, if you get a message that some packages are no longer needed, you can remove them with:

sudo apt-get autoremove

Actually, there’s really no harm in executing both of these commands anyways, since we’re setting up a new VM; they just might not do anything.

And now, we’re done!  We’ve got an up-to-date Debian system running.

Log out of the SSH session to return to the Windows command prompt:

logout

Shutting down the Virtual Machine

The last thing to do is to shut down the virtual machine.  That’s very easy to do from the Windows command prompt. Execute:

vagrant halt

And you’ll get a message that Vagrant is gracefully shutting down the virtual machine.

Next time you want to start the VM back up, just go to your vagrant-VMs\buster folder (or whatever you called it), and re-execute “vagrant up”.  It won’t need to recreate the VM; it’ll just use it as it was the last time you used it.

Do you want to clean up?

For completeness, I should mention how you can clean up what you’ve done.

If you want to delete the VM that you created, execute:

vagrant destroy

That will delete the virtual machine.  You can easily recreate the VM, though, just be executing “vagrant up” again.  This is a nice easy way to start your VM over fresh if you mess it up somehow. It leaves your Vagrantfile intact, so any configuration changes you made in there will be used the next time you recreate the virtual machine.  But, any changes you made inside the VM (such as updating Debian!) will need to be redone.

If you also want to remove the base box, execute:

vagrant box remove debian/buster64

If you want to use it again, you’ll need to re-download it; executing “vagrant up” will automatically do that for you if you need it.

Next steps

It’s very useful to have the VirtualBox guest additions installed on your system; I detail how to do that in my next post.  This will allow you to share files between your VM and your Windows machine that the VM is running on. Also, if you’re running a GUI (which I’ll describe how to set up in my third post), it allows you to resize the window, which is very handy!