Added Documentation

Update AUTHORS file

Update Copyright year

fixed the codestyle

Addded pcn-packetcapture test description

Added comments

Author: DavideAG

AUTHORS

@@ -2,6 +2,7 @@ The following people, in alphabetical order, have either authored or signed
 off on commits in the Polycube repository:
 
   Aasif Shaikh                            aasif@shaikh.cc
+  Davide Antonino Giorgio                 davideantonino94@gmail.com
   Francesco Messina                       francescomessina92@hotmail.com
   Fulvio Risso                            fulvio.risso@polito.it
   Gianluca Scopelliti                     gianlu.1033@gmail.com

Documentation/services/pcn-packetcapture/Packetcapture.rst

@@ -0,0 +1,139 @@
+Packetcapture service
+=====================
+
+Packetcapture is a transparent service that allows to capture packets flowing through the interface it is attached to, apply (simple) filters and obtain capture in *.pcap* format. In particular, the service supports either saving captured packets in the local filesystem (e.g., useful in case of high network traffic) or it can interact and deliver packets to a remote client that stores them in the remote filesystem.
+
+An example of a client that uses the REST api of the packetcapture service is available in '*Packetcapture_Client*' directory.
+
+Features
+--------
+- Transparent service, can be attached to any interface of any Polycube service
+- Support for (simple) IPv4 filters: source prefix, destination prefix, source port, destination port and layer 4 protocol.
+- Support partial capture of packets (i.e., snaplen)
+- Support localmode (store data locally) or network mode (send packets to a remote client) operations
+
+Limitations
+-----------
+- No IPv6 filtering
+- Traffic is returned as is, without any anonimization primitive.
+
+How to use
+----------
+The packetcapture service is a transparent service, it can be attached to a cube port.
+
+Create the service
+^^^^^^^^^^^^^^^^^^
+
+::
+
+    #create the packetcapture service
+    polycubectl packetcapture add sniffer capture=bidirectional
+
+This service can operate in four working modes (actually, the forth mode is just to turn the capture off):
+
+- capture only incoming packets: **capture=ingress**
+- capture only outgoing packets: **capture=egress**
+- capture both incoming and outgoing packets: **capture=bidirectional**
+- turn packet capture off: **capture=off**
+
+*capture* option indicates the direction of the packets that the service must capture.
+The direction of the captured packets is independent of the operation in "nework mode" or "non network mode".
+
+In this example the service named '*mysniffer*' will work in bidirectional mode.
+
+
+Attach to a cube port
+^^^^^^^^^^^^^^^^^^^^^
+::
+
+    # Attach the service to a cube port
+    polycubectl attach mysniffer br1:toveth1
+
+Now the packetcapture service is attached to the port *toveth1* of the bridge *br1*
+
+                +----------+
+ veth1 ---**x**-|   br1    |------ veth2    
+                +----------+
+
+
+Filters
+-------
+Traffic can be selected by means of the following filters:
+
+- source prefix
+- destination prefix
+- source port
+- destination port
+- later 4 protocol
+
+Source prefix filter
+^^^^^^^^^^^^^^^^^^^^
+::
+
+    # Example of the source prefix filter
+    polycubectl mysniffer filters set src=10.10.10.10/24
+
+Destination prefix filter
+^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+    
+    # Example of the destination prefix filter
+    polycubectl mysniffer filters set dst=10.10.10.10/24
+
+Source port filter
+^^^^^^^^^^^^^^^^^^
+::
+    
+    # Example of the source port filter
+    polycubectl mysniffer filters set sport=80
+
+Destination port filter
+^^^^^^^^^^^^^^^^^^^^^^^
+::
+    
+    # Example of the destination port filter
+    polycubectl mysniffer filters set dport=80
+
+Layer 4 protocol filter
+^^^^^^^^^^^^^^^^^^^^^^^
+::
+    
+    # Example of the layer 4 protocol filter
+    polycubectl mysniffer filters set l4proto=tcp
+
+Snaplen filter
+^^^^^^^^^^^^^^
+::
+    
+    # Example of the snaplen filter
+    #  In this case we capture only the first 80 bytes of each packet
+    polycubectl mysniffer filters set snaplen=80
+
+
+Filters can be viewed using the command **polycubectl mysniffer filters show**
+
+Get the capture dump
+--------------------
+When the service is not set in *networkmode*, the dump is automatically written in a resilient way in the current working directory.
+
+The path of the capture file can be shown using the command: **polycubectl mysniffer show dump**
+
+Otherwise, if the service is set in network mode, the capture file can be requested through the use of the provided Python client, or queried simply through the service API.
+
+How to use the demo client
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+    
+    # Start the client script
+    python3 client.py <IPv4 address> <file destination name>
+
+
+Set network mode
+^^^^^^^^^^^^^^^^
+::
+    
+    # Start sniffer in network mode
+    polycubectl mysniffer set networkmode=true
+
+    # Start sniffer in local model
+    polycubectl mysniffer set networkmode=false

