                    802.1Q VLAN implementation for Linux

                          Updated August 16, 2001
                                Release: 1.4

   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.)
     * 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.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 vlan.tar.gz file (to
   your $HOME directory.) Unpack it with your favorite commands, for
   example: tar -xvzf vlan.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. 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. 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: Thu Aug 16 13:54:45 MST 2001
