ONL NPR Tutorial

The ONL NPR Tutorial

TOC

Predefined Plugins

We introduced the delay plugin earlier. This section introduces you to the other predefined plugins. The predefined plugins have been written by the ONL staff with one of two purposes in mind:

To provide useful functionality; or
To demonstrate some programming feature

Thus, some plugins are more useful to the plugin writer while others are more useful to the plugin user. We call the former type of plugin a demo plugin (or demonstration plugin) and the latter a user plugin. For the most part, demo plugins are not useful by themselves except as coding examples. However, user plugins often contain code that demonstrate some programming feature and can also be useful to the plugin writer. All of the predefined plugins can be used as a base for developing more extended plugins.

The source code and documentation for predefined plugins can be found in the subdirectories of the directory ~onl/npr/plugins/. For example, the source code for the delay plugin is in the directory ~onl/npr/plugins/delay/. You can get the most up-to-date information on predefined plugins by looking at the README files in each of the plugin directories (e.g., ~onl/npr/plugins/delay/README describes the delay plugin). This section gives an overview of the predefined plugins. The page NPR Tutorial => Writing A Plugin => More Useful Code provides some more details of their inner workings.

The following table summarizes the functionality and/or purpose of the predefined plugins. We list the user plugins first followed by the demo plugins.

Plugin	Plugin Type	Description
delay	User	Delay packet X msec. Described in detail in this tutorial. Code shows how to delay packets through the use of a delay thread and the IXPs timestamp CSR.
drop-delay	User	Drop and delay packets. Drops packets probabilistically and delays those that are not dropped.
emulink	User	Emulates the transmission delay of a link with capacity R. Packets of length L experience a delay of L/R plus any queueing delay.
nstats	User	Counts ICMP, TCP and UDP packets and then drops all packets. Stores these three counts in PluginCounters 0, 1 and 2. If you want the packets to reach their destination, use an auxilliary filter to direct packets to the plugin so that the original packet can make it to its destination.
priq	User	Schedules packets based on three priority levels: high, medium and low. The priority is determined by the QID field of the filter that directs the meta-packet to the plugin. All meta-packets are placed in FIFO queue 64 of the chosen output port in priority order.
delay++	User	Delay packet X msec (plugin chaining) Same as the delay plugin but written to conform to the plugin chaining paradigm (plugin chaining is described below).
erd++	User	Early Random Drop (plugin chaining) Monitor the lengths of queues 64-67 at an output port and drop packets with a fixed probability if the queue length is greater than a drop threshold. Defaults are: output port 1; drop probability is 1/128; and threshold is one-fourth of the queue's capacity (i.e., queue threshold).
shaper++	User	Traffic shaper (plugin chaining) Shape traffic using a token bucket parameterized by its average rate (Kbps) and its bucket size or maximum burst (bytes). Defaults are: average rate is 1000 Kbps (1 Mbps); and bucket size is 3000 bytes.

mycount	Demo	Described in detail in this tutorial. Combines the features of the count and debug plugins: Code shows how to display debug messages and handle control messages; Counts packets using both an internal variable and a PluginCounter.
damage	Demo	Damage UDP packets selected deterministically or probabilistically. Modifies the first eight bytes of the payload and zeros the UDP checksum field. Requires use of the packet-pair client/server code pp-sndr and pp-rcvr.
debug	Demo	Code shows how to display debug messages and handle control messages. Counts packets using an internal variable instead of a PluginCounter.
count	Demo	Counts packets using PluginCounter 0 and forward packets. Code shows how to use PluginCounter 0 for monitoring.
drop	Demo	Drops selected packets or drops every kth packet
ipHdr	Demo	Checks IP checksum, TCP/UDP checksum, and IP header length fields. Forwards TCP/UDP packets to other plugins depending on checksum results. Rotates the payload bytes of UDP packets.
null	Demo	Forwards packets. Serves as a starting point for building other plugins.
stringSub	Demo	Replaces all occurrences of the string "hello" with the string "adieu" in the packet payload.

Because the set of predefined plugins continues to grow, these tutorial pages only touch on the most basic ones. Consult the README files in the subdirectories of ~onl/npr/plugins/ for the most up-to-date documentation.

