docs/quickstart.md

   1 # Getting Started with 'vsperf'
   2
   3 ## Hardware Requirements
   4 VSPERF requires the following hardware to run tests: IXIA traffic generator (IxNetwork), a machine that runs the IXIA client software and a CentOS Linux release 7.1.1503 (Core) host.
   5
   6 ## vSwitch Requirements
   7 The vSwitch must support Open Flow 1.3 or greater.
   8
   9 ## Installation
  10
  11 Follow the [installation instructions] to install.
  12
  13 ## IXIA Setup
  14 ###On the CentOS 7 system
  15 You need to install IxNetworkTclClient$(VER_NUM)Linux.bin.tgz.
  16
  17 ### On the IXIA client software system
  18 Find the IxNetwork TCL server app (start -> All Programs -> IXIA -> IxNetwork -> IxNetwork_$(VER_NUM) -> IxNetwork TCL Server)
  19   - Right click on IxNetwork TCL Server, select properties
  20   - Under shortcut tab in the Target dialogue box make sure there is the argument "-tclport xxxx" where xxxx is your port number (take note of this port number you will need it for the 10_custom.conf file).
  21   ![Alt text](TCLServerProperties.png)
  22   - Hit Ok and start the TCL server application
  23
  24 ## Cloning and building src dependencies
  25 In order to run VSPERF, you will need to download DPDK and OVS. You can do this manually and build them in a preferred location, or you could use vswitchperf/src. The vswitchperf/src directory contains makefiles that will allow you to clone and build the libraries that VSPERF depends on, such as DPDK and OVS. To clone and build simply:
  26
  27 ```bash
  28 cd src
  29 make
  30 ```
  31
  32 VSPERF can be used with OVS without DPDK support. In this case you have to specify path to the kernel sources by WITH_LINUX parameter:
  33
  34 ```bash
  35 cd src
  36 make WITH_LINUX=/lib/modules/`uname -r`/build
  37 ```
  38
  39 To delete a src subdirectory and its contents to allow you to re-clone simply use:
  40
  41 ```bash
  42 make cleanse
  43 ```
  44
  45 ## Configure the `./conf/10_custom.conf` file
  46
  47 The supplied `10_custom.conf` file must be modified, as it contains configuration items for which there are no reasonable default values.
  48
  49 The configuration items that can be added is not limited to the initial contents. Any configuration item mentioned in any .conf file in `./conf` directory can be added and that item will be overridden by the custom
  50 configuration value.
  51
  52 ## Using a custom settings file
  53
  54 Alternatively a custom settings file can be passed to `vsperf` via the `--conf-file` argument.
  55
  56 ```bash
  57 ./vsperf --conf-file <path_to_settings_py> ...
  58 ```
  59
  60 Note that configuration passed in via the environment (`--load-env`) or via another command line argument will override both the default and your custom configuration files. This "priority hierarchy" can be described like so (1 = max priority):
  61
  62 1. Command line arguments
  63 2. Environment variables
  64 3. Configuration file(s)
  65
  66 ---
  67
  68 ## Executing tests
  69 Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers:
  70 ```
  71 username ALL=(ALL)       NOPASSWD: ALL
  72 ```
  73 username in the example above should be replaced with a real username.
  74
  75 To list the available tests:
  76
  77 ```bash
  78 ./vsperf --list-tests
  79 ```
  80
  81 To run a group of tests, for example all tests with a name containing
  82 'RFC2544':
  83
  84 ```bash
  85 ./vsperf --conf-file=user_settings.py --tests="RFC2544"
  86 ```
  87
  88 To run all tests:
  89
  90 ```bash
  91 ./vsperf --conf-file=user_settings.py
  92 ```
  93
  94 Some tests allow for configurable parameters, including test duration (in
  95 seconds) as well as packet sizes (in bytes).
  96
  97 ```bash
  98 ./vsperf --conf-file user_settings.py
  99     --tests RFC2544Tput
 100     --test-param "rfc2544_duration=10;packet_sizes=128"
 101 ```
 102
 103 For all available options, check out the help dialog:
 104
 105 ```bash
 106 ./vsperf --help
 107 ```
 108
 109 ---
 110
 111 [installation instructions]: installation.md
 112