Version: January 28, 2009

Table of Contents

• Introduction to Mini Maxwell
• Getting Started
  • Unpacking and Physical Installation
  • Location
  • Power, Temperature, and Other Environmental Considerations
    • Power Over an Ethernet Cable
  • Temperature and Other Environmental Considerations
  • Connecting the Serial Console Interface
  • Setting Up the Control Network Interface
    • Offline Method
    • Via The Serial Console
    • DHCP
    • Default Addresses
    • Syslog
  • Connecting to the Devices Under Test
• Hardware Platform
• Basic Terminology
• What is Netem?
• Ethernet Bridging
• Directions of Packet Flow - LAN-A→LAN-B and LAN-B→LAN-A
• How Mini Maxwell Works
• Bands
• Filters
  • Filter Inventory
  • Filter Map
  • Filter Sequence
• Impairments
  • A Note on “Correlation”
  • Drop
  • Delay and Jitter
  • Reordering
  • Duplication
  • Corruption
  • Rate Limit
• Examples
  • Simulating a Slow DNS Server
• Saving and Restoring Impairment Settings
• Limitations
• Ugrading the Firmware
• References
• Online Support and Additional Materials

Introduction to Mini Maxwell

Mini Maxwell is a complete, easy to use, hardware+software network-impairment solution.

Mini Maxwell will divide the traffic into five bands based on the IP header and data content.  There are five bands for each direction of traffic.

Impairments may be imposed on each band.

Different bands may be subjected to different impairments.  Thus DNS queries may be subjected to different impairments than DNS replies while HTTP client-to-server traffic and HTTP server-to-client traffic are subjected to other impairments.

The impairments include:

• Rate Limitation
• Packet drop
• Packet duplication
• Packet delay:
  
  • Fixed delay
  • Jitter
  • Packet reordering as a side effect of jitter
• Packet bit corruption

Mini Maxwell operates as a layer-two Ethernet bridge; from the point of view of the traffic being impaired Mini Maxwell is just a bump in the Ethernet cable.  There is no need to adjust routing or IP address values in the devices under test.

Mini Maxwell uses a small, silent, portable, low-power platform with no rotating disks.

Mini Maxwell interacts with the user through a standard web browser to define the bands, to impose impairments, and, if desired, to save and restore band and impairment settings from a backup file on the user's computer.

Mini Maxwell is based on Linux and the netem module of the Linux kernel.

Unlike the typical single-ended netem configuration, Mini Maxwell creates a fully bi-directional, transparent layer-2 path in which netem impairments can be applied to traffic moving in either or both directions.

Mini Maxwell operates in layer-two bridging mode. There are two full duplex 10/100 Ethernet interfaces dedicated exclusively to test traffic.  Mini Maxwell thus becomes a “bump on the wire”.  It is not necessary to reconfigure the devices-under-test in any special way.  Mini Maxwell relays entire Ethernet frames, including the original MAC address, without alteration.

The only IP address Mini Maxwell needs is for its embedded web server.  Traffic to and from that server is carried over a management Ethernet interface that is distinct and separate from the interfaces used for the test traffic.

Mini Maxwell defines several uni-directional “bands” into which traffic can be directed by pattern-matching filters.  Several pre-written filters are provided and the user may add new filters.  Filters may be created, added, removed, enabled, disabled, and re-sequenced without restarting

Each filter may examine up to three different packet header fields, with each field being either 8, 16, or 32 bits wide.  These fields may be anywhere in the IPv4, UDP, or TCP headers.

A different netem impairment can be applied to each band.  Impairments may be altered at any time through Mini Maxwell's web pages without restarting.  Thus, for example, RTP (VOIP) packets flowing in one direction could be delayed by 250 milliseconds while the RTP packets flowing in the opposite direction are subjected to a 10% loss rate. And this could, for example, occur simultaneously with different impairments on HTTP, DNS, or SIP traffic.

Getting Started

You have received your new Mini Maxwell.  What should you do now?

You should take a glance at the Hardware Platform portion of this note in order to familiarize yourself with the Mini Maxwell box and its various interfaces.

If you have trouble with any of this please contact us by email at This e-mail address is being protected from spambots. You need JavaScript enabled to view it This e-mail address is being protected from spam bots, you need JavaScript enabled to view it or by phone at +1 831 460-7010 (ext 108)

Unpacking and Physical Installation

Unpack Mini Maxwell and make sure you have all the pieces:

• The Mini Maxwell chassis – this is an aluminum box, usually red in color, about 6.5 inches (16.5cm) square and about 1 inch (2.5cm) thick.
• A power “brick”

Take a look at the Hardware Platform section of this document  This will show you the various interfaces and plugs on the chassis.

You may also note some colored labels on the top or bottom of the chassis.  These should correspond to the colors shown in the figures the document mentioned in the previous paragraph:

• Red – Management interface (eth0)
• Yellow – LAN-A (eth2)
• Green – LAN-B (eth1)

There should be a label on the bottom of the chassis - this label shows the MAC address of the management ethernet interface (eth0).

Location

Consider where you will be installing Mini Maxwell.  This will dictate the IP address that you will need to assign to Mini Maxwell's management interface.

Note: Mini Maxwell's management interface is logically distinct from the two data ports on Mini Maxwell – the traffic that you will be impairing can be, and probably ought to be, on an entirely separate subnet.

Power, Temperature, and Other Environmental Considerations

Electrical Power

Power may be supplied via the power connector or via the rightmost of the three Ethernet RJ45 jacks.  (Note: This power-injection facility is not 802.3af compliant.  See the note Powering Mini Maxwell Over the Control Ethernet.)

The power connector has the following specifications:

