<commit_before>####################################
Welcome to ESCAPEv2's documentation!
####################################

.. Welcome! This is the API documentation for **ESCAPEv2**.

Overview
========

On the one hand, ESCAPE (Extensible Service ChAin Prototyping
Environment) is a general prototyping framework which supports the
development of several parts of the service chaining architecture
including VNF implementation, traffic steering, virtual network
embedding, etc.  On the other hand, ESCAPE is a proof of concept
prototype implementing a novel SFC (Service Function Chaining)
architecture proposed by `EU FP7 UNIFY project <https://www.fp7-unify.eu/>`__.
It is a realization of the UNIFY service programming and orchestration framework
which enables the joint programming and virtualization of cloud and networking
resources.

.. tip::

   For more information on the concept, motivation and demo use-cases, we
   suggest the following papers.

   **UNIFY Architecture:**

   * <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, and <NAME>, *UNIFYing Cloud and Carrier
     Network Resources: An Architectural View*, in Proc. IEEE Global
     Telecommunications Conference (GLOBECOM), 2015.

   **ESCAPE as a multi-domain orchestrator:**

   * <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>,
     *Multi-domain service orchestration over networks and clouds: a
     unified approach*, In Proceedings of ACM SIGCOMM (Demo), August
     17-21, 2015, London, United Kingdom.  `Download the paper
     <http://conferences.sigcomm.org/sigcomm/2015/pdf/papers/p377.pdf>`__
   * `Demo video <https://www.youtube.com/watch?v=T3Fna5v-hFw>`__
   * `Demo video as a presentation with manual control
     <http://prezi.com/f-ms1rwxxdwa/?utm_campaign=share&utm_medium=copy&rc=ex0share>`__

   **Previous version of ESCAPE:**

   * <NAME>, <NAME>, <NAME>, <NAME>,
     <NAME>, <NAME>, <NAME>, *ESCAPE: Extensible
     Service ChAin Prototyping Environment using Mininet, Click, NETCONF
     and POX*, In Proceedings of ACM SIGCOMM (Demo), August 17-22, 2014,
     Chicago, IL, USA.  `Download the paper
     <http://dl.acm.org/authorize?N71297>`__
   * The source code of the previous version of ESCAPE is available at
     our `github page <https://github.com/nemethf/escape>`__.

For further information contact <EMAIL>

Installation
============

Because ESCAPEv2 relies on POX and written in Python there is no need for
explicit compiling or installation. The only requirement need to be pre-installed
is a Python interpreter.

The recommended Python version, in which the development and mostly the testing
are performed, is the standard CPython **2.7.9** but the 2.7.6 (pre-build
Mininet VM) and 2.7.10 versions are also tested and supported.

.. warning::

  Only the standard CPython interpreter is supported!

If you want to use a different and separated Python version check the Virtual
Environment section below.

The preferred way
-----------------

1. Download one of pre-build Mininet image which has already had the necessary
tools (Mininet scripts and Open vSwitch).

  https://github.com/mininet/mininet/wiki/Mininet-VM-Images

  The images are in an open virtual format (``.ovf``) which can be imported by
  most of the virtualization managers.

  Username/password: **mininet/mininet**

  Our implementation relies on Mininet 2.1.0, but ESCAPEv2 has been tested on
  the newest image too (Mininet 2.2.1 on Ubuntu 14.04 - 64 bit) and no problem
  has occurred yet!

2. Create the ``.ssh`` folder in the home directory and copy your private RSA key
which you gave on the *fp7-unify.eu GitLab* site into the VM with the name
``id_rsa``. If you use the Mininet image then the following commands can be used
in the VM to copy your RSA key from your host:

  .. code-block:: bash

    $ cd
    $ mkdir .ssh
    $ scp <your_user>@<host_ip>:~/.ssh/<your_ssh_key> ~/.ssh/id_rsa
    $ sudo chmod 700 .ssh && sudo chmod 600 .ssh/id_rsa

3. Clone the shared escape repository in a folder named:
*escape*.

  .. code-block:: bash

    $ git clone <EMAIL>:Balazs.Sonkoly/escape-shared.git escape

