Important: You are required to change your passwords used for Gentoo services and set an email address for your Wiki account if you haven't done so. See the full announcement and Wiki email policy change for more information.

LTSP

From Gentoo Wiki
Jump to: navigation, search
External resources

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: 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.

Bugs can be reported in two locations. Check known issues before entering a potential duplicate.

  • Gentoo - For issues related to Gentoo
  • Upstream - For issues related to LTSP itself
Warning
LTSP and some other software used in this guide are not in the stable Portage tree.
Note
This tutorial uses i686 as architecture for the client install (x86 before ltsp-server-5.2.19)


Server Preparation

Installation

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

root # layman -a ltsp

The LTSP server package needs a tftp and dhcp server. In this tutorial net-dns/dnsmasq is used. It also requires a system logger which can accept client messages over tcp, for which app-admin/syslog-ng 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:

→ Information about USE flags
USE flag Default Recommended Description
dhcp No Installs a dhcp server, either dhcp or dnsmasq.
doc No Adds extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
examples No Install examples, usually source code
nbd No Client boot over NBD options are enabled.
nfs No Yes Client boot over NFS options are enabled.
pulseaudio Yes Yes Adds support for PulseAudio sound server
X Yes Yes Adds support for X11
root # emerge --ask app-admin/syslog-ng net-misc/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.

Kernel configurationLTSP server

File systems  --->
    [*] FUSE (Filesystem in Userspace) support
    [*] Network File Systems  --->
        <*> NFS server support
        [*]  NFS server support for NFS version 3

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 sys-boot/syslinux. 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 net-dns/dnsmasq 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.

File/var/lib/tftpboot/pxelinux.cfg/defaultltsp-client 5.3+

kernel kernel-YOURKERNELVERSION
append initrd=initramfs-YOURKERNELVERSION root=/dev/nfs nfsroot=YOURSERVERIP:/opt/ltsp/i686 real_init=/sbin/init-ltsp

Start the services, now and at every boot

root # /etc/init.d/dnsmasq start
root #
rc-update add dnsmasq default

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.

File/etc/xinetd.conf

...
only_from = 192.168.0.1/24
...
root # /etc/init.d/nfs start
root #
/etc/init.d/xinetd start
root #
rc-update add nfs default
root #
rc-update add xinetd default

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 sys-block/nbd. First, create an nbd-server initscript.

File/etc/init.d/nbd-server

#!/sbin/runscript

command="/usr/bin/nbd-server"
pidfile="/var/run/${SVCNAME}.pid"

depend() {
        use net
}

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

File/etc/nbd-server/config

[generic]
[ltsp]
exportname = /opt/ltsp/images/i686.img
readonly = true

Now, start the service now and at every boot.

root # /etc/init.d/nbd-server start
root #
rc-update add nbd-server default

System Logging

System logging is performed by app-admin/sysklogd. 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.

Note
Remote logging is only activated if SYSLOG_HOST is specified.
File/etc/syslog-ng/syslog-ng.conf

source net { udp(); };
destination remote { file("/var/log/remote/$FULLHOST"); };
log { source(net); destination(remote); };
root # /etc/init.d/syslog-ng restart

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 pulseaudio, 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, Kicktoo actually builds it. You can also use the Quickstart alternative.

Note
By default a 5.3 client is installed, for a 5.2 client, read the instructions.
Note
By default an NFS client is installed, for an NBD client, read the instructions.

Configuration

You can invoke the build script with command line arguments or configure the config file in /etc/ltsp/ltsp-build-client.conf. 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 you check if the video card drivers you need are installed. By default only fbdev and vesa are included.

File/etc/ltsp/ltsp-build-client.conf

VIDEO_CARDS="vesa intel radeon mach64"

Network Cards

If you use Genkernel and non default network cards, add the post_install_initramfs_builder() function in the kicktoo profile to add Genkernel network modules. This will be included in the next release (5.4.5).

File/etc/ltsp/profiles/kicktoo.profile

post_install_initramfs_builder() {
	if [ "${initramfs_builder}" == "genkernel" ]; then
		# add you're own network drivers if needed
		# eg. "MODULES_NET=\"\${MODULES_NET}\" via-rhine"
		echo "MODULES_NET=\"\${MODULES_NET}\"" >> "${chroot_dir}/usr/share/genkernel/arch/${MAIN_ARCH}/modules_load"
	fi
}

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 your network drivers are included as modules.

Kernel configurationLTSP client

General setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support 

[*] Networking support  ---> 
    Networking options  --->
        [*] IP: kernel level autoconfiguration
        [*] IP: DHCP support
        [*] IP: BOOTP support 

Device Drivers -->
    [*] Block devices  --->
        <M>   Network block device support

File systems  ---> 
    <*> Kernel automounter version 4 support (also supports v3)
    <*> FUSE (Filesystem in Userspace) support
    [*] Network File Systems  --->
        <M>   NFS client support
        [*]     NFS client support for NFS version 3
        [*]     NFS client support for the NFSv3 ACL protocol extension
        [*]     NFS client support for NFS version 4 (EXPERIMENTAL)
File/etc/ltsp/ltsp-build-client.conf

