Mini Maxwell is web based; except for initial configuration all operations are performed through a standard W3C standards-compliant web browser.

The user works with “ports”, “filters”, and “bands”.

Ports are physical interfaces on the Mini Max hardware.  There is “Port0” and “Port1”.

Bands are collections of traffic.

Impairments are applied to bands.  Each band may have a different set of impairments.

Filters are patterns that are applied to incoming packets for the purpose of classifying each packet and assigning it to a band.  Any traffic that is not classified is automatically placed into Band #5 in the appropriate direction.

This will be made more clear in the configuration example, below.

Ports

There are three Ethernet interfaces on the Mini Maxwell hardware.

One of these is used for control purposes.  This interface (“eth0”), and the packets arriving on and leaving from it, are not subject to the impairment system.

The other two are used to receive the packets to be impaired and to transmit them.

These two ports are called “Port0” and “Port1”.

Port0 is the Linux interface “eth1” and Port1 is the Linux interface “eth2”.

These ports are electrically and logically identical.

Mini Maxwell connects these ports together in bridging mode.  This means that packets that arrive on Port0 are relayed through netem and transmitted out of Port1.  And packets that arrive on Port1 are relayed through netem and transmitted out of Port0.

The bridging function is a normal IEEE 802 bridge, which means that it tracks MAC addresses and bridges only those packets that need to be bridged.  This is in alignment with user expectations and is consistent with the operation of most Ethernet switches.

The MAC addresses of these interfaces is not inserted into packets.  Rather, the original MAC address is preserved.

“Uphill” and “Downhill”

The terms “uphill” and “downhill” are used to describe the direction of packets flowing through Mini Maxwell.

“Uphill” means packets that arrive on Port0 and leave via Port1.

“Downhill” means packets that arrive by Port1 and leave by Port0.

You can remember which direction is which by remembering that “Port1” is a higher number than “Port0”. Packets that flow from the low number port (“Port0”) to the high number port (“Port1)” are flowing uphill, while those that go from the high port (“Port1”) to the low port (“Port0”) are moving downhill.

Bands

When a packet arrives on a port it is run past the filters and, based on those filters, is classified into one of five different bands.

Bands are uni-directional.  This means that a that carries traffic from Port0 to Port1 is different from a band that carries traffic in the reverse direction.

A band is thus a conceptual way of grouping together all the packets that match certain filters and that are all going in the same direction.

There are five bands for each direction.

The last band, Band #5, is the default band for packets that are not otherwise classified by the filters.

It is good practice to use Band #5 as a kind of catch-all for traffic that the user most likely does not want to impair, most particularly ARP and DHCP.

Filters

Filters are patterns that are applied to packets.

Only IPv4 packets may be filtered, all non IPv4 packets are automatically sent into Band #5.

Filters can be used to examine IPv4 header fields as well as UDP and TCP headers.

Mini Maxwell does not use the filter shortcuts supported by the IProute2 “tc” command.  The reason for this is that those shortcuts do not work in the presence of IP options.

Instead, Mini Maxwell uses the fully expanded “u32” filter representation provided by IProute2 and the “tc” command.

Mini Maxwell arranges filters so that the “nexthdr+” mechanism does work to allow the inspection of UDP an d TCP headers even if IP options are present in a packet.

Mini Maxwell provides a set of pre-written filters.  The user may use these directly or may use them as a base for user-written filters.

Mini Maxwell allows up to three “match” expressions per filter.

Mini Maxwell allows the user to assign a name and description to each filter.

Filter Map

Mini Maxwell maintains two filter maps: one map for each of the two directions that packets may flow through Mini Maxwell.

Think of each filter map as a kind of switchboard that plugs filters into bands.

Each filter map is a list of the available filters.

And for each filter the user may designate which band, if any, into which the filter should direct those packets that match the filter's criteria.