4. Install the necessary dependencies with the ``install_dep.sh`` script (system
and Python packages, OpenYuma with VNFStarter module):

  .. code-block:: bash

    $ cd escape
    $ ./install_dep.sh


  In a high level the script above does the following things:
    * Install the necessary system and Python packages
    * Compile and install the `OpenYuma <https://github.com/OpenClovis/OpenYuma>`__
      tools with our `VNF_starter` module
    * Compile and install `Click <http://read.cs.ucla.edu/click/click>`__ modular
      router and The Click GUI: `Clicky <http://read.cs.ucla.edu/click/clicky>`__
    * Install `neo4j <http://neo4j.com/>`__ graph database for NFIB

5. Run ESCAPEv2 with one of the commands listed in a later section. To see the
available arguments of the top starting script check the help menu:

  .. code-block:: bash

    $ ./escape.py --help

.. important::

    If you want to initiate more then 15 node (switch and Execution Environment
    too) in the Mininet-based Infrastructure layer zou should recompile the
    OpenSSH server from source to increase the number of possible listening ports
    up to 256. In this case you can use the following commands:

     .. code-block:: bash

         $ sudo -i
         $ cd /usr/src
         $ apt-get update && apt-get source openssh-server
         $ cd openssh-*
         $ sed -in 's/\(\#define MAX_LISTEN_SOCKS\).*/\1 256/' sshd.c
         $ sed -in 's/\(\#define MAX_PORTS\).*/\1 256/' servconf.h
         $ ./configure --prefix=/usr --sysconfdir=/etc/ssh --with-default-path=$PATH
         $ make
         $ make install
         $ service ssh restart

The hard way
------------

Obviously you can install ESCAPEv2 on your host or on an empty VM too. For that
you need to install the requirements manually.

To install the Python dependencies and other system packages you can use the
dependency installation script mentioned above or you can do it manually.

**Dependencies**

If you don't want to install the Python dependencies globally you can follow the
hard way and setup a virtual environment. Otherwise just run the following
command(s):

Required system and Python packages:

.. code-block:: bash<commit_msg>Fix sed param to rewrite port numbers correctly<commit_after>####################################
Welcome to ESCAPEv2's documentation!
####################################

.. Welcome! This is the API documentation for **ESCAPEv2**.

Overview
========

On the one hand, ESCAPE (Extensible Service ChAin Prototyping
Environment) is a general prototyping framework which supports the
development of several parts of the service chaining architecture
including VNF implementation, traffic steering, virtual network
embedding, etc.  On the other hand, ESCAPE is a proof of concept
prototype implementing a novel SFC (Service Function Chaining)
architecture proposed by `EU FP7 UNIFY project <https://www.fp7-unify.eu/>`__.
It is a realization of the UNIFY service programming and orchestration framework
which enables the joint programming and virtualization of cloud and networking
resources.

.. tip::

   For more information on the concept, motivation and demo use-cases, we
   suggest the following papers.

   **UNIFY Architecture:**

   * <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, and <NAME>, *UNIFYing Cloud and Carrier
     Network Resources: An Architectural View*, in Proc. IEEE Global
     Telecommunications Conference (GLOBECOM), 2015.

   **ESCAPE as a multi-domain orchestrator:**

   * <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>,
     *Multi-domain service orchestration over networks and clouds: a
     unified approach*, In Proceedings of ACM SIGCOMM (Demo), August
     17-21, 2015, London, United Kingdom.  `Download the paper
     <http://conferences.sigcomm.org/sigcomm/2015/pdf/papers/p377.pdf>`__
   * `Demo video <https://www.youtube.com/watch?v=T3Fna5v-hFw>`__
   * `Demo video as a presentation with manual control
     <http://prezi.com/f-ms1rwxxdwa/?utm_campaign=share&utm_medium=copy&rc=ex0share>`__

   **Previous version of ESCAPE:**

   * <NAME>, <NAME>, <NAME>, <NAME>,
     <NAME>, <NAME>, <NAME>, *ESCAPE: Extensible
     Service ChAin Prototyping Environment using Mininet, Click, NETCONF
     and POX*, In Proceedings of ACM SIGCOMM (Demo), August 17-22, 2014,
     Chicago, IL, USA.  `Download the paper
     <http://dl.acm.org/authorize?N71297>`__
   * The source code of the previous version of ESCAPE is available at
     our `github page <https://github.com/nemethf/escape>`__.

For further information contact <EMAIL>

