[docs] Add vEPC test case preparation steps

Add documentation to review the changes to original vEPC infrastructure
files to configure NSB test run in a specific test setup.

Add initial steps to prepare NSB to use Spirent Landslide for vEPC tests.

JIRA: YARDSTICK-1459

Change-Id: I3b937b1a21d6ec6851a92946e46c679385fdff9c
Signed-off-by: Orest Voznyy <orestx.voznyy@intel.com>

2 files changed, 157 insertions, 3 deletions

diff --git a/docs/testing/user/userguide/13-nsb-installation.rst b/docs/testing/user/userguide/13-nsb-installation.rst
index 0b76cdd30..10debbd9c 100644
--- a/docs/testing/user/userguide/13-nsb-installation.rst
+++ b/docs/testing/user/userguide/13-nsb-installation.rst
@@ -1,7 +1,7 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International
 .. License.
 .. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, 2016-2017 Intel Corporation.
+.. (c) OPNFV, 2016-2018 Intel Corporation.
 
 =====================================
 Yardstick - NSB Testing -Installation
@@ -926,7 +926,7 @@ Setup system proxy (if needed). Add the following configuration into the
 ``/etc/environment`` file:
 
 .. note:: The proxy server name/port and IPs should be changed according to
-  actuall/current proxy configuration in the lab.
+  actual/current proxy configuration in the lab.
 
 .. code:: bash
 
@@ -1182,3 +1182,52 @@ installed as part of the requirements of the project.
 
 3. Execute testcase in samplevnf folder e.g.
    ``<repo>/samples/vnf_samples/nsut/vfw/tc_baremetal_rfc2544_ipv4_1rule_1flow_64B_ixia.yaml``
+
+Spirent Landslide
+-----------------
+
+In order to use Spirent Landslide for vEPC testcases, some dependencies have
+to be preinstalled and properly configured.
+
+- Java
+
+    32-bit Java installation is required for the Spirent Landslide TCL API.
+
+    | ``$ sudo apt-get install openjdk-8-jdk:i386``
+
+    .. important::
+      Make sure ``LD_LIBRARY_PATH`` is pointing to 32-bit JRE. For more details
+      check `Linux Troubleshooting <http://TAS_HOST_IP/tclapiinstall.html#trouble>`
+      section of installation instructions.
+
+- LsApi (Tcl API module)
+
+    Follow Landslide documentation for detailed instructions on Linux
+    installation of Tcl API and its dependencies
+    ``http://TAS_HOST_IP/tclapiinstall.html``.
+    For working with LsApi Python wrapper only steps 1-5 are required.
+
+    .. note:: After installation make sure your API home path is included in
+      ``PYTHONPATH`` environment variable.
+
+    .. important::
+    The current version of LsApi module has an issue with reading LD_LIBRARY_PATH.
+    For LsApi module to initialize correctly following lines (184-186) in
+    lsapi.py
+
+    .. code-block:: python
+
+        ldpath = os.environ.get('LD_LIBRARY_PATH', '')
+        if ldpath == '':
+         environ['LD_LIBRARY_PATH'] = environ['LD_LIBRARY_PATH'] + ':' + ldpath
+
+    should be changed to:
+
+    .. code-block:: python
+
+        ldpath = os.environ.get('LD_LIBRARY_PATH', '')
+        if not ldpath == '':
+               environ['LD_LIBRARY_PATH'] = environ['LD_LIBRARY_PATH'] + ':' + ldpath
+
+.. note:: The Spirent landslide TCL software package needs to be updated in case
+  the user upgrades to a new version of Spirent landslide software.
diff --git a/docs/testing/user/userguide/14-nsb-operation.rst b/docs/testing/user/userguide/14-nsb-operation.rst
index adefe2f18..ac12b32a3 100644
--- a/docs/testing/user/userguide/14-nsb-operation.rst
+++ b/docs/testing/user/userguide/14-nsb-operation.rst
@@ -1,7 +1,7 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International
 .. License.
 .. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, 2016-2017 Intel Corporation.
+.. (c) OPNFV, 2016-2018 Intel Corporation.
 
 Yardstick - NSB Testing - Operation
 ===================================
@@ -459,3 +459,108 @@ Sample test case file
 
 .. literalinclude:: /samples/vnf_samples/nsut/acl/tc_ovs_rfc2544_ipv4_1rule_1flow_64B_trex.yaml
    :language: yaml
