configuration/bridging-unicast.rst

Bridging and Unicast Routing
============================

Access Ports
------------
The necessary but minimum configuration for an access port is simply a VLAN.

.. code-block:: json
    :linenos:

    {
      "ports" : {
        "of:0000000000000204/12" : {
          "interfaces" : [{
            "name" : "serverA-intf",
            "vlan-untagged": 10
          }]
        },
        "of:0000000000000204/16" : {
          "interfaces" : [{
            "name" : "serverB-intf",
            "vlan-untagged": 10
          }]
        }
      }
    }

The example above shows two ports (12 and 16) on switch of:204 that have been assigned to VLAN 10 using the ``vlan-untagged`` keyword.
It simply means that packets come in and leave out of these switches untagged,
but internally they are assigned VLAN 10 and they belong to the bridging domain defined for VLAN 10.

``name`` is used to associate the interface with a globally unique, user friendly name. It can be omitted.

With the configuration shown above, the packets will always be bridged, but they cannot be routed out of the VLAN (e.g. to other subnets).
To add the capability to route out of VLAN 10, we need to add a subnet/gateway IP (similar to `interface-vlans or SVIs in traditional networks <https://www.youtube.com/watch?v=bUXpmiJpGb0>`_).

.. code-block:: json
    :linenos:

    {
      "ports" : {
        "of:0000000000000204/12" : {
          "interfaces" : [{
            "name" : "serverA-intf",
            "ips" : [ "10.0.1.254/24"],
            "vlan-untagged": 10
          }]
        },
        "of:0000000000000204/16" : {
          "interfaces" : [{
            "name" : "serverB-intf",
            "ips" : [ "10.0.1.254/24"],
            "vlan-untagged": 10
          }]
        }
      }
    }

In this example, VLAN 10 is associated with subnet ``10.0.1.0/24``, and the gateway IP for hosts in this subnet is ``10.0.1.254/32``.
When the desire is to route out of a VLAN, this assignment is currently necessary on all ports configured in the same VLAN.

.. note::

    Typically we only expect a single subnet for a VLAN. Similar to traditional networks, for us, a subnet == VLAN. Different VLANs should be configured in different subnets.
    In certain use-cases, it may be necessary to configure multiple subnets in the same VLAN. This is possible by adding more subnet/gateway IPs in the ``ips`` array.


Tagged Ports
------------
Tagged port configuration is similar.

.. code-block:: json
    :linenos:

    {
      "ports" : {
        "of:0000000000000204/24" : {
          "interfaces" : [{
            "name" : "serverA-intf",
            "ips" : [ "10.0.2.254/24", "10.0.4.254/24" ],
            "vlan-tagged" : [ 20, 40 ]
          }]
        }
      }
    }

The configuration above for port 24 on switch of:204 shows two VLANs 20 and 40 configured on that port, with corresponding subnets and gateway IPs.
Note that there is no specific ordering required in the ``ips`` or ``vlan-tagged`` arrays to correlate the VLANs to their corresponding subnets.
In a future release, we will correlate VLAN and subnets configuration in a more readable way.


Native VLAN on Tagged Ports
---------------------------
An additional configuration ``vlan-native`` possible on tagged ports includes the ability to specify a VLAN (and thus a bridging domain) for incoming untagged packets.
Typically, such configuration in trunk ports in traditional networks is referred to a native VLAN.

.. code-block:: json
    :linenos:

    {
      "ports" : {
        "of:0000000000000204/24" : {
          "interfaces" : [ {
            "name" : "serverA-intf",
            "ips" : [ "10.0.2.254/24", "10.0.4.254/24", "10.0.1.254/24" ],
            "vlan-tagged" : [ 20, 40 ],
            "vlan-native" : 10
          }]
        }
      }
    }

Note that it is also necessary to configure the subnet/gateway IP corresponding to the native VLAN if you wish to route out of that VLAN.


Configuring interface for IPv6
------------------------------
It is similar to configure IPv6 routing. Simply replace the addresses in ``ips`` with IPv6 addresses. For example,

