Provided by: mahimahi_0.98-1.1build2_amd64 bug

NAME

       mahimahi - lightweight, composable network-emulation tools

       link emulation: mm-delay, mm-loss, mm-onoff, mm-link

       analysis scripts: mm-throughput-graph, mm-delay-graph

       observation: mm-meter

       record and replay multi-origin websites: mm-webrecord, mm-webreplay

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

       mm-delay delay [command...]

                Every packet is delayed by the specified delay  (in  milliseconds)  entering  and
                leaving the container.

       mm-loss 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.

       mm-onoff 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".

       mm-link [--uplink-log=filename] [--downlink-log=filename] [--meter-uplink] [--meter-
               uplink-delay] [--meter-downlink] [--meter-downlink-delay] [--once] uplink-filename
               downlink-filename [command...]

       mm-throughput-graph
       mm-delay-graph

                      Emulates  a  throughput-limited  link  with  a  specified   packet-delivery
                      schedule and analyzes the resulting performance. See mm-link(1).

OBSERVATION TOOLS

       mm-meter [--meter-uplink] [--meter-downlink] [command...]

                Displays  an  animated  live  plot  of  the transfer rate entering or leaving the
                container.

RECORD AND REPLAY WEBSITES

       mm-webrecord 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).

       mm-webreplay 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-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] $

SEE ALSO

       mm-link(1)

       Project home page: http://mahimahi.mit.edu

AUTHOR

       Mahimahi was written by Ravi Netravali, Anirudh Sivaraman, Greg D. Hill, Deepak Narayanan,
       and Keith Winstein.

BUGS

       Please report bugs to mahimahi@mit.edu.

                                            March 2015                                MAHIMAHI(1)