ONL Tutorial

The ONL Tutorial

TOC

Basic Plugin Tests

Even though you have successfully compiled your plugin, there still may be bugs in the code that will cause the plugin to misbehave. Typical signs that there is something wrong with your plugin include:

The plugin doesn't see any traffic.
Traffic doesn't get past the port where a plugin is installed.
The plugin will not respond.

So, our first task is to just see if traffic can flow through the plugin and the plugin continues to respond to our requests for the packet count even at a low traffic rate. This section will show you five tests:

Test 1: Will the plugin load?
Test 2: Will the plugin respond to the Hello command (0) even when you have not sent it any packets?
Test 3: Can you send a few ping packets through the plugin?
Test 4: Can you send ping packets continuously through the plugin?
Test 5: Can you send UDP and TCP packets through the plugin?

These are incrementally more difficult tests. While demonstrating these tests, you will see again how plugins are loaded, instances are created and bound to filters, and simple traffic generators.

We begin by running the RLI and telling it where to look for your plugin. Let's suppose you want to install your plugin at port 3 of a basic NSP cluster with its hosts on ports 1, 2 and 3. Start up the RLI and load a single NSP with default routing at all of the ports. Here is the recipe for adding a user-defined plugin directory:

Window/Panel	Selection/Entry	Explanation
Main RLI panel	Port 3 => Plugin Table	Open plugin and filter table panel
Port 3 Plugins	Edit => Add Plugin Directory	Open dialogue box asking for pathname of parent plugin directory
Dialogue Box	Enter /users/kenw/myplugins	Enter the full pathname (replace kenw with your login name

Now, when you want to create a plugin instance, the RLI will look in both the /users/onl/stdPlugins/ directory and your plugin directory. It looks for subdirectories with names of the form PluginName-Integer and builds an internal table of all subdirectories that contain a combined.o file. So, it should see your myplugins/mycounter-123 subdirectory. We are now ready for our first test.

Test 1 (Load)

In this first test, we will create an instance of the mycounter plugin at port 3, and just see if it can load successfully and respond to a HELLO message. Even though we have not bound the plugin instance to a GM filter and therefore can't send it any packets, we can still see if it loads properly and can respond to a message. In practice, we typically do not perform this test first, but only as a fallback if binding the plugin to a filter fails to function properly. Here is the recipe for loading the mycounter plugin:

Window/Panel	Selection/Entry	Explanation
Port 3 Plugins	Edit => Add Instance => mycounter:1100	Select user-defined plugin. Plugin entry appears.
	Enter spc qid: 8	Packets on FPX queue 136 (=128+8) will go to this plugin
Main RLI window	File => Commit	The instance field should show an instance number (probably 0)

The first time you try to create an instance of a plugin, the plugin will first be loaded and then the instance will be created. If a loading error occurs, a dialogue box will appear indicating a failure to load the plugin. Typically, there are two reasons why the loading might fail:

The SPC did not initialize properly.

You referenced an undefined function.

If the SPC failed to initialize properly, you can try a different port (while testing) or tear down the experiment and commit another experiment. Your mycounter plugin should not have undefined function references but more complicated plugins might. A common error is to assume that you have all functions in the POSIX library (e.g., memset) available to you. The functions available to you are listed in SPC Macros and Functions. You can verify this failure by looking at the log on the CP for the NSP. The CP can be displayed by right clicking on the center of the NSP icon. For example, if your CP is $n1cp, enter the following from a window on onusr:

    onlusr> ssh $n1cp tail /etc/ONL/log.txt

Test 2 (Hello)

If you can successfully create a plugin instance, you can send it a request even though it has not been bound to a filter. Use the RLI to send your plugin instance a HELLO command (0). Here is the recipe:

Window/Panel	Selection/Entry	Explanation
Port 3 Plugins	Edit => Send Command to Instance	Pop up Send Command dialogue box
Send Command	Command ID: 0	Code 0: HELLO
	Select Enter	There are no parameters. Send the command. A message reply box should appear with the response shown below.

If you were successful, a message reply box should appear as shown below. If there is no response but the plugin was loaded, there might be a bug in your handle_msg routine or the SPC has crashed. You can see if the SPC is still alive by sending a message to the SPC kernel from the SPC's CP.

If there is a response but the values shown are incorrect, you may have mistakenly modified the code associated with the HELLO command. You will have to delete the instance, unload the plugin, find/fix the bug, recompile, and create the instance again. The Port 3 Plugins => Edit menu contains items for doing the first two steps and the last step.

Test 3 (A Few Pings)

Now, let's see if we can send a few ping packets through the plugin. By default, the ping command will send a 64-byte ICMP Echo Request (56 bytes of payload, 8 bytes of header, 20 bytes of IP header) once per second. We will bind the plugin to the most general GM filter possible (i.e., all header fields are wild carded). Here is the recipe:

Window/Panel	Selection/Entry	Explanation
Main RLI window	Port 3 => Egress Filters	Filter and plugin tables panel appears
Port 3 Egress Table	Edit => Add General Match Filter
New GM Filter	Enter 0.0.0.0/0 for IP addresses, * for ports and protocol, priority = 56	Matches all packets
	spc qid 8	Should match plugin table entry. qid field should show 136.
	priority 56	Higher priority than RT
Main RLI window	File => Commit	Install GM filter

Now send one ping packet from n1p2 to n1p3 (this assumes that $n1p2 is in your environment):

    onlusr> ssh $n1p2 ping -c 1 n1p3

If you get the standard response, then ICMP request/reply packets made it from n1p2 to n1p3 and back. This doesn't mean that your plugin saw the ping packet. You should verify the following:

Verify that n1p3 got one packet: Enter ssh $n1p3 netstat -i before and after entering the ping command to see that the RX (receive) count has incremented.
Verify that the plugin got one packet: Send a command to the plugin instance to read the packet counter before and after entering the ping command to see that the count has incremented.

If the plugin shows that a packet was received, but the ping command failed you should turn on plugin debugging, recompile with MSR_DEBUG messages endabled, repeat the ping comand and see if the messages from the plugin make sense.

Test 4 (Continuous Pings)

Now, send a continuous sequence of ping packets by enterring:

    onlusr> ssh $n1p2 ping n1p3

Repeat the verification steps in the single-ping packet case.

Test 5 (UDP Packets)

Now, you are ready to send UDP packets. But note that if you have MSR_DEBUG messages enabled, the SPC can only handle a few packets per second. So, you may want to send the UDP packets at a low rate. For example, the iperf command:

    iperf -c n1p3 -u -b 12k

will send UDP packets to n1p3 at 12 Kbps or about one 1500-byte packet every second. If this works, then turn off all debugging output from the plugin and try increasing the iperf sending rate.

Test 6 (TCP Packets)

If your final goal is to handle TCP packets, you have to deal with the SPC loading problem (it can only handle a few packets per second if MSR_DEBUG messages are enabled. The only way to do this is to limit the traffic rate into the plugin to around a few tens of Kbps. And the only way you can do this is through the egress link rate or VOQ rate that feeds the plugin.

Revised: Tue, Aug 15, 2006

Tutorial >> Writing Your First Plugin	TOC