doc/README.vagrant

   1 1. Introduction
   2
   3 Vagrant is a virtual machine management program that makes it trivial to build
   4 and configure reproducible virtual machines. Wireshark's source code includes
   5 a Vagrantfile which can be used to set up a complete development environments
   6 in a virtual machine, including all necessary compilers, dependent libraries,
   7 and tools like valgrind.
   8
   9 Using vagrant can greatly simplify the creation of a Linux build environment
  10 for new developers, at the cost of running your builds in a virtual machine,
  11 thus with reduced performance.
  12
  13 2. Installation
  14
  15 The Vagrantfile included in Wireshark's source directory is configured to use
  16 VirtualBox as the backing virtual machine technology provider. You must first
  17 install VirtualBox from https://www.virtualbox.org/.
  18
  19 Now install vagrant itself from https://www.vagrantup.com/.
  20
  21 Please note that vagrant is a CLI command and should typically be installed in
  22 your host system's $PATH. To better understand what vagrant is doing you may
  23 want to review vagrant's `Getting Started` web pages.
  24
  25 3. Setup
  26
  27 By default vagrant looks for the file name Vagrantfile in the current
  28 directory. Wireshark's Vagrantfile is located in the root of the Wireshark
  29 source folder.
  30
  31 Once both VirtualBox and vagrant are installed, setting up an Ubuntu Wireshark
  32 development VM is as simple as running `vagrant up ubuntu`.
  33
  34 The first time that the `vagrant up` command is executed vagrant will initiate
  35 the download of a specific VM image (what they call a box) from HashiCorp's
  36 Atlas box catalog. Once the box is downloaded a VM will be instantiated and
  37 powered-on.
  38
  39 Use the command `vagrant status` to determine the state of the VMs.
  40
  41 The command `vagrant provision` will run any provisioning tasks defined in the
  42 Vagrantfile. Wireshark's Vagrantfile is configured to provision the machine
  43 and build the project using vagrant_build.sh.
  44
  45 The vagrant_build.sh script sets up a cmake
  46 build environment which includes creating a ~/build folder initialized for an
  47 out-of-tree cmake build and then triggering a build.
  48
  49 4. Usage
  50
  51 Running `vagrant ssh ubuntu` from the Wireshark source directory will log you
  52 into Ubuntu VM as the userid vagrant.
  53
  54 The Ubuntu VM's build folder is located in ~/build. The Ubuntu VM's source
  55 folder is actually the source folder from the host system mounted as
  56 /home/vagrant/wireshark. Any changes made in the VM's ~/wireshark folder are
  57 reflected in the host system's Wireshark source folder and vice-versa.
  58
  59 Installing the vagrant-vbguest plugin is strongly recommended to get synced
  60 folders working on all boxes and other niceties. You can install it with the
  61 command `vagrant plugin install vagrant-vbguest`.
  62
  63 Once logged into the VM issue the command `cd ~/build` followed by `make` to
  64 trigger a new wireshark build based on whatever is in your host system's source
  65 tree (the VM's ~/wireshark folder).
  66
  67 The various Wireshark applications can be run from the ~/build folder of the
  68 VM with commands such as `./run/wireshark`, `./run/tshark`, etc.
  69
  70 To run the Wireshark GUI you will need an X server and the X authority file
  71 utility (xauth) installed in the guest. For Ubuntu use `apt-get install xauth`,
  72 Fedora use `dnf install xorg-x11-xauth`.
  73
  74 If you are using macOS ({Mac} OS X) as the host system then you would likely
  75 use XQuartz as your X server. XQuartz can be downloaded from
  76 https://www.xquartz.org/.
  77
  78 The VM can be shutdown or suspended from the host system with the
  79 commands `vagrant halt` and `vagrant suspend` respectively. In either case the
  80 VM can be brought back up with the command `vagrant up`.
  81
  82 5. Using Vagrant with multiple VMs
  83 Wireshark's Vagrantfile is configured with more than one box so most vagrant
  84 commands, those that apply to machines, need to be provided with the machine
  85 name. You can list all machines and their state with the `vagrant status`
  86 command.