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
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?
A config file format for humans.
TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.
Ignition is a utility created to manipulate disks during the initramfs. This includes partitioning disks, formatting partitions, writing files (regular files, systemd units, etc.), and configuring users. On first boot, Ignition reads its configuration from a source of truth (remote URL, network metadata service, hypervisor bridge, etc.) and applies the configuration.
Butane (formerly the Fedora CoreOS Config Transpiler, FCCT) translates human readable Butane Configs into machine readable Ignition Configs. See the getting started guide for how to use Butane and the configuration specifications for everything Butane configs support.
VSCodeVim is a Vim emulator for Visual Studio Code.
- 🚚 For a full list of supported Vim features, please refer to our roadmap.
- 📃 Our change log outlines the breaking/major/minor updates between releases.
- Report missing features/bugs on GitHub.
ifupdown-ng is a network device manager that is largely compatible with Debian ifupdown, BusyBox ifupdown and Cumulus Networks' ifupdown2.
For more information read the admin guide.
For my work on Debian, i want to use my debian.org email address, while for my personal projects i want to use my gmail.com address.
One way to change the user.email git config value is to git config --local in every repo, but that's tedious, error-prone and doesn't scale very well with many repositories (and the chances to forget to set the right one on a new repo are ~100%).
[includeIf "gitdir:~/deb/"]
path = ~/.gitconfig-debSetting up and bootstrapping the zone catalog feature. The requierments are:
- a running knot dns server verion >= 3.0
- configured remote, acl and key sections for a primary/secondary zone transfer setup
Assumptions:
- nsp.domain.tld is the primary nameserver.
- ns1.domain.tld is the secondary nameserver
- There exist valid remote, acl and key configurations for this hosts on the other side
- special catalog zone is name "zone.catalog"
-
Create a zone template for the zones, which will be created on this zone catalog feature
- For the primary nameserver:
- id: "catalog-zone-template"
...
notify: ns1
acl: ns1
...- For the secondary nameserver:
- id: "catalog-zone-template"
...
notify: nsp
acl: nsp
... -
Create the special catalog zone for this feature
- For the primary nameserver:
zone:
- domain: "zone.catalog."
...
notify: ns1
acl: ns1
catalog-role: "interpret"
catalog-template: "catalog-zone-template"- For the secondary nameserver:
zone:
- domain: "zone.catalog."
...
notify: nsp
acl: nsp
catalog-role: "interpret"
catalog-template: "catalog-zone-template" -
Create the content for the special catalog zone. We need to have at least a SOA, NS and TXT resource record:
cat<<EOT | su -c "/usr/bin/knotc" knot
zone-begin zone.catalog
zone-set zone.catalog @ 60 NS nsp.REDACTED.DOM.
zone-set zone.catalog @ 60 SOA nsp.REDACTED.DOM. hostmaster.REDACTED.DOM. 1 16384 2048 1048576 2560
zone-set zone.catalog version 0 TXT "2"
zone-commit zone.catalog
EOT -
Create on the primary nameserver member zone in the special catalog zone.
- Create an unique id for the first member zone:
ZUID="id-$RANDOM-$RANDOM" # generate a random id string
# ZUID="id-$(pwgen -AB 8 1)" # or other method of generating a random id string- And create this zone with the knotc command as user knot:
NEWDOMAIN="my-first-domain.invalid"
cat<<EOT | su -c "/usr/bin/knotc" knot
zone-begin zone.catalog
zone-set zone.catalog id-${ZUID}.zones 0 IN PTR ${NEWDOMAIN%.}.
zone-commit zone.catalog
EOT- The easy thing to oversee is ".zones" part in the in the PTR resource record.
-
Last step: Setup the new domain content.
NEWDOMAIN="my-first-domain.invalid"
cat<<EOZ | su -c /usr/bin/knotc knot
zone-begin ${NEWDOMAIN%.}
zone-set ${NEWDOMAIN%.} @ 60 SOA nshp.REDACTED.DOM. hostmaster.REDACTED.DOM. 1 16384 2048 1048576 2560
zone-set ${NEWDOMAIN%.} @ 60 NS nshp.REDACTED.DOM.
zone-commit ${NEWDOMAIN%.}
EOZ -
Check this new domain content on your secondary nameserver:
NEWDOMAIN="my-first-domain.invalid"
su -c "/usr/bin/knotc zone-read ${NEWDOMAIN%.}." knot
Flux is a tool that automatically ensures that the state of a cluster matches the config in git. It uses an operator in the cluster to trigger deployments inside Kubernetes, which means you don't need a separate CD tool. It monitors all relevant image repositories, detects new images, triggers deployments and updates the desired running configuration based on that (and a configurable policy).
The benefits are: you don't need to grant your CI access to the cluster, every change is atomic and transactional, git has your audit log. Each transaction either fails or succeeds cleanly. You're entirely code centric and don't need new infrastructure.
An OpenStack library for parsing configuration options from the command line and configuration files.
This article provides you a simple solution of how to setup a Kubernetes on multiple nodes using a tool called Ansible.
Repository with copies of my XMPP server configuration for public interest / investigation.
Notes on this setup
- Database backend: PostgreSQL
- Admin web interface and API are disabled
- In-Band registration and web registration are enabled
- Captchas enabled
- Nginx is used as HTTP / Websocket Proxy
- Port 5223 used as TLS port for "XMPP over TLS" feature (Port 443 is forwarded to 5223)
Hey guys. I know I am not good in updating my blog currently, but I have some news to share. I became father few weeks ago. Two months actually. That is the reason why I don’t update my blog so often. Don’t expect a big change in this regard anytime soon :)
But I wanted to write something at least. Last week I migrated from urxvt to xterm, because I noticed that beginning last year (2012), xterm can finally open URLs nicely. This feature was a blocker for me, since I read all my e-mails in mutt and I hate copying links.
During migration, I noticed several nice features of xterm so I decided to write a blog post about some. Let’s start.
aenigma provisions a fully functional and out-of-the-box secure XMPP server you can get running today.
It does for XMPP what Mail-in-a-Box has done for email, Streisand for VPNs, and Easyengine for wordpress.
The installation takes you on a 15 minute, clearly worded, step-by-step setup and takes care of everything automagically.