ceph/src/spdk/scripts/vagrant/README.md

   1 # SPDK Vagrant and VirtualBox
   2
   3 The following guide explains how to use the scripts in the `spdk/scripts/vagrant`. Mac, Windows, and Linux platforms are supported.
   4
   5 1. Install and configure [Git](https://git-scm.com/) on your platform.
   6 2. Install [VirtualBox 5.1](https://www.virtualbox.org/wiki/Downloads) or newer
   7 3. Install [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads)
   8 4. Install and configure [Vagrant 1.9.4](https://www.vagrantup.com) or newer
   9
  10 ## Mac OSX Setup (High Sierra)
  11
  12 OSX 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
  14 Quick start instructions for OSX:
  15
  16 1. Install Homebrew
  17 2. Install Virtual Box Cask
  18 3. Install Virtual Box Extentions
  19 4. 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
  32 1. 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.
  34 2. Install [VirtualBox 5.1](https://www.virtualbox.org/wiki/Downloads) or newer
  35 3. Install [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads)
  36 4. 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
  43 Following 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 ## Configure Vagrant
  46
  47 If you are behind a corporate firewall, configure the following proxy settings.
  48
  49 1. Set the http_proxy and https_proxy
  50 2. Install the proxyconf plugin
  51
  52 ```
  53   $ export http_proxy=....
  54   $ export https_proxy=....
  55   $ vagrant plugin install vagrant-proxyconf
  56 ```
  57
  58 ## Download SPDK from GitHub
  59
  60 Use 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.
  61
  62 ## Create a Virtual Box
  63
  64 Use the `spdk/scripts/vagrant/create_vbox.sh` script to create a VM of your choice.  Supported VM platforms are:
  65
  66 - centos7
  67 - ubuntu16
  68 - ubuntu18
  69 - fedora26
  70 - fedora27
  71 - fedora28
  72 - freebsd11
  73
  74 ```
  75 $ spdk/scripts/vagrant/create_vbox.sh -h
  76  Usage: create_vbox.sh [-n <num-cpus>] [-s <ram-size>] [-x <http-proxy>] [-hvrld] <distro>
  77
  78   distro = <centos7 | ubuntu16 | ubuntu18 | fedora26 | fedora27 | fedora28 | freebsd11>
  79
  80   -s <ram-size> in kb       default: 4096
  81   -n <num-cpus> 1 to 4      default: 4
  82   -x <http-proxy>           default: ""
  83   -p <provider>             libvirt or virtualbox
  84   --vhost-host-dir=<path>   directory path with vhost test dependencies
  85                             (test VM qcow image, fio binary, ssh keys)
  86   --vhost-vm-dir=<path>     directory where to put vhost dependencies in VM
  87   -r dry-run
  88   -l use a local copy of spdk, don't try to rsync from the host.
  89   -d deploy a test vm by provisioning all prerequisites for spdk autotest
  90   -h help
  91   -v verbose
  92
  93  Examples:
  94
  95   ./scripts/vagrant/create_vbox.sh -x http://user:password@host:port fedora27
  96   ./scripts/vagrant/create_vbox.sh -s 2048 -n 2 ubuntu16
  97   ./scripts/vagrant/create_vbox.sh -rv freebsd
  98   ./scripts/vagrant/create_vbox.sh fedora26
  99 ```
 100
 101 It 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:
 102
 103 ```
 104    $ spdk/scripts/vagrant/create_vbox.sh -s 2048 -n 2 fedora26
 105 ```
 106
 107 This script will:
 108
 109 1. create a subdirectory named <distro> in your $PWD
 110 2. copy the needed files from `spdk/scripts/vagrant/` into the <distro> directory
 111 3. create a working virtual box in the <distro> directory
 112 4. rsync the `~/.gitconfig` file to `/home/vagrant/` in the newly provisioned virtual box
 113 5. rsync a copy of the source `spdk` repository to `/home/vagrant/spdk_repo/spdk` (optional)
 114 6. rsync a copy of the `~/vagrant_tools` directory to `/home/vagrant/tools` (optional)
 115 7. execute vm_setup.sh on the guest to install all spdk dependencies (optional)
 116
 117 This 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.
 118
 119 ```
 120   $ cd <distro>
 121   $ vagrant ssh
 122 ```
 123
 124 ## Finish VM Initializtion
 125
 126 A 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:
 127
 128 ```
 129    $ script -c 'sudo spdk_repo/spdk/scripts/vagrant/update.sh' update.log
 130 ```
 131
 132 The `update.sh` script completes initialization of the VM by automating the following steps.
 133
 134 1. Runs yum/apt-get update (Linux)
 135 2. Runs the scripts/pdkdep.sh script
 136 3. Installs the FreeBSD source in /usr/sys (FreeBSD only)
 137
 138 This 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.
 139
 140 ## Post VM Initializtion
 141
 142 Following VM initializtion you must:
 143
 144 1. Verify you have an emulated NVMe device
 145 2. Compile your spdk source tree
 146 3. Run the hello_world example to validate the environment is set up correctly
 147
 148 ### Verify you have an emulated NVMe device
 149
 150 ```
 151   $ lspci | grep "Non-Volatile"
 152   00:0e.0 Non-Volatile memory controller: InnoTek Systemberatung GmbH Device 4e56
 153 ```
 154
 155 ### Compile SPDK
 156
 157 ```
 158   $ cd spdk_repo/spdk
 159   $ git submodule update --init
 160   $ ./configure --enable-debug
 161   $ make
 162 ```
 163
 164 ### Run the hello_world example script
 165
 166 ```
 167   $ sudo scripts/setup.sh
 168   $ cd examples/bdev/hello_world
 169   $ sudo ./hello_bdev
 170 ```
 171
 172 ### Running autorun.sh with vagrant
 173
 174 After 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.
 175
 176 ```
 177    $ cp spdk/scripts/vagrant/autorun-spdk.conf ~/
 178    $ spdk/scripts/vagrant/run-autorun.sh -h
 179      Usage: scripts/vagrant/run-autorun.sh -d <path_to_spdk_tree> [-h] | [-q] | [-n]
 180        -d : Specify a path to an SPDK source tree
 181        -q : No output to screen
 182        -n : Noop - dry-run
 183        -h : This help
 184
 185      Examples:
 186          run-spdk-autotest.sh -d . -q
 187          run-spdk-autotest.sh -d /home/vagrant/spdk_repo/spdk
 188 ```
 189
 190 ## FreeBSD Appendix
 191
 192 ---
 193 **NOTE:** As of this writing the FreeBSD Virtualbox instance does not correctly support the vagrant-proxyconf feature.
 194 ---
 195
 196 The 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.:
 197
 198 ```
 199   $ script update.log sudo spdk_repo/spdk/scripts/vagrant/update.sh
 200 ```
 201
 202 1. Updates the pkg catalog
 203 1. Installs the needed FreeBSD packages on the system by calling pkgdep.sh
 204 2. Installs the FreeBSD source in /usr/src
 205
 206 ```
 207    $ sudo pkg upgrade -f
 208    $ sudo spdk_repo/spdk/scripts/pkgdep.sh
 209    $ sudo git clone --depth 10 -b releases/11.1.0 https://github.com/freebsd/freebsd.git /usr/src
 210 ```
 211
 212 To build spdk on FreeBSD use `gmake MAKE=gmake`.  E.g.:
 213
 214 ```
 215     $ cd spdk_repo/spdk
 216     $ git submodule update --init
 217     $ ./configure --enable-debug
 218     $ gmake MAKE=gmake
 219 ```