.\" $OpenBSD: vlan.4,v 1.13 2001/08/20 05:57:55 mpech Exp $
.\"
.Dd January 9, 2000
.Dt VLAN 4
.Os
.Sh NAME
.Nm vlan
.Nd "IEEE 802.1Q encapsulation/decapsulation pseudo-device"
.Sh SYNOPSIS
.Cd pseudo-device vlan Op Ar count
.Sh DESCRIPTION
The
.Nm
Ethernet interface allows construction of virtual LANs when used in
conjunction with IEEE 802.1Q-compliant Ethernet devices.
.Pp
This driver currently supports the following modes of operation:
.Bl -tag -width abc
.It 802.1Q encapsulation over Ethernet (Ethernet protocol 0x8100)
.Pp
The 802.1Q header specifies the virtual LAN number, and thus allows an
Ethernet switch (or other 802.1Q compliant network devices) to be aware of
which LAN the frame is part of, and in the case of a switch, which
port(s) the frame can go to.
Frames transmitted through the vlan interface will be diverted to the specified
physical interface with 802.1Q vlan encapsulation.
Frames with 802.1Q encapsulation received by the parent interface with the
correct vlan tag will be diverted to the associated vlan pseudo-interface.
.El
.Pp
Frame headers which normally contain the destination host, source host, and
protocol, are altered with additional information.
After the source host,
a 32-bit 802.1Q header is included, with 16 bits for the ether type (0x8100), 3
bits for the priority field (not used in this implementation), 1 bit for
the canonical field (always 0), and 12 bits for the vlan identifier.
Following the vlan header is the actual ether type for the frame and length
information.
.Pp
The network interfaces are named
.Sy vlan Ns Ar 0 ,
.Sy vlan Ns Ar 1 ,
etc.
The number of interfaces is given by the corresponding
.Sy pseudo-device
line in the system config file.
.Xr vlan 4
interfaces support the following unique
.Xr ioctl 2 Ns s :
.Bl -tag -width aaa
.It SIOCSETVLAN:
Set the vlan tag and parent for a given vlan interface.
.It SIOCGETVLAN:
Get the vlan tag and parent for a given vlan interface.
.Pp
.El
.Xr vlan 4
interfaces use the following interface capabilities:
.Bl -tag -width aaa
.It IFCAP_VLAN_MTU:
The parent interface can handle full sized frames, plus the size
of the vlan tag.
.It IFCAP_VLAN_HWTAGGING:
The parent interface will participate in the tagging and untagging of frames.
.El
.Sh DIAGNOSTICS
.Bl -diag
.It "vlan%d: initialized with non-standard mtu %d (parent %s)"
The IFCAP_VLAN_MTU capability was not set on the parent interface.  
We assume in this event that the parent interface is not capable of handling
frames larger then its MTU.   This will generally result in a non-compliant
802.1Q implementation.
.Pp
Some Ethernet chips will either discard or truncate
Ethernet frames that are larger then 1514 bytes.  This causes a problem as
802.1Q tagged frames can be up to 1518 bytes.
Most controller chips can be told not to discard large frames
and/or to increase the allowed frame size.  Refer to the hardware manual
for your chip to do this.
.El
.Pp
If the IFCAP_VLAN_MTU capability is set on a vlan parent,
.Xr vlan 4
assumes that Ethernet chip on the parent can handle
oversized frames.
Either the chip allows 1518 byte frames by default (such as
.Xr rl 4 ) ,
the driver has instructed the chip to do so (such as
.Xr fxp 4 
and
.Xr dc 4 ) ,
or the driver also takes advantage of a hardware tagging capability,
and thus oversized frames are never actually sent or received by
.Ox
(such as
.Xr txp 4
and
.Xr ti 4 ) .
.Sh SEE ALSO
.Xr bridge 4 ,
.Xr inet 4 ,
.Xr ip 4 ,
.Xr netintro 4 ,
.Xr ifconfig 8
.Pp
.Rs
.%T IEEE 802.1Q standard
.%O http://standards.ieee.org/getieee802/802.1.html
.Re
.Pp
The vlan interface is to be configured with
.Xr ifconfig 8 ,
see its manual page for more information.
.Sh BUGS
The 802.1Q specification allows for operation over FDDI and Token Ring
as well as Ethernet.
This driver only supports such operation with Ethernet devices.
.Pp
When the IFCAP_VLAN_HWTAGGING capability is set on the parent interface,
.Xr vlan 4
does not participate in the actual tagging or untagging of Ethernet frames.
It simply passes the vlan ID on to the parent interface for tagging on transmit,
and gets a vlan ID for each packet on receive. 
The vlan tagged packet is not actually visible to
.Ox .
Thus, 
.Xr bpf 4
will show untagged packets on the parent interface, although frames
are actually being transmitted and received with tags on the wire.
.Pp
This driver could be the basis for support of the Cisco ISL VLAN protocol,
detailed at http://www.cisco.com/warp/public/741/4.html .
Unfortunately, public reimplementation of this protocol is currently prevented
by patent (at least in the USA).
.Sh AUTHORS
Originally wollman@freebsd.org.