» Boxes

As with every Vagrant provider, theVagrant VMware providers have a custom box format.

This page documents the format so that you can create your own base boxes.Note that currently you must make these base boxes by hand. A future releaseof Vagrant will provide additional mechanisms for automatically creating suchimages.

Note: This is a reasonably advanced topic thata beginning user of Vagrant does not need to understand. If you arejust getting started with Vagrant, skip this and use an availablebox. If you are an experienced user of Vagrant and want to createyour own custom boxes, this is for you.

Prior to reading this page, please understand thebasics of the box file format.

» Contents

A VMware base box is a compressed archive of the necessary contentsof a VMware "vmwarevm" file. Here is an example of what is containedin such a box:

  1. $ tree
  2. .
  3. |-- disk-s001.vmdk
  4. |-- disk-s002.vmdk
  5. |-- ...
  6. |-- disk.vmdk
  7. |-- metadata.json
  8. |-- precise64.nvram
  9. |-- precise64.vmsd
  10. |-- precise64.vmx
  11. |-- precise64.vmxf
  13. 0 directories, 17 files

The files that are strictly required for a VMware machine to function are:nvram, vmsd, vmx, vmxf, and vmdk files.

There is also the "metadata.json" file used by Vagrant itself. This filecontains nothing but the defaults which are documented on thebox format page.

When bringing up a VMware backed machine, Vagrant copies all of the contentsin the box into a privately managed "vmwarevm" folder, and uses the first"vmx" file found to control the machine.

Vagrant 1.8 and higher support linked clones. Prior versionsof Vagrant do not support linked clones. For more information onlinked clones, please see the documentation.

» VMX Whitelisting

Settings in the VMX file control the behavior of the VMware virtual machinewhen it is booted. In the past Vagrant has removed the configured networkdevice when creating a new instance and inserted a new configuration. Withthe introduction of "predictable network interface names" thisapproach can cause unexpected behaviors or errors with VMware Vagrant boxes.While some boxes that use the predictable network interface names are configuredto handle the VMX modifications Vagrant makes, it is better if Vagrant doesnot make the modification at all.

Vagrant will now warn if a whitelisted setting is detected within a Vagrantbox VMX file. If it is detected, a warning will be shown alerting the userand providing a configuration snippet. The configuration snippet can beused in the Vagrantfile if Vagrant fails to start the virtual machine.

» Making compatible boxes

These are the VMX settings the whitelisting applies to:

  • ethernet*.pcislotnumberIf the newly created box does not depend on Vagrant's existing behavior ofmodifying this setting, it can disable Vagrant from applying the modificationby adding a Vagrantfile to the box with the following content:
  1. Vagrant.configure("2") do |config|
  2.   config.vm.provider "vmware_desktop" do |vmware|
  3.     vmware.whitelist_verified = true
  4.   end
  5. end

This will prevent Vagrant from displaying a warning to the user as well asdisable the VMX settings modifications.

» Installed Software

Base boxes for VMware should have the following software installed, asa bare minimum:

  • SSH server with key-based authentication setup. If you want the box towork with default Vagrant settings, the SSH user must be set to acceptthe insecure keypairthat ships with Vagrant.

  • VMware Tools so that things such as sharedfolders can function. There are many other benefits to installing the tools,such as improved networking performance.

» Optimizing Box Size

Prior to packaging up a box, you should shrink the hard drives as much aspossible. This can be done with vmware-vdiskmanager which is usuallyfound in /Applications/VMware Fusion.app/Contents/Library for VMware Fusion. You firstwant to defragment then shrink the drive. Usage shown below:

  1. $ vmware-vdiskmanager -d /path/to/main.vmdk
  2. ...
  3. $ vmware-vdiskmanager -k /path/to/main.vmdk
  4. ...

» Packaging

Remove any extraneous files from the "vmwarevm" folderand package it. Be sure to compress the tar with gzip (done below in asingle command) since VMware hard disks are not compressed by default.

  1. $ cd /path/to/my/vm.vmwarevm
  2. $ tar cvzf custom.box ./*