1# SPDK Vagrant and VirtualBox 2 3The following guide explains how to use the scripts in the `spdk/scripts/vagrant`. Mac, Windows, and Linux platforms are supported. 4 51. Install and configure [Git](https://git-scm.com/) on your platform. 62. Install [VirtualBox 5.1](https://www.virtualbox.org/wiki/Downloads) or newer 73. Install* [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads) 84. Install and configure [Vagrant 1.9.4](https://www.vagrantup.com) or newer 9 10* Note: The extension pack has different licensing than main VirtualBox, please 11 review them carefully as the evaluation license is for personal use only. 12 13## Mac OSX Setup (High Sierra) 14 15Quick start instructions for OSX: 16 171. Install Homebrew 182. Install Virtual Box Cask 193. Install Virtual Box Extension Pack* 204. Install Vagrant Cask 21 22* Note: The extension pack has different licensing than main VirtualBox, please 23 review them carefully as the evaluation license is for personal use only. 24 25``` 26 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 27 brew doctor 28 brew update 29 brew cask install virtualbox 30 brew cask install virtualbox-extension-pack 31 brew cask install vagrant 32``` 33 34## Windows 10 Setup 35 361. Windows platforms should install some form of git. 372. Install [VirtualBox 5.1](https://www.virtualbox.org/wiki/Downloads) or newer 383. Install* [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads) 394. Install and configure [Vagrant 1.9.4](https://www.vagrantup.com) or newer 40 41* Note: The extension pack has different licensing than main VirtualBox, please 42 review them carefully as the evaluation license is for personal use only. 43 44- Note: VirtualBox requires virtualization to be enabled in the BIOS. 45- Note: You should disable Hyper-V in Windows RS 3 laptop. Search `windows features` un-check Hyper-V, restart laptop 46 47## Linux Setup 48 49Following the generic instructions should be sufficient for most Linux distributions. For more thorough instructions on installing VirtualBox on your distribution of choice, please see the following [guide](https://www.virtualbox.org/wiki/Linux_Downloads). 50 51 Examples on Fedora26/Fedora27/Fedora28 52 531. yum check-update 542. yum update -y 553. yum install qt* 564. yum install libsdl* 575. rpm -ivh VirtualBox-5.2-5.2.16_123759_fedora26-1.x86_64.rpm (select the right version in https://www.virtualbox.org/wiki/Linux_Downloads) 586. VBoxManage extpack install Oracle_VM_VirtualBox_Extension_Pack-5.2.16.vbox-extpack(install the same pack* as your installed version of VirtualBox) 597. rpm -ivh vagrant_2.1.2_x86_64.rpm 60 61* Note: The extension pack has different licensing than main VirtualBox, please 62 review them carefully as the evaluation license is for personal use only. 63 64## Configure Vagrant 65 66If you are behind a corporate firewall, configure the following proxy settings. 67 681. Set the http_proxy and https_proxy 692. Install the proxyconf plugin 70 71``` 72 $ export http_proxy=.... 73 $ export https_proxy=.... 74 $ vagrant plugin install vagrant-proxyconf 75``` 76 77## Download SPDK from GitHub 78 79Use git to clone a new spdk repository. GerritHub can also be used. See the instructions at [spdk.io](http://www.spdk.io/development/#gerrithub) to setup your GerritHub account. Note that this spdk repository will be rsync'd into your VM, so you can use this repository to continue development within the VM. 80 81## Create a Virtual Box 82 83Use the `spdk/scripts/vagrant/create_vbox.sh` script to create a VM of your choice. Supported VM platforms are: 84 85- centos7 86- ubuntu16 87- ubuntu18 88- fedora26 89- fedora27 90- fedora28 91- freebsd11 92 93``` 94$ spdk/scripts/vagrant/create_vbox.sh -h 95 Usage: create_vbox.sh [-n <num-cpus>] [-s <ram-size>] [-x <http-proxy>] [-hvrld] <distro> 96 97 distro = <centos7 | ubuntu16 | ubuntu18 | fedora26 | fedora27 | fedora28 | freebsd11> 98 99 -s <ram-size> in kb default: 4096 100 -n <num-cpus> 1 to 4 default: 4 101 -x <http-proxy> default: "" 102 -p <provider> libvirt or virtualbox 103 --vhost-host-dir=<path> directory path with vhost test dependencies 104 (test VM qcow image, fio binary, ssh keys) 105 --vhost-vm-dir=<path> directory where to put vhost dependencies in VM 106 -r dry-run 107 -l use a local copy of spdk, don't try to rsync from the host. 108 -d deploy a test vm by provisioning all prerequisites for spdk autotest 109 -h help 110 -v verbose 111 112 Examples: 113 114 ./scripts/vagrant/create_vbox.sh -x http://user:password@host:port fedora27 115 ./scripts/vagrant/create_vbox.sh -s 2048 -n 2 ubuntu16 116 ./scripts/vagrant/create_vbox.sh -rv freebsd 117 ./scripts/vagrant/create_vbox.sh fedora26 118``` 119 120It is recommended that you call the `create_vbox.sh` script from outside of the spdk repository. Call this script from a parent directory. This will allow the creation of multiple VMs in separate <distro> directories, all using the same spdk repository. For example: 121 122``` 123 $ spdk/scripts/vagrant/create_vbox.sh -s 2048 -n 2 fedora26 124``` 125 126This script will: 127 1281. create a subdirectory named <distro> in your $PWD 1292. copy the needed files from `spdk/scripts/vagrant/` into the <distro> directory 1303. create a working virtual box in the <distro> directory 1314. rsync the `~/.gitconfig` file to `/home/vagrant/` in the newly provisioned virtual box 1325. rsync a copy of the source `spdk` repository to `/home/vagrant/spdk_repo/spdk` (optional) 1336. rsync a copy of the `~/vagrant_tools` directory to `/home/vagrant/tools` (optional) 1347. execute vm_setup.sh on the guest to install all spdk dependencies (optional) 135 136This arrangement allows the provisioning of multiple, different VMs within that same directory hierarchy using the same spdk repository. Following the creation of the vm you'll need to ssh into your virtual box and finish the VM initialization. 137 138``` 139 $ cd <distro> 140 $ vagrant ssh 141``` 142 143## Finish VM Initialization 144 145A copy of the `spdk` repository you cloned will exist in the `spdk_repo` directory of the `/home/vagrant` user account. After using `vagrant ssh` to enter your VM you must complete the initialization of your VM by running the `scripts/vagrant/update.sh` script. For example: 146 147``` 148 $ script -c 'sudo spdk_repo/spdk/scripts/vagrant/update.sh' update.log 149``` 150 151The `update.sh` script completes initialization of the VM by automating the following steps. 152 1531. Runs yum/apt-get update (Linux) 1542. Runs the scripts/pdkdep.sh script 1553. Installs the FreeBSD source in /usr/sys (FreeBSD only) 156 157This only needs to be done once. This is also not necessary for Fedora VMs provisioned with the -d flag. The `vm_setup` script performs these operations instead. 158 159## Post VM Initialization 160 161Following VM initialization you must: 162 1631. Verify you have an emulated NVMe device 1642. Compile your spdk source tree 1653. Run the hello_world example to validate the environment is set up correctly 166 167### Verify you have an emulated NVMe device 168 169``` 170 $ lspci | grep "Non-Volatile" 171 00:0e.0 Non-Volatile memory controller: InnoTek Systemberatung GmbH Device 4e56 172``` 173 174### Compile SPDK 175 176``` 177 $ cd spdk_repo/spdk 178 $ git submodule update --init 179 $ ./configure --enable-debug 180 $ make 181``` 182 183### Run the hello_world example script 184 185``` 186 $ sudo scripts/setup.sh 187 $ sudo scripts/gen_nvme.sh --json-with-subsystems > ./build/examples/hello_bdev.json 188 $ sudo ./build/examples/hello_bdev --json ./build/examples/hello_bdev.json -b Nvme0n1 189``` 190 191### Running autorun.sh with vagrant 192 193After running vm_setup.sh the `run-autorun.sh` can be used to run `spdk/autorun.sh` on a Fedora vagrant machine. Note that the `spdk/scripts/vagrant/autorun-spdk.conf` should be copied to `~/autorun-spdk.conf` before starting your tests. 194 195``` 196 $ cp spdk/scripts/vagrant/autorun-spdk.conf ~/ 197 $ spdk/scripts/vagrant/run-autorun.sh -h 198 Usage: scripts/vagrant/run-autorun.sh -d <path_to_spdk_tree> [-h] | [-q] | [-n] 199 -d : Specify a path to an SPDK source tree 200 -q : No output to screen 201 -n : Noop - dry-run 202 -h : This help 203 204 Examples: 205 run-spdk-autotest.sh -d . -q 206 run-spdk-autotest.sh -d /home/vagrant/spdk_repo/spdk 207``` 208 209## FreeBSD Appendix 210 211--- 212**NOTE:** As of this writing the FreeBSD Virtualbox instance does not correctly support the vagrant-proxyconf feature. 213--- 214 215The following steps are done by the `update.sh` script. It is recommended that you capture the output of `update.sh` with a typescript. E.g.: 216 217``` 218 $ script update.log sudo spdk_repo/spdk/scripts/vagrant/update.sh 219``` 220 2211. Updates the pkg catalog 2221. Installs the needed FreeBSD packages on the system by calling pkgdep.sh 2232. Installs the FreeBSD source in /usr/src 224 225``` 226 $ sudo pkg upgrade -f 227 $ sudo spdk_repo/spdk/scripts/pkgdep.sh --all 228 $ sudo git clone --depth 10 -b releases/11.1.0 https://github.com/freebsd/freebsd.git /usr/src 229``` 230 231To build spdk on FreeBSD use `gmake MAKE=gmake`. E.g.: 232 233``` 234 $ cd spdk_repo/spdk 235 $ git submodule update --init 236 $ ./configure --enable-debug 237 $ gmake MAKE=gmake 238``` 239