LTSP 4.2 Local Device support.

Overview

Local device support in LTSP 4.2 has been greatly improved. At its core, it's now using udev for handling plug events on the thin client, and the LtspFS filesystem for transmission of the data from the thin client.

Currently, support is included for the following devices:

• IDE cdroms
• Legacy floppy devices
• USB floppies
• USB cdroms
• Partitioned USB memory sticks. Unpartitioned sticks are not supported.

There are 2 parts required for successful plugging of devices: the udev rules and scripts that run on the thin client, and are included as part of the LTSP distribution, and the server side support programs, which are included as a separate package that must be installed on the server.

Installation

There are a few steps required for the installation of LTSP local device support.

Distribution specific pages

This page has become quite long. So some people wrote distribution specific pages for some Distributions:

• Alt Linux specific page
• Debian Etch specific page

Modify your dhcpd.conf

If you're using assigned addressing (i.e. you have host {} entries), make sure you're specifying:

use-host-decl-names         on;

in the dhcpd.conf section where you're specifying the hosts.

For dynamic host assignment, you'll want:

get-lease-hostnames         true;

IMPORTANT: The two settings are exclusive, so if you've got use-host-decl-names turned on globally, you're going to have to turn it off in the dynamic section of the dhcpd.conf file. Remember to restart your dhcpd server after modifying the file.

Install FUSE on your system

Note: while adding ALT Linux-related sections, I've created a specific page and propose to do so with all described distro-specific recipes.

Debian Etch

Look at the Debian Etch specific page azracon reports success using the Sarge fuse-source package from packages.debian.org with the Sarge localdev package available here

Debian Sarge

Sarge uses an older version of FUSE, however, LTSPFS will work just fine with this version. The only issue is that a dead mount won't time out by itself, but rather will timeout and unmount when a filesystem operation is actually tried.

• If you don't already have the 2.6.8 kernel, install it on your server.

aptitude install kernel-image-2.6.8-3-386 kernel-headers-2.6.8-3-386

• Reboot using the new 2.6.8 kernel.
• Install FUSE:

aptitude install fuse-source fuse-utils libfuse2

• Install module-assistant, if you don't already have it.

aptitude install module-assistant

• As root, build the fuse module

m-a a-i fuse

• Load the FUSE module into the kernel.

modprobe fuse

If this works, you'll want to add "fuse" to your /etc/modules file so that it'll be there whenever you reboot the server.

echo "fuse" >> /etc/modules

As well, in order for your LtspFS mounts to be visible by nautilus, you'll need to create the file /etc/fuse.conf, and add the following line:

user_allow_other

This will allow famd to gain access to your LtspFS mount.

Debian-Edu/Skolelinux

Same as for Debian Sarge, but make sure you use the correct kernel-image and kernel-headers, substitute 2.6.8-3-386 with 2.6.8-3-686-smp if you use a smp-enabled kernel.

-- KlausAdeJohnstad - 06 Jul 2006

Ubuntu Breezy

Ubuntu already includes the FUSE module, so you only need to install the libraries.

• Install FUSE:

aptitude install fuse-utils libfuse2

• Load the FUSE module into the kernel.

modprobe fuse

If this works, you'll want to add "fuse" to your /etc/modules file so that it'll be there whenever you reboot the server.

Fedora Core 4

Fedora already includes the FUSE module, so you only need to install the libraries.

• Install FUSE:

yum install fuse fuse-libs

• Load the FUSE module into the kernel.

modprobe fuse

SuSE 9.2

SuSE 9.2 does not include the FUSE module, so you need to compile and install manually

* Compile and Install FUSE

Download the Fuse source from http://fuse.sourceforge.net/. Untar it:

tar -xzvf fuse-2.5.3.tar.gz

and compile it:

cd fuse-2.5.3
./configure
make
checkinstall

or

make install

if you don't have checkinstall installed.

* Load the FUSE module into the kernel.

modprobe fuse

To add the module to be started automatically at boot time of the server, go to YaST->System->Editor for /etc/sysconfig-files/System->Kernel->MODULES_LOADED_ON_BOOT and add there

fuse

