photoncloud-monorepo/nix-nos/README.md

Nix-NOS

Generic NixOS network configuration modules. A declarative alternative to VyOS/OpenWrt.

Features

• BGP: BIRD2 and GoBGP backend support for dynamic routing
• Network Interfaces: systemd-networkd based configuration with DHCP, static addresses, gateway, and DNS
• VLANs: Network segmentation with automatic parent interface attachment
• Static Routing: Declarative route tables

Quick Start

Add Nix-NOS as a flake input:

{
  inputs.nix-nos.url = "github:centra/nix-nos";

  outputs = { nix-nos, nixpkgs, ... }: {
    nixosConfigurations.router = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        nix-nos.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

Enable Nix-NOS in your configuration:

{
  nix-nos.enable = true;
}

Modules

nix-nos.bgp

Dynamic routing with BGP support.

nix-nos.bgp = {
  enable = true;
  backend = "bird";        # or "gobgp"
  asn = 65000;             # Local AS number
  routerId = "10.0.0.1";   # BGP router ID

  peers = [
    { address = "10.0.0.2"; asn = 65001; description = "Peer router"; }
  ];

  announcements = [
    { prefix = "203.0.113.0/24"; }
  ];
};

Options:

• enable: Enable BGP routing
• backend: Choose BIRD2 ("bird") or GoBGP ("gobgp")
• asn: Local Autonomous System Number
• routerId: BGP router ID (auto-detected if null)
• peers: List of BGP peers to establish sessions with
• announcements: Prefixes to announce via BGP

nix-nos.interfaces

Declarative network interface configuration using systemd-networkd.

nix-nos.interfaces = {
  eth0 = {
    addresses = [ "192.168.1.10/24" ];
    gateway = "192.168.1.1";
    dns = [ "8.8.8.8" "8.8.4.4" ];
    mtu = 1500;
  };

  eth1 = {
    dhcp = true;
    mtu = 9000;
  };
};

Options (per interface):

• addresses: List of IP addresses in CIDR notation
• gateway: Default gateway (optional)
• dns: List of DNS servers (optional)
• dhcp: Enable DHCP client (boolean, default: false)
• mtu: Maximum Transmission Unit size (optional)

nix-nos.vlans

VLAN configuration with automatic netdev creation and parent interface attachment.

nix-nos.vlans = {
  storage = {
    id = 100;
    interface = "eth0";
    addresses = [ "10.0.100.1/24" ];
    mtu = 9000;
  };

  mgmt = {
    id = 200;
    interface = "eth0";
    addresses = [ "10.0.200.1/24" ];
    gateway = "10.0.200.254";
    dns = [ "10.0.200.53" ];
  };
};

Options (per VLAN):

• id: VLAN ID (1-4094)
• interface: Parent physical interface
• addresses: List of IP addresses in CIDR notation
• gateway: Default gateway (optional)
• dns: List of DNS servers (optional)
• mtu: MTU size for VLAN interface (optional)

nix-nos.routing.static

Static route configuration.

nix-nos.routing.static = {
  routes = [
    { destination = "10.0.0.0/8"; gateway = "192.168.1.254"; }
    { destination = "172.16.0.0/12"; gateway = "192.168.1.254"; }
  ];
};

Examples

See the examples/ directory for complete configuration examples:

• home-router.nix: Simple home router with WAN/LAN setup
• datacenter-node.nix: Data center node with BGP and VLANs
• edge-router.nix: Edge router with multiple VLANs and static routing

Architecture

Nix-NOS uses systemd-networkd as the underlying network backend, providing:

• Declarative configuration
• Atomic network changes
• Integration with NixOS module system
• No runtime dependencies on legacy networking tools

License

MIT OR Apache-2.0

Contributing

This is a generic network configuration system. Please keep contributions free of specific vendor or project references to maintain reusability.