Add the Shadow + Span documentation

Signed-off-by: francescomessina <francescomessina92@hotmail.com>

Author: francescomessina

Documentation/cubes.rst

@@ -25,7 +25,7 @@ A standard cube:
            | +----------+ |
    port1---|-|          |-|---port3
            | |   core   | |
-   port2---|-|          |-|---port3
+   port2---|-|          |-|---port4
            | +----------+ |
            |              |
            +--------------+
@@ -71,6 +71,44 @@ Following is example topology composed by standard and transparent cubes.
 
 ``polycubectl ?`` shows available cubes installed on your system.
 
+
+A shadow cube:
+  Only a standard cube can be **Shadow** type;
+   - ``polycubectl <cubetype> add <cubename> shadow=true``.
+
+  A shadow cube is associated with a Linux network namespace;
+
+  The parameters between the shadow cube and the namespace are aligned;
+
+  A port defined on a shadow cube is also visible from the network namespace:
+   - the user can decide to configure the ports using Linux (e.g. ifconfig or the ip command) or polycubectl;
+
+     for example: "``polycubectl <cubename> ports <PortName> set ip=<IpAddress>``" it is the same as "``ip netns exec pcn-<cubename> ifconfig <PortName> <IpAddress>``".
+   - the developer can let Linux handle some traffic by sending it to the namespace (e.g. ARP, ICMP, but in general all those protocols able to be managed by a tool running inside the namespace);
+
+::
+
+                       +--------------+
+               port1---|              |---port3
+                       |  namespace   |
+               port2---|              |---port4
+  Linux                +--------------+
+ ____________________________________________________________
+
+::
+
+  Polycube               shadow cube
+                       +--------------+
+                       |              |
+                       | +----------+ |
+               port1---|-|          |-|---port3
+                       | |   core   | |
+               port2---|-|          |-|---port4
+                       | +----------+ |
+                       |              |
+                       +--------------+
+
+
 Cubes structure
 ---------------
 
@@ -177,3 +215,19 @@ These primitives allow to associate transparent cubes to standard cube's ports o
   polycubectl attach firewall1 r1:port2
 
   polycubectl attach firewall0 veth1
+
+
+Span Mode
+---------
+
+The shadow cubes have a mode called **span**.
+
+The span mode when activated shows all the traffic seen by the service also to the namespace.
+ - To activate the span mode the command used is "``polycubectl <cubename> set span=true``".
+
+Span mode is very useful for debugging; On a shadow cube in span mode programs such as Wireshark or Tcpdump can sniff the traffic.
+
+However, the span mode consumes many resources when it is active, so it is disabled by default and it is recommended to use it only when necessary.
+
+N.B. Span mode duplicates traffic so that it is shown by the namespace, the cube continues to handle traffic.
+For this reason, for example, if we have a shadow router with active span mode we should not have Ip forwarding active on Linux, otherwise the router service forwards packets and copies them to the namespace, the namespace forwards again packets and there will be duplications.

Documentation/developers/controlplane.rst

@@ -95,6 +95,8 @@ Generating PacketOut events
 
 The ``Port`` class contains the ``send_packet_out(EthernetII &packet, bool recirculate = false)`` method that allows to inject packets into the datapath, the recirculate parameter allows to specify if the packet should be sent out of the port (`recirculate = false`) or received through the port (`recirculate = true`).
 
+Only in shadow services the ``Port`` class contains the ``send_packet_ns(EthernetII &packet)`` method that allows to send packets into the service namespace.
+
 A reference to a port can be got using the `get_port` function of the Cube base class.
 
 Debugging and logging in the control plane
@@ -106,4 +108,4 @@ Usage example:
 
 ::
 
-  logger()->info("Connected port {0}", port_name);
+  logger()->info("Connected port {0}", port_name);

Documentation/developers/datapath.rst

@@ -22,6 +22,8 @@ Polycube architecture adds a wrapper around the user's code, this wrapper calls
 
 - **pcn_pkt_controller_with_metadata(struct __sk_buff *skb, struct pkt_metadata *md, u16 reason, u32 metadata[3])**: Sends the packet to the custom code running in the control path. In addition to the reason the user can also send some additional medatada.
 
+- **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
+
 Checksum calculation
 ********************
 
@@ -107,4 +109,3 @@ Usage example:
 ::
 
   pcn_pkt_log(ctx, LOG_DEBUG);
-