<commit_before>###########
Build a Lab
###########

There are many different options for building a nmeta lab network. The
choice is likely to come down to what resources you have and the use cases
you want to test.

Virtual labs are easy to set up and don't require specialised hardware,
but aren't useful for testing devices in the real world.

Physical labs are harder to construct and require hardware, but can be
used to connect real-world devices.

UNDER CONSTRUCTION

************
Virtual Labs
************

VirtualBox
==========

TBD

Mininet
=======

Get in touch if you want to contribute instructions on building a lab with
Mininet.


*************
Physical Labs
*************

OpenWRT with Open vSwitch
=========================

UNDER CONSTRUCTION

This lab is based on a TP-Link TL-WR1043ND Hardware Version 2.1 home router
that is re-flashed to run OpenWRT with Open vSwitch running OpenFlow (yes,
that's three different pieces of software that start with the word 'Open'...)

Be warned that reflashing a router is likely to void it's warrantee, and may
result in the router becoming 'bricked', whereby it is unrecoverable. Continue
at your own risk...

Compile OpenWRT with Open vSwitch Image
---------------------------------------

Start by compiling the router firmware on an Ubuntu 16.04.2 server or desktop
(can be virtual) with at least 30GB of disk space:

Clone OpenWRT
^^^^^^^^^^^^^

Cloned OpenWRT (note: GitHub, not direct from OpenWRT site):

.. code-block:: text

  git clone https://github.com/openwrt/openwrt.git 

Install Dependancies
^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

  sudo apt-get update
  sudo apt-get install git-core build-essential libssl-dev libncurses5-dev unzip gawk zlib1g-dev
  sudo apt-get install subversion mercurial
  sudo apt-get install gcc-multilib flex gettext

Update Feeds
^^^^^^^^^^^^

.. code-block:: text

  cd openwrt
  ./scripts/feeds update -a
  ./scripts/feeds install -a

Make MenuConfig
^^^^^^^^^^^^^^^

.. code-block:: text

  make menuconfig

Change Target Profile to suit hardware (select *TP-LINK TL-WR1043N/ND* for
TP-Link TL-WR1043ND Hardware Version 2.1):

.. image:: images/OpenWRT_build_1.png

Then select Kernel Modules -> Network Support -> kmod-tun:

.. image:: images/OpenWRT_build_2.png

Exit out back to main screen, then select *Network ->  Open vSwitch* and
select:

.. image:: images/OpenWRT_build_3.png

Save on exit:

.. image:: images/OpenWRT_build_4.png

This one takes a while:

.. code-block:: text

  make kernel_menuconfig

When finished brings up another menu. Navigate to 
*Networking support -> Networking options* and select
*Hierarchical Token Bucket (HTB)*:

.. image:: images/OpenWRT_build_5.png


TBD


Links
-----

Instructions were based on these tutorials:

`Building and Configuring Open vSwitch on OpenWrt for Cloud Networking by<NAME>. <http://www.zymr.com/building-and-configuring-open-vswitch-on-openwrt-for-cloud-networking/>`_
 <commit_msg>more lab doc updates<commit_after>###########
Build a Lab
###########

There are many different options for building a nmeta lab network. The
choice is likely to come down to what resources you have and the use cases
you want to test.

Virtual labs are easy to set up and don't require specialised hardware,
but aren't useful for testing devices in the real world.

Physical labs are harder to construct and require hardware, but can be
used to connect real-world devices.

UNDER CONSTRUCTION

************
Virtual Labs
************

VirtualBox
==========

TBD

Mininet
=======

Get in touch if you want to contribute instructions on building a lab with
Mininet.


*************
Physical Labs
*************

OpenWRT with Open vSwitch
=========================

UNDER CONSTRUCTION

This lab is based on a TP-Link TL-WR1043ND Hardware Version 2.1 home router
that is re-flashed to run OpenWRT with Open vSwitch running OpenFlow (yes,
that's three different pieces of software that start with the word 'Open'...)

Be warned that reflashing a router is likely to void it's warrantee, and may
result in the router becoming 'bricked', whereby it is unrecoverable. Continue
**at your own risk**...

Convert Router to OpenWRT
-------------------------

Start by converting the TP-Link TL-WR1043ND to running OpenWRT as per the
instructions from the OpenWRT website at:

`<https://wiki.openwrt.org/toh/tp-link/tl-wr1043nd>`_

When router is successfully running OpenWRT, proceed to the next step:

Compile OpenWRT with Open vSwitch Image
---------------------------------------

Start by compiling the router firmware on an Ubuntu 16.04.2 server or desktop
(can be virtual) with at least 30GB of disk space:

Clone OpenWRT
^^^^^^^^^^^^^

Cloned OpenWRT (note: GitHub, not direct from OpenWRT site):

.. code-block:: text

  git clone https://github.com/openwrt/openwrt.git 

Install Dependancies
^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

  sudo apt-get update
  sudo apt-get install git-core build-essential libssl-dev libncurses5-dev unzip gawk zlib1g-dev
  sudo apt-get install subversion mercurial
  sudo apt-get install gcc-multilib flex gettext

Update Feeds
^^^^^^^^^^^^

.. code-block:: text

  cd openwrt
  ./scripts/feeds update -a
  ./scripts/feeds install -a

Make MenuConfig
^^^^^^^^^^^^^^^

.. code-block:: text

  make menuconfig

Change Target Profile to suit hardware (select *TP-LINK TL-WR1043N/ND* for
TP-Link TL-WR1043ND Hardware Version 2.1):

.. image:: images/OpenWRT_build_1.png

Then select Kernel Modules -> Network Support -> kmod-tun:

.. image:: images/OpenWRT_build_2.png

Exit out back to main screen, then select *Network ->  Open vSwitch* and
select:

.. image:: images/OpenWRT_build_3.png

Save on exit:

.. image:: images/OpenWRT_build_4.png

This one takes a while:

.. code-block:: text

  make kernel_menuconfig

When finished brings up another menu. Navigate to 
*Networking support -> Networking options* and select
*Hierarchical Token Bucket (HTB)*:

.. image:: images/OpenWRT_build_5.png

Run Make
^^^^^^^^

This may take a couple of hours...

.. code-block:: text

  make

Copy Image
^^^^^^^^^^
Navigate to the directory where the output files are:

.. code-block:: text

  cd bin/ar71xx

There should be multiple files in the directory, including this file:

.. code-block:: text

  openwrt-ar71xx-generic-tl-wr1043nd-v2-squashfs-factory.bin
  openwrt-ar71xx-generic-tl-wr1043nd-v2-squashfs-sysupgrade.bin

Use SCP to copy the appropriate file to the router:

.. code-block:: text

  scp ./openwrt-ar71xx-generic-tl-wr1043nd-v2-squashfs-sysupgrade.bin USERNAME@192.168.1.1:tmp/

Upgrade
^^^^^^^

Note: consider backing up config etc first...

On the TPLink:

.. code-block:: text

  sysupgrade -v /tmp/openwrt-ar71xx-generic-tl-wr1043nd-v2-squashfs-sysupgrade.bin

TBD


Links
-----

Instructions were based on these tutorials:

`Building and Configuring Open vSwitch on OpenWrt for Cloud Networking by<NAME>. <http://www.zymr.com/building-and-configuring-open-vswitch-on-openwrt-for-cloud-networking/>`_
 
{'fraction_non_alphanumeric': 0.13687669667095298, 'fraction_numerical': 0.01514502071724532, 'mean_word_length': 3.7748976807639836, 'pattern_counts': {'":': 0, '<': 8, '<?xml version=': 0, '>': 16, 'https://': 3, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4538192', 'n_tokens_mistral': 2263, 'n_tokens_neox': 2121, 'n_words': 822}