This project has an ambitious goal of creating a framework for writing NixOS router configurations - in other words, being the simple-nixos-mailserver of the networking world, but without the "simple" part, because networking is hard. This may include complex features like running multiple DHCP servers, using network namespaces, having interfaces turn on and off while the rest of the system keeps working, etc.
Welcome to the NixOS Router documentation. This guide will help you install, configure, and maintain your NixOS-based router.
Quick Links
- Installation Guide - Get started with installing the router
- Upgrading Guide - Learn how to upgrade your router
- Verification - Verify your router is working correctly
- WebUI Documentation - Learn about the web interface features
- Configuration - Configure all aspects of your router
My home internet connection comes with proper dual-stack support. I get a public IPv4 address via DHCP, a /128 (IA_NA) and a /48 IPv6 prefix (IA_PD) via DHCPv6.
Traditionally you would configure your networking via iproute2 and then fork-off a DHCP client to configure the external addresses.
Usually all of that is being hidden from you through wrappers (like Debian’s ifupdown). The configuration would be set, the daemons fired off and hopefully everything would go well.
The limitations of the system become visible once you have a more dynamic set of interfaces that have to be initialized in some order, some VPN device that depend on the uplink connection etc. While systems like ifupdown have employed hooks of all sorts that you still end up writing a bunch of (inlined) shell scripts that deal with some little details of your setup. Adding sleep statements at worst. Things get tricky when one interface going up changes things on another interface or even system wide (think sysctl, iptables, starting a VPN daemon, …).
I decided to switch to NixOS on my router as part of my crusade to switch most of my devices to it. So, here is how I did it! This post is more or less a raw thought stream from during the setup process. It also resembles a tutorial - that is purely because it makes it easier for me to write, this isn't really intended as a tutorial, more as an explanation of what I did - you're free to use this as reference though!
This is the second part of my journey of having NixOS based router on BananaPI R3 board (bpir3) in which I will focus more on the software side of things. The first part is here, however reading it is not essential for understanding of this part.
Before we begin I want to briefly mention that there are two different ways to have a reproducible router. The obvious one that I took is to just install NixOS there and configure it to serve as a router. The other one is to use OpenWRT, write your configuration in a declarative way and render set of uci commands to apply on an OpenWRT instance. You can read more about the second approach here: https://github.com/Mic92/dotfiles/tree/main/openwrt
This collection of nix modules provides a firewall for NixOS machines. This firewall utilizes nftables and uses network zones.
- Quickstart guide — nixos-nftables-firewall documentation
- GitHub - thelegy/nixos-nftables-firewall: A zone based firewall built ontop of nftables for nixos · GitHub
NixOS config tutorial series
Build and share reproducible software environments with Nix and NixOS
What if told you, that you can have a portable Neovim configuration, that runs on any system that has Nix? And that you only need a single nix run command to execute it, without having to clone your .config/neovim and install your plugins?
This manual will eventually describe how to install, use, and extend Home Manager.
- GitHub - nix-community/home-manager: Manage a user environment using Nix [maintainer=@khaneliman, @rycee] · GitHub
- Home Manager - NixOS Wiki
- Home Manager - Official NixOS Wiki
Colmena is a simple, stateless NixOS deployment tool modeled after NixOps and morph, written in Rust. It's a thin wrapper over Nix commands like nix-instantiate and nix-copy-closure, and supports parallel deployment.
Why I replaced my clickable hypervisor with declarative text files
I have officially decommissioned my Proxmox cluster. After years of running my homelab on Proxmox, starting with a single NUC and expanding to a multi-node cluster, I have migrated everything to NixOS running Incus.
I’ve been using NixOS for a while now, primarily to provision my personal and work Mac systems. While Nix can be complex and sometimes challenging to debug, I’ve enjoyed its unique approach to system configuration. However, I haven’t explored much beyond that scope. For some time, I’ve become particularly interested in using it for containers, as NixOS offers compelling features—reproducibility, declarative configuration, and reliable upgrades—which, in theory, make it an excellent choice. How well this theory holds up is something I’m eager to explore further. In this post, I’m documenting my steps for installing NixOS on Proxmox, my chosen virtual environment solution for my home server, as deploying NixOS onto my home server should help me further explore using it for configuring my containers
Nix is a purely functional package manager. This means that it treats packages like values in purely functional programming languages such as Haskell — they are built by functions that don’t have side-effects, and they never change after they have been built. Nix stores packages in the Nix store, usually the directory /nix/store, where each package has its own unique subdirectory such as
/nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
where b6gvzjyb2pg0… is a unique identifier for the package that captures all its dependencies (it’s a cryptographic hash of the package’s build dependency graph). This enables many powerful features.
Let’s talk about Docker and Nix today. Before explaining what Nix is, if you don’t know yet, and before going into the details, I will show you a snippet similar to a Dockerfile for creating a Redis image equivalent to the one in docker hub.
The final image will be around 42mb (or 25mb) in size, compared to 177mb.
EDIT: as mentioned on HN, alpine-based images can even go around 15mb in size.
If you want to try this, the first step is to install Nix.
Podman can run rootless containers and be a drop-in replacement for Docker.
Build Your Own Darknet
Discover the simplest way to re-enter independent computing with our framework. Placing control directly at your fingertips.
Self-hosting services empowers you with greater control and flexibility over your data. However, maintaining such systems today often comes with significant technical challenges, including firewall/NAT configuration, data loss prevention, and security management.
The Clan project aims to lower the technical barriers of self-hosting with NixOS, making it accessible even to non-technical users. Our goal is to simplify the installation and maintenance of NixOS machines.
In this talk, we will present the new NixOS extensions we've developed to scale self-hosting, including VPN integration, backup management, secret management, a unified CLI for installation and updates, and an inventory system for managing clusters of machines.
We will also provide a sneak preview of the upcoming graphical user interface.