Installation
============

Because ESCAPEv2 relies on POX and written in Python there is no need for
explicit compiling or installation. The only requirement need to be pre-installed
is a Python interpreter.

The recommended Python version, in which the development and mostly the testing
are performed, is the standard CPython **2.7.9** but the 2.7.6 (pre-build
Mininet VM) and 2.7.10 versions are also tested and supported.

.. warning::

  Only the standard CPython interpreter is supported!

If you want to use a different and separated Python version check the Virtual
Environment section below.

The preferred way
-----------------

1. Download one of pre-build Mininet image which has already had the necessary
tools (Mininet scripts and Open vSwitch).

  https://github.com/mininet/mininet/wiki/Mininet-VM-Images

  The images are in an open virtual format (``.ovf``) which can be imported by
  most of the virtualization managers.

  Username/password: **mininet/mininet**

  Our implementation relies on Mininet 2.1.0, but ESCAPEv2 has been tested on
  the newest image too (Mininet 2.2.1 on Ubuntu 14.04 - 64 bit) and no problem
  has occurred yet!

2. Create the ``.ssh`` folder in the home directory and copy your private RSA key
which you gave on the *fp7-unify.eu GitLab* site into the VM with the name
``id_rsa``. If you use the Mininet image then the following commands can be used
in the VM to copy your RSA key from your host:

  .. code-block:: bash

    $ cd
    $ mkdir .ssh
    $ scp <your_user>@<host_ip>:~/.ssh/<your_ssh_key> ~/.ssh/id_rsa
    $ sudo chmod 700 .ssh && sudo chmod 600 .ssh/id_rsa

3. Clone the shared escape repository in a folder named:
*escape*.

  .. code-block:: bash

    $ git clone <EMAIL>:Balazs.Sonkoly/escape-shared.git escape

4. Install the necessary dependencies with the ``install_dep.sh`` script (system
and Python packages, OpenYuma with VNFStarter module):

  .. code-block:: bash

    $ cd escape
    $ ./install_dep.sh


  In a high level the script above does the following things:
    * Install the necessary system and Python packages
    * Compile and install the `OpenYuma <https://github.com/OpenClovis/OpenYuma>`__
      tools with our `VNF_starter` module
    * Compile and install `Click <http://read.cs.ucla.edu/click/click>`__ modular
      router and The Click GUI: `Clicky <http://read.cs.ucla.edu/click/clicky>`__
    * Install `neo4j <http://neo4j.com/>`__ graph database for NFIB

5. Run ESCAPEv2 with one of the commands listed in a later section. To see the
available arguments of the top starting script check the help menu:

  .. code-block:: bash

    $ ./escape.py --help

.. important::

    If you want to initiate more then 15 node (switch and Execution Environment
    too) in the Mininet-based Infrastructure layer zou should recompile the
    OpenSSH server from source to increase the number of possible listening ports
    up to 256. In this case you can use the following commands:

     .. code-block:: bash

         $ sudo -i
         $ cd /usr/src
         $ apt-get update && apt-get source openssh-server
         $ cd openssh-*
         $ sed -i 's/^\(#define\s*MAX_LISTEN_SOCKS\s*\).*/\1256/' sshd.c
         $ sed -i 's/^\(#define\s*MAX_PORTS\s*\).*/\1256/' servconf.h
         $ ./configure --prefix=/usr --sysconfdir=/etc/ssh --with-default-path=$PATH
         $ make
         $ make install
         $ service ssh restart

The hard way
------------

Obviously you can install ESCAPEv2 on your host or on an empty VM too. For that
you need to install the requirements manually.

To install the Python dependencies and other system packages you can use the
dependency installation script mentioned above or you can do it manually.

**Dependencies**

If you don't want to install the Python dependencies globally you can follow the
hard way and setup a virtual environment. Otherwise just run the following
command(s):

Required system and Python packages:

.. code-block:: bash
{'fraction_non_alphanumeric': 0.10669191919191919, 'fraction_numerical': 0.014678030303030304, 'mean_word_length': 3.4939716312056737, 'pattern_counts': {'":': 0, '<': 75, '<?xml version=': 0, '>': 75, 'https://': 10, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3685053', 'n_tokens_mistral': 3889, 'n_tokens_neox': 3505, 'n_words': 1544}