mosnet

A bare-metal network bootstrap tool for Linux systems, supporting both static IP configuration (with MAC NAT for MAC-restricted environments) and automatic DHCP configuration.

Features

• Dual-mode operation: Automatically detects whether to use static or DHCP configuration
• Dual bridge backends: Linux bridge (no dependencies) or OVS bridge (MAC NAT, OpenFlow)
• MAC NAT: Transparent MAC address rewriting for MAC-restricted environments (e.g., Hetzner) — OVS only
• ARP/NDP Proxy: Responds to ARP (IPv4) and NDP (IPv6) requests for configured IPs — OVS only
• Built-in DHCP client: Full DHCP implementation with lease renewal
• RFC1918 Priority: In DHCP mode, prefers private addresses for interface selection
• IPv6 Support: Static configuration, SLAAC, or DHCPv6 in DHCP mode
• nftables Firewall: Configurable firewall with named services or custom ports
• NAT Support: Masquerading (SNAT) with auto-detection and port forwarding (DNAT)

Installation

Prerequisites

• Rust 1.85+ (2024 edition)
• Linux with netlink support
• Open vSwitch (optional — only needed for mosbridge=ovs)

Building

cargo build --release                          # Default: OVS + Linux bridge
cargo build --release --no-default-features    # Linux bridge only (no OVS dependency)

The binary will be at target/release/mosnet.

Cargo Features

Feature	Default	Description
ovs	yes	OVS bridge, MAC NAT, ARP/NDP proxy controller (requires rovs crates)

A minimal build (--no-default-features) produces a binary with Linux bridge + firewall/NAT but no OVS.

Usage

mosnet reads configuration from the kernel command line (/proc/cmdline). The operating mode is determined automatically based on which parameters are present.

Static Mode

Use static mode when you have a fixed IP address, especially in MAC-restricted environments like Hetzner dedicated servers.

Kernel parameters:

mosip4=<address>,<gateway>,<netmask>[,<device>]
mosip6=<address>/<prefix>,<gateway>[,<device>]

Examples:

Standard network:

mosip4=192.168.1.10,192.168.1.1,255.255.255.0

Hetzner point-to-point configuration:

mosip4=136.243.10.20,136.243.10.1,255.255.255.255
mosip6=2a01:4f8:c17:1234::1/128,fe80::1

With explicit interface:

mosip4=192.168.1.10,192.168.1.1,255.255.255.0,enp3s0

Dual-stack:

mosip4=192.168.1.10,192.168.1.1,255.255.255.0 mosip6=2001:db8::1/64,2001:db8::ffff

DHCP Mode

Use DHCP mode when no static IP is needed. mosnet will probe all interfaces for DHCP offers and select the best one.

Trigger: Absence of both mosip4 and mosip6 parameters.

Optional parameters:

mosdhcp_timeout=<seconds>           # Probe timeout per interface (default: 10)
mosdhcp_prefer_private=yes|no       # Prefer RFC1918 addresses (default: yes)

Examples:

Default DHCP (no parameters needed):

# Just boot without mosip4/mosip6

Custom timeout:

mosdhcp_timeout=30

Prefer public IPs:

mosdhcp_prefer_private=no

Firewall

mosnet includes an nftables-based firewall that can be configured via kernel cmdline.

Parameter:

mosfirewall=<service>[,<service>]...

Named services:

• ssh - TCP port 22
• http - TCP port 80
• https - TCP port 443
• dns - UDP port 53
• dhcp - UDP ports 67, 68

Custom ports:

• <port>/tcp - Custom TCP port
• <port>/udp - Custom UDP port

Special values:

• none - Disable firewall (skip setup entirely)
• permissive - Accept all traffic (creates table but default-accept)

Examples:

SSH only (secure default):

mosfirewall=ssh

Web server:

mosfirewall=ssh,http,https

Custom ports:

mosfirewall=ssh,8080/tcp,51820/udp

Permissive (accept all):

mosfirewall=permissive

The firewall creates an nftables inet table mosnet with:

• Default drop policy for input (unless permissive)
• Allow loopback
• Allow established/related connections
• Allow ICMP and ICMPv6 (ping)
• Allow specified TCP/UDP ports

NAT

mosnet supports Source NAT (masquerading) and port forwarding via nftables.

Parameter:

mosnat=<interface>[,<port_forward>...]

Interface options:

