                    802.1Q VLAN implementation for Linux

                           Updated March 24, 2002
                                Release: 1.6

   MTU  problems exist for many ethernet drivers. Other than that, things
   seem fairly stable!

     PLUG:   Check out my company that makes traffic generation and WAN
       simulation test equipment based on the Linux operating system:
                            Candela Technologies
      Let us help you test your DSL, Cable Access, Satellite and other
                              network systems!

   TIP jar on my home page.

   Join  the  vlan  mailing  list,  After  that,  to  post,  send mail to
   vlan@scry.wanfear.com.

   Submit a bug/issue/enhancement with the: VLAN Bugzilla

   Though I have no real VLAN hardware of my own, I hear that the 2.2/2.4
   kernel patches have worked with these systems:

     * Cisco:   {Catalyst:  6509},  3Com:  {Corebuilder,  Netbuilder  II,
       SuperStack  II  switch  630},  Alpine:  {3804(SMMi,F32Ti)} Extreme
       Ntwks {Summit 48, 48i, 5i} Foundry: {ServerIronXL, FastIron}
     * Alteon  ACENic  Gigabit, 3Com 3c509, realtek RTL8029(AS), RTL8139,
       DEC  DC21140  (tulip),  DFE-570TX  quad-21143, Intel PRO/1000 with
       Intel's driver

   Performance:  The difference in running traffic over VLANs v/s regular
   ethernet  is  very slight. If someone has done some sort of benchmark,
   I'll be happy to place it here!

                          VLAN related Resources.

     * VLAN Installation & Configuration info.
     * CVS Access.
     * VLAN HOWTO/FAQ (Some CISCO & 3COM specific info too.)
     * Another VLAN Recipe (Some info specific to Intel EEPRO Nics too.)
     * VLAN Research page in Japonese
     * VLAN page translated to English
     * IEEE 802.1Q Standard
     * Alternate VLAN implementation.

                                  Features

     * Implements 802.1Q VLAN spec.
     * Can support up to 4094 VLANs per ethernet interface.
     * Scales  well  in  critical  paths:  O(n), where n is the number of
       PHYSICAL ethernet interfaces, and that is only on ingress. O(1) in
       every other critical path, as far as I know.
     * Supports MULTICAST
     * Can change MAC address of VLAN.
     * Multiple naming conventions supported, and adjustable at runtime.
     * Optional  header-reordering,  to make the VLAN interface look JUST
       LIKE  an  Ethernet  interface. This fixes some problems with DHCPd
       and  anything else that uses a SOCK_PACKET socket. Default setting
       is  off, which works for every other protocol I know about, and is
       slightly faster.
     _________________________________________________________________

                                 Change Log

     * Release 1.6 (gz)   For Kernel: 2.4.14+   March 24, 2002:
          + Removed 2.4 kernel patch: It's in the standard kernel now.
          + Updated  vconfig  to  fix  some  compile  issues,  and enable
            cross-compilation  to  the StrongARM platform (changes should
            help other cross-compile attempts too.)
     * Release 1.5 (gz)   For Kernel: 2.4.12-pre5   October 22, 2001:
          + Mostly added other peoples fixes and patches (thanks folks!)
          + Finally fixed mc-list leakage (Ard van Breemen)
          + Flush mc-list at vlan-destory (Ard van Breemen)
          + Add vconfig man page to distribution (Ard van Breemen)
          + Fix  problem  with  /proc  and  renaming  VLAN devices (af AT
            devcon D.T net)
          + Add relatively large change by Nick Eggelston that makes VLAN
            devices  more transparent to tools like tcpdump and other raw
            packet   snoopers.   This  will  only  be  enabled  when  the
            REORDER_HDR flag is set.
     * Release 1.4 (gz)   For Kernel: 2.4.8   August 16, 2001:
          + Code should no longer require /proc interface in order to get
            at the IOCTLs. The IOCTLs are now tied to sockets. When using
            modules, it may auto-load now, too...
          + Fixed format string error in proc fs display.
          + Fixed crash bug relating to memory allocation with locks held
            (we now use GF_ATOMIC)
          + hard_start_xmit  will  now grow the packet header if there is
            not  enough headroom. This may fix an MPLS-over-VLAN problem,
            though  the  real  solution  is  to  make  MPLS allocate more
            headroom anyway...
          + vconfig  was  changed  to  use the new IOCTL API, and the old
            vconfig WILL NOT WORK with this or any newer patches...
     * Release 1.0.3 (gz)   For Kernel: 2.4.7   August 5, 2001:
          + Re-worked  code  to be more stable and more in-line with what
            the  kernel  maintainers want to see before the VLAN patch is
            included into the kernel.
          + One of those requests was to change the default naming scheme
            to  eth0.5,  for  a  VLAN of VID 5 on eth0. You can over-ride
            this naming behaviour with the vconfig tool.
          + There  were *NO* changes to the 2.2 series patch, and I don't
            expect to ever make any more changes there...
     * Release 1.0.1 (gz)   For Kernel: 2.2.18/19, 2.4.3-pre3   April 16,
       2001:
          + Incorporated  a  fix  for  changing  a  MAC on a VLAN, it now
            correctly  sets  PACKET_HOST.  Thanks to Martin Bokaemper for
            this one.
          + The  2.4  series patch should now compile as a module, thanks
            to  a  tweak  from  someone who's mail I have lost! Anyway, 3
            cheers to the un-named coder!
          + There were *NO* changes to the 2.2 series patch, though I did
            verify that it seems to work fine with the 2.2.19 kernel.
     * Release 1.0.0 (gz)   For Kernel: 2.2.18, 2.4.0   Jan 14, 2001:
          + Really  fixed  (and  tested) MAC change-ability. When you set
            the  MAC  address  on a VLAN, it will also attempt to set the
            underlying  device  to  PROMISCious mode (otherwise, the VLAN
            will not receive any packets.)
          + Hashed-device  lookup  is  disabled  by  default because some
            people  had trouble with the 'lo' device. Please feel free to
            re-enable  by  editing the line in net/core/dev.c (search for
            #define BEN_FAST_DEV_LOOKUP).
          + vconfig  should  warn when creating VLAN 1, because that VLAN
            is not compatible with many switches.
     * Release 0.0.15 (gz)   For Kernel: 2.2.18, 2.4.prerelease   Dec 31,
       2000:
          + Merged   most  of  Matti  Aarnio's  patches.  This  means  no
            significant  patch  to eth.c now, and will help port VLANs to
            non-ethernet devices (ie ppp, TokenRing??).
          + Setting  the  MAC  address  should  work  now..I think it was
            broken before.
          + Miscellaneous   code   re-organization  to  make  patches  to
            existing files smaller.
     * Release 0.0.14 (gz)   For Kernel: 2.2.17, 2.4.pre9   Oct 26, 2000:
       This code seems pretty stable.
          + Removed   vlan-space-per-machine,  so  vlan-space-per-NIC  is
            mandatory now.
          + DHCP  might work now, as I've added support for encapsulating
            regular ethernet frames if they are sent to the vlan driver.
          + Fixed  up the name/index hashing stuff to handle changing the
            name on a device.
          + Took out default VID & default priority, as their usefullness
            was in question, and the code was broken anyway.
     * Release 0.0.13 (gz)   For Kernel: 2.2.17, 2.4.pre9   Oct 11, 2000:

               KNOWN TO BE BUSTED, here for posterity's sake.
          + Added  support  for  MULTICAST to the VLAN devices. Thanks to
            Gleb & Co for most of that code.
          + Added  the  ability  to  set the MAC address on the VLAN. For
            now, you'll either need to set your Ethernet NIC into PROMISC
            mode, or maybe figure out some multi-cast ethernet address to
            set on the NIC. This has not been tested well at all.
          + Added a hashed device-name lookup scheme. This greatly speeds
            up  ifconfig  -a.  I  was  able  to  run an ifconfig -a in 20
            seconds on a Celeron 500, with 4000 vlan devices configured!!
          + Added  vlan_test.pl  to  help me find dumb bugs. Feel free to
            make this much more powerful, and send the code back to me!
          + vconfig.c  has  been converted to C code now, instead of C++.
            Thanks to MATHIEU.
          + Significantly cleaned up the code w/out decreasing any useful
            functionality, I believe.
          + Removed the DHCP stuff from the VLAN distribution.
     * Release  0.0.12  (gz)    For Kernel: 2.2.16, 2.4.pre7   August 27,
       2000:
       Added  ability to re-order the VLAN packet so that it looks like a
       real  ethernet  packet  for  the ingress pathway. This should help
       DHCP  and other programs that insist on reading the raw buffer and
       then  make assumptions about byte offsets. I don't have a good way
       to  test  this fully, so consider it experimental :) This behavior
       can  be  changed  at run-time, and is set on a per-VLAN basis. The
       default  is  NOT  to  reorder  the header, which has been the only
       behavior  up  untill this point. The vconfig program can set/clear
       the  flag,  by  using  a VLAN IOCTL. You can read the flag's value
       from the /proc/net/vlan/vlan* files.
       You  can  also  set  a default priority on a NON-VLAN device. This
       priority  will only be used when the default_VID for the device is
       set  as  well. This priority won't be mapped anywhere, just copied
       straight into the skb->priority. It is a uint16.
       The 2.3 patch is now the 2.4 patch, and it has been tested against
       2.4.pre7.
     * Release  0.0.11  (gz)    For Kernel: 2.2.13/14, 2.3.99   April 23,
       2000:
       Added  real  support  for  PRIORITY.  Through IOCTL calls (see the
       vconfig program), you can set explicit ingress and egress mappings
       to/from the VLAN QOS bits and the sk_buff->priority field. This is
       not tested very well, as I don't know much about how people really
       use  the  priority  field...  Took out the round-robin aggretation
       that  went in in rls 0.10, as it was mainly just a hack, and doing
       link  aggregation at a lower level and then putting VLAN on top of
       that virtual device probably makes more sense. The vconfig program
       changed to support the new features..here's it's new usage:
