1.\" $OpenBSD: veb.4,v 1.3 2021/10/28 15:06:36 sthen 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: October 28 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 32.Nm veb 33bridge to be used as ports. 34Unlike 35.Xr bridge 4 , 36.Nm veb 37takes over the operation of the interfaces that are added as ports. 38They are then independent of the host network stack: the individual 39Ethernet ports no longer function as independent devices and cannot 40be configured with 41.Xr inet 4 42or 43.Xr inet6 4 44addresses or other layer-3 features themselves. 45.Pp 46The Ethernet network managed by 47.Nm veb 48can be connected to the network stack as a whole by creating a 49.Nm vport 50interface and attaching it as a port to the bridge. 51From the perspective of the host network stack, a 52.Nm vport 53interface acts as a normal interface connected to an Ethernet 54network and can be configured with addresses. 55.Pp 56.Nm veb 57is a learning bridge that maintains a table of Ethernet addresses 58and the port that each address is reachable with. 59The bridge learns about the reachability of Ethernet addresses by 60reading the source address on packets received by ports, and then 61entering the address and port into the table dynamically. 62Static address entries may also be configured in the table, disabling 63dynamic learning for that address. 64Ethernet address learning can be disabled on individual ports. 65.Pp 66When forwarding a packet, the address table is searched for the 67destination Ethernet address and the packet is sent to the associated 68port in the table entry. 69If no entry is found in the table, or the packet is addressed to a 70multicast or broadcast address, the packet is flooded to all other 71ports on the bridge. 72Flooding of packets to unknown unicast addresses can be disabled 73on individual ports. 74.Pp 75.Nm veb 76provides multiple mechanisms for filtering packets traversing the 77bridge. 78By default it filters IEEE 802.1Q VLAN and SVLAN packets, but can 79be configured to forward them by setting the link0 flag. 80.Nm veb 81can filter Ethernet packets entering or leaving ports using bridge 82rules. 83Ports can be configured as members of protected domains to restrict 84communication between them. 85.\" Individual ports can be configured to only allow relaying of IP 86.\" (and ARP/RARP) packets by setting the blocknonip flag. 87.Pp 88.Xr pf 4 89can be used to filter IP packets as they enter or leave the bridge. 90By default this filtering is disabled, but can be enabled by setting 91the link1 flag. 92The exception to this policy is on 93.Nm vport 94interfaces, where 95.Xr pf 4 96runs as packets enter and leave the network stack regardless of 97the value of the link1 flag. 98A consequence of this behaviour is that packets traversing 99.Nm vport 100interfaces appear to travel in the opposite direction to packets 101travelling over other ports. 102.\" Packets traversing vport interfaces get their direction relative 103.\" to the host network stack, while other ports get their direction 104.\" from their relationship to the bridge. 105.\" .Pp 106.\" Transparent 107.\" .Xr ipsec 4 108.\" processing can be enabled by setting the link2 flag on the bridge. 109.Pp 110.Nm veb 111supports the addition of span ports to the bridge. 112Span ports transmit a copy of every packet received by the bridge, 113allowing for passive monitoring of traffic on a separate host. 114.\" .Pp 115.\" .Nm veb 116.\" interfaces support the following 117.\" .Xr ioctl 2 118.\" calls: 119.Sh SEE ALSO 120.Xr ipsec 4 , 121.Xr options 4 , 122.Xr pf 4 , 123.Xr hostname.if 5 , 124.Xr ifconfig 8 , 125.Xr netstart 8 126.Sh HISTORY 127The 128.Nm 129driver first appeared in 130.Ox 6.9 . 131.Sh AUTHORS 132.An David Gwynne Aq Mt dlg@openbsd.org 133