1 files changed, 86 insertions, 0 deletions
diff --git a/doc/README.vagrant b/doc/README.vagrant
new file mode 100644
index 00000000..88ff1a8c
--- /dev/null
+++ b/doc/README.vagrant
@@ -0,0 +1,86 @@
+1. Introduction
+
+Vagrant is a virtual machine management program that makes it trivial to build
+and configure reproducible virtual machines. Wireshark's source code includes
+a Vagrantfile which can be used to set up a complete development environments
+in a virtual machine, including all necessary compilers, dependent libraries,
+and tools like valgrind.
+
+Using vagrant can greatly simplify the creation of a Linux build environment
+for new developers, at the cost of running your builds in a virtual machine,
+thus with reduced performance.
+
+2. Installation
+
+The Vagrantfile included in Wireshark's source directory is configured to use
+VirtualBox as the backing virtual machine technology provider. You must first
+install VirtualBox from https://www.virtualbox.org/.
+
+Now install vagrant itself from https://www.vagrantup.com/.
+
+Please note that vagrant is a CLI command and should typically be installed in
+your host system's $PATH. To better understand what vagrant is doing you may
+want to review vagrant's `Getting Started` web pages.
+
+3. Setup
+
+By default vagrant looks for the file name Vagrantfile in the current
+directory. Wireshark's Vagrantfile is located in the root of the Wireshark
+source folder.
+
+Once both VirtualBox and vagrant are installed, setting up an Ubuntu Wireshark
+development VM is as simple as running `vagrant up ubuntu`.
+
+The first time that the `vagrant up` command is executed vagrant will initiate
+the download of a specific VM image (what they call a box) from HashiCorp's
+Atlas box catalog. Once the box is downloaded a VM will be instantiated and
+powered-on.
+
+Use the command `vagrant status` to determine the state of the VMs.
+
+The command `vagrant provision` will run any provisioning tasks defined in the
+Vagrantfile. Wireshark's Vagrantfile is configured to provision the machine
+and build the project using vagrant_build.sh.
+
+The vagrant_build.sh script sets up a cmake
+build environment which includes creating a ~/build folder initialized for an
+out-of-tree cmake build and then triggering a build.
+
+4. Usage
+
+Running `vagrant ssh ubuntu` from the Wireshark source directory will log you
+into Ubuntu VM as the userid vagrant.
+
+The Ubuntu VM's build folder is located in ~/build. The Ubuntu VM's source
+folder is actually the source folder from the host system mounted as
+/home/vagrant/wireshark. Any changes made in the VM's ~/wireshark folder are
+reflected in the host system's Wireshark source folder and vice-versa.
+
+Installing the vagrant-vbguest plugin is strongly recommended to get synced
+folders working on all boxes and other niceties. You can install it with the
+command `vagrant plugin install vagrant-vbguest`.
+
+Once logged into the VM issue the command `cd ~/build` followed by `make` to
+trigger a new wireshark build based on whatever is in your host system's source
+tree (the VM's ~/wireshark folder).
+
+The various Wireshark applications can be run from the ~/build folder of the
+VM with commands such as `./run/wireshark`, `./run/tshark`, etc.
+
+To run the Wireshark GUI you will need an X server and the X authority file
+utility (xauth) installed in the guest. For Ubuntu use `apt-get install xauth`,
+Fedora use `dnf install xorg-x11-xauth`.
+
+If you are using macOS ({Mac} OS X) as the host system then you would likely
+use XQuartz as your X server. XQuartz can be downloaded from
+https://www.xquartz.org/.
+
+The VM can be shutdown or suspended from the host system with the
+commands `vagrant halt` and `vagrant suspend` respectively. In either case the
+VM can be brought back up with the command `vagrant up`.
+
+5. Using Vagrant with multiple VMs
+Wireshark's Vagrantfile is configured with more than one box so most vagrant
+commands, those that apply to machines, need to be provided with the machine
+name. You can list all machines and their state with the `vagrant status`
+command.