First pass up to configuration
Change-Id: Ifd82c38aa18d5216c5772a64d9d77046def005fe
diff --git a/configuration/network.rst b/configuration/network.rst
index dbe6426..5bf70aa 100644
--- a/configuration/network.rst
+++ b/configuration/network.rst
@@ -3,8 +3,8 @@
Network Configuration
=====================
SD-Fabric uses several different types of network configurations.
-We only focus on ``devices`` and ``ports`` configuration in this section.
-With these configured properly, SD-Fabric can provide basic L2/L3 connectivity.
+We only focus on ``devices`` and ``ports`` configuration in this section, which
+are used to provide basic L2/L3 connectivity.
See :ref:`advanced-features` for advanced feature configurations.
@@ -36,7 +36,7 @@
}
}
-- ``device:leaf1``: DPID of the device.
+- ``device:leaf1``: arbitrary globally unique identifier of the device, must always be prefixed with ``device:``.
- ``ipv4NodeSid``: IPv4 node segment ID, which is used as an MPLS label in
forwarding IPv4 traffic. Can be arbitrary and should be globally unique.
@@ -61,38 +61,80 @@
- ``isEdgeRouter``: True for leaf switches. False for spine switches.
-- ``adjacencySids``: Deprecated. Just put an empty array for now.
+- ``adjacencySids``: Deprecated. Always use an empty array.
-- ``name``: Name of the device. It is an arbitrary name to identify the device easily.
+- ``name``: Human friendly name used in the ONOS UI.
-- ``managementAddress``: gRPC endpoint of the Stratum device and a numerical device ID.
- The IP address can be replaced by domain name as well.
+- ``managementAddress``: gRPC endpoint of the Stratum device and the P4Runtime
+ internal device ID associated to the ASIC (usually ``1``),
+ in the format of ``grpc://[device_addr]?device_id=[P4Runtime device ID]``
+ The IP address can be replaced by a domain name.
- ``driver``: ``stratum-bmv2`` or ``stratum-tofino``, depending on which switch this is.
-- ``pipeconf``: A list of available pipeconfs can be dumped by running ``pipeconfs`` in ONOS CLI.
- Select the pipeconf you would like to use for this device.
+- ``pipeconf``: the P4 program to deploy on this switch. A list of available
+ pipeconfs can be dumped by running ``pipeconfs`` in the ONOS CLI. When running
+ with Tofino-based devices, we provide pre-installed pipeconfs with ID
+ ``org.stratumproject.<profile>.<device-type>_<bf-sde-version>``:
+
+ - The available *profiles* are:
+
+ - ``fabric``: for basic L2/L3 capabilities
+ - ``fabric-spgw``: with 4G/5G mobile user plane support
+ - ``fabric-int``: with INT support
+ - ``fabric-spgw-int``: with SPGW and INT support
+
+ - The supported *device-types*:
+
+ - ``montara``: for dual-pipe Tofino ASIC SKUs
+ - ``mavericks``: for quad-pipe Tofino ASIC SKUs
+
+ - The Intel/Barefoot SDE version used in Stratum, e.g., ``sde_9_5_0``
.. caution::
- We should avoid using reserved MPLS labels for ``ipv4NodeSid`` and
+ You should avoid using reserved MPLS labels for ``ipv4NodeSid`` and
``ipv6NodeSid``. Please check here for the reserved values:
http://www.iana.org/assignments/mpls-label-values/mpls-label-values.xhtml
.. note::
- Most of the SD-Fabric configurations support dynamic configuration updates.
- Unfortunately, SD-Fabric currently **do not support dynamic device
- configuration updates**. You will have to restart the device when if
- corresponding device configuration changes.
+ Most of the SD-Fabric configurations support dynamic updates. Unfortunately,
+ we currently **do not support dynamic device configuration updates**. You
+ will have to restart (reboot) the switch if the corresponding device
+ configuration changes.
Having said that, when introducing a completely new device in the network,
- the device configurations pushed before the device's connection should
- apply correctly.
+ the device configurations pushed before ONOS connects to the switch for the
+ first time should be applied correctly.
+
+Port IDs for Tofino-based devices
+---------------------------------
+
+Before describing the ONOS netcfg, it is worth nothing how we refer to ports for
+Tofino-based devices. Netcfg uses the format ``device:<name>/<port-number>``.
+
+``<port-number>`` is a special value that is usually different than the number
+shown in the switch front panel. It is the same number used for P4 table
+programming and depends on the specific Tofino ASIC SKU (e.g., dual-pipe vs.
+quad-pipe) and switch vendor/platform. In Stratum this is often referred to as
+the *SDK port ID*, as this is the number used for all Tofino SDK calls. In Intel
+documentation this is referred to as the ``DP_ID``. We plan to remove this
+dependency on such a low level detail in future releases, but for now, to find
+out the mapping between front-panel ports and ``DP_ID`` you have the following
+options:
+
+- Ask your switch vendor
+- Use the command `pm.show` on the BF shell of a running Stratum instance
+ (see :ref:`troubleshooting_guide`)
Bridging and Unicast Routing
----------------------------
+In the following we illustrate how to enable basic bridging and routing on a
+per-port basis.
+
.. attention::
- VLAN **4094** is reserved for unconfigured ports (e.g. spine facing ports)
+ - VLAN **4090** is reserved for pseudowire transport flow rules on the spines
Access Ports
^^^^^^^^^^^^
@@ -103,13 +145,13 @@
{
"ports" : {
- "of:0000000000000204/12" : {
+ "device:leaf1/12" : {
"interfaces" : [{
"name" : "serverA-intf",
"vlan-untagged": 10
}]
},
- "of:0000000000000204/16" : {
+ "device:leaf1/16" : {
"interfaces" : [{
"name" : "serverB-intf",
"vlan-untagged": 10
@@ -118,7 +160,7 @@
}
}
-The example above shows two ports (12 and 16) on switch ``of:204`` that have
+The example above shows two ports (12 and 16) on switch ``leaf1`` 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,
@@ -138,14 +180,14 @@
{
"ports" : {
- "of:0000000000000204/12" : {
+ "device:leaf1/12" : {
"interfaces" : [{
"name" : "serverA-intf",
"ips" : [ "10.0.1.254/24"],
"vlan-untagged": 10
}]
},
- "of:0000000000000204/16" : {
+ "device:leaf1/16" : {
"interfaces" : [{
"name" : "serverB-intf",
"ips" : [ "10.0.1.254/24"],
@@ -170,8 +212,8 @@
the same VLAN. This is possible by adding more subnet/gateway IPs in the
``ips`` array.
-.. tip::
- One subnet cannot be configured on multiple leaf switches.
+.. attention::
+ The same subnet cannot be configured on multiple leaf switches.
We usually configure one subnet for all the ports on the same leaf switch.
@@ -183,7 +225,7 @@
{
"ports" : {
- "of:0000000000000204/24" : {
+ "device:leaf1/24" : {
"interfaces" : [{
"name" : "serverA-intf",
"ips" : [ "10.0.2.254/24", "10.0.4.254/24" ],
@@ -193,8 +235,8 @@
}
}
-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.
+The configuration above for port 24 on switch ``leaf1`` 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.
@@ -216,7 +258,7 @@
{
"ports" : {
- "of:0000000000000204/24" : {
+ "device:leaf1/24" : {
"interfaces" : [ {
"name" : "serverA-intf",
"ips" : [ "10.0.2.254/24", "10.0.4.254/24", "10.0.1.254/24" ],
@@ -230,8 +272,8 @@
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
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuring interface for IPv6 [#f1]_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is similar to configure IPv6 routing. Simply replace the addresses in
``ips`` with IPv6 addresses. For example:
@@ -240,7 +282,7 @@
{
"ports" : {
- "of:0000000000000204/24" : {
+ "device:leaf1/24" : {
"interfaces" : [ {
"name" : "serverA-intf",
"ips" : [ "10.0.2.254/24", "2000::1ff/120" ],
@@ -254,8 +296,8 @@
There is a known issue that breaks dynamic VLAN configuration.
Until the issue get resolved, you need to restart the switch agent to reinstall the flows.
-IPv6 Router Advertisement
-^^^^^^^^^^^^^^^^^^^^^^^^^
+IPv6 Router Advertisement [#f1]_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Router Advertisement overview
"""""""""""""""""""""""""""""
@@ -326,7 +368,7 @@
{
"ports": {
- "of:0000000000000018/16": {
+ "device:leaf2/16": {
"interfaces": [{
"ips": [ "192.168.114.1/24", "2001:0558:FF10:04C9::2:1ff/120", "FE80::4EA8:2AFF:FE24:8E5F/120" ],
"vlan-untagged": "11",
@@ -349,7 +391,7 @@
{
"devices": {
- "of:0000000000000018": {
+ "device:leaf2": {
"routeradvertisement" : {
"prefixes": [ "2001:0558:FF10:04C9::3:1ff/120"]
}
@@ -388,7 +430,7 @@
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.
+is restricted to one ToR.
If the bridging domain is extended across two ToRs directly linked to each
other, there is a chance of loops.
@@ -397,3 +439,7 @@
not be used as such.
.. image:: ../images/config-vlan-invalid.png
+
+.. rubric:: Footnotes
+
+.. [#f1] IPv6 support on the data plane (P4 program) is still work-in-progress.