mptcpanalyzer

Documentation (latest)
Documentation (stable)
License
Build Status
PyPI
DOI

• Presentation
• Installation
• Help
• Related tools

Presentation

Mptcpanalyzer is a python tool conceived to help with MPTCP pcap analysis (as mptcptrace for instance).

It accepts as input a capture file (.pcap or .pcapng) and from there generates a CSV file (thanks to tshark, the terminal version of wireshark) with the MPTCP fields required for analysis. From there you can:

• list MPTCP connections
• compute statistics on a specific MPTCP connection (list of subflows, reinjections, subflow actual contributions...) It accepts as input a capture file (*.pcap) and depending on from there can :
• export a CSV file with MPTCP fields
• plot one way delays
• ...

Most commands are self documented and/or with autocompletion.

Then you have an interpreter with autocompletion that can generate & display plots such as the following:

You can reference mptcpanalyzer via the following Digital Object Identifier:

Table of Contents

Installation

You will need a wireshark version >= 3.0.0

Once wireshark is installed you can install mptcpanalyzer via pip: $ python3 -mpip install mptcpanalyzer --user

python 3.7 is mandatory since we rely on its type hinting features. Dependancies are (some will be made optional in the future):

• stevedore to manage plugins
• the data analysis library pandas
• lnumexpr to run specific queries in pandas
• matplotlib to plot graphs
• cmd2 to generate the command line

Run the checkhealth command in case of problems.

How to use ?

mptcpanalyzer can run into 3 modes:

• interactive mode (default): an interpreter with some basic completion will accept your commands. There is also some help embedded.
• if a filename is passed as argument, it will load commands from this file
• otherwise, it will consider the unknow arguments as one command, the same that could be used interactively

For example, we can load an mptcp pcap (I made one available on wireshark wiki or in this repository, in the examples folder).

Run $ mptcpanalyzer --load examples/iperf-mptcp-0-0.pcap. The script will try to generate a csv file, it can take a few minutes depending on the computer/pcap until the prompt shows up. Type ? to list available commands (and their aliases). You have for instance:

• lc (list connections)
• ls (list subflows)
• plot
• ...

help ls will return the syntax of the command, i.e. ls [mptcp.stream] where mptcp.stream is one of the number appearing in lc output.

Look at Examples

Examples

Head to the Wiki for more examples.

Plot One Way Delays from a connection: plot owd tcp examples/client_2_filtered.pcapng 0 examples/server_2_filtered.pcapng 0 --display

Plot tcp sequence numbers in both directions: plot tcp_attr -h

Get a summary of an mptcp connection

> load_pcap examples/server_2_filtered.pcapng
> mptcp_summary 0

Map tcp.stream between server and client pcaps:

>map_tcp_connection examples/client_1_tcp_only.pcap examples/server_1_tcp_only.pcap  0
TODO
>print_owds examples/client_1_tcp_only.pcap examples/server_1_tcp_only.pcap 0 0

Map tcp.stream between server and client pcaps:

> map_mptcp_connection examples/client_2_filtered.pcapng examples/client_2_filtered.pcapng 0
2 mapping(s) found
0 <-> 0.0 with score=inf  <-- should be a correct match
-tcp.stream 0: 10.0.0.1:33782  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 0: 10.0.0.1:33782  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=inf
-tcp.stream 2: 10.0.0.1:54595  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 2: 10.0.0.1:54595  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=inf
-tcp.stream 4: 11.0.0.1:59555  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 4: 11.0.0.1:59555  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=inf
-tcp.stream 6: 11.0.0.1:35589  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 6: 11.0.0.1:35589  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=inf
0 <-> 1.0 with score=0
-tcp.stream 0: 10.0.0.1:33782  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 1: 10.0.0.1:33784  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=30
-tcp.stream 2: 10.0.0.1:54595  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 3: 10.0.0.1:57491  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=30
-tcp.stream 4: 11.0.0.1:59555  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 5: 11.0.0.1:50077  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=30
-tcp.stream 6: 11.0.0.1:35589  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 7: 11.0.0.1:50007  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=30

FAQ

Moved to the Wiki

How to contribute

PRs welcome ! See the doc.

Related tools

Similar software:

Tool	Description
mptcptrace	C based: an example
mptcpplot	C based developed at NASA: generated output example