From e4ba6dbc3f1e76890b22773807ea37fe8fa2b1bc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:34:10 +0200 Subject: Adding upstream version 4.2.2. Signed-off-by: Daniel Baumann --- doc/README.vagrant | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 doc/README.vagrant (limited to 'doc/README.vagrant') 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. -- cgit v1.2.3