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## Mac OSX Setup (High Sierra) 11 12OSX platforms already have Git installed, however, installing the [Apple xCode](https://developer.apple.com/xcode/) developer kit and [xCode Command Line tools](https://developer.apple.com/xcode/features/) will provide UNIX command line tools such as make, awk, sed, ssh, tar, and zip. xCode can be installed through the App Store on you Mac. 13 14Quick start instructions for OSX: 15 161. Install Homebrew 172. Install Virtual Box Cask 183. Install Virtual Box Extentions 194. Install Vagrant Cask 20 21``` 22 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 23 brew doctor 24 brew update 25 brew cask install virtualbox 26 brew cask install virtualbox-extension-pack 27 brew cask install vagrant 28``` 29 30## Windows 10 Setup 31 321. Windows platforms should install [Git](https://git-scm.com/download/win) from git-scm.com. 33 - This provides everything needed to use git on Windows, including a `git-bash` command line environment. 342. Install [VirtualBox 5.1](https://www.virtualbox.org/wiki/Downloads) or newer 353. Install [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads) 364. Install and configure [Vagrant 1.9.4](https://www.vagrantup.com) or newer 37 38- Note: VirtualBox requires virtualization to be enabled in the BIOS. 39- Note: You should disable Hyper-V in Windows RS 3 laptop. Search `windows features` uncheck Hyper-V, restart laptop 40 41## Linux Setup 42 43Following 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). 44 45 Examples on Fedora26/Fedora27/Fedora28 46 471. yum check-update 482. yum update -y 493. yum install qt* 504. yum install libsdl* 515. 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) 526. VBoxManage extpack install Oracle_VM_VirtualBox_Extension_Pack-5.2.16.vbox-extpack(install the same pack as your installed version of VirtualBox) 537. rpm -ivh vagrant_2.1.2_x86_64.rpm 54 55 56## Configure Vagrant 57 58If you are behind a corporate firewall, configure the following proxy settings. 59 601. Set the http_proxy and https_proxy 612. Install the proxyconf plugin 62 63``` 64 $ export http_proxy=.... 65 $ export https_proxy=.... 66 $ vagrant plugin install vagrant-proxyconf 67``` 68 69## Download SPDK from GitHub 70 71Use 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. 72 73## Create a Virtual Box 74 75Use the `spdk/scripts/vagrant/create_vbox.sh` script to create a VM of your choice. Supported VM platforms are: 76 77- centos7 78- ubuntu16 79- ubuntu18 80- fedora26 81- fedora27 82- fedora28 83- freebsd11 84 85``` 86$ spdk/scripts/vagrant/create_vbox.sh -h 87 Usage: create_vbox.sh [-n <num-cpus>] [-s <ram-size>] [-x <http-proxy>] [-hvrld] <distro> 88 89 distro = <centos7 | ubuntu16 | ubuntu18 | fedora26 | fedora27 | fedora28 | freebsd11> 90 91 -s <ram-size> in kb default: 4096 92 -n <num-cpus> 1 to 4 default: 4 93 -x <http-proxy> default: "" 94 -p <provider> libvirt or virtualbox 95 --vhost-host-dir=<path> directory path with vhost test dependencies 96 (test VM qcow image, fio binary, ssh keys) 97 --vhost-vm-dir=<path> directory where to put vhost dependencies in VM 98 -r dry-run 99 -l use a local copy of spdk, don't try to rsync from the host. 100 -d deploy a test vm by provisioning all prerequisites for spdk autotest 101 -h help 102 -v verbose 103 104 Examples: 105 106 ./scripts/vagrant/create_vbox.sh -x http://user:password@host:port fedora27 107 ./scripts/vagrant/create_vbox.sh -s 2048 -n 2 ubuntu16 108 ./scripts/vagrant/create_vbox.sh -rv freebsd 109 ./scripts/vagrant/create_vbox.sh fedora26 110``` 111 112It 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: 113 114``` 115 $ spdk/scripts/vagrant/create_vbox.sh -s 2048 -n 2 fedora26 116``` 117 118This script will: 119 1201. create a subdirectory named <distro> in your $PWD 1212. copy the needed files from `spdk/scripts/vagrant/` into the <distro> directory 1223. create a working virtual box in the <distro> directory 1234. rsync the `~/.gitconfig` file to `/home/vagrant/` in the newly provisioned virtual box 1245. rsync a copy of the source `spdk` repository to `/home/vagrant/spdk_repo/spdk` (optional) 1256. rsync a copy of the `~/vagrant_tools` directory to `/home/vagrant/tools` (optional) 1267. execute vm_setup.sh on the guest to install all spdk dependencies (optional) 127 128This 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 initializaton. 129 130``` 131 $ cd <distro> 132 $ vagrant ssh 133``` 134 135## Finish VM Initializtion 136 137A 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: 138 139``` 140 $ script -c 'sudo spdk_repo/spdk/scripts/vagrant/update.sh' update.log 141``` 142 143The `update.sh` script completes initialization of the VM by automating the following steps. 144 1451. Runs yum/apt-get update (Linux) 1462. Runs the scripts/pdkdep.sh script 1473. Installs the FreeBSD source in /usr/sys (FreeBSD only) 148 149This 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. 150 151## Post VM Initializtion 152 153Following VM initializtion you must: 154 1551. Verify you have an emulated NVMe device 1562. Compile your spdk source tree 1573. Run the hello_world example to validate the environment is set up correctly 158 159### Verify you have an emulated NVMe device 160 161``` 162 $ lspci | grep "Non-Volatile" 163 00:0e.0 Non-Volatile memory controller: InnoTek Systemberatung GmbH Device 4e56 164``` 165 166### Compile SPDK 167 168``` 169 $ cd spdk_repo/spdk 170 $ git submodule update --init 171 $ ./configure --enable-debug 172 $ make 173``` 174 175### Run the hello_world example script 176 177``` 178 $ sudo scripts/setup.sh 179 $ cd examples/bdev/hello_world 180 $ sudo ./hello_bdev 181``` 182 183### Running autorun.sh with vagrant 184 185After 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. 186 187``` 188 $ cp spdk/scripts/vagrant/autorun-spdk.conf ~/ 189 $ spdk/scripts/vagrant/run-autorun.sh -h 190 Usage: scripts/vagrant/run-autorun.sh -d <path_to_spdk_tree> [-h] | [-q] | [-n] 191 -d : Specify a path to an SPDK source tree 192 -q : No output to screen 193 -n : Noop - dry-run 194 -h : This help 195 196 Examples: 197 run-spdk-autotest.sh -d . -q 198 run-spdk-autotest.sh -d /home/vagrant/spdk_repo/spdk 199``` 200 201## FreeBSD Appendix 202 203--- 204**NOTE:** As of this writing the FreeBSD Virtualbox instance does not correctly support the vagrant-proxyconf feature. 205--- 206 207The following steps are done by the `update.sh` script. It is recommened that you capture the output of `update.sh` with a typescript. E.g.: 208 209``` 210 $ script update.log sudo spdk_repo/spdk/scripts/vagrant/update.sh 211``` 212 2131. Updates the pkg catalog 2141. Installs the needed FreeBSD packages on the system by calling pkgdep.sh 2152. Installs the FreeBSD source in /usr/src 216 217``` 218 $ sudo pkg upgrade -f 219 $ sudo spdk_repo/spdk/scripts/pkgdep.sh 220 $ sudo git clone --depth 10 -b releases/11.1.0 https://github.com/freebsd/freebsd.git /usr/src 221``` 222 223To build spdk on FreeBSD use `gmake MAKE=gmake`. E.g.: 224 225``` 226 $ cd spdk_repo/spdk 227 $ git submodule update --init 228 $ ./configure --enable-debug 229 $ gmake MAKE=gmake 230``` 231