The figure below shows a typical filter mapping.  In this mapping the tcp filter is sending its packets into Band #3, the udp filter is sending its packets into Band #4, and the udp_dst_port_sip and udp_src_port_sip filters are sending their packets into Band #1.  The maps for uphill and downhill are the same, but that is not necessary.

Filter Sequence

When a packet arrives it is checked against the active filters (as determined from the Filter Map for the direction in which the packet is moving.)

The sequence of in which these filters are examined is often important.

For example, a typical configuration may want to send all UDP encapsulated Domain Name System (DNS) packets into Band #1 while sending all other UDP packets into Band #2.

In that configuration it is important that the filter that selects for “DNS-in-UDP” is checked before the filter that selects for “any UDP”.  Otherwise all of the DNS packets, because they are UDP packets, would be swept in with all of the other UDP packets.

In the figure below we see that in both the uphill and downhill directions the first filter will be tcp, then udp, udp_dst_port_sip, udp_src_port_sip, and finally voip_256_qos_ignore.

This sequence contains a configuration error – since the udp filter will be checked before the sip and voip filters, those latter filters will never see a packet.

To avoid this problem the sequence should be changed to be:

Note that the voip_256_qos_ignore filter is placed after the udp_dst_port_sip and udp_src_port_sip filters. This is necessary because the voip_256_qos_ignore filter is defined in such a way that it could sweep-in packets with the SIP ports if they matched the size and QoS criteria of the filter.

In Mini Maxwell, there is a Filter Sequence for each of the two directions that packets may flow through Mini Maxwell.

(Only those filters that are active in the Filter Map are shown in the Filter Sequence.)

Mini Maxwell gives the user a graphical means of putting the filters into any desired order.

Impairments

The following figure shows the impairment settings for pair of bands.

Each of these fields is described in the following sections.

Notice that there are five pairs of Bands.

A Note on “Correlation”

Netem uses a mechanism called “correlation” to emulate burst behavior.

Inside netem each probability based event – such as the decision whether to drop, duplicate, or reorder a packet – is based on a random number calculation.  That random number is compared with the user designated probability for that particular event.  The even is triggered or not based on the result of that comparison.

When netem is calculating a delay, it can also make use of a random number.  Netem uses this number to increase or decrease the basic delay amount.

These random number calculations can either be independent of any other random number calculation or, if correlation is active for a particular kind of event, the result of the new random number calculation can be made partially dependent on the calculations that preceded it for the same kind of event.

