This page is specific to Ubuntu versions 8.04, 8.10, 9.04, 9.10, 10.04, 12.04

If you find this information applicable to additional versions/releases, please edit this page and modify this header to reflect that. Please also include any necessary modifications for this information to apply to the additional versions.


A proxy DHCP server is defined by the PXE specification as a server which sends auxiliary boot information to clients, like the boot filename, tftp server or rootpath, but leaves the task of IP leasing to the normal DHCP server. This functionality perfectly matches certain LTSP configurations where an external, unmodifiable DHCP server is present (e.g. a router).

Getting a recent dnsmasq version

The usual dhcp3-server can't be configured to act as a proxy DHCP server; fortunately, the newest dnsmasq versions (>=2.48) support this functionality. Karmic comes with dnsmasq 2.49; for previous Ubuntu versions read on.

You can find a backport of dnsmasq 2.49 in this PPA:; you may either download the appropriate dnsmasq.deb file for your Ubuntu series, or insert the PPA to your apt sources:

echo "deb jaunty main
deb-src jaunty main" \
  | sudo tee /etc/apt/sources.list.d/ > /dev/null
sudo apt-key adv --recv-keys --keyserver 03AFA832
sudo apt-get update

The example above is for jaunty, replace with intrepid or hardy as appropriate. *Note: 12.04 users should have a good working dnsmasq program already in the repositories.

Installing dnsmasq and removing ltsp-server-standalone

If you've installed your LTSP server using the alternate CD, then ltsp-server-standalone was automatically installed. This package depends on dhcp3-server which would conflict with dnsmasq. In order to remove dhcp3-server and install dnsmasq, follow the steps below.

Mark ltsp-server as manually installed, so that it doesn't get purged along with ltsp-server-standalone:

sudo apt-get install ltsp-server  # This may update ltsp-server instead
sudo apt-get install ltsp-server  # So do it twice to be certain

Remove dhcp3-server and ltsp-server-standalone:

sudo apt-get --yes --auto-remove purge ltsp-server-standalone

Install dnsmasq. If you haven't put the PPA to your apt sources, then you need to do dpkg -i dnsmasq.deb instead.

sudo apt-get install dnsmasq

Creating the dnsmasq ltsp.conf file

Now an appropriate configuration file needs to be created for dnsmasq to function as a proxy DHCP server.

Create an /etc/dnsmasq.d/ltsp.conf file and paste the following contents into it, while adjusting them to your needs:

# Sample configuration for dnsmasq to function as a proxyDHCP server,
# enabling LTSP clients to boot when an external, unmodifiable DHCP
# server is present.
# The main dnsmasq configuration is in /etc/dnsmasq.conf;
# the contents of this script are added to the main configuration.
# You may modify the file to suit your needs.

# Don't function as a DNS server:

# Log lots of extra information about DHCP transactions.

# Dnsmasq can also function as a TFTP server. You may uninstall
# tftpd-hpa if you like, and uncomment the next line:

# Set the root directory for files available via FTP.

# The boot filename.

# rootpath option, for NFS

# kill multicast

# Disable re-use of the DHCP servername and filename fields as extra
# option space. That's to avoid confusing some old or broken DHCP clients.

# PXE menu
pxe-prompt="Press F8 for boot menu", 3

# The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86,
# Intel_Lean_Client, IA32_EFI, BC_EFI, Xscale_EFI and X86-64_EFI
pxe-service=X86PC, "Boot from network", /ltsp/i386/pxelinux

# A boot service type of 0 is special, and will abort the
# net boot procedure and continue booting from local media.
pxe-service=X86PC, "Boot from local hard disk", 0

# If an integer boot service type, rather than a basename is given, then the
# PXE client will search for a suitable boot service for that type on the
# network. This search may be done by multicast or broadcast, or direct to a
# server if its IP address is provided.
#pxe-service=x86PC, "Install windows from RIS server", 1

# This range(s) is for the public interface, where dnsmasq functions
# as a proxy DHCP server providing boot information but no IP leases.
# Any ip in the subnet will do, so you may just put your server NIC ip here.

# This range(s) is for the private network on 2-NIC servers,
# where dnsmasq functions as a normal DHCP server, providing IP leases.

# For static client IPs, and only for the private subnets,
# you may put entries like this:

*Note: 12.04 users can also use the AMD64 version, but must replace all "i386" with "amd64".

Adjusting pxelinux.cfg/default

Unfortunately, the ipconfig and udhcp programs used in the initramfs do not support the proxy DHCP part of the PXE specification.

Adjusting pxelinux.cfg/default for Ubuntu 8.04 - 9.10

In order to work around this problem, an "IPAPPEND 3" line needs to be added at the end of the /var/lib/tftpboot/ltsp/i386/pxelinux.cfg/default file., so that it contains the following:

DEFAULT vmlinuz ro initrd=initrd.img quiet splash

If you use nfs (which isn't used by default), then you also need to put boot=nfs nfsroot= right next to "splash".

The pxelinux.cfg/default file may get overwritten by the ltsp-update-kernels command. To make it keep its contents, run:

sudo cp /var/lib/tftpboot/ltsp/i386/pxelinux.cfg/default \
sudo mkdir -p /opt/ltsp/i386/etc/ltsp/
(cat <<EOF
BOOTPROMPT_OPTS='quiet splash'
PXELINUX_CMDLINE='$(cat /opt/ltsp/i386/boot/pxelinux.cfg/default)'
) | sudo tee /opt/ltsp/i386/etc/ltsp/update-kernels.conf

Also, the following line must be executed in order to prevent some problems locating lts.conf:

sudo ln -s ltsp/i386/lts.conf /var/lib/tftpboot/lts.conf

Adjusting pxelinux.cfg/default for Ubuntu 10.04

Run the following commands in order to put the necessary options to /etc/ltsp/ltsp-update-image.conf, followed by ltsp-update-image --force to create a new pxelinux.cfg/default file with those options:

(cat <<EOF
BOOTPROMPT_OPTIONS='quiet splash autoconf=dhcp'
) | sudo tee -a /etc/ltsp/ltsp-update-image.conf
sudo ltsp-update-image --force

Adjusting pxelinux.cfg/default for Ubuntu 12.04

(cat <<EOF
ipappend 3
) | sudo tee -a /var/lib/tftpboot/ltsp/i386/pxelinux.cfg/default

Additional step for 12.04

Installing ltsp-server does not install tftpd-hpa, which is a necessary component needed in order to load tftp images to the client computers upon pxe boot. The tftpd-hpa program listens on port 69, therefore in order to transfer the ltsp image files to the clients it must be installed. There is no additional configuring to do once it is installed. APT should install and start the program, you do not have to "ltsp-update-image", the syntax:

sudo apt-get install tftpd-hpa


"Real" PXE clients do support the proxy DHCP specification, as do recent (> May 2009) gPXE clients. But older etherboot clients may be unable to get their boot information from a proxy DHCP server, so for those clients a normal DHCP server is needed (either dhcp3-server or dnsmasq in normal DHCP mode).


Dynamic Server IP Address Precaution

With an external DHCP server, it may change the assigned IP address for your LTSP server. This will result in thin clients being unable to login because the ssh key is tied to the server's IP address. To prevent this, you can either assign your ltsp server a static IP address, or if you have a modifiable external dhcp server, provide a reserved IP address for the LTSP server.

Should the IP address change and you find clients unable to login, run these two commands to regenerate the ssh keys and rebuilt the client image.

  sudo ltsp-update-sshkeys
  sudo ltsp-update-image

Then reboot your thin client(s.)

Failure: Insufficient Information to set up nbd, quitting

This is the most common error, there are many tutorials used to get ltsp working on Ubuntu. The most common error made is setting nbdroot=192.168.x.x (where x is you ip information). In 12.04 you must specify that nbdroot=:ltsp_i386 (or amd64 depending on your installation). N.B. for more recent version of ltsp, use nbdroot=/opt/ltsp/i386 instead, i.e. the name of the section in /etc/nbd-server/conf.d/ltsp_i386.conf)

Error: Socket failed: Connection refused

This is another type of error seen alot in setting up ltsp. Specific to 12.04, nbd-server uses a separate port (with the standard being port 2000). You may need to modify the default file and remove the port number after the nbdroot. ex:

nbdroot=192.168.x.x:2000 or nbdroot=192.168.x.x nbdport=2000

In the above case nbdroot should again be:


N.B. for more recent version of ltsp, use nbdroot=/opt/ltsp/i386 instead.

Ubuntu LTSP debugging

Sometimes when those pesky errors do occur its difficult to see whats happening with the new ubuntu bootup screen. To get console debugging working you can remove the below from the /var/lib/tftpboot/ltsp/i386/pxelinux.cfg/default file:

quiet splash and / or plymouth:force-splash vt.handoff=7

*Note: you do not need to restart nbd-server for the setting to take. The settings should be immediate.

See Also

  • UbuntuLTSP - Community Ubuntu LTSP Documentation.

External Links

  • Dnsmasq - A light DHCP/DNS/TFTP server that supports the proxy DHCP specification.

  • Proxy DHCP - A small explanation of the term by wikipedia.

  • PXE specification - The complete PXE specification, published by Intel and Systemsoft.


UbuntuLTSP/ProxyDHCP (last edited 2013-11-23 14:02:55 by mmenaz)