man(1)

NAME
mptcpplot - Generate MPTCP connection-level time sequence graphs from a pcap.

SYNOPSIS
mptcpplot [-2] [-a] [-b] [-j] [ -l] [-t] [-r] pcap_filename

DESCRIPTION
mptcpplot is a tool for reading in a pcap file and creating time sequence graphs for all MPTCP connections contained in the pcap file pcap_filename. The time sequence graphs display data segments and data acknowledgments for an MPTCP connection by color-coding segments belonging to particular subflows. One time sequence graph is generated for each direction of every MPTCP connection in pcap_filename. For example, if there are N MP_CAPABLE handshakes in pcap_filename, then there will be 2N time sequence graphs generated. Each time sequence graph is in xplot format and can be viewed with the command: xplot.org time_sequence_graph_name.xpl MPTCP connections are tracked and output as long as their MP_CAPABLE handshake is captured in pcap_filename. Otherwise an MPTCP connection is ignored. This means that any MP_JOIN subflows carrying tokens that do not match a token generated by a previously seen key in pcap_filename will be ignored. Individual subflows that have been ignored may still be analyzed in a TCP-context with tools like tcptrace. The primary symbols contained in a time sequence graph are as follows:

Data segments
    Vertical lines with arrows at either end represent a segment of data at the MPTCP connection level. Each segment is drawn from the lowest data level sequence number to the highest data level sequence number a packet contains.

Data acknowledgments
    Boxes represent data acknowledgments sent on a particular subflow. Each box is plotted at the time the acknowledgment packet was received on the x-axis, and the y-axis is the data level sequence number the acknowledgment is for.

Green acknowledgment line
    The cumulative acknowledgment at the MPTCP connection level is tracked across all subflows for a particular connection, and the green acknowledgment line tracks this maximum over time. While duplicate acknowledgments containing MPTCP options do not carry the same meaning as duplicate acknowledgments in TCP, the presence of the line gives a quick visual reference to see if the sequence space is advancing or not.

Certain options may annotate time sequence graphs with extra pieces of information. Additional information about this can be found in the OPTIONS section of this man page. Each pair of time sequence graphs will have an associated MAPPING file. The MAPPING file will contain a 4-tuple per subflow and an associated color or TOKEN for each subflow. See the OPTIONS section for more information on TOKENS generated by the -t option.

EXAMPLES

mptcpplot pcap_filename
    Read in pcap_filename and create a pair of time sequence graphs for each MPTCP connection with a valid MP_CAPABLE handshake. The default behavior is to assign a unique color to each subflow for an MPTCP connection, but these are currently limited to 7 colors. After all of the colors are used, any additional subflows are displayed in white.

mptcpplot -2 pcap_filename
    Read in pcap_filename and create a pair of time sequence graphs for each MPTCP connection with a valid MP_CAPABLE handshake. Colors in this plot are based on IP address pairs rather than 4-tuples. See the -2 flag in the OPTIONS section for more information.

mptcpplot -t pcap_filename
    Read in pcap_filename and create a pair of time sequence graphs for each MPTCP connection with a valid MP_CAPABLE handshake. Rather than using colors, each subflow will be assigned a TOKEN value. These values can then be post-processed and replaced with any valid xplot color that a user wants. More information on the -t option can be found in the OPTIONS section.

mptcpplot -r pcap_filename
    Read in pcap_filename and create a pair of time sequence graphs for each MPTCP connection with a valid MP_CAPABLE handshake. This command uses the default coloring scheme and will display sequence numbers relative to the initial MPTCP connection level sequence number on the y-axis.

mptcpplot -a -j pcap_filename
    Read in pcap_filename and create a pair of time sequence graphs for each MPTCP connection with a valid MP_CAPABLE handshake. This command uses the default coloring scheme and will include additional markings for any ADD_ADDRESS options, REMOVE_ADDRESS options, or MP_JOIN packets for a particular connection.

mptcpplot -l pcap_filename
    Read in pcap_filename and create a pair of time sequence graphs for each MPTCP connection with a valid MP_CAPABLE handshake. Additionally, output some extra information for each connection.

mptcpplot -b pcap_filename
    Read in pcap_filename and create a pair of time sequence graphs for each MPTCP connection with a valid MP_CAPABLE handshake. Additionally, output some basic information for each connection.

POSITIONAL ARGUMENTS

  Required arguments

pcap_filename
    mptcpplot will read packets from pcap_filename and generate time sequence plots and mapping files for the MPTCP connections in the file. Exactly one file must be passed as an argument to mptcpplot.

OPTIONS

  General options

-2  Generate colors and mapping based on pairs of IP addresses for each subflow rather than using the 4-tuple of each subflow.

-a  Add tick marks and labels for packets containing ADD_ADDRESS and REMOVE_ADDRESS information.

-b  Output basic information about each MPTCP connection in the given file. Displays keys and tokens generated from the MP_CAPABLE handshake of each subflow and the 4-tuple of the initial subflow for a connection.

-h  Print out a help dialogue and exit.

-j  Add tick marks and labels for packets containing the MP_JOIN option.

-l  Output the information contained in the -b option, but also include additional information about connection level sequence numbers, the number of subflows for a connection, and the duration of a connection.

-r  Output relative connection level sequence numbers for the y-axis of each time sequence graph.

-t  Output TOKEN values rather than colors in the xplot files and MAPPING files. These TOKENs can be post processed and replaced with any color a user wants. This is useful for implementing custom coloring rules. For example, a user may wish to color all subflows containing the address 1.1.1.1 as red and all of the subflows containing address 2.2.2.2 as blue. This could be done by looking up which subflow tokens match these patterns in the MAPPING file and then replacing the proper tokens in the xplot files.

LIMITATIONS
mptcpplot is still under development and may not work under certain conditions due to incomplete code. Known limitations include:

No IPv6 support
    Currently only IPv4 is supported. IPv6 support is planned for future releases.

Little-Endian Only
    mptcpplot has only been developed and tested on little-endian machines. Certain code (like bitfields) may need to be reworked to support big-endian machines.

No control over output file
    I plan to add an option that allows a user to specify an output file pattern. Another limitation I should spend several minutes on to fix in the near future. :-)

Sequence number wrapping not handled
    Connections sending more than 2^32 bytes will not be tracked properly. Further, xplot is unable to display full 64-bit sequence numbers, so the 32-bit numbers are used when generating xplot files. This means that connections sending a large amount of data may generate nonsensical plots or textual output.

SEE ALSO
mptcpsplit(1) mptcpcrunch(1) tcptrace(1)

AUTHOR
Matt Sargent