Charles Chan | 9e5c617 | 2019-09-07 11:24:54 -0700 | [diff] [blame] | 1 | Multicast |
| 2 | ========= |
Charles Chan | 3d8c0ce | 2019-09-09 11:11:47 -0700 | [diff] [blame] | 3 | |
| 4 | Trellis supports IP multicast in an classic SDN way. |
| 5 | **None of the common IP multicast protocols (e.g. IGMP, PIM) is used when calculating the multicast tree internally**. |
| 6 | 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. |
| 7 | |
| 8 | Here's a summary of multicast features Trellis supports. |
| 9 | |
| 10 | - Support both **IPv4 and IPv6** multicast |
| 11 | - Support **multi-stage** topology |
| 12 | - Support **dual-homed sinks** (with failure recovery) |
| 13 | - Support **multiple sources** |
| 14 | |
| 15 | .. image:: ../images/config-mcast.png |
| 16 | |
| 17 | .. note:: |
| 18 | Dual-homed sinks and multiple sources support comes with major changes in the Multicast Routing subsystem. |
| 19 | **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. |
| 20 | Multicast subsystem listen for Host events and according to them modify properly the ConnectPoint associated to the HostId. |
| 21 | In particular, it leverages the Host Location which is a collection of ONOS ConnectPoint where the Host is attached. |
| 22 | This information is maintained updated by ONOS thanks to several discovery mechanisms implemented in the Host subsystem. |
| 23 | Following image try to summarize the work flow of the Multicast Routing subsystem after the aforementioned changes: |
| 24 | |
| 25 | .. image:: ../images/config-mcast-internal.png |
| 26 | :width: 600px |
| 27 | :align: center |
| 28 | |
| 29 | |
| 30 | Activate Multicast |
| 31 | ------------------ |
| 32 | The multicast service need to be activated by the following command: |
| 33 | |
| 34 | .. code-block:: console |
| 35 | |
| 36 | onos> app activate mcast |
| 37 | |
| 38 | You can also add ``mcast`` into ``$ONOS_APPS`` environment variable such that it gets started automatically every time. |
| 39 | |
| 40 | |
| 41 | CLI commands |
| 42 | ------------ |
| 43 | |
| 44 | Creating a route and adding sinks |
| 45 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 46 | In order to add a new Multicast route, we have to use ``mcast-host-join`` command and we need to provide following information: |
| 47 | 1) **source address**; 2) **group address**; 3) **sources** ; 4) **sinks**. |
| 48 | Here's an example: |
| 49 | |
| 50 | .. code-block:: console |
| 51 | |
| 52 | 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 |
| 53 | |
| 54 | - ``-sAddr``: we can provide **\* for ASM** or an **IP address for SSM**. |
| 55 | At the time being we do not enforce the matching of the -sAddr on the data-plane; |
| 56 | - ``-gAddr`` specifies Multicast group address |
| 57 | - ``-srcs`` identifies the source we changed from ConnectPoint to HostId in this release. |
| 58 | - ``-sinks`` specifies the sinks of the group, we changed from ConnectPoint to HostId in this release. |
| 59 | |
| 60 | |
| 61 | Removing a sink |
| 62 | ^^^^^^^^^^^^^^^ |
| 63 | A sink can be removed through ``mcast-sink-delete`` command. |
| 64 | The major difference is that the sinks to be removed is provided through ``-h`` option. |
| 65 | If ``-h`` is not provided the command will issue a route removal. |
| 66 | |
| 67 | .. code-block:: console |
| 68 | |
| 69 | onos> mcast-sink-delete -sAddr * -gAddr 224.0.0.1 -h 00:AA:00:00:00:03/None |
| 70 | |
| 71 | |
| 72 | Modifying a source |
| 73 | ^^^^^^^^^^^^^^^^^^ |
| 74 | We also provide a command to modify the sources of a Multicast group. |
| 75 | In particular ``mcast-source-delete`` allows to modify the source connect points of a source. |
| 76 | If ``-src`` is not provided, the command will issue a route removal |
| 77 | |
| 78 | .. code-block:: console |
| 79 | |
| 80 | onos> mcast-source-delete -sAddr * -gAddr 224.0.0.1 -src 00:AA:00:00:00:01/None |
| 81 | |
| 82 | |
| 83 | Removing a route |
| 84 | ^^^^^^^^^^^^^^^^ |
| 85 | The removal of a route can be achieved in several ways: |
| 86 | |
| 87 | 1. **removing all sources** |
| 88 | |
| 89 | .. code-block:: console |
| 90 | |
| 91 | 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 |
| 92 | |
| 93 | 2. **not providing -h to the mcast-host-delet** command |
| 94 | |
| 95 | .. code-block:: console |
| 96 | |
| 97 | onos> mcast-sink-delete -sAddr * -gAddr 224.0.0.1 |
| 98 | |
| 99 | 3. **not providing -src option to the mcast-source-delete** command. |
| 100 | |
| 101 | .. code-block:: console |
| 102 | |
| 103 | onos> mcast-source-delete -sAddr * -gAddr 224.0.0.1 |
| 104 | |
| 105 | |
| 106 | REST APIs |
| 107 | --------- |
| 108 | You can find the REST API documentation at ``http://<ONOS-IP>:8181/onos/v1/docs``. |
| 109 | Please click the drop down list and select Multicast API. |
| 110 | |
| 111 | .. image:: ../images/config-mcast-rest.png |
| 112 | |
| 113 | We configure and implement multicast routes through the dedicated REST API. |
| 114 | Some of the APIs are outlined here, you can find complete list in the ONOS docs page. |
| 115 | The referenced files in these examples can be found in ``$ONOS_ROOT/apps/mcast/web/src/main/resources/jsonExamples`` |
| 116 | |
| 117 | GET operations |
| 118 | ^^^^^^^^^^^^^^ |
| 119 | |
| 120 | - Get all routes |
| 121 | |
| 122 | .. code-block:: console |
| 123 | |
| 124 | $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast' |
| 125 | |
| 126 | - Get a specific route |
| 127 | |
| 128 | .. code-block:: console |
| 129 | |
| 130 | $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/{group_ip}/{source_ip}/' |
| 131 | |
| 132 | - Get all source connect point for a route |
| 133 | |
| 134 | .. code-block:: console |
| 135 | |
| 136 | $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sources/{group_ip}/{source_ip}/' |
| 137 | |
| 138 | - Get all sink connect points for a route |
| 139 | |
| 140 | .. code-block:: console |
| 141 | |
| 142 | $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sinks/{group_ip}/{source_ip}/' |
| 143 | |
| 144 | - Get all connect points for a given host Id in a given route |
| 145 | |
| 146 | .. code-block:: console |
| 147 | |
| 148 | $ curl --user onos:rocks -X GET -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast' |
| 149 | |
| 150 | |
| 151 | POST operations |
| 152 | ^^^^^^^^^^^^^^^ |
| 153 | |
| 154 | - Single route post |
| 155 | |
| 156 | .. code-block:: console |
| 157 | |
| 158 | $ curl --user onos:rocks -X POST -H 'Content-Type:application/json' http://<controller-ip>:8181/onos/mcast/mcast -d@mcastRoute.json |
| 159 | |
| 160 | - Bulk routes post |
| 161 | |
| 162 | .. code-block:: console |
| 163 | |
| 164 | $ curl --user onos:rocks -X POST -H 'Content-Type:application/json' http://<controller-ip>:8181/onos/mcast/mcast/bulk -d@mcastRoutes.json |
| 165 | |
| 166 | - Add a specific set of source connect points to a given route |
| 167 | |
| 168 | .. code-block:: console |
| 169 | |
| 170 | $ 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 |
| 171 | |
| 172 | - Add a specific set of host Ids as sinks to a given route |
| 173 | |
| 174 | .. code-block:: console |
| 175 | |
| 176 | $ 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 |
| 177 | |
| 178 | - Add a specific set of connect points from a host source for a given route |
| 179 | |
| 180 | .. code-block:: console |
| 181 | |
| 182 | $ 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 |
| 183 | |
| 184 | - Add a specific set of connect points from a host sink from a given route |
| 185 | |
| 186 | .. code-block:: console |
| 187 | |
| 188 | $ 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 |
| 189 | |
| 190 | |
| 191 | DELETE operations |
| 192 | ^^^^^^^^^^^^^^^^^ |
| 193 | |
| 194 | - Remove all routes |
| 195 | |
| 196 | .. code-block:: console |
| 197 | |
| 198 | $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast |
| 199 | |
| 200 | - Bulk route removal |
| 201 | |
| 202 | .. code-block:: console |
| 203 | |
| 204 | $ curl --user onos:rocks -X DELETE -H 'Content-Type:application/json' http://<controller-ip>:8181/onos/mcast/mcast/bulk -d@mcastRoutes.json |
| 205 | |
| 206 | - Remove a specific route given group and ip |
| 207 | |
| 208 | .. code-block:: console |
| 209 | |
| 210 | $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/{group_ip}/{source_ip}' |
| 211 | |
| 212 | - Remove a specific source from a given route |
| 213 | |
| 214 | .. code-block:: console |
| 215 | |
| 216 | $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sources/{group_ip}/{source_ip}/{host_id}' |
| 217 | |
| 218 | - Remove a specific sink from a given route |
| 219 | |
| 220 | .. code-block:: console |
| 221 | |
| 222 | $ curl --user onos:rocks -X DELETE -H 'Accept: application/json' 'http://<controller-ip>:8181/onos/mcast/mcast/sinks/{group_ip}/{source_ip}/{host_id}' |
| 223 | |
| 224 | |
| 225 | JSON Example |
| 226 | ^^^^^^^^^^^^ |
| 227 | Below we find the configuration json for a single multicast route. |
| 228 | |
| 229 | .. code-block:: json |
| 230 | |
| 231 | { |
| 232 | "group": "224.0.1.1", |
| 233 | "source": "*", |
| 234 | "sources": [ |
| 235 | "00:AA:00:00:00:01/None", |
| 236 | "00:AA:00:00:00:05/None" |
| 237 | ], |
| 238 | "sinks": [ |
| 239 | "00:CC:00:00:00:01/None", |
| 240 | "00:AA:00:00:00:03/None" |
| 241 | ] |
| 242 | } |
| 243 | |
| 244 | - ``group``: IP address of the Multicast Group |
| 245 | - ``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) |
| 246 | - ``sources``: Array containing the connect points to which the source is connected to. |
| 247 | - ``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. |
| 248 | |
| 249 | |