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/configuration/pseudowire.rst b/configuration/pseudowire.rst
index 60d1ca0..09b3917 100644
--- a/configuration/pseudowire.rst
+++ b/configuration/pseudowire.rst
@@ -1,19 +1,28 @@
Pseudowire
==========
-In Trellis, we assign different subnets to hosts that attach to different edge (leaf) switches.
-These hosts communicate over IP when traversing the spine switches, meaning that the layer-2 header is not preserved across transportation.
-However, in some use cases it is beneficial for hosts that connect to different leaves to be able to talk directly over L2 and also belong to the same IP subnet.
+In Trellis, we assign different subnets to hosts that attach to different edge
+(leaf) switches. These hosts communicate over IP when traversing the spine
+switches, meaning that the layer-2 header is not preserved across
+transportation. However, in some use cases it is beneficial for hosts that
+connect to different leaves to be able to talk directly over L2 and also belong
+to the same IP subnet.
+
We implemented Pseudowire (PW) in Trellis to fulfill this requirement.
-Pseudowires create tunnels between different connection points that transport L2 traffic between them.
-Pseudowires can handle single-tagged/double-tagged traffic and are able to modify the VLAN tags in some cases.
+Pseudowires create tunnels between different connection points that transport
+L2 traffic between them.
+
+Pseudowires can handle single-tagged/double-tagged traffic and are able to
+modify the VLAN tags in some cases.
.. note::
Pseudowires are only supported on OF-DPA hardware switches.
Managing pseudowires via REST
-----------------------------
+
You can find the REST API documentation at ``http://${ONOS-IP}:8181/onos/v1/docs``.
+
Please click the drop down list and select Segment Routing Server.
.. image:: ../images/config-pw-rest.png
@@ -27,9 +36,9 @@
$ curl --user onos:rocks -X GET -H 'Content-Type:application/json' http://${ONOS-IP}:8181/onos/segmentrouting/pseudowire/ -d@pseudowire.json
$ curl --user onos:rocks -X DELETE -H 'Content-Type:application/json' http://${ONOS-IP}:8181/onos/segmentrouting/pseudowire/ -d@pseudowire.json
-Below is an example configuration for a single pseudowire,
-which transfers L2 double tagged traffic from cp1 to cp2 and also changes the outer VLAN tag of the packets.
-
+Below is an example configuration for a single pseudowire, which transfers L2
+double tagged traffic from cp1 to cp2 and also changes the outer VLAN tag of
+the packets.
.. code-block:: json
@@ -47,13 +56,21 @@
}
- ``cP1``: First connection point of PW
+
- ``cP2``: Second connection point of PW
-- ``cP1InnerTag / cp1OuterTag``: The expected inner and outer VLAN tags for ``cp1``. If you only want to use a single incoming tag,
- use the innerTag, and use ``None`` for the outerTag.
+
+- ``cP1InnerTag / cp1OuterTag``: The expected inner and outer VLAN tags for
+ ``cp1``. If you only want to use a single incoming tag, use the innerTag, and
+ use ``None`` for the outerTag.
+
- ``cP2InnerTag / cp2OuterTag``: The expected inner and outer VLAN tags for ``cp2``.
+
- ``mode``: Pseudowire mode - RAW and TAGGED. Only RAW mode is supported in Trellis.
+
- ``sdTag``: Service delimiting tag, only meaningful when in TAGGED mode.
+
- ``pwLabel``: Unique pseudowire label.
+
- ``pwId``: ID of the pseudowire.
The REST API also supports bulk addition and removal of pseudowire.
@@ -131,50 +148,76 @@
Type of pseudowires
-------------------
+
- **Leaf - Leaf** : As explained above we support leaf - leaf pseudowires.
-- **Spine - Leaf** : We further support leaf to spine pseudowires,
- where one termination point resides in a spine switch rather than a leaf switch.
- Please note that the encapsulated traffic for these types of pseudowires is carried **tagged** between leaf and spines,
- the reason for this is due to some hardware limitation. The **reserved transport VLAN is 4093**.
+- **Spine - Leaf** : We further support leaf to spine pseudowires, where one
+ termination point resides in a spine switch rather than a leaf switch.
+ Please note that the encapsulated traffic for these types of pseudowires is
+ carried **tagged** between leaf and spines, the reason for this is due to
+ some hardware limitation. The **reserved transport VLAN is 4093**.
- Multi-stage
- - **Leaf - Spine-1 - Spine-2**: Where Spine-1 and Spine-2 are interconnected between them and are part of distinct topologies.
- - **Leaf_1 - Spine_1 - Spine_2 - Leaf_2**: Where leaf-1 and leaf-2 are part of different fabric topologies which are interconnected between them between two spines.
+ - **Leaf - Spine-1 - Spine-2**: Where Spine-1 and Spine-2 are interconnected
+ between them and are part of distinct topologies.
+
+ - **Leaf_1 - Spine_1 - Spine_2 - Leaf_2**: Where leaf-1 and leaf-2 are part
+ of different fabric topologies which are interconnected between them
+ between two spines.
Common errors
-------------
-If your pseudowires do not work make sure you have done the following in the host side :
-- Disabled VLAN offloading in the VM interfaces and also in the compute node interfaces.
+If your pseudowires do not work make sure you have done the following in the
+host side:
+
+- Disabled VLAN offloading in the VM interfaces and also in the compute node
+ interfaces.
+
- Set the compute node interfaces and the VM interfaces at promiscuous mode.
-- In general, do the above for all the interfaces and bridges participated in the topology (either in a VM or physical server).
-- Before programming pseudowires make sure that the topology is completely up and running and also the configuration is added to the controller and the fabric is
- in an operational state.
+
+- In general, do the above for all the interfaces and bridges participated in
+ the topology (either in a VM or physical server).
+
+- Before programming pseudowires make sure that the topology is completely up
+ and running and also the configuration is added to the controller and the
+ fabric is in an operational state.
Restrictions
------------
-We list now some restrictions of pseudowire support, some of them stem from the implementation while others from switch hardware constraints.
+
+We list now some restrictions of pseudowire support, some of them stem from the
+implementation while others from switch hardware constraints.
- We only support pseudowires with the same type of tagged traffic at each end.
- For example, if cP1 handles single tagged traffic then cP2 must handle single tagged traffic (same applies for single tagged and double tagged traffic).
- However, for pseudowires with single tagged traffic we support changing the tag,
- and for pseudowires with double tagged traffic we support changing the outer tag.
- We would like to support more use cases, however we are limited by hardware pipeline restrictions.
- In the future, and if needed, we might address this by using the egress tables of OF-DPA.
-- As of now, we only support RAW mode. We will support also TAGGED mode in the future if needed by any use case.
- Since, we only support RAW mode the sdTag must always be empty or None.
+ For example, if cP1 handles single tagged traffic then cP2 must handle single
+ tagged traffic (same applies for single tagged and double tagged traffic).
+ However, for pseudowires with single tagged traffic we support changing the
+ tag, and for pseudowires with double tagged traffic we support changing the
+ outer tag. We would like to support more use cases, however we are limited
+ by hardware pipeline restrictions. In the future, and if needed, we might
+ address this by using the egress tables of OF-DPA.
+- As of now, we only support RAW mode. We will support also TAGGED mode in the
+ future if needed by any use case. Since, we only support RAW mode the
+ ``sdTag`` must always be empty or None.
Implementation limits
---------------------
+
- **Link failures**: We partially support link failures.
- Specifically, our PW implementation does not properly handle link failures when the link involved is the one used for pseudowire traffic at the spine switches towards a leaf switch.
- This is due to an OF-DPA limitation which does not allow the use of MPLS ECMP groups in the spine.
+ Specifically, our PW implementation does not properly handle link failures
+ when the link involved is the one used for pseudowire traffic at the spine
+ switches towards a leaf switch.
+
+ This is due to an OF-DPA limitation which does not allow the use of MPLS ECMP
+ groups in the spine.
+
We plan to address this in the next release.
-- **Device failures**: We do not handle device failures currently, on a device failure please remove and re-install the pseudowire.
- We will address this soon.
+- **Device failures**: We do not handle device failures currently, on a device
+ failure please remove and re-install the pseudowire. We will address this
+ soon.