Details

Reviewers

des
kevans
adrian
allanjude
pauamma_chezdork.com
ziaee
crest_rlwinm.de

Group Reviewers

network
manpages
bridge

Commits

rGdd69f1261ec5: bridge.4: Improve VLAN documentation

Summary

Consider this a draft; there are probably other things we want to
mention and perhaps the wording could be improved.

Document both "legacy" and "VLAN filtering" bridges, but steer users towards VLAN filtering bridges, because this configuration is better in 99% of cases.

Document the interaction between bridge(4) and vlan(4) which is confusing if you don't know what's going on. I haven't gone so far as to say configuring bridge(4) and vlan(4) on the same interface is unsupported, mainly because VLAN filtering bridges solve this problem anyway.

Provides some examples of VLAN filtering bridges, and examples of how to migrate from legacy bridges.

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

Herald added subscribers: ziaee, imp. · View Herald TranscriptJul 6 2025, 8:24 PM

ivy requested review of this revision.Jul 6 2025, 8:24 PM

Harbormaster completed remote builds in B65242: Diff 158067.Jul 6 2025, 8:24 PM

ivy added a parent revision: D51182: bridge: be consistent about PVID terminology.Jul 6 2025, 8:24 PM

fix a couple of tyops

Harbormaster completed remote builds in B65243: Diff 158068.Jul 6 2025, 8:41 PM

tweak wording a bit

Harbormaster completed remote builds in B65244: Diff 158070.Jul 6 2025, 8:55 PM

This is awesome!

share/man/man4/bridge.4
295	Should we use filtered and unfiltered, or some other descriptive title? Using legacy as a name instead of an adjective gets a bit confusing, and doesn't age well if it's still around when a third idea comes out.
324	Should we use RFC style language to improve semantic density?
330	Does it make sense to put numbered examples in an EXAMPLES section?
363	Putting macros in titles is discouraged per mdoc(7)

ivy added inline comments.Jul 6 2025, 11:00 PM