src/services/pcn-packetcapture/cmake/LoadFileAsVariable.cmake

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 The Polycube Authors
+ * Copyright 2019 The Polycube Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -61,7 +61,7 @@ uint32_t Filters::getSnaplen() {
 void Filters::setSnaplen(const uint32_t &value) {
   snaplen = value;
   set_snaplen = true;
-  if(!bootstrap)
+  if (!bootstrap)
     parent_.updateFiltersMaps();
 }
 
@@ -78,10 +78,9 @@ void Filters::setSrc(const std::string &value) {
   inet_pton(AF_INET, source_ip.data(), &ip_src_filter);
   ip_src_filter = ntohl(ip_src_filter);
   networkSrc = ip_src_filter & netmaskSrc;
-  //network_packet = pkt_values.srcIp & netmask_filter;     //TODO: do it in the fast path
 
   set_srcIp = true;
-  if(!bootstrap)
+  if (!bootstrap)
     parent_.updateFiltersMaps();
 }
 
@@ -98,10 +97,9 @@ void Filters::setDst(const std::string &value) {
   inet_pton(AF_INET, source_ip.data(), &ip_dst_filter);
   ip_dst_filter = ntohl(ip_dst_filter);
   networkDst = ip_dst_filter & netmaskDst;
-  //network_packet = pkt_values.dstIp & netmask_filter;     //TODO: do it in the fast path
 
   set_dstIp = true;
-  if(!bootstrap)
+  if (!bootstrap)
     parent_.updateFiltersMaps();
 }
 
@@ -110,13 +108,14 @@ std::string Filters::getL4proto() {
 }
 
 void Filters::setL4proto(const std::string &value) {
-  if((value.compare(std::string("tcp")) == 0) || (value.compare(std::string("udp")) == 0)){
+  if ((value.compare(std::string("tcp")) == 0) || (value.compare(std::string("udp")) == 0)){
     l4proto = value;
     set_l4proto = true;
-    if(!bootstrap)
+    if (!bootstrap)
       parent_.updateFiltersMaps();
-  }else
+  } else {
     throw std::runtime_error("Bad value at setL4proto. Please enter 'tcp' or 'udp'");
+  }
 }
 
 uint16_t Filters::getSport() {
@@ -126,7 +125,7 @@ uint16_t Filters::getSport() {
 void Filters::setSport(const uint16_t &value) {
   srcPort = value;
   set_srcPort = true;
-  if(!bootstrap)
+  if (!bootstrap)
     parent_.updateFiltersMaps();
 }
 
@@ -137,22 +136,22 @@ uint16_t Filters::getDport() {
 void Filters::setDport(const uint16_t &value) {
   dstPort = value;
   set_dstPort = true;
-  if(!bootstrap)
+  if (!bootstrap)
     parent_.updateFiltersMaps();
 }
 
-uint32_t Filters::getNetworkFilterSrc(){
+uint32_t Filters::getNetworkFilterSrc() {
   return networkSrc;
 }
 
-uint32_t Filters::getNetworkFilterDst(){
+uint32_t Filters::getNetworkFilterDst() {
   return networkDst;
 }
 
-uint32_t Filters::getNetmaskFilterSrc(){
+uint32_t Filters::getNetmaskFilterSrc() {
   return netmaskSrc;
 }
 
-uint32_t Filters::getNetmaskFilterDst(){
+uint32_t Filters::getNetmaskFilterDst() {
   return netmaskDst;
 }

src/services/pcn-packetcapture/src/Filters.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 The Polycube Authors
+ * Copyright 2019 The Polycube Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/services/pcn-packetcapture/src/Filters.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 The Polycube Authors
+ * Copyright 2019 The Polycube Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/services/pcn-packetcapture/src/Globalheader.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 The Polycube Authors
+ * Copyright 2019 The Polycube Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/services/pcn-packetcapture/src/Globalheader.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 The Polycube Authors
+ * Copyright 2019 The Polycube Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -89,10 +89,10 @@ std::string ascii_to_utf8(const std::vector<uint8_t> &packet){
   std::string ret("");
   char ch;
 
-  for(int i = 0 ; i < packet.size(); i++){
-    if(packet[i] < 128){
+  for (int i = 0 ; i < packet.size(); i++){
+    if (packet[i] < 128){
       ret.push_back((char) packet[i]);
-    }else{
+    } else {
       ch = (char) packet[i];
       ret.push_back((char)((packet[i] >> 6) | 0xC0));
       ret.push_back((ch & 0x3F) | 0x80);

src/services/pcn-packetcapture/src/Packet.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 The Polycube Authors
+ * Copyright 2019 The Polycube Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/services/pcn-packetcapture/src/Packet.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 The Polycube Authors
+ * Copyright 2019 The Polycube Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.