• 16-24v, 0.9A DC
• 2.1mm receptacle
• Center post: Positive

Note: Power-over-Ethernet (PoE) is not provided by any Ethernet port.

Note: Take care to use the correct power brick.  Do not use a 110v/120v power brick in a 220/240v location.

The boot-up process takes between 60 and 90 seconds.  At the end of that time the power LED on the front of the Mini Maxwell chassis should be lit.  (The power LED is the one of three LEDs on the front – the power LED is the one closest to the edge of the box.)

Now you should set the IP address using the method you have selected.  If you previously used the Offline or Serial Console method then the address that was set previously will remain and need not be set again.

Power Over an Ethernet Cable

It is possible to provide power to the Mini Maxwell via its management Ethernet interface.

This powering facility is not compliant with IEEE 802.3af.  A special DC injector is required.

Mini Maxwell may be plugged into a switch that provides IEEE compliant power over Ethernet; however Mini Maxwell will not utilize that power source.

Temperature and Other Environmental Considerations

Mini Maxwell uses passive cooling.  However it should not be placed in a tightly confined space with no airflow.

Mini Maxwell should be placed in a location with normal office or computer room temperature and humidity levels.

Mini Maxwell contains no rotating or moving parts.  However it should not be subjected to more vibration than is typical for a computer rack that contains operating disk drives.

Mini Maxwell may be mounted in any orientation.

Care should be taken to assure that the power brick is not dangling from a power strip and that the cord from the power brick to the Mini Maxwell itself is not entangled and safe from being accidentally or damaged in a door jam.

Connecting the Serial Console Interface

The serial console is typically used only for initial configuration.

The serial console uses the RS232 interface.  Generally one attaches a laptop or desktop computer to this interface using a female DB-9 to female DB-9 null-modem cable.

An appropriate cable may have been included with your Mini Maxwell.

Note: Some laptops may lack a serial DB-9 connector.  In that case one might use a USB serial adapter with drivers as appropriate for the operating system used on the laptop.

Note: If your computer does not have its own RS232/serial interface or if you do not have the appropriate cable an alternative is to plug a Bluetooth serial adapter, such as the IOGear GBS301, into the console port on Mini Maxwell and then to use a laptop or desktop that has Bluetooth to connect to that adapter.

Many modern computer users are not familiar with RS232 and may find it to have rather more settings and physical configurations than they are used to.

Note: If you are in a position to let the device use DHCP to obtain an address for its management interface and you can easily learn what address has been assigned then you may find it easiest to not use the serial console at all.

Once the device has been configured it is not necessary to leave the serial interface connected.  However, it is sometimes convenient to leave the serial console connected to a nearby PC.

True RS232 terminals have long been obsolete; today they have been replaced by software on personal computer platforms.  Most personal computers use a male DB-9 connector exactly like that used on the device.

In RS232 terminology the device is a DTE - Data Terminal Equipment.  PC's and laptops are also RS232 DTE's.  This means that they must be connected using what is called a "Null Modem" cable.  (As was mentioned above, it is often easier to use a Bluetooth serial adapter than to try to find the correct RS232 cable.)

The cable to connect a PC to the device must have the following characteristics:

• Female DB-9 to Female DB-9
• Null Modem (crossover) wiring

Such cables are available through many electronics suppliers.  Take care to find ones with DB-9 female connectors at both ends.

Note: Some suppliers now sell only null modem cables with a male DB-9 at one end and a female DB-9 connector at the other end.  In these cases a female-female DB-9 "gender changer" will also be required.

Note: Unless cables are well marked, there is no visual way to differentiate whether a given cable is a null modem or not.  It is good practice to appropriately mark serial cables as soon as they are unwrapped from the vendor's packaging.

Once the wiring is installed it is necessary to use a terminal emulator program on the PC.  Here are the settings that should be used.  Because there are many terminal emulator programs and each is configured in its own way, the details of how these settings are name, expressed, and applied will vary:

• Asynchronous
• 38,400 bits/second
• 8 bits per character/byte
• no parity
• 1 stop bit
• Full duplex (i.e. remote echo)
• No modem controls
• No flow control (i.e. no RTS/CTS, no xon/xoff)

Here is an example configuration file used by the popular (and free) Kermit terminal emulator:

; The following is typical for built-in serial ports on Linux machines:
set line /dev/ttyS0
; The following line (which is commented-out) is typical
; for USB based serial ports on Linux machines"
; set line /dev/ttyUSB0
; On Windows machines the port will probably look something like
; the following, but perhaps with a different number.
; set line com1
set carrier-watch off
set speed 38400
set serial 8N1
set flow-control none

NOTE: The device does not use modem control signals; use the “Enter” key on the terminal emulator program to cause the device to issue a login prompt.  If you receive gibberish then the communications settings, probably the bits-per-second-rate, are incorrect.  If you do not get any response at all then it is likely that either the communications settings of the terminal emulator are incorrect or the cable is not a null-modem cable.

Setting Up the Control Network Interface

There are several methods to assign an address:

1. Recommended: Offline Method: This method is described below at Setting the IP Address - Offline Method.

2. Serial Console: This method requires that you attach a serial cable to the Mini Maxwell chassis and use a terminal emulator program.  Please see the Frequently Asked Questions (FAQ) for information about serial ports, USB-to-serial adaptors, and terminal emulator software.

   This method is described below at Setting the IP Address - Via The Serial Console.

   See the section Connecting the Serial Console Interface for information about what kind of cable is required and what serial data rate settings should be used.

3. DHCP: This method allows Mini Maxwell to ask a DHCP server on your network for a dynamic IP address.  The drawback of this method is that it may be difficult for you to ascertain what address the DHCP server assigned.
   This method is described below at Setting the IP Address - DHCP.

   Note: With DHCP you may obtain a different IP address every time you reboot Mini Maxwell.

Once you have decided how you are going to handle the IP address for Mini Maxwell's management interface you can begin to wire Mini Maxwell into your network and boot it up:

Be aware that Mini Maxwell's management interface may attempt to use or provide certain services on your network:

• DHCP
• ARP
• Domain Name System (DNS, UDP port 53)
• Network Time Protocol (NTP, UDP port 53)
• SNMP (UDP ports 161 and 162)
• System logging (Syslog, UDP port 514)
• HTTP (TCP port 80)
• SSH (TCP port 22)

Using a standard RJ45 based ethernet cable, hook Mini Maxwell's console port into your network.  Normally a standard straight-through cable is used.  The ethernet jacks on Mini Maxwell have auto MDI/MDI-X logic and will usually adapt a crossover or non-crossover setting as needed.  As usual, the link state indicators at both ends should be checked (once power is applied) to verify that the link has been established and that the speed is correct.

Note: The link state LED's on the ethernet ports on Mini Maxwell do not indicate whether they are linked at 10 or 100 mbits/second; they merely indicate whether link state is present or not.

If you have been successful you should be able to “ping” the Mini Maxwell from another computer on your network.  You should also be able to reach Mini Maxwell from a web browser on your network using a URL of the form http://xxx.xxx.xxx.xxx/ where xxx.xxx.xxx.xxx is the IP address that was assigned to Mini Maxwell.

Setting the IP Address - Offline Method

Often the easiest way to establish a knowable IP address to is to use what we call the Offline Method.

This method depends on the fact that, in its factory default state, the device will fall-back onto a default address and mask if it can not otherwise obtain one over the network.

That default address and mask are:

• 192.168.0.5
• 255.255.255.0 (length 24, i.e. a /24)

Here's how you do it:

1. Obtain the following information from your system administrator:
   
   • IPv4 address for the device to use.
   • Subnet mask in the form of prefix length.  A table of masks to prefix lengths may be found in another note.
   • Hostname and domain name - These do not have to be in DNS.
   • IPv4 address to use as a default route.
   • IPv4 address of at least one DNS server.
   • IPv4 address or domain name of NTP time servers (optional).
   • IPv4 address of a syslog server (optional).
2. Locate a computer that you can use that has both a web browser and on which you can change the IP address of its wired network interface.
3. Change its IP address to 192.168.0.6 and it's subnet mask to 255.255.255.0.  If it requires a default route, give it 192.168.0.1.
4. Launch the web browser.  It might be very sluggish as a result of it not being able to perform DNS queries or reaching home pages.  Be patient.
5. Attach the management interface to your network or, if your network administrator prefers, to an isolated network composed of nothing more than a simple Ethernet hub or switch.
6. Power cycle the device.  After a few seconds you should see the link-state LED's come on on on the management interface socket.
7. Wait at least 90 seconds for device to fully boot.
8. Use the web browser to go to the following URL: http://192.168.0.5/
9. You should see the configuration web pages.  Use the "Configure Network" page to set the desired settings.  Don't forget to click the "static" checkbox!  When you have entered all of the settings, use the "Submit" button.
10. You will probably be prompted to supply a name and password when you submit the changes.  Use user name "sbump" with password "4ZytYqbm".
11. You may now unplug the device and install it in its proper location on your network.

Setting the IP Address - Via The Serial Console

Note: It is strongly recommended that you set the basic IP address information using the offline method as described above.

The serial console is intended to be used only during initial system installation and configuration and for management purposes.  Only the basic IP address information can be set using through the serial console.

Once the basic information is set the web interface should be used to set all of the IP addressing information.

Before starting you should ascertain the addressing information you will need:

• Hostname (e.g. bump72) and domain name (e.g.example.com)
• IPv4 address
• Subnet mask (in either address notation, e.g. 255.255.255.0, or prefix notion, e.g. /24)
• Default route
• IPv4 address of a DNS server
• IPv4 address of an NTP server (optional)
• IPv4 of a syslog server (optional)

Perform the following steps:

1. Connect a personal computer running a terminal emulator program.  See the section of this document entitled “Connecting the Serial Console Interface”

2. Login:
   Username: setup
   Password: 83Pj4Dmt

3. Follow the instructions.  The script may ask you whether you want to reboot.  If it is a good time to do so, then perform a reboot and bypass the next step below.

4. Logoff using Ctrl-D or the “exit” command, or reboot the device using the “reboot” command.

NOTE: The address changes will not have effect until the device is rebooted.

After you set the basic IP address information you can use the web interface to extend or change that information.

Use a URL of the form shown below, but replace “192.168.1.100” with the IP address actually being used for the device.  This will bring up the home page.

http://192.168.1.100/

Then follow the links to the “Network Configuration” page.

Setting the IP Address - DHCP

Mini Maxwell can obtain its network configuration using the Dynamic Host Configuration Protocol, DHCP.  This is an easy way to operate but it comes with a drawback: It can be difficult to ascertain the IP address that the DHCP server assigned to Mini Maxwell.  For that reason it is often useful to create an explicit DHCP assignment entry into the DHCP server configuration so that Mini Maxwell will obtain a known IP address from the DHCP server.

The attempt to use DHCP happens only when Mini Maxwell is powered on or restarted.  If there is no DHCP server available at that time the device will self-assign the following IP address and subnet mask:

• 192.168.0.5
• 255.255.255.0 (i.e. /24)

DHCP Server Configuration

Below is a typical entry used for in the configuration file (/etc/dhcpd.conf) for the ISC DHCP server.  In this example we are configuring device "device.example.com" that has a MAC address of 00:0D:B9 01:8C:6C.

(See ISC DHCP Server – http://www.isc.org/index.pl?/sw/dhcp/)

option ntp-servers pool.ntp.org;option domain-name "example.com";
option domain-name-servers ns1.example.com, ns2.example.com;
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.17.255;
option routers 192.168.17.66;
option log-servers logserver.example.com;
max-lease-time 64800;
default-lease-time 64800

group {
    host board-1 {
        hardware ethernet 00:0D:B9:01:8C:6C;
        fixed-address device.example.com;
        # Coerce the client to take the log server option whether they
        # ask for it or not.
        # Note: The next line may appear to be wrapped, in real-life it is one line.
        option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,7);

        option host-name "device.example.com";
        option tftp-server-name "tftpserver.example.com";
        option root-path "/tftpboot";
        next-server tftpserver.example.com;
        if substring (option vendor-class-identifier, 0, 9) = "Etherboot" {
            filename "pxelinux.0";
            }
        }
}

Ascertaining the IP Address Assigned by DHCP

The question then arises: How does one ascertain the IP address that was assigned to the device?

There are three broadly defined methods to do this:

• Configure the device Offline - In many cases this is the easiest and best way to deal with the issue.  See the information at offline method.

• Ask the DHCP server - This method may require special knowledge and privilege on the DHCP server.

  If you are uncomfortable with dealing with DHCP servers or do not have adequate system privileges to get to DHCP logs, then the offline configuration method is likely to be the best choice.

  In order to ask the DCHP server you need to ascertain which device on your network is providing the DHCP service.

  Different DHCP servers note their assignments in different ways.

  The ISC DHCP server, popular on Linux and Unix systems, sends reports of DHCP activity into the system's syslog.  These messages are usually recorded into the file named /var/log/messages.  This file is often protected and readable only by the system administrator.

  The ISC DHCP server also records its assignments in the file /var/lib/dhcp/dhcpd.leases.

  If you inspect these files you may find that you have several possible IP addresses.  The easiest way to find which one is correct is to try to connect to each via a web browser until you get the the device web pages.  An example of a URL that contains an IP address is this, which contains the address 192.168.1.100:  http://192.168.1.100/

  If your DHCP server is within your router, then it may have a web page that displays its DHCP assignments.

• Ask Mini Maxwell via the serial console - Mini Maxwell will display its network address just before issuing login prompts on the serial console.  This means that you have to go through the steps to connect to the serial console - see Setting the IP Address - Via The Serial Console

Default Addresses

If Mini Maxwell is using DHCP to obtain an IP address and if DHCP fails to ascertain an address, the following IP address and subnet mask will be self-assigned the management interface:

• IP address: 192.168.0.5
• Subnet Mask: 255.255.255.0 (prefix length 24, i.e. a /24)

NOTE: The other interfaces do not have IP addresses.

Syslog

Mini Maxwell sends event information into “syslog”.  Mini Maxwell may be configured so that this “syslog” actually resides on a separate computer.

Note: Some systems, such as Fedora Linux, are preconfigured to not accept syslog messages from other computers.

This may be altered by changing the file /etc/sysconfig/syslog so that the “-r” parameter is supplied, as shown below.

SYSLOGD_OPTIONS="-m 0 -r"

The syslog server must be restarted after this change has been made

Connecting to the Devices Under Test

Because Mini Maxwell operates at layer 2 it appears to most Ethernet devices as merely a bump in the Ethernet cable - there are no addressing or routing parameters to be configured.

Mini Maxwell does introduce a small store-and-forward delay - on the order of a few hundred microseconds.  This is insignificant for most IP and higher level protocol testing purposes because it is typically an order of magnitude (or more) smaller than the kinds of delays normally perceived at that level.

Some issues may arise when you connect devices to Mini Maxwell's two data interfaces.

Forwarding Loops

A common error when wiring Mini Maxwell between devices is to directly (or indirectly) plugging both of Mini Maxwell's data ports into the same switch.  This creates a packet forwarding loop.  As soon as the first packet is sent by any device the network will reach full capacity as the packet goes around and around in an infinite loop.

When wiring Mini Maxwell into the network care should be exercised to assure that the two network segments, the one attached to LAN-A and the one attached to LAN-B, are isolated from one another without any routers, switches, or hubs connecting them together.  Mini Maxwell should be the sole point of interconnection.

Link State

When you connect devices to Mini Maxwell's two data interfaces you should always check that you are getting the link-state indicator on the Mini Maxwell interfaces and on the interfaces to the devices.

Gigabit-only Devices

Mini Maxwell's interfaces operate at 10 or 100 megabits/second; they do not support gigabit (1000 megabit/second) rates.

Most gigabit devices will auto-negotiate down to 10 or 100 megabits and thus will work automatically with Mini Maxwell.  However some devices, particular some routers, switches, and test equipment has interfaces that are locked onto a single speed or which may be configured by their operator to be locked onto a single speed.

If speed negotiation is not possible the easiest cure is to insert an inexpensive, consumer-grade 10/100/1000 ethernet switch into the path betwee the device and Mini Maxwell.  These switches will usually solve all of the negotiation issues.

Duplex/Half-Duplex

Mini Maxwell's interfaces will auto-adapt to the full or half duplex mode used by the device at the far end of the Ethernet cable.  Normally you should have no problems with this, however duplex negotiation has had more than its share of devices that have had difficulty.  Hopefully that is a thing of the past for modern equipment.  If there is a duplex issue, often inserting an inexpensive, consumer grade 10/100 switch into the path will solve the problem.

Hardware Platform

