|MAHIMAHI(1)||General Commands Manual||MAHIMAHI(1)|
mahimahi - lightweight, composable network-emulation tools
link emulation: mm-delay, mm-loss, mm-onoff, mm-link
analysis scripts: mm-throughput-graph, mm-delay-graph
record and replay multi-origin websites: mm-webrecord, mm-webreplay
mahimahi is a suite of user-space tools for network emulation and analysis.
Each mahimahi tool spawns a lightweight container, generally connected to the outside via a synthetic network device that observes packets in transit or emulates a desired behavior.
The tools are composable so that a series of emulated network effects can be chained together, with mahimahi containers nested inside each other. Each tool takes an optional command to execute, so it is possible to create a series of nested containers with one command line.
LINK EMULATION TOOLS¶
||uplink|downlink rate [command...]|
Packets are lost at the given rate either when leaving (uplink) or entering (downlink) the container. rate is a number between 0 and 1.
||uplink|downlink mean-on-time mean-off-time [command...]|
The uplink or downlink will be intermittent and will switch between connected and disconnected states according to a Poisson point process with specified average durations spent "on" and "off".
||[--uplink-log=filename] [--downlink-log=filename] [--meter-uplink] [--meter-uplink-delay] [--meter-downlink] [--meter-downlink-delay] [--once] uplink-filename downlink-filename [command...]|
Emulates a throughput-limited link with a specified packet-delivery schedule and analyzes the resulting performance. See mm-link(1).
||[--meter-uplink] [--meter-downlink] [command...]|
Displays an animated live plot of the transfer rate entering or leaving the container.
RECORD AND REPLAY WEBSITES¶
Transparently proxies outgoing HTTP and HTTPS connections, saving the requests, corresponding responses, and IP address of each Web server contacted in the given directory. mm-webrecord uses a self-signed TLS certificate in its HTTPS proxy, causing typical Web browsers to reject it. For testing or debugging purposes, this behavior can usually be turned off, e.g.: with the --no-check-certificate option to wget(1) or the --ignore-certificate-errors option to chromium-browser(1).
Replays a saved session from a previous run of mm-webrecord. Unlike most mahimahi tools, the mm-webreplay container does not have a network connection to the outside world. Instead, it has dummy network interfaces bound to each IP address on which a Web server in the saved session had answered a request. mm-webreplay runs an apache2(8) Web server bound to each such IP address inside the container. Each Web server emulates the corresponding server from the saved session. When receiving a request that matches one in the directory, the corresponding apache2 replies with the same reply as previously captured.
mm-webreplay can be used to measure the performance of Web browsers on complex websites and the effect of changes in Web protocols (e.g. HTTP, HTTP/2, SPDY, QUIC). Unlike tools like web-page-replay, mm-webreplay preserves the sharded structure of a website, binds to the actual IP addresses that the real website used, and serves requests from real Web servers.
The MAHIMAHI_BASE environment variable is set to an IP address of the host, outside any container. This can be used to conduct scripted measurements over a series of mahimahi containers chained together.
To spawn a shell with a delayed, lossy link to the Internet:
$ mm-delay 50 mm-loss uplink 0.2 [delay 50 ms] [loss up=0.1] $
To run ping over the same link:
$ mm-delay 50 mm-loss uplink 0.2 sh -c 'ping -c 10 -n $MAHIMAHI_BASE' PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. 64 bytes from 100.64.0.1: icmp_seq=1 ttl=63 time=101 ms 64 bytes from 100.64.0.1: icmp_seq=2 ttl=63 time=100 ms 64 bytes from 100.64.0.1: icmp_seq=4 ttl=63 time=101 ms 64 bytes from 100.64.0.1: icmp_seq=5 ttl=63 time=100 ms 64 bytes from 100.64.0.1: icmp_seq=7 ttl=63 time=101 ms 64 bytes from 100.64.0.1: icmp_seq=8 ttl=63 time=101 ms 64 bytes from 100.64.0.1: icmp_seq=9 ttl=63 time=101 ms 64 bytes from 100.64.0.1: icmp_seq=10 ttl=63 time=101 ms --- 100.64.0.1 ping statistics --- 10 packets transmitted, 8 received, 20% packet loss, time 8999ms rtt min/avg/max/mdev = 100.910/101.009/101.092/0.279 ms
To record a page load from www.nytimes.com:
$ mm-webrecord /tmp/nytimes chromium-browser --ignore-certificate-errors --user-data-dir=/tmp/nonexistent$(date +%s%N) www.nytimes.com
The use of --user-data-dir=/tmp/nonexistent$(date +%s%N) is to prevent the browser from reusing an existing chromium-browser process.
To make Chrome retrieve the saved website over a delayed, lossy link whose throughput is limited to 1 full-sized packet per millisecond:
$ mm-webreplay /tmp/nytimes mm-delay 50 mm-loss uplink 0.1 mm-link <(echo 1) <(echo 1) -- chromium-browser --ignore-certificate-errors --user-data-dir=/tmp/nonexistent$(date +%s%N) www.nytimes.com
To emulate a variable cellular network and visualize a process's use of the network:
$ mm-delay 20 mm-link --meter-all /usr/share/mahimahi/traces/Verizon-LTE-short.up /usr/share/mahimahi/traces/Verizon-LTE-short.down [delay 20 ms] [link] $
Project home page: http://mahimahi.mit.edu
Mahimahi was written by Ravi Netravali, Anirudh Sivaraman, Greg D. Hill, Deepak Narayanan, and Keith Winstein.
Please report bugs to firstname.lastname@example.org.