DESCRIPTION
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
delay [command...]
-
- Every packet is delayed by the specified delay (in milliseconds) entering and leaving the container.
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).
-
OBSERVATION TOOLS
[ --meter-uplink ] [ --meter-downlink ] [command...]
-
-
Displays an animated live plot of the transfer rate entering or leaving the container.
-
RECORD AND REPLAY WEBSITES
directory [command...]
-
-
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).
directory [command...]
-
-
-
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.
-
ENVIRONMENT
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.
EXAMPLES
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-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
-
-
$ 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-webrecord /tmp/nytimes chromium-browser --ignore-certificate-errors --user-data-dir=/tmp/nonexistent$(date +%s%N) www.nytimes.com
-
- $ 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] $
-
$ 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] $