Release 1.0
$Id: UserGuide.htm,v 1.13 2003/01/14 11:30:52 joe Exp $
2002 QA Cafe http://qacafe.com
support@qacafe.com
By installing and running this test suite, you are agreeing to the terms
outlined in the LICENSE AGREEMENT. See LICENSE.txt. For more information
contact support@qacafe.com.
This release of lbrouter tests the following areas:
lbrouter can be installed on a debian linux system using the apt interface. QA cafe maintains a debian archive with the latest version of the lbrouter test suite demo and other required software. In order acess the archive using apt-get, you'll need to add the following line to your /etc/apt/sources.list file.
deb http://qacafe.com/debian unstable local
Next update your apt cache using apt-get update
qacafe:/etc/apt# apt-get update
Once apt has been updated, you can run apt-get install to install the lbrouterdemo. apt will install all the required packages. Note: The apt interface can only be used for the demo version of lbrouter (lbrouterdemo). For the full version og lbrouter, follow the dpkg instructions below.
qacafe:/home/joe/lab/lbrouter# apt-get install lbrouterdemo Reading Package Lists... Done Building Dependency Tree... Done The following extra packages will be installed: buddy pktsrc The following NEW packages will be installed: buddy lbrouterdemo pktsrc 0 packages upgraded, 3 newly installed, 0 to remove and 56 not upgraded. Need to get 0B/166kB of archives. After unpacking 1044kB will be used. Do you want to continue? [Y/n] y Selecting previously deselected package pktsrc. (Reading database ... 27255 files and directories currently installed.) Unpacking pktsrc (from .../pktsrc_1.2.16_i386.deb) ... Selecting previously deselected package buddy. Unpacking buddy (from .../archives/buddy_1.2_i386.deb) ... Selecting previously deselected package lbrouterdemo. Unpacking lbrouterdemo (from .../lbrouterdemo_1.0_i386.deb) ... Setting up pktsrc (1.2.16) ... Setting up buddy (1.2) ... Setting up lbrouterdemo (1.0) ...
Once the installation is complete, the lbrouter test suite is ready to run. On debian linux systems, the tests are installed under
/usr/share/doc/lbrouter (or for demo version) /usr/share/doc/lbrouterdemo
lbrouter can also be installed on a debian linux system using dpkg. Download the latest pktsrc*.deb, buddy*.deb, and lbrouter* or lbrouterdemo*.deb packages from http://qacafe.com/lbrouter. Install them using dpkg.
# for demo version ... # dpkg -i pktsrc_1.2.20_i386.deb # dpkg -i buddy_1.5_i386.deb # dpkg -i lbrouterdemo_1.0_i386.deb # for full version ... # dpkg -i pktsrc_1.2.20_i386.deb # dpkg -i buddy_1.5_i386.deb # dpkg -i lbrouter_1.0_i386.deb
lbrouter can be installed using rpm on a redhat linux system. Download the latest pktsrc*.rpm, buddy*.rpm, and lbrouterdemo*.rpm packages. Once downloaded, you can install them directly using rpm.
[root@localhost rlab]# rpm -ivh pktsrc-1.2.16-1.i386.rpm buddy-1.2-1.i386.rpm lbrouterdemo-1.0-1.i386.rpm Preparing... ########################################### [100%] 1:pktsrc ########################################### [ 33%] 2:buddy ########################################### [ 66%] 3:lbrouterdemo ########################################### [100%] [root@localhost rlab]#
Once all the rpm packages have been installed, you will find the lbrouter test suite on red hat systems installed under:
/usr/share/doc/lbrouter (or for demo version) /usr/share/doc/lbrouterdemo
If you are not running on redhat or debian, you will need to build and install pktsrc and buddy. Before doing this, you must have the development headers for Tcl installed. You will also need to build against libpcap. A source version of libpcap is availale on the pktsrc home page.
Download the latest pktsrc*.tgz , buddy*.tgz and lbrouterdemo*.tgz tar files. Untar them in a build directory.
Run the configure script, make, and then as root, make install.
# cd pktsrc-1.2.20 # ./configure -prefix=/usr --with-libpcap=../libpcap-0.4a6 # make # -- now as root # make install # cd buddy-1.5 # ./configure -prefix=/usr # -- now as root # make install
Note: Only pktsrc and buddy need to be built and installed. The lbrouter test suite is runable directly from the untared directory.
You are now ready to run the test suite. The lbrouter test suite requires
root access in order to use pktsrc. You can either run the test suite
directly as root or setup sudo for buddy. However, before you begin, you
must edit the configuration file 'local.conf' to match your test environment.
Basic Configuration
lbrouter can be run on a standard linux PC with 2 ethernet interfaces. The interfaces selected should not be connected to a 'real' network. These interfaces must be configured 'up', but they should not have any IP configuration.
You can find the available network interfaces on your system using the 'ifconfig' command. From this list of interfaces, you can select 2 available network interfaces.
# -- example of interface configuration # ifconfig eth2 eth2 Link encap:Ethernet HWaddr 00:D0:B7:79:8C:DE UP BROADCAST PROMISC MULTICAST MTU:1500 Metric:1 RX packets:755666 errors:0 dropped:0 overruns:0 frame:6 TX packets:39955 errors:0 dropped:0 overruns:201 carrier:0 collisions:0 txqueuelen:100 Interrupt:9 Base address:0xdd00
The networks connecting the lbrouter linux PC to the router should be isolated networks with no other network devices. Generally, the ports can be directly cabled together using an Ethernet cross-over cable or cabled into a hub/switch so that other sniffer tools can be used.
The following is the typical configuration:
The 'local.conf' file lives in the top level directory of the lbrouter test suite. This file contains all the configuration information needed by the test suite to test the router. The configuration must match your actual test setup and configuration of your device under test.
The public and private sides for your test setup must be configured in the local.conf file. Note: The actual IPv4 addresses used for the public and private sides do not have to be public or private as far as IPv4 addresses are concerned (rfc1918). These terms are only used to describe the follow of connections. NAT connections originate on the private side, while load balacing connections originate on the public side. There are no restrictions on actual addresses.
The following parameters must be configured for the private and public
interfaces.
Private Interface Configuration | |
privateInterface | This is the name of the physical device attached to the private network. This should be one of the devices displayed using ifconfig such as eth0, eth1, etc. Note, this device should be configured up, but it should not have its own IP address configured. |
privateIp | This is the IP address of the device under test on the private side. |
privateNextIp | This is the first unused IP address on the private side. The test suite will use this address for any private side hosts that are created. |
privateMask | This is the network mask on the private side interface. |
privateIfMac | This is the Ethernet MAC address to use on the private side interface. If this variable is not specified, the test suite will use the real Ethernet MAC on the network card. |
Public Interface Configuration | |
publicInterface | This is the name of the physical device attached to the public network. This should be one of the devices displayed using ifconfig such as eth0, eth1, etc. Note, this device should be configured up, but it should not have its own IP address configured. Note: This device must be different from the privateInterface. |
publicIp | This is the IP address of the device under test on the public side. |
publicNextIp | This is the first unused IP address on the public side. The test suite will use this address for any public side hosts that are created. |
publicMask | This is the network mask on the public side interface. |
publicIfMac | This is the Ethernet MAC address to use on the public side interface. If this variable is not specified, the test suite will use the real Ethernet MAC on the network card. |
The lbrouter test suite supports two different modes of NAT operation -
basic NAT and NAPT (Network Adress Port Translation). The 'natMode'
variable must be configured to match the NAT mode expected on the
device. You can also set the 'natMode' to none, if you want to skip
all the NAT tests.
Values for natMode variable | |
natAddress | The device is using basic NAT (rfc3022) |
natPort | The device is using Network Port Translation (rfc3022) |
none | Device is not performing NAT, all NAT tests will be skipped |
When the natMode is configured to natAdress, basic NAT will be tested.
The following parameters must be configured.
Basic NAT (natAddress) Configuration Variables | |
addressPoolStart | This is the first IP address that should be used as the outbound public NAT address for basic NAT. Private side addresses from the privateNetStart/End range will be mapped into this address pool. |
addressPoolEnd | This is the last IP address that marks the end of the address pool used for basic NAT. |
privateNetStart | This is the first address on the private side interface that should be translated with basic NAT. Normally, these addresses are on the same network as the privateIp address. Some care should be taken to make sure these addresses to not conflict with any of the configured load balance servers. |
privateNetEnd | This is the last IP address that marks the end of the privateNet address range. All addresses in this range will be mapped to the public side addresses configured in the addressPool. |
When the natMode is configured to natPort, NAPT will be tested.
The following parameters must be configured.
NAPT (natPort) Configuration Variables | |
publicNatIp | This is the public side IP address used by the device. All private side connections will have their source IP address mapped to this address (along with port mapping). |
For the load balancing tests, you must configure the IP address that
is load balanced and the pool of servers. The following parameters
must be configured.
Load Balancing Configuration Variables | |
loadBalanceIp | This is the IP address on the public side of the device used for load balancing. All TCP and UDP connections will use this address as the destination IP address. |
loadBalancePoolStart | This is the IP address of the first load balancing server that will be created on the private side. Normally, these addresses are in the same network as the private side interface. |
loadBalancePoolEnd | This is the IP address of the last load balancing server that will be created on the private side. If the start address is 192.168.1.10 and the end address is 192.168.1.18, 9 load balancing servers will be created for each address in the pool range. HTTP, FTP, and DNS servers are run on each load balance server. |
deadServerTimeout | This is the amount of time in seconds the device needs to detect a dead HTTP server. After this time, the device should forward and new load balance connection to a different server. |
loadBalanceMethod | This is the load balancing method supported by the device. Acceptable values are roundRobin, URL, and none. For URL balancing, the URLs for each server must be configured. |
LB-servern-urls | Each load balacing server may have an optional list of URLs that should be URL balanced to a specific server. The load server number corresponds to its position in the defined load balance server pool range. So LB-server1-urls refers to the urls for the first server, LB-server2-urls refers to the urls for the second server, etc. Each URL should be seperated by a blank space character. |
default-url | This is the url used for all tests that send HTTP GET requests. |
You can also use multiple configuration files. By default, buddy looks
for a file names 'local.conf' in the current directory, but a different
configuration file may be specified using the -config option of buddy.
Running the Tests
Once the test setup has been configured, the tests may be run using buddy. With no arguments, buddy will run all the tests. NOTE: buddy needs to be run with root privilage in order to access the network interfaces of the Linux host.
qacafe:/lab/lbrouter# buddy INFO(setup): starting buddy ... INFO(setup): loaded Tcl Package 'buddy' INFO(setup): loaded Tcl Package 'pktsrc' INFO(setup): pktsrc version is 1.2.18
Depending on the tracing level used during a test run, various messages will be reported. Most test messages have a simple format. The general format is as follows:
Message-Type ( Location ): Timestamp| Text of message
The Message-Type can be either INFO, WARNING, PASS or FAIL. Most messages reported are INFO messages to explain what is happening during the test. WARNING messages are reported by the protocol state machines when an error or unexpected event happens. The PASS and FAIL Message-Types are use to indicate that some part of a test passed or failed.
The Location indicates where the message originated. Messages are associated with different parts of the test. During the initial setup of the test suite, messages will be associated with 'setup'. For example,
INFO(setup): 14:01:07| starting DHCP client on LAN interface eth1
During an actual test, messages that originate from the test case themselves are associated directly with the test case number.
INFO(cdrouter-3): 14:08:44| starting new DHCP client
When event happens on a specific interface, the message is associated with the specific protocol stack on that interface. For example, if an ARP packet is received on the LAN interface, you might see the following message.
INFO(lan): 14:08:45| ARP request, who is 192.168.1.3, tell 192.168.1.3
To see full protocol decodes of the packets sent and received, you can specify the -trace2 option of the command line. The fully decoded packet will be displayed along with the sending or receiving interface.
PACKET-IN(eth1): received eth proto type 0800 ETH: ---- Ethernet Packet (length = 590) ---- ETH: ETH: Source = 00:20:78:d2:bf:a5 ETH: Destination = ff:ff:ff:ff:ff:ff ETH: Type = IPv4 (0x0800) ETH: IPv4: ---- IPv4 Header ---- IPv4: IPv4: Version = 4 IPv4: Header Length = 5 IPv4: TOS byte = 0x00 IPv4: Total Length = 576 IPv4: ID = 0x0001 IPv4: Flags/Offset = 0x0000 IPv4: Don't Fragment = 0 IPv4: More Fragments = 0 IPv4: Offset = 0 IPv4: TTL = 150 IPv4: Protocol = UDP (0x11) IPv4: Checksum = 0x6103 IPv4: Src = 192.168.1.1 IPv4: Dest = 255.255.255.255 IPv4: UDP: ---- UDP Packet ---- UDP: UDP: Source Port = 67 UDP: Destination Port = 68 UDP: Length = 556 UDP: Checksum = 0x525a UDP: DHCP: ---- DHCP Packet ---- DHCP: DHCP: Type = Reply (0x02) DHCP: Hardware Type = 0x01 DHCP: Hardware Address Len = 0x06 DHCP: Hops = 0x00 DHCP: Transaction ID = 0x00408289 (xid) DHCP: Seconds = 0x0000 DHCP: Flags = 0x0000 DHCP: Client IP = 0.0.0.0 (ciaddr) DHCP: Your IP = 192.168.1.2 (yiaddr) DHCP: Server IP = 0.0.0.0 (siaddr) DHCP: Relay IP = 0.0.0.0 (giaddr) DHCP: Client HW Addr = 00:d0:b7:6b:04:2c (chaddr) DHCP: ---- Options ---- DHCP: DHCP: Magic Cookie = 99.130.83.99 DHCP: Message Type = DHCPACK DHCP: Mask = 255.255.255.0 DHCP: Routers DHCP: Router 1 = 192.168.1.1 DHCP: DNS Servers DHCP: DNS Server 1 = 1.1.1.1 DHCP: IP Address Lease Time = 86400 seconds (24.0 hours) DHCP: Server Identifier = 192.168.1.1 DHCP: DHCP: ---- End DHCP Packet ----
Normally, the lbrouter test suite is used to test a single IP device. However, the test suite can be configured to test through a network that contains additional IP devices.
linux host --/public/-- router 1 -- router 2 --- LB device w/lbrouter | | | +--------/private/--------------------------------+
If multiple IP routers are connected between the LB Router and the public interface on the test host, the publicIp and publicNextIp addresses should be set based on the IP addresss of the first router connected to the public side of the test suite. In the topology above, 'publicIp' would be set to router 1's IP address on the public side and 'publicNextIp' would be set to an available IP address on the same network. The 'publicNatIP' or 'loadBalanceIp' variable should be set to the expected public side address of the load balancing device.
Since the additional IP routers change the expected IPv4 hop count between
the private and public interfaces, the 'IPv4HopCount' variable should be set
to the number of IPv4 hops. Normally, this is set to 1.
Getting More out of the test suite
There are several techniques that can be used to increase your testing mileage with the lbrouter test suite.
You can setup a test run that repeats a single test or collection of tests. This is helpful to verify that the router continues to function correctly over time.
Example.
# -- repeat all the NAPT tests until one fails. # buddy -module nat-port.tcl -repeat -until-fail
It is often useful to save the test output for later analysis. There are several ways of doing this, but one useful technique is 'tee'.
Example.
# -- capture output with tee # buddy | tee testrun.log
There are three tracing options that can display different levels of output.
It is often useful to combine 'lbrouter' with other tools to get
different views of events as they happen. tcpdump or ethereal
are good examples.
More Information
More information on buddy's test execution control options can be
found in the buddy README file. On redhat and debian systems, this is
included in the /usr/share/doc/buddy directory.
Getting Help
Help is available through
support@qacafe.com.