.\"	$NetBSD: vlan.4,v 1.35 2017/05/29 03:41:53 ozaki-r Exp $
.\"
.\" Copyright (c) 2000, 2015 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jason R. Thorpe of Zembu Labs, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 29, 2017
.Dt VLAN 4
.Os
.Sh NAME
.Nm vlan
.Nd IEEE 802.1Q Virtual LAN network device
.Sh SYNOPSIS
.Cd "pseudo-device vlan"
.Sh DESCRIPTION
The
.Nm
interface provides support for
.Tn IEEE
802.1Q Virtual Local Area Networks
.Pq Tn VLAN .
This supports the
trunking of more than one network on a single network interface by using
802.1Q tagged and untagged frames.
.Pp
To use a
.Nm vlan
interface, the administrator must first create the interface and then
specify the VID
.Po
.Tn VLAN
identifier, the first 12 bits from a 16-bit integer which
distinguishes each
.Tn VLAN
from any others
.Pc
and
.Pq parent
physical interface associated with the
.Tn VLAN .
This can be done by using the
.Xr ifconfig 8
.Ic create ,
.Ic vlan ,
and
.Ic vlanif
subcommands from a shell command line or script.
From within a C program, use the
.Xr ioctl 2
system call with the
.Dv SIOCSIFCREATE
and
.Dv SIOCSIFVLAN
arguments.
.Pp
Packets sent through a
.Nm
interface are tagged with the VID and passed to the parent interface for
transmission.
Tagged packets received on the parent interface are passed to the
.Nm
interface with the corresponding VID associated with the parent interface.
Packets sent directly through the parent interface are transmitted as
untagged frames.
Untagged frames received on the parent interface are handled by the
parent interface.
Tagged frames received on the parent interface with a VID of 0 and an
EtherType of IP or IPv6 are processed on the parent interface.
Tagged frames received on the parent interface for which no
.Nm
interface with a matching VID exists are dropped and counted as
.Dq unknown protocol .
.Po
These are displayed by the
.Xr ifconfig 8
.Fl v
option.
.Pc
.Pp
If the
.Nm
pseudo-device is not configured in the kernel only packets tagged with a
VID of 0 are processed.
.Pp
To be compatible with other
.Tn IEEE
802.1Q devices, the
.Nm
interface supports a 1500 byte
.Tn MTU ,
which means that the parent interface will have to handle packets
that are 4 bytes larger than the original
.Tn Ethernet
standard.
.Pp
.Nm
can be used with devices not supporting the
.Tn IEEE
802.1Q
.Tn MTU ,
but then the
.Tn MTU
of the
.Nm
interface will be 4 bytes too small and will not interoperate
properly with other
.Tn IEEE
802.1Q devices, unless the
.Tn MTU
of the other hosts on the
.Tn VLAN
are also lowered to match.
.Sh EXAMPLES
The following will create interface
.Sy vlan0
with VID six, on the
.Tn Ethernet
interface
.Sy tlp0 :
.Bd -literal -offset indent
ifconfig vlan0 create
ifconfig vlan0 vlan 6 vlanif tlp0
.Ed
.Pp
After this set up,
.Tn IP
addresses (and/or other protocols) can be assigned to the
.Sy vlan0
interface.
All other hosts on the
.Tn Ethernet
connected to
.Sy tlp0
which configure a
.Tn VLAN
and use VID six will see all traffic transmitted through
.Sy vlan0 .
.Pp
The same
.Tn VLAN
can be created at system startup time
by placing the following in
.Pa /etc/ifconfig.vlan0 :
.Bd -literal -offset indent
create
vlan 6 vlanif tlp0
.Ed
.Sh SEE ALSO
.Xr bridge 4 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
device first appeared in
.Nx 1.5.1 ,
and was derived from a
.Tn VLAN
implementation that appeared in
.Fx
and
.Ox .
.Sh BUGS
The
.Nm
interfaces do not currently inherit changes made to the physical
interfaces'
.Tn MTU .