Locolomo

Vitinha: A Comprehensive Operational Guide for PXE Boot Server Implementation

March 12, 2026

Vitinha: A Comprehensive Operational Guide for PXE Boot Server Implementation

1. Scope and Prerequisites

This manual provides a detailed, step-by-step procedure for deploying and configuring a Vitinha PXE (Preboot eXecution Environment) boot server. Vitinha represents a modern, open-source solution for automated network-based system provisioning, significantly streamlining data center operations and large-scale workstation deployments.

Applicability: This guide is designed for IT system administrators, DevOps engineers, and infrastructure specialists responsible for bare-metal server provisioning, diskless workstation clusters, or automated OS installation across enterprise or laboratory environments.

Prerequisites:

  • A dedicated server running a recent, stable release of a Linux distribution (e.g., Ubuntu Server 22.04 LTS, Rocky Linux 9).
  • Root or sudo privileges on the server.
  • A static IP address configured on the server's network interface.
  • A basic understanding of Linux command-line operations, TCP/IP networking (DHCP, TFTP), and HTTP protocols.
  • Client hardware with a network adapter that supports PXE boot (standard on most enterprise hardware).
  • Sufficient disk space for OS images and configuration files (minimum 20GB recommended).

2. Preparation

Before initiating the installation, ensure your environment is correctly prepared. The optimistic outlook of network automation begins with a solid foundation.

  1. System Update: Log into your designated server and update the package repository. 
    sudo apt update && sudo apt upgrade -y  # For Debian/Ubuntu
# OR
sudo dnf update -y                       # For RHEL/Rocky Linux/Fedora
  2. Configure Static IP: Assign a permanent IP address (e.g., 192.168.1.10) to your server. Edit the network configuration file (e.g., /etc/netplan/01-netcfg.yaml on Ubuntu, /etc/sysconfig/network-scripts/ifcfg-ens192 on RHEL).
  3. Firewall Configuration: Open necessary ports to allow PXE traffic. 
    sudo ufw allow 69/udp   # TFTP
sudo ufw allow 80/tcp   # HTTP (for serving install files)
sudo ufw allow 67/udp   # DHCP (if using the integrated option)
sudo ufw reload
  4. Gather Installation Media: Download the ISO files for the operating systems you intend to deploy (e.g., Ubuntu, CentOS Stream). You will extract these later.

3. Operational Steps

Follow this sequence meticulously to build a robust and efficient Vitinha PXE server. Each step contributes to a seamless, automated provisioning experience.

  1. Install Core Dependencies

    Vitinha relies on several open-source components. Install them using your distribution's package manager.

    # For Debian/Ubuntu:
sudo apt install -y dnsmasq syslinux-common nginx wget

# For RHEL/Rocky Linux/Fedora:
sudo dnf install -y dnsmasq syslinux nginx wget

    Expected Result: All required software packages are installed without errors.

  2. Configure the DHCP/TFTP Service (dnsmasq)

    Dnsmasq will provide IP addresses and inform clients of the boot file location. Create or edit the configuration file: /etc/dnsmasq.conf.

    # Disable DNS functionality if not needed
port=0

# DHCP Configuration
interface=eth0                    # Use your server's interface name
dhcp-range=192.168.1.100,192.168.1.200,12h
dhcp-boot=pxelinux.0
enable-tftp
tftp-root=/var/lib/tftpboot

    Start and enable the service:

    sudo systemctl restart dnsmasq
sudo systemctl enable dnsmasq

    Expected Result: The dnsmasq service runs actively. A new client on the network should receive an IP in the defined range.

  3. Set Up the TFTP Boot Directory

    Populate the TFTP directory with PXE bootloaders from the SYSLINUX package.

    sudo mkdir -p /var/lib/tftpboot