The Mini Maxwell hardware consists of a small chassis, approximate 6.5 inches square by 1 inch thick.  It is usually powered via an external power supply “brick” but may alternatively be powered via its management ethernet interface (eth0).  (Note: This power-injection facility is not 802.3af compliant.  See the note Powering Mini Maxwell Over the Control Ethernet.)

NOTE: Mini Maxwell may be damaged beyond repair if an incorrect power supply is used.  Power voltage must be between 7v and 18v DC.  Please take care to avoid using a non-universal (i.e. 110/120v only) power supply in a 220/240v location.

Below are drawings of the front and rear of the Mini Maxwell chassis.

Front View of Mini Maxwell 2

Rear View of Mini Maxwell 2

Mini Maxwell contains no rotating disks or fans.  It generates almost no noticeable heat and is silent.  It may be mounted in any convenient orientation.  However, a small amount of air circulation is necessary to dissipate the small amount of heat (about 4 watts) that is generated.

The three Ethernet interfaces operate at 10 and 100 megabits/second and support auto crossover (auto MDI/MDI-X).

Each of the ethernet interfaces on Mini Maxwell has two LEDs.  The LED on the upper left corner indicates whether link state is present or not.  This LED blinks off/on to indicate packet reception.  The LED on the upper right corner indicates whether the interface is active (which is normally the case when power is on) and blinks off/on to indicate packet transmission.  Neither LED indicates whether the link is operating at 10mbits/second or 100mbits/second or whether the link is operating in half or full duplex mode.

Note: The Reset button is not supported by the current software release.

Basic Terminology

The table below defines some basic terms used in Mini Maxwell.  Several of these terms will be revisited in greater detail in later sections of this document.

What is Netem?

Netem is a Linux kernel module that can be instructed to impair streams of packets.

These impairments include delay, loss, duplication, and reordering.

Netem is fully described on its website at http://linux-net.osdl.org/index.php/Netem.

Netem is controlled using the tc command.  Tc is one of the most arcane of all of the Unix/Linux commands.

How Is Mini Maxwell Different From Netem?

Mini Maxwell uses the netem kernel module to do the actual real-time impairments.

However, Mini Maxwell has applied netem in a way that avoids many of the difficulties of using netem directly.

For example, a typical netem user tries to run netem on an interface on a Linux box which is acting as one end of the conversation, or is acting as a router.  In the former case, the user has relatively poor control over the impairments applied to incoming traffic; often only outgoing traffic is impaired.  In the latter case the user has to configure the Linux box to be a router.  Routers are not transparent; the devices that are communicating via this impairing-router have to be configured accordingly.  This can be difficult for those who are not familiar with routing and it also add a degree of uncontrolled impairment due to the queuing that can occur in a router (for example, packets may be held back while the router is performing an ARP transaction.)

Mini Maxwell deals with these, and other netem issues.

Mini Maxwell runs on a dedicated platform with three Ethernet interfaces, two of which are run in bridging mode.  Netem is applied to the outgoing packets on these two interfaces.  This means that:

• Mini Maxwell can operate as a bump on the wire.  There is no need to create special IP addresses or routes.
• Mini Maxwell can impair traffic flowing in both directions simultaneously.
• Mini Maxwell can partition the traffic by protocol, address, or other header fields and perform different kinds of impairments on each of those traffic partitions.
• Mini Maxwell can simultaneously impair traffic flowing between several different source-destination host pairs.

Netem is part of the IProute2 traffic control system on Linux.  IProute2 is full of arcane and incompletely documented commands.  Mini Maxwell hides nearly all of the complexity of IProute2 from the user.

Because Mini Maxwell is on a dedicated platform side effects from other applications are avoided.

The Linux kernel on Mini Maxwell operates with a 1000Hz clock.  This improves the accuracy of its timers as compared to a typical Linux kernel with a 100Hz or 250Hz clock.

Ethernet Bridging

Mini Maxwell connects LAN-A and LAN-B together in bridging mode.  This means that packets that arrive on LAN-A are relayed through netem and transmitted out of LAN-B.  And packets that arrive on LAN-B are relayed through netem and transmitted out of LAN-A.

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.

The store and forward delay caused by this bridging (in the absence of any impairments) is very small - on the order of a few hundred microseconds.  This store and forward delay is inconsequential when compared with ordinary packet network transit times that are typically from tens to hundreds of milliseconds.

Mini Maxwell will bridge ethernet frames that have IEEE 802.1q VLAN headers.  However, Mini Maxwell's filters will not properly operate on these packets.  Thus, if Mini Maxwell is placed on a trunked VLAN (i.e. one in which all of the ethernet packets contain 802.1q headers, then all of the packets will be classified into the default band, Band 5.  Impairments specified for Band 5 will be applied to these tagged packets.

The Two Directions of Packet Flow: LAN-A→LAN-B and LAN-B→LAN-A

Mini Maxwell can do different things to the packets flowing in the two different directions, i.e. from LAB-A to LAN-B and in the reverse direction from LAN-B to LAN-A.

Users may inadvertently apply an impairment to the LAN-A→LAN-B direction when they really need to apply it to the LAN-B→LAN-A direction instead.

Hint: In order to check whether you are applying an impairment on the correct direction of packet flow, temporarily apply an obvious impairment - such as a 500millisecond delay or 100% packet loss in one of the directions and observe the effect.

How Mini Maxwell Works

The diagram below shows how a packet is processed in Mini Maxwell.  The diagram shows only one direction of packet flow; in reality Mini Maxwell contains two such flows, one for packets arriving on LAN-A and another for packets arriving on LAN-B.

Packet Classification and Impairment

1. A packet enters Mini Maxwell through either LAN-A or LAN-B.

2. The packet is processed by the Ethernet hardware - any packets that have an invalid Ethernet layer CRC (cyclic redundancy check) will be discarded by the hardware.

