*****************
About the "veth"
******************

"veth" is a virtual ethernet device driver and an implementation of the
IEEE 802.3ad (Aggregation of Multiple Link Segment) standard.

"veth" provides multiple virtual interface to kernel (veth0,
veth1...). Each virtual interface works as "aggregator" and it can
contain single or multiple physical interfaces (eth0, eth1...) as its
stuff.

By default maximum number of virtual interfaces are 8 and maximum
number of physical interface is same as number of virtual interfaces.

"vethcfg" utility will support to configure each virtual interface
(aggregator) and it comes with "veth" itself or you can download it from
following WWW page.

http://www.st.rim.or.jp/~yumo



************
Usage
************

1. Extract package
  # cd /usr/src
  # tar xzf veth.tar.gz

2. Apply patch to the kernel. This example shows patching to 2.2.x or
   2.4.x kernel.

  For Linux 2.2.x
  (current directory is /usr/src)
  # patch -p0 < veth-2.2.17.patch

  For Linux 2.4.x
  (current directory is /usr/src)
  # patch -p0 < veth-2.4.x.patch (it depends on the linux version)

3. Rebuild your kernel and modules. Then install it. Don't forget lilo. then reboot.
  E.g.
  # cd linux;
  # make mrproper (linux-2.4, linux-2.6)
  # make menuconfig
  # make dep (linux-2.2, linux-2.4)
  # make bzImage;
  # make modules;
  # make modules_install;
  # make install

4. Build veth and insert module.
  # cd /usr/src/veth
  # make; make install
  # insmod veth

  If you fail to make with many errors, check following linux kernel
  configuration.

  Loadable module support | Set version information on all module symbols

  If it is not checked, delete following compile option on the line
  for compiling veth.o in the Makefile and try again.

  -DMODVERSIONS -include /usr/src/linux/include/linux/modversions.h

  After compiling, you may want to add following line to
  /etc/modules.conf for demand module loading.

  alias veth0 veth

5. Configure link aggregatoion group.
  # vethcfg add eth0 veth0
  # vethcfg add eth1 veth0

6. Make sure all the links are connected with link aggregatable bridge
   and link aggregation group on the bridge is configured correctly.
   If the bridge supports dynamic allocation, you may not have to do
   so because it does automatic link aggregation using key -- i.e. PnP.

7. Configure virtual interface.
  # ifconfig veth0 inet 192.168.1.1 netmask 255.255.255.0 up

8. Check veth status. (Each value depends on your environment. This is
   an example.)
  # cat /proc/net/veth
  S Port   Agg A_KEY P_KEY  PARTNER_SYS     MUX    RECV   PERIO   A_STAT   P_STAT
  S eth0 veth0  0100  001b 0001e6168780    DIST  CURRNT  SLOW_P L_ASCD__ L_ASCD__
  S eth1 veth0  0100  001b 0001e6168780    DIST  CURRNT  SLOW_P L_ASCD__ L_ASCD__
  S eth2 veth0  0100  001b 0001e6168780    DIST  CURRNT  SLOW_P L_ASCD__ L_ASCD__

9. If at least one of port MUX status (belongs to same aggregator) is DIST
   (distributing), then your node can communicate with other nodes via
   veth0 virtual interface.

10. Remove veth module
  # ifconfig veth0 down
  # rmmod veth



*************
Restrictions:
*************

 At this time point, there no ethernet device driver report media
speed, link status and duplex mode by standard way. Therefore "veth"
cannot recognize correct status of such devices. On the other hand, if
"veth" follows the standard, "veth" cannot handle such "unknown" status
devices. i.e. there are no places where "veth" can work. Therefore I
decided to implement a wildcard option (agg_wc) for aggregator until
most of ethernet devices report their status correctly... I introduced
media, link_status and duplex mode field in the net_device_stats
structure with "veth". I hope ethernet device drivers report their
status using it in the future...

 Because of above restrictions, if module parameter "agg_wc" is 1
(enabled; default), "veth" does not comply the standard about following
points.

 - "veth" allows to aggregate unknown (may be different) speed of
   ethernet devices.
 - veth allows unknown duplex mode (may not be full-duplex) devices as
   its stuff.
 - veth recognizes unknown link status (may be link-down) as link up.

Again, after most of ethernet device drivers report their status,
above restrictions will be removed so "veth" will be able to comply the
standard. i.e. "agg_wc" will be changed to 0 (disabled) by default at 
the time point...


Regards, Yumo//                           )))
Katsuyuki Yumoto                         (((
yumo@st.rim.or.jp                        ~~~~