• snat - Auto-detect default gateway interface (recommended)
• eth0 - Specific interface name
• none - Disable NAT

Port forward format:

<external_port>:<internal_ip>:<internal_port>/<protocol>

Examples:

Auto-detect masquerade interface:

mosnat=snat

Masquerade on specific interface:

mosnat=eth0

Masquerade with port forwarding:

mosnat=snat,8080:192.168.1.100:80/tcp

Multiple port forwards:

mosnat=snat,8080:192.168.1.100:80/tcp,2222:192.168.1.100:22/tcp,53:192.168.1.53:53/udp

The NAT creates an nftables table mosnet-nat with:

• Postrouting chain for masquerading outbound traffic
• Prerouting chain for DNAT port forwarding

Bridge Backend

mosnet supports two bridge backends, selectable via kernel cmdline.

Parameter:

mosbridge=ovs|linux

• ovs — OVS bridge with OpenFlow (requires ovs feature + running ovsdb-server/ovs-vswitchd)
• linux — Linux bridge via netlink (no external daemons, always available)
• When not specified: auto-selects OVS if compiled with ovs feature, otherwise Linux bridge

Examples:

mosbridge=linux                    # Force Linux bridge
mosbridge=ovs                      # Force OVS bridge
# (no parameter)                   # Auto-select based on compiled features

Running

Simply execute the binary as root:

sudo ./mosnet

mosnet will:

1. Parse the kernel command line
2. Detect the operating mode (static or DHCP)
3. Discover network interfaces
4. Probe for connectivity (ARP for static, DHCP for dynamic)
5. Select bridge backend (OVS or Linux, based on mosbridge= and compiled features)
6. Create bridge and enslave the physical NIC
7. Configure IP addresses and routes
8. Configure firewall/NAT if specified
9. In static mode + OVS: run the ARP/NDP proxy controller
10. In DHCP mode: handle lease renewal in the background

Environment Variables

• RUST_LOG: Control logging verbosity (e.g., RUST_LOG=debug)

RUST_LOG=debug sudo ./mosnet

Operating Modes Comparison

Aspect	Static Mode	DHCP Mode
Trigger	mosip4 or mosip6 present	No static IP params
Interface selection	ARP probe to gateway	DHCP probe (RFC1918 priority)
IPv4 source	Kernel cmdline	DHCP lease
IPv6 source	Kernel cmdline	SLAAC + DHCPv6
Lease renewal	N/A	Background task (T1/T2)
Use case	Hetzner, MAC-restricted, fixed IP	Standard networks

Bridge Backend Comparison

Aspect	Linux Bridge	OVS Bridge
IP interface	br-mosnet	public (static) / mos (DHCP)
MAC NAT	No	Yes (OpenFlow)
ARP/NDP proxy	Kernel proxy ARP/NDP	OpenFlow controller
Dependencies	None (kernel only)	ovsdb-server, ovs-vswitchd
Host routing	kernel forwarding + proxy ARP/NDP	OpenFlow flows
Hetzner support	No (no MAC NAT)	Yes

Architecture

Both bridge backends use the same physical pattern — the physical NIC is enslaved as a pure L2 port:

Physical NIC (enp3s0) ──► Bridge (br-mosnet)
     │                         │
     │                         ├── Host IP configured here (Linux) or on internal port (OVS)
     │                         └── VM ports (future)
     └── No IP (pure L2 bridge port), MAC inherited by bridge

Linux Bridge

Created via rtnetlink — no external daemons needed. IP is configured directly on the bridge interface (br-mosnet). Host routing uses kernel IP forwarding + proxy ARP/NDP.

OVS Bridge

Created via rovs-ovsdb — requires running ovsdb-server and ovs-vswitchd. IP is configured on an internal port (public for static, mos for DHCP). The internal port inherits the physical NIC's MAC address.

┌─────────────────────────────────────────────┐
│           OVS Bridge: br-mosnet             │
│                                             │
│  ┌─────────────────┐  ┌─────────────────┐  │
│  │ Uplink Port     │  │ Internal Port   │  │
│  │ (physical NIC)  │  │ "public"/"mos"  │  │
│  │ Type: system    │  │ Type: internal  │  │
│  │ No IP           │  │ Host IP here    │  │
│  └─────────────────┘  └─────────────────┘  │
│                                             │
│  OpenFlow: unix socket                      │
└─────────────────────────────────────────────┘

