photoncloud-monorepo/chainfire/baremetal/pxe-server/examples/nixos-config-examples.nix

# NixOS Configuration Examples for PXE Boot Server
#
# This file contains example configurations for different deployment scenarios.
# Copy the relevant section to your /etc/nixos/configuration.nix

##############################################################################
# Example 1: Basic Single-Subnet PXE Server
##############################################################################

{
  imports = [ ./baremetal/pxe-server/nixos-module.nix ];

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";
    serverAddress = "10.0.100.10";

    dhcp = {
      subnet = "10.0.100.0";
      netmask = "255.255.255.0";
      broadcast = "10.0.100.255";
      range = {
        start = "10.0.100.100";
        end = "10.0.100.200";
      };
      router = "10.0.100.1";
      nameservers = [ "10.0.100.1" "8.8.8.8" ];
      domainName = "centra.local";
    };
  };
}

##############################################################################
# Example 2: PXE Server with Known Nodes (MAC-based Auto-Selection)
##############################################################################

{
  imports = [ ./baremetal/pxe-server/nixos-module.nix ];

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";
    serverAddress = "10.0.100.10";

    dhcp = {
      subnet = "10.0.100.0";
      netmask = "255.255.255.0";
      broadcast = "10.0.100.255";
      range = {
        start = "10.0.100.100";
        end = "10.0.100.200";
      };
      router = "10.0.100.1";
    };

    # Define known nodes with MAC addresses
    nodes = {
      # Control plane nodes
      "52:54:00:12:34:56" = {
        profile = "control-plane";
        hostname = "control-plane-01";
        ipAddress = "10.0.100.50";
      };
      "52:54:00:12:34:59" = {
        profile = "control-plane";
        hostname = "control-plane-02";
        ipAddress = "10.0.100.51";
      };
      "52:54:00:12:34:5a" = {
        profile = "control-plane";
        hostname = "control-plane-03";
        ipAddress = "10.0.100.52";
      };

      # Worker nodes
      "52:54:00:12:34:57" = {
        profile = "worker";
        hostname = "worker-01";
        ipAddress = "10.0.100.60";
      };
      "52:54:00:12:34:5b" = {
        profile = "worker";
        hostname = "worker-02";
        ipAddress = "10.0.100.61";
      };

      # All-in-one test node
      "52:54:00:12:34:58" = {
        profile = "all-in-one";
        hostname = "homelab-01";
        ipAddress = "10.0.100.70";
      };
    };
  };
}

##############################################################################
# Example 3: PXE Server with Custom DHCP Configuration
##############################################################################

{
  imports = [ ./baremetal/pxe-server/nixos-module.nix ];

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";
    serverAddress = "10.0.100.10";

    dhcp = {
      subnet = "10.0.100.0";
      netmask = "255.255.255.0";
      broadcast = "10.0.100.255";
      range = {
        start = "10.0.100.100";
        end = "10.0.100.200";
      };
      router = "10.0.100.1";
      nameservers = [ "10.0.100.1" "1.1.1.1" "8.8.8.8" ];
      domainName = "prod.centra.cloud";

      # Longer lease times for stable infrastructure
      defaultLeaseTime = 3600;  # 1 hour
      maxLeaseTime = 86400;     # 24 hours

      # Additional DHCP configuration
      extraConfig = ''
        # NTP servers
        option ntp-servers 10.0.100.1;

        # Additional subnet for management network
        subnet 10.0.101.0 netmask 255.255.255.0 {
            range 10.0.101.100 10.0.101.200;
            option routers 10.0.101.1;
            option subnet-mask 255.255.255.0;
            next-server 10.0.100.10;

            if exists user-class and option user-class = "iPXE" {
                filename "http://10.0.100.10/boot/ipxe/boot.ipxe";
            } elsif option architecture-type = 00:00 {
                filename "undionly.kpxe";
            } elsif option architecture-type = 00:07 {
                filename "ipxe.efi";
            }
        }

        # Deny unknown clients (only known MAC addresses can boot)
        # deny unknown-clients;
      '';
    };
  };
}

##############################################################################
# Example 4: Multi-Homed PXE Server (Multiple Network Interfaces)
##############################################################################

{
  imports = [ ./baremetal/pxe-server/nixos-module.nix ];

  # Note: The module currently supports single interface.
  # For multiple interfaces, configure multiple DHCP server instances manually
  # or extend the module to support this use case.

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";  # Primary provisioning network
    serverAddress = "10.0.100.10";

    dhcp = {
      subnet = "10.0.100.0";
      netmask = "255.255.255.0";
      broadcast = "10.0.100.255";
      range = {
        start = "10.0.100.100";
        end = "10.0.100.200";
      };
      router = "10.0.100.1";
    };
  };

  # Manual configuration for second interface
  # services.dhcpd4.interfaces = [ "eth0" "eth1" ];
}

##############################################################################
# Example 5: High-Availability PXE Server (with Failover)
##############################################################################

