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/multicast.rst b/configuration/multicast.rst
index a33fe3c..1d435b0 100644
--- a/configuration/multicast.rst
+++ b/configuration/multicast.rst
@@ -2,8 +2,14 @@
=========
Trellis supports IP multicast in an classic SDN way.
-**None of the common IP multicast protocols (e.g. IGMP, PIM) is used when calculating the multicast tree internally**.
-Instead, benefiting from SDN, Trellis calculates the multicast tree in a centralized way and program the switches accordingly. Having said that, it doesn't prevent us from using common IP multicast protocols to communicate with externals.
+
+**None of the common IP multicast protocols (e.g. IGMP, PIM) is used when
+calculating the multicast tree internally**.
+
+Instead, benefiting from SDN, Trellis calculates the multicast tree in a
+centralized way and program the switches accordingly. Having said that, it
+doesn't prevent us from using common IP multicast protocols to communicate with
+externals.
Here's a summary of multicast features Trellis supports.
@@ -16,19 +22,30 @@
:width: 1000px
.. note::
- Dual-homed sinks and multiple sources support comes with major changes in the Multicast Routing subsystem.
- **Sink and sources are now identified by an ONOS HostId (MAC/VLAN)** and has associated a number of ConnectPoint while in the past we identified the sinks and the sources just using one ConnectPoint.
- Multicast subsystem listen for Host events and according to them modify properly the ConnectPoint associated to the HostId.
- In particular, it leverages the Host Location which is a collection of ONOS ConnectPoint where the Host is attached.
- This information is maintained updated by ONOS thanks to several discovery mechanisms implemented in the Host subsystem.
- Following image try to summarize the work flow of the Multicast Routing subsystem after the aforementioned changes:
+ Dual-homed sinks and multiple sources support comes with major changes in
+ the Multicast Routing subsystem.
+
+ **Sink and sources are now identified by an ONOS HostId (MAC/VLAN)** and
+ has associated a number of ConnectPoint while in the past we identified the
+ sinks and the sources just using one ConnectPoint.
+
+ Multicast subsystem listen for Host events and according to them modify
+ properly the ConnectPoint associated to the HostId.
+
+ In particular, it leverages the Host Location which is a collection of ONOS
+ ConnectPoint where the Host is attached. This information is maintained
+ updated by ONOS thanks to several discovery mechanisms implemented in the
+ Host subsystem. Following image try to summarize the work flow of the
+ Multicast Routing subsystem after the aforementioned changes:
.. image:: ../images/config-mcast-internal.png
:width: 600px
:align: center
.. caution::
- We should avoid using reserved Multicast groups. Please check here for the reserved values: http://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml
+ We should avoid using reserved Multicast groups. Please check here for the
+ reserved values:
+ http://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml
Activate Multicast
@@ -39,7 +56,8 @@
onos> app activate mcast
-You can also add ``mcast`` into ``$ONOS_APPS`` environment variable such that it gets started automatically every time.
+You can also add ``mcast`` into ``$ONOS_APPS`` environment variable such that
+it gets started automatically every time.
CLI commands
@@ -47,25 +65,35 @@
Creating a route and adding sinks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In order to add a new Multicast route, we have to use ``mcast-host-join`` command and we need to provide following information:
+In order to add a new Multicast route, we have to use ``mcast-host-join``
+command and we need to provide following information:
+
1) **source address**; 2) **group address**; 3) **sources** ; 4) **sinks**.
+
Here's an example:
.. code-block:: console
onos> mcast-host-join -sAddr * -gAddr 224.0.0.1 -srcs 00:AA:00:00:00:01/None -srcs 00:AA:00:00:00:05/None -sinks 00:AA:00:00:00:03/None -sinks 00:CC:00:00:00:01/None
-- ``-sAddr``: we can provide **\* for ASM** or an **IP address for SSM**.
- At the time being we do not enforce the matching of the -sAddr on the data-plane;
-- ``-gAddr`` specifies Multicast group address
-- ``-srcs`` identifies the source we changed from ConnectPoint to HostId in this release.
-- ``-sinks`` specifies the sinks of the group, we changed from ConnectPoint to HostId in this release.
+- ``-sAddr``: we can provide **\* for ASM** or an **IP address for SSM**
+ At this time being we do not enforce the matching of the ``-sAddr`` on the
+ data plane.
+- ``-gAddr`` specifies Multicast group address
+
+- ``-srcs`` identifies the source we changed from ConnectPoint to HostId in
+ this release.
+
+- ``-sinks`` specifies the sinks of the group, we changed from ConnectPoint to
+ HostId in this release.
Removing a sink
^^^^^^^^^^^^^^^
-A sink can be removed through ``mcast-sink-delete`` command.
-The major difference is that the sinks to be removed is provided through ``-h`` option.
+
+A sink can be removed through ``mcast-sink-delete`` command. The major
+difference is that the sinks to be removed is provided through ``-h`` option.
+
If ``-h`` is not provided the command will issue a route removal.
.. code-block:: console
@@ -75,9 +103,11 @@
Modifying a source
^^^^^^^^^^^^^^^^^^
-We also provide a command to modify the sources of a Multicast group.
-In particular ``mcast-source-delete`` allows to modify the source connect points of a source.
-If ``-src`` is not provided, the command will issue a route removal
+
+We also provide a command to modify the sources of a Multicast group. In
+particular ``mcast-source-delete`` allows to modify the source connect points
+of a source. If ``-src`` is not provided, the command will issue a route
+removal
.. code-block:: console
@@ -109,14 +139,20 @@
REST APIs
---------
+
You can find the REST API documentation at ``http://<ONOS-IP>:8181/onos/v1/docs``.
+
Please click the drop down list and select Multicast API.
.. image:: ../images/config-mcast-rest.png
We configure and implement multicast routes through the dedicated REST API.
-Some of the APIs are outlined here, you can find complete list in the ONOS docs page.
-The referenced files in these examples can be found in ``$ONOS_ROOT/apps/mcast/web/src/main/resources/jsonExamples``
+
+Some of the APIs are outlined here, you can find complete list in the ONOS docs
+page.
+
+The referenced files in these examples can be found in
+``$ONOS_ROOT/apps/mcast/web/src/main/resources/jsonExamples``
GET operations
^^^^^^^^^^^^^^
@@ -246,8 +282,14 @@
}
- ``group``: IP address of the Multicast Group
-- ``source``: IP address of the Multicast source. If specified (e.g. 10.0.1.1) we will treat this route as SSM (Single Source Multicast), if instead * is used the route will be ASM (Any Source Multicast)
-- ``sources``: Array containing the connect points to which the source is connected to.
-- ``sinks``: Array containing a set of Hosts that we want as sinks of the multicast stream. ONOS will automatically handle the connect points of these hosts if they are single or dual homed.
+- ``source``: IP address of the Multicast source. If specified (e.g. 10.0.1.1)
+ we will treat this route as SSM (Single Source Multicast), if instead * is
+ used the route will be ASM (Any Source Multicast)
+- ``sources``: Array containing the connect points to which the source is
+ connected to.
+
+- ``sinks``: Array containing a set of Hosts that we want as sinks of the
+ multicast stream. ONOS will automatically handle the connect points of these
+ hosts if they are single or dual homed.