Open vSwitch on Saphira

A hardware switch shuffles Ethernet frames between its ports in silicon. Your Saphira host forwards packets between networks. Between those two worlds sits Open vSwitch: a production-grade software switch that runs inside the operating system itself. It looks to the kernel like a switch you own entirely — you create it, name it, and decide what plugs into it — while behaving like real switching hardware for everything attached.

Open vSwitch is more than a simple bridge. One bridge can carry many tagged VLANs, several physical links can join into one bonded uplink that negotiates LACP with a peer switch, tunnels such as GRE or VXLAN let switches on different machines behave as one, and fine-grained flow rules control or mirror specific traffic. Where a basic Linux bridge answers 'can these interfaces talk?', Open vSwitch answers 'how should this network be built?'

• VLANs: carve one physical uplink into many isolated segments without extra cabling.
• Bonds and LACP: treat two or more cables as one fat, failover-capable link.
• Tunnels: connect switches across hosts and sites over an ordinary IP network.
• Flow rules, mirroring and QoS: observe and steer traffic with switch-level precision.

Think of an OVS bridge purely as a switch: its only job is moving frames between whatever is plugged into it. The interesting design decisions live in the port types, because each kind answers a different question about who — or what — is joining the network.

• Physical port (uplink): a real NIC such as eno4 handed over to the bridge. From that moment the cable belongs to the switch, and the NIC stops being something the host configures directly.
• Internal port: a virtual socket the host itself uses to join its own switch. This is where the host's address lives; on Saphira these are the named gateway interfaces such as igw0 or servergw0. Giving a machine a leg into its own switch sounds odd until you meet it once — then every routing design starts here.
• Patch port: a virtual cable joining two OVS bridges inside the same host, so separate switching domains can have one explicitly controlled Layer-2 connection. Nothing routes across it unless you deliberately route.
• vnet/tap port: the socket a hypervisor creates when a virtual machine boots. Libvirt adds it to your bridge automatically, and from the switch's point of view the VM is just another device on a port.
• Bond: several cables acting as one logical uplink, typically negotiating LACP with the physical switch on the other end.
• Tunnel port: a virtual cable threaded through other networks — GRE, VXLAN or Geneve inside ordinary IP packets — letting switches on different machines behave like ports of one bigger switch.

The tunnel port is what turns Open vSwitch from clever into remarkable. Two hypervisors in different buildings — or on different continents — each run a bridge; VXLAN wraps their frames and carries them across the public Internet between them. Machines on either side share one broadcast domain, one DHCP range, even one MAC-talking-to-MAC relationship. The LAN stretches around the world and still behaves as a single logical network, because to Open vSwitch the tunnel is just another port with peers at both ends.

These examples use raw ovs-vsctl deliberately, so the objects stay visible and unambiguous. On persistent Saphira hosts express the same shape in network.d afterwards; the managed definitions are what survive reboot (the section below explains why).

# Read everything before touching anything.
ovs-vsctl show

# Create a switch, then hand it a physical uplink.
ovs-vsctl add-br br-servers
ovs-vsctl add-port br-servers eno4

# eno4 now belongs to the switch. Do not give it an address:
# addresses belong to the socket the HOST will use instead.

# Join the host itself onto its own switch via an internal port.
ovs-vsctl add-port br-servers sgw0 -- \
+  set Interface sgw0 type=internal

# sgw0 exists now, with no address yet.
ip addr show dev sgw0

One further trick matters when migrating a role that used to live on the bare NIC: other devices on the LAN learned the NIC's MAC address — DHCP leases, ARP caches, port-security rules on upstream switches may all pin to it. Make the OVS side present that same identity and the outside world notices nothing:

# Read the identity the NIC used to wear.
NEW=$(cat /sys/class/net/eno4/address)

# Stamp it onto the bridge so the SWITCH speaks as that NIC.
ovs-vsctl set bridge br-servers other-config:hwaddr="$NEW"

# Or stamp it onto the internal port instead:
ip link set sgw0 address "$NEW"

# Verify the swap from another machine: the same MAC answers,
# now living behind the software switch.
ping -c1 <gateway-address> && ip neigh | grep -i "$NEW"