3. The incoming packets are presented to the packet classification part of netem.  This classifier uses the filters and the filter map to sort each packet into one of five bands.  The filter contains a pattern that will be compared to packet contents; the filter map entry associated with each filter will designate which band should receive matching packets.  Filters are tested against the packet in the order defined by the filter sequence.  The packet will be classified according to the first filter that matches the packet contents.

   The last of these bands, Band #5, is a default band that will handle any packets that do not match any filters.  Packets may also be explicitly routed into Band #5 using filters that map to Band #5.

   Please note that although the diagram shows only one direction of packet flow there are, in actuality, classifier and five bands for each of the two directions.  The five bands in one direction are separate from the five bands in the other direction.

4. Once classified into a band a packet will be subjected to the impairments that the user has specified for that band.

5. Upon leaving the impairment stage of its assigned band, a packet is sent to the outgoing Ethernet interface.  At this point the Ethernet CRC will be computed and attached to the packet.  The Ethernet hardware will then transmit the packet.

Bands

When a packet arrives on either LAN-A or LAN-B 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 LAN-A to LAN-B is different from a band that carries traffic in the reverse direction, from LAB-B to LAN-A.

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.

Filters are collected into a "Filter Inventory".

Filters in the inventory may be created, copied, deleted, and edited as shown in the following diagram.

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 basic tcp filter is sending its packets into Band #5 - which is the default band where they would have gone anyway if they don't match any other filter.
• The filter to pick HTTP traffic flowing to the host with IPv4 address 1.2.3.40 is sending its packets into Band #4.
• The basic udp filter is also sending its packets into Band #4.
• All UDP based Domain Name System (DNS) packets are being sent into Band #1.
• All UDP based Session Initiation Protocol (SIP) packets are being sent into Band #2.
• All UDP packets of length less than 256, with or without QoS settings, are being sent into Band #3.

Note: The map for the LAN-A→LAN-B direction need not be the same as the map for the LAN-B→LAN-A direction.

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 would be 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, based on the filter map from the previous diagram, we see the default filter sequence.

This sequence contains two configuration errors:  First, the basic TCP filter will be used before the HTTP to host 1.2.3.40 filter thus denying that second filter any chance of ever seeing a packet.  Second, because the udp filter will be checked before the dns, 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_dns_dst_port, udp_dns_src_port, 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 and DNS 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.

Netem performs many of its impairments by generating random numbers and then basing its action on the particular number that was generated.  Normally each random number is independent of the number(s) that came before.  Correlation is a mechanism in which each random number is affected by the number that came before.

The correlation value can be small, in which case the prior number has little or no impact on the new number.  Or the correlation value can be large, in which case the prior number strongly affects the new number, even to the degree of making the new number the same as the prior number.  Correlation values range from zero (no effect) to 100 (new number will be the same as the prior number.)

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 event is triggered or not based on the result of that comparison.

In addition 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 within the same Band.  Thus, for example, a burst on Band#3 in the LAN-A→LAN-B direction is independent of whether a burst is occurring on Band #2/in the LAN-B→LAN-A direction.)

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 behavior.

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.

If all of this is confusing it might be useful to consider Mini Maxwell and Netem as having a single dice (die) that has 100 sides with values of 0 through 99.

When the user enters an impairment probability, for example, a drop probability of 33%, what happens is this:  When Mini Maxwell needs to decide whether to drop a packet, that 100 sided die will be rolled.  If the number comes up less than the user-specified percentage, in our example this means that the die comes up with the number 32 or less, then the packet is dropped.  If the roll of the die comes up with a value equal to or higher than what the user entered then the packet would not be dropped.

If a non-zero correlation value is indicated then that simple test above is slightly changed.  With correlation active, when the die is rolled, rather than using the number that shows on the die, the correlation calculation will be used to combine the visible number with the prior number.  It is this combined number that will then be compared with the user generated probability threshold.

That "prior number" is itself the result of a correlation computation.

Assume, for example, that the user has set a drop probability threshold of 33% and a correlation value of 75.  Further assume that the previous value used was 60 and that for the current packet a value of 30 comes up on the die.  The correlation calculation for the current packet would calculate (.75 * 60) + (.25 * 30), which results in a value of 52.5.  That 52.5 will be compared with the user threshold (30) and thus the current packet will not be dropped.  That 52.5 value will be retained and used when computing the correlated value for the next packet that is to be considered for dropping.

These correlation chains are maintained for each separate type of impairment within each separate band in each direction.  This means that a correlation caused burst may be occurring for one type of impairment in one band while in the other bands no correlation caused bursts are occurring.

Delay and Jitter

Delay and Jitter are variations on the same thing.  Delay is simply the amount of time that occurs between the transmission of a packet and the reception of that packet.  Jitter (also called "Interarrival Jitter") is a statistical measure of the variation in the Delay time experienced by several packets over a period of time.

There is no single mathematical formula for computing Jitter.  However, a well known and widely used formula is found in Appendix A.8 of RFC3550.

In Mini Maxwell, jitter is created by allowing the delay to vary from one packet to the next.  This variation is controlled through the Variation, Correlation, and Distribution parmeters that may be applied to the basic Delay Amount.  If these parameters are not used then the delay will not vary from one packet to the next and there will be no jitter.

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 9999 milliseconds (about 10 seconds.)

• 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.

Corruption is composed of the following components:

• 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 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.

The rate limit impairment imposes a restriction on how many bits may be carried per second.  Because we are dealing with packets rather than bits and because of the presence of buffering virtually all modern network devices, the topic of rate limitation is not as simple as it might at first appear.

