LTSP - Linux Terminal Server Project

Jim McQuillan (

v2.02 11 August 2000

Linux makes a great platform for deploying diskless workstations that boot from a network server. The LTSP is an open source project to create the administration tools that will make setting up a diskless workstation easier. This document provides a description of how a diskless workstation works, describes how to obtain the ltsp distribution and how to install the LTSP.

1. Introduction

This project was born out of the need to solve a problem for a customer who needed a terminal that could communicate with both an IBM AS/400 and a Unix application server. It needed to run TCP/IP, it needed to be inexpensive, and it needed to be easy to maintain. As a plus, it should allow the user to browse the web, and allow them to read and send email.

We could have used PC's running windows, the software is certainly available, but the cost would have been high. Both in terms of the initial investment, and in supporting and maintaining the PC's over time.

We decided that a diskless workstation running the Linux kernel and X-Windows would fit nicely as a solution to the customer problem.

We didn't really invent anything new here, we searched the web and found the etherboot and netboot packages. Then we found an inexpensive ne2000 network interface card that had an eprom socket. We searched and found an affordable eprom burner, figured out what kind of eprom chips to buy, learned about bootp, xdm, nfs-root and all kinds of other things. Then, we put it all together. Initially we tried it on an old 486 PC we had lying around and it worked pretty well.

So, we installed a server and 11 workstations. The customer loved it. They ordered an additional 22 workstations, and they will probably add many more in the future. ( 16 June 2000 Update: They now have over 100 workstations)

After several months, and virtually no support problems with the workstations, we have decided to share our solution with the rest of the world.

The package we developed works very well for our uses. Hopefully, it will solve problems for others as well.

If you have any questions or comments about the package, please join the discuss mailing list at There are several people who may be able to help you out.

2. Copyright

Copyright 2000 James A. McQuillan. Permission to distribute and modify this document is granted under the GNU General Public License - Version 2, June 1991. For the full text of the License, you can view it at:

3. Security Concerns

The installation of the LTSP software will enable some services that could make your system vulnerable to hack attempts.

The install script will modify the following files:

4. Problems with Redhat supplied programs

There are a few problems with some of the packages supplied by Redhat. Other distributions may have similar problems.

4.1 /usr/sbin/inetd

The /usr/sbin/inetd program supplied with RedHat 6.2 has a problem after it has spawned about 40 invokations of tftpd. It will just refuse to spawn any additional tftpd processes until the server is rebooted. There isn't any mention on Redhat's errata page, but the problem goes away if you use a version of init from an older version of Redhat.


Redhat no longer supplies a bootp daemon on the distribution CD. You can download a bootp package from the LTSP download site. If you use DHCP instead, you won't need bootp.

4.3 DHCP

When the DHCP package is installed, the dhcpd.leases file is not created. To correct this, you just need to create an empty /var/state/dhcp/dhcpd.leases file.

4.4 XFS

The X Font Server package (XFS) that ships with Redhat 6.0 doesn't handle serving fonts to remote workstations. Newer versions of xfs are fine, and you can upgrade the xfs on Redhat 6.0 and it will work properly. See the installation instructions on 'Setting up the server' for information on how to upgrade xfs. If you don't use XFS, then you don't need to upgrade it.

5. Quick Installation Guide

If you just want to install the software, without reading all of the gory details, you can just use this quick installation guide.

5.1 Minimum requirements:

The Quick Installation requires that your installation meets the following criteria:

5.2 Ready-Set-Go

For the sake of these instructions, we will assume that you have a Tulip based network card and an SVGA based video card.

  1. Download the LTSP RPM packages from the ltsp download site (

  2. Install the packages.

  3. Verify that dhcpd is installed on the server. Run the following command:
    rpm -qa | grep dhcp
    It should report a line like:
    If it doesn't, then you need to load the DHCP rpm from the RedHat installation CD.
  4. Once the installation of the above packages is complete, then you need to change into the /tftpboot/lts/templates directory. There are several files there that will configure the system files on your server. Each one of these files is responsible for one system file. Take a look at those files and make sure you agree with what they are going to do. They can potentially make your system vulnerable to a security hack. You may wish to make the changes to the system files manually. If you want to do it automatically, the run the ltsp_initialize command:
    cd /tftpboot/lts/templates
  5. Verify that dhcpd is installed on the server. Run the following command:
    rpm -qa | grep dhcp
    It should report a line like:
    If it doesn't, then you need to load the DHCP rpm from the RedHat installation CD.
  6. Copy the /etc/dhcpd.conf.example file to /etc/dhcpd.conf
  7. Modify the dhcpd.conf file to include the MAC address of the network card in the workstation.
  8. Add the following line to the /etc/hosts file:    ws001
  9. Edit the /tftpboot/lts/ltsroot/etc/lts.conf file to make sure the entries are correct for the workstation.
  10. Reboot the server
  11. Turn on the workstation

You should get a graphical login prompt on the workstation. You can log in using any user ID availabe on the server.

If the workstation fails to boot, re-read the above instructions. Pay particular attention to the list of Minimum Requirements above, to make sure your setup meets those requirements. If not, then you should read the rest of this document to gain a more clear understanding of how the LTSP works and what may be wrong with your setup.

When running a diskless workstation, keep the following in mind:

6. Description of a diskless workstation

A Diskless Workstation is a computer that doesn't need a hard disk, floppy or CDRom to boot from.

When the workstation is booted, it does the following:

  1. It gets it's ip address from a bootp or dhcp server
  2. It downloads the kernel from a tftp server
  3. It mounts it's root filesystem from an nfs server
  4. It loads the X-Server software into memory and begins executing it
  5. It contacts an XDM server and allows the user to log into it

In most cases, the bootp server, tftp server, nfs server and xdm server will all be the same machine, we will refer to that simply as the 'Server', and we will refer to the diskless workstation as the 'Workstation'.

Once the workstation is booted, and the user logs in, any application programs that they invoke will be running on the server, while the output is being displayed on the workstation. This is a fundamental feature of X-Windows. The workstation is only running the Linux kernel, XFree86, Init and possibly a print server daemon for printing to the local printer.

Because there is very little running on the workstation, you can get away with a fairly inexpensive, low-power machine. We found in our initial testing that an i486 with 16mb of ram was actually pretty good at being an X terminal.

We used the Etherboot package available from: The Etherboot Home Page. That takes care of the image that gets burned into the eprom, and it helps us prepare the kernel for downloading to a workstation.

There are several HOWTO's that explain how to setup a server for diskless booting of a single workstation, but they don't discuss the problems involved in serving many workstations from a single server. The problem is that when the workstation is running, it needs to write to some files on the server, so each workstation needs to mount it's own unique root filesystem. If you had 50 workstations, you would need 50 directory trees exported. This can be a real pain to try to manage.

We have developed a method of setting up the root filesystem hierarchy that can be shared among all of the workstations. The kernel mounts the filesystem in readonly mode, then mounts a ramdisk as it's /tmp filesystem. The size of the ramdisk is configurable, and it defaults to 1mb. While the kernel and XFree86 are running, they like to update a few files, so we have placed those files on the ramdisk, and created symbolic links to them in the proper place within the hierarchy.

Additionally, we have created a configuration file and a program that runs as part of the workstation bootup sequence. Each workstation can include different hardware. Things such as Network board, Video Card and the type of mouse can be configured either as a default, or individually for each workstation.

Because there aren't any application programs running on the workstation, we don't need a swap device, although it is possible to configure the kernel to swap to an NFS filesystem.

This method of booting a workstation is being used very successfully on a network with over 100 workstations all running from a single server running RedHat 6.0 on a 400mhz Pentium-II. Each workstation is a 166mhz Pentium machine with 32mb of ram. We could have used a smaller processor, but these days it is getting pretty tough to find the low-end cpus.

There is also an option that will allow applications to run directly on the workstation. We refer to this as Local Apps.

7. Theory of operation

Booting a diskless workstation involves several steps. Understanding what is happening along the way will make it much easier to solve problems, should they arise.

This description of the events is assuming that there is a server configured to handle the booting of a workstation.

  1. When you turn on the workstation, it will go through it's power on self test (POST) and the bootcode in the eprom on the network card will begin executing.
  2. The bootcode will attempt to detect a network card. Once it detects the card, it will initialize it.
  3. The bootcode will then broadcast a bootp request to the local network. The request will include the MAC address of the network card. (DHCP can also be used)
  4. The inetd process on the server will see the broadcast and invoke the bootpd daemon to respond to the request.
  5. The bootpd process will read it's configuration file, /etc/bootptab, and locate the entry that matches the MAC address that was sent in the request. Once the entry is found, it will be put into a reply packet and sent back to the workstation that requested the information. Several pieces of information will be passed back in the reply, the items that are important at this point are:
    1. IP address assigned to the workstation ('ip=')
    2. NETMASK setting for the local network ('sm=')
    3. Bootfile home directory ('hd=')
    4. The name of the kernel to download ('bf=')
  6. The bootcode will receive the reply from bootp and it will configure the TCP/IP interface in the network card with the parameters that were supplied.
  7. The bootcode will then send a TFTP request to the server to begin downloading the kernel from the server.
  8. Once the kernel has been completely downloaded to the workstation, the bootcode will do a jump to the starting code in the kernel.
  9. The kernel will then start executing, initializing the entire system and all of the peripherals.
  10. The kernel will issue another bootp broadcast to the network, looking for all of it's networking parameters. Note, the bootcode does NOT pass the information to the kernel, the kernel MUST request the information for itself.
  11. The server will respond with another reply packet, containing the information that the kernel needs to continue. The relevant items in the reply this time are:
    1. IP address assigned to the workstation ('ip=')
    2. NETMASK setting for the local network ('sm=')
    3. The root directory to be mounted via NFS ('rp=')
    4. The gateway ('gw=')
    5. The DNS server ('ds=')
    6. The hostname of the workstation (The value of the first field in the bootptab entry)
    Once all of the above parameters have been passed back to the workstation, the network interface will be configured and brought up.
  12. The root filesystem will be mounted via NFS. This filesystem will be mounted read-only. We do this because we may have many workstations mounting the same filesystem, and we don't want any of the workstations to modify the contents of the root filesystem.
  13. At this point, control will be passed from the kernel to the 'init' process.
  14. init will read the /etc/inittab file and begin setting up the environment.
  15. One of the first items in the inittab file is the rc.local command that will be run while the workstation is in the 'sysinit' state.
  16. The rc.local script will create a 1mb ramdisk to contain all of the things that need to be written to or modified in any way.
  17. This ramdisk will be mounted as the /tmp directory. Any files that need to be written will actually exist in the /tmp directory, and there are symbolic links pointing to these files. For example, when the workstation is running, it will try to modify the permissions on the /dev/tty0 device node. If the device node actually existed in the /dev directory, the permissions would not be modifiable, because the root filesystem is read-only. So, we have created symbolic links for all of the files and created the actual files/nodes in the /tmp directory (which is writeable).
  18. The /proc filesystem will be mounted.
  19. The loopback network interface will be configured.
  20. Several directories will be created under the /tmp filesystem for holding some of the transient files that are needed while the system is running. Directories such as:
    1. /tmp/compiled
    2. /tmp/var
    3. /tmp/var/run
    4. /tmp/var/log
    5. /tmp/var/lock
    6. /tmp/var/lock/subsys
    will all be created.
  21. The /etc/XF86Config file will be generated based on entries in the /tftpboot/lts/ltsroot/etc/lts.conf configuration file. This is where information about the type of mouse, and other X parameters are combined to create the config file for X.
  22. The /tmp/start_ws script will be created. This script will determine which X server to run, and the IP address of the server running xdm. This is Based on information found in the /tftpboot/lts/ltsroot/etc/lts.conf file.
  23. The /tmp/syslog.conf file will be created. This file will contain information telling the syslogd daemon which host on the network to send the logging information to. The syslog host is specified in the lts.conf file. There is a symbolic link called /etc/syslog.conf that points to the /tmp/syslog.conf file.
  24. The syslogd daemon is started, using the config file that was just created.
  25. Control is passed back to init. Init will then look at the initdefault entry to determine which runlevel to enter.
  26. If runlevel 3 is specified, then a shell will be started on the console. This is good for doing trouble shooting.
  27. If runlevel 5 is specified, then the /tmp/start_ws script will be invoked, which will either bringup X-windows, or start a telnet session to the server, depending on the value of the configuration entry 'UI_MODE'.
  28. If GUI mode is chosen, then when X is started, it will send and XDMCP query to the server, which will cause the login dialog box to be displayed.
  29. Once the user logs in, they will be running processes on the server. That is, if they bring up an xterm session, it will be running on the server, and it will be displaying it's output on the workstation.
Basically, we now have either an X station or a telnet terminal.

8. Local apps versus Remote apps

In an LTSP environment you have a choice of running the applications locally on the workstation, or remotely on the server.

By far, the easiest way to setup an LTSP environment is to run the apps on the server. That is, the client application runs on the server, using the servers' CPU and memory, while it displays it's output on the workstation and uses the workstations' keyboard and mouse.

This is a fundamental capability of X Windows. The workstation works just like a standard X-Windows terminal.

8.1 Issues with setting up support for local apps

Setting up the ability to run apps locally requires much more.

8.2 Benefits of running apps locally

9. Setting up the server

We have created RPM's and TGZ's containing all of the pieces you will need to setup a Linux system as the server.

The distributions are known to work with RedHat 6.0, 6.1 or 6.2 systems, but have also been reported to work on other distributions of Linux.

You can download all of the software from the LTSP download page or you can ftp the files from the LTSP ftp server.

9.1 Packages available for download


Core LTS package, contains the root filesystem, including the configuration utilities and documentation for the workstations.

Linux Kernels

Pre-compiled kernels for diskless booting with various network cards are available.

X Servers

There is a large assortment of X servers available for download from the site.

All of these packages are available at LTSP> or LTSP ftp server.

9.2 Planning the IP-Address scheme

Each machine in your network needs a unique IP address. We have chosen one of the reserved Class-C networks, Of course, you are free to choose any addresses you want.

For the server, we chose, and for the workstations, we started with and climb up from there, this gives us the possibility of having 253 workstations associated with a single server. If you need more workstations than that, you can either setup another class-c on the server, perhaps and have the additional workstations use the addresses between and Or, you can go to a Class-B address, and have 65533 workstations all running on the same network. (Sounds pretty cool eh?)

We kept the names of the workstations simple, starting with 'ws001' and going up. Again, you are free to choose any names you want for the workstation. Just make sure they are setup in /etc/hosts or in DNS.

9.3 Upgrade the xfs package

By default, the X Font Server is not used with LTSP. If you want to use it, you should read this section. If not, then skip it.

As of lts version 1.01, the default mode is to NOT run xfs. The following instructions are only required if you choose to set the 'USE_XFS' configuration parameter in the /tftpboot/lts/ltsroot/etc/lts.conf file to 'Y'

The version of xfs that ships with Redhat-6.0 doesn't handle remote workstations. There is an updated xfs that you can download from Redhat or from the LTSP web and ftp sites. You will need XFree86-xfs- or later. If you are running Redhat 6.1 or later on the server, you don't need to worry about the XFS package, it will handle serving fonts to remote workstations. You will, however, need to change the startup script and the XF86Config file on the server.

The command you need to use to install the upgrade is:

rpm -U XFree86-xfs-

Once you install the upgrade, you will need to modify the startup script so that it will serve fonts to remote workstations. The file to edit is: /etc/rc.d/init.d/xfs. There are two lines that need to be modified. The changes you make to the startup script depends on which version of Redhat you are running on the server.

Redhat 6.0

Look for the lines that start with daemon --check xfs su xfs -c \"xfs -port -1\" -s /bin/sh. There are two of them, one is on or around line 22 and the other is on or around line 41.

Change the lines to read:

daemon --check xfs su xfs -c \"xfs -port 7100\" -s /bin/sh

* NOTE: Make sure you change the '-1' to '7100' (without the minus '-' sign).

Redhat 6.1 & 6.2

Look for the lines that start with daemon xfs -droppriv -daemon -port -1. There are two of them, one is on or around line 22 (line 53 for RH6.2) and the other is on or around line 41 (line 73 for RH6.2).

Change the lines to read:

daemon xfs -droppriv -daemon -port 7100

* NOTE: Make sure you change the '-1' to '7100' (without the minus '-' sign).

The above change will allow the X font server daemon to serve fonts to remote workstations.

A change MUST now be made to the /etc/X11/XF86Config file.

Look for the line that says:

FontPath   "unix/:-1"
You will need to change it to:
FontPath   "tcp/localhost:7100"

That is, change the 'unix' to 'tcp' and change the ':-1' to 'localhost:7100'.

9.4 Install bootpd (optional)

If you are using BOOTP instead of DHCP, you will need to download the bootpd package. Redhat doesn't include bootpd on the 6.0, 6.1 or 6.2 distribution CD, so you will need to get it from an earlier version, download it from Redhat, or you can download it from

The command to install the bootp package is:

rpm -i bootp-2.4.3-7.i386.rpm

This will install the bootp daemon and a sample configuration file.

The installation script will also put a copy of the installation messages in a file called /tmp/ltsp.installlog. Take a look at that file to make sure there aren't any errors.

9.5 Install DHCP

You need to make sure that the DHCP server is installed on the server. You can verify that by running the following command:

rpm -qa | grep dhcp
It should report a line like:
If it doesn't, then you need to load the DHCP rpm from the RedHat installation CD.

The DHCP installation routine from Redhat fails to create the dhcpd.leases file, so you will need to create it yourself. The command:

will create the new empty file.

9.6 Install the lts_core package for the first time

Download the lts_core-2.xx-xx.i386.rpm file and install it using the following command:

rpm -i lts_core-2.xx-xx.i386.rpm
This will install the ltsp core package.

It will then setup the /tftpboot/lts directory, which contains the basic root hierarchy that will be mounted as the root filesystem of the workstation. It will also modify several system files. See the Security Concerns above for a list of the system files that will be modified.

9.7 Upgrade the lts_core package from a previous version

If you are upgrading from a previous version of ltsp, your /tftpboot/lts/ltsroot directory will be saved by renaming it and appending a number to the end of the directory name.

For example, if it is the first time you have upgraded, /tftpboot/lts/ltsroot will become /tftpboot/lts/ltsroot.1 and a new /tftpboot/lts/ltsroot directory will be created.

After downloading the lts_core-2.xx-xx.i386.rpm file, you can install the upgrade by using the following command:

rpm -U lts_core-2.xx-xx.i386.rpm
This will save the existing configuration by making backup copies of all of the system files that it updates.

9.8 Choose the appropriate kernel

When the workstation boots, it pulls a kernel from the server and loads it into memory. The kernel that it loads needs to be configured specifically for network booting, and it needs to have the proper network card driver included. It cannot load a network card driver module at this point. We have prepared a few kernels that are ready to go, you will just need to pick the correct one for your network card, download it and install it.

Various Linux kernels are available on our ftp and web site. They are pre-configured for specific network cards and available in RPM and TGZ format. The kernels that are available are:

For example, to install the Linux kernel for a NE2000 network card, do the following:

rpm -i lts_kernel_ne2000-2.0-0.i386.rpm 
This will put the vmlinuz.ne2000 kernel in the /tftpboot/lts directory. You can install other workstation kernels the same way.

You can create your own kernel. When setting kernel parameters, you MUST make sure you specify the following:

Once the kernel is built, it must be converted into a tagged image format, using the mknbi-linux command, which is part of the Etherboot package.

mknbi-linux --output=/tmp/vmlinuz.ne2000         \
            --append="ramdisk=1024"              \
            --rootdir=/tftpboot/lts/ltsroot      \

The kernel then needs to be placed into the /tftpboot/lts directory.

9.9 Choose the X server

You will need to pick the correct X server that is compatible with your video card. The XF86_SVGA server works with most video chipsets, but you may get better performance by using the server made specifically for your chipset.

You can download one of X servers from that will automatically install themselves in the proper location.

We have packages in both RPM and TGZ format available on our ftp site. Files such as: lts_xmach64-2.0-0.i386.rpm and lts_xsvga-2.0-0.i386.rpm can be downloaded and installed.

For example, to install the X server for SVGA do the following:

rpm -i lts_xsvga-2.0-0.i386.rpm 
This will put the XF86_SVGA server in the /tftpboot/lts/ltsroot/ltsbin directory.

9.10 Edit the configuration files

The installation of the lts_core package will add entries to several configuration files, but these entries may need to be modified for your specific needs.


By default, the lines in the inetd.conf file for the bootp and tftp servers are commented out. The LTSP installation procedure will uncomment the tftp daamon line, but it will NOT uncomment the bootps line.

tftp    dgram   udp     wait    root    /usr/sbin/tcpd  in.tftpd
#bootps dgram   udp     wait    root    /usr/sbin/tcpd  bootpd


If you already have the server setup in runlevel 5, then you are already getting the graphical login screen when the server is booted. In this case, the installation script will leave the Xservers file untouched. If you are running the server in runlevel 3, then the installation script will modify the Xservers file by commenting out the entry for the server's console. This is so that when the installation script changes the default runlevel to 5, the console won't switch into graphical mode unexpectedly. If you do want the server to run in graphical mode, then you can either start X-Windows by running the startx command or uncomment the line in the Xservers file.


This file controls whether a remote workstation can communicate with the xdm program on the server. The installation script will uncomment the wildcard entry to allow the remote workstations to get a login screen.

The line that is modified looks like:

*                                     #any host can get a login window

/etc/X11/xdm/xdm-config (Redhat 6.2 only!)

By default, in Redhat 6.2, there is an entry that must be removed (or commented out).

The installation script will take care of commenting the line for you.

The line that is commented out looks like:

DisplayManager.requestPort:    0


The server needs to have xdm running. This is usually started from the /etc/inittab file. There are multiple xdm type servers available on a Redhat 6.0 system. (xdm, gdm and kdm)

We recommend using xdm.

The installation script will setup xdm to run for you, and it will change the default runlevel to 5.

The line that is added looks like:

x:5:respawn:/usr/bin/X11/xdm -nodaemon

The initdefault line is modified. It looks like:


Indicating that the server will boot into runlevel 5 when it starts up.


If you are not using bootp, then you can skip this item.

When you install the lts_core package, it adds the following entries to the /etc/bootptab file:

## LTS-begin ####################################################
# The following is an example of a line needed for a workstation
# ws001:tc=.ltsp:ha=AABBCCDDEEFF:bf=vmlinuz.ne2000:ip=
## LTS-end ######################################################
You will need to create a line for each workstation. You can use the example line (commented out) as a template for the lines you add.

You will need to fill in the ha= entry with the ethernet address from the network card, you will need to fill in the bf= entry with the name of the kernel that you want the workstation to load, and you will need to fill in the ip= entry with the IP address that you want to assign to the workstation.

Also, if you are using a class-c other than the default of, then you will need to change the ip, ds, gw and lg entries above.


An example dhcpd.conf file is installed as part of the LTSP installation. The file is called /etc/dhcpd.conf.example It can be copied or renamed to /etc/dhcpd.conf and dhcpd can be started.

The file looks like:

default-lease-time 21600;
max-lease-time 21600;

option subnet-mask    ;
option broadcast-address;
option routers        ;
option domain-name-servers;
option domain-name              "";
option netbios-name-servers;

shared-network WORKSTATIONS {
        subnet netmask {

group   {
        use-host-decl-names             on;
        option log-servers    ;
        host ws001 {
                hardware ethernet       00:80:C8:D9:31:C1;
                fixed-address ;
                filename                "/tftpboot/lts/vmlinuz.ne2000";
        host ws002 {
                hardware ethernet       00:E0:18:E0:0C:09;
                fixed-address ;
                filename                "/tftpboot/lts/vmlinuz.eepro100";

If your server is configured with more than one IP address, then you will need to create additional 'subnet' entries in the dhcpd.conf file. You can use the example 'subnet ....' entry as a template.


Once you have added the workstation to the bootptab file or dhcpd.conf file, make sure you add the IP-Address and name of the workstation to either the /etc/hosts file, or set it up in your DNS tables either on the server, or somewhere on your network. The NFS server MUST be able to resolve the IP address to a name.


The LTSP installation script will add entries to the /etc/hosts.allow file that will allow bootpd, portmapper and tftp to function properly.

The entries added look like:

in.tftpd:  192.168.0.
portmap:   192.168.0.
The above entries are assuming that you are using the private class-C. If you are using a different class-C then substitute accordingly.


The default entry that is put into this file should be Ok. Unless you are using a Class-C other than If you are using a different class-c, then you need to modify this file to show it. The default entry looks like:

## LTS-begin ##

# The lines between the 'LTS-begin' and the 'LTS-end' were added
# on: Sun Aug  6 23:30:29 EDT 2000 by the ltsp installation script.
# For more information, visit the ltsp homepage
# at


# The following entries need to be uncommented if you want
# Local App support in ltsp
#/usr         ,no_root_squash)
#/bin         ,no_root_squash)
#/sbin        ,no_root_squash)
#/lib         ,no_root_squash)
#/home        ,no_root_squash)

## LTS-end ##
If you want to run local apps (see: LOCAL_APPS) then you will need to uncomment the entries for the directories other than /tftpboot/lts/ltsroot.


The LTSP installation script will modify the /etc/rc.d/init.d/syslog startup script for you, to enable remote workstations to send their syslog messages to the server.

The modified line looks like:

daemon syslogd -m 0 -r 


This is the config file for the workstations. Most of the configurable parameters for the workstations can be specified here.

The config file is comprised of sections, each section represents a workstation, and there is a Default section.

Section headers contain the name of the workstation or the word 'Default', surrounded by square brackets ('[' and ']'). If all of the workstations are identical, then you could get away with just having a Default section.

Example of a /tftpboot/lts/ltsroot/etc/lts.conf file:

        XSERVER            = XF86_SVGA
        SERVER             =
        X_MOUSE_PROTOCOL   = "PS/2"
        X_MOUSE_DEVICE     = "/dev/psaux"
        X_MOUSE_RESOLUTION = 400
        X_MOUSE_BUTTONS    = 3
        USE_XFS            = N
        UI_MODE            = GUI

        XSERVER            = XF86_SVGA
        X_MOUSE_PROTOCOL   = "Microsoft"
        X_MOUSE_DEVICE     = "/dev/ttyS1"
        X_MOUSE_BUTTONS    = 3
        X_MOUSE_BAUD       = 1200

        XSERVER            = XF86_Mach64

        XSERVER            = XF86_SVGA
        X_COLOR_DEPTH      = 24
        USE_XFS            = N

        UI_MODE            = CHAR

9.11 Available lts.conf parameters

General parameters


This is the server that is used for the XDM_SERVER, TELNET_HOST, XFS_SERVER and SYSLOG_HOST, if any of those are not specified explicitly. If you have one machine that is acting as the server for everything, then you can just specify the address here and omit the other server parameters. If this value is not set, will be used.


If you want to send logging messages to a machine other than the default server, then you can specify the machine here. If this parameter is NOT specified, then it will use the 'SERVER' parameter described above.


This will determine whether X-Windows will run, or a telnet session will run. The available choices are:

Currently, this is only used when NOT running local apps. The default value is GUI.


If the workstation is setup to have a character based interface, then the value of this parameter will be used as the host to telnet into. If this value is NOT set, then it will use the value of SERVER above.


Used to build the resolv.conf file.


Used to build the resolv.conf file.

MODULE_01 thru MODULE_10

Upto 10 kernel modules can be loaded by using these configuration entries. The entire command line that you would use when running insmod can be specified here. For example:

MODULE_01   = agpgart.o
MODULE_02   = uart401.o
MODULE_03   = sb.o io=0x220 irq=5 dma=1
MODULE_04   = opl3.o


When the workstation boots, it creates a ramdisk and mounts it on the /tmp directory. You can control the size of the filesystem with this parameter. Specify it in units of kbytes (1024 bytes). To create a ramdisk of 2 megabytes, specify RAMDISK_SIZE = 2048

If you change the size of the ramdisk here, you will also need to change the size of the ramdisk within the kernel. This can be compiled in, or if you are using Etherboot or Netboot, you tell the kernel the ramdisk size when you tag the kernel with mknbi-linux.

The default value for this is 1024 ( 1 mb )

X-Windows parameters


If you want to point XDM to a machine other than the default server, then you can specify the server here. If this parameter is NOT specified, then it will use the 'SERVER' parameter described above.


This defines which X server the workstation will run. Possible values include: XF86_SVGA and XF86_Mach64. Any other XFree86 X server should work, as long as it has been installed in the /tftpboot/lts/ltsroot/ltsbin directory. The default value for this is XF86_SVGA.


Any value that will work for the XFree86 Pointer Protocol keyword can be put here. Typical values include "Microsoft" and "PS/2". The default value for this is "PS/2".


This is the device node that the mouse is connected to. If it is a serial mouse, this would be a serial port, such as /dev/ttyS0 or /dev/ttyS1. If it is a PS/2 keyboard mouse, this value would be /dev/psaux. The default value for this is /dev/psaux.


This is the 'Resolution' value in the XF86Config file. A typical value for a serial mouse is 50 and a typical value for a PS/2 mouse would be 400. The default value for this is 400


This tells the system how many buttons the mouse has. Usually set to 2 or 3. The default value for this is 3


For serial mice, this defines the baud rate. The default value for this is 1200.


This is the number of bits to use for the color depth. Possible values are 8, 15, 16, 24 and 32. 8 bits will give 256 colors, 16 will give 65536 colors, 24 will give 16 million colors and 32 bits will give 4.2 billion colors! Not all X servers support all of these values. The default value for this is 16.


You have a choice of running the X Font Server (XFS) or reading the fonts through the NFS filesystem. The font server should provide a simple way of keeping all of the fonts in one place, but there has been some problems when the number of workstations grows past about 40. The 2 values for this option are Y and N. The default value is N. If you do want to use a font server, then you can use the XFS_SERVER entry to specify which host will act as the font server.


If you are using an X Font Server to serve fonts, then you can use this entry to specify the IP address of the host that is acting as the font server. If this is not specified, it will use the default server, which is specified with the SERVER entry described above.


This sets the XFree86 HorizSync configuration parameter. It defaults to "31-62"


This sets the XFree86 VertRefresh configuration parameter. It defaults to "55-90"


This sets the XFree86 Modeline entry for the 1024 x 768 resolution. There is already a default for the 1024x768, 800x600 and 640x480. If you set Any of the X_MODE_ entries then the 3 default entries will NOT be used and only the entries that you set explicitly will be used.

Below is an example of the X_MODE_1024x760 entry.

    X_MODE_1024x768 = "75.00 1024 1048 1184 1328 768 771 777 806 -hsync -vsync"


This sets the XFree86 Modeline entry for the 800 x 600 resolution. See the note on the 1024x768 entry for an explanation about the defaults.


This sets the XFree86 Modeline entry for the 640 x 480 resolution. See the note on the 1024x768 entry for an explanation about the defaults.


If you want to create your own complete XF86Config file you can do so and place it in the /tftpboot/lts/ltsroot/etc directory. Then, whatever you decide to call it needs to be entered as a value for this configuration variable. For example:

XF86CONFIG_FILE = XF86Config.ws004

Touch screen parameters


If you are connecting a touch screen to the workstation, you can enable it by setting this entry to Y. If enabled, additional configuration entries will configure specific aspects of the touch screen. The default value is N.


A touch screen works like a mouse and usually is interfaced with the workstation through a serial port. You can specify which serial port with this entry. For example, you could set it equal to /dev/ttyS0. There is no default value for this entry.


Callibration entry for an EloTouch touch screen. Defaults to 433.


Callibration entry for an EloTouch touch screen. Defaults to 3588.


Callibration entry for an EloTouch touch screen. Defaults to 569.


Callibration entry for an EloTouch touch screen. Defaults to 3526.


Callibration entry for an EloTouch touch screen. Defaults to 10.


Callibration entry for an EloTouch touch screen. Defaults to 10.

Local apps parameters


If you want the ability to run applications locally on a workstation, set this variable to Y. Several additional steps must be taken on the server to enable local apps. See the 'Local Apps' section in the LTSP manual for more information. The default value is N.


If you do setup LOCAL_APPS, then you have a choice of where you want the window manager to run. It can either run on the workstation or on the server. If you set LOCAL_WM to Y then the window manager will run on the workstation. If you set it to N then it will run on the server. Local apps are much easier to setup if you run the window manager locally on the workstation. Then, by default, any programs that are launched are also run locally. The default value is Y.


If you do setup LOCAL_APPS, then you need to have an NIS server on the network. The NIS_DOMAIN entry is where you specify the NIS domain name. It needs to match a domain name that has been defined on the NIS server. This is NOT the same thing as an internet DOMAIN. The default value is ltsp.


Set this to the IP address of your NIS server if you don't want it to send a broadcast looking for an NIS server.

Keyboard parameters

All of the keyboard support files are now copied into the ltsroot hierarchy so configuring internation keyboard support is now a matter of configuring XFree86. Several configuration parameters are available to make this possible.


The default value for this is the word 'default'.


The default value for this is the word 'default'.


The default value for this is 'us(pc101)'.


The default value for this is 'pc101'.


The default value for this is 'us'.

The values for the above parameters are from the XFree86 documentation. Whatever is valid for XFree86 is valid for these parameters.

We would like to add documentation to show what values are needed for each type of international keyboard. If you work with this and can configure your international keyboards, feedback to the ltsp core group would be greatly appreciated.

Printer configuration parameters

Upto three printers can be connected to a diskless workstation. A combination of serial and parallel printers can be configured via the following entries in the lts.conf file:


The device name of the first printer. Names such as /dev/lp0', /dev/ttyS0 or /dev/ttyS1 are allowed.


The type of the printer. Valid choices are 'P' or for Parallel, and 'S' for Serial.


The TCP/IP Port number to use. By default, it will use '9100'


If the printer is serial, this is the setting that will select the baud rate. By default, '9600' will be used.


For serial printers, the flow control can be specified. Either 'S' for Software (XON/XOFF) flow control, or 'H' for Hardware (CTS/RTS) flow control. If neither is specified, 'S' will be used.


For serial printers, the Parity can be specified. The choices are: 'E'-Even, 'O'-Odd or 'N'-None. If not specified, 'N' will be used.


For serial printers, the number of data bits can be specified. The choices are: '5', '6', '7' and '8'. If not specified, '8' will be used.


Second printer device name


Second printer type


Second printer tcp/ip port


Second printer baud rate (serial)


Second printer flow control (serial)


Second printer parity (serial)


Second printer data bits (serial)


Third printer device name


Third printer type


Third printer tcp/ip port


Third printer baud rate (serial)


Third printer flow control (serial)


Third printer parity (serial)


Third printer data bits (serial)


Comments start with the hash '#' sign and continue through the end of the line.

9.12 Configuring the server for Local apps

Several additional changes must be made on the server to enable it to provide the ability to run local applications on the workstations.

Network Information System - NIS

NIS is a very complex system to administer, and this document does not attempt to explain it in great depth. For a more complete reference, there is an O'Reilly book available called Managing NFS and NIS. Refer to the list of references at the end of this document for more information about the book.

There is also a very good HOWTO document on the LDP called The Linux NIS(YP)/NYS/NIS+ HOWTO. Refer to the list of references at the end of this document for the url.

There are a few simple settings that can be done to get it running with LTSP:

  1. Turn off shadow passwords. The NIS HOWTO explains why.

    If your password file has '*' in the 2nd field, then you have shadow passwords enabled.

    You can turn them off with the pwunconv command.

  2. Edit the yp Makefile.

    Change into the /var/yp directory, edit the Makefile.

    1. Look for the MERGE_PASSWD setting, on or near line 34. Change it to false.
    2. Look for the MERGE_GROUP setting, on or near line 38. Change it to false.
    3. Look for the line that starts with all:, on or near line 96. Comment out the netgrp entry by putting a '#' in front of the word.

  3. Start ypserv by running:

    /etc/rc.d/init.d/ypserv start

    You should run ntsysv to set it to start everytime the server is booted.

  4. Set the NIS domain so you can run ypinit.

    domainname ltsp
  5. Initialize NIS by running ypinit:

    /usr/lib/yp/ypinit -m

At this point, NIS should be ready to go.


This is the config file for the workstations. Most of the

10. Setting up the workstation

The workstation needs a network card with a bootrom.

If you have access to an eprom programmer, you can download the etherboot image from the LTSP website. It is based on the Etherboot project, and the source code is available at if you want to compile the image yourself.

You can purchase bootroms, network cards w/bootroms, eprom programmers, or complete diskless workstations from <shameless plug></shameless plug>.

Another alternative is to download the bootrom image from the LTSP website, along with the floppyload.bin file. Then, copy the two files to the boot sector of a floppy, then boot from the floppy. It will probe for the network card, then begin the boot process just as if the code came from an eprom on the network card. This is very useful for testing purposes.

The command for copying the files to the floppy is:

cat floppyload.bin ne.rom >/dev/fd0
This will place the files into the first sector of the floppy.

10.1 Restarting the daemons

After creating and/or modifying the configuration files, several daemons need to be restarted, to take advantage of the changes. You can restart each of them individually, or you can simply reboot the system.


exportfs -ra


killall -q -HUP bootpd


/etc/rc.d/init.d/syslog restart


killall -HUP inetd


/etc/rc.d/init.d/dhcpd restart


Stop the daemon by running:

/etc/rc.d/init.d/xfs  stop
Then, start the daemon by running:
/etc/rc.d/init.d/xfs  start
For some reason, 'xfs restart' doesn't work correctly. That is why we have to stop it first, then start it up.

11. Testing

Reboot the server after making all of the above changes. Then, just turn on the workstation and you should see it query the network for it's IP information, then you should see a tftp transfer of the kernel and the kernel will begin booting. You should then see X-Windows come up, and finally, a login window should appear.

If it fails somewhere along the way go back through the instructions above and double check the setup. If you are still having trouble, join the LTSP discussion mailing list, available at

12. Tuning the server

Once you get the server and workstations setup, and you begin to increase the size of the network, you may need to perform some tuning of the server.

The following items may need to be tuned:

12.1 Maximum number of files that can be opened on the server

By default, the maximum number of files that can be opened is set to 4096. You can check what the max is on your system by running:

cat /proc/sys/fs/file-max
It will report what the limit is.

You can change this limit by echoing a new value into that file, like this:

echo 8192 >/proc/sys/fs/file-max
This will change the limit immediately. A reboot of the server is NOT necessary.

You should put this command in the /etc/rc.d/rc.local file so that it runs each time the server is rebooted.

12.2 Maximum number of inodes that can be opened on the server

By default, the maximum number of open inodes is 16384. You can check what the max is on your system by running:

cat /proc/sys/fs/inode-max
It will report what the limit is.

You can change this limit by echoing a new value into that file, like this:

echo 32768 >/proc/sys/fs/inode-max
This will change the limit immediately. A reboot of the server is NOT necessary.

You should put this command in the /etc/rc.d/rc.local file so that it runs each time the server is rebooted.

12.3 Maximum number of processes that can be run on the server

On Redhat 6.0, and in kernels downloaded from, the limit on the total number of processes is 512, and the limit on the number of tasks per user is half of that.

Since Redhat 6.1, using the standard redhat supplied kernel, the total number of process is 2560, and the max per user is 2048.

If you need to increase the limits, you will need to modify the /usr/src/linux/include/tasks.h file. The parameters to change are NR_TASKS and MAX_TASKS_PER_USER.

In all cases, the maximum value for these parameters is 4092 ( 4090 if APM is enabled ).

If you change these parameters, you will need to build a new kernel.

13. Troubleshooting

13.1 Places to look for error messages:

If there is a problem booting the workstation, there are a couple of places you can look for errors:

  1. /var/log/messages - Lots of useful messages appear here.
  2. /var/log/secure - If tcpwrappers are enabled, you may see some messages here.
  3. /var/log/xdm-error.log - If you get past the kernel booting, and X has a problem showing the login screen, messages may be logged here.
  4. The workstation console (I know this seems obvious, but...)

13.2 The workstation doesn't boot

Failed to detect IRQ line

The full error is:

NE*0000 ethercard probe at 0x300 failed to detect IRQ line
which will cause another error after the kernel has been loaded:
IP-config NO network devices available
Root-NFS NO NFS server available  giving up
VFS: Unable to mount root fs via NFS, trying floppy
VFS: cannot open root device 02:00
PANIC VFS unable to mount root fs on 02:00
This usually indicates an IRQ conflict between the network card and another device in the system. Try removing the other cards, leaving only the netwrk and video card.

It displays 'Searching for server':

   NE2000 base 0x0300, addr XX:XX:XX:XX:XX:XX
   Searching for server (BOOTP)...
This indicates that the workstation is unable to find a bootp server. Check the following:
  1. Cabling - Check the link lights on both the card and the hub. They both MUST be lit. Also, your server must be connected to the hub, and they also MUST have the lights lit on both the server's network card and the hub.
  2. Bootpd daemon - Make sure the bootpd process is configured in the /etc/inetd.conf file on the server.
  3. /etc/bootptab file - When the bootrom probes for the network card, it will display the MAC address of the card. Make sure that address exists in the /etc/bootptab file on the server.
  4. bootpd may be inhibited from running, due to tcpwrappers. If you have enabled tcpwrappers, by setting up the /etc/hosts.allow and /etc/hosts.deny files, then you need to make sure you have the following entry for bootpd:
    The entry is the address in the bootp request. This address is used during the reqeust, because the workstation doesn't have it's address yet.

It bombs with a "Loading /tftpboot/lts/vmlinuz.ne2000... Unable to load file"

Check the following:

  1. This could be a problem with entries in the /etc/bootptab file. Make sure the following entries are set:
    1. hd=/tftpboot/lts
    2. bf=kernel where kernel is the name of the kernel that matches the type of network card in the workstation. Such as vmlinuz.ne2000 or vmlinuz.rtl8139.
  2. Make sure the kernel actually exists in the /tftpboot/lts directory.

Tftp appears to be trying to download the kernel, but it just doesn't complete

The screen shows:

My IP, Server IP, GW IP
Loading /tftpboot/lts/vmlinuz.ne2000... <sleep>
tftpd may be inhibited from running, due to tcpwrappers. If you have enabled tcpwrappers, by setting up the /etc/hosts.allow and /etc/hosts.deny files, then you need to make sure you have the following entry for tftpd:
in.tftpd:  192.168.0.
This will allow tftp access to all workstations in the class-C.

Problem with NFS mounting root filesystem, errno=13

Errno 13 followed by Panic. This indicates a permission problem for NFS. It may be caused by the following:

  1. The workstation name and IP address MUST be specified in /etc/hosts or in the DNS tables.
  2. The /etc/exports file MUST contain an entry for the /tftpboot/lts/ltsroot directory.
    The IP address MUST match the local network.
  3. After modifying the exports file, you must either run exportfs -ra to tell the kernel that the exports file has changed. Or, you may want to try restarting NFS and portmapper, using the following commands:
    /etc/rc.d/init.d/nfs     stop
    /etc/rc.d/init.d/portmap stop
    /etc/rc.d/init.d/portmap start
    /etc/rc.d/init.d/nfs     start
  4. Make sure NFS is running on the server. Run ntsysv on the server and make sure that 'nfs' is checked. If it isn't, then enable it and reboot the server to bring it up.

RPC call returned error 111

During boot, the workstation displays:

Looking up port of RPC 100003/2 on
Root-NFS: Unable to get nfsd port number from server, using default
Looking up port of RPC 100005/1 on
Root-NFS: Unable to get mountd port number from server, using default
mount: RPC call returned error 111
RPC: task of released request still queued!
RPC: (task is on xprt_pending)
Root-NFS: Server returned error -111 while mounting /tftpboot/lts/ltsroot
VFS: Unable to mount root fs via NFS, trying floppy.
VFS: Cannot open root device 02:00
Kernel panic: VFS: Unable to mount root fs on 02:00
This is most likely caused because of tcpwrappers being enabled. If you are using tcpwrappers, You will need to add an entry to the /etc/hosts.allow file, such as this:
portmap:      192.168.0.
This will allow portmapper access to all workstations in the class-C.

INIT: cannot execute "/etc/rc.local"

During boot, the workstation displays:

INIT: cannot execute "/etc/rc.local"
INIT: Entering runlevel: 5
/tmp/start_ws: /tmp/start_ws: No such file or directory
/tmp/start_ws: /tmp/start_ws: No such file or directory
/tmp/start_ws: /tmp/start_ws: No such file or directory
/tmp/start_ws: /tmp/start_ws: No such file or directory
/tmp/start_ws: /tmp/start_ws: No such file or directory
This is probably caused by incorrect permissions on the /tftpboot/lts/ltsroot/etc/rc.local script. There is a bug in lts_core-1.02 that sets up the rc.local script with the incorrect permissions. It should be "-rwxr-xr-x". You can either change the permissions by doing:
chmod 0755 /tftpboot/lts/ltsroot/etc/rc.local
Or upgrade to lts_core-1.03.

13.3 Problems starting X-Windows

XDMCP fatal error: Manager unwilling Host unwilling

The full error is:

Fatal server error:
XDMCP fatal error: Manager unwilling Host unwilling

when reporting a problem related to a server crash, please send
the full server output, not just the last messages

INIT: Id "2" respawning too fast: disabled for 5 minutes
INIT: no more processes left in this runlevel
This is usually caused by an entry missing from the /etc/X11/xdm/Xaccess file. This file controls which machines can connect to the server via XDM. The trick is to add a line that starts with an Asterisk '*'. On Redhat 6.0, this line already existed, but on Redhat 6.1, the line was commented out. Look for a line that looks like:
# *                                     #any host can get a login window
and remove the hash '#' sign at the beginning of the line. Then, you need to restart xdm by sending the SIGHUP signal to it.
killall -HUP xdm

X tries to start, but displays funny, or not at all

There are lots of things that can go wrong with X, here are some of them:

  1. Is your font server properly running on port 7100? Double check the setup of the /etc/rc.d/init.d/xfs file.
  2. If you are running more than 4 clients, you'll need to increase the max clients setting in the /etc/X11/fs/config file.
  3. It can be helpful to run a shell while in runlevel 5. Change the /tftpboot/lts/ltsroot/etc/inittab file so that the shell line looks like:
    Then, after starting the workstation, you should be able to press CTRL-ALT-F1 to get to the screen where the X startup messages should appear. CTRL-ALT-F2 should get you back to the X-Windows screen.
  4. Your "Modeline" entries may be wrong for your Monitor/Adapter combination. If you want to change them, do it in /tftpboot/lts/ltsroot/etc/rc.local file. This is the script that runs to generate the XF86Config file as the workstation boots. If you can connect the monitor to the server and run Xconfigurator, you might be able to copy the relevant portions of the /etc/X11/XF86Config file it generates into the rc.local script.

X starts successfully, but the login window never appears

This indicates a possible problem with the workstation communicating with xdm on the server. Check the following:

  1. If running Redhat 6.2, Make sure you commented out the 'DisplayManager.requestPort entry.
  2. Check the XDM_SERVER entry in the /tftpboot/lts/ltsroot/etc/lts.conf file. It must be set to the address of the server.

13.4 Problems on the server

X starts on the server, but fails, even though it used to work properly

After changing the /etc/rc.d/init.d/xfs, you also need to change the server's /etc/X11/XF86Config file.

fh_verify errors on server while invoking X on the workstation

The following messages appear on the server:

fh_verify: dev/tty2 permission failure, acc=8, error=30
fh_verify: dev/tty0 permission failure, acc=8, error=30
This happens because the X server is trying to change the ownership and group of the /dev/tty2 and /dev/tty0 device nodes. The root filesystem is mounted readonly, so it can't change the ownership. The X server doesn't really need to change it, because the ownership is already correct. There are updated X servers on the download page that will correct this problem.

No graphical login on the server

If the server is set for runlevel 5, it is supposed to bring up the graphical login prompt when the server is booted.

The installation procedure of LTS Version 1.0 mistakenly commented out the line in the /etc/X11/xdm/Xservers file. The line should looks like:

:0 local /usr/X11R6/bin/X
Make sure the entry is NOT commented out.

This has been fixed in LTS version 1.01.

13.5 If all else fails:

If you still can't get the workstation going, please use the discuss mailing list at to report your problems. There are several people who can help and I try to keep a close eye on that list.

14. LTSP on other versions of Linux and Unix

The LTSP is currently written to work on Redhat Linux 6.0 and 6.1, although there is nothing specific about it that requires Redhat.

Various people have reported success with making it work on other distributions, such as Debian and SuSE.

I have received a report from David Anders ( who was able to install LTSP on SCO OpenServer 5.0.5!

At some point, we would like to include the instructions for the other distributions, so if you have had some experience making LTSP work on platforms other than Redhat, please send us some info.

15. Additional references

15.1 Online references

  1. Linux Terminal Server Project (LTSP) home page
  2. Diskless-Nodes HOW-TO document for Linux
  3. Etherboot Home Page
  4. XFree86-Video-Timings-HOWTO
  5. The Linux NIS(YP)/NYS/NIS+ HOWTO
  6. home page

15.2 Print Publications - for additional reference

  1. Managing NFS and NIS
    Hal Stern
    O'Reilly & Associates, Inc.
    ISBN 0-937175-75-7
  2. TCP/IP Illustrated, Volume 1
    W. Richard Stevens
    ISBN 0-201-63346-9
  3. X Window System Administrator's Guide
    Linda Mui and Eric Pearce
    O'Reilly & Associates, Inc.
    ISBN 0-937175-83-8
    (Volume 8  of the The Definitive Guides to the X Window System)