Addressing#

Three screens in this section put an address on an interface: the interface panel, Adding an interface, and the add-uplink wizard on Uplinks. They all write the same node — interfaces <type> <name> address <value> — and none of them validates the value: the text is passed through to POST /api/stage as typed, and VyOS accepts or refuses it at commit. This page is what the router will accept, and what each choice then implies.

The three forms of an address value#

Value	What it means
an IPv4 CIDR, `203.0.113.2/24`	a static address with its prefix length
an IPv6 CIDR, `2001:db8:1::1/64`	the same, on the other family
the literal `dhcp`	run a DHCP client on this interface and take what it is given
the literal `dhcpv6`	run a DHCPv6 client on this interface

The hint under the field says exactly this: CIDR, or the literal dhcp / dhcpv6.

An address is added, not replaced. set … address on an interface that already has one leaves both in place, and a VyOS interface holding several addresses is a normal configuration, not a mistake. To move an address you stage the new set and the old delete in the same round, from the interface panel.

The prefix length is not optional#

10.0.20.1 on its own is refused at commit. Write 10.0.20.1/24. A host address on a dummy or loopback interface is /32 for IPv4 and /128 for IPv6.

Which address the pages show you#

Two lists of addresses exist for every interface and they mean different things.

Configured — what the interfaces subtree declares. This is what the Remove address buttons in the interface panel operate on, and what the Uplinks table falls back to when the kernel has not been read.
Live — what the kernel holds, parsed from the inet and inet6 lines of the interface's block. An address from a DHCP lease appears here and not in the configured list, because the configuration only ever said dhcp.

The Interfaces table prefers the live list and filters fe80… out of it. The interface panel shows the live list unfiltered. Where the two disagree — an address configured but not present, or present but not configured — that is drift, and it is the disagreement itself that is the useful signal.

What `dhcp` implies#

Setting an interface's address to dhcp does more than fetch an address. The client also installs a default route through whatever gateway the lease names, which is what turns the interface into an uplink as far as the rest of the product is concerned.

Node	Default	Effect
`interfaces … address dhcp`	—	run the client
`interfaces … dhcp-options default-route-distance <n>`	210	the administrative distance of the route the client installs
`interfaces … dhcp-options no-default-route`	unset	do not install a default route at all

The 210 default is what the agent assumes when the node is absent, and it is why a DHCP uplink loses to a static default route (distance 1) unless you say otherwise — agent/wan.go (defaultRouteDistance).

A PPPoE interface works the same way with different spelling: the distance node is interfaces pppoe <name> default-route-distance and its default is 1, and the opt-out is interfaces pppoe <name> no-default-route.

IPv6#

An IPv6 address is written into the same field and committed the same way. What is different is everything after the commit.

There is no IPv6 forwarding-table view. Static routes reads show ip route, which is IPv4 — agent/opmode.go (handleRoutes).
The uplink model has no IPv6 concept. GET /api/wan looks for default routes named 0.0.0.0/0 and nothing else — agent/wan.go.
The neighbour tab reads show arp, so what it lists is whatever that command prints — Neighbours.
Handing out IPv6 to hosts is router advertisements and, optionally, DHCPv6, both on DHCP and IPv6.

IPv6 is therefore configurable through these screens and has to be inspected from the CLI. This is recorded as a known gap in README.md (Status) and docs/security.md ("No IPv6 in the operational views").

MTU#

The MTU field is on the interface panel and stages set interfaces <type> <name> mtu <n> only when the number differs from the MTU the kernel currently reports. The hint under the field gives the three numbers that matter:

Value	When
1500	plain Ethernet — the default, and right almost everywhere
1492	an interface behind PPPoE, which spends 8 bytes on its own header
up to 9000	jumbo frames, on a path where every device agrees

There is no automatic path-MTU adjustment here and nothing warns you. An MTU larger than the smallest link on the path produces the classic failure: pings work, DNS works, and anything that fills a packet — a TLS handshake, a file copy — hangs. If you raise the MTU on one interface, raise it on the switch and on the far end, and test with a full-size packet before you rely on it.

Lowering an MTU is safe and instant. Raising it is the one to be careful with.

What breaks if you get it wrong#

Prefix length omitted. The commit fails. Nothing is applied; the staged set stays in the Commit Bar until you fix it.
Two interfaces in the same subnet. The commit succeeds. Return traffic picks an interface by the routing table and it may not be the one you meant.
dhcp on a LAN interface. The router becomes a DHCP client on a segment where it was meant to be the server, and — unless no-default-route is set — installs a default route through it at distance 210, which the Uplinks page will then list as an uplink.
Changing the address you are connected through. The session ends at commit. Arm commit-confirm; if the new address is wrong you get the old configuration back after a reboot rather than a router that answers on nothing.
An address the firewall does not expect. Rules that match on a source prefix keep matching the prefix, not the interface. Moving a segment to a new prefix means editing the rules too.