An OVS bridge is not automatically a router. It is a software switch. Saphira or a guest becomes a router only when an interface on a bridge has an IP address, forwarding is enabled where needed, and nftables allows the selected traffic. Keep the switched layer and routed layer separate in your drawing and configuration.

                     Saphira host

  internet0 ── igw0        public or uplink-facing Layer 3
  servernet0 ─ servergw0   server VLAN / VM network
  datanet0 ─── datagw0     database network
  ns1network0 ─ ns1gw0     nameserver network
  ns0net0 ──── ns0gw0      second nameserver network

  vnet14, vnet15, ...      virtual-machine tap interfaces

A bridge carries frames between its ports. An internal gateway interface
receives the bridge's IP address and is where routing/firewall policy begins.

ovs-vsctl show
ovs-vsctl list bridge
ovs-vsctl list port
ip -br link
ip addr
ip route
ip -6 route

This is a real Saphira routing design using the delegated 2a02:8012:bc57::/48. It is included because it teaches more than a toy AAAA example: each directly connected /64 has a gateway interface, selected remote /64s have a next hop, and the PPP uplink learns its default route from an IPv6 Router Advertisement. These are real addresses from the Saphira team; do not copy them into another network.

2a02:8012:bc57:1::/64      dev eth1       proto kernel
2a02:8012:bc57:3::/64      dev eth0       proto kernel
2a02:8012:bc57:53a::/64    dev ns1gw0     proto kernel
2a02:8012:bc57:db01::/64   dev datagw0    proto kernel
2a02:8012:bc57:face::/64   dev igw0       proto kernel
2a02:8012:bc57:fead::/64   dev servergw0  proto kernel

2a02:8012:bc57:25::/64     via 2a02:8012:bc57:253::2 dev eth0
2a02:8012:bc57:c64c::/64   via 2a02:8012:bc57:fead::c000 dev servergw0
2a02:8012:bc57:f00f::/64   via 2a02:8012:bc57:fead::beef dev servergw0

unreachable 2a02:8012:bc57::/48 dev lo proto dhcp metric 1001
default via fe80::827f:f8ff:fe74:b127 dev ppp0 proto ra metric 1023

• A route marked dev and proto kernel is on-link: the local interface owns that /64 and uses IPv6 Neighbor Discovery to find neighbours.
• A route marked via has a next-hop router. The next-hop address must be reachable on the named interface; it is a route between distinct routed networks, not an OVS switching rule.
• The default via fe80::… on ppp0 was learned by RA. IPv6 default routers commonly use link-local addresses, because a link-local next hop is meaningful only on the specified interface.
• The unreachable /48 guard rejects destinations inside the delegated aggregate that have no more-specific route. It stops an accidental fallback to the Internet for a prefix that this Saphira router owns.

The full table also contains one fe80::/64 route per Ethernet, OVS internal, and vnet link. That is normal IPv6 plumbing. Link-local addresses support Router Advertisements, Neighbour Discovery, and next-hop reachability even when a segment has no global service address.

The same reference host demonstrates how virtual-machine ports and internal gateway ports share bridges. servernet0 carries vnet14, vnet17, vnet18, vnet20, and vnet22 with servergw0 as the routed gateway. datanet0 has vnet16 and datagw0. ns1network0 has vnet15 and ns1gw0. internet0 has vnet21 and igw0. ns0net0 has ns0gw0. Each internal gateway appears as a real OVS Interface of type internal.

Bridge servernet0                 Bridge datanet0
  Port servergw0  type=internal    Port datagw0     type=internal
  Port vnet14                       Port vnet16
  Port vnet17
  Port vnet18                       Bridge ns1network0
  Port vnet20                         Port ns1gw0      type=internal
  Port vnet22                         Port vnet15

Bridge internet0                 Bridge ns0net0
  Port igw0       type=internal    Port ns0gw0      type=internal
  Port vnet21

The bridge's own internal interface is part of normal OVS bridge creation, but the named gateway interface is the deliberate Layer-3 attachment used by the routing design. Give your operators names that describe the job—servergw0, datagw0, igw0—not a mystery address with no role.

Saphira's network service supports physical links, ovs-bridge, ovs-port, and ovs-internal definitions. Put an IP address on the ovs-internal interface, never on a physical ovs-port. The service validates that a port belongs to one declared bridge and that a bridge exists before its dependent internal interface.

# /etc/network.d/20-servernet0.conf
TYPE=ovs-bridge
INTERFACE=servernet0
OVS_PORTS="eno2"
OVS_PROTOCOLS=
OVS_FAIL_MODE=
OVS_DATAPATH_TYPE=
IPV4_MODE=off
IPV6_MODE=off

# /etc/network.d/30-eno2-servernet0.conf
TYPE=ovs-port
INTERFACE=eno2
OVS_BRIDGE=servernet0
IPV4_MODE=off
IPV6_MODE=off

# /etc/network.d/40-servergw0.conf
TYPE=ovs-internal
INTERFACE=servergw0
OVS_BRIDGE=servernet0
IPV4_MODE=static
IPV4_CIDR=192.0.2.1/24
IPV4_GATEWAY=
IPV6_MODE=static
IPV6_CIDR=2001:db8:200::1/64
IPV6_GATEWAY=
DNS_SERVERS=

The physical eno2 is now a Layer-2 member of servernet0. servergw0 is the host's Layer-3 gateway for the server network. Guests attached as vnet ports can be placed on the bridge by the virtualisation layer; do not invent a network.d definition for a vnet device that another system owns.

# Start the OVS daemon, validate the complete Saphira topology, then apply it.
rc-service openvswitch start
/sbin/akadata-network-config validate
rc-service network restart

# Verify that the address belongs to the internal interface.
ovs-vsctl show
ip addr show dev servergw0
ip addr show dev eno2

This small transaction is useful on a non-production laboratory host because it shows the two separate objects: demobridge is the switch, and demogateway0 is the named internal port that could later receive an address. The -- separators make this one OVS database transaction. Do not run it on an edge host unless demobridge and demogateway0 are names you have confirmed are unused.

# Create a switch and a separate internal gateway port.
ovs-vsctl add-br demobridge -- \
+  add-port demobridge demogateway0 -- \
+  set Interface demogateway0 type=internal

# Inspect; no address or route has been created yet.
ovs-vsctl show
ip link show demobridge
ip link show demogateway0

# In a disposable lab only, remove the entire demo bridge.
ovs-vsctl --if-exists del-br demobridge

The native OVS manual's internal-port example next assigns an IP address to the named internal port. In persistent Saphira networking, express that address in the ovs-internal network.d definition instead of using a one-off ip addr add command, so the network service can validate and restore the intended state.

A patch port is a pair of local, virtual Ethernet-like ports that joins two OVS bridges inside one host. It is useful when two separately named switching domains need one explicitly controlled Layer-2 connection. A patch pair is not a route, not a VPN, and not an Internet tunnel. It carries frames; routing and nftables policy are still separate decisions.

# Lab example: make both ends in one OVS transaction.
ovs-vsctl add-port servernet0 patch-to-data -- \
+  set Interface patch-to-data type=patch options:peer=patch-to-server -- \
+  add-port datanet0 patch-to-server -- \
+  set Interface patch-to-server type=patch options:peer=patch-to-data

ovs-vsctl show

ovs-vsctl is the correct inspection and emergency diagnosis tool. Its native syntax includes ovs-vsctl --may-exist add-br bridge and ovs-vsctl --may-exist add-port bridge port. For persistent Saphira-managed bridges, however, write the network.d definitions and let the network service own their lifecycle. Mixing one-off commands and the managed files creates a topology that may disappear, duplicate, or surprise the next operator.

1. 1. Check the daemon

   rc-service openvswitch status must show an operating daemon before ovs-vsctl can describe useful state.

2. 2. Check membership

   ovs-vsctl show must put the expected physical and vnet ports under the intended bridge, exactly once.

3. 3. Check Layer 3

   ip addr must show addresses on the internal gateway interface, not on the OVS port or bridge unless that is the explicitly supported design.

4. 4. Check the policy path

   Use ip route, ip -6 route, nft list ruleset, and a test from a guest or peer. A healthy bridge does not prove routing or firewall permission.

• Control routed traffic with nftables
• Apply OVS in a segmented business design

Open vSwitch repays reading beyond what one manual can cover, and the material below has taught generations of network engineers — including this one. Everything Saphira-specific above is our own; for OVS mechanics in general depth, start here.

• OVN documentation (PDF) — where Open vSwitch thinking goes next
• Connecting OVS bridges with patch ports — Scott Lowe
• Some insight into Open vSwitch configuration (incl. LACP bonds) — Scott Lowe
• OVS integrations with hypervisors/libvirt — Scott Lowe
• VLANs with fake bridges on Open vSwitch — Scott Lowe

Scott Lowe's OVS series in particular is the reference we kept returning to while building these pages. We reworked its ideas into our own words and examples here; read his originals directly for deeper edge cases.