Usage: add             [interface-name] [vlan_id]
       rem             [vlan-name]
       set_dflt        [interface-name] [vlan_id]
       add_port        [port-name]      [vlan_id]
       rem_port        [port-name]      [vlan_id]
       set_egress_map  [vlan-name]      [skb_priority]   [vlan_qos]
       set_ingress_map [vlan-name]      [skb_priority]   [vlan_qos]
       set_name_type   [name-type]
       set_bind_mode   [bind-type]

* The [interface-name] is the name of the ethernet card that hosts
  the VLAN you are talking about.
* The port-name is the name of the physical interface that a VLAN
  may be attached to.
* The vlan_id is the identifier (0-4095) of the VLAN you are operating on.
* skb_priority is the priority in the socket buffer (sk_buff).
* vlan_qos is the 3 bit priority in the VLAN header
* name-type:  VLAN_PLUS_VID (vlan0005), VLAN_PLUS_VID_NO_PAD (vlan5),
              DEV_PLUS_VID (eth0.0005), DEV_PLUS_VID_NO_PAD (eth0.5)
* bind-type:  PER_DEVICE  # Allows vlan 5 on eth0 and eth1 to be unique.
              PER_KERNEL  # Forces vlan 5 to be unique across all devices.
       The  2.3  patches  have  been  ported  foward to 2.3.99, thanks to
       Patrick for the vlanproc.c updates!
     _________________________________________________________________

                        VLAN Setup and Configuration

   To  get  started, you will want to download the latest vlan.X.X.tar.gz
   file (to your $HOME directory.) Unpack it with your favorite commands,
   for  example:  tar -xvzf vlan.1.6.tar.gz Alternatively, you can get it
   from the CVS Repository using something like this:
    1. Install and configure cvs on your machine.
    2. Specify the vlan repository:
       export CVSROOT=:pserver:anonymous@scry.wanfear.com:/home/cvs/vlan
    3. Log in to the repository:
       cvs login     (PASSWORD: anonymous)
    4. Check out the source:
       mkdir vlan; cd vlan; cvs -z3 checkout vlan

   Now, you should have a vlan directory in your home directory. You only
   have  to  patch  the  kernel if you are using Linux 2.4.14 or earlier.
   Now,  read  the  README  or  other  docs  to figure out what kernel it
   patches  against.  A list of mirrors are kept at www.kernel.org. Unzip
   and  un-tar this in your home directory as well, which should create a
   linux   directory   in   your  $HOME  directory.  Example:  tar  -xvzf
   linux-2.2.14.tar.gz

   Now  add the VLAN kernel changes to the kernel if your kernel requires
   it.  I  finally  figured out how to do patches that diff can handle (I
   think  I  did it right at least!). You will find the patch in the vlan
   directory.  It  will  be  called:  vlan.patch,  or  something  equally
   straight-foward. Apply the patch to your kernel:

   cd $HOME/linux
   patch -p 1 < $HOME/vlan/[vlan.patch]

   Your new, patched, kernel should be in your INCLUDE path before trying
   to  compile  the  vconfig program. One way to get things working is to
   link  $HOME/linux to the 'linux' directory that you just un-zipped and
   patched.   A  command  might  be  something  like:  cd  $HOME;  ln  -s
   /home/greear/kernel/2.4/linux.dev linux

   Build the vconfig program in the $HOME/vlan directory:
   cd $HOME/vlan
   make

   Now,  time to compile your new kernel! Use the make xconfig command in
   your  $HOME/linux  directory to select your kernel options. The option
   related  to 802.1Q VLANs is found under the Networking options. If the
   option is not highlighted, make sure you select "Experimental Drivers"
   in one of the first xconfig menus.

   Assuming your kernel compiled cleanly (yell if it didn't and you think
   my  code  broke  it!!), you are now ready to try it out!! Install your
   kernel   in  the  normal  manner  (fix  up  your  /etc/lilo.conf  file
   appropriately  and  run lilo as root.) Reboot your computer and choose
   your new kernel.

   As  your  computer  comes back to life, there will be little sign that
   you are now 802.1Q capable, other than a line spit out during the boot
   process.  There  should  be  a  config  programs  in  your  $HOME/vlan
   directory:  vconfig.  vconfig  is  used  to  create  and  destroy VLAN
   devices.  So,  lets  create  a VLAN device on your first ethernet NIC.
   vconfig<return>  will list a short spiel on how to use it. The vconfig
   command I usually use is:

   vconfig add eth0 5

   This  attempts  to  create a VLAN device with VLAN-ID of 5 on the eth0
   device. If you want to delete a VLAN, use something like:

   vconfig rem eth0.5

   You  will  also  need  to  give  it  an  ip,  eg:  ifconfig  -i eth0.5
   192.168.2.1
   and configure it UP: ifconfig -i eth0.5 up

   NOTE:  You can get lots of VLAN related configuration information from
   the /proc/net/vlan/* files by using 'cat' or 'more' to look at them.

   Please  get  in  contact  with me if you have suggestions, patches, or
   other comments.
     _________________________________________________________________


    greearb@candelatech.com   Ben Greear's Home Page

   Last modified: Sun Mar 24 13:33:26 MST 2002
