Skip to content

RTFM · Networking

Saphira network service and network.d

Saphira networking is plain, ordered configuration under /etc/network.d. The helper validates the whole topology before applying addresses, routes, DNS, DHCP, and supported Open vSwitch objects.

Saphira Linux dragon mascot

What this service owns

The Saphira helper is /sbin/akadata-network-config. It reads active /etc/network.d/*.conf files in bytewise lexical order. One file describes one interface or object. Earlier files must create the things later files consume: a physical link before an OVS bridge port, an OVS bridge before its internal gateway interface, and an address only after its interface exists.

Configuration order and service controls
00-loopback.conf
10-uplink.conf
20-servernet0.conf
30-eno2-servernet0.conf
40-servergw0.conf

# Read-only safety check before changing live state.
/sbin/akadata-network-config validate

# Normal OpenRC service controls.
rc-service network status
rc-service network start
rc-service network stop

The network service records the state it manages under /run/akadata-network so that stop removes its own addresses, routes, DHCP clients, DNS changes, and OVS objects rather than flushing unrelated networking state.

A complete ordinary server example

This example is a server with a fixed IPv4 address, a public documentation IPv6 address, and two DNS resolvers. Replace interface names and addresses only after checking ip link and the upstream router. A static address must be outside a DHCP pool or reserved by the DHCP server; otherwise another machine may be given the same address.

Static dual-stack interface
# /etc/network.d/10-uplink.conf
TYPE=physical
INTERFACE=eno1

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:100::10/64
IPV6_GATEWAY=
IPV6_METRIC=

DNS_SERVERS="192.0.2.53 2001:db8:100::53"
DNS_SEARCH=example.test

IPV4_CIDR and IPV6_CIDR use address/prefix notation. A blank gateway is allowed when there is no default route on that interface. If more than one interface supplies a default route in the same address family, give each an explicit metric so the route choice is predictable.

Apply and prove the result
# Validate first. It must exit successfully before start changes anything.
/sbin/akadata-network-config validate
rc-service network restart

# Prove addresses, routes, DNS, and listeners separately.
ip addr show dev eno1
ip route
ip -6 route
getent hosts example.test
ss -lntup

Prove it works: The host is reachable on the intended network

ip addr shows the two configured addresses, ip route has the expected IPv4 default route, ip -6 route has the expected IPv6 route, and a second host on the same LAN can reach an intentionally enabled service.

DHCP is a client decision, not a router configuration

IPV4_MODE=dhcp or IPV6_MODE=dhcp asks Saphira to use the DHCP client for that family. It does not turn Saphira into a DHCP server. The packaged dhcpcd client receives leases, addresses, routes, and options from an existing network. Server-side DHCP is covered by the network-services chapter.

DHCP client interface
# /etc/network.d/10-uplink.conf
TYPE=physical
INTERFACE=eno1

IPV4_MODE=dhcp
IPV4_CIDR=
IPV4_GATEWAY=
IPV4_METRIC=

IPV6_MODE=dhcp
IPV6_CIDR=
IPV6_GATEWAY=
IPV6_METRIC=

DNS_SERVERS=
DNS_SEARCH=

Do not run another network manager against the same interfaces. A second tool can replace addresses, routes, resolver state, or carrier handling behind Saphira's back and leave a configuration that appears correct only until reboot.

Failure, rollback, and recovery

If validation fails, read the reported file and correct the topology rather than attempting a forced start. If a remote change might cut your access, keep a provider console, physical console, or already-working management VPN. A route or firewall rollback plan is part of the configuration, not an afterthought.

  • An interface named in a file does not exist: compare INTERFACE with ip link, including predictable kernel names such as eno1 or enp3s0.
  • An OVS internal interface appears before its bridge: renumber files so the bridge is created first.
  • Two default routes have no metrics: decide which uplink should win and set explicit metrics.
  • DNS works before a restart but not after: find which service owns resolver configuration; do not let another manager overwrite Saphira networking.