You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
4
+
Packetcapture is a transparent service that allows to capture packets flowing through the interface it is attached to, apply 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.
5
5
6
6
An example of a client that uses the REST api of the packetcapture service is available in '*Packetcapture_Client*' directory.
7
7
8
8
Features
9
9
--------
10
+
10
11
- Transparent service, can be attached to any interface of any Polycube service
11
-
- Support for (simple) IPv4 filters: source prefix, destination prefix, source port, destination port and layer 4 protocol.
12
+
- Support for filters (i.e., source prefix, destination prefix, source port, destination port, layer 4 protocol, etc.).
12
13
- Support partial capture of packets (i.e., snaplen)
13
14
- Support localmode (store data locally) or network mode (send packets to a remote client) operations
14
15
15
16
Limitations
16
17
-----------
17
-
- No IPv6 filtering
18
+
18
19
- Traffic is returned as is, without any anonimization primitive.
19
20
21
+
20
22
How to use
21
23
----------
22
24
The packetcapture service is a transparent service, it can be attached to a cube port.
@@ -37,13 +39,14 @@ This service can operate in four working modes (actually, the forth mode is just
37
39
- turn packet capture off: **capture=off**
38
40
39
41
*capture* option indicates the direction of the packets that the service must capture.
40
-
The direction of the captured packets is independent of the operation in "nework mode" or "non network mode".
42
+
The direction of the captured packets is independent of the operation in "network mode" or "non network mode".
41
43
42
44
In this example the service named '*mysniffer*' will work in bidirectional mode.
43
45
44
46
45
47
Attach to a cube port
46
48
^^^^^^^^^^^^^^^^^^^^^
49
+
47
50
::
48
51
49
52
# Attach the service to a cube port
@@ -56,70 +59,76 @@ Now the packetcapture service is attached to the port *toveth1* of the bridge *b
56
59
57
60
58
61
59
-
Filters
62
+
Filter
60
63
-------
61
-
Traffic can be selected by means of the following filters:
64
+
Traffic can be selected by adding filters with syntax (tcpdump like):
65
+
66
+
polycubectl <service name> set filter=<string value>
67
+
68
+
-if the filter contains only one word you can put it normally
69
+
-if the filter contains more than a word you have to put the string inside the ""
70
+
71
+
-if you want to capture all the traffic you can put as filter: all
72
+
73
+
polycubectl <service name> set filter=all
74
+
75
+
- default filter captures no packets (the eBPF datapath simply returns ok)
76
+
77
+
Filter can be viewed using the command **polycubectl mysniffer filter show**
78
+
Snaplen can be viewed using the command **polycubectl mysniffer snaplen show**
79
+
80
+
For further details of the implementation of the filter see :doc:`Packetcapture filter <packetcapture-filter>`
62
81
63
-
- source prefix
64
-
- destination prefix
65
-
- source port
66
-
- destination port
67
-
- later 4 protocol
82
+
For more details about the filters supported by libpcap (hence, the syntax allowed to specify filters) see `pcap-filter <https://linux.die.net/man/7/pcap-filter>`__
83
+
84
+
85
+
Examples of possible filters
86
+
----------------------------
68
87
69
-
Source prefix filter
70
-
^^^^^^^^^^^^^^^^^^^^
71
88
::
72
89
73
90
# Example of the source prefix filter
74
-
polycubectl mysniffer filters set src=10.10.10.10/24
91
+
polycubectl mysniffer set filter="ip src 10.0.2.11"
75
92
76
-
Destination prefix filter
77
-
^^^^^^^^^^^^^^^^^^^^^^^^^
78
93
::
79
-
80
-
# Example of the destination prefix filter
81
-
polycubectl mysniffer filters set dst=10.10.10.10/24
82
94
83
-
Source port filter
84
-
^^^^^^^^^^^^^^^^^^
85
-
::
86
-
87
95
# Example of the source port filter
88
-
polycubectl mysniffer filters set sport=80
96
+
polycubectl mysniffer set filter="src port 80"
89
97
90
-
Destination port filter
91
-
^^^^^^^^^^^^^^^^^^^^^^^
92
-
::
93
-
94
-
# Example of the destination port filter
95
-
polycubectl mysniffer filters set dport=80
96
98
97
-
Layer 4 protocol filter
98
-
^^^^^^^^^^^^^^^^^^^^^^^
99
99
::
100
100
101
101
# Example of the layer 4 protocol filter
102
-
polycubectl mysniffer filters set l4proto=tcp
102
+
polycubectl mysniffer set filter=tcp
103
103
104
-
Snaplen filter
105
-
^^^^^^^^^^^^^^
106
104
::
107
105
108
106
# Example of the snaplen filter
109
-
# In this case we capture only the first 80 bytes of each packet
110
-
polycubectl mysniffer filters set snaplen=80
107
+
# In this case we capture only the first 80 bytes of each packet
108
+
polycubectl mysniffer set snaplen=80
111
109
112
110
113
-
Filters can be viewed using the command **polycubectl mysniffer filters show**
114
-
115
111
Get the capture dump
116
112
--------------------
117
-
When the service is not set in *networkmode*, the dump is automatically written in a resilient way in the temporary user folder.
113
+
When the service is not set in *networkmode*, the dump is by default written in a resilient way in the temporary user folder.
114
+
The folder where the dump is written can be changed by using the syntax:
115
+
116
+
polycubectl <service name> set dump="<string value>"
117
+
118
+
::
119
+
120
+
# Example of new dump folder
121
+
polycubectl mysniffer set dump="/home/user_name/Desktop/capture"
122
+
123
+
At the end of the file name will be added the file extension ".pcap"
124
+
125
+
If a file with the same name already exists it will be overwritten otherwise it will be created
118
126
119
127
The path of the capture file can be shown using the command: **polycubectl mysniffer show dump**
120
128
121
129
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.
122
130
131
+
123
132
How to use the demo client
124
133
^^^^^^^^^^^^^^^^^^^^^^^^^^
125
134
::
@@ -137,3 +146,51 @@ Set network mode
137
146
138
147
# Start sniffer in local model
139
148
polycubectl mysniffer set networkmode=false
149
+
150
+
151
+
Implementation details
152
+
----------------------
153
+
The pipeline to convert into C code the filtering string entered in the packetcapture service is the following:
More in details, the first step is to obtain the cBPF (assembly) code from the filtering string, using the ``libpcap``/``tcpdump`` format. The filtering string is read from ``polycubed`` REST interface, then it is compiled in cBPF using the ``pcap_compile_nopcap()`` function that returns a ``bpf_program`` structure containing a list of ``bpf_insn``.
158
+
159
+
Then, the code creates a ``sock_fprog`` structure called ``cbpf`` that contains all the required filter blocks.
160
+
161
+
The second step (traslation from cBPF to C) starts with the validation of the cBPF code.
162
+
Function ``_cbpf_dump()`` is called for each filtering block and it returns a string containing the equivalent C code for that block.
163
+
164
+
Inside ``_cbpf_dump()``, a switch statement creates two variables, ``op`` (operation) and ``fmt`` (operand) depending on the type of instruction of the block (e.g.,return, load, store, alu op. etc.); the above variables will be used to generate the final C code.
165
+
166
+
This ASM-to-C traslator is ispired to a similar project proposed by `Cloudflare <https://blog.cloudflare.com/xdpcap/>`_; however, in Polycube the translator is written in C/C++ (the CLoudfare one is in Go); furthermore, in Polycube the final output of the translator is a C equivalent of the packet filter, while in the latest version of the Cloudfare project, the final outcome of the translation are eBPF assembly instructions.
167
+
168
+
The C output facilitates any further modification of the code, e.g., with when additional processing steps are needed, although it impacts on the overall filter conversion time as it requires one additional processing pass involving CLANG/LLVM to convert the C code into eBPF assembly.
169
+
170
+
171
+
Example of C code generated
172
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
173
+
As a example, we list here is the generated C code for the filter ``icmp``:
0 commit comments