LTSP

The Linux Terminal Server Project (website) is a collection of scripts and documentation to create a cluster of thin clients. For instance, an entire client chroot environment is built with a single command: ltsp-build-client. This article will guide you through the installation and configuration of a basic LTSP 5 system.

This guide shows you how to install and configure the Gentoo LTSP 5 port. This guide assumes some knowledge of thin client architecture and experience in manually installing Gentoo. Also, you need a server and client with the specifications listed in the LTSP manual. Concerning the client networkcard, only PXE is included in this manual.

Several resources can help you speed you on your way in time of need. Others are listed in the Resources section. For more online LTSP help, you can visit #ltsp on one of the freenode irc servers.
 * LTSP Administrator's Reference
 * LTSP upstream development page
 * LTSP mailing lists

Bugs can be reported in two locations. Check known issues before entering a potential duplicate.
 * - For issues related to Gentoo
 * - For issues related to LTSP itself

Installation
Gentoo's LTSP packages are stored in the ltsp-overlay. To use the Gentoo LTSP-Overlay, get it with. Because ltsp resides in the git overlays, the git USE flag is needed.

The LTSP server package needs a tftp and dhcp server (dhcp or dnsmasq). In this tutorial and  are used. It also requires a system logger which can accept client messages over tcp, for which is used in this tutorial. Don't forget to add a window manager, ltsp-client won't log in if no window manager is installed on the server. The USE flags for ltsp-server:

Kernel
Besides the obvious drivers, the server kernel ought to have the following settings. If you're going to use NFS to serve the chroot environments, make sure to compile it in as well and reboot afterwards.

DHCP and PXE-boot
First, setup the server to provide client machines with a kernel at boottime. Install a few packages on the server. The PXE bootloader is provided by. Dnsmasq is a simple DHCP/DNS server. Advanced TFTP is one of the TFTP server options, and the only one to support multicast TFTP.1 The chroot environments as well as the kernels served at boot time are stored in /opt/ltsp.

Configure ; for help on configuration, view the the Dnsmasq page.

Setup the PXE bootloader; view the PXE install section for more detail. In the example configuration, the system mounts the local client disk after booting and loading the kernel from the server. Make sure the kernel and initramfs are in /var/lib/tftpboot. You can test the work so far with a working kernel and system.

Configure next. This is used for the client nodes to retrieve the kernel and initrd/initramfs, before they mount their root filesystems via NFS.1

Start the services, now and at every boot

NFS and Xinetd
The chroot environments are shared with NFS. Xinetd is used for ldminfod and nbd sharing. By default only the localhost is allowed access, so edit the /etc/xinetd.conf and restart the service.

System Logging
System logging is performed by. Log files are not stored locally however, but sent to the server specified by SYSLOG_HOST in lts.conf. While executing, the ltsp-client-setup script adds the syslog-ng configuration to perform this. To allow the server to process these incoming log messages, some changes have to be made in that configuration as well. In the syslog-ng setting below, messages are logged to a file named after each client's fully qualified domain name.

Sound
As you might have seen in the list of emerged dependencies for ltsp, both for the client and the server, PulseAudio was among them. In addition to, its alsa-plugin needs to be installed on both client and server with the pulseaudio use flag enabled. Refer to the Gentoo Wiki chapter for detailed installation instructions.

Client Install
The ltsp-server package amongst others ships a command called ltsp-build-client. This command is responsible for building the entire chroot environment. And while ltsp-build-client and available plugins setup the environment, Quickstart actually builds it. You can also use the Kicktoo alternative. While Quickstart is more stable, Kicktoo is under active development.

Configuration
You can invoke the build script with command line arguments or configure the config file in /etc/ltsp/ltsp-build-client.conf. An example config file was included in the installation of ltsp-server. Commandline options take precedence over config file options.

Kernel
A separate section for the client kernel is in order. A standard Genkernel kernel is created during the installation when configuration changes are made. It's advisable to take a closer look at the client's kernel config and use the config during the client install.