Static Mode Flow

1. Parse mosip4/mosip6 from kernel cmdline
2. Discover physical interfaces via netlink
3. Send ARP probes to find which interface can reach the gateway
4. Select bridge backend (OVS or Linux)
5. Create bridge, enslave physical NIC
6. Configure IP address and routes on bridge interface
7. Configure firewall/NAT if specified
8. OVS only: install MAC NAT flows + run ARP/NDP proxy controller
9. Linux bridge: enable kernel forwarding + proxy ARP/NDP

DHCP Mode Flow

1. Check for absence of static IP parameters
2. Discover physical interfaces via netlink
3. Send DHCP DISCOVER on each interface (raw sockets)
4. Collect DHCP OFFERs and select best interface:
   • Prefer RFC1918 addresses (10.x, 172.16-31.x, 192.168.x)
   • Fall back to global addresses
5. Select bridge backend (OVS or Linux)
6. Create bridge, enslave physical NIC
7. Run full DHCP client (DISCOVER → OFFER → REQUEST → ACK)
8. Configure IP/gateway from lease
9. Configure DNS from lease (/etc/resolv.conf)
10. Enable IPv6 SLAAC (accept_ra=2)
11. Try DHCPv6 for stateful IPv6 (fallback to SLAAC-only)
12. Configure firewall/NAT if specified
13. Spawn background task for lease renewal at T1/T2 timers

The Hetzner Problem

Hetzner dedicated servers have MAC-based filtering at the switch level. Any packet with a source MAC different from the physical NIC's MAC is dropped. This causes problems when:

• Running VMs/containers with their own MAC addresses
• Using virtual network interfaces

mosnet's solution:

1. All traffic flows through an OVS bridge
2. OpenFlow rules rewrite source MACs to the physical NIC's MAC (egress)
3. OpenFlow rules rewrite destination MACs for incoming VM traffic (ingress)
4. ARP/NDP proxy responds to requests for all configured IPs using the physical MAC

This allows VMs and containers to have their own MAC addresses internally while appearing to use the physical MAC externally.

Testing with QEMU

Build the Alpine image

./scripts/build-alpine-image.sh

Output: out/mosnet-alpine-x86_64.img (2 GB raw disk). The image is root-owned after build; fix permissions if needed:

sudo chown $(whoami) out/mosnet-alpine-x86_64.img

Set up the test network

Create a bridge with a tap device and DHCP/DNS server. Pick one of the two options below depending on whether you have OVS installed.

Option A: Linux bridge (no OVS required)

# Create bridge and tap
sudo ip link add mosnet type bridge
sudo ip addr add 10.0.100.1/24 dev mosnet
sudo ip -6 addr add fd00:dead:beef::1/64 dev mosnet
sudo ip link set mosnet up

sudo ip tuntap add dev tap-mosnet mode tap user $(whoami)
sudo ip link set tap-mosnet master mosnet
sudo ip link set tap-mosnet up

# Start dnsmasq as DHCP/DNS server
sudo dnsmasq \
  --conf-file=docs/dnsmasq.conf \
  --pid-file=/tmp/mosnet-dnsmasq.pid

Option B: OVS bridge

sudo ovs-vsctl add-br mosnet
sudo ip addr add 10.0.100.1/24 dev mosnet
sudo ip -6 addr add fd00:dead:beef::1/64 dev mosnet
sudo ip link set mosnet up

sudo ip tuntap add dev tap-mosnet mode tap user $(whoami)
sudo ip link set tap-mosnet up
sudo ovs-vsctl add-port mosnet tap-mosnet

sudo dnsmasq \
  --conf-file=docs/dnsmasq.conf \
  --pid-file=/tmp/mosnet-dnsmasq.pid

Boot the VM

qemu-system-x86_64 \
  -m 1024 \
  -drive file=out/mosnet-alpine-x86_64.img,format=raw \
  -netdev tap,id=net0,ifname=tap-mosnet,script=no,downscript=no \
  -device virtio-net-pci,netdev=net0 \
  -nographic

Login as root (no password). Check mosnet status:

rc-service mosnet status        # OpenRC service status
cat /var/log/mosnet.log         # mosnet output
ip addr show                    # Verify IP from DHCP
ip route show                   # Verify default route
cat /etc/resolv.conf            # Verify DNS

Tear down

Linux bridge:

sudo kill $(cat /tmp/mosnet-dnsmasq.pid)
sudo ip link set tap-mosnet nomaster
sudo ip tuntap del dev tap-mosnet mode tap
sudo ip link del mosnet

OVS bridge:

sudo kill $(cat /tmp/mosnet-dnsmasq.pid)
sudo ovs-vsctl del-port mosnet tap-mosnet
sudo ip tuntap del dev tap-mosnet mode tap
sudo ovs-vsctl del-br mosnet

Static mode testing

Rebuild the image with static IP kernel parameters:

MOSNET_KERNEL_APPEND="mosip4=10.0.100.10,10.0.100.1,255.255.255.0 mosfirewall=ssh" \
  ./scripts/build-alpine-image.sh

Troubleshooting

Check bridge status

Linux bridge:

ip link show br-mosnet
bridge link show

OVS bridge:

ovs-vsctl show
ovs-ofctl dump-flows br-mosnet

Check interface configuration

ip addr show br-mosnet   # Linux bridge
ip addr show public      # OVS static mode
ip addr show mos         # OVS DHCP mode
ip route show

View logs

RUST_LOG=debug sudo ./mosnet
# or
sudo ./mosnet -v

Check firewall rules

nft list table inet mosnet

Check NAT rules

nft list table ip mosnet-nat

Common issues

"no working interface found"

• Ensure at least one physical interface is up
• Check that the gateway is reachable (static mode)
• Verify DHCP server is available (DHCP mode)

"no DHCP offer received"

• Increase timeout: mosdhcp_timeout=30
• Check network connectivity
• Verify DHCP server is running

OVS errors

• Ensure Open vSwitch is installed and running: systemctl status openvswitch-switch
• Check OVS logs: journalctl -u openvswitch-switch
• Or switch to Linux bridge: mosbridge=linux

"mosbridge=ovs requested but 'ovs' feature is not compiled"

• Rebuild with OVS support: cargo build --release (default features include ovs)
• Or use Linux bridge: mosbridge=linux

Firewall blocking traffic

• Check rules: nft list table inet mosnet
• Temporarily disable: mosfirewall=none
• Verify correct ports are open

NAT not working

• Check masquerade interface: nft list table ip mosnet-nat
• Verify IP forwarding: sysctl net.ipv4.ip_forward
• Check routing: ip route

Development

Project Structure

src/
├── main.rs        # Entry point, mode dispatch
├── lib.rs         # Library exports
└── mosnet/
    ├── bridge.rs      # Linux bridge via netlink (always available)
    ├── cmdline.rs     # Kernel parameter parsing
    ├── controller.rs  # ARP/NDP proxy (feature-gated: ovs)
    ├── dhcp/          # DHCP probe and client (modular)
    ├── dns.rs         # DNS from DHCP lease (/etc/resolv.conf)
    ├── firewall.rs    # nftables firewall and NAT
    ├── mode.rs        # Mode detection, bridge backend selection
    ├── netlink.rs     # IP/route/bridge configuration
    ├── ovs.rs         # OVS bridge management (feature-gated: ovs)
    ├── probe.rs       # Interface discovery, ARP probing
    └── error.rs       # Error types
scripts/
└── build-alpine-image.sh   # Alpine image builder
packaging/alpine/
└── rootfs-overlay/         # OpenRC init script for mosnet
docs/
├── dnsmasq.conf            # Test DHCP/DNS server config
└── adr/                    # Architecture decision records

Running Tests

cargo test

Linting

cargo clippy

License

See LICENSE file.

Related Documentation

• docs/PRD.md - Product Requirements Document (as-built v1.0 + roadmap)
• CLAUDE.md - Development guidance
• static-network-params.md - Full kernel parameter specification
• docs/alpine-image.md - Bootable Alpine image builder

Architecture Decision Records

ADR	Title
000	Hetzner Static Config
001	DHCP Mode and Interface Probing
002	DHCP pnet Refactor
003	Feature Gates and Linux Bridge Mode
004	OVS Kernel Module Not Loaded
005	nftables Firewall and NAT
006	DHCP Security Hardening
007	OVS Secure Fail Mode
008	DHCPv6 with SLAAC Fallback
009	Netlink Shared Handle, Atomic DNS, Bridge MAC
010	Daemon Restart and State Recovery
011	Split mosnet into mosnetd (Daemon) + mosnet (CLI)