Skip to content

Commit df3c16e

Browse files
frissofrisso
authored
Merge pull request #275 from michelsciortino/pcn-dynmon
New transparent service: Dynamic Monitor
2 parents 0b5c7f5 + 57ee78d commit df3c16e

File tree

65 files changed

+5912
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+5912
-0
lines changed

‎Documentation/services/pcn-dynmon/dynmon.rst

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
Dynmon service
2+
==============
3+
4+
Dynmon is a transparent service that allows the dynamic injection of eBPF code in the linux kernel, enabling the monitoring of the network traffic and the collection and exportation of custom metrics.
5+
6+
This service exploits the capabilities of Polycube to replace the eBPF code running in the dataplane and the use of eBPF maps to share data between the control plane and the data plane.
7+
8+
Features
9+
--------
10+
- Transparent service, can be attached to any network interface and Polycube services
11+
- Support for the injection of any eBPF code at runtime
12+
- Support for eBPF maps content exportation through the REST interface as metrics
13+
- Support for two different exportation formats: JSON and OpenMetrics
14+
15+
Limitations
16+
-----------
17+
- The OpenMetrics format does not support complex data structures, hence the maps are exported only if their value type is a simple type (structs and unions are not supported)
18+
- The OpenMetrics Histogram and Summary metrics are not yet supported
19+
20+
How to use
21+
----------
22+
23+
24+
Creating the service
25+
^^^^^^^^^^^^^^^^^^^^
26+
::
27+
28+
#create the dynmon service instance
29+
polycubectl dynmon add monitor
30+
31+
32+
Configuring the data plane
33+
^^^^^^^^^^^^^^^^^^^^^^^^^^
34+
In order to configure the dataplane of the service, a configuration JSON object must be sent to the control plane; this action cannot be done through the **polycubectl** tool as it does not handle complex inputs.
35+
36+
To send the data plane configuration to the control plane it is necessary to exploit the REST interface of the service, applying a ``PUT`` request to the ``/dataplane`` endpoint.
37+
38+
Configuration examples can be found in the *examples* directory.
39+
40+
41+
Attaching to a interface
42+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
43+
::
44+
45+
# Attach the service to a network interface
46+
polycubectl attach monitor eno0
47+
48+
# Attach the service to a cube port
49+
polycubectl attach monitor br1:toveth1
50+
51+
52+
Collecting metrics
53+
^^^^^^^^^^^^^^^^^^
54+
To collect the metrics of the service, two endpoints have been defined to enable the two possible exportation formats:
55+
56+
- JSON format
57+
58+
::
59+
60+
polycubectl monitor metrics show
61+
62+
- OpenMetrics format
63+
64+
::
65+
66+
polycubectl monitor open-metrics show
67+
68+
69+
Dynmon Injector Tool
70+
--------------------
71+
72+
This tool allows the creation and the manipulation of a `dynmon` cube without using the standard `polycubectl` CLI.
73+
74+
Install
75+
^^^^^^^
76+
Some dependencies are required for this tool to run:
77+
::
78+
pip install -r requirements.txt
79+
80+
81+
Running the tool
82+
^^^^^^^^^^^^^^^^
83+
::
84+
85+
Usage: `dynmon_injector.py [-h] [-a ADDRESS] [-p PORT] [-v] cube_name peer_interface path_to_dataplane`
86+
87+
positional arguments:
88+
cube_name indicates the name of the cube
89+
peer_interface indicates the network interface to connect the cube to
90+
path_to_dataplane indicates the path to the json file which contains the new dataplane configuration
91+
which contains the new dataplane code and the metadata associated to the exported metrics
92+
93+
optional arguments:
94+
-h, --help show this help message and exit
95+
-a ADDRESS, --address ADDRESS set the polycube daemon ip address (default: localhost)
96+
-p PORT, --port PORT set the polycube daemon port (default: 9000)
97+
-v, --version show program's version number and exit
98+
99+
100+
Usage examples
101+
^^^^^^^^^^^^^^
102+
::
103+
104+
basic usage:
105+
./dynmon_injector.py monitor_0 eno1 ../examples/packet_counter.json
106+
107+
setting custom ip address and port to contact the polycube daemon:
108+
./dynmon_injector.py -a 10.0.0.1 -p 5840 monitor_0 eno1 ../examples/packet_counter.json
109+
110+
111+
This tool creates a new `dynmon` cube with the given configuration and attaches it to the selected interface.
112+
113+
If the monitor already exists, the tool checks if the attached interface is the same used previously; if not, it detaches the cube from the previous interface and attaches it to the new one; then, the selected dataplane is injected.

