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!