Please note that as of 2023-12-17, this project is archived and will not receive further updates or support from me.
However, the existing codebase will remain available for reference and use under the project's open-source license.
vagrant-vbguest is a Vagrant plugin which automatically installs the host's VirtualBox Guest Additions on the guest system.
Requires vagrant 1.3 or later
vagrant plugin install vagrant-vbguest
If you're lucky, vagrant-vbguest does not require any configuration.
However, here is an example of Vagrantfile
:
Vagrant.configure("2") do |config|
# we will try to autodetect this path.
# However, if we cannot or you have a special one you may pass it like:
# config.vbguest.iso_path = "#{ENV['HOME']}/Downloads/VBoxGuestAdditions.iso"
# or an URL:
# config.vbguest.iso_path = "http://company.server/VirtualBox/%{version}/VBoxGuestAdditions.iso"
# or relative to the Vagrantfile:
# config.vbguest.iso_path = "../relative/path/to/VBoxGuestAdditions.iso"
# set auto_update to false, if you do NOT want to check the correct
# additions version when booting this machine
config.vbguest.auto_update = false
# do NOT download the iso file from a webserver
config.vbguest.no_remote = true
end
iso_path
: The full path or URL to the VBoxGuestAdditions.iso file. iso_path
may contain the optional placeholder %{version}
replaced with detected VirtualBox version (e.g. 4.1.8
).
Relative paths are tricky, try to use an absolute path where possible. If not, the path is relative to the current working directory, that is where the vagrant
command is issued. You can make sure to always be relative to the Vagrantfile
with a little bit of ruby: File.expand_path("../relative/path/to/VBoxGuestAdditions.iso", __FILE__)
The default URI for the actual iso download is: https://download.virtualbox.org/virtualbox/%{version}/VBoxGuestAdditions_%{version}.iso
iso_upload_path
(String, default: /tmp
): A writeable directory where to put the VBoxGuestAdditions.iso file on the guest system.iso_mount_point
(String, default: /mnt
): Where to mount the VBoxGuestAdditions.iso file on the guest system.auto_update
(Boolean, default: true
) : Whether to check the correct additions version on each start (where start is not resuming a box).auto_reboot
(Boolean, default: true
when running as a middleware, false
when running as a command) : Whether to reboot the box after GuestAdditions has been installed, but not loaded.allow_downgrade
(Boolean, default: true
) : Allow to install an older version of Guest Additions onto the guest. (Eg. you are running a host with VirtualBox 5 and the box is already on 6).no_install
(Boolean, default: false
) : Whether to check the correct additions version only. This will warn you about version mis-matches, but will not try to install anything.no_remote
(Boolean, default: false
) : Whether to not download the iso file from a remote location. This includes any http
location!installer
(VagrantVbguest::Installers::Base
, optional) : Reference to a (custom) installer class or a named installer.
Build-in named installers are:
:arch
, :archlinux
, :arch_linux
: Arch Linux:centos
, :cent_os
: CentOS:debian
: Debian:fedora
: Fedora:opensuse
, :open_suse
: openSUSE:oracle
, :oraclelinux
, :oracle_linux
: Oracle Linux:redhat
, :red_hat
: Red Hat:suse
: SUSE:ubuntu
: Ubuntu:windows
: Windowsinstaller_arguments
(Array, default: ['--nox11']
) : List of additional arguments to pass to the installer. eg: %w{--nox11 --force}
would execute VBoxLinuxAdditions.run install --nox11 --force
installer_options
(Hash, default: {}
) : Configure how a Installer internally works. Should be set on a vm
level.installer_hooks
(Hash, default: {}
) : Configure scripts to be run before/after installer steps.yes
(Boolean or String, default: true
): Wheter to pipe yes
to the installer. If true
, executes yes | VBoxLinuxAdditions.run install
. With false
, the command is executed without yes
. You can also put in a string here for yes
(e.g. no
to refuse all messages)installer_options
)Those settings are specific for OS-specific installer. Especially in a multi-box environment, you should put those options on the box configuration like this:
Vagrant.configure("2") do |config|
config.vm.define "my_cent_os_box" do |c|
c.box = "centos/8"
c.vbguest.installer_options = { allow_kernel_upgrade: true }
end
end
Note that box-specific settings overwrite earlier settings:
Vagrant.configure("2") do |config|
config.vbguest.installer_options = { foo: 1, bar: 2 }
config.vm.define "a" do |box_config|
# not setting any `installer_options` will inherit the "global" ones
# installer_options => { foo: 1, bar: 2 }
end
config.vm.define "b" do |box_config|
# setting any `installer_options` will start from scratch
box_config.vbguest.installer_options[:zort] = 3 # => { zort: 3 }
end
config.vm.define "c" do |box_config|
# however, you can explicitly merge the global config
box_config.vbguest.installer_options = config.vbguest.installer_options.merge(zort: 3) # => { foo: 1, bar: 2, zort: 3 }
end
end
This option is available on all Linux type installers.
:running_kernel_modules
(default: ["vboxguest", "vboxsf"]
) The list used to check for the "running" state. Each of these modules need to appear at the beginning of a line in /proc/modules
.:allow_kernel_upgrade
(default: false
): If true
, instead of trying to find matching the matching kernel-devel package to the installed kernel version, the kernel will be updated and the (now matching) up-to-date kernel-devel will be installed. NOTE: This will trigger a reboot of the box.:reboot_timeout
(default: 300
): Maximum number of seconds to wait for the box to reboot after a kernel upgrade.:enablerepo
: (default: false
) Configure yum --enablerepo
settings. Possible values are:
"C*-base"
converts to --enablerepo=C*-base
['C*-base', 'C*-updates']
converts to --enablerepo=C*-base --enablerepo=C*-updates
true
: Enables C${release_version}-base
and C${release_version}-updates
with release_version read from /etc/centos-release
if the repo exists, otherwise *
.false
: Does not set any --enablerepo
Using Vagrantfile Load Order you may change default configuration values.
Edit (create, if missing) your ~/.vagrant.d/Vagrantfile
like this:
For Vagrant >= 1.1.0 use:
Vagrant.configure("2") do |config|
config.vbguest.auto_update = false
end
For older versions of Vagrant:
# vagrant's autoloading may not have kicked in
require 'vagrant-vbguest' unless defined? VagrantVbguest::Config
VagrantVbguest::Config.auto_update = false
Settings in a project's Vagrantfile
will overwrite those setting. When executed as a command, command line arguments will overwrite all of the above.
installer_hooks
)Additionally to the build-in installer_options
, you can configure to execute scripts around the install steps install
, rebuild
and start
.
Accepts either a single command or and array of commands. Box-specific settings overwrite earlier settings, just like with installer_options
.
Use this make changes to the guest, for example to install specific dependencies or tweak the network setup.
before_install
/after_install
: Runs before/after the install step. That is before uploading the iso file into the guest and after unmounting the iso file.before_rebuild
/after_rebuild
: Runs before/after the installer runs a command to let the GuestAdditions rebuild itself.before_start
/after_start
: Runs before/after the installer runs a command to start the GuestAdditions service.Vagrant.configure("2") do |config|
config.vm.define "my_cent_os_box" do |c|
c.vbguest.installer_hooks[:before_install] = ["yum install -y epel-release", "sleep 1"]
end
end
Running as a middleware is the default way of using vagrant-vbguest.
It will run automatically right after the box started. This is each time the box boots, i.e. vagrant up
or vagrant reload
.
It won't run on vagrant resume
(or vagrant up
a suspended box) to save you some time resuming a box.
You may switch off the middleware by setting the vm's config vbguest.auto_update
to false
.
This is a per box setting. On multi vm environments you need to set that for each vm.
When vagrant-vbguest is running it will provide you some logs:
[...]
[default] Booting VM...
[default] Booting VM...
[default] Waiting for VM to boot. This can take a few minutes.
[default] VM booted and ready for use!
[default] GuestAdditions versions on your host (4.2.6) and guest (4.1.0) do not match.
stdin: is not a tty
Reading package lists...
Building dependency tree...
Reading state information...
The following extra packages will be installed:
fakeroot linux-headers-2.6.32-33 patch
[...]
[default] Copy iso file /Applications/VirtualBox.app/Contents/MacOS/VBoxGuestAdditions.iso into the box /tmp/VBoxGuestAdditions.iso
stdin: is not a tty
[default] Installing Virtualbox Guest Additions 4.2.6 - guest version is 4.1.0
stdin: is not a tty
Verifying archive integrity... All good.
Uncompressing VirtualBox 4.2.6 Guest Additions for Linux...........
VirtualBox Guest Additions installer
Removing installed version 4.1.0 of VirtualBox Guest Additions...
tar: Record size = 8 blocks
Removing existing VirtualBox DKMS kernel modules ...done.
Removing existing VirtualBox non-DKMS kernel modules ...done.
Building the VirtualBox Guest Additions kernel modules ...done.
Doing non-kernel setup of the Guest Additions ...done.
You should restart your guest to make sure the new modules are actually used
Installing the Window System drivers ...fail!
(Could not find the X.Org or XFree86 Window System.)
stdin: is not a tty
[default] Restarting VM to apply changes...
[default] Attempting graceful shutdown of VM...
[default] Booting VM...
[default] Waiting for VM to boot. This can take a few minutes.
[default] VM booted and ready for use!
[default] Configuring and enabling network interfaces...
[default] Setting host name...
[default] Mounting shared folders...
[default] -- v-root: /vagrant
[default] -- v-csc-1: /tmp/vagrant-chef-1/chef-solo-1/cookbooks
[default] Running provisioner: Vagrant::Provisioners::ChefSolo...
[default] Generating chef JSON and uploading...
[default] Running chef-solo...
[...]
The plugin's part starts at [default] Installing Virtualbox Guest Additions 4.1.14 - guest's version is 4.1.1
, telling you that:
No worries on the Installing the Window System drivers ...fail!
. Most dev boxes you are using won't run a Window Server, thus it's absolutely safe to ignore that error.
When everything is fine, and no update is needed, you see log like:
[...]
[default] Booting VM...
[default] Waiting for VM to boot. This can take a few minutes.
[default] VM booted and ready for use!
[default] GuestAdditions 4.2.6 running --- OK.
[...]
When you switched off the middleware auto update, or you have a box up and running you may also run the installer manually.
vagrant vbguest [vm-name] [--do start|rebuild|install] [--status] [-f|--force] [-b|--auto-reboot] [-R|--no-remote] [--iso VBoxGuestAdditions.iso] [--no-cleanup]
For example, when you just updated VirtualBox on your host system, you should update the guest additions right away. However, you may need to reload the box to get the guest additions working.
If you want to check the guest additions version, without installing, you may run:
vagrant vbguest --status
Telling you either about a version mismatch:
[default] GuestAdditions versions on your host (4.2.6) and guest (4.1.0) do not match.
or a match:
[default] GuestAdditions 4.2.6 running --- OK.
The auto-reboot
is turned off by default when running as a command. Vbguest will suggest you to reboot the box when needed. To turn it on simply pass the --auto-reboot
parameter:
vagrant vbguest --auto-reboot
You can also pass vagrant's reload
options like:
vagrant vbguest --auto-reboot --no-provision
When running the install step manually like this: vagrant vbguest --do install
, adding --no-cleanup
keeps the downloaded, uploaded files and mounted iso in their place. Happy debugging ;)
vagrant-vbguest will try to autodetect a VirtualBox GuestAdditions iso file on your system, which usually matches your installed version of VirtualBox. If it cannot find one, it downloads one from the web (virtualbox.org).
Those places will be checked in order:
/usr/share/virtualbox/VBoxGuestAdditions.iso
/Applications/VirtualBox.app/Contents/MacOS/VBoxGuestAdditions.iso
%PROGRAMFILES%/Oracle/VirtualBox/VBoxGuestAdditions.iso
The VirtualBox GuestAdditions Installer will try to load the newly built kernel module. However the installer may fail to load, just as it is happening when updating GuestAdditions from version 4.1 to 4.2.
Hence, vbguest will check for a loaded kernel module after the installation has finished and reboots the box, if it could not find one.
vagrant-vbguest provides installers for generic linux and debian/ubuntu.
Installers take care of the whole installation process, that includes where to save the iso file inside the guest and where to mount it.
class MyInstaller < VagrantVbguest::Installers::Linux
# use /temp instead of /tmp
def tmp_path
'/temp/VBoxGuestAdditions.iso'
end
# use /media instead of /mnt
def mount_point
'/media'
end
def install(opts=nil, &block)
communicate.sudo('my_distos_way_of_preparing_guestadditions_installation', opts, &block)
# calling `super` will run the installation
# also it takes care of uploading the right iso file into the box
# and cleaning up afterward
super
end
end
Vagrant::Config.run do |config|
config.vbguest.installer = MyInstaller
end
If you find yourself copying the same installer in each of your vagrant project, it might be a good idea to make it a plugin itself. Like vagrant-vbguest itself, installers can be distributed as ruby gems
This project contains a sample installer gem which might serve as an boilerplate.
Bug reports and pull requests are welcome on GitHub at https://github.com/dotless-de/vagrant-vbguest.
For the foreseeable future, no more pull requests will be accepted which add new guest support/installers. Please build your gem as a plugin to vbguest (see "Very Advanced Usage" section of this file). In fact, please open a pull request to remove support for a guest system if feel confident that your solution is better.
/tmp
but can be overwritten with the iso_upload_path
option./mnt
but can be overwritten with the iso_mount_point
option.vagrant gem install vagrant-vbguest
). Try C:\vagrant\vagrant\embedded\bin\gem.bat install vagrant-vbguest
instead. (See issue #19)