NixOS Wiki

Netboot: Difference between revisions

← Older edit
VisualWikitext
No edit summary
Nh2 (talk | contribs)
7 edits
Link issue
 
(8 intermediate revisions by 5 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/main/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 44: Line 47:
in
in
   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 -w -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
Line 62: Line 62:
sudo iptables -w -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 ===
=== Another example ===
File <code>netboot.nix</code>:
{{file|netboot.nix|nix|3={
<syntaxHighlight lang=nix copy>
  name ? "netboot",
{ name ? "netboot", arch ? "x86_64-linux"
  arch ? "x86_64-linux",
, configuration ? _: {} # --arg configuration 'import ./netboot-config.nix'
  configuration ? _: { }, # --arg configuration 'import ./netboot-config.nix'
, legacy ? false # variation with pxelinux and dnsmasq for older systems
  legacy ? false, # variation with pxelinux and dnsmasq for older systems
, cmdline ? []
  cmdline ? [ ],
, loglevel ? 4
  loglevel ? 4,
, pixiecoreport ? 64172
  pixiecoreport ? 64172,
, proxynets ? [ "192.168.0.0" ]
  proxynets ? [ "192.168.0.0" ],
, serialconsole ? false
  serialconsole ? false,
, serialport ? 0
  serialport ? 0,
, serialspeed ? 9600
  serialspeed ? 9600,
, nixpkgs ? import <nixpkgs> {}, ... }:
  nixpkgs ? import <nixpkgs> { },
with nixpkgs; with lib; let
  ...
}:
with nixpkgs;
with lib;
let


   example-configuration = {pkgs, config, ...}: with pkgs; {
   example-configuration =
    config = {
    { pkgs, config, ... }:
      environment.systemPackages = [
    with pkgs;
        mtr bridge-utils vlan ethtool jwhois sipcalc
    {
        netcat-openbsd tsocks psmisc pciutils usbutils
      config = {
        lm_sensors dmidecode microcom unar mkpasswd ripgrep
        environment.systemPackages = [
        wget rsync sshfs-fuse iperf3 mc mutt borgbackup
          mtr
         rxvt_unicode.terminfo
          bridge-utils
      ];
          vlan
      # users.users.nixos.openssh.authorizedKeys.keys = [ … ];
          ethtool
      # services.openssh = { ports = [2]; settings.PasswordAuthentication = false; };
          jwhois
      # virtualisation.lxc.enable = true;
          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> {
   config = import <nixpkgs/nixos/lib/eval-config.nix> {
Line 100: Line 127:
     modules = [
     modules = [
       <nixpkgs/nixos/modules/installer/netboot/netboot-minimal.nix>
       <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
       version-module
       example-configuration
       example-configuration
Line 106: Line 135:
   };
   };


   version-module = { config, ... }: {
   version-module =
    system.stateVersion = config.system.nixos.version; # be quiet
    { config, ... }:
    system.nixos.tags = [ name ];
    {
  };
      system.stateVersion = builtins.substring 0 (builtins.stringLength "XX.XX") config.system.nixos.version;
      system.nixos.tags = [ name ];
    };


   run-pixiecore = writeShellScript "${name}-run-pixiecore" ''
   run-pixiecore = writeShellScript "${name}-run-pixiecore" ''
Line 125: Line 156:
   '';
   '';


   tftp-root = linkFarm "${name}-tftp-root"  
   tftp-root = linkFarm "${name}-tftp-root" (
     ( mapAttrsToList (name: path: { inherit name path; }) {
     mapAttrsToList (name: path: { inherit name path; }) {
       "pxelinux.cfg/default" = pxelinux-cfg;
       "pxelinux.cfg/default" = pxelinux-cfg;
       "pxelinux.0"           = "syslinux/pxelinux.0";
       "pxelinux.0" = "syslinux/pxelinux.0";
       "syslinux"             = "${syslinux}/share/syslinux";
       "syslinux" = "${syslinux}/share/syslinux";
       "bzImage"             = kernel;
       "bzImage" = kernel;
       "initrd"               = initrd;
       "initrd" = initrd;
     } );
     }
  );


   dnsmasq-conf = writeText "${name}-dnsmasq-conf" ''
   dnsmasq-conf = writeText "${name}-dnsmasq-conf" ''
Line 138: Line 170:
     local-service=net
     local-service=net
     dhcp-boot=pxelinux.0
     dhcp-boot=pxelinux.0
     ${ flip concatMapStrings proxynets (net: ''
     ${flip concatMapStrings proxynets (net: ''
       dhcp-range=${net},proxy
       dhcp-range=${net},proxy
     '')}
     '')}
Line 149: Line 181:
   '';
   '';


   cmd-line = concatStringsSep " "
   cmd-line = concatStringsSep " " (
     ([ "init=${build.toplevel}/init" "loglevel=${toString loglevel}" ]
     [
     ++ optional serialconsole
      "init=${build.toplevel}/init"
      "console=ttyS${toString serialport},${toString serialspeed}"
      "loglevel=${toString loglevel}"
     ++ cmdline );
    ]
     ++ optional serialconsole "console=ttyS${toString serialport},${toString serialspeed}"
     ++ cmdline
  );


   pxelinux-cfg = writeText "${name}-pxelinux.cfg" ''
   pxelinux-cfg = writeText "${name}-pxelinux.cfg" ''
     ${ optionalString serialconsole
     ${optionalString serialconsole "serial ${toString serialport} ${toString serialspeed}"}
      "serial ${toString serialport} ${toString serialspeed}" }
     console 1
     console 1
     prompt 1
     prompt 1
Line 172: Line 206:
   initrd = "${build.netbootRamdisk}/initrd";
   initrd = "${build.netbootRamdisk}/initrd";


in if legacy then run-dnsmasq else run-pixiecore
in
</syntaxHighlight>
if legacy then run-dnsmasq else run-pixiecore|name=netboot.nix|lang=nix}}


Usage example:
Building:
<syntaxHighlight lang=bash>
<syntaxhighlight lang="bash"># Build pixiecore runner
# Build pixiecore runner
nix-build netboot.nix -o /tmp/run-pixiecore
nix build -f netboot.nix -o /tmp/run-pixiecore


# Build dnsmasq + pxelinux runner
# Build dnsmasq + pxelinux runner
nix build -f netboot.nix --arg legacy true -o /tmp/run-dnsmasq
nix-build netboot.nix --arg legacy true -o /tmp/run-dnsmasq


# Build for some ancient system with a serial console
# Build for some ancient system with a serial console
nix build -f netboot.nix --arg name '"ancient-netboot"' -o /tmp/run-netboot \
nix-build netboot.nix --arg name '"ancient-netboot"' -o /tmp/run-netboot \
   --arg configuration 'import ./ancient-config.nix' \
   --arg configuration 'import ./ancient-config.nix' \
   --arg legacy true --arg proxynets '["10.2.1.0"]' \
   --arg legacy true --arg proxynets '["10.2.1.0"]' \
   --arg serialconsole true --arg serialport 3 --arg serialspeed 115200
   --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 ===


</syntaxHighlight>
* 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=23.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].
Retrieved from "https://wiki.nixos.org/wiki/Netboot"