diff options
Diffstat (limited to 'docs/release/userguide')
| -rw-r--r-- | docs/release/userguide/Ftrace.debugging.tool.userguide.rst | 68 | ||||
| -rw-r--r-- | docs/release/userguide/common.platform.render.rst | 2 | ||||
| -rw-r--r-- | docs/release/userguide/feature.userguide.render.rst | 2 | ||||
| -rw-r--r-- | docs/release/userguide/kvmfornfv.cyclictest-dashboard.userguide.rst | 104 | ||||
| -rw-r--r-- | docs/release/userguide/kvmfornfv_glossary.rst | 20 | ||||
| -rw-r--r-- | docs/release/userguide/live_migration.userguide.rst | 93 | ||||
| -rw-r--r-- | docs/release/userguide/low_latency.userguide.rst | 44 | ||||
| -rw-r--r-- | docs/release/userguide/openstack.rst | 14 | ||||
| -rw-r--r-- | docs/release/userguide/packet_forwarding.userguide.rst | 309 |
9 files changed, 556 insertions, 100 deletions
diff --git a/docs/release/userguide/Ftrace.debugging.tool.userguide.rst b/docs/release/userguide/Ftrace.debugging.tool.userguide.rst index 95b7f8fe5..bd4d76d73 100644 --- a/docs/release/userguide/Ftrace.debugging.tool.userguide.rst +++ b/docs/release/userguide/Ftrace.debugging.tool.userguide.rst @@ -35,6 +35,10 @@ Version Features | Danube | 4.4-linux-kernel level issues | | | - Option to disable if not required | +-----------------------------+-----------------------------------------------+ +| | - Breaktrace option is implemented. | +| Euphrates | - Implemented post-execute script option to | +| | disable the ftrace when it is enabled. | ++-----------------------------+-----------------------------------------------+ Implementation of Ftrace @@ -56,7 +60,8 @@ Or you can mount it at run time with: mount -t debugfs nodev /sys/kernel/debug -Some configurations for Ftrace are used for other purposes, like finding latency or analyzing the system. For the purpose of debugging, the kernel configuration parameters that should be enabled are: +Some configurations for Ftrace are used for other purposes, like finding latency or analyzing the +system. For the purpose of debugging, the kernel configuration parameters that should be enabled are: .. code:: bash @@ -65,7 +70,8 @@ Some configurations for Ftrace are used for other purposes, like finding latency CONFIG_STACK_TRACER=y CONFIG_DYNAMIC_FTRACE=y -The above parameters must be enabled in /boot/config-4.4.0-el7.x86_64 i.e., kernel config file for ftrace to work. If not enabled, change the parameter to ``y`` and run., +The above parameters must be enabled in /boot/config-4.4.0-el7.x86_64 i.e., kernel config file for +ftrace to work. If not enabled, change the parameter to ``y`` and run., .. code:: bash @@ -85,11 +91,13 @@ The below is a list of few major files in Ftrace. ``available_tracers:`` - This holds the different types of tracers that have been compiled into the kernel. The tracers listed here can be configured by echoing their name into current_tracer. + This holds the different types of tracers that have been compiled into the kernel. + The tracers listed here can be configured by echoing their name into current_tracer. ``tracing_on:`` - This sets or displays whether writing to the tracering buffer is enabled. Echo 0 into this file to disable the tracer or 1 to enable it. + This sets or displays whether writing to the tracering buffer is enabled. Echo 0 into this + file to disable the tracer or 1 to enable it. ``trace:`` @@ -97,11 +105,13 @@ The below is a list of few major files in Ftrace. ``tracing_cpumask:`` - This is a mask that lets the user only trace on specified CPUs. The format is a hex string representing the CPUs. + This is a mask that lets the user only trace on specified CPUs. The format is a hex string + representing the CPUs. ``events:`` - It holds event tracepoints (also known as static tracepoints) that have been compiled into the kernel. It shows what event tracepoints exist and how they are grouped by system. + It holds event tracepoints (also known as static tracepoints) that have been compiled into + the kernel. It shows what event tracepoints exist and how they are grouped by system. Avaliable Tracers @@ -125,11 +135,13 @@ Brief about a few: ``function_graph:`` - Similar to the function tracer except that the function tracer probes the functions on their entry whereas the function graph tracer traces on both entry and exit of the functions. + Similar to the function tracer except that the function tracer probes the functions on their + entry whereas the function graph tracer traces on both entry and exit of the functions. ``nop:`` - This is the "trace nothing" tracer. To remove tracers from tracing simply echo "nop" into current_tracer. + This is the "trace nothing" tracer. To remove tracers from tracing simply echo "nop" into + current_tracer. Examples: @@ -221,7 +233,8 @@ The set_event file contains all the enabled events list sudo bash -c "echo function > $TRACEDIR/current_tracer -- When tracing is turned ON by setting ``tracing_on=1``, the ``trace`` file keeps getting append with the traced data until ``tracing_on=0`` and then ftrace_buffer gets cleared. +- When tracing is turned ON by setting ``tracing_on=1``, the ``trace`` file keeps getting append +with the traced data until ``tracing_on=0`` and then ftrace_buffer gets cleared. .. code:: bash @@ -231,7 +244,42 @@ The set_event file contains all the enabled events list To Start/Restart, echo 1 >tracing_on; -- Once tracing is diabled, disable_trace.sh script is triggered. +- Once tracing is disabled, disable_trace.sh script is triggered. + +BREAKTRACE +---------- +- Send break trace command when latency > USEC. This is a debugging option to control the latency +tracer in the realtime preemption patch. It is useful to track down unexpected large latencies on a +system. This option does only work with following kernel config options. + +For kernel < 2.6.24: +* CONFIG_PREEMPT_RT=y +* CONFIG_WAKEUP_TIMING=y +* CONFIG_LATENCY_TRACE=y +* CONFIG_CRITICAL_PREEMPT_TIMING=y +* CONFIG_CRITICAL_IRQSOFF_TIMING=y + +For kernel >= 2.6.24: +* CONFIG_PREEMPT_RT=y +* CONFIG_FTRACE +* CONFIG_IRQSOFF_TRACER=y +* CONFIG_PREEMPT_TRACER=y +* CONFIG_SCHED_TRACER=y +* CONFIG_WAKEUP_LATENCY_HIST + +- Kernel configuration options enabled. The USEC parameter to the -b option defines a maximum +latency value, which is compared against the actual latencies of the test. Once the measured latency +is higher than the given maximum, the kernel tracer and cyclictest is stopped. The trace can be read +from /proc/latency_trace. Please be aware that the tracer adds significant overhead to the kernel, +so the latencies will be much higher than on a kernel with latency tracing disabled. + +- Breaktrace option will enable the trace by default, suppress the tracing by using --notrace option. + +Post-execute scripts +-------------------- +post-execute script to yardstick node context teardown is added to disable the ftrace soon after the +completion of cyclictest execution throughyardstick. This option is implemented to collect only +required ftrace logs for effective debugging if needed. Details of disable_trace Script ------------------------------- diff --git a/docs/release/userguide/common.platform.render.rst b/docs/release/userguide/common.platform.render.rst index 46b4707a3..6487194d8 100644 --- a/docs/release/userguide/common.platform.render.rst +++ b/docs/release/userguide/common.platform.render.rst @@ -7,7 +7,7 @@ Using common platform components ================================ This section outlines basic usage principals and methods for some of the -commonly deployed components of supported OPNFV scenario's in Danube. +commonly deployed components of supported OPNFV scenario's in Euphrates. The subsections provide an outline of how these components are commonly used and how to address them in an OPNFV deployment.The components derive from autonomous upstream communities and where possible this guide will diff --git a/docs/release/userguide/feature.userguide.render.rst b/docs/release/userguide/feature.userguide.render.rst index 3bed21fc9..e103f5f2d 100644 --- a/docs/release/userguide/feature.userguide.render.rst +++ b/docs/release/userguide/feature.userguide.render.rst @@ -3,7 +3,7 @@ .. http://creativecommons.org/licenses/by/4.0 ========================== -Using Danube Features +Using Euphrates Features ========================== The following sections of the user guide provide feature specific usage diff --git a/docs/release/userguide/kvmfornfv.cyclictest-dashboard.userguide.rst b/docs/release/userguide/kvmfornfv.cyclictest-dashboard.userguide.rst index c119b43c7..e5be012b6 100644 --- a/docs/release/userguide/kvmfornfv.cyclictest-dashboard.userguide.rst +++ b/docs/release/userguide/kvmfornfv.cyclictest-dashboard.userguide.rst @@ -96,10 +96,11 @@ Three type of dispatcher methods are available to store the cyclictest results. - InfluxDB - HTTP -**1. File**: Default Dispatcher module is file. If the dispatcher module is configured as a file,then the test results are stored in a temporary file yardstick.out -( default path: /tmp/yardstick.out). -Dispatcher module of "Verify Job" is "Default". So,the results are stored in Yardstick.out file for verify job. -Storing all the verify jobs in InfluxDB database causes redundancy of latency values. Hence, a File output format is prefered. +**1. File**: Default Dispatcher module is file. If the dispatcher module is configured as a file, +then the test results are stored in a temporary file yardstick.out(default path: /tmp/yardstick.out). +Dispatcher module of "Verify Job" is "Default". So,the results are stored in Yardstick.out file for +verify job. Storing all the verify jobs in InfluxDB database causes redundancy of latency values. +Hence, a File output format is prefered. .. code:: bash @@ -112,8 +113,9 @@ Storing all the verify jobs in InfluxDB database causes redundancy of latency va max_bytes = 0 backup_count = 0 -**2. Influxdb**: If the dispatcher module is configured as influxdb, then the test results are stored in Influxdb. -Users can check test resultsstored in the Influxdb(Database) on Grafana which is used to visualize the time series data. +**2. Influxdb**: If the dispatcher module is configured as influxdb, then the test results are +stored in Influxdb. Users can check test resultsstored in the Influxdb(Database) on Grafana which is +used to visualizethe time series data. To configure the influxdb, the following content in /etc/yardstick/yardstick.conf need to updated @@ -130,9 +132,11 @@ To configure the influxdb, the following content in /etc/yardstick/yardstick.con username = root password = root -Dispatcher module of "Daily Job" is Influxdb. So, the results are stored in influxdb and then published to Dashboard. +Dispatcher module of "Daily Job" is Influxdb. So, the results are stored in influxdb and then +published to Dashboard. -**3. HTTP**: If the dispatcher module is configured as http, users can check test result on OPNFV testing dashboard which uses MongoDB as backend. +**3. HTTP**: If the dispatcher module is configured as http, users can check test result on OPNFV +testing dashboard which uses MongoDB as backend. .. code:: bash @@ -150,12 +154,14 @@ Dispatcher module of "Daily Job" is Influxdb. So, the results are stored in infl Detailing the dispatcher module in verify and daily Jobs: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -KVM4NFV updates the dispatcher module in the yardstick configuration file(/etc/yardstick/yardstick.conf) depending on the Job type(Verify/Daily). -Once the test is completed, results are published to the respective dispatcher modules. +KVM4NFV updates the dispatcher module in the yardstick configuration (/etc/yardstick/yardstick.conf) +file depending on the Job type(Verify/Daily). Once the test is completed, results are published to +the respective dispatcher modules. Dispatcher module is configured for each Job type as mentioned below. -1. ``Verify Job`` : Default "DISPATCHER_TYPE" i.e. file(/tmp/yardstick.out) is used. User can also see the test results on Jenkins console log. +1. ``Verify Job`` : Default "DISPATCHER_TYPE" i.e. file(/tmp/yardstick.out) is used. User can also +see the test results on Jenkins console log. .. code:: bash @@ -197,14 +203,17 @@ With the help of "influxdb_line_protocol", the json is transformed as a line str -Influxdb api which is already implemented in `Influxdb`_ will post the data in line format into the database. +Influxdb api which is already implemented in `Influxdb`_ will post the data in line format into the +database. ``Displaying Results on Grafana dashboard:`` -- Once the test results are stored in Influxdb, dashboard configuration file(Json) which used to display the cyclictest results -on Grafana need to be created by following the `Grafana-procedure`_ and then pushed into `yardstick-repo`_\ +- Once the test results are stored in Influxdb, dashboard configuration file(Json) which used to +display the cyclictest results on Grafana need to be created by following the `Grafana-procedure`_ +and then pushed into `yardstick-repo`_\ -- Grafana can be accessed at `Login`_ using credentials opnfv/opnfv and used for visualizing the collected test data as shown in `Visual`_\ +- Grafana can be accessed at `Login`_ using credentials opnfv/opnfv and used for visualizing the +collected test data as shown in `Visual`_\ .. figure:: images/Dashboard-screenshot-1.png @@ -232,7 +241,8 @@ on Grafana need to be created by following the `Grafana-procedure`_ and then pus Understanding Kvm4nfv Grafana Dashboard --------------------------------------- -The Kvm4nfv dashboard found at http://testresults.opnfv.org/ currently supports graphical view of cyclictest. For viewing Kvm4nfv dashboarduse, +The Kvm4nfv dashboard found at http://testresults.opnfv.org/ currently supports graphical view of +cyclictest. For viewing Kvm4nfv dashboarduse, .. code:: bash @@ -267,7 +277,8 @@ Note: 1. Idle-Idle Graph ~~~~~~~~~~~~~~~~~~~~ -`Idle-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running Idle_Idle test-type of the cyclictest. +`Idle-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running +Idle_Idle test-type of the cyclictest. Idle_Idle implies that no stress is applied on the Host or the Guest. .. _Idle-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=10&fullscreen @@ -279,8 +290,9 @@ Idle_Idle implies that no stress is applied on the Host or the Guest. 2. CPU_Stress-Idle Graph ~~~~~~~~~~~~~~~~~~~~~~~~~ -`Cpu_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running Cpu-stress_Idle test-type of the cyclictest. -Cpu-stress_Idle implies that CPU stress is applied on the Host and no stress on the Guest. +`Cpu_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by +running Cpu-stress_Idle test-type of the cyclictest. Cpu-stress_Idle implies that CPU stress is +applied on the Host and no stress on the Guest. .. _Cpu_stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=11&fullscreen @@ -291,8 +303,9 @@ Cpu-stress_Idle implies that CPU stress is applied on the Host and no stress on 3. Memory_Stress-Idle Graph ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -`Memory_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running Memory-stress_Idle test-type of the Cyclictest. -Memory-stress_Idle implies that Memory stress is applied on the Host and no stress on the Guest. +`Memory_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by +running Memory-stress_Idle test-type of the Cyclictest. Memory-stress_Idle implies that Memory +stress is applied on the Host and no stress on the Guest. .. _Memory_Stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=12&fullscreen @@ -303,8 +316,9 @@ Memory-stress_Idle implies that Memory stress is applied on the Host and no stre 4. IO_Stress-Idle Graph ~~~~~~~~~~~~~~~~~~~~~~~~~ -`IO_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running IO-stress_Idle test-type of the Cyclictest. -IO-stress_Idle implies that IO stress is applied on the Host and no stress on the Guest. +`IO_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running +IO-stress_Idle test-type of the Cyclictest. IO-stress_Idle implies that IO stress is applied on the +Host and no stress on the Guest. .. _IO_Stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=13&fullscreen @@ -313,6 +327,46 @@ IO-stress_Idle implies that IO stress is applied on the Host and no stress on th :width: 100% :align: center +Packet Forwarding Results +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Understanding Kvm4nfv Grafana Dashboard +--------------------------------------- + +The Kvm4nfv dashboard found at http://testresults.opnfv.org/grafana/ currently supports graphical +view of packet forwarding as well. For viewing Kvm4nfv packet forwarding dashboard use, + +.. code:: bash + + http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-packet-forwarding + + The login details are: + + Username: opnfv + Password: opnfv + + +.. code:: bash + + The JSON of the KVMFORNFV-Packet-Forwarding dashboard can be found at., + + $ git clone https://gerrit.opnfv.org/gerrit/yardstick.git + $ cd yardstick/dashboard + $ cat KVMFORNFV-Packet-Forwarding + +The Dashboard has five tables for each specific test of packet forwarding, one for each frame size. + +- KVM4NFV-PHY2PHY-TPUT-OVS_WITH_DPDK_AND_VHOST_USER +- KVM4NFV-PVP-TPUT-OVS_WITH_DPDK_AND_VHOST_USER +- KVM4NFV-PVP-TPUT-SRIOV +- KVM4NFV-PVVP-TPUT-OVS_WITH_DPDK_AND_VHOST_USER +- KVM4NFV-PVVP-TPUT-OVS_WITH_DPDK_AND_VHOST_USER + +Note: + +- For all graphs, X-axis is marked with time stamps, Y-axis with value in microsecond units. + Future Scope -------------- -The future work will include adding the kvmfornfv_Packet-forwarding test results into Grafana and influxdb. +------------ +The future work will include adding new tables to packet forwarding Grafana dashboard to publish the +results of new packet forwarding test cases to be added if any. diff --git a/docs/release/userguide/kvmfornfv_glossary.rst b/docs/release/userguide/kvmfornfv_glossary.rst index aed5a971e..4dd731475 100644 --- a/docs/release/userguide/kvmfornfv_glossary.rst +++ b/docs/release/userguide/kvmfornfv_glossary.rst @@ -6,8 +6,8 @@ OPNFV Glossary ************** -Danube 1.0 ------------- +Euphrates 1.0 +------------- Contents @@ -25,6 +25,11 @@ Arno A river running through Tuscany and the name of the first OPNFV release. +Apex + + OPNFV Installation and Deployment tool based on the RDO Project's Triple-O + OpenStack installation tool. + API Application Programming Interface @@ -100,7 +105,7 @@ D Danube - Danube is the fourth release of OPNFV and also a river in Europe + A river in Europe and name of the Fourth OPNFV release. Data plane @@ -129,6 +134,15 @@ DSCP -------- +E +~ + +Euphrates + + Longest river of Western Asia and name of the fifth OPNFV release. + +-------- + F ~ diff --git a/docs/release/userguide/live_migration.userguide.rst b/docs/release/userguide/live_migration.userguide.rst index 9fa9b82fd..ff075ac26 100644 --- a/docs/release/userguide/live_migration.userguide.rst +++ b/docs/release/userguide/live_migration.userguide.rst @@ -72,16 +72,83 @@ QEMU v2.4.0 Ethernet controller: Intel Corporation Ethernet Controller 10-Gigabit X540-AT2 (rev 01) + +Vhost-user with OVS/DPDK as backend: +:: +The goal is to connect guests' virtio-net devices having vhost-user backend to OVS dpdkvhostuser +ports and be able to run any kind of network traffic between them. + +Installation of OVS and DPDK: +:: +Using vsperf,installing the OVS and DPDk. Prepare the directories + +.. code:: bash + + mkdir -p /var/run/openvswitch + mount -t hugetlbfs -o pagesize=2048k none /dev/hugepages + +Load Kernel modules + +.. code:: bash + + modprobe openvswitch + +For OVS setup, clean the environment + +.. code:: bash + + rm -f /usr/local/var/run/openvswitch/vhost-user* + rm -f /usr/local/etc/openvswitch/conf.db + +Start database server + +.. code:: bash + + ovsdb-tool create /usr/local/etc/openvswitch/conf.db $VSPERF/src/ovs/ovs/vswitchd/vswitch.ovsschema + ovsdb-server --remote=punix:$DB_SOCK --remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach + +Start OVS + +.. code:: bash + + ovs-vsctl --no-wait init + ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0xf + ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=1024 + ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true + +Configure the bridge + +.. code:: bash + + ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev + ovs-vsctl add-port ovsbr0 vhost-user1 -- set Interface vhost-user1 type=dpdkvhostuser + ovs-vsctl add-port ovsbr0 vhost-user2 -- set Interface vhost-user2 type=dpdkvhostuser + QEMU parameters: :: -${qemu} -smp ${guest_cpus} -monitor unix:${qmp_sock},server,nowait -daemonize \ --cpu host,migratable=off,+invtsc,+tsc-deadline,pmu=off \ --realtime mlock=on -mem-prealloc -enable-kvm -m 1G \ --mem-path /mnt/hugetlbfs-1g \ --drive file=/root/minimal-centos1.qcow2,cache=none,aio=threads \ --netdev user,id=guest0,hostfwd=tcp:5555-:22 \ --device virtio-net-pci,netdev=guest0 \ --nographic -serial /dev/null -parallel /dev/null +qemu-system-x86_64 -enable-kvm -cpu host -smp 2 +-chardev socket,id=char1,path=/usr/local/var/run/openvswitch/vhost-user1 +-netdev type=vhost-user,id=net1,chardev=char1,vhostforce \ +-device virtio-net-pci,netdev=net1,mac=52:54:00:12:34:56 \ +-chardev socket,id=char2,path=/usr/local/var/run/openvswitch/vhost-user2\ +-netdev type=vhost-user,id=net2,chardev=char2,vhostforce \ +-device virtio-net-pci,netdev=net2,mac=54:54:00:12:34:56 -m 1024 -mem-path /dev/hugepages \ +-mem-prealloc -realtime mlock=on -monitor unix:/tmp/qmp-sock-src,server,nowait \ +-balloon virtio -drive file=/root/guest1.qcow2 -vnc :1 & + +Run the standby qemu with -incoming tcp:-incoming tcp:${incoming_ip}:${migrate_port}:${migrate_port} + +For local live migration + +.. code:: bash + + incoming ip=0 + +For peer -peer live migration + +.. code:: bash + + incoming ip=dest_host Network connection @@ -90,6 +157,16 @@ Network connection :alt: live migration network connection :figwidth: 80% +Commands for performing live migration: +:: + +.. code:: bash + + echo "migrate_set_speed 0" |nc -U /tmp/qmp-sock-src + echo "migrate_set_downtime 0.10" |nc -U /tmp/qmp-sock-src + echo "migrate -d tcp:0:4444" |nc -U /tmp/qmp-sock-src + #Wait till livemigration completed + echo "info migrate" | nc -U /tmp/qmp-sock-src Test Result ----------- diff --git a/docs/release/userguide/low_latency.userguide.rst b/docs/release/userguide/low_latency.userguide.rst index f027b4939..e521a84c2 100644 --- a/docs/release/userguide/low_latency.userguide.rst +++ b/docs/release/userguide/low_latency.userguide.rst @@ -127,18 +127,18 @@ The above name signifies that, Version Features ~~~~~~~~~~~~~~~~ -+-----------------------+------------------+-----------------+ -| **Test Name** | **Colorado** | **Danube** | -| | | | -+-----------------------+------------------+-----------------+ -| - Idle - Idle | ``Y`` | ``Y`` | -+-----------------------+------------------+-----------------+ -| - Cpustress - Idle | | ``Y`` | -+-----------------------+------------------+-----------------+ -| - Memorystress - Idle | | ``Y`` | -+-----------------------+------------------+-----------------+ -| - IOstress - Idle | | ``Y`` | -+-----------------------+------------------+-----------------+ ++-----------------------+------------------+-----------------+-----------------+ +| **Test Name** | **Colorado** | **Danube** | **Euphrates** | +| | | | | ++-----------------------+------------------+-----------------+-----------------+ +| - Idle - Idle | ``Y`` | ``Y`` | ``Y`` | ++-----------------------+------------------+-----------------+-----------------+ +| - Cpustress - Idle | | ``Y`` | ``Y`` | ++-----------------------+------------------+-----------------+-----------------+ +| - Memorystress - Idle | | ``Y`` | ``Y`` | ++-----------------------+------------------+-----------------+-----------------+ +| - IOstress - Idle | | ``Y`` | ``Y`` | ++-----------------------+------------------+-----------------+-----------------+ Idle-Idle test-type @@ -165,8 +165,8 @@ Outputs Avg, Min and Max latency values. Memory_Stress-Idle test-type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In this type, the host is under memory stress where continuos memory operations are implemented to -increase the Memory stress (Buffer stress).The cyclictest will run on the guest, where the guest is under -no stress. It outputs Avg, Min and Max latency values. +increase the Memory stress (Buffer stress).The cyclictest will run on the guest, where the guest is +under no stress. It outputs Avg, Min and Max latency values. .. figure:: images/memory-stress-idle-test-type.png :name: memory-stress-idle test type @@ -176,8 +176,8 @@ no stress. It outputs Avg, Min and Max latency values. IO_Stress-Idle test-type ~~~~~~~~~~~~~~~~~~~~~~~~ The host is under constant Input/Output stress .i.e., multiple read-write operations are invoked to -increase stress. Cyclictest will run on the guest VM that is launched on the same host, where the guest -is under no stress. It outputs Avg, Min and Max latency values. +increase stress. Cyclictest will run on the guest VM that is launched on the same host, where the +guest is under no stress. It outputs Avg, Min and Max latency values. .. figure:: images/io-stress-idle-test-type.png :name: io-stress-idle test type @@ -186,15 +186,15 @@ is under no stress. It outputs Avg, Min and Max latency values. CPU_Stress-CPU_Stress test-type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Not implemented for Danube release. +Not implemented for Euphrates release. Memory_Stress-Memory_Stress test-type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Not implemented for Danube release. +Not implemented for Euphrates release. IO_Stress-IO_Stress test type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Not implemented for Danube release. +Not implemented for Euphrates release. 2. Packet Forwarding Test cases ------------------------------- @@ -203,9 +203,9 @@ to source after reaching its destination. This test case uses automated test-fra OPNFV VSWITCHPERF project and a traffic generator (IXIA is used for kvm4nfv). Only latency results generating test cases are triggered as a part of kvm4nfv daily job. -Latency test measures the time required for a frame to travel from the originating device through the -network to the destination device. Please note that RFC2544 Latency measurement will be superseded with -a measurement of average latency over all successfully transferred packets or frames. +Latency test measures the time required for a frame to travel from the originating device through +the network to the destination device. Please note that RFC2544 Latency measurement will be +superseded with a measurement of average latency over all successfully transferred packets or frames. Packet forwarding test cases currently supports the following test types: diff --git a/docs/release/userguide/openstack.rst b/docs/release/userguide/openstack.rst index 929d2ba42..c35535860 100644 --- a/docs/release/userguide/openstack.rst +++ b/docs/release/userguide/openstack.rst @@ -2,19 +2,19 @@ .. http://creativecommons.org/licenses/by/4.0 -============================ -Danube OpenStack User Guide -============================ +============================== +Euphrates OpenStack User Guide +============================== OpenStack is a cloud operating system developed and released by the `OpenStack project <https://www.openstack.org>`_. OpenStack is used in OPNFV for controlling pools of compute, storage, and networking resources in a Pharos compliant infrastructure. -OpenStack is used in Danube to manage tenants (known in OpenStack as +OpenStack is used in Euphrates to manage tenants (known in OpenStack as projects),users, services, images, flavours, and quotas across the Pharos infrastructure.The OpenStack interface provides the primary interface for an -operational Danube deployment and it is from the "horizon console" that an +operational Euphrates deployment and it is from the "horizon console" that an OPNFV user will perform the majority of administrative and operational activities on the deployment. @@ -26,7 +26,7 @@ details and descriptions of how to configure and interact with the OpenStack deployment.This guide can be used by lab engineers and operators to tune the OpenStack deployment to your liking. -Once you have configured OpenStack to your purposes, or the Danube +Once you have configured OpenStack to your purposes, or the Euphrates deployment meets your needs as deployed, an operator, or administrator, will find the best guidance for working with OpenStack in the `OpenStack administration guide <http://docs.openstack.org/user-guide-admin>`_. @@ -46,6 +46,6 @@ and enter the username and password: password: admin Other methods of interacting with and configuring OpenStack,, like the REST API -and CLI are also available in the Danube deployment, see the +and CLI are also available in the Euphrates deployment, see the `OpenStack administration guide <http://docs.openstack.org/user-guide-admin>`_ for more information on using those interfaces. diff --git a/docs/release/userguide/packet_forwarding.userguide.rst b/docs/release/userguide/packet_forwarding.userguide.rst index 31341a908..554d4efb9 100644 --- a/docs/release/userguide/packet_forwarding.userguide.rst +++ b/docs/release/userguide/packet_forwarding.userguide.rst @@ -33,6 +33,11 @@ Version Features | | VSWITCHPERF software (PVP/PVVP) | | | - Works with IXIA Traffic Generator | +-----------------------------+---------------------------------------------------+ +| | - Test cases involving multiple guests (PVVP/PVPV)| +| | included. | +| Euphrates | - Implemented Yardstick Grafana dashboard to | +| | publish results of packet forwarding test cases | ++-----------------------------+---------------------------------------------------+ VSPERF ------ @@ -90,7 +95,8 @@ environment and compilation of OVS, DPDK and QEMU is performed by script **systems/build_base_machine.sh**. It should be executed under user account, which will be used for vsperf execution. - **Please Note:** Password-less sudo access must be configured for given user before script is executed. + **Please Note:** Password-less sudo access must be configured for given user before script is +executed. Execution of installation script: @@ -123,9 +129,9 @@ For CentOS 7 ## Python 3 Packages -To avoid file permission errors and Python version issues, use virtualenv to create an isolated environment with Python3. -The required Python 3 packages can be found in the `requirements.txt` file in the root of the test suite. -They can be installed in your virtual environment like so: +To avoid file permission errors and Python version issues, use virtualenv to create an isolated +environment with Python3. The required Python 3 packages can be found in the `requirements.txt` file +in the root of the test suite. They can be installed in your virtual environment like so: .. code:: bash @@ -150,7 +156,8 @@ To activate, simple run: Working Behind a Proxy ~~~~~~~~~~~~~~~~~~~~~~ -If you're behind a proxy, you'll likely want to configure this before running any of the above. For example: +If you're behind a proxy, you'll likely want to configure this before running any of the above. +For example: .. code:: bash @@ -164,12 +171,14 @@ If you're behind a proxy, you'll likely want to configure this before running an For other OS specific activation click `this link`_: -.. _this link: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/installation.html#other-requirements +.. _this link: +http://artifacts.opnfv.org/vswitchperf/colorado/configguide/installation.html#other-requirements Traffic-Generators ------------------ -VSPERF supports many Traffic-generators. For configuring VSPERF to work with the available traffic-generator go through `this`_. +VSPERF supports many Traffic-generators. For configuring VSPERF to work with the available traffic +generator go through `this`_. .. _this: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/trafficgen.html @@ -191,7 +200,8 @@ To see the list of traffic gens from the cli: This guide provides the details of how to install and configure the various traffic generators. -As KVM4NFV uses only IXIA traffic generator, it is discussed here. For complete documentation regarding traffic generators please follow this `link`_. +As KVM4NFV uses only IXIA traffic generator, it is discussed here. For complete documentation +regarding traffic generators please follow this `link`_. .. _link: https://gerrit.opnfv.org/gerrit/gitweb?p=vswitchperf.git;a=blob;f=docs/configguide/trafficgen.rst;h=85fc35b886d30db3b92a6b7dcce7ca742b70cbdc;hb=HEAD @@ -201,8 +211,8 @@ IXIA Setup Hardware Requirements ~~~~~~~~~~~~~~~~~~~~~ -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. +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. Installation ~~~~~~~~~~~~ @@ -217,11 +227,13 @@ You need to install IxNetworkTclClient$(VER_NUM)Linux.bin.tgz. On the IXIA client software system ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Find the IxNetwork TCL server app (start -> All Programs -> IXIA -> IxNetwork -> IxNetwork_$(VER_NUM) -> IxNetwork TCL Server) +Find the IxNetwork TCL server app + - (start -> All Programs -> IXIA -> IxNetwork -> IxNetwork_$(VER_NUM) -> IxNetwork TCL Server) - Right click on IxNetwork TCL Server, select properties - 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). +where xxxx is your port number (take note of this port number you will need it for the +10_custom.conf file). .. figure:: images/IXIA1.png :name: IXIA1 setup @@ -336,11 +348,12 @@ To delete a src subdirectory and its contents to allow you to re-clone simply us Configure the `./conf/10_custom.conf` file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The supplied `10_custom.conf` file must be modified, as it contains configuration items for which there are no reasonable default values. +The supplied `10_custom.conf` file must be modified, as it contains configuration items for which +there are no reasonable default values. -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 -configuration value. +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 configuration value. Using a custom settings file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -381,7 +394,9 @@ IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd Executing tests ~~~~~~~~~~~~~~~~ -Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers: +Before running any tests make sure you have root permissions by adding the following line to +/etc/sudoers: + .. code:: bash username ALL=(ALL) NOPASSWD: ALL @@ -408,7 +423,8 @@ To run all tests: ./vsperf --conf-file=user_settings.py -Some tests allow for configurable parameters, including test duration (in seconds) as well as packet sizes (in bytes). +Some tests allow for configurable parameters, including test duration (in seconds) as well as packet +sizes (in bytes). .. code:: bash @@ -467,7 +483,7 @@ In case, that VSPERF is executed in "trafficgen" mode, then configuration of traffic generator can be modified through ``TRAFFIC`` dictionary passed to the ``--test-params`` option. It is not needed to specify all values of ``TRAFFIC`` dictionary. It is sufficient to specify only values, which should be changed. -Detailed description of ``TRAFFIC`` dictionary can be found at: ref:`configuration-of-traffic-dictionary`. +Detailed notes on ``TRAFFIC`` dictionary can be found at: ref:`configuration-of-traffic-dictionary`. Example of execution of VSPERF in "trafficgen" mode: @@ -499,8 +515,8 @@ please refer to figure.2 :width: 100% :align: center -Packet Forwarding Guest Scenario -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Packet Forwarding Guest Scenario (PXP Deployment) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Here the guest is a Virtual Machine (VM) launched by using vloop_vnf provided by vsperf project on host/DUT using Qemu. In this latency test the time taken by the frame/packet to travel from the @@ -512,6 +528,173 @@ The resulting latency values will define the performance of installed kernel. :width: 100% :align: center +Every testcase uses one of the supported deployment scenarios to setup test environment. +The controller responsible for a given scenario configures flows in the vswitch to route +traffic among physical interfaces connected to the traffic generator and virtual +machines. VSPERF supports several deployments including PXP deployment, which can +setup various scenarios with multiple VMs. + +These scenarios are realized by VswitchControllerPXP class, which can configure and +execute given number of VMs in serial or parallel configurations. Every VM can be +configured with just one or an even number of interfaces. In case that VM has more than +2 interfaces, then traffic is properly routed among pairs of interfaces. + +Example of traffic routing for VM with 4 NICs in serial configuration: + +.. code-block:: console + + +------------------------------------------+ + | VM with 4 NICs | + | +---------------+ +---------------+ | + | | Application | | Application | | + | +---------------+ +---------------+ | + | ^ | ^ | | + | | v | v | + | +---------------+ +---------------+ | + | | logical ports | | logical ports | | + | | 0 1 | | 2 3 | | + +--+---------------+----+---------------+--+ + ^ : ^ : + | | | | + : v : v + +-----------+---------------+----+---------------+----------+ + | vSwitch | 0 1 | | 2 3 | | + | | logical ports | | logical ports | | + | previous +---------------+ +---------------+ next | + | VM or PHY ^ | ^ | VM or PHY| + | port -----+ +------------+ +---> port | + +-----------------------------------------------------------+ + + +It is also possible to define different number of interfaces for each VM to better +simulate real scenarios. + +The number of VMs involved in the test and the type of their connection is defined +by deployment name as follows: + + * ``pvvp[number]`` - configures scenario with VMs connected in series with + optional ``number`` of VMs. In case that ``number`` is not specified, then + 2 VMs will be used. + + Example of 2 VMs in a serial configuration: + + .. code-block:: console + + +----------------------+ +----------------------+ + | 1st VM | | 2nd VM | + | +---------------+ | | +---------------+ | + | | Application | | | | Application | | + | +---------------+ | | +---------------+ | + | ^ | | | ^ | | + | | v | | | v | + | +---------------+ | | +---------------+ | + | | logical ports | | | | logical ports | | + | | 0 1 | | | | 0 1 | | + +---+---------------+--+ +---+---------------+--+ + ^ : ^ : + | | | | + : v : v + +---+---------------+---------+---------------+--+ + | | 0 1 | | 3 4 | | + | | logical ports | vSwitch | logical ports | | + | +---------------+ +---------------+ | + | ^ | ^ | | + | | +-----------------+ v | + | +----------------------------------------+ | + | | physical ports | | + | | 0 1 | | + +---+----------------------------------------+---+ + ^ : + | | + : v + +------------------------------------------------+ + | | + | traffic generator | + | | + +------------------------------------------------+ + +* ``pvpv[number]`` - configures scenario with VMs connected in parallel with + optional ``number`` of VMs. In case that ``number`` is not specified, then + 2 VMs will be used. Multistream feature is used to route traffic to particular + VMs (or NIC pairs of every VM). It means, that VSPERF will enable multistream + feaure and sets the number of streams to the number of VMs and their NIC + pairs. Traffic will be dispatched based on Stream Type, i.e. by UDP port, + IP address or MAC address. + + Example of 2 VMs in a parallel configuration, where traffic is dispatched + based on the UDP port. + + .. code-block:: console + + +----------------------+ +----------------------+ + | 1st VM | | 2nd VM | + | +---------------+ | | +---------------+ | + | | Application | | | | Application | | + | +---------------+ | | +---------------+ | + | ^ | | | ^ | | + | | v | | | v | + | +---------------+ | | +---------------+ | + | | logical ports | | | | logical ports | | + | | 0 1 | | | | 0 1 | | + +---+---------------+--+ +---+---------------+--+ + ^ : ^ : + | | | | + : v : v + +---+---------------+---------+---------------+--+ + | | 0 1 | | 3 4 | | + | | logical ports | vSwitch | logical ports | | + | +---------------+ +---------------+ | + | ^ | ^ : | + | | ......................: : | + | UDP | UDP : | : | + | port| port: +--------------------+ : | + | 0 | 1 : | : | + | | : v v | + | +----------------------------------------+ | + | | physical ports | | + | | 0 1 | | + +---+----------------------------------------+---+ + ^ : + | | + : v + +------------------------------------------------+ + | | + | traffic generator | + | | + +------------------------------------------------+ + + +PXP deployment is backward compatible with PVP deployment, where ``pvp`` is +an alias for ``pvvp1`` and it executes just one VM. + +The number of interfaces used by VMs is defined by configuration option +``GUEST_NICS_NR``. In case that more than one pair of interfaces is defined +for VM, then: + + * for ``pvvp`` (serial) scenario every NIC pair is connected in serial + before connection to next VM is created + * for ``pvpv`` (parallel) scenario every NIC pair is directly connected + to the physical ports and unique traffic stream is assigned to it + +Examples: + + * Deployment ``pvvp10`` will start 10 VMs and connects them in series + * Deployment ``pvpv4`` will start 4 VMs and connects them in parallel + * Deployment ``pvpv1`` and GUEST_NICS_NR = [4] will start 1 VM with + 4 interfaces and every NIC pair is directly connected to the + physical ports + * Deployment ``pvvp`` and GUEST_NICS_NR = [2, 4] will start 2 VMs; + 1st VM will have 2 interfaces and 2nd VM 4 interfaces. These interfaces + will be connected in serial, i.e. traffic will flow as follows: + PHY1 -> VM1_1 -> VM1_2 -> VM2_1 -> VM2_2 -> VM2_3 -> VM2_4 -> PHY2 + +Note: In case that only 1 or more than 2 NICs are configured for VM, +then ``testpmd`` should be used as forwarding application inside the VM. +As it is able to forward traffic between multiple VM NIC pairs. + +Note: In case of ``linux_bridge``, all NICs are connected to the same +bridge inside the VM. + Packet Forwarding SRIOV Scenario ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -622,12 +805,92 @@ PCI passthrough support. Note: Qemu with PCI passthrough support can be used only with PVP test deployment. +Guest Core and Thread Binding +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +VSPERF provides options to achieve better performance by guest core binding and +guest vCPU thread binding as well. Core binding is to bind all the qemu threads. +Thread binding is to bind the house keeping threads to some CPU and vCPU thread to +some other CPU, this helps to reduce the noise from qemu house keeping threads. + + +.. code-block:: python + + GUEST_CORE_BINDING = [('#EVAL(6+2*#VMINDEX)', '#EVAL(7+2*#VMINDEX)')] + +**NOTE** By default the GUEST_THREAD_BINDING will be none, which means same as +the GUEST_CORE_BINDING, i.e. the vcpu threads are sharing the physical CPUs with +the house keeping threads. Better performance using vCPU thread binding can be +achieved by enabling affinity in the custom configuration file. + +For example, if an environment requires 28,29 to be core binded and 30,31 for +guest thread binding to achieve better performance. + +.. code-block:: python + + VNF_AFFINITIZATION_ON = True + GUEST_CORE_BINDING = [('28','29')] + GUEST_THREAD_BINDING = [('30', '31')] + +Qemu CPU features +^^^^^^^^^^^^^^^^^ + +QEMU default to a compatible subset of performance enhancing cpu features. +To pass all available host processor features to the guest. + +.. code-block:: python + + GUEST_CPU_OPTIONS = ['host,migratable=off'] + +**NOTE** To enhance the performance, cpu features tsc deadline timer for guest, +the guest PMU, the invariant TSC can be provided in the custom configuration file. + +Selection of loopback application for tests with VMs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To select the loopback applications which will forward packets inside VMs, +the following parameter should be configured: + +.. code-block:: python + + GUEST_LOOPBACK = ['testpmd'] + +or use ``--test-params`` CLI argument: + +.. code-block:: console + + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ + --test-params "GUEST_LOOPBACK=['testpmd']" + +Supported loopback applications are: + +.. code-block:: console + + 'testpmd' - testpmd from dpdk will be built and used + 'l2fwd' - l2fwd module provided by Huawei will be built and used + 'linux_bridge' - linux bridge will be configured + 'buildin' - nothing will be configured by vsperf; VM image must + ensure traffic forwarding between its interfaces + +Guest loopback application must be configured, otherwise traffic +will not be forwarded by VM and testcases with VM related deployments +will fail. Guest loopback application is set to 'testpmd' by default. + +**NOTE:** In case that only 1 or more than 2 NICs are configured for VM, +then 'testpmd' should be used. As it is able to forward traffic between +multiple VM NIC pairs. + +**NOTE:** In case of linux_bridge, all guest NICs are connected to the same +bridge inside the guest. + Results ~~~~~~~ -The results for the packet forwarding test cases are uploaded to artifacts. -The link for the same can be found below +The results for the packet forwarding test cases are uploaded to artifacts and +also published on Yardstick Grafana dashboard. +The links for the same can be found below .. code:: bash http://artifacts.opnfv.org/kvmfornfv.html + http://testresults.opnfv.org/KVMFORNFV-Packet-Forwarding |