ceph/src/spdk/doc/vagrant.md

   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
   6 NVMe enabled virtual machine sandbox running without the need for any
   7 special hardware.
   8 The Vagrant environment for SPDK has support for a variety of Linux distributions as well as FreeBSD.
   9 Run scripts/vagrant/create_vbox.sh -h to see the complete list.
  10 This environment requires Vagrant 1.9.4 or newer and
  11 VirtualBox 5.1 or newer with the matching VirtualBox extension pack.
  12
  13 Note: If you are behind a corporate firewall, set `http_proxy` and `https_proxy` in
  14 your environment before trying to start up the VM.  Also make sure that you
  15 have installed the optional vagrant module `vagrant-proxyconf`:
  16
  17 ~~~{.sh}
  18 export http_proxy=...
  19 export https_proxy=...
  20 vagrant plugin install vagrant-proxyconf
  21 ~~~
  22
  23 In case you want use kvm/libvirt you should also install `vagrant-libvirt`
  24
  25 # VM Configuration {#vagrant_config}
  26
  27 To create a configured VM with vagrant you need to run `create_vbox.sh` script.
  28
  29 Basically, the script will create a new sub-directory based on distribution you choose,
  30 copy the vagrant configuration file (a.k.a. `Vagrantfile`) to it,
  31 and run `vagrant up` with some settings defined by the script arguments.
  32
  33 By 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
  38 In order to modify some advanced settings like provisioning and rsyncing,
  39 you may want to change Vagrantfile source.
  40
  41 For additional support, use the Vagrant help function to learn how to destroy, restart, etc.
  42 Further below is sample output from a successful VM launch and execution of the NVMe hello
  43 world example application.
  44
  45 ~~~{.sh}
  46     vagrant --help
  47 ~~~
  48
  49 # Running An Example {#vagrant_example}
  50
  51 The following shows sample output from starting up a Ubuntu18 VM,
  52 compiling SPDK on it and running the NVMe sample application `hello_world`.
  53 If you don't see the NVMe device as seen below in both the `lspci` output as well as the
  54 application output, you likely have a VirtualBox and/or Vagrant
  55 versioning issue.
  56
  57 ~~~{.sh}
  58 user@dev-system:~$ cd spdk/scripts/vagrant
  59 user@dev-system:~/spdk/scripts/vagrant$ ./create_vbox.sh ubuntu18
  60 mkdir: created directory '/home/user/spdk/scripts/vagrant/ubuntu18'
  61 ~/spdk/scripts/vagrant/ubuntu18 ~/spdk/scripts/vagrant
  62 vagrant-proxyconf already installed... skipping
  63 Bringing 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
 118 Check the enviroment.
 119
 120 ~~~{.sh}
 121 user@dev-system:~/spdk/scripts/vagrant$ cd ubuntu18
 122 user@dev-system:~/spdk/scripts/vagrant/ubuntu18$ vagrant ssh
 123 Welcome to Ubuntu Bionic Beaver (development branch) (GNU/Linux 4.15.0-12-generic x86_64)
 124 <<some output trimmed>>
 125 vagrant@vagrant:~$ lspci | grep "Non-Volatile"
 126 00:0e.0 Non-Volatile memory controller: InnoTek Systemberatung GmbH Device 4e56
 127 vagrant@vagrant:~$ ls
 128 spdk_repo
 129 ~~~
 130
 131 Compiling SPDK and running an example.
 132
 133 ~~~{.sh}
 134 vagrant@vagrant:~/spdk_repo/spdk$ sudo apt update
 135 <<output trimmed>>
 136 vagrant@vagrant:~/spdk_repo/spdk$ sudo scripts/pkgdep.sh
 137 <<output trimmed>>
 138
 139 vagrant@vagrant:~/spdk_repo/spdk$ ./configure
 140 Creating mk/config.mk...done.
 141 Type 'make' to build.
 142
 143 vagrant@vagrant:~/spdk_repo/spdk$ make
 144 <<output trimmed>>
 145
 146 vagrant@vagrant:~/spdk_repo/spdk$ sudo ./scripts/setup.sh
 147 0000:00:0e.0 (80ee 4e56): nvme -> uio_pci_generic
 148
 149 vagrant@vagrant:~/spdk_repo/spdk$ sudo examples/nvme/hello_world/hello_world
 150 Starting 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 ]
 152 EAL: Detected 4 lcore(s)
 153 EAL: Detected 1 NUMA nodes
 154 EAL: Auto-detected process type: PRIMARY
 155 EAL: Multi-process socket /var/run/dpdk/spdk0/mp_socket
 156 EAL: Probing VFIO support...
 157 Initializing NVMe Controllers
 158 EAL: PCI device 0000:00:0e.0 on NUMA socket 0
 159 EAL:   probe driver: 80ee:4e56 spdk_nvme
 160 Attaching to 0000:00:0e.0
 161 Attached to 0000:00:0e.0
 162 Using controller ORCL-VBOX-NVME-VER12 (VB1234-56789        ) with 1 namespaces.
 163   Namespace ID: 1 size: 1GB
 164 Initialization complete.
 165 INFO: using host memory buffer for IO
 166 Hello world!
 167 ~~~