Rate limitation is obtained by metering the flow of packets.  Although the calculations are based on the number of bits per second and the number of bits within the packets, control is exercised by placing packets into a queue and releasing them at a controlled rate so that the number of bits carried, over a period of time, will not exceed the configured rate.

Packets that exceed the rate limitation will be delayed in a FIFO (First-In/First-Out) queue until the backlog reaches a cutoff point; at that point, additional packets are silently discarded until the queue drops below the cutoff point.

The queue and cutoff point have been defined to resemble that of a generic, but typical, internet device such as a router.

Rates are limited using a token bucket filter with the following parameters.  (Note: The Mini Maxwell kernel operates at 1000HZ, not 100HZ as suggested by the tbf document.)

• Clock rate: 1000HZ
• Buffer (Burst): 1600 bytes
• Latency: 1,000,000 microseconds (1 second) plus any user specified delay.
• Minimum Packet Unit (MPU): 64 bytes

This causes a rate limitation behavior with the following characteristics when the bit arrival rate (as measured by the bits contained within packets) exceeds the user specified rate limitation:

• The queue will begin to fill with arriving packets.  Simultaneously the queue will be drained by sending packets.
• For a short period of time (a few milliseconds) no rate limitation will be perceived - this is because a short period of time is required to evaluate the number of bits that are being moved over a time interval and there will be a pool of available "tokens" in the token bucket filter that have accumulated during the preceding period in which arriving packets were not exceeding the rate limit.
• Arriving packets will begin to accumulate in the queue faster than they are being released onto the outbound interface.  This will cause these packets to appear to be delayed and the amount of that delay will increase as the queue of pending packets gets longer.
• The queue cutoff may be reached.  At this time arriving packets will be discarded.  At the same time the queue continues to drain according to the rate limit, thus tending to cause the queue to drop below the cutoff and thus permitting new packets to be placed into the queue.  This interaction will be perceived as a situation in which some packets are lost while other packets are delayed.
• When the arrival rate drops the packets in the queue will continue to trickle out according to the rate limit.

Examples

Simulating a Slow DNS Server

In this example we will see how to set-up Mini Maxwell to simulate a network with a very slow domain name (DNS) resolver.  To do this we will delay all UDP encapsulated DNS packets, whether queries or responses.

We will create two filters to find DNS/UDP packets.  One filter will locate packets with the DNS well known UDP port (53) as a source port and one filter will look for UDP port 53 as the destination port.  We will then use the filter map to instruct these filters, in both the LAN-A→LAN-B and LAN-B→LAN-A directions, to send their packets into Band #1.  Then we will impose a 500 millisecond delay on packets flowing through Band #1 in both the LAN-A→LAN-B and LAN-B→LAN-A directions.  This will result in a general DNS resolution delay of about one second, which should have a substantial negative impact on the setup time for many applications, particularly those, such as web browsers, that do a lot of DNS queries.

Creating the Filters

The easiest way to create any filter is to copy an existing filter and then modify it.  So we will begin by copying and modifying the two standard filters used to identify UDP based SIP packets.  We will need to change only the filter names, the descriptions, and the port numbers.

Note: Mini Maxwell comes with filters pre-defined for DNS over UDP.  However, for illustrative purposes we will create new ones here.

Under the “Filter Inventory” menu, select the “udp_sip_dst_port” filter, and push the “copy” button.  This will create a new filter with a temporary name and bring up a form to change the contents of the filter:

Change the filter name to “example_udp_dns_dst_port”. Modify the description.  Change the second match as shown in the following diagram.  (The first match selects the UDP protocol, so it should be left unchanged.  The third match is unused, which is indicated by a mask with a value of zero.)

Note: The Pattern and Mask fields are specified as hexadecimal values (with a leading "0x").

Note: The Pattern and Mask fields are specified in network byte order.

Now do the same, but using “udp_sip_src_port_sip” as the starting point to create an “example_udp_src_port_dns” filter:

Now set the filtermap so that all UDP DNS packets, as selected by our new filters, are sent into the LAN-A→LAN-B and LAN-B→LAN-A directions of Band #1.  All other packets will go into the default, Band #5.

Finally, we need to impose the actual delay impairment.