Basic User Plugins

We describe the user plugins in more detail below. But we leave the complete details to the tutorial pages referenced at the beginning of this page and the README files in the source code directories.

The delay Plugin

The delay plugin delays packets for a number of milliseconds. Because numerous examples of its use have been given earlier, we will not describe it further here.

The drop-delay Plugin

The drop-delay plugin is an extension of the delay plugin. The plugin first determines if it should drop a packet. Then, any surviving packet is delayed by a fixed number of milliseconds. The drop selection can be deterministic or probabiliistic. If deterministic, the user specifies a stride value k which causes every kth packet to be dropped. If probabilistic, the user specifies a percentage P which causes P percent of packets to be randomly dropped.

The emulink Plugin

The emulink plugin emulates the delay experienced by a link with capacity R. This is different than setting the port rate in the Queue Table because the port rate setting configures a token bucket regulator. The regulator will allow an initial burst of two maximum sized packets at maximum rate (1 Gbps). But the plugin will always delay the first packet by L/R if L is the length of the packet; i.e., it is delayed by its theoretical transmission delay. If the next packet arrives during the transmission period of the first packet, it will be queued until the first packet's emulated transmission delay has finished. In the long-run, a token bucket with average rate R will have the same long-term average output rate as the emulated link with capacity R.

The nstats Plugin

The nstats plugin counts the number of ICMP, TCP, and UDP packets storing them in the PluginCounters 0, 1, and 2 respectively. If you want the packets to reach their destination, use an auxilliary filter to direct packets to the plugin so that the original packet can make it to its destination. PluginCounters can be easily monitored through the Monitoring => PluginCounter menu item that each NPR has. The next page gives and example of the nstats plugin in use. And the tutorial page NPR Tutorial => Examples => Using An Auxilliary Filter gives a detailed example of its use.

The priq Plugin

The priq plugin implements priority queueing for three traffic priorities: high, medium and low. The priority is based on the QID selected in the filter that directs the meta-packet to the plugin. All packets are placed into queue 64 of the chosen output port in priority order. To do this, it immediately passes all high-priority meta-packets to the Queue Manager, but queues medium- and low-priority packets until queue 64 is empty.

Plugin Chaining Plugins

Plugin chaining is a meta-packet forwarding paradigm that follows these rules:

If the plugin is loaded into plugin ME 4, it will forward all meta-packets to the Queue Manager.
If the plugin is loaded into a plugin ME k where k is not 4, it will forward all meta-packets to plugin ME k+1.

By convention, plugins with names ending in ++ (e.g., shaper++, delay++, erd++) follow the plugin chaining paradigm. An example of a plugin chain might be the plugin sequence shaper++, delay++, erd++ in which traffic is first shaped, then delayed, and finally dropped or forwarded to the Queue Manager depending on the length of its destination queue.

The delay++ Plugin

The delay++ plugin is just the basic delay plugin that has been changed to conform to the plugin chaining rules.

The erd++ Plugin

The erd++ plugin implements the Early Random Drop (ERD) queue management algorithm: it drops packets with a fixed probability if the length of the queue being managed exceeds a threshold. ERD was intended to punish unresponsive, aggressive flows. The idea was that if a large backlog developed, we should drop packets with a fixed probability. The hope was that flows consuming more than their fair share would see their packets dropped. But ERD didn't work well in practice. Since ERD was first developed, better queue management algorithms have been developed such as RED (Random Early Detection), BLUE, Stochastic Fair BLUE, and Queue State DRR.

The shaper++ Plugin

The shaper++ plugin implements traffic shaping using a token bucket; that is, the output of the traffic shaper with burst size B and rate R has a long-term average rate of R with an initial burst of B bytes after a sufficient idle period. Thus, it maintains a constant output rate of R Kbps when sufficiently backlogged but will allow a burst of atmost B bytes if it has been idle long enough. Equivalently, it ensures that the following bound is maintained during a period when a queue is backlogged:

Number of bits transmitted in time t <= R*t + 8*B

More details of the plugins that support chaining can be found in the page NPR Tutorial => Writing A Plugin => More Useful Code

Revised: Fri, Apr 3, 2009

NPR Tutorial >> Router Plugins	TOC