Vagrant is awesome and most of the time things just work, but like any piece of software, occasionally things go wrong or don’t quite function as planned. I’ve gathered all the issues I’ve run into here and included things you can do to solve them. Hopefully they can help you to get where you’re going quickly. If you’re new to Vagrant, check out my tutorial here:
Sometimes it may become necessary to boot a machine with monitor attached for debugging. In these cases you’ll usually see a message like the following:
SSH connection was refused! This usually happens if the VM failed to
boot properly. Some steps to try to fix this: First, try reloading your
VM with `vagrant reload`, since a simple restart sometimes fixes things.
If that doesn't work, destroy your VM and recreate it with a `vagrant destroy`
followed by a `vagrant up`. If that doesn't work, contact a Vagrant
maintainer (support channels listed on the website) for more assistance.
You can have a look at what is going on by adding the following to your Vagrantfile:
config.vm.boot_mode = :gui
You should now be able to log in via the console as user vagrant with password vagrant. Once in, you should have the ability to become root using sudo to have a look at logs or make changes to the system.
[vagrant@vm-localhost ~]$ sudo su -
Occasionally you’ll try and boot a VM and Vagrant will get tired of waiting to connect via SSH before the machine is fully booted. You can increase the number of attempts as well as the maximum length of time vagrant will wait by massaging the following variables in the Vagrantfile
web_config.ssh.timeout = 300
web_config.ssh.max_tries = 300
By default, a Vagrant VM gets 384 Megabytes of RAM. Depending on what you’re actually running in the virtual machine, this might not be enough. You can adjust the RAM allocated to a VM in the Vagrantfile as well.
config.vm.customize do |vm| vm.memory_size = 512 end
Occasionally, you might boot up a VM and see a message such as the following:
[default] The guest additions on this VM do not match the install version of
VirtualBox! This may cause things such as forwarded ports, shared
folders, and more to not work properly. If any of those things fail on
this machine, please update the guest additions and repackage the
Guest Additions Version: 4.0.4
VirtualBox Version: 4.1.4
This is letting you know that the Virtual Box tools installed in the VM don’t match the Virtual Box version you are running on your system. We can fix this issue without doing a complete reinstall of our Base Box from scratch. Inside the VM you’ll need to have the appropriate version of the kernel headers package for your platform installed. In addition, you’ll need to ensure you have GCC
apt-get install linux-headers-$(uname -r) gcc
The RHEL or Centos equivalent:
yum install kernel-headers-$(uname -r) gcc
You need to download the guest additions from the Virtual Box website that match the version of Virtual Box you have installed. I prefer to do this outside the VM in the same directory as my Vagrantfile. This allows me to reuse the downloaded iso from in other VMs I have defined rather than download it over and over. To download version 4.1.4:
From inside the VM, we’ll need to mount the ISO file we downloaded. The trick to making this happen is to mount it as a loop device.
[root@vm-localhost ~]# mount -o loop /vagrant/VBoxGuestAdditions_4.1.4.iso /mnt
Next we must move to the mounted ISO file and run the installer. Like me, you might get an error about the Window System drivers. This is just an artifact of my VM not having X11 installed.
[root@vm-localhost ~]# cd /mnt [root@vm-localhost mnt]# ./VBoxLinuxAdditions.run Verifying archive integrity... All good. Uncompressing VirtualBox 4.1.4 Guest Additions for Linux......... VirtualBox Guest Additions installer Removing installed version 4.0.4 of VirtualBox Guest Additions... Removing existing VirtualBox DKMS kernel modules [ OK ] Removing existing VirtualBox non-DKMS kernel modules [ OK ] Building the VirtualBox Guest Additions kernel modules Not building the VirtualBox advanced graphics driver as this Linux version is too old to use it. Building the main Guest Additions module [ OK ] Building the shared folder support module [ OK ] Doing non-kernel setup of the Guest Additions [ OK ] You should restart your guest to make sure the new modules are actually used Installing the Window System drivers [FAILED] (Could not find the X.Org or XFree86 Window System.) [root@vm-localhost mnt]# cd ~ [root@vm-localhost ~]# umount /mnt
At this point, you can call vagrant reload to reboot the running VM and with a bit of patience, you should see that the message about mismatched versions has disappeared. Great! We’ve fixed our VM, but wait, our base box is still broken. We don’t want to do this every time we make a new image from it. Luckily vagrant provides us with a handy tool for converting a VM to a base box.
$ vagrant halt
[default] Attempting graceful shutdown of linux...
[default] Forcing shutdown of VM...
$ vagrant package
[default] Clearing any previously set forwarded ports...
[default] Cleaning previously set shared folders...
[default] Creating temporary directory for export...
[default] Exporting VM...
[default] Compressing package to: /Users/zsprackett/test/package.box
We can now either import it as a new base box and update our Vagrantfiles to use it, or we can remove the old one and replace it with the new one.
$ vagrant box remove Centos-5.7-x86_64-test.box
[vagrant] Deleting box 'Centos-5.7-x86_64-test.box'...
$ vagrant box add Centos-5.7-x86_64-test.box package.box
[vagrant] Downloading with Vagrant::Downloaders::File...
[vagrant] Copying box to temporary location...
[vagrant] Extracting box...
[vagrant] Verifying box...
[vagrant] Cleaning up downloaded box...