Renamed and moved a few things
address assignment -> dhcp relay
community -> resource
Change-Id: I807a896d8a8f610eb8af0063ba36ba0f0d55c070
diff --git a/configuration/aaa.rst b/configuration/aaa.rst
index 9af2cfd..56846e2 100644
--- a/configuration/aaa.rst
+++ b/configuration/aaa.rst
@@ -1,2 +1,207 @@
AAA
===
+
+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.
+
+.. image:: ../images/config-aaa.png
+
+
+Configure ONOS
+--------------
+
+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.
+
+.. code-block::console
+
+ $ onos-app localhost install! aaa-1.1-SNAPSHOT.oar
+
+
+Provide network configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+We need to provide AAA configuration in the apps section of network configuration.
+
+.. code-block:: json
+ :linenos:
+
+ {
+ "apps": {
+ "org.opencord.aaa" : {
+ "AAA" : {
+ "radiusIp": "10.128.0.231",
+ "radiusServerPort": "1812",
+ "radiusSecret": "howdoyouturnthison"
+ }
+ }
+ }
+ }
+
+
+- ``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
+
+Then push the JSON to ONOS:
+
+.. code-block:: console
+
+ $ onos-netcfg $OC1 aaa-config.json
+
+
+Configure Radius server
+-----------------------
+
+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:
+
+.. code-block:: console
+
+ sudo apt-get install freeradius
+
+Configure FreeRadius
+^^^^^^^^^^^^^^^^^^^^
+
+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:
+
+.. code-block:: text
+
+ admin Cleartext-Password := "cord_test"
+ Reply-Message = "Hello, %{User-Name}"
+
+Allow external clients
+""""""""""""""""""""""
+By default the Radius server only accepts requests from ``localhost``.
+To allow external clients, we need to modify ``/etc/freeradius/clients.conf``
+We also need to change the secret.
+
+.. code-block:: diff
+
+ -client localhost {
+ +client 0.0.0.0/0 {
+
+ - secret = testing123
+ + secret = howdoyouturnthison
+
+Use TLS
+"""""""
+By default, FreeRadius use MD5 challenge response to authenticate clients.
+To use TLS, we need to modify ``/etc/freeradius/eap.conf``
+We also need to change the private key password.
+
+.. code-block:: diff
+
+ - default_eap_type = md5
+ + default_eap_type = tls
+
+ - private_key_password = whatever
+ + 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.
+ 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.
+
+Generate CA certificate (ca.pem) and private key (privkey.pem)
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: console
+
+ openssl req -out ca.pem -new -x509
+
+Generate and sign server certificate (server.pem) and private key (server.key)
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: console
+
+ openssl genrsa -out server.key 1024
+ openssl req -key server.key -new -out server.req
+ openssl x509 -req -in server.req -CA ca.pem -CAkey privkey.pem -CAserial file.srl -out server.pem
+
+Generate and sign client certificate (client.pem) and private key (client.key)
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: console
+
+ openssl genrsa -out client.key 1024
+ openssl req -key client.key -new -out client.req
+ openssl x509 -req -in client.req -CA ca.pem -CAkey privkey.pem -CAserial file.srl -out client.pem
+
+
+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.
+
+
+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``
+
+Compose wpa_supplicant.conf
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: text
+
+ ctrl_interface=/var/run/wpa_supplicant
+ eapol_version=1
+ ap_scan=0
+ fast_reauth=0
+ network={
+ key_mgmt=WPA-EAP
+ eap=TLS
+ identity="admin"
+ password="cord_test"
+ ca_cert="ca.pem"
+ client_cert="client.pem"
+ private_key="client.key"
+ private_key_passwd="onos_test"
+ eapol_flags=3
+ }
+
+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.
+ Otherwise the EAPOL messages won't go through the bridge.
+
+.. code-block:: console
+
+ $ sudo wpa_supplicant -Dwired -ieth1 -cwpa_supplicant.conf
+
+You should see the following message if authentication succeed:
+
+.. code-block:: console
+
+ Successfully initialized wpa_supplicant
+ eth1: Associated with 01:80:c2:00:00:03
+ eth1: CTRL-EVENT-EAP-STARTED EAP authentication started
+ eth1: CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=13
+ eth1: CTRL-EVENT-EAP-METHOD EAP vendor 0 method 13 (TLS) selected
+ eth1: CTRL-EVENT-EAP-PEER-CERT depth=1 subject='/C=US/ST=CA/L=Menlo Park/O=ON.Lab/CN=ca.cord.lab/emailAddress=xxx@xxx.xxx'
+ eth1: CTRL-EVENT-EAP-PEER-CERT depth=0 subject='/C=US/ST=CA/L=Menlo Park/O=ON.Lab/CN=server.cord.lab/emailAddress=xxx@xxx.xxx'
+ eth1: CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
+
+Reference
+---------
+- https://tools.ietf.org/html/rfc3580
+- https://www.vocal.com/secure-communication/eapol-extensible-authentication-protocol-over-lan/
+- https://dst.lbl.gov/~boverhof/openssl_certs.html
diff --git a/configuration/bridging-unicast.rst b/configuration/bridging-unicast.rst
index ede859d..1eb54a9 100644
--- a/configuration/bridging-unicast.rst
+++ b/configuration/bridging-unicast.rst
@@ -138,7 +138,7 @@
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/vlan-config.png
+.. 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. '
@@ -150,4 +150,4 @@
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/vlan-config-invalid.png
+.. image:: ../images/config-vlan-invalid.png
diff --git a/configuration/address-assignment.rst b/configuration/dhcp-relay.rst
similarity index 83%
rename from configuration/address-assignment.rst
rename to configuration/dhcp-relay.rst
index 8568152..a53c208 100644
--- a/configuration/address-assignment.rst
+++ b/configuration/dhcp-relay.rst
@@ -1,15 +1,20 @@
-Address Assignment
-==================
+DHCP Relay
+==========
.. tip::
We strongly recommend you to setup DHCP relay and configure the hosts to **obtain address via DHCP**.
-
-DHCP Relay
-----------
+ See `Alternative: Configure static IP`_ if you want to statically configure IP address on each host.
-Static IP
----------
+Direct vs. Indirect hosts
+-------------------------
+
+Configure DHCP Relay
+--------------------
+
+
+Alternative: Configure static IP
+--------------------------------
Although we strongly recommend to use `DHCP Relay`_ for IP assignment,
it is also possible to statically configure the IP address and route on the host.
diff --git a/configuration/images/pw-rest.png b/configuration/images/pw-rest.png
deleted file mode 100644
index c586dab..0000000
--- a/configuration/images/pw-rest.png
+++ /dev/null
Binary files differ
diff --git a/configuration/images/vlan-config-invalid.png b/configuration/images/vlan-config-invalid.png
deleted file mode 100644
index c0f8196..0000000
--- a/configuration/images/vlan-config-invalid.png
+++ /dev/null
Binary files differ
diff --git a/configuration/images/vlan-config.png b/configuration/images/vlan-config.png
deleted file mode 100644
index dd93425..0000000
--- a/configuration/images/vlan-config.png
+++ /dev/null
Binary files differ
diff --git a/configuration/pseudowire.rst b/configuration/pseudowire.rst
index 16998db..60d1ca0 100644
--- a/configuration/pseudowire.rst
+++ b/configuration/pseudowire.rst
@@ -16,7 +16,7 @@
You can find the REST API documentation at ``http://${ONOS-IP}:8181/onos/v1/docs``.
Please click the drop down list and select Segment Routing Server.
-.. image:: images/pw-rest.png
+.. image:: ../images/config-pw-rest.png
:width: 700px
We configure and implement PWs through the dedicated REST API.
