1# Vagrant Development Environment {#vagrant} 2 3## Introduction {#vagrant_intro} 4 5[Vagrant](https://www.vagrantup.com/) provides a quick way to get a basic 6NVMe enabled virtual machine sandbox running without the need for any 7special hardware. 8The Vagrant environment for SPDK has support for a variety of Linux distributions as well as FreeBSD. 9Run scripts/vagrant/create_vbox.sh -h to see the complete list. 10This environment requires Vagrant 1.9.4 or newer and 11VirtualBox 5.1 or newer with the matching VirtualBox extension pack. 12 13Note: If you are behind a corporate firewall, set `http_proxy` and `https_proxy` in 14your environment before trying to start up the VM. Also make sure that you 15have installed the optional vagrant module `vagrant-proxyconf`: 16 17~~~{.sh} 18export http_proxy=... 19export https_proxy=... 20vagrant plugin install vagrant-proxyconf 21~~~ 22 23In case you want use kvm/libvirt you should also install `vagrant-libvirt` 24 25## VM Configuration {#vagrant_config} 26 27To create a configured VM with vagrant you need to run `create_vbox.sh` script. 28 29Basically, the script will create a new sub-directory based on distribution you choose, 30copy the vagrant configuration file (a.k.a. `Vagrantfile`) to it, 31and run `vagrant up` with some settings defined by the script arguments. 32 33By default, the VM created is configured with: 34 35- 2 vCPUs 36- 4G of RAM 37- 2 NICs (1 x NAT - host access, 1 x private network) 38 39In order to modify some advanced settings like provisioning and rsyncing, 40you may want to change Vagrantfile source. 41 42For additional support, use the Vagrant help function to learn how to destroy, restart, etc. 43Further below is sample output from a successful VM launch and execution of the NVMe hello 44world example application. 45 46~~~{.sh} 47 vagrant --help 48~~~ 49 50## Running An Example {#vagrant_example} 51 52The following shows sample output from starting up a Ubuntu18 VM, 53compiling SPDK on it and running the NVMe sample application `hello_world`. 54If you don't see the NVMe device as seen below in both the `lspci` output as well as the 55application output, you likely have a VirtualBox and/or Vagrant 56versioning issue. 57 58~~~{.sh} 59user@dev-system:~$ cd spdk/scripts/vagrant 60user@dev-system:~/spdk/scripts/vagrant$ ./create_vbox.sh ubuntu18 61mkdir: created directory '/home/user/spdk/scripts/vagrant/ubuntu18' 62~/spdk/scripts/vagrant/ubuntu18 ~/spdk/scripts/vagrant 63vagrant-proxyconf already installed... skipping 64Bringing machine 'default' up with 'virtualbox' provider... 65==> default: Box 'bento/ubuntu-18.04' could not be found. Attempting to find and install... 66 default: Box Provider: virtualbox 67 default: Box Version: 201803.24.0 68==> default: Loading metadata for box 'bento/ubuntu-18.04' 69 default: URL: https://vagrantcloud.com/bento/ubuntu-18.04 70==> default: Adding box 'bento/ubuntu-18.04' (v201803.24.0) for provider: virtualbox 71 default: Downloading: https://vagrantcloud.com/bento/boxes/ubuntu-18.04/versions/201803.24.0/providers/virtualbox.box 72==> default: Box download is resuming from prior download progress 73==> default: Successfully added box 'bento/ubuntu-18.04' (v201803.24.0) for 'virtualbox'! 74==> default: Importing base box 'bento/ubuntu-18.04'... 75==> default: Matching MAC address for NAT networking... 76==> default: Setting the name of the VM: ubuntu18_default_1237088131451_82174 77==> default: Fixed port collision for 22 => 2222. Now on port 2202. 78==> default: Clearing any previously set network interfaces... 79==> default: Preparing network interfaces based on configuration... 80 default: Adapter 1: nat 81 default: Adapter 2: hostonly 82==> default: Forwarding ports... 83 default: 22 (guest) => 2202 (host) (adapter 1) 84==> default: Running 'pre-boot' VM customizations... 85==> default: Booting VM... 86==> default: Waiting for machine to boot. This may take a few minutes... 87 default: SSH address: 127.0.0.1:2202 88 default: SSH username: vagrant 89 default: SSH auth method: private key 90 default: Warning: Remote connection disconnect. Retrying... 91 default: Warning: Connection reset. Retrying... 92<<some output trimmed>> 93 default: Warning: Connection reset. Retrying... 94 default: Warning: Remote connection disconnect. Retrying... 95 default: 96 default: Vagrant insecure key detected. Vagrant will automatically replace 97 default: this with a newly generated keypair for better security. 98 default: 99 default: Inserting generated public key within guest... 100 default: Removing insecure key from the guest if it's present... 101 default: Key inserted! Disconnecting and reconnecting using new SSH key... 102==> default: Machine booted and ready! 103==> default: Checking for guest additions in VM... 104==> default: Configuring and enabling network interfaces... 105==> default: Configuring proxy for Apt... 106==> default: Configuring proxy environment variables... 107==> default: Rsyncing folder: /home/user/spdk/ => /home/vagrant/spdk_repo/spdk 108==> default: Mounting shared folders... 109 default: /vagrant => /home/user/spdk/scripts/vagrant/ubuntu18 110==> default: Running provisioner: file... 111 112 SUCCESS! 113 114 cd to ubuntu18 and type "vagrant ssh" to use. 115 Use vagrant "suspend" and vagrant "resume" to stop and start. 116 Use vagrant "destroy" followed by "rm -rf ubuntu18" to destroy all trace of vm. 117~~~ 118 119Check the environment. 120 121~~~{.sh} 122user@dev-system:~/spdk/scripts/vagrant$ cd ubuntu18 123user@dev-system:~/spdk/scripts/vagrant/ubuntu18$ vagrant ssh 124Welcome to Ubuntu Bionic Beaver (development branch) (GNU/Linux 4.15.0-12-generic x86_64) 125<<some output trimmed>> 126vagrant@vagrant:~$ lspci | grep "Non-Volatile" 12700:0e.0 Non-Volatile memory controller: InnoTek Systemberatung GmbH Device 4e56 128vagrant@vagrant:~$ ls 129spdk_repo 130~~~ 131 132Compiling SPDK and running an example. 133 134~~~{.sh} 135vagrant@vagrant:~/spdk_repo/spdk$ sudo apt update 136<<output trimmed>> 137vagrant@vagrant:~/spdk_repo/spdk$ sudo scripts/pkgdep.sh 138<<output trimmed>> 139 140vagrant@vagrant:~/spdk_repo/spdk$ ./configure 141Creating mk/config.mk...done. 142Type 'make' to build. 143 144vagrant@vagrant:~/spdk_repo/spdk$ make 145<<output trimmed>> 146 147vagrant@vagrant:~/spdk_repo/spdk$ sudo ./scripts/setup.sh 1480000:00:0e.0 (80ee 4e56): nvme -> uio_pci_generic 149 150vagrant@vagrant:~/spdk_repo/spdk$ sudo build/examples/hello_world 151Starting SPDK v18.10-pre / DPDK 18.05.0 initialization... 152[ DPDK EAL parameters: hello_world -c 0x1 --legacy-mem --file-prefix=spdk0 --base-virtaddr=0x200000000000 --proc-type=auto ] 153EAL: Detected 4 lcore(s) 154EAL: Detected 1 NUMA nodes 155EAL: Auto-detected process type: PRIMARY 156EAL: Multi-process socket /var/run/dpdk/spdk0/mp_socket 157EAL: Probing VFIO support... 158Initializing NVMe Controllers 159EAL: PCI device 0000:00:0e.0 on NUMA socket 0 160EAL: probe driver: 80ee:4e56 spdk_nvme 161Attaching to 0000:00:0e.0 162Attached to 0000:00:0e.0 163Using controller ORCL-VBOX-NVME-VER12 (VB1234-56789 ) with 1 namespaces. 164 Namespace ID: 1 size: 1GB 165Initialization complete. 166INFO: using host memory buffer for IO 167Hello world! 168~~~ 169