DOCSEARCHbyAlgolia
Submit Docs

nix-openwrt-imagebuilder

repository·main·Indexed 42 days ago

https://github.com/astro/nix-openwrt-imagebuilder

A tool for generating customized, reproducible, and declarative OpenWRT sysupgrade images using Nix. It wraps official OpenWRT binary ImageBuilders and requires an x86_64-linux host. Supports package selection, service disabling, and custom file inclusion via Nix derivations, with built-in profile helper functionality for OpenWRT releases since 19.07.

Tokens
1.5K
Snippets
4
Records
5
Agent score
4%

What's inside nix-openwrt-imagebuilder

  1. Generate OpenWRT images using nix-openwrt-imagebuilder

    main

    This project allows you to generate customized OpenWRT sysupgrade images by leveraging the official upstream binary ImageBuilders. It uses Nix derivations to specify packages, files, and configurations.

    Requirements:

    • The host machine must be x86_64-linux because it relies on official binary ImageBuilders.
    • For OpenWRT releases since 19.07, the project provides profile helper functionality to automatically map hardware profile names to the correct image specification (target and variant).

  2. Configure OpenWRT image parameters

    main

    When defining your image configuration, you can customize several fields to modify the resulting image:

    • packages: A list of strings representing OpenWRT packages to include in the image (e.g., [ "tcpdump" ]).
    • disabledServices: A list of services to disable in the image.
    • files: A Nix derivation that provides files to be included in the image. To set UCI configuration, you should create scripts in /etc/uci-defaults/ as per official OpenWRT recommendations.
    config = profiles.identifyProfile "avm_fritz7412" // {
  packages = [ "tcpdump" ];
  disabledServices = [ "dnsmasq" ];
  files = pkgs.runCommand "image-files" {} ''
    mkdir -p $out/etc/uci-defaults
    cat > $out/etc/uci-defaults/99-custom <<EOF
    uci -q batch << EOI
    set system.@system[0].hostname='testap'
    commit
    EOI
    EOF
  '';
};

  3. Use nix-openwrt-imagebuilder with Nix Flakes

    main

    In a Flake-based project, add openwrt-imagebuilder as an input. You can then use openwrt-imagebuilder.lib.profiles to resolve hardware profiles and openwrt-imagebuilder.lib.build to generate the image package.

    {
  inputs = {
    openwrt-imagebuilder.url = "github:astro/nix-openwrt-imagebuilder";
  };
  outputs = { self, nixpkgs, openwrt-imagebuilder }: {
    packages.x86_64-linux.my-router = 
      let
        pkgs = nixpkgs.legacyPackages.x86_64-linux;
        profiles = openwrt-imagebuilder.lib.profiles { inherit pkgs; };
        config = profiles.identifyProfile "avm_fritz7412" // {
          packages = [ "tcpdump" ];
          disabledServices = [ "dnsmasq" ];
          files = pkgs.runCommand "image-files" {} ''
            mkdir -p $out/etc/uci-defaults
            cat > $out/etc/uci-defaults/99-custom <<EOF
            uci -q batch << EOI
            set system.@system[0].hostname='testap'
            commit
            EOI
            EOF
          '';
        };
      in
        openwrt-imagebuilder.lib.build config;
  };
}

  4. Use nix-openwrt-imagebuilder with vanilla Nix

    main

    To use the project in a standard Nix setup, import profiles.nix to identify your hardware profile and then pass that configuration to builder.nix.

    Note: You must point openwrt-imagebuilder to the local path of this repository or use a method like fetchurl or Hydra inputs to reference it.

    let
  pkgs = import <nixpkgs> {};
  openwrt-imagebuilder = ../nix-openwrt-imagebuilder;
  profiles = import (openwrt-imagebuilder + "/profiles.nix") { inherit pkgs; };

  config = profiles.identifyProfile "avm_fritz7412" // {
    packages = [ "tcpdump" ];
    disabledServices = [ "dnsmasq" ];
    files = pkgs.runCommand "image-files" {} ''
      mkdir -p $out/etc/uci-defaults
      cat > $out/etc/uci-defaults/99-custom <<EOF
      uci -q batch << EOI
      set system.@system[0].hostname='testap'
      commit
      EOI
      EOF
    '';
  };
in
  import (openwrt-imagebuilder + "/builder.nix") config

  5. Refresh OpenWRT download hashes

    main

    If you encounter hash mismatch in fixed-output derivation errors due to changes on downloads.openwrt.org, you can manually update the hashes using the provided release2nix and list-versions tools.

    To build using a local working copy of the project when it is defined as a Flake input, use --override-input.

    # Update hashes
nix run .#release2nix -- $(nix run .#list-versions -- -l)

# Build using a local copy of the flake input
nix build --override-input openwrt-imagebuilder git+file:///path/to/local/repo .#your-package