Missing symlink to libfuse

As root, goto /usr/lib and do:

link -s /usr/local/lib/libfuse.so.2

This creates a symlink to libfuse. Without it, a USB-stick will show up empty in KDE/SuSE9.2

(Open)SuSE 10.0

SuSE already includes the FUSE module, so you only need to install the libraries.

• Install FUSE:

If you use APT or smart, just type

apt|smart install fuse

FUSE is located in the 'packman' repository. If you do not use APT or smart, go to the packman homepage, get the file for your architecture and install it with

rpm -i PACKAGE_NAME

• Load the FUSE module into the kernel.

modprobe fuse

To add the module to be started automatically at boot time of the server, go to YaST->System->Editor for /etc/sysconfig-files/System->Kernel->MODULES_LOADED_ON_BOOT and add there

fuse

Slackware Linux 10.x and 11.0

Slackware still comes with a 2.4.x kernel, so you need to get the 2.6 packages in the extra or testing dir, or use a third-party precompiled package, or compile it yourself.

The easiest way is using a precompiled package. These are available here at linuxpackages.net for Slackware 10.2 and 11.0. They include both the Fuse kernel module for the 2.4 kernel shipping with the system and the Fuse library and userspace utilities.

For compiling from source, use:

• testing - just get the packages, installpkg them and change your /etc/lilo.conf
• kernel source - you'll need to compile, remember to include FUSE either as a module or builtin, it's under: File Systems ---> Filesystem in Userspace support.

You'll also need the Fuse library. Download the Fuse source from http://fuse.sourceforge.net/. Untar it:

tar -xzvf fuse-2.5.3.tar.gz

and compile it:

cd fuse-2.5.3
./configure
make
checkinstall

or

make install

if you don't have checkinstall installed.

ALT Linux 3.0 or Sisyphus

Note: brief description here.

Everything is packaged already (also available here), on 3.0 with 2.6.12 you should consult `uname -r` for UP or SMP kernel running and install FUSE kernel module package:

apt-get install kernel-modules-fuse-std26-up

or

apt-get install kernel-modules-fuse-std26-smp

FUSE got included into vanilla 2.6.14, so you won't need to do that for recent kernels. Anyways, next do

apt-get install fuse
modprobe fuse && echo fuse >> /etc/modules

Adding users to the "fuse" group

Any users who you want to provide localdevice access to must be added to the "fuse" group. You can usually accomplish this (as root) by executing:

Debian, Ubuntu

adduser someuser fuse

Debian-Edu/Skolelinux

Since we use Ldap for authentication, using adduser won't help. The proper method is to add a group to Ldap, I'll look at that later, for now we let everyone use it: Add this line to the file /etc/udev/rules.d/60-fuse.rules

KERNEL="fuse", NAME="%k", MODE="0666",OWNER="root" GROUP="fuse"

Then you remove and add the fuse module again (or you could just reboot ...), this time you will see that /dev/fuse has the rights 0666/crw-rw-rw-, open to everyone.