share/man/man4/bridge.4
295	i'm open to other names for the "legacy" bridge configuration, but i'm not sure "unfiltered" really works: an "unfiltered bridge" is not a thing anyone knows about, so it's not very descriptive. "legacy" at least implies "this is the old way of doing it". i would be open to something like "basic bridge" and "VLAN filtering bridge", except i don't really like "basic bridge", but perhaps there's another word we could use here?
324	unless we use that language in other manual pages (which i don't think we do?) i don't think that is more clear.
330	i thought about this and i really prefer having examples inline here, rather than referring to the EXAMPLES section, because it makes it easier for the reader to understand what's going on. trying to explain the configuration without being able to show actual ifconfig commands is quite difficult and ends up being more verbose and less explanatory, at least in my experience. but i'm open to other ways of doing this if you have a better suggestion.
363	noted, but then what is the preferred formatting here?

ivy added inline comments.Jul 6 2025, 11:05 PM

share/man/man4/bridge.4
356	note to self: typo, "a separate STP instances"

fix some instances of ye olde Britishe Englische

Harbormaster completed remote builds in B65249: Diff 158082.Jul 7 2025, 9:07 AM

be consistent about "frames" vs "packets" and "Ethernet address" vs "MAC address"

Harbormaster completed remote builds in B65251: Diff 158096.Jul 7 2025, 11:45 AM

be more clear about how STP works when a vlan(4) is in a bridge.

Suggested by: adrian

Harbormaster completed remote builds in B65252: Diff 158097.Jul 7 2025, 1:51 PM

ivy added a child revision: D51227: bridge: make 802.1ad (Q-in-Q) configurable.Jul 9 2025, 6:42 PM

ivy mentioned this in D51231: bridge: allow VLAN protocol to be configured.Jul 10 2025, 8:45 AM

Nothing jumps out to me regarding spelling and grammar. I'd like someone more familiar with the topic to review the content.

share/man/man4/bridge.4
391	Audience check: how well understood is the DMZ acronym as it relates to networks?

This revision is now accepted and ready to land.Jul 10 2025, 7:16 PM

ziaee added inline comments.Jul 10 2025, 8:47 PM

share/man/man4/bridge.4
295	I do not have any alternative names to propose but I think almost anything is better than legacy almost all the time.
312	Consider using an appositive instead of nested parentheticals. I think appositives always read more clearly than parentheticals, and especially nested parentheticals.
336	Also consider using an appositive.
363	Titles shouldn't have cross-references. I'm not sure I understand this clearly, maybe not because of your writing but just because I'm not a network engineer, but maybe something like "Configuring VLAN-aware bridges" or "Understanding bridge VLAN capture"?
391	Almost all of this is well over my head except DMZ. Afaik DMZ is the first thing they teach you about networking.

copyedit

This revision now requires review to proceed.Jul 11 2025, 2:51 AM

Harbormaster completed remote builds in B65329: Diff 158294.Jul 11 2025, 2:51 AM

ivy added inline comments.Jul 11 2025, 2:56 AM

share/man/man4/bridge.4
312	since we never use the acronym again i've just removed it, and we can also remove "sometimes called" since this term comes from 802.1Q, so it's always called that.
336	the wording here was redundant, so i've changed it to simply say what it meant.
363	this section is about a specific interaction between bridge(4) and vlan(4) in FreeBSD, not about VLANs in general, so i think that should be reflected in the title. i've changed it to use "if_bridge and if_vlan" to make that a bit more clear without using Xr.
391	i think anyone reading this will know what a DMZ is, but that's a detail that isn't actually relevant to the example, so i've reworded it to talk about "isolated networks" instead.

ivy removed a parent revision: D51182: bridge: be consistent about PVID terminology.Jul 28 2025, 2:45 PM

This is a massively good update! Thank you so much! I hope it can be landed soon.

share/man/man4/bridge.4
698	I believe this is supposed to defuntagged 100 to match the vlan ID below? I hope I understand correctly.

ivy added inline comments.Jul 28 2025, 7:41 PM

share/man/man4/bridge.4
698	correct, i will fix this prior to landing

emaste added a subscriber: emaste.Jul 31 2025, 10:22 PM

emaste added inline comments.

share/man/man4/bridge.4
297	I don't like "previous" here without a reference first (previous to what?). Maybe "releases prior to 15.0" or maybe describe filtering first and legacy second?
309	Will it become the default in the future?

ivy added inline comments.Aug 1 2025, 2:59 PM

share/man/man4/bridge.4
297	i was thinking "previous to this release", but i suppose that won't be true when someone is reading this manual page in FreeBSD 20.0. the reason i wrote it this way around is because (at least technically) the vlan filtering bridge is just the same bridge with some extra features, so it felt reasonable to describe the shared features first then describe the extra features. however maybe this isn't the best way to present it to users... if we want users to use the vlan filtering bridge, we could describe that first, then have a short section on the legacy bridge that describes what you can't do and what you might want to do instead (e.g., vlan(4) in a bridge).
309	hard to say. i would like to make "vlanfilter defuntagged 1" the default at some point, but this means people would have to configure IP addresses on `bridge0.1` instead of `bridge0` and i expect a large amount of push-back on that (as we saw with member_ifaddrs) so it may end up being easier to leave things as they are but recommend people use the new setup.

emaste added inline comments.Aug 1 2025, 3:14 PM

share/man/man4/bridge.4
297	Yeah, that's exactly what I was thinking of. We have lots of "new" and "ng" and such which stop being new but don't lose the name - things like newbus. Maybe it's fine here though because it does go on to explain where the new mode arrived.

ivy added inline comments.Aug 1 2025, 3:22 PM

share/man/man4/bridge.4
297	what gives me pause is that it feels strange to describe an optional feature, then describe the default behaviour in a footnote... if we had consensus that vlanfilter will become the default, that would be fine, but otherwise it feels backwards. i can't land this anyway until some other changes have gone in (particularly D51600) so i'll have a think in the mean time and maybe do another pass of the manpage before landing it.

ziaee added inline comments.Aug 1 2025, 5:24 PM

share/man/man4/bridge.4
297	We have lots of "new" and "ng" and such which stop being new but don't lose the name - things like newbus. Yes this is very bad and renaming things after the fact is harder than finding a decent name for them. New/ng/legacy as names really makes me sad, because it is broken and we will never fix it.

Theyre broken to begin with, age unacceptably poorly, and are not descriptive at all. All the worst elements. Almost as bad as $other_os making difficult to remember fantasy names that have no reflection on anything.

ivy added inline comments.Aug 1 2025, 5:29 PM

share/man/man4/bridge.4
297	the difference is that "newbus" is no longer the new bus, it's just the bus, whereas the legacy bridge will always be the legacy bridge (at least until we remove it... but i have no plans for that). a better comparison would be if i'd named these "bridge" and "new bridge", but, anticipating, this problem, i did not :-)

Legacy has a different set of similar problems. It really tells people nothing, and ages poorly. What happens when there's a third one, and we still have to support the first one because of compat?

ivy added a reviewer: bridge.Aug 3 2025, 10:26 PM

ivy mentioned this in rGd43ac3b76ef7: bridge: Make 802.1ad (Q-in-Q) configurable.Aug 5 2025, 7:26 PM

ivy retitled this revision from bridge.4: improve VLAN documentation to bridge.4: Improve VLAN documentation.Aug 6 2025, 3:59 PM

rewrite

update to the current bridge syntax.

with D51760, vlan support in general is less tied to vlan filtering, so we can
describe vlan support first then document filtering as a separate feature.

Harbormaster completed remote builds in B66018: Diff 159874.Aug 6 2025, 4:01 PM

fix tyop

Harbormaster completed remote builds in B66019: Diff 159875.Aug 6 2025, 4:11 PM