dotlinux blog

Network Installation of Debian 7 (Wheezy) on Client Machines using DNSMASQ Network Boot Server

Installing an operating system on multiple client machines can be a time-consuming and tedious process when done manually. Network installation, specifically using the Preboot Execution Environment (PXE), offers a powerful and efficient solution for system administrators. This method allows you to boot and install an operating system over the network, eliminating the need for physical media like USB drives or CDs on each client machine.

In this comprehensive guide, we will walk through the process of setting up a PXE boot server using Dnsmasq—a lightweight and versatile tool that combines a DNS forwarder, a DHCP server, and a TFTP server—to perform a network installation of Debian 7 (Wheezy) on client machines. While Debian 7 is an older release (and we strongly recommend using a current, supported version like Debian 12 "Bookworm" for production systems), this tutorial serves as a foundational blueprint. The principles remain largely the same for newer versions, making this knowledge highly transferable.

Prerequisites:

  • A machine running a Linux distribution (we'll use a Debian/Ubuntu-based server for commands) that will act as the PXE server.
  • Root or sudo access on the PXE server.
  • A separate client machine that supports PXE booting (check your BIOS/UEFI settings).
  • A stable network connection where the server and client(s) can communicate.
  • Sufficient disk space on the server for the Debian ISO image and network boot files.
2026-05

Table of Contents#

  1. Network Setup and Server Preparation
  2. Installing and Configuring Dnsmasq
  3. Downloading the Debian 7 NetInstall ISO
  4. Setting Up the TFTP Root and PXE Boot Files
  5. Configuring the PXE Boot Menu
  6. Configuring the HTTP/NFS Server for the Installation Files
  7. Testing the PXE Boot Installation
  8. Troubleshooting Common Issues
  9. Conclusion
  10. References

1. Network Setup and Server Preparation#

First, ensure your PXE server has a static IP address. This is crucial because client machines will rely on this server's IP for booting. We'll assume the server's IP is 192.168.1.10 and the network is 192.168.1.0/24. Adjust these values according to your own network configuration.

Set a static IP (example using netplan on Ubuntu Server):

sudo nano /etc/netplan/01-netcfg.yaml

Add a configuration similar to this:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens33: # Replace with your network interface name
      addresses:
        - 192.168.1.10/24
      gateway4: 192.168.1.1
      nameservers:
          addresses: [8.8.8.8, 1.1.1.1]

Apply the changes:

sudo netplan apply

Update your system packages:

sudo apt update && sudo apt upgrade -y

2. Installing and Configuring Dnsmasq#

Dnsmasq is our all-in-one solution for DHCP, DNS, and TFTP. Install it using your package manager.

sudo apt install dnsmasq -y

Before configuring Dnsmasq, it's a good practice to back up the original configuration file.

sudo cp /etc/dnsmasq.conf /etc/dnsmasq.conf.backup

Now, edit the main configuration file. We will disable the system's default DNS resolver (systemd-resolved) for the interface Dnsmasq is using, or configure Dnsmasq to not listen on port 53 if it's already in use. For simplicity, we'll configure Dnsmasq to handle DHCP and TFTP only for our specific subnet.

Open the configuration file:

sudo nano /etc/dnsmasq.conf

Add or uncomment the following lines, adjusting for your network:

# Disable DNS functionality if you already have a DNS server
#port=0
 
# Interface to listen on (use your server's interface, e.g., ens33, eth0)
interface=ens33
 
# Enable the integrated DHCP server
dhcp-range=192.168.1.50,192.168.1.150,255.255.255.0,12h
 
# Set the gateway (optional, but good practice)
dhcp-option=3,192.168.1.1
 
# Set DNS servers (optional)
dhcp-option=6,8.8.8.8,1.1.1.1
 
# Enable the TFTP server
enable-tftp
 
# Set the TFTP root directory
tftp-root=/srv/tftp
 
# PXE boot menu. Points to the boot file for PXE clients.
# 'pxelinux.0' is the bootloader for BIOS clients.
dhcp-boot=pxelinux.0
 
# For UEFI clients, you would also need:
# dhcp-boot=pxelinux.0
# dhcp-match=set:efi-x86_64,option:client-arch,7
# dhcp-boot=tag:efi-x86_64,efi64/syslinux.efi
# (This guide focuses on BIOS booting for simplicity).

Important: If you already have a DHCP server on your network (like on your router), you must disable it to avoid conflicts. Alternatively, you can configure your existing DHCP server with IP helper/DHCP relay options to point to this PXE server, but that is more advanced.

After making changes, restart the Dnsmasq service.

sudo systemctl restart dnsmasq
sudo systemctl enable dnsmasq

Check its status to ensure it's running without errors:

sudo systemctl status dnsmasq

3. Downloading the Debian 7 NetInstall ISO#

We need the network installation (netinst) ISO for Debian 7 (Wheezy). Since it's an old release, you can find it on the Debian archive servers.

Create a directory to store the ISO and mount it later.

sudo mkdir -p /srv/debian
cd /srv/debian

Download the ISO (this is a small netinst image):

sudo wget http://archive.debian.org/debian/dists/wheezy/main/installer-amd64/current/images/netboot/mini.iso
# Or, if you need i386:
# sudo wget http://archive.debian.org/debian/dists/wheezy/main/installer-i386/current/images/netboot/mini.iso

4. Setting Up the TFTP Root and PXE Boot Files#

The TFTP server will provide the initial boot files to the client. Let's set up the directory structure.

sudo mkdir -p /srv/tftp

Now, we need to extract the necessary boot files from the ISO. First, mount the ISO:

sudo mkdir /mnt/iso
sudo mount -o loop /srv/debian/mini.iso /mnt/iso

Copy the kernel (linux) and initial RAMdisk (initrd.gz) to the TFTP root. These are the core files needed to start the Linux system before the installer takes over.

sudo cp /mnt/iso/linux /srv/tftp/
sudo cp /mnt/iso/initrd.gz /srv/tftp/

We also need the PXELINUX bootloader from the syslinux-common package.

sudo apt install syslinux-common -y

Copy the pxelinux.0 file and the menu.c32 module (which provides a nice menu interface) to the TFTP root.

sudo cp /usr/lib/syslinux/pxelinux.0 /srv/tftp/
sudo cp /usr/lib/syslinux/menu.c32 /srv/tftp/

Create a directory for the PXE configuration menu.

sudo mkdir /srv/tftp/pxelinux.cfg

Unmount the ISO when finished:

sudo umount /mnt/iso

5. Configuring the PXE Boot Menu#

The PXE configuration tells the client what to boot. The default configuration file is named default and is placed inside the pxelinux.cfg directory.

Create and edit the file:

sudo nano /srv/tftp/pxelinux.cfg/default

Add the following configuration. This creates a simple menu with options to install Debian.

DEFAULT menu.c32
PROMPT 0
TIMEOUT 100
 
MENU TITLE PXE Boot Menu - Debian 7 Wheezy Installer
 
LABEL install_debian_7_amd64
    MENU LABEL Install Debian 7 Wheezy (64-bit)
    KERNEL linux
    APPEND initrd=initrd.gz priority=low vga=normal netcfg/disable_autoconfig=true netcfg/get_ipaddress=192.168.1.10 netcfg/get_netmask=255.255.255.0 netcfg/get_gateway=192.168.1.1 netcfg/get_nameservers=8.8.8.8 netcfg/confirm_static=true interface=auto domain=local.net url=http://192.168.1.10/debian/install.amd/gtk/initrd.gz
    # The 'url' parameter is critical. It points to the location of a *different* initrd.gz that the installer will fetch via HTTP.
 
LABEL local
    MENU LABEL Boot from Local Drive
    LOCALBOOT 0

Explanation of the critical APPEND line:

  • priority=low: Ensures all installer questions are asked.
  • vga=normal: Sets a standard video mode.
  • netcfg/disable_autoconfig=true ...: Forces a static IP configuration for the client during installation to ensure it can find our server. This can be tricky; using DHCP within the installer is often easier but requires the url parameter to be correctly resolvable via the DHCP-provided settings.
  • url=...: This is the most important part. It tells the Debian installer to fetch the rest of its files (the main initrd.gz and the SquashFS filesystem) from an HTTP server. We will set this up next.

6. Configuring the HTTP/NFS Server for the Installation Files#

The initial TFTP boot only loads a small kernel and initrd. The bulk of the installer files are fetched via HTTP (or NFS). We'll use a simple HTTP server. Install apache2 or nginx. We'll use Apache here.

sudo apt install apache2 -y

We need to provide the contents of the Debian NetInstall CD. The easiest way is to use the netboot tar.gz file which contains the exact structure needed.

Download the netboot tar.gz for Debian 7:

cd /tmp
wget http://archive.debian.org/debian/dists/wheezy/main/installer-amd64/current/images/netboot/netboot.tar.gz

Extract it into the Apache web root:

sudo tar -xzf netboot.tar.gz -C /var/www/html/

This will create a directory like /var/www/html/debian-installer/amd64/. The url parameter in our PXE menu must point to the initrd.gz file inside this structure. Let's create a simpler symlink.

sudo ln -s /var/www/html/debian-installer/amd64 /var/www/html/debian

Now, the files are accessible at http://192.168.1.10/debian/. Verify this by visiting that URL in a browser on another machine on the network. You should see a directory listing.

Go back and double-check the url parameter in your /srv/tftp/pxelinux.cfg/default file. It should now correctly point to http://192.168.1.10/debian/install.amd/gtk/initrd.gz (the path might vary slightly; check the exact path in the /var/www/html/debian/ directory).

7. Testing the PXE Boot Installation#

  1. Configure the Client: Take a client machine, connect it to the same network as your PXE server, and enter its BIOS/UEFI settings.
  2. Enable PXE Boot: Enable "Network Boot" or "PXE Boot" and ensure it is the first boot device in the boot order.
  3. Boot the Client: Save the BIOS settings and reboot the client machine.
  4. The Magic Should Happen: The client should broadcast a DHCP request, receive an IP from your Dnsmasq server, and then be directed to download pxelinux.0 via TFTP. You should then see the "PXE Boot Menu" we configured.
  5. Start Installation: Select "Install Debian 7 Wheezy (64-bit)" and press Enter. The client will load the kernel and initial ramdisk from TFTP, and then begin fetching the rest of the installer files from the HTTP server.

If all goes well, the standard Debian installer will start. You can then proceed with the installation as you normally would, with the system automatically using the network mirror for packages.

8. Troubleshooting Common Issues#

  • Client gets an IP but fails to PXE boot: Check the Dnsmasq logs on the server: sudo journalctl -u dnsmasq -f. Look for TFTP-related messages. Ensure pxelinux.0 and all other files are in the correct /srv/tftp directory with correct permissions (world-readable).
  • Client hangs after loading pxelinux.0: The pxelinux.cfg/default file might have a syntax error. Check it carefully. Also, ensure menu.c32 is present in the TFTP root.
  • Installer starts but fails to fetch files via HTTP: Check the url parameter in the PXE menu. Can you wget that URL directly from another machine on the network? Verify the Apache server is running and the files are in the correct location. Check the Apache error logs: sudo tail -f /var/log/apache2/error.log.
  • DHCP conflicts: If the client gets an IP from your router instead of your Dnsmasq server, you must disable the DHCP server on your router.

Conclusion#

You have now successfully set up a fully functional PXE boot server using Dnsmasq to deploy Debian 7 (Wheezy) over the network. This setup, while demonstrated on an older release, forms the basis for modern network installation techniques. The same core concepts—configuring a DHCP/TFTP server (Dnsmasq), providing boot files, and serving the installer image via HTTP—apply to installing current versions of Debian, Ubuntu, CentOS, and many other distributions.

This method is incredibly powerful for system administrators managing labs, data centers, or any environment with multiple machines, significantly reducing deployment time and ensuring consistency.

References#

  1. Dnsmasq Documentation: http://www.thekelleys.org.uk/dnsmasq/doc.html
  2. Debian GNU/Linux Installation Guide (Chapter 4.3 - Preparing Files for TFTP Net Booting): https://www.debian.org/releases/stable/amd64/ch04s03.html.en (Replace stable with wheezy for the old guide).
  3. Syslinux Wiki - PXELINUX: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX
  4. Debian Archive: http://archive.debian.org/