Integrating LTSP-5 into your favorite Linux distro

So, let's say that you are an engineer at an organization that produces a distribution of Linux, and you want to integrate LTSP into your set of available packages. Here's roughly what you need to do:

1. Install an instance of the distro into a subdirectory on the server. You don't need all of the packages. You just need enough of an operating system to boot up the thin client, and launch an Xserver to connect back to the main server. The default location for the LTSP tree is /opt/ltsp. (/opt/ltsp/i386 for x86 thin clients, /opt/ltsp/ppc for PPC thin clients)

2. Install LTSP supplied scripts/executables into the tree
   • ltspfsd (http://bazaar.launchpad.net/~ltsp-upstream/ltspfs/ltspfs-trunk/, for more info see bottom of this wiki article)
   • get the following from bzr branch http://bazaar.launchpad.net/~ltsp-upstream/ltsp/ltsp-trunk/
     • • getltscfg
       • ldminfod
       • common and distribution dependend plugins, needed to get the client booted

3. Install a Linux kernel and an initramfs in a location accessible to your tftpd server. Usually /tftpboot/lts or /var/lib/tftpboot/ltsp
   • Your standard Linux kernel that you use to boot a full Linux machine should work just fine.

   • You may need to modify your initramfs to handle network booting. This includes sending out a DHCP request, and mounting the root filesystem via NFS.

   • Prepare the kernel and initramfs for PXE booting
     You'll need the pxelinux package which includes a Network boot loader (NBP) and configuration files.

   • Prepare the kernel and initramfs for Etherboot booting
     You'll need to install the mknbi package to tag the kernel + initramfs for network booting.

4. Configure the services on the server:
   • dhcp
   • tftp
   • nfs
   • xdmcp
   • nbd

Sounds pretty easy, eh? Well, don't be fooled. There's really quite a bit to it, once you dig in and see the gory details.

Start off by downloading a copy of the source tree, so we can work towards a common code base.

we use bzr http://bazaar-vcs.org for a version control system, so install that, and then:

bzr get http://bazaar.launchpad.net/~ogra/ltsp/ltsp-mainline ltsp-YOUR-DISTRO

(recent changes to that branch can be seen on https://launchpad.net/people/ogra/+branch/ltsp/ltsp-mainline a list of branches is under https://launchpad.net/products/ltsp/+branches)

a good first step is to gain an understanding of server/ltsp-build-client. this is the tool used to generate your /opt/ltsp/i386 (or other arch) chroot. it is a pretty basic script, itself. it essentially calls a series of plugins in alpha-numeric order:

taken from server/doc/plugins in the sources (check there for the most up-to-date information):

common plugins are located in /usr/share/ltsp/plugins/ltsp-build-client/common, while vendor-specific plugins are defined in /usr/share/ltsp/plugins/ltsp-build-client/VENDOR. if a vendor plugin has the same filename as a common plugin, it will override the common plugin. optionally, the admin can install or override common or vendor plugins in /etc/ltsp/plugins/ltsp-build-client.

NOTE: Plugins are "sourced" not "executed", so be careful to avoid such things as "exit" in your plugin scripts

each plugin should be written in such a way as the code is only executed in the appropriate phase, such as wrapping the code in case statements.

there are several modes in which these plugins are called:

commandline:

builds the list of commandline arguments supported by the loaded plugins

configure:

sets variables for commandline options that are set

we recommend putting very early in your DISTRO plugin dir a plugin such as 000-basic-configuration that detects and defines some appropriate variables for your distro- like which particular version of the distro you are running, default lists of packages or package sets to install, default package mirror to use, etc.

before-install:

before the initial chroot is built

install:

where the initial chroot is built

in the install phase, you want to essentially bootstrap a basic chroot of your distro. on Debian, this is done with the debootstrap tool. this will obviously vary greatly for each distro.

after-install:

additional package installation(ltsp-client), tweaks, etc.

in the after-install phase, you may want to add additional packages that might be difficult to include as part of the initial bootstrapping of the chroot, if the bootstrap tools don't support proper dependency resolution (i.e. debootstrap). you may want to add certain configuration tweaks to certain packages at this point as well, such as configuring an initramfs generator so it will support NFS root.

finalization:

in the finalization phase, you may want to install additional packages that needed custom configurations to other software before installing, such as a kernel (which may require certain initramfs tweaks). you may also want to copy the kernel images into a location accessible by tftp at this phase, or seed the chroot's /etc/ssh/ssh_known_hosts file with your server's public ssh keys.

for starting a new distro implementation, focus on the configure, install, after-install, and finalization phases at first.

ltsp-client init scripts

i hate to say it, but the current init scripts are very distro specific. we intend to improve that in the future, but take a look at: debian/ltsp-client.init and debian/ltsp-client.ltsp-client-setup.init to get a basic idea for what they do.

/etc/init.d/ltsp-client-setup (a.k.a. debian/ltsp-client/ltsp-client-setup.init):

• mounts certain directories and files as writeable using tmpfs and bind mounting
• loads MODULE_NN modules
• loads CONSOLE_KEYMAP
• configures swap (using NBD and/or local hard disk)
• configure syslogging to a server
• loads custom RCFILE_NN scripts
• configures X
• configures local devices (usb sticks, cdrom/floppy drives) using ltspfs
• configure local printer

/etc/init.d/ltsp-client (a.k.a. debian/ltsp-client.init):

• starts a sound daemon such as esd, nas or polypaudio if sound is configured
• starts screen sessions using the client/screen_session command, such as an LDM or XDMCP session, NX client session, shell, etc.

The init scripts can be extracted from the debian package ltsp-client located at: http://packages.debian.org/src:ltsp It is further interesting to inspect the package ltsp-server as well.

ltspfs

It is not clear where the ltspfs project is hosted. A version can be downloaded from: http://packages.ubuntu.com/edgy/misc/ltspfs

The sources in the /opt/ltsp tree have to be kept up to date seperate from the main distribution. This could be done e.g. with:

 chroot /opt/ltsp; apt update; apt -y upgrade