Doc fixes (#247)

frisso · web-flow · commit e2c788ab2675 · 2019-12-03T10:10:13.000+01:00
* Fixed command syntax.
* Updated NAT documentation
* Integrated missing files in the online documentation

Signed-off-by: Fulvio Risso &lt;fulvio.risso@polito.it&gt;
diff --git a/Documentation/README.md b/Documentation/README.md
@@ -2,18 +2,18 @@
 
 **The polycube documentation is available on [ReadTheDocs](https://polycube-network.readthedocs.io/en/latest/).**
 
-The instructions below are intended if you want to generate the documentation locally.
+The instructions below are intended only if you want to generate the documentation locally.
 
 ## Building the documentation locally
 
 ### Installing the dependencies
 
 Our documentation uses `sphinx`.
-In order to install the dependencies do
+In order to install the dependencies type:
 
 ```
 cd Documentation
-pip install -r Documentation/requirements.txt
+pip install -r requirements.txt
 ```
 
 ### Build it
diff --git a/Documentation/architecture.rst b/Documentation/architecture.rst
@@ -1,12 +1,6 @@
 Polycube Architecture
 =====================
 
-**NOTE: this file is outdated**
-
-Polycube is a framework to **create** and **deploy** arbitrary virtual network functions, such as bridges, routers, NATs, firewalls and more, and enables the creation of complex **service chains** by connecting together the above modules.
-
-It is based on the eBPF technology available in the Linux kernel and leverages some companion tools developed in the Iovisor community, such as [BCC](https://github.com/iovisor/bcc/).
-
 The Polycube architecture is depicted below:
 
 .. image:: images/architecture_overview.png
@@ -32,6 +26,7 @@ Each network function is implemented as a separated module and multiple flavors
 Each service implementation includes the `datapath`, namely the eBPF code to be injected in the kernel, the `control/management plane`, which defines the primitives that allow to configure the service behavior, and the `slow path`, which handles packets that cannot be fully processed in the kernel. While the former code runs in the Linux kernel, the latter components are executed in user-space.
 Given the feature-rich nature of the eBPF, the slow path should be rather small; an example can be the implementation of the spanning tree for 802.1Q bridges, which does not make sense to have in the kernel and that can stay in user space.
 
+
 Polycubectl
 -----------
 This module implements the service-agnostic command-line interface (CLI) that allows to control the entire system, such as starting/stopping services, creating service instances (e.g., bridges `br1` and `br2`), and configuring / querying the internals of each single service (e.g., enabling the spanning tree on bridge `br1`).
diff --git a/Documentation/developers/index.rst b/Documentation/developers/index.rst
@@ -3,6 +3,21 @@ Polycube Developers Guide
 
 This guide represents an initial starting point for developers that want to implement new services (e.g., custom NAT, router, etc) using the Polycube software infrastructure.
 
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   datapath
+   controlplane
+   datamodel
+   codegen
+   debugging
+   profiler
+   hints
+
+
+
 How to create a new service / update an existing one
 ----------------------------------------------------
 
@@ -16,21 +31,3 @@ The process to create or update service could be summarized in these steps:
 Please note that steps (1) and (2) are needed only when there is a change to the the YANG data model.
 In case we have to slightly modify an existing service (e.g., fixing a bug in the code), only steps (3) and (4) are required.
 
-
-Debugging Polycube services
----------------------------
-:doc:`See how to use the provided logging primitives <debugging>`
-
-
-How to benchmark code execution
--------------------------------
-
-To measure time taken by functions, instructions or a whole service, an internal easy to use profiling framework can be used.
-
-Please follow the instructions in the guide :doc:`Profiling Polycube Framework <profiler>`.
-
-
-Some hints for programmers
---------------------------
-
-:doc:`hints for programmers <hints>`
diff --git a/Documentation/index.rst b/Documentation/index.rst
@@ -13,6 +13,7 @@ Welcome to Polycube's documentation!
    intro
    quickstart
    installation
+   architecture
    cubes
    polycubed/polycubed
    polycubectl/polycubectl
diff --git a/Documentation/installation.rst b/Documentation/installation.rst
@@ -1,17 +1,17 @@
 Installing Polycube
 ===================
 
-This installation guide includes instructions to install polycube on ``Ubuntu 18.04``, however with few changes those should also work on other versions and distributions.
+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.
 
 Dependencies
 ------------
 
-``polycube`` requires following dependencies:
-
-- At least **Linux kernel v4.15** that includes a set of the eBPF features which are needed by polycube
-- **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)
+Polycube requires following dependencies:
+ - At least **Linux kernel v4.15** that includes a set of the eBPF features which are needed by polycube
+ - **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.
 
@@ -31,8 +31,8 @@ Use ``uname -a`` to check the kernel version you are running, if this is ``<v4.1
     sudo dpkg -i *.deb
     sudo reboot
 
-Automatic installation
-----------------------
+Automatic installation from source files
+----------------------------------------
 
 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 is not guaranteed that the script works on versions or distributions other than ``Ubuntu 18.04``.
@@ -62,8 +62,9 @@ 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
 
-Installing from source
-----------------------
+
+Manual installation from source files
+-------------------------------------
 
 Install GO
 ^^^^^^^^^^
diff --git a/Documentation/services/pcn-nat/nat.rst b/Documentation/services/pcn-nat/nat.rst
@@ -15,19 +15,19 @@ Limitations
 -----------
 
 - Unsupported IPv6
-- Unsupported ARP: the ARP messages will be forwarded without processing them
+- Unsupported ARP: ARP messages are forwarded without any processing
 - Incremental external port choice, starting from 1024 each time 65535 is reached
 
 How to use
 ----------
 
-The nat is a transparent service, it can be attached to a cube port or to a netdev.
-The nat is intended to be used with a router, it could not work when attached to different services.
+The NAT is a transparent service, it can be attached to a cube port or to a netdev.
+The NAT is intended to be used with a router, it may not work when attached to different services.
 
 Attached to a router
 ^^^^^^^^^^^^^^^^^^^^
 
-When a nat instance is attached to a router the external IP is automatically configured.
+When a NAT instance is attached to a router, the external IP is automatically configured.
 
 ::
 
@@ -53,31 +53,41 @@ Attached to a netdev
     # TODO: there is not an API for it!
 
 
-Rules
------
+Working modes
+-------------
 
-Adding rules
-^^^^^^^^^^^^
 
 Source NAT
-**********
+^^^^^^^^^^
+
+Source NAT selects a given range of hosts (i.e., the ```internal-net```) to be translated with a given public IP address (i.e., the ```external-ip```).
+Each time a new session originated from the internal network is recognized, the NAT creates a new binding also for return packets.
 
-Available and mandatory fields for SNAT rules are
-- ```internal-net```: the internal network to translate (e.g 10.0.0.0/24, 10.0.0.1/32)
-- ```external-ip```: the external IP address (e.g. 1.2.3.4)
+Source NAT enables users to specify exactly the range of addresses belonging to the ```internal-net```, e.g., excluding some hosts from being natted. In addition, it specifies exactly the external IP that has to be used, e.g., in case multiple external IP addresses are available.
+
+Available and mandatory fields for SNAT rules are:
+ - ```internal-net```: the internal network to translate (e.g 10.0.0.0/24, 10.0.0.1/32)
+ - ```external-ip```: the external IP address (e.g. 1.2.3.4)
 
 Sample rule:
 
 ::
 
     polycubectl nat1 rule snat append internal-net=10.0.0.0/24 external-ip=1.2.3.4
 
+
 Masquerade
-**********
+^^^^^^^^^^
 
-Masquerade can be either enabled or disabled.
+NAT masquerading is a simpler form of source NAT: it automatically translates the traffic of all hosts coming from the internal network with the IP address currently present on the external interface.
+Hence, it requires a simpler configuration that is usually enough for most cases.
+
+Unlike ```iptables``` in Linux, NAT masquerading in Polycube does not add extra overhead compared to SNAT.
+In fact, the ```external-ip``` address is kept in a dedicated table in the data plane and it is automatically updated each time the actual IP address configured on the external virtual interface is changed.
+This avoid to check which IP address has to be used each time a new packet is received.
 
-When enabled, the source IP address of the packet is set to the external IP of the NAT, and a new source port is assigned.
+Masquerade can be either enabled or disabled.
+When enabled, the source IP address of outgoing packets is set to the external IP of the NAT, and a new source port is assigned.
 
 To enable masquerade:
 
@@ -91,12 +101,19 @@ To disable masquerade:
 
     polycubectl nat1 rule masquerade disable
 
+
 Destination NAT
-***************
+^^^^^^^^^^^^^^^
 
-Available and mandatory fields for DNAT rules are
-- ```internal-ip```: the internal IP address (e.g 10.0.0.1)
-- ```external-ip```: the external IP address (e.g. 1.2.3.4)
+Destination NAT adds a new translation rule for traffic coming from the external network directed to the internal network. It implements what is also called `static` NAT in other contexts.
+This features allows external traffic to be forwarded to the internal network without having a corresponding session already established from inside.
+
+The destination NAT forwards all the traffic coming to a specific ```external-ip``` to a given ```internal-ip```, without inspecting other packet fields such as TCP/UDP ports, or protocols (e.g., ICMP).
+Obviously, this option requires a dedicated ```external-ip``` for each mapping.
+
+Available and mandatory fields for DNAT rules are:
+ - ```internal-ip```: the internal IP address (e.g 10.0.0.1)
+ - ```external-ip```: the external IP address (e.g. 1.2.3.4)
 
 Sample rule:
 
@@ -106,15 +123,18 @@ Sample rule:
 
 All the packets directed to ```1.2.3.4``` will be sent to ```10.0.0.1```, so use this rule carefully.
 
+
 Port Forwarding
-***************
+^^^^^^^^^^^^^^^
+
+Port forwarding implements a more selective form of destination NAT, allowing to specify the exact binding by means of other parameters such as the destination TCP/UDP port. This enables the sharing of the same ```external-ip``` among many ```internal-ip``` hosts, provided that their traffic can be differentiated e.g., by means of other parameters such as the ```external-port``` in use. 
 
-Available and mandatory fields for Port Forwarding rules are
-- ```internal-ip```: the internal IP address (e.g 10.0.0.1)
-- ```external-ip```: the external IP address (e.g. 1.2.3.4)
-- ```internal-port```: the internal port number (e.g 8080)
-- ```external-port```: the external port number (e.g. 80)
-- ```proto```: the upper layer protocol (e.g. tcp, udp, all). This field is optional: if not specified, all protocols are considered
+Available and mandatory fields for Port Forwarding rules are:
+ - ```internal-ip```: the internal IP address (e.g 10.0.0.1)
+ - ```external-ip```: the external IP address (e.g. 1.2.3.4)
+ - ```internal-port```: the internal port number (e.g 8080)
+ - ```external-port```: the external port number (e.g. 80)
+ - ```proto```: the upper layer protocol (e.g. tcp, udp, all). This field is optional: if not specified, all protocols are considered
 
 Sample rule:
 
@@ -127,6 +147,10 @@ Sample rule:
 
 This type of rule is especially useful to make a server in the inside network reachable from the outside.
 
+
+Other NAT operations
+--------------------
+
 Deleting rules
 ^^^^^^^^^^^^^^
 
@@ -152,6 +176,7 @@ To delete a single rule (an SNAT rule in the example):
 
 Deleting a rule does not affect ongoing natting sessions: to prevent a deleted rule from being applied, `flush the natting table <Natting-table>`_.
 
+
 Showing rules
 ^^^^^^^^^^^^^
 
@@ -169,13 +194,14 @@ To display one type of rule (SNAT in the example):
 
     polycubectl nat1 rule snat show
 
+
 Rule priority
 ^^^^^^^^^^^^^
 
-It is not possible to manually set a priority for each rule, but:
-- SNAT rules have higher priority than Masquerade
-- Port Forwarding rules have higher priority than DNAT rules
-- Port Forwarding rules with protocol have higher priority than Port Forwarding rules without protocol
+Explicit rule priorities are not supported; however:
+ - SNAT rules have higher priority than Masquerade
+ - Port Forwarding rules have higher priority than DNAT rules
+ - Port Forwarding rules with protocol have higher priority than Port Forwarding rules without protocol
 
 Natting table
 -------------