+
+Preparing test run of vEPC test case
+------------------------------------
+
+Provided vEPC test cases are examples of emulation of vEPC infrastructure
+components, such as UE, eNodeB, MME, SGW, PGW.
+
+Location of vEPC test cases: ``samples/vnf_samples/nsut/vepc/``.
+
+Before running a specific vEPC test case using NSB, some preconfiguration
+needs to be done.
+
+Update Spirent Landslide TG configuration in pod file
+=====================================================
+
+Examples of ``pod.yaml`` files could be found in
+:file:`etc/yardstick/nodes/standalone`.
+The name of related pod file could be checked in the context section of NSB
+test case.
+
+The ``pod.yaml`` related to vEPC test case uses some sub-structures that hold the
+details of accessing the Spirent Landslide traffic generator.
+These subsections and the changes to be done in provided example pod file are
+described below.
+
+1. ``tas_manager``: data under this key holds the information required to
+access Landslide TAS (Test Administration Server) and perform needed
+configurations on it.
+
+ * ``ip``: IP address of TAS Manager node; should be updated according to test
+   setup used
+ * ``super_user``: superuser name; could be retrieved from Landslide documentation
+ * ``super_user_password``: superuser password; could be retrieved from
+   Landslide documentation
+ * ``cfguser_password``: password of predefined user named 'cfguser'; default
+   password could be retrieved from Landslide documentation
+ * ``test_user``: username to be used during test run as a Landslide library
+   name; to be defined by test run operator
+ * ``test_user_password``: password of test user; to be defined by test run
+   operator
+ * ``proto``: *http* or *https*; to be defined by test run operator
+ * ``license``: Landslide license number installed on TAS
+
+2. The ``config`` section holds information about test servers (TSs) and
+systems under test (SUTs). Data is represented as a list of entries.
+Each such entry contains:
+
+ * ``test_server``: this subsection represents data related to test server
+   configuration, such as:
+
+   * ``name``: test server name; unique custom name to be defined by test
+     operator
+   * ``role``: this value is used as a key to bind specific Test Server and
+     TestCase; should be set to one of test types supported by TAS license
+   * ``ip``: Test Server IP address
+   * ``thread_model``: parameter related to Test Server performance mode.
+     The value should be one of the following: "Legacy" | "Max" | "Fireball".
+     Refer to Landslide documentation for details.
+   * ``phySubnets``: a structure used to specify IP ranges reservations on
+     specific network interfaces of related Test Server. Structure fields are:
+
+    * ``base``: start of IP address range
+    * ``mask``: IP range mask in CIDR format
+    * ``name``: network interface name, e.g. *eth1*
+    * ``numIps``: size of IP address range
+
+ * ``preResolvedArpAddress``: a structure used to specify the range of IP
+   addresses for which the ARP responses will be emulated
+
+    * ``StartingAddress``: IP address specifying the start of IP address range
+    * ``NumNodes``: size of the IP address range
+
+ * ``suts``: a structure that contains definitions of each specific SUT
+   (represents a vEPC component). SUT structure contains following key/value
+   pairs:
+
+    * ``name``: unique custom string specifying SUT name
+    * ``role``: string value corresponding with an SUT role specified in the
+      session profile (test session template) file
+    * ``managementIp``: SUT management IP adress
+    * ``phy``: network interface name, e.g. *eth1*
+    * ``ip``: vEPC component IP address used in test case topology
+    * ``nextHop``: next hop IP address, to allow for vEPC inter-node communication
+
+Update NSB test case definitions
+================================
+NSB test case file designated for vEPC testing contains an example of specific
+test scenario configuration.
+Test operator may change these definitions as required for the use case that
+requires testing.
+Specifically, following subsections of the vEPC test case (section **scenarios**)
+may be changed.
+
+1. Subsection ``options``: contains custom parameters used for vEPC testing
+
+ * subsection ``dmf``: may contain one or more parameters specified in
+   ``traffic_profile`` template file
+ * subsection ``test_cases``: contains re-definitions of parameters specified
+   in ``session_profile`` template file
+
+    .. note:: All parameters in ``session_profile``, value of which is a
+      placeholder, needs to be re-defined to construct a valid test session.
+
+2. Subsection ``runner``: specifies the test duration and the interval of
+TG and VNF side KPIs polling. For more details, refer to :doc:`03-architecture`.