Added multicast
Change-Id: Ie4c417417569baa8ff8565c6321536a6c91a30d7
diff --git a/configuration/multicast.rst b/configuration/multicast.rst
index ca8cb97..3d34bf0 100644
--- a/configuration/multicast.rst
+++ b/configuration/multicast.rst
@@ -1,2 +1,249 @@
Multicast
=========
+
+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.
+
+Here's a summary of multicast features Trellis supports.
+
+- Support both **IPv4 and IPv6** multicast
+- Support **multi-stage** topology
+- Support **dual-homed sinks** (with failure recovery)
+- Support **multiple sources**
+
+.. image:: ../images/config-mcast.png
+
+.. 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:
+
+ .. image:: ../images/config-mcast-internal.png
+ :width: 600px
+ :align: center
+
+
+Activate Multicast
+------------------
+The multicast service need to be activated by the following command:
+
+.. code-block:: console
+
+ onos> app activate mcast
+
+You can also add ``mcast`` into ``$ONOS_APPS`` environment variable such that it gets started automatically every time.
+
+
+CLI commands
+------------
+
+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:
+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.
+
+
+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.
+If ``-h`` is not provided the command will issue a route removal.
+
+.. code-block:: console
+
+ onos> mcast-sink-delete -sAddr * -gAddr 224.0.0.1 -h 00:AA:00:00:00:03/None
+
+
+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
+
+.. code-block:: console
+
+ onos> mcast-source-delete -sAddr * -gAddr 224.0.0.1 -src 00:AA:00:00:00:01/None
+
+
+Removing a route
+^^^^^^^^^^^^^^^^
+The removal of a route can be achieved in several ways:
+
+1. **removing all sources**
+
+ .. code-block:: console
+
+ onos> mcast-source-delete -sAddr * -gAddr 224.0.0.1 -src 00:AA:00:00:00:01/None -src 00:AA:00:00:00:05/None
+
+2. **not providing -h to the mcast-host-delet** command
+
+ .. code-block:: console
+
+ onos> mcast-sink-delete -sAddr * -gAddr 224.0.0.1
+
+3. **not providing -src option to the mcast-source-delete** command.
+
+ .. code-block:: console
+
+ onos> mcast-source-delete -sAddr * -gAddr 224.0.0.1
+
+
+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``
+
+GET operations
+^^^^^^^^^^^^^^
+
+- Get all routes
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast'
+
+- Get a specific route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/{group_ip}/{source_ip}/'
+
+- Get all source connect point for a route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sources/{group_ip}/{source_ip}/'
+
+- Get all sink connect points for a route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sinks/{group_ip}/{source_ip}/'
+
+- Get all connect points for a given host Id in a given route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast'
+
+
+POST operations
+^^^^^^^^^^^^^^^
+
+- Single route post
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X POST -H 'Content-Type:application/json' http://<controller-ip>:8181/onos/mcast/mcast -d@mcastRoute.json
+
+- Bulk routes post
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X POST -H 'Content-Type:application/json' http://<controller-ip>:8181/onos/mcast/mcast/bulk -d@mcastRoutes.json
+
+- Add a specific set of source connect points to a given route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X POST -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sources/{group_ip}/{source_ip}/' -d@mcastSources.json
+
+- Add a specific set of host Ids as sinks to a given route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X POST -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sinks/{group_ip}/{source_ip}/' -d@mcastSinks.json
+
+- Add a specific set of connect points from a host source for a given route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X POST -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sources/{group_ip}/{source_ip}/{hostId}' -d@mcastSourcesHostId.json
+
+- Add a specific set of connect points from a host sink from a given route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X POST -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sinks/{group_ip}/{source_ip}/{hostId}' -d@mcastSinksHostId.json
+
+
+DELETE operations
+^^^^^^^^^^^^^^^^^
+
+- Remove all routes
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast
+
+- Bulk route removal
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X DELETE -H 'Content-Type:application/json' http://<controller-ip>:8181/onos/mcast/mcast/bulk -d@mcastRoutes.json
+
+- Remove a specific route given group and ip
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/{group_ip}/{source_ip}'
+
+- Remove a specific source from a given route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sources/{group_ip}/{source_ip}/{host_id}'
+
+- Remove a specific sink from a given route
+
+ .. code-block:: console
+
+ $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sinks/{group_ip}/{source_ip}/{host_id}'
+
+
+JSON Example
+^^^^^^^^^^^^
+Below we find the configuration json for a single multicast route.
+
+.. code-block:: json
+
+ {
+ "group": "224.0.1.1",
+ "source": "*",
+ "sources": [
+ "00:AA:00:00:00:01/None",
+ "00:AA:00:00:00:05/None"
+ ],
+ "sinks": [
+ "00:CC:00:00:00:01/None",
+ "00:AA:00:00:00:03/None"
+ ]
+ }
+
+- ``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.
+
+