NixOS Wiki

Netboot: Difference between revisions

← Older edit
VisualWikitext
imported>Erikarvstedt
Improve example: Move script definition to system build. Fix old `nix build` syntax. Add firewall commands.
Nh2 (talk | contribs)
7 edits
Link issue
 
(17 intermediate revisions by 9 users not shown)
Line 1: Line 1:
== Building and serving a netboot image ==
== Building and serving a netboot image ==
This provides an easy way to serve the NixOS installer over netboot, such as when you already have a working NixOS machine and want to install NixOS on a second machine connected to the same network.


=== Example ===
=== Example ===
This example uses [https://github.com/danderson/netboot/tree/master/pixiecore Pixiecore] for hosting, which works in an ordinary network environment with an existing DHCP server.
This example uses [https://github.com/danderson/netboot/tree/main/pixiecore Pixiecore] for hosting, which works in an ordinary network environment with an existing DHCP server.
 
Pixiecore will notice when the booted machine talks to the network's existing DHCP server, and send netboot information to it at that time.


Create file <code>system.nix</code>:
Create file <code>system.nix</code>:
Line 12: Line 15:
   sys = nixpkgs.lib.nixosSystem {
   sys = nixpkgs.lib.nixosSystem {
     system = "x86_64-linux";
     system = "x86_64-linux";
     modules = [
     modules = [
      pixiecoreNetboot
       ({ config, pkgs, lib, modulesPath, ... }: {
       ({ config, pkgs, lib, ... }: with lib; {
        imports = [
          (modulesPath + "/installer/netboot/netboot-minimal.nix")
        ];
         config = {
         config = {
           ## Some useful options for setting up a new system
           ## Some useful options for setting up a new system
           # services.getty.autologinUser = mkForce "root";
           # services.getty.autologinUser = lib.mkForce "root";
           # users.users.root.openssh.authorizedKeys.keys = [ ... ];
           # users.users.root.openssh.authorizedKeys.keys = [ ... ];
           # console.keyMap = "de";
           # console.keyMap = "de";
Line 29: Line 33:
   };
   };


   pixiecoreNetboot = { config, pkgs, lib, modulesPath, ... }: {
   run-pixiecore = let
    imports = [
    hostPkgs = if sys.pkgs.system == builtins.currentSystem
      (modulesPath + "/installer/netboot/netboot-minimal.nix")
              then sys.pkgs
    ];
              else nixpkgs.legacyPackages.${builtins.currentSystem};
 
     build = sys.config.system.build;
     system.build.run-pixiecore = let
  in hostPkgs.writers.writeBash "run-pixiecore" ''
      build = config.system.build;
    exec ${hostPkgs.pixiecore}/bin/pixiecore \
    in
      boot ${build.kernel}/bzImage ${build.netbootRamdisk}/initrd \
      pkgs.writers.writeBash "run-pixiecore" ''
      --cmdline "init=${build.toplevel}/init loglevel=4" \
        exec ${lib.getExe pkgs.pixiecore} \
      --debug --dhcp-no-bind \
          boot ${build.kernel}/bzImage ${build.netbootRamdisk}/initrd \
      --port 64172 --status-port 64172 "$@"
          --cmdline "init=${build.toplevel}/init loglevel=4" \
  '';
          --debug --dhcp-no-bind \
          --port 64172 --status-port 64172 "$@"
      '';
  };
in
in
   sys.config.system.build.run-pixiecore
   run-pixiecore
</syntaxHighlight>
</syntaxHighlight>Building:<syntaxhighlight lang="bash">
 
Run pixiecore:
<syntaxHighlight lang=bash>
# Build pixiecore runner
# Build pixiecore runner
nix build -f system.nix -o /tmp/run-pixiecore
nix-build system.nix -o /tmp/run-pixiecore
 
</syntaxhighlight>Running:<syntaxhighlight lang="bash">
# Open required firewall ports
# Open required firewall ports
sudo iptables -I nixos-fw -p udp -m multiport --dports 67,69,4011 -j ACCEPT
sudo iptables -w -I nixos-fw -p udp -m multiport --dports 67,69,4011 -j ACCEPT
sudo iptables -I nixos-fw -p tcp -m tcp --dport 64172 -j ACCEPT
sudo iptables -w -I nixos-fw -p tcp -m tcp --dport 64172 -j ACCEPT


# Run pixiecore
# Run pixiecore
Line 62: Line 59:


# Close ports
# Close ports
sudo iptables -D nixos-fw -p udp -m multiport --dports 67,69,4011 -j ACCEPT
sudo iptables -w -D nixos-fw -p udp -m multiport --dports 67,69,4011 -j ACCEPT
sudo iptables -D nixos-fw -p tcp -m tcp --dport 64172 -j ACCEPT
sudo iptables -w -D nixos-fw -p tcp -m tcp --dport 64172 -j ACCEPT
</syntaxHighlight>
 
</syntaxhighlight>
 
=== Another example ===
{{file|netboot.nix|nix|3={
  name ? "netboot",
  arch ? "x86_64-linux",
  configuration ? _: { }, # --arg configuration 'import ./netboot-config.nix'
  legacy ? false, # variation with pxelinux and dnsmasq for older systems
  cmdline ? [ ],
  loglevel ? 4,
  pixiecoreport ? 64172,
  proxynets ? [ "192.168.0.0" ],
  serialconsole ? false,
  serialport ? 0,
  serialspeed ? 9600,
  nixpkgs ? import <nixpkgs> { },
  ...
}:
with nixpkgs;
with lib;
let
 
  example-configuration =
    { pkgs, config, ... }:
    with pkgs;
    {
      config = {
        environment.systemPackages = [
          mtr
          bridge-utils
          vlan
          ethtool
          jwhois
          sipcalc
          netcat-openbsd
          tsocks
          psmisc
          pciutils
          usbutils
          lm_sensors
          dmidecode
          microcom
          unar
          mkpasswd
          ripgrep
          wget
          rsync
          sshfs-fuse
          iperf3
          mc
          mutt
          borgbackup
          rxvt-unicode
        ];
        # users.users.nixos.openssh.authorizedKeys.keys = [ … ];
        # services.openssh = { ports = [2]; settings.PasswordAuthentication = false; };
        # virtualisation.lxc.enable = true;
      };
    };
 
  config = import <nixpkgs/nixos/lib/eval-config.nix> {
    # see <nixpkgs/nixos/release.nix>
    system = arch;
    modules = [
      <nixpkgs/nixos/modules/installer/netboot/netboot-minimal.nix>
      # Reduce build time by ~7x (~1 minute instead of many minutes) by not using the highest compression (image is 5% larger).
      ({ ... }: { netboot.squashfsCompression = "zstd -Xcompression-level 6"; })
      version-module
      example-configuration
      configuration
    ];
  };
 
  version-module =
    { config, ... }:
    {
      system.stateVersion = builtins.substring 0 (builtins.stringLength "XX.XX") config.system.nixos.version;
      system.nixos.tags = [ name ];
    };
 
  run-pixiecore = writeShellScript "${name}-run-pixiecore" ''
    exec ${pixiecore}/bin/pixiecore \
      boot ${kernel} ${initrd} \
      --cmdline "${cmd-line}" \
      --debug --dhcp-no-bind --log-timestamps \
      --port ${toString pixiecoreport} \
      --status-port ${toString pixiecoreport} "$@"
  '';
 
  run-dnsmasq = writeShellScript "${name}-run-dnsmasq" ''
    exec ${dnsmasq}/bin/dnsmasq \
      -d -k --no-daemon -C "${dnsmasq-conf}" "$@"
  '';
 
  tftp-root = linkFarm "${name}-tftp-root" (
    mapAttrsToList (name: path: { inherit name path; }) {
      "pxelinux.cfg/default" = pxelinux-cfg;
      "pxelinux.0" = "syslinux/pxelinux.0";
      "syslinux" = "${syslinux}/share/syslinux";
      "bzImage" = kernel;
      "initrd" = initrd;
    }
  );
 
  dnsmasq-conf = writeText "${name}-dnsmasq-conf" ''
    pxe-prompt="Booting NixOS..",1
    local-service=net
    dhcp-boot=pxelinux.0
    ${flip concatMapStrings proxynets (net: ''
      dhcp-range=${net},proxy
    '')}
    dhcp-no-override
    dhcp-leasefile=/dev/null
    log-dhcp
    enable-tftp
    tftp-port-range=6900,6999
    tftp-root=${tftp-root}
  '';
 
  cmd-line = concatStringsSep " " (
    [
      "init=${build.toplevel}/init"
      "loglevel=${toString loglevel}"
    ]
    ++ optional serialconsole "console=ttyS${toString serialport},${toString serialspeed}"
    ++ cmdline
  );
 
  pxelinux-cfg = writeText "${name}-pxelinux.cfg" ''
    ${optionalString serialconsole "serial ${toString serialport} ${toString serialspeed}"}
    console 1
    prompt 1
    timeout 37
    default NixOS
    label NixOS
      kernel bzImage
      append initrd=initrd ${cmd-line}
  '';
 
  build = config.config.system.build;
  kernel = "${build.kernel}/${kernel-target}";
  kernel-target = config.pkgs.stdenv.hostPlatform.linux-kernel.target;
  initrd = "${build.netbootRamdisk}/initrd";
 
in
if legacy then run-dnsmasq else run-pixiecore|name=netboot.nix|lang=nix}}
 
Building:
<syntaxhighlight lang="bash"># Build pixiecore runner
nix-build netboot.nix -o /tmp/run-pixiecore
 
# Build dnsmasq + pxelinux runner
nix-build netboot.nix --arg legacy true -o /tmp/run-dnsmasq
 
# Build for some ancient system with a serial console
nix-build netboot.nix --arg name '"ancient-netboot"' -o /tmp/run-netboot \
  --arg configuration 'import ./ancient-config.nix' \
  --arg legacy true --arg proxynets '["10.2.1.0"]' \
  --arg serialconsole true --arg serialport 3 --arg serialspeed 115200</syntaxhighlight>Running:
 
* Run the example exactly like the other example further up on the page.
 
=== Troubleshooting ===
 
* Error "'''autoexec.ipxe... Operation not supported'''": See [https://github.com/NixOS/nixpkgs/pull/378513#pullrequestreview-3081586117 this issue].


=== See also ===
=== See also ===
NixOS: [https://search.nixos.org/options?channel=22.11&from=0&size=30&sort=relevance&type=packages&query=services.pixiecore Pixiecore module].
NixOS: [https://search.nixos.org/options?type=packages&query=services.pixiecore Pixiecore module].


NixOS manual: [https://nixos.org/nixos/manual/index.html#sec-booting-from-pxe PXE booting].
NixOS manual: [https://nixos.org/nixos/manual/index.html#sec-booting-from-pxe PXE booting].
Line 76: Line 238:


<b>Note:</b> Your iPXE must be recent enough to support https:// links
<b>Note:</b> Your iPXE must be recent enough to support https:// links
[[Category:Booting]]
Retrieved from "https://wiki.nixos.org/wiki/Netboot"