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