ceph/src/spdk/test/common/config/README.md

   1 # Virtual Test Configuration
   2
   3 This readme and the associated bash script, vm_setup.sh, are intended to assist developers in quickly
   4 preparing a virtual test environment on which to run the SPDK validation tests rooted at autorun.sh.
   5 This file contains basic information about SPDK environment requirements, an introduction to the
   6 autorun-spdk.conf files used to moderate which tests are run by autorun.sh, and step-by-step instructions
   7 for spinning up a VM capable of running the SPDK test suite.
   8 There is no need for external hardware to run these tests. The linux kernel comes with the drivers necessary
   9 to emulate an RDMA enabled NIC. NVMe controllers can also be virtualized in emulators such as QEMU.
  10
  11 ## VM Envronment Requirements (Host)
  12
  13 - 8 GiB of RAM (for DPDK)
  14 - Enable intel_kvm on the host machine from the bios.
  15 - Enable nesting for VMs in kernel command line (for vhost tests).
  16   - In `/etc/default/grub` append the following to the GRUB_CMDLINE_LINUX line: intel_iommu=on kvm-intel.nested=1.
  17
  18 ## VM Specs
  19
  20 When creating the user during the fedora installation, it is best to use the name sys_sgsw. Efforts are being made
  21 to remove all references to this user, or files specific to this user from the codebase, but there are still some
  22 trailing references to it.
  23
  24 ## Autorun-spdk.conf
  25
  26 Every machine that runs the autotest scripts should include a file titled autorun-spdk.conf in the home directory
  27 of the user that will run them. This file consists of several lines of the form 'variable_name=0/1'. autorun.sh sources
  28 this file each time it is run, and determines which tests to attempt based on which variables are defined in the
  29 configuration file. For a full list of the variable declarations available for autorun-spdk.conf, please see
  30 `test/common/autotest_common.sh` starting at line 13.
  31
  32 ## Steps for Configuring the VM
  33
  34 1. Download a fresh Fedora 26 image.
  35 2. Perform the installation of Fedora 26 server.
  36 3. Create an admin user sys_sgsw (enabling passwordless sudo for this account will make life easier during the tests).
  37 4. Run the vm_setup.sh script which will install all proper dependencies.
  38 5. Modify the autorun-spdk.conf file in the home directory.
  39 6. Reboot the VM.
  40 7. Run autorun.sh for SPDK. Any output files will be placed in `~/spdk_repo/output/`.
  41
  42 ## Additional Steps for Preparing the Vhost Tests
  43
  44 The Vhost tests also require the creation of a second virtual machine nested inside of the test VM.
  45 Please follow the directions below to complete that installation. Note that host refers to the Fedora VM
  46 created above and guest or VM refer to the Ubuntu VM created in this section.
  47
  48 1. Follow instructions from spdk/scripts/vagrant/README.md
  49         - install all needed packages mentioned in "Mac OSX Setup" or "Windows 10 Setup" sections
  50         - follow steps from "Configure Vagrant" section
  51
  52 2. Use Vagrant scripts located in spdk/scripts/vagrant to automatically generate
  53         VM image to use in SPDK vhost tests.
  54         Example command:
  55         ~~~{.sh}
  56         spdk/scripts/vagrant/create_vhost_vm.sh --move-to-def-dirs ubuntu16
  57         ~~~
  58         This command will:
  59                 - Download a Ubuntu 16.04 image file
  60                 - upgrade the system and install needed dependencies (fio, sg3-utils, bc)
  61                 - add entry to VM's ~/.ssh/autorized_keys
  62                 - add appropriate options to GRUB command line and update grub
  63                 - convert the image to .qcow2 format
  64                 - move .qcow2 file and ssh keys to default locations used by vhost test scripts
  65
  66 Alternatively it is possible to create the VM image manually using following steps:
  67
  68 1. Create an image file for the VM. It does not have to be large, about 3.5G should suffice.
  69 2. Create an ssh keypair for host-guest communications (performed on the host):
  70     - Generate an ssh keypair with the name spdk_vhost_id_rsa and save it in `/root/.ssh`.
  71     - Make sure that only root has read access to the private key.
  72 3. Install the OS in the VM image (performed on guest):
  73     - Use the latest Ubuntu server (Currently 16.04 LTS).
  74     - When partitioning the disk, make one partion that consumes the whole disk mounted at /. Do not encrypt the disk or enable LVM.
  75     - Choose the OpenSSH server packages during install.
  76 4. Post installation configuration (performed on guest):
  77     - Run the following commands to enable all necessary dependencies:
  78       ~~~{.sh}
  79       sudo apt update
  80       sudo apt upgrade
  81       sudo apt install fio sg3-utils bc
  82       ~~~
  83     - Enable the root user: "sudo passwd root -> root".
  84     - Enable root login over ssh: vim `/etc/ssh/sshd_config` -> PermitRootLogin=yes.
  85     - Disable DNS for ssh: `/etc/ssh/sshd_config` -> UseDNS=no.
  86     - Add the spdk_vhost key to root's known hosts: `/root/.ssh/authorized_keys` -> add spdk_vhost_id_rsa.pub key to authorized keys.
  87     Remember to save the private key in `~/.ssh/spdk_vhost_id_rsa` on the host.
  88     - Change the grub boot options for the guest as follows:
  89       - Add "console=ttyS0 earlyprintk=ttyS0" to the boot options in `/etc/default/grub` (for serial output redirect).
  90       - Add "scsi_mod.use_blk_mq=1" to boot options in `/etc/default/grub`.
  91       ~~~{.sh}
  92       sudo update-grub
  93       ~~~
  94     - Reboot the VM.
  95     - Remove any unnecessary packages (this is to make booting the VM faster):
  96       ~~~{.sh}
  97       apt purge snapd
  98       apt purge Ubuntu-core-launcher
  99       apt purge squashfs-tools
 100       apt purge unattended-upgrades
 101       ~~~
 102 5. Copy the fio binary from the guest location `/usr/bin/fio` to the host location `/home/sys_sgsw/fio_ubuntu`.
 103 6. Place the guest VM in the host at the following location: `/home/sys_sgsw/vhost_vm_image.qcow2`.
 104 7. On the host, edit the `~/autorun-spdk.conf` file to include the following line: SPDK_TEST_VHOST=1.