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