xref: /freebsd/share/man/man4/vlan.4 (revision ea906c4152774dff300bb26fbfc1e4188351c89a)
1.\"
2.\" Copyright (c) 2001 Yar Tikhiy
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd May 27, 2008
29.Dt VLAN 4
30.Os
31.Sh NAME
32.Nm vlan
33.Nd "IEEE 802.1Q VLAN network interface"
34.Sh SYNOPSIS
35To compile this driver into the kernel,
36place the following lines in your
37kernel configuration file:
38.Bd -ragged -offset indent
39.Cd "device miibus"
40.Cd "device vlan"
41.Ed
42.Pp
43Alternatively, to load the driver as a
44module at boot time, place the following line in
45.Xr loader.conf 5 :
46.Bd -literal -offset indent
47if_vlan_load="YES"
48.Ed
49.Sh DESCRIPTION
50The
51.Nm
52driver demultiplexes frames tagged according to
53the IEEE 802.1Q standard into logical
54.Nm
55network interfaces, which allows routing/bridging between
56multiple VLANs through a single switch trunk port.
57.Pp
58Each
59.Nm
60interface is created at runtime using interface cloning.
61This is
62most easily done with the
63.Xr ifconfig 8
64.Cm create
65command or using the
66.Va cloned_interfaces
67variable in
68.Xr rc.conf 5 .
69.Pp
70To function, a
71.Nm
72interface must be assigned a parent interface and
73numeric VLAN tag using
74.Xr ifconfig 8 .
75A single parent can be assigned to multiple
76.Nm
77interfaces provided they have different tags.
78The parent interface is likely to be an Ethernet card connected
79to a properly configured switch port.
80The VLAN tag should match one of those set up in the switched
81network.
82.Pp
83Initially
84.Nm
85assumes the same minimum length for tagged and untagged frames.
86This mode is selected by the
87.Xr sysctl 8
88variable
89.Va net.link.vlan.soft_pad
90set to 0 (default).
91However, there are network devices that fail to adjust frame length,
92should it fall below the allowed minimum due to untagging.
93Such devices should be able to interoperate with
94.Nm
95after changing the value of
96.Va net.link.vlan.soft_pad
97to 1.
98In the latter mode,
99.Nm
100will pad short frames before tagging them
101so that their length stays not less than the minimum value
102after untagging by the non-compliant devices.
103.Sh HARDWARE
104The
105.Nm
106driver supports efficient operation over parent interfaces that can provide
107help in processing VLANs.
108Such interfaces are automatically recognized by their capabilities.
109Depending on the level of sophistication found in a physical
110interface, it may do full VLAN processing or just be able to
111receive and transmit long frames (up to 1522 bytes including an Ethernet
112header and FCS).
113The capabilities may be user-controlled by the respective parameters to
114.Xr ifconfig 8 ,
115.Cm vlanhwtag
116and
117.Cm vlanmtu .
118However, a physical interface is not obliged to react to them:
119It may have either capability enabled permanently without
120a way to turn it off.
121The whole issue is very specific to a particular device and its driver.
122.Pp
123By now, the list of physical interfaces able of full VLAN processing
124in the hardware is limited to the following devices:
125.Xr age 4 ,
126.Xr bce 4 ,
127.Xr bge 4 ,
128.Xr cxgb 4 ,
129.Xr em 4 ,
130.Xr ixgb 4 ,
131.Xr jme 4 ,
132.Xr msk 4 ,
133.Xr nge 4 ,
134.Xr re 4 ,
135.Xr stge 4 ,
136.Xr ti 4 ,
137.Xr txp 4 ,
138and
139.Xr vge 4 .
140.Pp
141The rest of the Ethernet interfaces can run
142VLANs using software emulation in the
143.Nm
144driver.
145However, some of them lack the capability
146of transmitting and receiving long frames.
147Assigning such an interface as the parent to
148.Nm
149will result in a reduced MTU on the corresponding
150.Nm
151interfaces.
152In the modern Internet, this is likely to cause
153.Xr tcp 4
154connectivity problems due to massive, inadequate
155.Xr icmp 4
156filtering that breaks the Path MTU Discovery mechanism.
157.Pp
158The following interfaces support long frames for
159.Nm
160natively:
161.Xr bfe 4 ,
162.Xr dc 4 ,
163.Xr fwe 4 ,
164.Xr fxp 4 ,
165.Xr gem 4 ,
166.Xr hme 4 ,
167.Xr le 4 ,
168.Xr nfe 4 ,
169.Xr nve 4 ,
170.Xr rl 4 ,
171.Xr sf 4 ,
172.Xr sis 4 ,
173.Xr sk 4 ,
174.Xr ste 4 ,
175.Xr tl 4 ,
176.Xr tx 4 ,
177.Xr vr 4 ,
178and
179.Xr xl 4 .
180.Pp
181The
182.Nm
183driver automatically recognizes devices that natively support long frames
184for
185.Nm
186use and calculates the appropriate frame MTU based on the
187capabilities of the parent interface.
188Some other interfaces not listed above may handle long frames,
189but they do not advertise this ability of theirs.
190The MTU setting on
191.Nm
192can be corrected manually if used in conjunction with such a parent interface.
193.Sh SEE ALSO
194.Xr kqueue 2 ,
195.Xr miibus 4 ,
196.Xr ifconfig 8 ,
197.Xr sysctl 8
198.Sh BUGS
199No 802.1Q features except VLAN tagging are implemented.
200.Pp
201.Dv EVFILT_NETDEV
202events on a
203.Nm
204interface will be sent through
205.Xr kqueue 2
206only if the parent interface uses
207.Xr miibus 4
208for link state notification.
209