rmmod fuse
modprobe fuse
stat /dev/fuse
  File: `/dev/fuse'
  Size: 0               Blocks: 0          IO Block: 4096   character special file
Device: ch/12d  Inode: 251701      Links: 1     Device type: a,e5
Access: (0666/crw-rw-rw-)  Uid: (    0/    root)   Gid: (  119/    fuse)

You must also open up the access to /usr/bin/fusermount

chmod 4755  /usr/bin/fusermount

Fedora

usermod -G fuse -a someuser

The -a flag is required to avoid removing the user from current groups

(Open)SuSE 10.0 and SuSE 9.2

There is no need to do this.

Slackware Linux 10.x

There is no need to do this.

Slackware Linux 12

I had to put the users at fuse group. Otherwise it doesn't work.

usermod -G fuse someuser

ALT Linux

You can either let everyone use fusermount:

control fusermount public

or restrict it to "wheel" group and add users there (which might have other implications):

control fusermount public
apt-get install shadow-groups
gpasswd -a someuser wheel

Installing X11 library support for perl

LTSP's event notification system, lbus, needs X11 support in perl. You'll need to install the appropriate libraries to get this to function. Note: you CANNOT install the X11::Protocol module though ssh or ny any other means of remote connection. The perl module installation should be done at the actual X console of the TS.

Debian Sarge

aptitude install libx11-protocol-perl

Debian-Edu/Skolelinux

aptitude install libx11-protocol-perl

Ubuntu Breezy

aptitude install libx11-protocol-perl

Fedora Core 4

yum install perl-X11-Protocol

(Open)SuSE 10.0 and SuSE 9.2

For SuSE there is no packaged module. So you need to install it from CPAN. Open a perl shell as root with

perl -MCPAN -e shell

Say yes to all questions or give witted answers. Then type

install X11::Protocol

Say yes to all questions wether to install dependencies and leave the perl shell with

q

While installing a window should pop up that titulates itself as window and wants to be closed.

Slackware Linux 10.x

For Slackware there is no packaged module, so you need to install it from CPAN, the worldwide Perl module repository. There is a handy cpan2tgz program for automatically getting Perl modules from CPAN and making them into Slackware packages. Get it and type (as root):

cpan2tgz X11::Protocol

If you never used CPAN before, you might have to answer a bunch of configuration questions; the defaults should work. Other than that, the module will be automatically downloaded, packaged and installed. The perl-x11-protocol package is left in /usr/src.

If CPAN displays an error message and won't install, you can download X11:Protocol from ftp://ftp.cpan.org/pub/CPAN/authors/id/S/SM/SMCCAM/X11-Protocol-0.55.tar.gz. Untar it and install it thus:

tar -xzvf X11-Protocol-0.55.tar.gz
cd X11-Protocol-0.55/
perl Makefile.pl
make install

If you return to MCPAN and type

install X11::Protocol

again, you will get the message: "X11::Protocol is up to date"

ALT Linux 3.0 or Sisyphus

The package is available in unstable (Sisyphus) and should be available in backports/3.0 shortly; in the latter case, you need to add that repository before doing

apt-get install perl-X11-Protocol

Installing the LTSP localdev support package.

The LTSP localdevice support package contains both localdevice files, and files needed for NBD swapping.

Debian Sarge

• Download the file Download deb
• Install it with:

dpkg -i <file>

Debian-Edu/Skolelinux

• Download the file Download deb
• Install it with:

dpkg -i <file>

Ubuntu Breezy

• Download the file Download deb
• Install it with:

dpkg -i <file>

Fedora Core 4

• Download the file Download rpm
• Install it with:

rpm -i <file>

(Open)SuSE 10.0 and SuSE 9.2

• Download the file Download rpm
• Install it with:

rpm -i <file> --nodeps

Use '--nodeps' because of the perl module not being registered in the RPM database. Because some tools like APT refuse to work properly with packages installed with broken dependencies, delete the package out of the database with

rpm -e ltsp-server-pkg-fedora --justdb

If you don't want to have a package installed without being registered in the RPM database (which is mostly no really good idea) you can do the following instead. Install cpan2rpm. When you use APT or smart just type

apt|smart install perl-cpan2rpm

cpan2rpm is located in the repository 'suser-oc2pus'. I you do not use APT or smart download the package perl-cpan2rpm from http://ftp.gwdg.de//pub/linux/misc/suser-oc2pus/10.0/RPMS/noarch/ and install it with

rpm -Uhv <file>

Type

cpan2rpm --install X11::Protocol

This will build a RPM package 'perl-X11-Protocol-SOME_VERSION' in /usr/src/packages/RPMS/i386/ and install it. As last step install the ltsp server package with

rpm -Uhv <file>

Slackware Linux 10.x

• Download the file Download rpm
• Install it with:

rpm2tgz ltsp-server-pkg-fedora-0.1-1.i386.rpm
installpkg ltsp-server-pkg-fedora-0.1-1.i386.tgz

ALT Linux 3.0 or Sisyphus

The packages should be soon available in both unstable (Sisyphus) and backports/3.0 so just do

apt-get install ltsp-server-pkg

It's a meta package, it will pull all the rest needed (including perl-X11-Protocol).

Others

• Download the file Download tarball of statically built binaries
• Install it with:

tar xzf ltsp-server-pkg-static-0.1.tgz

Then, read the README file in the ltsp-server-pkg-static-0.1 directory.

Enabling localdevice on the client

In your lts.conf file, either in the [Defaults] section, or on a per-workstation basis, adding the line:

LOCAL_STORAGE = Y

Disabling local device access for the floppy drive

If you use Etherboot floppy disks to boot clients, the localdevice system (LDA) will scan the floppy disk every time any local device, e.g., a USB stick, is accessed. This slows down access to the other local devices, and since the floppy is being used to boot the client, you probably don't want users using the floppy drive anyway. To prevent LDA from accessing the floppy drive, edit the /opt/ltsp/i386/etc/udev/rules.d/15-ltsp-block.rules file and comment out this line in the Legacy Floppy section:

KERNEL=="fd[0-9]*",     RUN+="/etc/udev/scripts/ltsp-device.sh"

-- PetreScheie - 17 Aug 2006

Replacing the default icon with something else.

If you want to have another looking icon popup on your desktop, then replace the line in /etc/ltsp-localdev.conf with the name of you prefered icon, either full path to icon, or like this:

FOLDER_ICON="usbpendrive_unmount"

Enabling autostart of lbussd on the server with (Open)SuSE 10.0 and Slackware Linux 10.x

Because the RPM package has been built for Fedora, lbussd won't automatically start. To get around this, you need to edit the file /etc/X11/xinit/xinitrc and add the following line BEFORE the line that looks like: 'exec $WINDOWMANGER'

sh /etc/X11/xinit/xinitrc.d/lbus-start.sh

If some users have their own ~/.xinitrc, they have to add this line there.

For a system using KDE (this works with 3.5.2), you can make the following link:

mkdir /opt/kde/env
cd /opt/kde/env
ln -s /etc/X11/xinit/xinitrc.d/lbus-start.sh .

SLACKWARE 11.0

If you are using SLACK and KDM, then xinitrc won't work, insted add sh /etc/X11/xinit/xinitrc.d/lbus-start.sh & to /opt/kde/share/config/kdm/Xsession and that's it. Also you don't have to make the link in /opt/kde/env ... enjoy

At this point, you should be able to reboot your workstation, and start plugging devices!

AudioCD's

There is no official support for Audio CD's under 4.2. For discussion of possible solutions, and implementations in progress, please see LtspAudioCd.

Normal Use

Safely Removing Devices

Jim McQuillan wrote this on the ltsp-discuss mailing list:

This is one of the coolest features of the local device support in LTSP-4.2.

Once the local device has been idle for 2 seconds, it is internally un-mounted, so that there's no data lingering around in buffers, and the filesystem is sync'd properly. Even though the device isn't mounted, the icon stays on the screen. If the user accesses anything on the device, it will automatically re-mount it and read/write it.

A user certainly shouldn't be pulling the usb stick out in the middle of saving a document, but once the save operation is finished, only 2 seconds is needed before you can pull the device.

-- JasonMaas - 07 Jul 2006

Troubleshooting

Well, Local Device support is a difficult topic. There's a lot of little bits that need to all work well together in order for the whole thing to work. Have no fear, if localdev isn't working well for you, here's where to look for help.

IMPORTANT: Chances are, you've posted on the mailing list, or are in IRC, and have been directed here for help. IT IS IMPORTANT THAT YOU DOCUMENT EACH STEP COMPLETELY, PROVIDING ALL OUTPUT FOR EACH STEP. Failure to do so will more than likely meet with the request that you do it again. We're happy to help, but we need ALL the information to do so, and the reason why we've documented this procedure is so that we don't have to re-ask all these questions again.

Step 1: Disable X on the workstation.

We'll want to start out by switching to a text shell on the client. You'll want to change the line that says:

SCREEN_01 = startx

to:

SCREEN_01 = shell

Reboot the workstation, and you should be sitting at a command prompt.

Step 2: Are you running LTSP 4.2?

Sometimes, if you've not got things set up correctly in your dhcpd.conf file, you may not actually be running 4.2. The easiest way to check this is by running the following command on the workstation:

cat /etc/version

You should see something that looks like:

VERSION=4.2

If not, go back and check your dhcpd.conf file. Specifically, your root-path line.

Step 3: Determining if LOCAL_STORAGE is on.

On the workstation, execute the command ps -ef | grep lbuscd. If you see the lbuscd running, then LOCAL_STORAGE has been enabled. There should also be a /tmp/drives directory. If neither of these are there, then you haven't properly specified LOCAL_STORAGE = Y in your lts.conf file.

Step 4: Does your workstation know its name?

At the command prompt, type the command "hostname". You should see a name come back like ws001, or some other valid name. If you get a blank, then the workstation doesn't know it's name, and LTSPFS authentication won't work. Re-check your dhcpd.conf file as per the instructions in the installation section.

Step 5: Do you have devices in your fstab?

If you're trying to get USB plugging going, plug in a device now. A USB CDrom, floppy, or memory stick should work fine. You should see some messages pass by on the screen, indicating that the right kernel modules are being loaded.

If it's legacy CDroms, or legacy floppies you're after, these should have been detected when the workstation booted.

In either case, if you cat /etc/fstab (on WS) you should see some device entries in there. If the file is empty, then udev isn't recognizing your device. Make sure you've got the USB controller or IDE/Floppy controller on your thin client enabled in the BIOS. If it still doesn't work, then there's something else going on. Please contact the LTSP developers on the LTSP mailing list or IRC channel for assistance.

Step 6: Booting X.

If you can plug in a device, and you get an fstab entry, then things are probably ok on the thin client, now we can boot into the server, and log in as the user who we want localdev to work for. To get X started up, you can type the following:

startx

Log in as the user, and open up an xterm.

Step 7: Is the user in the fuse group?

At the xterm prompt, type the command id. One of the groups listed should be the fuse group. If not, then make sure you add the user to the fuse group. You'll have to log out and log back in again for it to take effect.

Step 8: Is lbussd running?

As the user, check that lbussd is running on TS. This should have been started by the startup script /etc/X11/Xsession.d/51lbus-start on Debian and Ubuntu, and /etc/X11/xinit/xinitrc.d/lbus-start.sh on Fedora core. You can check this with ps -ef | grep lbussd. If it's not running, then either the login manager isn't picking up the startup script, or, something's wrong with lbussd. A probable cause of it not starting up would be that you don't have the X11 perl protocol package loaded. Check the installation section above for instructions on how to install it.

Step 9: Is the fuse module loaded?

Execute the following command: lsmod | grep fuse (on TS). The fuse module should appear. As well, in your /dev directory, you should have a /dev/fuse file, owned by root, and group owned by fuse, with permissions 660. If not, then something's wrong with your fuse install; check distro-specific advise above.

Step 10: Does your $DISPLAY variable match the terminal's hostname?

Execute the following command: echo $DISPLAY. You should get back something that looks like the following:

ws001:0.0

The bit before the colon (the hostname part) must EXACTLY match the hostname that the terminal thinks it has back in step 3. If it's different, then the dhcp server is handing out a name that's different from what the server THINKS your hostname is. Check your dhcpd.conf for which name is being assigned to the terminal.

Step 11: is the lbus_event_handler firing?

A quick verification that the whole LtspFS system is working, is to try to manually fire up a mount. You should be able to manually invoke a mount by executing the following in an xterm:

/usr/sbin/lbus_event_handler.sh add block /tmp 1024 Temp

An icon should pop up on the desktop, called "Temp", and browsing it should reveal the /tmp directory on your client. If not, check to see if a "tmp" folder is created in your $HOME/Drives directory, and that a "Temp.desktop" file appears in your $HOME/Desktop folder.

As well, the command mount should show an ltspfs mount in your home directory, similar to this:

ltspfs on /home/sbalneav/Drives/tmp type fuse (rw,nosuid,nodev,user=sbalneav)

To remove the mount, type the following:

/usr/sbin/lbus_event_handler.sh remove block /tmp 1024 Temp

The icon should disappear, as well as the directory in $HOME/Drives. As well, the mount command should not show the ltspfs mount anymore.

If there are any errors printed out by the lbus_event_handler.sh script, save them, and check on the IRC channel or the mailing list. They are important, and will help the people there to help you.

Things that might cause you trouble if this script fails:

• If you've compiled fuse yourself, and installed it, make sure that the fusermount program is owned by root, and setuid root (i.e. permissions look like rwsr-xr-x). Also, make sure you haven't got the fusermount program on a filesystem mounted with the nosuid flag (check your /etc/fstab file)
• Make sure your user's $HOME environment variable is set. I've seen some people running ldap authentication who haven't got some of the standard environment variables set. Checking if $HOME is set correctly will ensure this.

Step 12: Reboot, and plug.

If everything's checked out OK from this point, then you should be able to reset:

SCREEN_01 = startx

in your lts.conf, and reboot the box. Hopefully, localdevices should work for you. If not, don't hesitate to contact us. As well, keep watching this space for the first few weeks after release. We may update some packages if bugs that weren't discovered during development rear their ugly heads.

User Reported Problems:

If you're a user of LTSP, please put your comments, or contributed info here:

• If lbus_event_handler.sh gives you an error about a stale ~NFS handle, it's because ltspfs can't mount on ~NFS (sometimes or always?), so you need to move your mount point from ~/Drives to somewhere else. See Bug 6560 for a patch.
  • I've since updated this bug, LtspFS works fine for me on several tested systems under NFS, in fact, it was one of my design requirements, as I use NFS for home directories where I work. If someone's having trouble with this, I'd like to work through the problem, rather than coming up with a myriad of patched lbus_event_handlers. There's nothing in the design of ltspfs that should cause it not to work under NFS. -- ScottBalneaves
• lbus_event_handler.sh: Edited lbus_event_handler.sh, will create symlinks for devices in homedir - handy with OpenOffice^?.
  • I'm not sure why this is necessary, as you can simple do a file->open and look in the Drives folder in your home directory to find the devices. I haven't tested this, you'll have to contact the patch author for help on this if it doesn't work for you. -- ScottBalneaves

-- ScottBalneaves - 16 May 2006

• If you are using KDE and you want to be able to change icon themes while still keeping an appropriate folder icon for the mounted media, you can change the file /etc/ltsp-localdev.conf, and uncomment the line # FOLDER_ICON="gnome-fs-directory.svg" and change it to FOLDER_ICON="folder.png".

Of course you can choose any icon you want, this one seems to be consistent across most themes.

-- AndrewJohnston - 30 May 2006

• Has anybody ever looked into connecting the remote device to the server via iSCSI stack? I just stubled over this protocol some time ago, but I think, since all usb-storage-devices show up as scsi devices anyway, that might be an easy way to connect them to the server.
  • How do you propose to handle device removal? As far as I know, iSCSI doesn't particularily like the device to disappear suddenly, as would be the case with a usb device unplug. Certainly, if you'd like to invest some time getting it to work, we'd be more than happy to look at it. -- ScottBalneaves - 5 Sept 2006

• This page is awfully long and largely irrelevant for those having just one distro and not a whole bunch at once; maybe it's worth splitting up distro's deficiencies and ugly #make install's into LTSP-42-LocalDev-$DISTRO pages which would be largely cut-n-paste walkthrough?

• Still fighting with cdrom support -- floppy and usbflash work just fine, but udev seems not to recognize cdrom (/dev/hdc, mounts by hand locally just fine too). LTSP is supposedly 4.2U4 but /etc/version has "VERSION=4.2 update 3" (single root, no mixups here).

-- MichaelShigorin - 18 Jan 2007

• I have a problem with floppies that happens when a floppy disk is not properly mounted and any user tries do write on it. As the system shows him a icon of a mounted device, the user "writes" but the files that should be written at the disk remain at the folder in the filesystem, due to it, he thinks that he has the files on the disk and they are not there, and worst, as the files were copied to a folder it's impossible for the system to umount it once there are some files in the specified folder.

-- NielsenGoncalves - 25 Jul 2007