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

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.