Monarch: A tool for emulating TCP flows over the Internet

Overview | Usage | Downloads | FAQ | Data sets | Papers | People | Contact | Legal notice and imprint


What is Monarch?

Monarch is a tool that accurately emulates transport protocol flows from an end host under the experimenter's control to any other end host that responds to simple TCP, UDP or ICMP packet probes. Since many Internet hosts and routers respond to such probes, Monarch can evaluate transport protocols such as TCP Vegas, TCP Nice, and PCP over a large and diverse set of Internet paths.

What is Monarch good for?

Monarch can be used to evaluate new transport protocols. Ideally, these protocols would be evaluated on a large and diverse set of real Internet hosts. In practice, this is often not possible; instead, researchers have to rely on testbeds such as PlanetLab, which are small and fairly homogeneous. Monarch simplifies this problem. Researchers now need to control only one endpoint of the flows and can pick the other endpoint from a huge set of Internet hosts. Thus, it becomes possible to evaluate protocols in a setting that is more realistic and several orders of magnitude larger.

Monarch can also be used for measurement studies. For example, it is now much easier to study emerging access networks such as broadband and cellular networks because it is no longer necessary to recruit a large number of users in these networks. Finally, Monarch can be used to test new and existing implementations of transport protocols over a variety of Internet links. The more link types a protocol is tested on, the more likely it is that bugs can be discovered and fixed.

How is Monarch used?

If a kernel-level implementation of the new protocol is available, you can run Monarch directly. If the protocol is implemented in the ns2 simulator, you can use a small
tool to connect Monarch to the simulator, which allows you to use the same code both for simulations and for evaluation over the Internet. Finally, there is an interface that allows protocols to interact with Monarch directly. If you plan to use this option, please contact us for more information.


Latest Monarch source code (v0.9.12):
Tool for using Monarch with ns-2: [tgz]

Data sets

We have used Monarch to measure TCP performance to several large groups of Internet hosts. So far, we have collected the following data sets:
The data format is described here. If you have questions about any of these data sets, please send e-mail to the contact address provided below.


To invoke Monarch, run
    monarch [-m mode] [-o packetTraceFile] [-k kernelTraceFile] [-M pathMTU]
            [-z transferSizeKB] [-b bufferSizeKB] [-i interface]
            [-t traceType] [-c captureMethod] [-p probeType] host:port
The following command-line options are always available:
-m mode
  Specifies how Monarch should operate. In flow mode, Monarch emulates a TCP flow, whose size can be controlled with the -z option. In standalone mode, Monarch captures packets sent and received by another application. The default is flow.
-p probeType
Specifies the packet type Monarch should use as probes. Currently supported are: tcp-ack, udp-data, icmp-echo and icmp-timestamp. Not all hosts respond to all probe types.
-o traceFile
Tells Monarch to write a packet trace to the specified file. The type of output can be controlled with the -t option.
-t traceType
Selects one of two trace formats: mout, Monarch's own packet trace format, and pcap, a standard format that can be read by standard tools such as tcpdump. The default is mout.
-c captureMethod
If the netfilter method is selected, Monarch uses libipq and the Linux kernel's Netfilter framework to capture packets. The tun method uses the TUN/TAP framework instead, and the planetlab method is for use with PlanetLab slices. Note that not all probe types are available with all capture methods.
-M pathMTU
If this option is used, Monarch will patch the MSS option in TCP packets and thus force the flow to use the specified MTU. The default is 1500 bytes.
-i interface
Specifies the network interface for sending probes and receiving responses.
The following command-line options are only available when Monarch is run in flow mode, i.e. when it internally emulates a TCP flow:
-k traceFile
  Tells Monarch to write traces of certain TCP variables, such as congestion window and slowstart threshold, to the specified file. Monarch produces two traces, one for the TCP sender and one for the TCP receiver.
-z sizeKB       
Specifies the length of the emulated TCP flow.
-b sizeKB
Tells Monarch to explicitly set the size of the kernel's send and receive buffers to the specified value, using the SO_SNDBUF and SO_RCVBUF socket options. If the option is not specified, Monarch uses the kernel's default values.
Note that Monarch must be run as root, so it can access the Netfilter and the TUN devices.



If you are interested in learning more about Monarch, or in case of any questions that are not answered in the
Monarch FAQ, email us at:


Andreas Haeberlen
Marcel Dischinger
Prateek Singhal
Krishna P. Gummadi
Stefan Saroiu

Imprint | Data Protection