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/aaa.rst b/configuration/aaa.rst
index a2da53d..8d839f2 100644
--- a/configuration/aaa.rst
+++ b/configuration/aaa.rst
@@ -3,8 +3,9 @@
Introduction
------------
-In this section, we will explain how to use Trellis with AAA service, which can be used to authenticate a client host.
-We will explain how this works with a simple **single switch** topology.
+In this section, we will explain how to use Trellis with AAA service, which can
+be used to authenticate a client host. We will explain how this works with a
+simple **single switch** topology.
.. image:: ../images/config-aaa.png
@@ -13,8 +14,9 @@
Activate AAA app
^^^^^^^^^^^^^^^^
-We need to install and activate AAA app separately since it is located in a separate (CORD) repository.
-There are multiple methods to install and activate a pre-compiled app. Let's use CLI now.
+We need to install and activate AAA app separately since it is located in a
+separate (CORD) repository. There are multiple methods to install and activate
+a pre-compiled app. Let's use CLI now.
.. code-block::console
@@ -23,10 +25,10 @@
Provide network configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-We need to provide AAA configuration in the apps section of network configuration.
+We need to provide AAA configuration in the apps section of network
+configuration.
.. code-block:: json
- :linenos:
{
"apps": {
@@ -42,8 +44,12 @@
- ``radiusIp``: The IP address of the Radius server
-- ``radiusServerPort``: The UDP port of the Radius server. (Optional -- ONOS will use port 1812 by default).
-- ``radiusSecret``: The Radius secret. This needs to be consistent with the Radius server configuration
+
+- ``radiusServerPort``: The UDP port of the Radius server. (Optional -- ONOS
+ will use port 1812 by default).
+
+- ``radiusSecret``: The Radius secret. This needs to be consistent with the
+ Radius server configuration
Then push the JSON to ONOS:
@@ -57,10 +63,10 @@
Install FreeRadius
^^^^^^^^^^^^^^^^^^
-Technically all Radius server should work.
-However, the way to configure them are probably different case to case.
-Here we use FreeRadius on Ubuntu as an example.
-To install the Radius server, simply run:
+
+Technically, any Radius server should work. However, the way to configure them
+are probably different case to case. Here we use FreeRadius on Ubuntu as an
+example. To install the Radius server, simply run:
.. code-block:: console
@@ -71,9 +77,11 @@
Add a user
""""""""""
-We usually connect Radius server to a database where we store the user information.
-In this section, we statically configure a user to simplify the setup.
-To add a user ``admin`` with password ``cord_test``, edit ``/etc/freeradius/users`` and add following lines:
+
+We usually connect Radius server to a database where we store the user
+information. In this section, we statically configure a user to simplify the
+setup. To add a user ``admin`` with password ``cord_test``, edit
+``/etc/freeradius/users`` and add following lines:
.. code-block:: text
@@ -109,14 +117,16 @@
+ private_key_password = onos_test
.. note::
- The key and certificates required by TLS will locate under ``/etc/freeradius/certs`` by default.
- There will be three symbolic links link to ``ca.pem``, ``server.key``, ``server.pem``.
- We only need to change the symbolic links after we generates the keys and certificates.
+ The key and certificates required by TLS will locate under
+ ``/etc/freeradius/certs`` by default. There will be three symbolic links
+ link to ``ca.pem``, ``server.key``, ``server.pem``. We only need to change
+ the symbolic links after we generates the keys and certificates.
Therefore, we don't need to change the path in ``/etc/freeradius/eap.conf``
.. note::
- Both server certificate and client certificate need to be signed by the same CA certificate.
- Also note that each key we generate below needs a unique Common Name.
+ Both server certificate and client certificate need to be signed by the
+ same CA certificate. Also note that each key we generate below needs a
+ unique Common Name.
Generate CA certificate (ca.pem) and private key (privkey.pem)
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -146,14 +156,17 @@
Deploy keys and certificates
""""""""""""""""""""""""""""
-On the server side, please link **/etc/freeradius/{ca.pem, server.key, server.pem}** to the files we just generated.
-Also copy **ca.pem, client.key, client.pem** to the client side through a secured channel.
-They will later be used when testing the Radius authentication.
+On the server side, please link **/etc/freeradius/{ca.pem, server.key,
+server.pem}** to the files we just generated. Also copy **ca.pem, client.key,
+client.pem** to the client side through a secured channel. They will later be
+used when testing the Radius authentication.
Testing
-------
-We can use the ``wpa_supplicant`` as the test client. In case ``wpa_supplicant`` has not been installed, you can run ``sudo apt-get install wpasupplicant``
+We can use the ``wpa_supplicant`` as the test client. In case
+``wpa_supplicant`` has not been installed, you can run ``sudo apt-get install
+wpasupplicant``
Compose wpa_supplicant.conf
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -178,8 +191,10 @@
Run the test client
^^^^^^^^^^^^^^^^^^^
+
.. tip::
- If you are using a Linux VM behind a bridge to send out this authentication message, make sure the Linux kernel of your host machine is 3.2 or above.
+ If you are using a Linux VM behind a bridge to send out this authentication
+ message, make sure the Linux kernel of your host machine is 3.2 or above.
Otherwise the EAPOL messages won't go through the bridge.
.. code-block:: console