# Primary PXE server
{
  imports = [ ./baremetal/pxe-server/nixos-module.nix ];

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";
    serverAddress = "10.0.100.10";  # Primary server IP

    dhcp = {
      subnet = "10.0.100.0";
      netmask = "255.255.255.0";
      broadcast = "10.0.100.255";
      range = {
        start = "10.0.100.100";
        end = "10.0.100.150";  # Split range for failover
      };
      router = "10.0.100.1";

      extraConfig = ''
        # DHCP Failover Configuration
        failover peer "centra-pxe-failover" {
          primary;
          address 10.0.100.10;
          port 647;
          peer address 10.0.100.11;
          peer port 647;
          max-response-delay 30;
          max-unacked-updates 10;
          load balance max seconds 3;
          mclt 1800;
          split 128;
        }

        pool {
          failover peer "centra-pxe-failover";
          range 10.0.100.100 10.0.100.150;
        }
      '';
    };
  };
}

# Secondary PXE server (similar config with "secondary" role)
# Deploy on a different server with IP 10.0.100.11

##############################################################################
# Example 6: PXE Server with HTTPS Boot (Secure Boot)
##############################################################################

{
  imports = [ ./baremetal/pxe-server/nixos-module.nix ];

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";
    serverAddress = "10.0.100.10";

    http = {
      port = 443;  # Use HTTPS
    };

    dhcp = {
      subnet = "10.0.100.0";
      netmask = "255.255.255.0";
      broadcast = "10.0.100.255";
      range = {
        start = "10.0.100.100";
        end = "10.0.100.200";
      };
      router = "10.0.100.1";
    };
  };

  # Configure SSL certificates
  services.nginx = {
    virtualHosts."pxe.centra.local" = {
      enableSSL = true;
      sslCertificate = "/etc/ssl/certs/pxe-server.crt";
      sslCertificateKey = "/etc/ssl/private/pxe-server.key";
    };
  };

  # Note: You'll need to rebuild iPXE with embedded certificates
  # for seamless HTTPS boot without certificate warnings
}

##############################################################################
# Example 7: Development/Testing Configuration (Permissive)
##############################################################################

{
  imports = [ ./baremetal/pxe-server/nixos-module.nix ];

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";
    serverAddress = "192.168.1.10";  # Typical home network

    dhcp = {
      subnet = "192.168.1.0";
      netmask = "255.255.255.0";
      broadcast = "192.168.1.255";
      range = {
        start = "192.168.1.100";
        end = "192.168.1.120";
      };
      router = "192.168.1.1";

      # Short lease times for rapid testing
      defaultLeaseTime = 300;   # 5 minutes
      maxLeaseTime = 600;       # 10 minutes
    };
  };

  # Enable nginx directory listing for debugging
  services.nginx.appendHttpConfig = ''
    autoindex on;
  '';
}

##############################################################################
# Example 8: Production Configuration with Monitoring
##############################################################################

{
  imports = [
    ./baremetal/pxe-server/nixos-module.nix
  ];

  services.centra-pxe-server = {
    enable = true;
    interface = "eth0";
    serverAddress = "10.0.100.10";

    dhcp = {
      subnet = "10.0.100.0";
      netmask = "255.255.255.0";
      broadcast = "10.0.100.255";
      range = {
        start = "10.0.100.100";
        end = "10.0.100.200";
      };
      router = "10.0.100.1";
    };

    nodes = {
      # Production node definitions
      # ... (add your nodes here)
    };
  };

  # Enable Prometheus monitoring
  services.prometheus.exporters.nginx = {
    enable = true;
    port = 9113;
  };

  # Centralized logging
  services.rsyslog = {
    enable = true;
    extraConfig = ''
      # Forward DHCP logs to centralized log server
      if $programname == 'dhcpd' then @@logserver.centra.local:514
    '';
  };

  # Backup DHCP leases
  systemd.services.backup-dhcp-leases = {
    description = "Backup DHCP leases";
    serviceConfig = {
      Type = "oneshot";
      ExecStart = "${pkgs.rsync}/bin/rsync -a /var/lib/dhcp/dhcpd.leases /backup/dhcp/dhcpd.leases.$(date +%Y%m%d)";
    };
  };

  systemd.timers.backup-dhcp-leases = {
    wantedBy = [ "timers.target" ];
    timerConfig = {
      OnCalendar = "daily";
      Persistent = true;
    };
  };
}

##############################################################################
# Notes
##############################################################################

# 1. Always update serverAddress, subnet, and interface to match your network
#
# 2. For MAC-based auto-selection, add nodes to the `nodes` attribute
#
# 3. DHCP failover requires configuration on both primary and secondary servers
#
# 4. HTTPS boot requires custom-built iPXE with embedded certificates
#
# 5. Test configurations in a development environment before production deployment
#
# 6. Keep DHCP lease database backed up for disaster recovery
#
# 7. Monitor DHCP pool utilization to avoid exhaustion
#
# 8. Use fixed IP addresses (via MAC mapping) for critical infrastructure nodes