Packetdrill for testing TCP and UDP
===================================

Summary
=======
This is a port of Google's Packetdrill testing tool into the INET Framework.

Google released the script-based Packetdrill tool in 2013. It allows one
to test transport protocols like UDP and TCP on Linux and BSD-based
operating systems. Scripts define test cases that inject packets to the
protocol implementation under test, perform operations using the API
controlling the transport protocol, and verify the sending of packets, all
at specified times. The ported version provides a simple and powerful
method of testing transport protocols implemented in INET.

Current tests for UDP and TCP
=============================
For packetdrill based tests for the current UDP and TCP implementation
see the 'tests/packetdrill' directory.

Usage
=====
As the scripts are embedded in the INET test suite, their specification 
follows the same rules as other module tests. The packetdrill tests always 
consist of a script, a .ned file, a routing file and a configuration file 
like the following:

%description:
SUT is server. It accepts a connection.
The peer closes the connection.
%#----------------------------------------------
%inifile: omnetpp.ini
[General]
network = PacketDrillTcp
**.scriptFile="../../lib/openPassive.pkt"
**.pdhost.numTcpTunApps = 1
**.hasTun = true
**.startTime = 2s
**.pdhost.routingFile = "../../lib/pdhost.mrt"
**.pdhost.numPcapRecorders=1
**.pdhost.pcapRecorder[0].pcapFile="openPassive.pcap"
**.pdhost.pcapRecorder[0].moduleNamePatterns="tun"
**.pdhost.pcapRecorder[0].sendingSignalNames="packetSentToUpper"
**.pdhost.pcapRecorder[0].receivingSignalNames="packetReceivedFromUpper"
**.pdapp.dataTransferMode = "bytecount"
**.tcp.mss = 1460
**.tcp.sackSupport = true
**.tcp.windowScalingSupport = true
**.tcp.windowScalingFactor = 6
**.tcp.advertisedWindow = 29200
**.tcp.useDataNotification = true
%#----------------------------------------------
%not-contains: test.out
Packetdrill error:
%#----------------------------------------------

Packetdrill script example
==========================
Packetdril scripts use a very compact notation to describe the expected
protocol behavior. For more information please check the original packetdrill paper:
https://0b4af6cdc2f0c5998459-c0245c5c937c5dedcca3f1764ecc9b2f.ssl.cf2.rackcdn.com/11758-atc13-cardwell.pdf

Here is a packetdrill script for TCP fast retransmit:

0 socket(..., SOCK_STREAM, IPPROTO_TCP) = 3                    // Create a socket.
+0 setsockopt(3, SOL_SOCKET, SO_REUSEADDR, [1], 4) = 0         // Avoid binding issues.
+0 bind(3, ..., ...) = 0                                       // Bind the socket.
+0 listen(3, 1) = 0                                            // Start listening.
+0 < S 0:0(0) win 32792 <mss 1000,sackOK,nop,nop,nop,wscale 7> // Inject a SYN.
+0 > S. 0:0(0) ack 1 <...>                                     // Expect a SYN/ACK.
+.1 < . 1:1(0) ack 1 win 257                                   // Inject an ACK.
+0 accept(3, ..., ...) = 4                                     // Accept connection.
+0 write(4, ..., 1000) = 1000                                  // Write 1 MSS of data.
+0 > P. 1:1001(1000) ack 1                                     // Expect it to be sent immediately.
+.1 < . 1:1(0) ack 1001 win 257                                // Inject an ACK after 100ms.
+0 write(4, ..., 4000) = 4000                                  // Write 4 MSS of data.
+0 > . 1001:2001(1000) ack 1                                   // Expect immediate transmission.
+0 > . 2001:3001(1000) ack 1
+0 > . 3001:4001(1000) ack 1
+0 > P. 4001:5001(1000) ack 1
+.1 < . 1:1(0) ack 1001 win 257 <sack 2001:3001,nop,nop>       // Inject 3 ACKs with SACKs.
+0 < . 1:1(0) ack 1001 win 257 <sack 2001:4001,nop,nop>
+0 < . 1:1(0) ack 1001 win 257 <sack 2001:5001,nop,nop>
+0 > . 1001:2001(1000) ack 1                                   // Expect a fast retransmit.
+.1 < . 1:1(0) ack 6001 win 257                                // Inject an ACK for all data.

Limitations
===========
- Remote mode is unsupported
- Python snippets, shell code and command line arguments are unsupported
- Blocking system calls are unsupported
- The getsockopt() method is unsupported
- Explicit address handling is unsupported
- IPv6 is unsupported

Credits
=======
Packetdrill has been contributed by Irene Rungeler and Michael Tuexen at
FH Muenster. Packetdrill has been presented at the 2nd OMNeT++ Community
Summit in September 2015; find the paper (http://arxiv.org/pdf/1509.03127.pdf)
and presentation slides at http://summit.omnetpp.org.
