[VOL-2875] Documentation update
- Updated the main landing page and overview documentation
- Added the lab setup (copied from CORD docs)
- Use forked sphinx-multiversion to publish docs, which allows versions
to be listed at bottom of sidebar
- Updated logo and favicon, fixed CSS to make logo legible
- Use VERSION file to set the version in the sidebar
- Add more words to dictionary
- removed reload functionality that is nonworking in Sphinx 2.x
- Fixed lint/linkcheck issues
Change-Id: I032e67d76393778fc697944a6d5df9c8cdacbbc4
diff --git a/overview/lab_setup.rst b/overview/lab_setup.rst
new file mode 100644
index 0000000..5ec8054
--- /dev/null
+++ b/overview/lab_setup.rst
@@ -0,0 +1,195 @@
+.. _lab_setup:
+
+Hardware Setup of a VOLTHA Test Pod
+===================================
+
+Overview
+--------
+
+In a testing setup rather than using a real RG or BNG emulated ones are
+deployed on a Linux development server:
+
+- The ``RG`` can be emulated by an ``lxc`` container (from now on ``client``)
+- The ``BNG`` can be emulated by a Linux server
+- The ``AggSwitch`` is optional in a VOLTHA deployment.
+
+.. figure:: ../_static/voltha_lab_setup.png
+ :alt: VOLTHA Lab Setup
+
+ VOLTHA Lab Setup
+
+*The image above represents the data plane connections in a LAB setup.
+It does not include the kubernetes cluster for simplicity.*
+
+What you’ll need to emulate E2E traffic is:
+
+- 1 x86 server with Ubuntu 16.04 and at least the following interfaces:
+
+ - 1 1G Ethernet port
+ - 1 10G Ethernet port (this can be a second 1G interface as long as you have a media converter)
+
+Setting up a client
+-------------------
+
+The first thing you need to do is to install ``lxd`` on your server. To do that
+you can follow `this guide
+<http://tutorials.ubuntu.com/tutorial/tutorial-setting-up-lxd-1604>`_
+
+Once ``lxd`` is successfully installed you need to initialize it with:
+
+.. code:: bash
+
+ lxd init
+
+we recommend to use all the provided default values.
+
+Once ``lxd`` is initialized you can create a container and assign a physical
+Ethernet interface to the container:
+
+.. code:: bash
+
+ lxc launch ubuntu:16.04 <name>
+ lxc config device add <name> eth1 nic name=eth1 parent=<physical-intf> nictype=physical
+
+Where:
+
+- ``name`` is the desired container name. The convention used to identify which
+ RG container is connected to an ONU is to use the ONU serial number as the
+ lxc container name.
+
+- ``physical-intf`` is the name of the interface on the server where the ONU
+ is physically connected
+
+Once the container is created you can check it's state with with ``lxc list``:
+
+.. code:: bash
+
+ +---------------+---------+--------------------+------+------------+-----------+
+ | NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
+ +---------------+---------+--------------------+------+------------+-----------+
+ | voltha-client | RUNNING | 10.63.3.144 (eth0) | | PERSISTENT | 0 |
+ +---------------+---------+--------------------+------+------------+-----------+
+
+Please make sure the container has an assigned IP or we it won’t be able
+to login and install the ``wpasupplicant`` tool inside the RG.
+
+Once the container is running you need to enter it for configuration. To access
+the container run: ``lxc exec <name> /bin/bash``
+
+Once inside:
+
+.. code:: bash
+
+ # activate the interface
+ ip link set eth1 up
+ # install the wpasupplicant tool
+ apt update
+ apt install wpasupplicant
+
+..
+
+ NOTE: ``wpasupplicant`` is a Linux tool to perform 802.1X authentication.
+ `wpasupplicant documentation can be found here
+ <https://help.ubuntu.com/community/WifiDocs/WPAHowTo>`_.
+
+Create a configuration file for ``wpasupplicant`` in
+``/etc/wpa_supplicant/wpa_supplicant.conf`` with the content:
+
+.. code:: text
+
+ ctrl_interface=/var/run/wpa_supplicant
+ eapol_version=1
+ ap_scan=0
+ fast_reauth=1
+ network={
+ key_mgmt=WPA-EAP
+ eap=MD5
+ identity="user"
+ password="password"
+ ca_cert="/etc/cert/cacert.pem"
+ client_cert="/etc/cert/client.pem"
+ private_key="/etc/cert/client.key"
+ private_key_passwd="whatever"
+ eapol_flags=3
+ }
+
+..
+
+ NOTE: The configuration in this file is not really important if you are
+ using the ``freeradius`` server provided as part of the VOLTHA helm charts.
+ Do not worry if the certificates do not exist, they won’t affect
+ authentication as that is password based.
+
+At this point you’ll be able kickoff the authentication process (by
+sending ``EAPOL`` packets into the system) with the command:
+
+.. code:: bash
+
+ wpa_supplicant -i eth1 -Dwired -c /etc/wpa_supplicant/wpa_supplicant.conf
+
+If everything has been set up correctly, you should see output similar to this
+in the VOLTHA logs:
+
+.. code:: bash
+
+ cord@node1:~$ kubectl logs -f -n voltha vcore-0 | grep -E "packet_indication|packet-in" | grep 888e
+ 20180912T003237.453 DEBUG MainThread adapter_agent.send_packet_in {adapter_name: openolt, logical_port_no: 16, logical_device_id: 000100000a5a0097, packet: 0180c200000390e2ba82fa8281000ffb888e01000009020100090175736572000000000000000000000000000000000000000000000000000000000000000000, event: send-packet-in, instance_id: compose_voltha_1_1536712228, vcore_id: 0001}
+
+Setting up an emulated BNG on Linux
+-----------------------------------
+
+The emulated BNG needs to perform only two operations: ``DHCP`` and
+``NAT``.
+
+To setup a NAT router on an Ubuntu 16.04 server you can look at this
+tutorial:
+https://www.nairabytes.net/81-linux/418-how-to-set-up-a-nat-router-on-ubuntu-server-16-04
+
+To install a DHCP server you can follow this tutorial:
+http://nairabytes.net/81-linux/415-how-to-install-a-dhcp-server-in-ubuntu-server-16-04
+
+Once the ``DHCP`` server is installed, you need to configure it.
+
+Create Q-in-Q interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the interface that connects to the Agg Switch (upstream) you are
+going to receive double tagged traffic, so you’ll need to create
+interfaces to received it.
+
+Supposing that your subscriber is using ``s_tag=111``, ``c_tag=222`` and
+the upstream interface name is ``eth2`` you can use this commands to
+create it:
+
+.. code:: bash
+
+ ip link set eth2 up
+ ip link add link eth2 name eth2.111 type vlan id 111
+ ip link set eth2.111 up
+ ip link add link eth2.111 name eth2.111.222 type vlan id 222
+ ip link set eth2.111.222 up
+ ip addr add 10.11.2.254/24 dev eth2.111.222
+
+Then you’ll need to tell the ``dhcp`` server to listen on that
+interface, you can do that by editing the file
+``/etc/default/isc-dhcp-server`` so that it looks like:
+
+.. code:: bash
+
+ INTERFACES="eth2.111.222"
+
+..
+
+ NOTE that you can list multiple interfaces, separated by spaces, in
+ case you have multiple subscribers in your setup
+
+In the ``/etc/dhcp/dhcpd.conf`` config file, configure the IP address
+range to assign to the double tagged interface:
+
+.. code:: text
+
+ subnet 10.11.2.0 netmask 255.255.255.0 {
+ range 10.11.2.1 10.11.2.100;
+ option routers 10.11.2.254;
+ option domain-name-servers 8.8.8.8;
+ }