#nix-routeros

Declarative MikroTik RouterOS configuration using Nix. Define your router config with NixOS-module-style options, generate Terraform JSON via terranix, and apply with OpenTofu.

#Quick Start

# Initialize from template
nix flake init -t github:aleks-sidorenko/nix-routeros

# Edit router.nix with your network settings, then:
export FLAKE_DIR=$(pwd)
nix run .#default          # Show generated Terraform JSON
nix run .#default.plan     # Plan changes
nix run .#default.apply    # Apply to router

#Usage

Add nix-routeros as a flake input:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    terranix = {
      url = "github:terranix/terranix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    nix-routeros = {
      url = "github:aleks-sidorenko/nix-routeros";
      inputs.nixpkgs.follows = "nixpkgs";
      inputs.terranix.follows = "terranix";
    };
  };

  outputs = { nixpkgs, nix-routeros, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      packages.${system}.default = nix-routeros.lib.mkRouterDerivation {
        inherit pkgs system;
        modules = [ ./router.nix ];
      };
    };
}

Create router.nix with your configuration:

{
  routeros = {
    connection.gateway = "10.0.0.1";

    network = {
      subnet = "10.0.0.0/24";
      dhcp.server.range = "10.0.0.50-10.0.0.250";
    };

    bridge.ports = [ "ether2" "ether3" "ether4" "ether5" ];

    hosts.server = {
      ip = "10.0.0.10";
      mac = "AA:BB:CC:DD:EE:FF";
      comment = "Home server";
      aliases = [ "jellyfin" "home-assistant" ];
    };

    wifi = {
      enable = true;
      ssid = "MY-NETWORK";
      country = "united states";
    };
  };
}

For a full production example with SOPS secrets, WiFi, LTE, custom firewall rules, and 11 managed hosts, see aleks-sidorenko/nix-config/infra/router.

#Generated Scripts

mkRouterDerivation produces a derivation with four scripts (where name defaults to "router"):

The plan, apply, and destroy scripts require the FLAKE_DIR environment variable to be set to the flake root directory. They:

1. Decrypt secrets from SOPS (if secretsFile and secrets are configured)
2. Copy the generated config.tf.json into stateDir
3. Run tofu init and the corresponding command

export FLAKE_DIR=$(pwd)

# Preview what would change
nix run .#default.plan

# Apply changes to router
nix run .#default.apply

# Inspect the raw Terraform JSON
nix run .#default | jq .

If you use a custom name, the scripts are named accordingly (e.g. name = "myrouter" produces myrouter-show, myrouter-plan, etc.).

#Option Reference

#routeros.connection

#routeros.system

Services: ssh (22), winbox (8291), api (8728) enabled by default. ftp (21), telnet (23), www (80), api-ssl (8729) disabled by default.

#routeros.network

#routeros.bridge

#routeros.hosts

Attribute set of hosts. Each host is a submodule:

Hosts are the central source of truth — DHCP leases, DNS A records, and aliases are all derived from this option.

#routeros.dns

#routeros.firewall

The preset includes 13 filter rules (accept established, drop invalid, ICMP, loopback, IPsec, fasttrack, drop WAN DNS) and 2 NAT rules (masquerade, DNS redirect). User rules are appended after. Filter rules use place_before chaining for deterministic ordering.

#routeros.wifi

#routeros.interfaces

#Preset

Import presets.router (auto-imported by mkRouterDerivation) for a secure home router out of the box:

• SSH, WinBox, API enabled and restricted to LAN subnet
• FTP, Telnet, WWW, API-SSL disabled
• DHCP server + client enabled
• DNS with Google upstream, .local domain
• Full firewall with sane defaults
• IPv6 disabled
• WiFi and LTE opt-in

All preset values use lib.mkDefault — override them in your config without mkForce.

#Secrets

mkRouterDerivation supports SOPS for secrets:

nix-routeros.lib.mkRouterDerivation {
  inherit pkgs system;
  modules = [ ./router.nix ];
  stateDir = "infra/router";
  secretsFile = "infra/router/secrets.yaml";
  secrets = {
    TF_VAR_routeros_password = "router-api-password";
    TF_VAR_wifi_password = "wifi-password";
    TF_VAR_state_passphrase = "state-passphrase";
  };
};

The secrets attrset maps environment variable names to SOPS key paths. The generated scripts decrypt them at runtime.

#Importing Existing Resources

For routers already configured, create an imports.nix to map existing resource IDs:

_: {
  import = [
    { to = "routeros_interface_bridge.bridge"; id = "*E"; }
    { to = "routeros_ip_dhcp_server.defconf"; id = "*1"; }
    # Discover IDs with: /interface bridge print show-ids
  ];
}

Pass it as a module:

modules = [ ./router.nix ./imports.nix ];

#Resource Naming Convention

Terraform resource names are derived from option values using a sanitization function:

• - and . replaced with _
• Names starting with a digit get _ prepended
• DHCP leases: routeros_ip_dhcp_server_lease.<sanitized_hostname>
• DNS records: routeros_ip_dns_record.<sanitized_hostname>
• DNS aliases: routeros_ip_dns_record.alias_<sanitized_alias>

#Flake Outputs

#Repository Layout

nix-routeros/
├── flake.nix
├── modules/
│   ├── default.nix        # Shared options (hosts, subnet, _lib)
│   ├── connection.nix     # Provider + connection
│   ├── system.nix         # Identity, clock, services
│   ├── bridge.nix         # Bridge interface + ports
│   ├── interfaces.nix     # WAN, LTE, interface lists
│   ├── dhcp.nix           # DHCP server/client + leases
│   ├── dns.nix            # DNS records + forwarding
│   ├── firewall.nix       # Filter rules, NAT, address lists
│   └── wifi.nix           # CAPsMAN configuration
├── presets/
│   └── router.nix         # Home router defaults
├── lib/
│   ├── helpers.nix        # sanitizeName, networkAddress, prefixLength
│   └── types.nix          # hostType, firewallRuleType, natRuleType
├── templates/default/     # nix flake init template
└── examples/basic/        # Minimal working example

#License

MIT