KERNEL_SOURCES="=sys-kernel/gentoo-sources-2.6.34-r12"
KERNEL_CONFIG_URI="tftp://192.168.67.1/ltsp/x86/gentoo-sources-2.6.34-r12.config"

Building the Client

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

root # ltsp-build-client --config=/etc/ltsp/my-ltsp-build-client.conf

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.

Note
When having to perform ltsp-build-client again, it is recommended to first copy the downloaded stage outside the chroot and point the ltsp-build-client command to it, so it won't have to be downloaded again.

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:

root # ltsp-update-kernels --tftpdirs="/opt/tftproot"

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:

root # ltsp-update-sshkeys

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.

File/var/lib/tftpboot/ltsp/i686/lts.conf

[default]
 SERVER=192.168.67.1
Note
The default LTSP server ip is set to 192.168.67.1, set yours if it is different.

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.

File/var/lib/tftproot/ltsp/i686/lts.conf

[acer-aspire-one]
  X_CONF = /etc/X11/xorg-acer-aspire-one.conf

[00:1E:68:C2:FF:EE]
  LIKE=acer-aspire-one

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).

File/var/lib/tftpboot/ltsp/i686/lts.conf

LDM_XSESSION = /usr/bin/fluxbox

NBD Boot

If you configured the nbd USE flag, you'll be able to generate a NBD bootable image and initramfs. This is optional (and testing) for now, so you have to follow some steps 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.

File/etc/ltsp/ltsp-build-client.conf

INITRAMFS_BUILDER="dracut"
Warning
A Dracut initramfs won't boot from NFS (tested <025).

You have to generate an image with ltsp-build-client. The resulting image ends up in /opt/ltsp/image/i686.img.

root # ltsp-update-image i686

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

5.2 Client

Warning
This is deprecated.

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.

File/etc/ltsp/ltsp-build-client.conf

INSTALLER_PROFILE=/etc/ltsp/profiles/quickstart-5.2.profile

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

File/var/lib/tftpboot/pxelinux.cfg/defaultltsp-client-5.2

kernel kernel-YOURKERNELVERSION
append initrd=initramfs-YOURKERNELVERSION root=/dev/nfs nfsroot=YOURSERVERIP:/opt/ltsp/i686

Tips & 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 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).

File/etc/ltsp/nbdswapd.conf

SIZE=128
SWAPDIR=/mnt/usbswap
File/var/lib/tftpboot/ltsp/i686/lts.conf

[default]
  NBD_SWAP = True

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.

File/etc/ltsp/ltsp-build-client.conf

EXCLUDE="sys-apps/man-pages sys-kernel/genkernel"

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.

root # emerge --depclean --with-bdeps=n
Note
If you build a client a second time from binary packages, those build time dependencies won't be installed.

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:

root # mkdir /opt/ltsp/i686/etc/X11/xorg.conf.d/
root # cp /opt/ltsp/i686/usr/share/X11/xorg.conf.d/10-evdev.conf /opt/ltsp/i686/etc/X11/xorg.conf.d/10-evdev.conf

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

File/opt/ltsp/i686/etc/X11/xorg.conf.d/10-evdev.conf

Option "XkbLayout" "fr"

Quickstart

Warning
Support for Quickstart is deprecated, see the Gentoo Bug, comment 186, for more info.

You can also use Quickstart as a possible installer for ltsp-build-client (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:

File/etc/ltsp/ltsp-build-client.conf

...
INSTALLER=quickstart
INSTALLER_PROFILE=/etc/ltsp/profiles/quickstart.profile
...

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.

Warning
Any changes made in this profile will be reset when syncing the overlay.

Troubleshooting

python_get_implementational_package not installed

  • reported on: 2011-06-06
  • reported by: Wimmuskee
  • no bug

problem

An emerge error for "=dev-lang/python-2.6* is not installed", with a "die "$(python_get_implementational_package) is not installed";"

solution

This means that some of your binary packages were installed against Python 2.6, Remove your binary packages to let them compile against your new python environment.

do not move package and distfiles dir

  • reported on: 2012-02-19
  • reported by: Wimmuskee
  • no bug

problem

The ltsp-build-client and ltsp-chroot programs asume the portage package and distfiles dirs are at Gentoo defaults when they bind mount it into the chroot. Symlinking to another location won't work, neither is moving the dir although refering correctly in /etc/portage/make.conf, all created packages will still be made in /usr/portage version.

solution

Leave the packagedir to default.

virtual terminals on clients

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

File/opt/ltsp/i686/etc/inittabcommenting example

...
# TERMINALS
#c1:12345:respawn:/sbin/agetty 38400 tty1 linux
#c2:2345:respawn:/sbin/agetty 38400 tty2 linux
#c3:2345:respawn:/sbin/agetty 38400 tty3 linux
#c4:2345:respawn:/sbin/agetty 38400 tty4 linux
#c5:2345:respawn:/sbin/agetty 38400 tty5 linux
#c6:2345:respawn:/sbin/agetty 38400 tty6 linux
...

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:

root # ltsp-build-client ...
No fetcher for protocol: file

unset your locale, remove the directory and restart:

root # unset LANG; unset LC_ALL; ltsp-build-client --purge

External resources

Diskless Install

Union Mounts

Other