‎src/services/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ add_service(iptables pcn-iptables)
3636
add_service(transparenthelloworld pcn-transparent-helloworld)
3737
add_service(synflood pcn-synflood)
3838
add_service(packetcapture pcn-packetcapture)
39+
add_service(dynmon pcn-dynmon)
3940

4041
# save string to create code that load the services
4142
SET_PROPERTY(GLOBAL PROPERTY LOAD_SERVICES_ ${LOAD_SERVICES})

‎src/services/pcn-dynmon/.swagger-codegen-ignore

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Swagger Codegen Ignore
2+
# Generated by swagger-codegen https://github.com/swagger-api/swagger-codegen
3+
4+
# Use this file to prevent files from being overwritten by the generator.
5+
6+
.swagger-codegen-ignore
7+
8+
src/*.cpp
9+
src/*.h
10+
11+
!src/*Interface.h
12+
!src/*JsonObject.h
13+
!src/*JsonObject.cpp

‎src/services/pcn-dynmon/CMakeLists.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
cmake_minimum_required (VERSION 3.2)
2+
3+
set (CMAKE_CXX_STANDARD 11)
4+
5+
add_subdirectory(src)

‎src/services/pcn-dynmon/cmake/LoadFileAsVariable.cmake

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Loads the contents of a file into a std::string variable
2+
#
3+
# It creates a header file in ${CMAKE_CURRENT_BINARY_DIR}/${file}.h
4+
# that wrapps the contents of the file in a std::string using the raw
5+
# string literal feature of C++11. The user needs to include that file
6+
# into the source code in order to see the variable.
7+
#
8+
# parameters:
9+
# target: target to add a dependency on file
10+
# file: file to be loaded
11+
# variable_name: name variable where the file is loaded
12+
#
13+
# example:
14+
# load_file_as_variable(my-lib resource.c my_resource)
15+
# Creates a resource.h in CMAKE_CURRENT_BINARY_DIR with a string variable
16+
# my_resource with the contents of resource.c
17+
# A dependency in resource.c is added to my-lib
18+
19+
function(load_file_as_variable target file variable_name)
20+
get_filename_component(file_name ${file} NAME_WE)
21+
get_filename_component(file_dir ${file} DIRECTORY)
22+
23+
set(new_path ${file_dir}/${file_name}.h)
24+
25+
add_custom_command(
26+
OUTPUT
27+
${CMAKE_CURRENT_BINARY_DIR}/${new_path}
28+
COMMAND
29+
mkdir -p ${CMAKE_CURRENT_BINARY_DIR}/${file_dir}
30+
COMMAND
31+
echo "#pragma once" > ${CMAKE_CURRENT_BINARY_DIR}/${new_path}
32+
COMMAND
33+
echo "#include <string>" >> ${CMAKE_CURRENT_BINARY_DIR}/${new_path}
34+
COMMAND
35+
echo "const std::string ${variable_name} = R\"POLYCUBE_DP(" >> ${CMAKE_CURRENT_BINARY_DIR}/${new_path}
36+
COMMAND
37+
cat ${CMAKE_CURRENT_SOURCE_DIR}/${file} >> ${CMAKE_CURRENT_BINARY_DIR}/${new_path}
38+
COMMAND
39+
cmake -E echo ")POLYCUBE_DP\";" >> ${CMAKE_CURRENT_BINARY_DIR}/${new_path}
40+
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${file}
41+
VERBATIM
42+
)
43+
44+
string(REPLACE "/" "-" path_replaced ${new_path})
45+
46+
add_custom_target(
47+
generate_${path_replaced}
48+
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${new_path}
49+
)
50+
51+
add_dependencies(${target} generate_${path_replaced})
52+
endfunction()

‎src/services/pcn-dynmon/datamodel/dynmon.yang

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
module dynmon {
2+
yang-version 1.1;
3+
namespace "http://polycube.network/dynmon";
4+
prefix "dynmon";
5+
6+
import polycube-base {
7+
prefix "polycube-base";
8+
}
9+
import polycube-transparent-base {
10+
prefix "polycube-transparent-base";
11+
}
12+
import "ietf-inet-types" {
13+
prefix "inet";
14+
}
15+
import "ietf-yang-types" {
16+
prefix "yang";
17+
}
18+
19+
organization
20+
"Polycube open source project";
21+
description
22+
"YANG data model for the Polycube Dynamic Traffic Monitor transparent service";
23+
polycube-base:service-description "Dynamic Traffic Monitor transparent service";
24+
polycube-base:service-version "1.0";
25+
polycube-base:service-name "dynmon";
26+
polycube-base:service-min-kernel-version "4.14.0";
27+
28+
uses polycube-transparent-base:transparent-base-yang-module;
29+
30+
container dataplane {
31+
description
32+
"Running dataplane";
33+
leaf name {
34+
type string;
35+
description
36+
"eBPF program name";
37+
polycube-base:init-only-config;
38+
}
39+
leaf code {
40+
type string;
41+
description
42+
"eBPF source code";
43+
polycube-base:init-only-config;
44+
}
45+
list metrics {
46+
key "name";
47+
description
48+
"Exported Metric";
49+
polycube-base:init-only-config;
50+
leaf name {
51+
type string;
52+
description
53+
"Name of the metric (e.g., number of HTTP requests)";
54+
polycube-base:init-only-config;
55+
}
56+
leaf map-name {
57+
type string;
58+
description
59+
"Corrisponding eBPF map name";
60+
polycube-base:init-only-config;
61+
}
62+
container open-metrics-metadata {
63+
presence
64+
"The metric will be exported with the OpenMetric format";
65+
description
66+
"Open-Metrics metadata";
67+
polycube-base:init-only-config;
68+
leaf help {
69+
type string;
70+
description
71+
"Metric description";
72+
polycube-base:init-only-config;
73+
}
74+
leaf type {
75+
type enumeration{
76+
enum Counter;
77+
enum Gauge;
78+
enum Histogram;
79+
enum Summary;
80+
enum Untyped;
81+
}
82+
description
83+
"Metric type";
84+
polycube-base:init-only-config;
85+
}
86+
list labels {
87+
key "name";
88+
description
89+
"Label attached to the metric";
90+
polycube-base:init-only-config;
91+
leaf name {
92+
type string;
93+
description
94+
"Name of the label (e.g., 'method')";
95+
polycube-base:init-only-config;
96+
}
97+
leaf value {
98+
type string;
99+
description
100+
"Label value (e.g., 'POST')";
101+
polycube-base:init-only-config;
102+
}
103+
}
104+
}
105+
}
106+
}
107+
list metrics {
108+
config false;
109+
key "name";
110+
description
111+
"Collected metrics";
112+
leaf name {
113+
config false;
114+
type string;
115+
description
116+
"Name of the metric (e.g, number of HTTP requests)";
117+
}
118+
leaf value {
119+
config false;
120+
type string;
121+
description
122+
"Value of the metric";
123+
}
124+
leaf timestamp {
125+
config false;
126+
type int64;
127+
description
128+
"Timestamp";
129+
}
130+
}
131+
leaf open-metrics {
132+
config false;
133+
type string;
134+
description
135+
"Collected metrics in OpenMetrics Format";
136+
}
137+
}

‎src/services/pcn-dynmon/examples/README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Monitoring examples
2+
3+
This folder contains a set of monitoring dataplanes, which can be used as examples for the Dynamic Monitoring service.
4+
5+
- [packet_counter.json](packet_counter.json):
6+
- the `packets_total` metric represents the number of packets that have traversed the attached network interface
7+
8+
- [ntp_packets_counter.json](ntp_packets_counter.json):
9+
- the `ntp_packets_total` metric represents the number of NTP packets that have traversed the attached network interface
10+
11+
- [ntp_packets_ntp_mode_private_counters.json](ntp_packets_ntp_mode_private_counters.json):
12+
- the `ntp_packets_total` metric represents the number of NTP packets that have traversed the attached network interface;
13+
- the `ntp_mode_private_packets_total` metric represents the number of NTP packets with NTP_MODE = 7 (MODE_PRIVATE) that have traversed the attached network interface
14+
15+
All counters are *incremental*, hence their values are monotonically increasing.
16+
17+
18+
Unfortunately the dataplane code (eBPF restricted C) contained in the above JSONs is not easy to read for a human, due to the formatting limitations of the JSON format. A more human friendly version can be produced by unescaping the code by using [this online free tool](https://www.freeformatter.com/json-escape.html).
19+
20+
The same tool can be used also to escape any multiline code strings in order to create new valid injectable dataplanes.

‎src/services/pcn-dynmon/examples/ntp_packets_counter.json

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"name": "NTP Amplification BUA probe",
3+
"code": "\r\n#include <uapi/linux/ip.h>\r\n#include <uapi/linux/udp.h>\r\n\r\n#define IP_PROTO_UDP 17\r\n#define NTP_PORT 123\r\n\r\nstruct eth_hdr {\r\n __be64 dst : 48;\r\n __be64 src : 48;\r\n __be16 proto;\r\n} __attribute__((packed));\r\n\r\nBPF_ARRAY(NTP_PACKETS_COUNTER, uint64_t,1);\r\n\r\nstatic __always_inline\r\nint handle_rx(struct CTXTYPE *ctx, struct pkt_metadata *md) {\r\n /*Parsing L2*/\r\n void *data = (void *) (long) ctx->data;\r\n void *data_end = (void *) (long) ctx->data_end;\r\n struct eth_hdr *ethernet = data;\r\n if (data + sizeof(*ethernet) > data_end)\r\n return RX_OK;\r\n\r\n if (ethernet->proto != bpf_htons(ETH_P_IP))\r\n return RX_OK;\r\n\r\n /*Parsing L3*/\r\n struct iphdr *ip = data + sizeof(struct eth_hdr);\r\n if (data + sizeof(struct eth_hdr) + sizeof(*ip) > data_end)\r\n return RX_OK;\r\n if ((int) ip->version != 4)\r\n return RX_OK;\r\n\r\n if (ip->protocol != IP_PROTO_UDP)\r\n return RX_OK;\r\n\r\n /*Parsing L4*/\r\n uint8_t ip_header_len = 4 * ip->ihl;\r\n struct udphdr *udp = data + sizeof(*ethernet) + ip_header_len;\r\n if (data + sizeof(*ethernet) + ip_header_len + sizeof(*udp) > data_end)\r\n return RX_OK;\r\n\r\n if (udp->source == bpf_htons(NTP_PORT) || udp->dest == bpf_htons(NTP_PORT)) {\r\n pcn_log(ctx, LOG_TRACE, \"%I:%P\\t-> %I:%P\", ip->saddr,udp->source,ip->daddr,udp->dest);\r\n unsigned int key = 0;\r\n uint64_t * ntp_pckts_counter = NTP_PACKETS_COUNTER.lookup(&key);\r\n if (!ntp_pckts_counter)\r\n pcn_log(ctx, LOG_ERR, \"[NTP_AMP_BUA] Unable to find NTP_PACKETS_COUNTER map\");\r\n else\r\n *ntp_pckts_counter+=1;\r\n }\r\n\r\n return RX_OK;\r\n}",
4+
"metrics": [
5+
{
6+
"name": "ntp_packets_total",
7+
"map-name": "NTP_PACKETS_COUNTER",
8+
"open-metrics-metadata": {
9+
"help": "This metric represents the number of NTP packets that has traveled through this probe.",
10+
"type": "counter",
11+
"labels": [
12+
{
13+
"name": "IP_PROTO",
14+
"value": "UDP"
15+
},
16+
{
17+
"name": "L4",
18+
"value": "NTP"
19+
}
20+
]
21+
}
22+
}
23+
]
24+
}

0 commit comments

Comments
 (0)