.\"                                      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 mm-link 1 "February 2014"
.\" 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 <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
mm-link - UNIX shell connected to an emulated link with a user-specified packet-delivery schedule.
.SH SYNOPSIS
.B mm-link
\fIuplink\fP
\fIdownlink\fP
[\-\- command...]
.br
.SH DESCRIPTION
mm-link is a network emulation tool that emulates links using packet delivery
trace files (\fIuplink\fP for the uplink direction and \fIdownlink\fP for the downlink direction) provided on the command
line. mm-link uses \fBclone\fP(2) to fork a new shell in a distinct network
namespace.  uplink_trace_file emulates the link from mm-link to the Internet
and downlink_trace_file emulates the link from the Internet to mm-link.

mm-link can emulate both time-varying links, such as cellular links, and
links with fixed link speeds. When a packet arrives at the link (from either
the Internent or from mm-link), it is directly placed into one of two packet
queues depending on its intended direction: the uplink queue or the downlink
queue.  mm-link releases packets from each queue based on the corresponding
input packet-delivery trace. 

Each line in the trace  represents a packet delivery opportunity: the time at
which an MTU-sized packet can be delivered in the emulation. Accounting is done
at the byte-level, and each delivery opportunity represents the ability to
deliver 1500 bytes. Thus, a single line in the trace file can delivery several
smaller packets whose sizes sum to 1500 bytes. Delivery opportunities are
wasted if bytes are unavailable at the instant of an opportunity. When
mm-link reaches the end of an input trace file, it wraps around to the
beginning of the trace file. mm-link can be nested within delayshell (1) to
flexibly create links with a user-supplied one-way delay and a user-supplied
link rate.

To exit mm-link, simply type "exit" or CTRL-D inside mm-link.

.SH EXAMPLE

.nf
To emulate a 12 Mbit/s link (in each direction), make a 12 Mbit/s
tracefile, "12Mbps_trace". This file can be of arbitrary length
and must follow the pattern below:
0
1
2
3
4
5...
The link above delivers an MTU-sized packet (1500 bytes or 12000 bits) every
ms.

Run mm-link with:
$ mm-link 12Mbps_trace 12Mbps_trace

All programs run from within mm-link are sent according 
to the packet delivery times specified in 12Mbps_trace.

mm-link
[...] (copyright notice omitted)

.fi

.SH SEE ALSO
.BR mahimahi (1),
.BR mm-delay (1),
.BR mm-webrecord (1),
.BR mm-webreplay (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.