Update Sphinx version and versioning process
- Updated to newer Sphinx version
- Changed to use doc8 to check .rst files
- Added a dictionary (dict.txt) and spellchecking
- Reformatted and fixed issues that were found in the content
Change-Id: If7b35e01ee8be25dbbd1ecd0e67b264aa6cc2a94
diff --git a/configuration/bridging-unicast.rst b/configuration/bridging-unicast.rst
index 2dc8c92..7a590f9 100644
--- a/configuration/bridging-unicast.rst
+++ b/configuration/bridging-unicast.rst
@@ -7,10 +7,10 @@
Access Ports
------------
+
The necessary but minimum configuration for an access port is simply a VLAN.
.. code-block:: json
- :linenos:
{
"ports" : {
@@ -29,17 +29,23 @@
}
}
-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.
+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.
+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.
+``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>`_).
+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" : {
@@ -60,15 +66,24 @@
}
}
-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.
+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.
+ 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.
.. tip::
One subnet cannot be configured on multiple leaf switches.
+
We usually configure one subnet for all the ports on the same leaf switch.
Tagged Ports
@@ -76,7 +91,6 @@
Tagged port configuration is similar.
.. code-block:: json
- :linenos:
{
"ports" : {
@@ -90,18 +104,26 @@
}
}
-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.
+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.
+
+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" : {
@@ -116,15 +138,16 @@
}
}
-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.
-
+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,
+
+It is similar to configure IPv6 routing. Simply replace the addresses in
+``ips`` with IPv6 addresses. For example:
.. code-block:: json
- :linenos:
{
"ports" : {
@@ -144,36 +167,63 @@
Router Advertisement overview
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Router advertisement application is for enabling **Router Advertisement** and **Router Solicitation** functionalities supported by IPv6 routers.
+
+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 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.
-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.
+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.
+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
+
+- ``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.
+
+- ``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**.
+
+For example, in following configuration, Prefix will include only
+**2001:0558:FF10:04C9::2:1ff/120**.
.. code-block:: json
@@ -192,8 +242,12 @@
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.
+
+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
@@ -208,23 +262,42 @@
}
.. note::
- When global prefix is configured, RA app will ignore any prefixes configured on switch interfaces.
+ 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).
+
+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.
+Furthermore, note that the same VLAN can be configured on multiple ToRs - e.g.
+vlan 20 in the figure above.
-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.
+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