Update Sphinx version and versioning process
- Updated to newer Sphinx version
- Changed to use doc8 to check .rst files
- Added a dictionary (dict.txt) and spellchecking
- Reformatted and fixed issues that were found in the content
Change-Id: If7b35e01ee8be25dbbd1ecd0e67b264aa6cc2a94
diff --git a/troubleshooting.rst b/troubleshooting.rst
index 4412a28..0a50212 100644
--- a/troubleshooting.rst
+++ b/troubleshooting.rst
@@ -4,10 +4,16 @@
Overview
========
-The **Trellis Troubleshooting Tools (T3)** is an ONOS application intended to **help you troubleshoot traffic-related problems** in your network by **tracing installed flows and groups**.
-T3 works both on simulated OVS-based topologies but also on real HW, basing it's internal decisions on the driver assigned to the device.
-T3 also currently supports dual links between leaf and spine and properly handles the difference between deferred and immediate rules.
-Dual Homed hosts are also supported in T3.
+The **Trellis Troubleshooting Tools (T3)** is an ONOS application intended to
+**help you troubleshoot traffic-related problems** in your network by **tracing
+installed flows and groups**.
+
+T3 works both on simulated OVS-based topologies but also on real HW, basing
+it's internal decisions on the driver assigned to the device.
+
+T3 also currently supports dual links between leaf and spine and properly
+handles the difference between deferred and immediate rules. Dual Homed hosts
+are also supported in T3.
To activate this tool on your ONOS environment, you need to run:
@@ -28,8 +34,11 @@
t3-troubleshoot
===============
+
As of right now the tools provides a CLI command (troubleshoot).
-As arguments to the CLI command you have to pass arguments describing the packet you want to trace through the network.
+
+As arguments to the CLI command you have to pass arguments describing the
+packet you want to trace through the network.
t3-troubleshoot Help
--------------------
@@ -235,7 +244,8 @@
onos> t3-troubleshoot -vv -s 10.0.2.1 -sp of:0000000000000204/3 -sm 00:AA:00:00:00:01 -et IPV4 -d 10.0.3.1 -dm 00:00:00:00:02:04 -vid None
-This verbosity level prints all the flows and groups that are met along the path
+This verbosity level prints all the flows and groups that are met along the
+path:
.. code-block:: console
@@ -368,7 +378,9 @@
Successful Example
------------------
-In this example we trace a packet that should be bridged between two hosts in the same subnet
+
+In this example we trace a packet that should be bridged between two hosts in
+the same subnet
.. code-block:: console
@@ -381,9 +393,13 @@
Failed Example
--------------
+
Obviously failures can happen along one of the paths that the packet can take.
-In our sample we removed a flow in ``of:0000000000000226`` thus disabling that possible path for our initial packet.
-The output of our trace would then look something like
+
+In our sample we removed a flow in ``of:0000000000000226`` thus disabling that
+possible path for our initial packet.
+
+The output of our trace would then look something like:
.. code-block:: console
@@ -396,7 +412,8 @@
Reached required destination Host
No output out of device of:0000000000000226 Packet is dropped
-Notice that on the second path that was previously going through ``of:0000000000000226`` now the packet is dropped due to the rule we removed.
+Notice that on the second path that was previously going through
+``of:0000000000000226`` now the packet is dropped due to the rule we removed.
Example of Various Packet Types
-------------------------------
@@ -453,9 +470,15 @@
- LLDP from CONTROLLER
T3 is also capable of tracing packets coming in from the CONTROLLER.
- We use the same input port with the possibility to give CONTROLLER as logical port number.
- This is a mere convenience to carry the information inside T3 and do the proper flooding to all the ports of the given device.
- This case is not treated like all the rest and the input port here is a logical entity that has no match on any physical element on the device.
+
+ We use the same input port with the possibility to give CONTROLLER as logical
+ port number.
+
+ This is a mere convenience to carry the information inside T3 and do the
+ proper flooding to all the ports of the given device.
+
+ This case is not treated like all the rest and the input port here is a
+ logical entity that has no match on any physical element on the device.
.. code-block:: console
@@ -472,8 +495,15 @@
t3-troubleshoot-simple
======================
-T3 also offers a simplified version of the command to be able to ping between two given hosts without having to specify all the information.
-This commands bases itself on top of some configuration present in ONOS through netcfg, namely the VLAN interface configuration and the segment routing leaf router MAC for L3 Unicast. If that is not present the user needs to input this information manually recurring to the the previously shown command. Same verbosity levels and output as the troubleshoot command are possible.
+
+T3 also offers a simplified version of the command to be able to ping between
+two given hosts without having to specify all the information.
+
+This commands bases itself on top of some configuration present in ONOS through
+netcfg, namely the VLAN interface configuration and the segment routing leaf
+router MAC for L3 Unicast. If that is not present the user needs to input this
+information manually recurring to the the previously shown command. Same
+verbosity levels and output as the troubleshoot command are possible.
t3-troubleshoot-simple Help
---------------------------
@@ -575,8 +605,10 @@
t3-troubleshoot-mcast
=====================
-T3 also offers a mcast command queries the system for all the multicast routes given a certain vlanId.
-It prints all the traces given a certain group, source and source connect point. It has two "standard" verbosity levels.
+
+T3 also offers a mcast command queries the system for all the multicast routes
+given a certain vlanId. It prints all the traces given a certain group, source
+and source connect point. It has two "standard" verbosity levels.
t3-troubleshoot-mcast Help
--------------------------
@@ -614,8 +646,13 @@
<ONOS_IP>:8181/onos/v1/docs/#/t3
The rest API offered are a non verbose and a verbose version of the troubleshoot simple command.
-It bases itself on top of some configuration present in ONOS through netcfg, namely the VLAN interface configuration and the segment routing leaf router MAC for L3 Unicast.
-The use need to specify just the Source Host, the destination host and the ETH type.
+
+It bases itself on top of some configuration present in ONOS through netcfg,
+namely the VLAN interface configuration and the segment routing leaf router MAC
+for L3 Unicast.
+
+The use need to specify just the Source Host, the destination host and the ETH
+type.
.. code-block:: console
@@ -629,14 +666,24 @@
Last Resort
===========
-In the case where you can't figure out what is going wrong even with help of T3, you can seek help on Trellis developer mailing list ``trellis-dev@opennetworking.org``.
+In the case where you can't figure out what is going wrong even with help of
+T3, you can seek help on Trellis developer mailing list
+``trellis-dev@opennetworking.org``.
+
There are a few things we would like you to attach:
- **Issue description**
-- **Environment description**, such as ONOS version, switch model and OF-DPA version
+
+- **Environment description**, such as ONOS version, switch model and OF-DPA
+ version
+
- **Steps of reproduction**, as detail as possible
+
- **Diagnostics**.
- We have built a tool ``onos-diagnostics`` (see `ONOS Remote Admin Tools <https://wiki.onosproject.org/display/ONOS/ONOS+Remote+Admin+Tools>`_) to help you easily collect and package ONOS diagnostics
+
+ We have built a tool ``onos-diagnostics`` (see `ONOS Remote Admin Tools
+ <https://wiki.onosproject.org/display/ONOS/ONOS+Remote+Admin+Tools>`_) to
+ help you easily collect and package ONOS diagnostics
Reference