Skip to content

doc: add a HOWTO for vde_router - #75

Merged
danielinux merged 1 commit into
virtualsquare:masterfrom
zirize:doc/vde_router-howto
Oct 4, 2026
Merged

danielinux merged 1 commit into
virtualsquare:masterfrom
zirize:doc/vde_router-howto

Conversation

@zirize

@zirize zirize commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Authored by Claude Code (Claude Opus 5). I reviewed it, ran every command in it
on my own hardware, and I am submitting it.

Depends on #74. Without those fixes vde_router does not forward at all,
so a document describing how to route with it would be describing something
that does not happen. This branch is stacked on that one; GitHub therefore
shows its commits here too, and only the last one belongs to this PR. I can
rebase onto master once #74 lands, or fold this in there, whichever you
prefer.

Why

doc/ carries a HOWTO or a README for most of what vde-2 ships — vde_autolink,
vdeqemu, slirpvde, vde_over_ns, vde_vxlan — and nothing at all for
vde_router.

The manual page (rewritten in #74) is reference material: it says what each
option and each management command does. This is the other half — how to get
from nothing to a working router, and what to look at when it does not work.

What is in it

  • What it is for, and when a switch alone is enough instead.
  • A first router between two switches, with the configuration file and the
    checks that tell you it came up.
  • Putting hosts on it — vdens, qemu, or anything else that speaks to a
    switch — and handing out addresses with the built-in DHCP server.
  • Reaching the outside. This is where people get stuck: vde_router does no
    address translation, so the uplink has to be an interface connected to
    something that does. The slirp plugin as a URL passed straight to connect
    gives a complete userspace gateway in one process, and the section explains
    why slirp's own DHCP server wants a link of its own.
  • Filtering and priorities, including the ordering rule that catches people
    out — rules are evaluated in the reverse of the order they were added.
  • When it does not work: what each management command tells you, and the
    behaviours that look like faults and are not — the first packet towards an
    unresolved next hop is dropped, ARP entries never expire, the DHCP server
    advertises a fixed resolver.

Verification

Every command in the document was run against a live router, not transcribed
from the source: the two-switch example brought up and checked, HTTP carried
between hosts on either segment through it, each ipfilter and queue line
accepted and its effect confirmed in the tables, and the DHCP server observed
handing out a lease.

Plain text, in the style of the other files in doc/, and added to
EXTRA_DIST so it installs with them.

@danielinux
danielinux self-requested a review October 3, 2026 10:36
@danielinux

Copy link
Copy Markdown
Member

Thank you @zirize please rebase + resolve conflicts

doc/ has a HOWTO or a README for most of what vde-2 ships - vde_autolink,
vdeqemu, slirpvde, vde_over_ns, vde_vxlan - and nothing for vde_router.  The
manual page says what each option and command does; this covers the other half,
which is how to arrive at a working router and what to look at when it does
not.

It walks through a first router between two switches, the ways of putting hosts
on the networks it serves, and how to reach the outside - the part people get
stuck on, since vde_router does no address translation and needs an uplink
connected to something that does.  Then filtering and the priority queues, and
a short section on what to check when traffic does not flow, including the
behaviours that look like faults and are not: the first packet towards an
unresolved next hop is dropped, and ARP entries never expire.

Every command in it was run against a live router.

This depends on the fixes in the 'make it forward' series: without them
vde_router does not forward at all, so a document describing how to route with
it would be describing something that does not happen.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@zirize
zirize force-pushed the doc/vde_router-howto branch from eff793b to 4238bda Compare October 3, 2026 12:07
@zirize

zirize commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto master — the PR now carries just the HOWTO commit, and there are no conflicts left. Thanks for the review!

@danielinux

Copy link
Copy Markdown
Member

Thank you for the contribution!

@danielinux
danielinux merged commit 51f387b into virtualsquare:master Oct 4, 2026
2 checks passed
@zirize
zirize deleted the doc/vde_router-howto branch October 4, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants