System documentation
Networking
Saphira networking is a small, inspectable configuration layer. It is built around akadata-network, iproute2, dhcpcd, Open vSwitch where configured, and OpenRC service integration.
What Saphira networking is
The configuration helper is /sbin/akadata-network-config. It reads one interface definition per file under /etc/network.d/, validates the complete set, and applies links, addresses, routes, DHCP and DNS.
The OpenRC network service invokes the helper. There is no hidden database: the active configuration is plain shell-style text that can be inspected with normal tools.
Configuration directory
File order is dependency order.
Active files are /etc/network.d/*.conf, loaded in bytewise lexical order. Files ending in .example are documentation and are not loaded. A typical layout is:
00-loopback.conf
10-eth0.conf
20-saphira0.conf
30-sapgw0.confKeep earlier objects before consumers: loopback first, physical links before objects that use them, OVS bridges before OVS ports and internal interfaces, and higher-order virtual interfaces after their parent exists. The implementation also applies OVS in phases (bridges, ports, internal interfaces, then addresses), but the numbered files should still express the topology clearly.
Supported interface types
| TYPE | Purpose | Rules |
|---|---|---|
| physical | Existing kernel link | INTERFACE must already exist; this is the default. |
| ovs-bridge | Open vSwitch bridge | INTERFACE is the bridge name. OVS_PORTS may list physical or declared OVS ports. |
| ovs-port | Existing link attached to OVS | OVS_BRIDGE is required; both address modes must be off; the link must exist. |
| ovs-internal | OVS internal L3 interface | OVS_BRIDGE is required; addresses belong here, not on an OVS port. |
Physical interfaces
Static dual-stack and DHCP are both supported.
Static IPv4 and IPv6
TYPE=physical
INTERFACE=eth0
IPV4_MODE=static
IPV4_CIDR=192.0.2.10/24
IPV4_GATEWAY=192.0.2.1
IPV4_METRIC=
IPV6_MODE=static
IPV6_CIDR=2001:db8:1::10/64
IPV6_GATEWAY=
IPV6_METRIC=
DNS_SERVERS="192.0.2.53 2001:db8::53"
DNS_SEARCH=DHCP for both families
TYPE=physical
INTERFACE=eth1
IPV4_MODE=dhcp
IPV4_CIDR=
IPV4_GATEWAY=
IPV4_METRIC=
IPV6_MODE=dhcp
IPV6_CIDR=
IPV6_GATEWAY=
IPV6_METRIC=
DNS_SERVERS=Each family accepts off, static, or dhcp. Static mode requires a valid CIDR. Gateways may be blank. If multiple static default gateways exist in one family, each gateway needs an explicit metric.
Open vSwitch
20-saphira0.conf — bridge
TYPE=ovs-bridge
INTERFACE=saphira0
OVS_PORTS="eth1"
OVS_PROTOCOLS=
OVS_FAIL_MODE=
OVS_DATAPATH_TYPE=
IPV4_MODE=off
IPV6_MODE=off30-sapgw0.conf — internal interface
TYPE=ovs-internal
INTERFACE=sapgw0
OVS_BRIDGE=saphira0
IPV4_MODE=off
IPV4_CIDR=
IPV4_GATEWAY=
IPV6_MODE=static
IPV6_CIDR=2a02:8012:bc57:f00f::1/64
IPV6_GATEWAY=
DNS_SERVERS=saphira0 is the switch/bridge. sapgw0 is the L3 internal interface, so its IPv6 address is assigned to sapgw0. The bridge definition is placed first so the dependency is visible in the filenames.
30-eth1-ovs.conf — OVS port
TYPE=ovs-port
INTERFACE=eth1
OVS_BRIDGE=saphira0
IPV4_MODE=off
IPV6_MODE=offAn OVS port has no IPv4 or IPv6 configuration. The physical interface is attached to the bridge and its Layer-3 addresses are removed before attachment. The bridge must be declared in the configuration set; put its file earlier than the port file.
Patch ports, tunnels and link aggregation
The current akadata-network-config format does not have a TYPE for OVS patch ports, GRE, VXLAN, bonds, or VPN tunnel devices. Those objects are therefore not managed by the Saphira network service, are not represented by OVS_PORTS, and are not tracked for cleanup under /run/akadata-network. Do not add names such asTYPE=gre, TYPE=vxlan, or TYPE=bond to a network file and expect them to work.
What the underlying packages make possible
- Open vSwitch can provide patch-port connections between bridges, and can provide tunnel ports such as GRE or VXLAN when configured separately with the OVS tooling.
iproute2provides the kernel link and route tooling needed by a separately managed GRE or VXLAN design. The Stage4 VPN profile also includeswireguard-toolsfor WireGuard administration.ipvsadmis packaged and the build tree includes L4 IPVS examples, including direct server return (DSR). IPVS configuration is separate fromakadata-network.
Stretched LAN and L4 DSR
A separately managed, bridged tunnel can present a Layer-2 path between two sites. That can be used for a stretched-LAN design where an IPVS director and real servers share the VIP network. In L4 DSR mode, the director forwards the selected packet and the real server returns traffic directly to the client; the tunnel must carry the required Layer-2/Layer-3 behaviour and the VIP/ARP handling must be correct at every endpoint.
This is a network architecture that Saphira packages can participate in, not a promise that the numbered /etc/network.d files build the tunnel or configure IPVS automatically.
Bonding and aggregate bandwidth
To use two or more physical Ethernet links for aggregate capacity, bonding must be created and managed outside the current Saphira network configuration layer. The resulting bond can then be used as the lower layer for a bridge, VPN, or tunnel design. The same arrangement is required at both ends when the remote side is also being bonded or bridged.
Account for the cost: bonding does not guarantee that one flow uses the sum of all links; the hashing policy, peer capabilities, tunnel/VPN overhead, MTU, CPU cost, and the slowest path determine the usable result. A stretched LAN or bridged VPN also carries broadcast, ARP, control and possible retransmission traffic across the underlay. Measure both aggregate throughput and per-flow throughput before treating the links as equivalent to one faster circuit.
Boundary: create and order these advanced devices with their own tested tooling or service, then attach only the resulting existing interface to anovs-port or a supported physical definition. Keep ownership separate; akadata-network stop will not clean up devices it did not create.
IPv4, IPv6 and DNS
IPV4_CIDR and IPV6_CIDR use address/prefix syntax. Gateways are optional and must be valid for the configured family. IPV4_METRIC and IPV6_METRIC disambiguate multiple default routes.
DNS_SERVERS is a space-separated list of IPv4 or IPv6 server addresses; DNS_SEARCH is an optional search domain. When either is configured, the helper writes a resolver file and records the previous file for restoration on stop. DNS provider selection during first boot is separate: first boot writes the resulting network configuration; this helper consumes it.
This layer does not implement NAT or forwarding policy.
Commands and validation
/sbin/akadata-network-config validate
/sbin/akadata-network-config start
/sbin/akadata-network-config stop
rc-service network start
rc-service network stopvalidate checks configuration without changing links, addresses, routes, DNS or OVS state.
start validates everything first, then applies the configuration. Repeated starts use replace/may-exist operations.
stop removes only state recorded by Saphira networking.
Validation catches missing fields, invalid types or modes, malformed CIDRs and gateways, duplicate interfaces, undeclared or multiply assigned OVS ports, missing bridge declarations, and missing metrics for multiple default gateways.
Start, stop and state ownership
State is recorded under /run/akadata-network. It includes addresses, routes, DHCP interfaces, DNS changes, OVS ports and OVS bridges created by the helper.
On stop, recorded addresses and routes are removed, DHCP is stopped for managed interfaces, the previous resolver file is restored, and only managed OVS ports and bridges are removed. Unrelated addresses and routes are not flushed.
Legacy configuration
/etc/akadata-network.conf is a deprecated compatibility input. When no active /etc/network.d/*.conf files exist, it is converted automatically to /etc/network.d/10-legacy.conf. The legacy file remains for recovery but is not read after migration.
New configurations should use numbered files under /etc/network.d.
How to do it correctly
00-loopback.conf TYPE=physical, INTERFACE=lo
10-eth0.conf physical uplink
20-saphira0.conf TYPE=ovs-bridge, INTERFACE=saphira0
30-eth1-ovs.conf TYPE=ovs-port, OVS_BRIDGE=saphira0
30-sapgw0.conf TYPE=ovs-internal, OVS_BRIDGE=saphira0On start, Saphira validates all files, creates the bridge, attaches physical and internal ports, then applies addresses, routes and DNS. Keep one definition per interface and make the dependency order obvious.
How not to do it
Incorrect ordering
20-sapgw0.conf TYPE=ovs-internal
OVS_BRIDGE=saphira0
30-saphira0.conf TYPE=ovs-bridge
INTERFACE=saphira0A dependent internal interface appears before its bridge. Declare the bridge first and use one consistent numbered topology. Also do not put addresses on anovs-port, define the same interface twice, assign one OVS port to two bridges, use an unsupported TYPE, or apply a malformed CIDR.
Do not run another network manager against the same interfaces. The optional ifupdown package installs an inactive example only; it must not replace akadata-network.
OpenRC integration and design
Stage4 installs /etc/init.d/network. The OpenRC service needs localmount, runs before netmount, and invokes /sbin/akadata-network-config start and stop.
The result is plain text, deterministic lexical ordering, explicit validation, normal command-line inspection, and first-class Open vSwitch support without a proprietary control plane.