Hxbt is a STREAMS module/driver which emulates a WAN environment. It
captures packets from IP and manipulates the packets according to the
WAN setup. There are five parameters to control the environment. They
are network propagation delay, bandwidth, drop rate, reordering, and
corruption. Hxbt acts like a "pipe" between two hosts. And the pipe is
the emulated WAN.

Note that the current hxbt implementation only operates on the output
side. Hxbt can be visualized as a emulated router on the outgoing
path.  And the returning path is a "direct" link. In normal
circumstances, this asymmetry should not be a problem as long as the
parameters are set properly to reflect WAN condition on BOTH paths.
For example, if outgoing and incoming paths both introduce a 10ms
delay, set hxbt to emulate a 20ms delay. If incoming and outgoing paths
need to be emulated, set up hxbt in machines on both sides of the
path.


INSTALLATION
------------

1. Download the latest hxbt source from:

	http://opensolaris.org/os/community/networking/

2. unpack the src to a convenient location.

3.1 Copy the precompiled binaries to the appropriate locations 

	SPARC
	cp <src_root>/onnv/usr/src/uts/sparc/hxbt/obj64/hxbt /kernel/drv/sparcv9

	X86
	cp <src_root>/onnv/usr/src/uts/intel/hxbt/obj32/hxbt /kernel/drv
	cp <src_root>/onnv/usr/src/uts/intel/hxbt/obj64/hxbt /kernel/drv/amd64

	Common
	cp <src_root>/onnv/usr/src/uts/common/inet/hxbt/hxbt.conf /kernel/drv

or

3.2 Recompile yourself.

	At present you will need the opensolairs Markfile's to compile
	the source. Stand along Makefiles will be provided soon.

4. Copy the ifhit binary to /usr/sbin

	cp <src_root>/onnv/usr/src/cmd/cmd-inet/usr.sbin/ifhit/ifhit /usr/sbin

5. Create the /dev/hxbt entry

	add_drv -m"* 0666 root root" hxbt


SETUP
-----

To configure hxbt, use the ifconfig (1M) command to put the hxbt
module under IP and above the device.  For example, in a normal Solaris
box, do the following to set up hxbt for bge0 for both IPv4 and IPv6.

Example:

# ifconfig bge0 modlist			# To find the position to put hxbt
0 arp
1 ip
2 bge					# It should be above bge

# ifconfig bge0 modinsert hxbt@2	# Put it at position 2

# ifconfig bge0 modlist			# Check if hxbt is inserted
0 arp
1 ip
2 hxbt
3 bge

# ifconfig bge0 inet6 modlist		# Find the position for IPv6
0 ip
1 bge

# ifconfig bge0 inet6 modinsert hxbt@1

# ifconfig bge0 inet6 modlist		# Verify
0 ip
1 hxbt
2 bge

To remove hxbt from the above system, do the following.

# ifconfig bge0 modremove hxbt@2
# ifconfig bge0 inet6 modremove hxbt@1

Note that the above assumes that there is no other module inserted
above hxbt, so that the position of hxbt does not change.  To
unload the hxbt module from the system.

# modinfo | grep hxbt
 87 10252cc2   1f2b  19   1  hxbt (hxbt stream module v1.1)
 87 10252cc2   1f2b  54   1  hxbt (hxbt stream driver v1.1)
# modunload -i 87


RUNNING
-------

The binary ifhit is also used to control the hxbt module.  The synopsis is

Usage: ifhit [<host> | off]
  [ -z ]
  [ -d <drop rate> | [ -i <drop interval> -n <drop length> [ -o <drop gap>]]]
  [ -l <delay> ]
  [ -b <bandwidth> ]
  [ -r <reorder threshold -R <reorder interval ]
  [ -c <corrupt rate> -C <bytes to corrupt> ]

  <host>: name of host to hit
  off: turn off hxbt for all targets
  -?: usage
  -z: turn off hxbt for this target
  -d <drop rate>: drop rate in %
  -i <drop interval>: interval between drops
  -n <drop length>: how many packets to drop
  -o <drop gap>: (with -n), packets between drops
    NOTE: -d and -i -n are mutually exclusive
  -l <delay>: delay in ms
  -b <bandwidth>: emulated link bandwidth in Kbps, default: interface bandwidth
  -r <reorder threshold>: re-ordering threshold
  -R <reorder interval>: interval between reordering
  -c <corrupt rate>: packet corruption rate in %
  -C <bytes to corrupt>: number of bytes to corrupt per packet

Examples:

1. To emulate a WAN with 50ms propagation delay between the hxbt host
   and the target theta, do:

	ifhit theta -l 50

2. To turn this off, do:

	ifhit theta -z

3. To emulate a WAN to host with IP address a.b.c.d with drop rate 10%,
   bandwidth 14.4Kbps, and delay 20ms, do:

	ifhit a.b.c.d -b 14.4 -d 10 -l 20

4. For every 10 packets sent, drop the next 2 consecutive packets for
   host theta:

	ifhit theta -i 10 -n 2

5. After sending 15 packets, and repeat the following action 3 times:
   drop 1 packet, let 2 packets go.

	ifhit theta -i 15 -n 3 -o 2

6. To corrupt 10% of packets going to theta such that there are 3 bytes
   in each packet which are corrupted.

	ifhit theta -c 10 -C 3

7. Reorder every 5th packet going to theta such that the reordered
   packet is sent at the latest 3 packets after it should be sent.

	ifhit theta -r 3 -R 5

8. To emulate a delay of 50ms to fe80::a00:20ff:fec4:c56e

	ifhit fe80::a00:20ff:fec4:c56e -l 50

9. To know the current hxbt target, do:

	ifhit

   and it will print out the current list.

10. To turn all targets off, do:

	ifhit off

NOTE: before creating any target, it is a good idea to test whether
hxbt is plumbed, i.e. in use.  Run ifhit without argument, it will tell
you if hxbt is plumbed or not.  If it is plumbed, it will print out
something like:

hxbt target list:



LIMITATIONS
-----------

1. When a new set of parameters is specified for a host, the old set is
   erased.  So if you do

	ifhit R -l 50, and then

	ifhit R -d 50

   There will be no propagation delay with the new setup.  And all the
   statistics will be reset.

2. If you first specify a 50ms delay, and then after some time, you
   change that to 20ms, you may not get correct result immediately.
   hxbt needs to finish processing the remaining packets with 50ms
   delay.  Then it will find the 20ms delayed packets.  And it will
   flush them off.  After that, all new packets will have a 20ms
   delay.


BUGS, COMMENTS and QUESTIONS
----------------------------

Please send them to networking-discuss@opensolaris.org.