Building the Client
By default, the packaged quickstart profile in /etc/ltsp/profiles/quickstart.profile is used with no debug options. Another profile can be selected with command line options. The kernel config you just made can be used in the build process by adding the server vars to ltsp-build-client.conf (See in Configuration section above).

After invoking the ltsp-build-client command, the environment is preparing. For each architecture the first build takes up the most time because binary packages are created from source in the first run. These binary packages are stored in /usr/portage/packages through a bind mount on your server. Any consequent builds use these packages to speed up the process.

Finishing the Install
Some things still need to be done after building the environment. First up is the kernel, which needs to be put in your tftroot. In the default setup, this is copied from the chroot in /opt/ltsp and copied to the tftproot in an ltsp subdir in /var/lib/tftpboot, /tftpboot or /srv/tftp, if one exists. Calling ltsp-update-kernels with a different tftproot location:

Your pxelinux configuration has to be updated to reflect the changes in the setup. See the PXE boot section for more info.

For a user to be able to login over ssh from the thin client to the server, the client needs the server ssh-keys. Although executed when building the client, these can be updated to the clients chroot with the following command:

Client Configuration
While some properties of the client's environment are more or less statically set in the chroot environment, others can be changed at boot time. The lts.conf file allows properties to be set for all clients or for each workstation specifically. Explaining the syntax of the file goes beyond the scope of this tutorial, but it is explained on the LTSP wiki and in the lts.conf man page. The latter is available after emerging the ltsp-docs package.

The lts.conf file is downloaded at client boot time from a preconfigured location in the tftproot, namely /ltsp/i686/lts.conf. Create your lts.conf there and change your architecture if applicable.

The script that invokes the download is /etc/init.d/ltsp-client-setup. Together with /etc/init.d/ltsp-client it is responsible for settings like the swap configuration, sound daemon, and date among others. While ltsp-client-setup performs the environment settings, ltsp-client starts the sound daemon and the ldm login process. Some of these settings will now be discussed in detail.

LDM
If all is well, LDM will be started by ltsp-client and you can proceed to log in with a user on the server. If not, you might want to check if the LDM Info Daemon is disabled in /etc/xinitd.d/ldminfod. When the X server cannot start it might help to add your own xorg.conf file. As many different xorg.conf files can exist for many different clients in the same chroot, make sure to name them properly.

If you want another window manager, install it on the server and put the following in the LTSP configuration file (replace Fluxbox with the window manager of your choice).

5.3 Client
A 5.3 client is somewhat different from a 5.2 client. The main difference is that a 5.2 client has to be specifically prepared to function as an LTSP client while a 5.3 client takes care of this during the boot init process. In theory ltsp-client-5.3 can be installed on any Gentoo system, allowing it to be booted as an LTSP client.

Starting from ltsp-server-5.3, it's possible to install a 5.2 or a 5.3 client. This can be done by setting one of the different provided build profiles. By default, the quickstart-5.2.profile is used.

Booting a 5.3 client requires a custom init option in the PXE configuration:

Tips & Tricks
Several optional tips and tricks concerning LTSP can be found here. They are not Gentoo specific.

Chrooting
When chrooting into the client, you don't have a portage (and layman) tree in the client chroot by default. In the installation, the server portage tree (among others) is bind mounted in the client tree, which means the client chroot actually uses the server's copied portage tree. This can be achieved manually however since ltsp-server 5.2.19, the command ltsp-chroot can be used to chroot into a specified chroot. By default it chroots into /opt/ltsp/i686 and mounts nothing. Default behavior can be changed by using the /etc/ltsp/ltsp-chroot.conf file, or by using command line arguments. The following example mounts the portage and layman package dirs and chroots into /opt/ltsp-dev/amd64.

Local Apps
If you want apps to run on the client itself, a few changes need to be made. First of all, an extra line in your lts.conf.

Each application which has to run locally, needs to be installed in the client chroot. You can do this by chrooting into to client chroot environment and emerging the desired packages. It is also possible to combine this with your ltsp-build-client by adding the packages to the build client configuration.

When logged in on your LTSP client, you can now run an application locally by running the following command.

