| 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 |
| :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: |
| |
| .. 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 |
| |
| |
| 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. |
| |
| |