(Don't forget that you have to submit the screens shown above for them to have effect.)

Saving and Restoring Impairment Settings

Mini Maxwell holds its configuration in a textual format that can be exported to the user's computer or imported from the user's computer

This impairment configuration is stored in volatile memory - unless it is exported it will vanish (and replaced by the factory configuration) when Mini Maxwell is powered down or restarted.

Note: The user should not edit the exported configuration file - there may be unpredictable effects if an altered configuration file is imported back into Mini Maxwell.

Note: The impairment configuration is does not include the network settings for the management interface.

Importing and Exporting Impairment Configuration

Mini Maxwell saves its working configuration, including filters, filter maps, filter sequences, and impairment settings, in a textual configuration file.

The user may export this file from Mini Maxwell into the user's computer.

And the user may import a saved configuration into Mini Maxwell, replacing the previously existing configuration.

Import and export are, as are all Mini Maxwell tasks, done via a standard web browser.

Because Microsoft Windows and Unix/Linux/Bsd disagree on how text lines should be terminated, there are two different Export buttons, one for each format.  There is only one Import button; Mini Maxwell will accept either format.

Clearing Impairment Configuration

The “Clear” button on the Mini Maxwell's main web page will reset Mini Maxwell's filters and bands back to their original, factory settings.

This this button erases all existing filter and band configurations.

Tip: Export the existing configuration before clearing it.

Limitations

Packet and Bit Rates

Mini Maxwell operates on a platform with 10/100 full duplex Ethernet interfaces.  Gigabit Ethernet is supported only in that peer gigabit devices will usually down-shift to 100mbit rates when attached to Mini Maxwell.

Maximum packet size is 1500 bytes (plus MAC header and Ethernet framing.)  (No jumbo packets.)

Mini Maxwell operates as a layer 2 bridge.  IEEE 802 spanning tree protocol is not enabled.

In the absence of any impairments Mini Maxwell has a total forwarding capacity of approximately 20,000 packets per second when the packet size is 84 bytes and 5,000 packets per second when the packet size is 1480 bytes.  The user interface becomes sluggish when the packet rate reaches approximately 75% of these rates.

Mini Maxwell does not support IPv6

Mini Maxwell will carry IEEE 802 tagged VLAN traffic but it will not be able to classify the packets into bands.  Mini Maxwell will carry tagged ethernet frames between its two data interfaces.  However the filters will not work as expected and should not be used.  All of the IEEE 802.1q tagged packets will fall, by default, into Band 5 where they may be subjected to impairments.

Power-Over-Ethernet (PoE)

The power-injection facility on the Management Ethernet port (eth0) is not 802.3af compliant.  See the section of this note Power Over an Ethernet Cable.

Power-Over Ethernet is not provided by any Ethernet port.

Power-Over-Ethernet that may be presented on eth1 (LAN-B) or eth2 (LAN-A) is not neither used nor carried through to the other port (eth2 or eth1).

Impairment Limitations:

• Time increments are in in 1 millisecond units.  The underlying kernel is configured to minimize timing inaccuracies.

• User configured delay values are limited to 9999 milliseconds (about 10 seconds) (otherwise internal queues could overflow and unexpected packet loss could occur.)

Note: Mini Maxwell's web pages are W3C compliant.  Firefox is the recommended browser.  Microsoft's Internet Explorer version 6 (now obsolete) sometimes has difficulty properly formatting Mini Maxwell's web pages.

Upgrading the Firmware

The firmware inside Mini Maxwell may be upgraded by the user.

Make sure that you have the following things handy:

• A USB "thumb drive" with at least 150megabytes of free space.
• A computer with terminal emulator software such as Microsoft Hyper Terminal on Windows or Kermit for Windows, Linux, and Macintosh machines.
• If your machine does not have an RS323 Serial port then you may need a USB-based serial adaptor.
• An appropriate "null modem" cable.

Before you begin, take a moment and review the instructions below:

1. The user begins by using a standard web browser to download the update file from the Mini Maxwell update repository.

   Note: This update file may sometimes be more than 100megabytes in size.

2. The user then transfers that file to a commonly available USB "thumb drive".

   This USB device must be formatted as FAT, FAT-16, FAT-32, or VFAT.  These are the formats usually found on USB "thumb drive" devices of 4gigabytes or less.  It is rare for "thumb drives" to use different formats, so it is reasonably safe to assume that you already have the appropriate format.

   Note: Although the update process does not write to the USB device, it is good practice to do an update from an otherwise empty USB device.

   The update file must be placed in the root directory of the USB device.

   The update image will have a file name of the form umf#####.tgz where ##### are replaced by a five digit sequence.  As a general practice, lower valued digit sequences are older updates than higher valued digit sequences, i.e. update umf40000.tgz is more recent than umf32345.tgz.

   Updates will generally replace all of the software rather than patching what is already there.  Consequently it will rare, if ever, that the user will need to apply more than the most recent update.

3. The user will need to connect to Mini Maxwell's serial interface.  This is described in the section Connecting the Serial Console Interface

4. With the serial cable connected and an appropriate terminal emulator running, the user should power-cycle the Mini Maxwell.  Be prepared for the next step; it happens quickly after power is applied.

   The user should quickly see text from the Mini Maxwell that looks like:

   PC Engines ALIX.2 v0.99
   640 KB Base Memory
   261120 KB Extended Memory
   
   01F0 Master 045A CF 1GB
   Phys C/H/S 2014/16/63 Log C/H/S 1007/32/63
   
   EXTLINUX 3.52 2007-09-25 CBIOS Copyright (C) 1994-2007 H. Peter Anvin
   boot:

5. At the "boot:" prompt the user should enter the word "maint" followed by the Enter or Return key.

   Note: There is only a 4 second window to enter that word, otherwise Mini Maxwell will proceed with its normal start up.  If you miss the time window then simply power cycle the Mini Maxwell again and try again.

   Note: If you see the following two lines (they appear rather quickly) then you are entering the normal start-up system and not the firmware upgrade system:

   Loading /linux...............................
   Loading /initrd.gz..............................................ready.

   Entry into the upgrade system will be indicated by the following two lines (again, they occur rather quickly and may scroll off your screen):

   Loading /maintlinux...............................
   Loading /maintrd.gz...............................................ready.

6. Wait for the system to finish booting.  This will take about a minute.  The system will ask you to hit the "enter" key to obtain a login prompt.

7. Login as user "reflash".  The password is "2pALgZDP".

   From this point on you will be given a sequence of instructions.  In outline, you will be asked to remove any USB devices that may be installed, then to insert the USB device containing the update image.  Then the update will be verified and you will be asked to confirm whether to go ahead or not.  Finally you will be asked to remove the USB memory device and reboot the system.

   Note: Some of the update steps take several minutes to complete.  There will not necessarily be any visible activity during that time.  Be patient; do not give up or interrupt the process.

References

1. Maxwell – http://www.iwl.com/

2. Network Emulation in the Wikipedia - http://en.wikipedia.org/wiki/Network_emulation

3. Netem – http://linux-net.osdl.org/index.php/Netem

4. IProute2 – http://linux-net.osdl.org/index.php/Iproute2

5. Pareto Distribution – http://en.wikipedia.org/wiki/Pareto_distribution