NBD Swap from USB
The nbdswapd allows clients to use swap space through a NBD. For this to work, the ltsp-server has to be emerged with the nbd USE flag enabled. Also, the lts.conf needs to be updated and the nbdswapd.conf has to contain the mountpoint of your usb stick and the desired swap size (64Mb by default).

LDM Greeter
The language of the texts in LDM are controlled by the client's locale. Some of the texts come from gtk while most are derived from ldm. You can see in /opt/ltsp/i686/usr/share/locale/your-language/LC_MESSAGES if ldm.po is available. If it is, the ldm messages will be translated if you set the client's language locale correctly.

If it isn't, to translate the file, download the template translation file from the LTSP upstream LDM trunk and translate it. Compile it and copy the binary to locale dir with:

The themes of the LDM greeter are stored in /opt/ltsp/i686/usr/share/ldm/themes where the symlink default points to the chosen theme.

Decreasing Chroot Size
You can make the make the built LTSP client chroot smaller using a combination of several methods. It's possible to get a chroot less than 1Gb. First up is the EXCLUDE var in the ltsp-build-client program. This can be used to automatically unmerge packages at the end of the client build.

If you never intend to do any maintenance on the chroot again, you can even unmerge gcc this way. Also you can remove the build time dependencies in the chroot by chrooting into the client chroot and executing the following command.

Another option are the x11 video card drivers. By default more than 10 are installed. By setting the VIDEO_CARDS variable in the LTSP build configuration (>= 5.3.6), the installed amount can be decreased to your need.

Rdesktop
Besides logging on to the LTSP server, you can also login to a Windows machine using Remote Desktop. For this to work, install into the client chroot and add the following to your lts.conf. Make sure a screen with ldm is defined (and replace the ip with your rdp server ip). Add rdesktop to your PACKAGES variable in ltsp-build-client.conf to install the program by default in each new client chroot.

Move the Chroot
You might want to move the client chroot installation on the server. This can be easily done with the following command. Don't forget to change to NFS entry in /etc/exports and reload it on the server prior to booting the client again.

If you want to copy the installation to another computer, archive it with tar, copy the archive and unpack it on the other server. Remember to not only install NFS on the new server and copy the /etc/exports file, but also the network boot file used by the PXE.

X11 Keyboard Layout
At the moment, X configuration is disabled. Therefore, all LTSP X settings (in lts.conf) does not work, especially XKBLAYOUT. For setting the X layout of clients do the following:

Then edit the file and add the line to the keyboard section of the evdev.conf

Kicktoo
Starting from ltsp-server-5.2.18, you can also use Kicktoo as a possible installer for ltsp-build-client (instead of the quickstart default). While only a 9999 version is available, versioned ebuilds will be available pending further stabilization upstream. To use this option, install Kicktoo and do the following:

Portage Profile
Since ltsp-server-5.3, most of the Portage settings needed to build an ltsp-client chroot are not set in the Quickstart or Kicktoo profiles anymore. Instead they are derived from an LTSP Portage profile. This profile is present in the ltsp overlay, and symlinked to the ${chroot}/make.profile during the ltsp-client install.

Debugging
Below some practical debug tips.

SSHD
Logging in to a booted client with ssh might also be useful. You need to perform three actions for this.
 * 1) Chroot into the client.
 * 2) Add sshd to the default runlevel.
 * 3) Add /etc/ssh to the copy_dirs variable in /etc/conf.d/ltsp-client-setup.

Log Files
On client: On server:
 * /var/log/ldm.log
 * /var/log/Xorg.7.log
 * /var/log/remote/
 * /home/ /.xsession-errors

Commands
On client:

On Server: should return tcp: :4713 Top like statistics of X11 client's server side resource usage to check if client's Pulse Audio daemon is listing on port 4713

virtual terminals on clients
Several programs will fight for the virtual terminals on the clients. Comment out getty in inittab:

Locales
ltsp-build-client does not work witch all locale. quickstart actually requires 'C' locale. So if ltsp-build-client shouts with the following message:

unset your locale, remove the directory and restart: