Added info for downloading Polycube release (#310)

* Added installation procedure in case of a release
* Improved docs

Documentation/README.md

@@ -21,6 +21,13 @@ pip install -r requirements.txt
 Documentation is created in the ReSTructured text format.
 A nice document listing important commands is the [Restructured Text (reST) and Sphinx CheatSheet](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html).
 
+Please note that you have mostly two ways to create a link to another location of the documentation:
+
+- use an explicit reference to the target location (e.g., ```:ref:`sec-updating-linux-kernel` ```), which must declare a 'label' (e.g., ```.. _sec-updating-linux-kernel:``` followed by an empty line);
+
+- use the ```:doc:`polycubectl CLI <polycubectl/polycubectl>` ``` primitive, which enables to refer to a specific file and allows to specify the text to be written in the link.
+
+- use the ```:scm_web:``` macro, which avoids to declare the entire path of the linked document when this refers to the github repository (e.g., ``` :scm_web:`Nat <src/services/pcn-nat/src/Nat_dp.c>` ```)
 
 ### Build it
 

Documentation/developers/dataplane.rst

@@ -5,28 +5,28 @@ Writing the eBPF datapath
 The Polycube architecture leverages the software abstraction provided by `BCC <https://github.com/iovisor/bcc/>`_, which is further extended in this project particular with respect to eBPF features that are useful for networking services.
 In order to get more information about how to use the maps in BCC please read the `BCC reference guide <https://github.com/iovisor/bcc/blob/master/docs/reference_guide.md>`_, additionally there is a list of the `available eBPF helpers <https://github.com/iovisor/bcc/blob/master/docs/kernel-versions.md>`_.
 
-Polycube architecture adds a wrapper around the user's code, this wrapper calls the `handle_rx` function with the following parameters:
+Polycube architecture adds a wrapper around the user's code, this wrapper calls the ``handle_rx`` function with the following parameters:
 
-1. **ctx**: Packet to be processed
-2. **md**: packet's metadata:
+- **ctx**: packet to be processed
+- **md**: packet metadata
+- **in_port**: integer that identifies the ingress port of the packet.
 
- - **in_port**: integer that identifies the ingress port of the packet.
+Polycube provides a set of functions to handle the packets, the return value of the ``handle_rx`` function should be the result of calling one of these functions.
 
-``polycube`` provides a set of functions to handle the packets, the return value of the `handle_rx` function should be the result of calling one of these functions.
+- **pcn_pkt_redirect(struct __sk_buff *skb, struct pkt_metadata *md, u16 port);**: sends the packet through an the ``ifc`` port. :scm_web:`Example: Helloworld service <src/services/pcn-helloworld/src/Helloworld_dp_ingress.c#L96>`.
 
-- **pcn_pkt_redirect(struct __sk_buff *skb, struct pkt_metadata *md, u16 port);**: sends the packet through an the ``ifc`` port. [Example](services/pcn-helloworld/src/Helloworld_dp.h#L86)
+- **pcn_pkt_drop(struct __sk_buff *skb, struct pkt_metadata *md);**: drops the packet. It is the same that just returning `RX_DROP`. :scm_web:`Example: Helloworld service <src/services/pcn-helloworld/src/Helloworld_dp_ingress.c#L80>`.
 
-- **pcn_pkt_drop(struct __sk_buff *skb, struct pkt_metadata *md);**: drops the packet. It is the same that just returning `RX_DROP`. [Example](services/pcn-helloworld/src/Helloworld_dp.h#L78)
-
-- **pcn_pkt_redirect_ns(struct __sk_buff *skb, struct pkt_metadata *md, u16 port)**: (it is only available for shadow services) sends the packet to the namespace as if it came from the port indicated as parameter
+- **pcn_pkt_redirect_ns(struct __sk_buff *skb, struct pkt_metadata *md, u16 port)**: (available only for *shadow* services) sends the packet to the namespace if it comes from the port indicated as parameter.
 
 Processing packets in the slowpath
 **********************************
 
 A copy of the packet can be sent to the controller to be processed by the slowpath using the following helpers:
 
-- **pcn_pkt_controller(struct __sk_buff *skb, struct pkt_metadata *md, u16 reason)**: sends a copy of the packet to the controller. Reason can be used to indicate why the packet is being sent to the custom code running in the control path. [Example](services/pcn-helloworld/src/Helloworld_dp.h#L82)
-
+- **pcn_pkt_controller(struct __sk_buff *skb, struct pkt_metadata *md, u16 reason)**: sends a copy of the packet to the controller. Reason can be used to indicate why the packet is being sent to the custom code running in the control path.
+:scm_web:`Example: Helloworld service <src/services/pcn-helloworld/src/Helloworld_dp_ingress.c#L79>`.
+
 - **pcn_pkt_controller_with_metadata(struct __sk_buff *skb, struct pkt_metadata *md, u16 reason, u32 metadata[3])**: sends a copy of the packet to the custom code running in the control path. In addition to the reason the user can also send some additional metadata.
 
 The packet will be processed by the ``packet_in`` method of the controller.
@@ -38,38 +38,29 @@ The L3 (IP) and L4 (TCP, UDP) checksums has to be updated when fields in the pac
 ``polycube`` provides a set of wrappers of the eBPF helpers to do it:
 
 - **pcn_csum_diff()**: wrapper of `BPF_FUNC_csum_diff <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=7d672345ed295b1356a5d9f7111da1d1d7d65867>`_
-
-    Note: For XDP cubes and kernels version prior to 4.16 this function supports only 4 bytes arguments.
+Note that in case of XDP cubes and kernels version prior to 4.16 this function supports only 4 bytes arguments.
 
 - **pcn_l3_csum_replace()**: wrapper of `BPF_FUNC_l3_csum_replace <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=91bc4822c3d61b9bb7ef66d3b77948a4f9177954>`_
 
 - **pcn_l4_csum_replace()**: wrapper of `BPF_FUNC_l4_csum_replace <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=91bc4822c3d61b9bb7ef66d3b77948a4f9177954>`_
 
-Services as :scm_web:`nat <src/services/pcn-nat/src/Nat_dp.c>` and :scm_web:`nat <src/services/pcn-loadbalancer-rp/src/Lbrp_dp.c>` show how to use these functions.
+Services as :scm_web:`NAT <src/services/pcn-nat/src/Nat_dp.c>` and :scm_web:`Load Balancer <src/services/pcn-loadbalancer-rp/src/Lbrp_dp.c>` show how to use these functions.
 
-Vlan Support
+VLAN Support
 ************
 
-The vlan handling in TC and XDP eBPF programs is a little bit different, so polycube includes a set of helpers to uniform this accross.
-
-- bool pcn_is_vlan_present(struct CTXTYPE* pkt)
-
-- int pcn_get_vlan_id(struct CTXTYPE* pkt, uint16_t* vlan_id, uint16_t* eth_proto);
-
-- uint8_t pcn_vlan_pop_tag(struct CTXTYPE* pkt);
-
-- uint8_t pcn_vlan_push_tag(struct CTXTYPE* pkt, u16 eth_proto, u32 vlan_id);
-
-
-Known limitations:
-******************
-- It is not possible to send a packet through multiple ports, then multicast, broadcast of any similar functionality has to be implemented in the control path.
+The VLAN handling in TC and XDP eBPF programs is a little bit different, so polycube includes a set of helpers to uniform this accross.
 
+- bool **pcn_is_vlan_present** (struct CTXTYPE* pkt)
+- int **pcn_get_vlan_id** (struct CTXTYPE* pkt, uint16_t* vlan_id, uint16_t* eth_proto);
+- uint8_t **pcn_vlan_pop_tag** (struct CTXTYPE* pkt);
+- uint8_t **pcn_vlan_push_tag** (struct CTXTYPE* pkt, u16 eth_proto, u32 vlan_id);
 
-TODO:
-*****
 
-- Document support for multiple eBPF programs
+Known limitations
+*****************
+- Since you cannot send a packet on multiple ports, multicast, broadcast or any similar functionality has to be implemented in the control path.
+- The support for multiple eBPF programs is not yet documented.
 
 
 Debugging the data plane

Documentation/installation.rst

@@ -1,5 +1,5 @@
-Installing Polycube from source files
-=====================================
+Installing Polycube from sources
+================================
 
 This installation guide includes instructions to install Polycube on ``Ubuntu >= 18.04``.
 However those should also work on other versions and distributions with a few changes.
@@ -8,21 +8,21 @@ Dependencies
 ------------
 
 Polycube requires following dependencies:
- - **Recent Linux kernel**: most Polycube services work with kernel **>= v4.15**; however, there are cases in which a newer kernel may be required, e.g., in case we want to execute the ``dynmon`` service with a custom code that requires more recent kernel primitives. In case you are unsure, please upgrade to **kernel v5.4**.
+ - **Recent Linux kernel**: most Polycube services work with kernel **>= v4.15**; however, there are cases in a newer kernel may be required. In case you are unsure, please upgrade to **kernel v5.4** (section :ref:`sec-updating-linux-kernel` ).
  - **pistache**: a library to build rest API servers
  - **libints**: a library for crafting packets (needed only for some services)
  - **Go language**: required to run ``polycubectl`` (polycube command line interface)
 
 Following sections will detail the installation process for the above components.
 
-.. _updating-linux-kernel:
+.. _sec-updating-linux-kernel:
 
-Updating Linux Kernel
--------------------------------
+Updating Linux kernel
+---------------------
 
-Most Polycube services require at least the **Linux kernel v4.15**. However, the ``dynmon`` service allow the dynamic injection of a custom data plane, which may exploit latest eBPF kernel features and hence require more up-to-date kernel versions. Therefore we suggest to upgrade the to the latest Linux kernel (https://kernel.ubuntu.com/~kernel-ppa/mainline/) in order to be on the safe side.
+Most Polycube services require at least the **Linux kernel v4.15**. However, the :doc:`Dynmon service <services/pcn-dynmon/dynmon>` allows the dynamic injection of a custom data plane, which may exploit latest eBPF kernel features and hence require more up-to-date kernel versions. Therefore we suggest to upgrade the to the latest Linux kernel in order to be on the safe side.
 
-The following examples show how to update kernel to version **4.15** and **5.4**. To check the kernel version you are running, please use ``uname -a``.
+The following examples show how to update kernel to either version **4.15** and **5.4**. To check your current kernel version, please use ``uname -a``.
 After a kernel update, please remember to reboot your machine at choose the newly installed one while the boot process starts.
 
 To update to kernel **v4.15**:
@@ -38,25 +38,64 @@ To update to kernel **v4.15**:
 
 To update to kernel **v5.4**:
 
+::
+
     wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v5.4/linux-headers-5.4.0-050400_5.4.0-050400.201911242031_all.deb
     wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v5.4/linux-headers-5.4.0-050400-generic_5.4.0-050400.201911242031_amd64.deb
     wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v5.4/linux-image-5.4.0-050400-generic_5.4.0-050400.201911242031_amd64.deb
     wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v5.4/linux-modules-5.4.0-050400-generic_5.4.0-050400.201911242031_amd64.deb
 
     sudo dpkg -i *.deb
-    sudo reboot    
+    sudo reboot
+
 
+To update to **other** kernels:
 
-Automatic installation from source files
-----------------------------------------
+You can follow the instructions at `Upgrading Ubuntu 20.04 to the latest Linux kernel <https://linuxconfig.org/how-to-upgrade-kernel-to-latest-version-on-ubuntu-20-04-focal-fossa-linux>`_, and possibly adapting the script there.
+The list of available kernels is available at https://kernel.ubuntu.com/~kernel-ppa/mainline/ .
 
-If you are running ``Ubuntu >= 18.04`` and you do not want to manually install Polycube and its dependencies, you can use the install script available under the `scripts` folder.
+
+Automatic installation from sources
+-----------------------------------
+
+If you are running ``Ubuntu >= 18.04`` and you do not want to manually install Polycube and its dependencies, you can use the install script available under the ``scripts`` folder.
 This scripts has been tested on ``Ubuntu 18.04``, ``Ubuntu 19.04`` and ``Ubuntu 20.04``.
 
 Please notice that this script does not update the kernel version.
 
-In order to install Polycube with the script, you have to:
+In order to install Polycube with the script, you can either download the most recent `Released version (stable)`_ or compile the `Most recent snapshot (from GitHub)`_.
+
+Once the installation is completed, you can follow the :doc:`quickstart` instructions.
+
+Note: if you have llvm 6.0 installed (check with ``apt list --installed | grep "llvm"``), the installation script will fail.
+In this case, remove llvm 6.0 before starting the installation script:
+
+::
+
+    sudo apt remove llvm-6.0 llvm-6.0-dev llvm-6.0-runtime
+
 
+**Released version** (stable)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+    # Download the source pack from Polycube repository 
+    #  (i.e., https://github.com/polycube-network/polycube/releases)
+    # Look at the most recent version and update the following lines accordingly
+    wget https://github.com/polycube-network/polycube/archive/v0.9.0-rc.zip
+
+    # Unpack the source files (e.g., this refers to version 0.9)
+    unzip v0.9.0-rc.zip
+
+    # Move into the newly created folder:
+    cd polycube-0.9.0-rc
+
+    # Launch the automatic install script (use -h to see the different installation modes)
+    ./scripts/install.sh
+
+
+**Most recent snapshot** (from GitHub)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ::
 
     # install git
@@ -70,18 +109,14 @@ In order to install Polycube with the script, you have to:
     # launch the automatic install script (use -h to see the different installation modes)
     ./scripts/install.sh
 
-Once the installation is completed, you can follow the :doc:`quickstart` instructions.
 
-Note: if you have llvm 6.0 installed (check with ``apt list --installed | grep "llvm"``), the installation script will fail.
-In this case, remove llvm 6.0 before starting the installation script:
 
-::
-
-    sudo apt remove llvm-6.0 llvm-6.0-dev llvm-6.0-runtime
+Manual installation from the most recent snapshop (on GitHub)
+-------------------------------------------------------------
 
+This procedure is discouraged, as the `Automatic installation from sources`_ looks appropriate for most of the people.
 
-Manual installation from source files
--------------------------------------
+The following steps are required only if you want to compile and install everything manually, without the provides install script (``./scripts/install.sh``).
 
 Install GO
 ^^^^^^^^^^

Documentation/intro.rst

@@ -1,21 +1,18 @@
 Introduction to Polycube
 ========================
 
-Polycube brief
---------------
+**Polycube** is an **open source** software framework for Linux that provides **fast** and **lightweight** **network functions**, such as `bridge`, `router`, `nat`, `load balancer`, `firewall`, `DDoS mitigator`, and more.
 
-``Polycube`` is an **open source** software framework for Linux that enables the creation of **virtual networks** and provides **fast** and **lightweight** **network functions**, such as `bridge`, `router`, `nat`, `load balancer`, `firewall`, `DDoS mitigator`, and more.
-
-Within each virtual network, individual network functions can be composed to build arbitrary **service chains** and provide custom network connectivity to **namespaces**, **containers**, **virtual machines**, and **physical hosts**.
+Individual network functions can be composed to build arbitrary **service chains** and provide custom network connectivity to **namespaces**, **containers**, **virtual machines**, and **physical hosts**. Polycube supports also multitenancy, with multiple **virtual networks** that can be enabled concurrently.
 
-Virtual functions, called `cubes`, are extremely **efficient** because are based on the recent `BPF` and `XDP` Linux kernel technologies. In addition, cubes are easily **extensible** and **customizable**.
+Network functions, called `cubes`, are extremely **efficient** because are based on the recent `BPF` and `XDP` Linux kernel technologies. In addition, cubes are easily **extensible** and **customizable**.
 
-Polycube can control its entire virtual topology and all the network services with a simple and coherent command line, available through the `polycubectl` tool.
-A set of equivalent commands can be issued diretly to `polycubed`, the Polycube REST-based daemon, for better machine-to-machine interaction.
+Polycube can control its entire virtual topology and all the network services with a simple and coherent command line, available through the ``polycubectl`` tool.
+A set of equivalent commands can be issued diretly to ``polycubed``, the Polycube REST-based daemon, for better machine-to-machine interaction.
 
 Polycube also provides two working **standalone applications** built up using this framework.
-`pcn-K8s` is a Polycube-based CNI plug-in for *Kubernetes*, which can handle the network of an entire data center. It also delivers better throughput as compared with some of the existing CNI plug-ins.
-`pcn-iptables` is a more efficient and scalable clone of the existing Linux *iptables*.
+**pcn-k8s** is a Polycube-based CNI plug-in for *Kubernetes*, which can handle the network of an entire data center. It also delivers better throughput as compared with some of the existing CNI plug-ins.
+**pcn-iptables** is a more efficient and scalable clone of the existing Linux *iptables*.
 
 A brief overview of the Polycube layered structure, including the command line interface (CLI), standalone applications, and some of the available cubes, is shown in the picture below.
 
@@ -63,13 +60,13 @@ Outstanding performance with real applications
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Two standalone applications have been released to show the potential of Polycube, ``pcn-iptables`` and ``pcn-k8s``.
 
-- `pcn-iptables`: is a clone of **iptables** that is able to filter packets passing through a Linux host, demonstrating how packet filtering can be achieved with impressive performance, while at the same time guaranteeing the same command line and the same external behavior of the original software.
-- `pcn-k8s`: is a CNI network plugin for **Kubernetes**, i.e., a software that handles the entire virtual network of a Kubernetes cluster, which includes bridging, routing, NAT, load balancing and tunneling services. Our plug-in has been tested for scalability and guarantees outstanding performance in terms of network throughput.
+- **pcn-iptables**: is a clone of **iptables** that is able to filter packets passing through a Linux host, demonstrating how packet filtering can be achieved with impressive performance, while at the same time guaranteeing the same command line and the same external behavior of the original software.
+- **pcn-k8s**: is a CNI network plugin for **Kubernetes**, i.e., a software that handles the entire virtual network of a Kubernetes cluster, which includes bridging, routing, NAT, load balancing and tunneling services. Our plug-in has been tested for scalability and guarantees outstanding performance in terms of network throughput.
 
 
 Powered by eBPF and XDP
 ~~~~~~~~~~~~~~~~~~~~~~~
-`BPF` and `XDP` are the main Linux kernel technologies on which `Polycube` is based. `BPF` supports dynamic code injection in the Linux kernel at runtime, enabling the dynamic creation of a data plane. The `BPF` data plane has a minimal feature set which avoids processing overhead and is exactly tailored to user needs.
+`BPF` and `XDP` are the main Linux kernel technologies on which Polycube is based upon. `BPF` supports dynamic code injection in the Linux kernel at runtime, enabling the dynamic creation of a data plane. The `BPF` data plane has a minimal feature set which avoids processing overhead and is exactly tailored to user needs.
 
 - `bpf` (Extended Berkeley Packet Filter) code is dynamically compiled and injected, checked for safety to avoid any hazard in the kernel, while efficiency is achieved thanks to a just-in-time compiler (JIT) that transforms each instruction into a native 64-bit (x64) code for maximum performance.
 - `XDP` (eXpress Data Path) provides a new way to intercept network packets very early in Linux network stack, with a significant gain in performance thanks to the possibility to avoid costly operations such as `skbuff` handling.