.. code-block:: json
    :linenos:

    {
      "ports" : {
        "of:0000000000000204/24" : {
          "interfaces" : [ {
            "name" : "serverA-intf",
            "ips" : [ "10.0.2.254/24", "2000::1ff/120" ],
            "vlan-tagged" : [ 20, 40 ]
          }]
        }
      }
    }


IPv6 Router Advertisement
-------------------------

Router Advertisement overview
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Router advertisement application is for enabling **Router Advertisement** and **Router Solicitation** functionalities supported by IPv6 routers.
More details are available in `RFC 4861 <https://tools.ietf.org/html/rfc4861>`_.

Application identifies which IPv6 interfaces are currently configured in the system and it will try to send out **unsolicited Router Advertisement** (RA) messages from these interfaces.
Each such RA message will have two mandatory options named **Source link-layer address** and **MTU**.
Additional RA option **prefix** can be enabled using component configuration **raGlobalPrefixConfStatus**.

Application also processes **Router Solicitations** (RS) sent from hosts. Upon receiving RS on a particular interface application stops RA transmission in that interface and immediately sends RA targeted to the solicited host. After that application continues unsolicited RA transmission on that interface.

Activate and configure RA
^^^^^^^^^^^^^^^^^^^^^^^^^
RA application can be activated from CLI by running

.. code-block:: console

  onos> app activate routeradvertisement

Behavior of RA application is controlled by ONOS component configuration subsystem and following are possible configuration options.

- ``raThreadDelay``: Delay between consecutive RA transmissions
- ``raPoolSize``: Capacity of thread pool to be used for RA transmissions
- ``raFlagMbitStatus``: RA flag “Managed address configuration” enabled/disabled
- ``raFlagObitStatus``: RA flag “Other configuration” enabled/disabled
- ``raOptionPrefixStatus``: RA Option “prefix” is enabled/disabled. Router prefixes will be available in RA only if this flag is “true”
- ``raGlobalPrefixConfStatus``: Enable switch level global prefix configuration.
  Once “raGlobalPrefixConfStatus” is enabled, RA prefix option is generated from port configuration of device, see for more details.

Prefix details are picked up from network interface configuration.
RA app will filter out link-local IPs while preparing prefixes.
For example, in following configuration, Prefix will include only **2001:0558:FF10:04C9::2:1ff/120**.

.. code-block:: json

    {
      "ports": {
        "of:0000000000000018/16": {
          "interfaces": [{
            "ips": [ "192.168.114.1/24", "2001:0558:FF10:04C9::2:1ff/120", "FE80::4EA8:2AFF:FE24:8E5F/120" ],
            "vlan-untagged": "11",
            "name": "18-15",
            "mac": "8c:ea:1b:67:24:90"
          }]
        }
      }
    }

Global prefix configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^
In some cases, users may want to have a set of global prefix **advertised on all edge interfaces**.
Such prefixes can be configured in **devices** section of network configuration in the following way.

.. code-block:: json

    {
      "devices": {
        "of:0000000000000018": {
          "routeradvertisement" : {
            "prefixes": [ "2001:0558:FF10:04C9::3:1ff/120"]
          }
        }
      }
    }

.. note::
    When global prefix is configured, RA app will ignore any prefixes configured on switch interfaces.

Notes about interface config
----------------------------
There is no need to configure ports on switches that are meant to connect to other switches.
The VLAN (untagged or tagged) configuration is only meant for ports that are connected to hosts (edge ports).

.. image:: ../images/config-vlan.png

Furthermore, note that the same VLAN can be configured on multiple ToRs - e.g. vlan 20 in the figure above.
However this does not mean that the ports are in the same bridging domain, because in the fabric, the communication between ToRs is through a routed network. '
In other words, a host on VLAN 20 (untagged or tagged) connected to one ToR can communicate with another host on VLAN 20 (untagged or tagged) connected to a different ToR,
but the MAC addresses will change as the traffic goes through a routed network.

Please do not use this feature to connect switches in unsupported topologies as shown in the example below.
The fabric is not designed to be one big Ethernet fabric. The bridging domain is restricted to within one ToR.
If the bridging domain is extended across two ToRs directly linked to each other, there is a chance of loops.
In other words, the ToRs/Leafs are not standalone 802.1Q bridges, and should not be used as such.

.. image:: ../images/config-vlan-invalid.png