.\" Hey, EMACS: -*- nroff -*- .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) .TH MAHIMAHI 1 "March 2015" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: .\" .nh disable hyphenation .\" .hy enable hyphenation .\" .ad l left justify .\" .ad b justify to both left and right margins .\" .nf disable filling .\" .fi enable filling .\" .br insert line break .\" .sp insert n+1 empty lines .\" for manpage-specific macros, see man(7) .SH NAME \fBmahimahi\fP \- lightweight, composable network-emulation tools link emulation: \fBmm-delay\fP, \fBmm-loss\fP, \fBmm-onoff\fP, \fBmm-link\fP analysis scripts: \fBmm-throughput-graph\fP, \fBmm-delay-graph\fP observation: \fBmm-meter\fP record and replay multi-origin websites: \fBmm-webrecord\fP, \fBmm-webreplay\fP .SH DESCRIPTION \fBmahimahi\fP 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. .SH LINK EMULATION TOOLS .SY mm-delay .I delay .RI [ command... ] .YS . .IP "" .RS Every packet is delayed by the specified .I delay (in milliseconds) entering and leaving the container. .RE .SY mm-loss uplink|downlink .I rate .RI [ command... ] .YS . .IP "" .RS Packets are lost at the given .I rate either when leaving (uplink) or entering (downlink) the container. .I rate is a number between 0 and 1. .RE .SY mm-onoff uplink|downlink .I mean-on-time .I mean-off-time .RI [ command... ] .YS . .IP "" .RS 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". .RE .SY mm-link .OP --uplink-log=\fIfilename\fR .OP --downlink-log=\fIfilename\fR .OP --meter-uplink .OP --meter-uplink-delay .OP --meter-downlink .OP --meter-downlink-delay .OP --once .I uplink-filename .I downlink-filename .RI [ command... ] .YS .SY mm-throughput-graph .SY mm-delay-graph .YS . .IP "" .RS Emulates a throughput-limited link with a specified packet-delivery schedule and analyzes the resulting performance. See .BR mm-link (1). .RE .SH OBSERVATION TOOLS .SY mm-meter .OP --meter-uplink .OP --meter-downlink .RI [ command... ] .YS . .IP "" .RS Displays an animated live plot of the transfer rate entering or leaving the container. .RE .SH RECORD AND REPLAY WEBSITES .SY mm-webrecord .I directory .RI [ command... ] .YS . .IP "" .RS Transparently proxies outgoing HTTP and HTTPS connections, saving the requests, corresponding responses, and IP address of each Web server contacted in the given \fIdirectory\fR. \fBmm-webrecord\fP 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 \fB--no-check-certificate\fP option to .BR wget (1) or the \fB--ignore-certificate-errors\fP option to .BR chromium-browser (1). .RE .SY mm-webreplay .I directory .RI [ command... ] .YS . .IP "" .RS Replays a saved session from a previous run of \fBmm-webrecord\fR. Unlike most mahimahi tools, the \fBmm-webreplay\fP 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. \fPmm-webreplay\fR runs an .BR 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 \fIdirectory\fR, the corresponding apache2 replies with the same reply as previously captured. \fBmm-webreplay\fP 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, \fBmm-webreplay\fP 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. .RE .SH 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. .SH EXAMPLES To spawn a shell with a delayed, lossy link to the Internet: .IP "" .RS .EX \fB$\fR mm-delay 50 mm-loss uplink 0.2 \fB[delay 50 ms] [loss up=0.1] $\fR .EE .RE To run ping over the same link: .IP "" .RS .EX \fB$\fR 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 .EE .RE To record a page load from \fIwww.nytimes.com\fR: .IP "" .RS .EX \fB$\fR mm\-webrecord /tmp/nytimes chromium-browser \-\-ignore\-certificate\-errors \-\-user\-data\-dir=/tmp/nonexistent$(date +%s%N) www.nytimes.com .EE The use of \fI\-\-user\-data\-dir=/tmp/nonexistent$(date +%s%N)\fR is to prevent the browser from reusing an existing chromium-browser process. .RE To make Chrome retrieve the saved website over a delayed, lossy link whose throughput is limited to 1 full-sized packet per millisecond: .IP "" .RS .EX \fB$\fR 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 .EE .RE To emulate a variable cellular network and visualize a process's use of the network: .IP "" .RS .EX \fB$\fR mm\-delay 20 mm\-link \-\-meter-all /usr/share/mahimahi/traces/Verizon-LTE-short.up /usr/share/mahimahi/traces/Verizon-LTE-short.down \fB[delay 20 ms] [link] $\fR .EE .SH SEE ALSO .BR mm-link (1) Project home page: .I http://mahimahi.mit.edu .br .SH AUTHOR Mahimahi was written by Ravi Netravali, Anirudh Sivaraman, Greg D. Hill, Deepak Narayanan, and Keith Winstein. .SH BUGS Please report bugs to \fImahimahi@mit.edu\fP.