(Not only is a correlation-based random number calculation based on earlier calculations for the same kind of event, they are also based only on same-kind events withing the same Band.  Thus, for example, a burst on Band#3/uphill is independent of whether a burst is occurring on Band #2/downhill.)

With correlation the calculation for a new random number is as follows, with “Rand()” being a more basic random number generator that returns a value uniformly distributed such that 0 <= value < 1.0.

Random_n = (Random_n-1 * Correlation/100) + (Rand() * ( 1 – Correlation/100))

A correlation value of zero means that every event is independent – there is no burst behaviour.

A correlation value of 100 means that the very first random value is preserved forever – the entire impairment system becomes static, locked into its initial choice.

Intermediate correlation values with higher values (but less than 100) tend to create longer periods in which an event is either occurring or not occurring; bursts, once they start, will tend to be longer lived.

Intermediate correlation values with lower values (but more than 0) tend to allow greater, but not complete, independence between one event and the next.

Delay

Delay is composed of the following components:

• Amount – (Milliseconds)  This is the basic measure of delay.  The actual amount of delay is derived from this basic value through the action of the other components.
  
  The value for this should be between 0 and 1000 milliseconds.  Higher values are possible, but it appears that netem starts to transform delay into packet loss as delay values move above 1000 milliseconds.  This has been partially redressed in Mini Maxwell by a substantial increase in the memory queue resources made available to netem.

• Variation – (Milliseconds)  This is an amount (in milliseconds) that characterizes the range over which the basic amount may be varied.  This amount is not the actual amount that will be applied, that number will be generated based on the Variation, Correlation, and Distribution parameters.
  
  If the variation value is zero, then the basic delay given by Amount is used without any variation – all of the other delay components are ignored.
  
  If the variation is not zero then a random value is selected, based on the “Distribution” and “Correlation” parameters, and shaped using this variation as a standard deviation.  The result will be used to increase or decrease the basic delay given by Amount.

• Correlation – (Percentage)  See the section on Correlation, above.

• Distribution – This describes the shape of the curve that will be formed if a large number of delays were graphed.

• None – The variation value is uniformly distributed between 0 and “Variation”

• Normal – A bell curve centered on “Amount” with a standard deviation of “Variation”

• Pareto – An 80/20 curve.

• Paretonormal – A curve composed of 25% normal and.75% pareto.

Reordering By Delay

Packets are reordered as a side effect of adding delay: If an earlier packet is delayed it may be passed by subsequent packets that receive less delay.

If the delay being imposed (as described in the section “Delay” above) is less than the inter-packet spacing then the reordering mechanisms here are unlikely to have any effect.  Thus, for VOIP packets which tend to come along every 20 milliseconds, the delay imposed should be at least 20 milliseconds, otherwise there will be no delayed packet waiting inside Mini Maxwell that a subsequent packet could pass and thus cause reordering.

Reordering is composed of the following components:

• Reorder Gap – This value (“N”) determines which packets, if any, will be sent through without delay of any kind.
  
  If zero this parameter has no effect.
  
  If not zero, then every N^th packet will be sent through without delay.  A value of 1 means that every-other packet will be sent without delay, a value of 2 means that every third packet will be sent without delay.

• Amount – (Percentage)  This value indicates that a certain percentage of the packets are to be selected and sent along without delay.  This selection is based on a random number and is affected by the Correlation value, below.

• Correlation – (Percentage)  See the section on Correlation, above.

Drop

Drop is composed of the following components:

• Amount – (Percentage)  This value indicates that a certain percentage of the packets are to be selected and dropped.  This selection is based on a random number and is affected by the Correlation value, below.

• Correlation – See the section on Correlation, above.

Duplication

Duplication is composed of the following components:

• Amount – (Percentage)  This value indicates that a certain percentage of the packets are to be selected and duplicated.  This selection is based on a random number and is affected by the Correlation value, below.
  
  Duplicated packets are sent back to the head of the gauntlet of impairments and are thus subject to Delay, Reordering, Drop, re-Duplication, and the Rate Limit.
  
  Note: If the duplication value is set at 100% it is likely that an infinite loop of packet duplication will result.

• Correlation – (Percentage)  See the section on Correlation, above.

Corruption

The netem “corruption” facility will change a random bit in a randomly selected packet

The bit changed may be any bit in the packet - from the start of the MAC/Ethernet header until the last bit of the Ethernet data.

This corruption facility simulates single-bit errors that occur on telecommunications links.

Because the Ethernet CRC is computed by the transmitting Ethernet hardware on Mini Maxwell, the Ethernet CRC on the packets will be correct.

For corruption that occurs within the IP header or data carried by higher level protocols, the fault should be caught by the checksum of that protocol.

Note, however, that some protocols do not always use checksums even if they have the capacity.  UDP, for example, allows the sender to provide a null checksum, indicating that the receiver should skip checksum validation of the received UDP packets.

• Amount – (Percentage)  This value indicates that a certain percentage of the packets are to be selected and corrupted.  This selection is based on a random number and is affected by the Correlation value, below.

• Correlation – (Percentage)  See the section on Correlation, above.

Rate Limit

RATE LIMITATION IS NOT IN THE CURRENT RELASE

Rate Limit is composed of the following components:

• Amount – (Bits/second)  Maximum bit rate.
  
  This limit is not enforced on an instantaneous basis.  Rather it is enforced over relatively long time spans (100s of milliseconds and longer.)
  
  The rate limitation is an approximate value.

Note that the rate limit is a per-Band limit.  The traffic in other Bands is subject to the rate limits, if any, imposed on those bands.