sudo cp /usr/share/syslinux/pxelinux.0 /var/lib/tftpboot/
sudo cp /usr/share/syslinux/menu.c32 /var/lib/tftpboot/
sudo cp /usr/share/syslinux/ldlinux.c32 /var/lib/tftpboot/
sudo mkdir -p /var/lib/tftpboot/pxelinux.cfg
  4. Create the PXE Boot Menu

    This menu is the user interface presented to booting clients. Create the default configuration file: /var/lib/tftpboot/pxelinux.cfg/default.

    DEFAULT menu.c32
PROMPT 0
TIMEOUT 100
ONTIMEOUT local

MENU TITLE Vitinha PXE Boot Server

LABEL local
    MENU LABEL Boot from local disk
    LOCALBOOT 0

LABEL ubuntu-2204
    MENU LABEL Install Ubuntu 22.04 LTS
    KERNEL ubuntu/22.04/vmlinuz
    APPEND initrd=ubuntu/22.04/initrd.gz root=/dev/ram0 ramdisk_size=1500000 ip=dhcp url=http://192.168.1.10/iso/ubuntu-22.04.iso

# Additional labels for other OSes can be added here.
  5. Prepare and Serve Installation Images via HTTP

    Extract the kernel and initrd from your OS ISO and place them in the TFTP directory. Then, serve the full ISO via Nginx.

    # Mount the ISO and copy necessary files (Example for Ubuntu)
sudo mount -o loop ~/ubuntu-22.04.iso /mnt
sudo mkdir -p /var/lib/tftpboot/ubuntu/22.04
sudo cp /mnt/casper/vmlinuz /var/lib/tftpboot/ubuntu/22.04/
sudo cp /mnt/casper/initrd /var/lib/tftpboot/ubuntu/22.04/
sudo umount /mnt

# Place the full ISO in the web server directory
sudo mkdir -p /var/www/html/iso
sudo cp ~/ubuntu-22.04.iso /var/www/html/iso/

    Ensure Nginx is running: sudo systemctl restart nginx.

    Expected Result: Files are accessible via http://[SERVER_IP]/iso/ubuntu-22.04.iso and the kernel/initrd are in the TFTP root.

  6. Client Boot Test

    Configure a client machine to boot from the network (PXE). It should:

    1. Obtain an IP address from your Vitinha server's dnsmasq.
    2. Download pxelinux.0 and the menu files via TFTP.
    3. Display the "Vitinha PXE Boot Server" menu.
    4. Successfully start the installation process when selecting "Install Ubuntu 22.04 LTS".
    This successful boot represents the positive impact of automation: reducing manual intervention from hours to minutes.

4. Common Issues and Troubleshooting

Even well-planned systems may encounter issues. Here are solutions for common scenarios, reinforcing the resilience of your setup.

  • Client receives no IP address (PXE-E51: No DHCP or proxyDHCP offers were received):
    • Verify the server's firewall allows UDP port 67.
    • Confirm dnsmasq is running (sudo systemctl status dnsmasq).
    • Ensure the interface= directive in dnsmasq.conf matches the server's active interface name.
    • Check for other DHCP servers on the network causing conflicts.
  • Client gets an IP but fails to download boot file (PXE-E32: TFTP open timeout):
    • Confirm TFTP is enabled in dnsmasq.conf (enable-tftp).
    • Verify the tftp-root directory path is correct and contains pxelinux.0.
    • Ensure firewall allows UDP port 69.
    • Check file permissions in /var/lib/tftpboot/; they should be readable by all.
  • Boot menu appears, but OS installation fails to start:
    • Validate the paths to the KERNEL and APPEND initrd= files in the default menu are accurate.
    • Confirm the HTTP URL to the ISO file is correct and accessible from a client browser.
    • Check that the kernel and initrd files were correctly extracted from the target OS ISO.
  • Performance is slow during file transfer:
    • Consider network bottlenecks. A Gigabit Ethernet connection is recommended.
    • For larger deployments, explore using a dedicated, high-performance HTTP server or caching proxy for serving ISO files.

By mastering this Vitinha PXE server implementation, you unlock tremendous opportunities for infrastructure automation, enabling rapid, consistent, and reliable deployment of systems—a cornerstone of modern, agile IT operations.

VitinhatechnologyLinuxopen-source