1.\" $OpenBSD: veb.4,v 1.2 2021/02/23 11:43:41 dlg Exp $ 2.\" 3.\" Copyright (c) 2021 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: February 23 2021 $ 18.Dt VEB 4 19.Os 20.Sh NAME 21.Nm veb , 22.Nm vport 23.Nd Virtual Ethernet Bridge network device 24.Sh SYNOPSIS 25.Cd "pseudo-device veb" 26.Sh DESCRIPTION 27The 28.Nm veb 29pseudo-device supports the creation of a single layer 2 Ethernet 30network between multiple ports. 31Ethernet interfaces are added to the bridge to be used as ports. 32.Nm veb 33takes over the operation of the interfaces that are added as ports 34and uses them independently of the host network stack. 35The network stack can be connected to the Ethernet network managed 36by 37.Nm veb 38by creating a 39.Nm vport 40interface and attaching it as a port to the bridge. 41From the perspective of the host network stack, a 42.Nm vport 43interface acts as a normal interface connected to an Ethernet 44network. 45.Pp 46.Nm veb 47is a learning bridge that maintains a table of Ethernet addresses 48and the port that each address is reachable with. 49The bridge learns about the reachability of Ethernet addresses by 50reading the source address on packets received by ports, and then 51entering the address and port into the table dynamically. 52Static address entries may also be configured in the table, disabling 53dynamic learning for that address. 54Ethernet address learning can be disabled on individual ports. 55.Pp 56When forwarding a packet, the address table is searched for the 57destination Ethernet address and the packet is sent to the associated 58port in the table entry. 59If no entry is found in the table, or the packet is addressed to a 60multicast or broadcast address, the packet is flooded to all other 61ports on the bridge. 62Flooding of packets to unknown unicast addresses can be disabled 63on individual ports. 64.Pp 65.Nm veb 66provides multiple mechanisms for filtering packets traversing the 67bridge. 68By default it filters IEEE 802.1Q VLAN and SVLAN packets, but can 69be configured to forward them by setting the link0 flag. 70.Nm veb 71can filter Ethernet packets entering or leaving ports using bridge 72rules. 73Ports can be configured as members of protected domains to restrict 74communication between them. 75.\" Individual ports can be configured to only allow relaying of IP 76.\" (and ARP/RARP) packets by setting the blocknonip flag. 77.Pp 78.Xr pf 4 79can be used to filter IP packets as they enter or leave the bridge. 80By default this filtering is disabled, but can be enabled by setting 81the link1 flag. 82The exception to this policy is on 83.Nm vport 84interfaces, where 85.Xr pf 4 86runs as packets enter and leave the network stack regardless of 87the value of the link1 flag. 88A consequence of this behaviour is that packets traversing 89.Nm vport 90interfaces appear to travel in the opposite direction to packets 91travelling over other ports. 92.\" Packets traversing vport interfaces get their direction relative 93.\" to the host network stack, while other ports get their direction 94.\" from their relationship to the bridge. 95.\" .Pp 96.\" Transparent 97.\" .Xr ipsec 4 98.\" processing can be enabled by setting the link2 flag on the bridge. 99.Pp 100.Nm veb 101supports the addition of span ports to the bridge. 102Span ports transmit a copy of every packet received by the bridge, 103allowing for passive monitoring of traffic on a separate host. 104.\" .Pp 105.\" .Nm veb 106.\" interfaces support the following 107.\" .Xr ioctl 2 108.\" calls: 109.Sh SEE ALSO 110.Xr ipsec 4 , 111.Xr options 4 , 112.Xr pf 4 , 113.Xr hostname.if 5 , 114.Xr ifconfig 8 , 115.Xr netstart 8 116.Sh HISTORY 117The 118.Nm 119driver first appeared in 120.Ox 6.9 . 121.Sh AUTHORS 122.An David Gwynne Aq Mt dlg@openbsd.org 123