LTSP

The Linux Terminal Server Project 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:. This article will guide the administrator through the installation and configuration of a basic LTSP 5 system.

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

In addition to this guide, several other resources can be of aid while configuring the system. These can be found in the External resources section below.

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  USE flag is needed.

The LTSP server package needs a tftp and dhcp server. In this tutorial is 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.

Kernel
Besides the obvious drivers, the server kernel ought to have the following settings. If NFS is going to be used 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. Although the server depends on a range of possible packages, the manual will use the ones listed in this paragraph. The PXE bootloader is provided by. Dnsmasq is a DHCP/DNS/TFTP server. Advanced TFTP is also 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 as a DHCP/TFTP server. The TFTP server is used by the client nodes to retrieve the kernel, initramfs and lts.conf. For help on configuration, view the Gentoo Wiki 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 as well as the custom real_init option. You can test the work so far with a working kernel and system.

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.

NBD
Booting from NBD is still considered testing and doesn't work quite out-of-the-box. On the server, several changes are required besides installing. First, create an nbd-server initscript.

For the initscript to work, a default config file has to be created also:

Now, start the service now and at every boot.

System logging
System logging is performed by. Log files are not stored locally however, but sent to the server specified by SYSLOG_HOST in. 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  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. This command is responsible for building the entire chroot environment. And while and available plugins setup the environment, Kicktoo actually builds it. You can also use the Quickstart alternative.

Configuration
You can invoke the build script with command line arguments or configure the config file in. During the build, the packaged kicktoo profile in /etc/ltsp/profiles/kicktoo.profile is invoked. For both, example config files were included in the installation of ltsp-server, but other profiles can be configured. Commandline options take precedence over config file options.

Video cards
Make sure to check if the video card drivers that are needed are installed. By default only  and   are included.

Network cards
If Genkernel is used with non default network cards, add the  function in the kicktoo profile to add Genkernel network modules. This will be included in the next release (5.4.5).

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. Make sure the network drivers are included as modules.

Building the client
When all configuration has been done, start building the client.

After invoking the 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 through a bind mount on the 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 inside the tftproot. In the default setup, this is copied from the chroot in and copied to the tftproot in an ltsp subdir in,  or , if one exists. Calling with a different tftproot location:

The 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. Create the lts.conf there and change your architecture if applicable.

The script that invokes the download is. Together with it is responsible for settings like the swap configuration, sound daemon, and date among others. While performs the environment settings,  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 and it should be possible to log in with a user on the server. If not, it might be worth checking if the LDM Info Daemon is disabled in. When the X server cannot start it might help to add a customized 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.

To choose another window manager, install it on the server and put the following in the LTSP configuration file (replace Fluxbox with the chosen window manager).

NBD boot
If the  USE flag was enabled, it will be possible to generate a NBD bootable image and initramfs. This is optional (and testing) for now, so there are some steps to be followed to accomplish this. First, before the client install, configure the initramfs-builder for using Dracut. This generates an initramfs which allows to boot an NBD image.

An image has to be generated with. The resulting image ends up in.

Because Dracut's named export function isn't bugfree yet, export names can't end with a number (like ). It is therefore advised to configure the file manually. Look at the example in the server NBD part of the manual for a working example.

5.2 client
A 5.2 client is somewhat different from a 5.3 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 kicktoo-5.3.profile is used.

Booting a 5.3 client requires the following PXE configuration, without a real_init.

Tips and tricks
Several optional tips and tricks concerning LTSP can be found here. Most of them are Gentoo specific. Non-Gentoo specific tips & tricks can be found on the LTSP Wiki.

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

Decreasing chroot size
It is possible to 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 there is never any intention 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.

X11 keyboard layout
At the moment, X configuration is disabled. Therefore, all LTSP X settings (in ) 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

Quickstart
There is also the option to use Quickstart as a possible installer for (instead of the kicktoo default). Quickstart was the foundation of Kicktoo, but is not under active development anymore. To use this option, emerge it 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.

Troubleshooting
Bugs can be reported in two locations:


 * - For issues related to Gentoo.
 * - For issues related to LTSP itself.

Check the sections below for workarounds, and see if an existing bug has been opened before entering a potential duplicate bug.

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  locale. So if ltsp-build-client shouts with the following message:

unset your locale, remove the directory and restart:

External resources
Diskless Install
 * Gentoo Diskless install using PXE boot
 * Diskless Nodes with Gentoo
 * Syslinux' PXE Linux page
 * Etherboot Project page

Union Mounts
 * Unionfs: Bringing Filesystems Together
 * Aufs
 * aufs example
 * HOWTO Simple NFS Single System Image with Genkernel 4

Other
 * LTSP Upstream development
 * Mailing lists
 * into your favorite Linux distro
 * OpenSUSE LTSP Tips & Tricks
 * FreeNX
 * LTSP: Thin clients made easy
 * A Beginner "How To" for gtkrc themes
 * Ubuntu Community LTSP docs