
                        LTSP - ThinkNIC HOWTO
                               Version 0.1
                                6/24/2001

                John D. Robertson, RRCI  (john@rrci.com)


                                Copyright

"LTSP - ThinkNIC HOWTO" and its accompanying software distribution is Copyright
2001 John D. Robertson, and is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by the
Free Software Foundation, Inc., 675 Mass Ave, Cambridge MA 02139, USA; either
version 2 of the License, or (at your option) any later version.


                                INTRODUCTION

This document supplies a cookbook recipe for integrating the ThinkNIC computer
(http://www.thinknic.com) into the LTSP (http://www.ltsp.org) environment as a
client. The ThinkNIC hardware package is small and quiet, and possesses the
necessary capabilities to be an LTSP client computer. At the time of writing the
ThinkNIC (http://www.thinknic.com) can be purchased for $200 + $24 shipping
(USD), and comes with a keyboard, mouse, mouse pad, CD-ROM drive, and pair of
speakers. All you need to add is a monitor.

                                OVERVIEW

Information in this document is presented in the order a practitioner would use
to get a prototype ThinkNIC client working with LTSP. For the sake of avoiding
redundancy it is assumed that the reader has successfully installed the LTSP,
and has at least one client computer working. Just about any computer possessing
an ethernet card supported by etherboot (see http://www.rom-o-matic.com) and a
floppy disk drive may be used as an LTSP client without disturbing the contents
of any installed hard disks. I suggest that novices start with a client computer
supported by the etherboot package because it is simpler to get working with
LTSP.

This document presents instructions to use the PXE booting feature of the
ThinkNIC to obtain the Linux kernel from a network server. Another approach not
addressed in this document is to create a bootable CD-ROM disk with a root-nfs
kernel, etc.

Also, the TFTP pathnames I present assume that you are running the TFTP server
in secure mode (-s option) such that the "/tftpboot/" prefix is disallowed.


                                DHCP

You will need to provide a host entry for the ThinkNIC in your "/etc/dhcpd.conf"
file which includes a "filename" entry for the pxelinux boot file, and some
extra PXE voodoo. It is NOT necessary to run a PXE server. Here is an example
entry for the ThinkNIC:

        host ws100 {
                hardware ethernet       00:E0:06:E7:DE:B5;
                fixed-address           192.168.0.100;
                filename "pxelinux.0";
                option dhcp-class-identifier "PXEClient";
# NOTE: The following line is broken only for the sake of readability!!
#       If you use this example, put it back together in the dhcpd.conf file.
                option vendor-encapsulated-options 09:0f:80:00:0c:4e:65:74\
                :77:6f:72:6b:20:62:6f:6f:74:0a:07:00:50:72:6f:6d:70:74:06:01\
                :02:08:03:80:00:00:47:04:80:00:00:00:ff;
        }

I have supplied a complete example "dhcpd.conf" file in the accompanying
software distribution. Don't forget to restart dhcpd after you add the host
entry to your "/etc/dhcpd.conf" file.


                                CONFIGURE BIOS

As shipped from the factory the ThinkNIC's BIOS is configured to boot from the
CD-ROM drive. For our purposes we will reconfigure the BIOS to use PXE booting,
and maximize the functionality of the built-in graphics hardware.

To configure the BIOS turn on the power and, as soon as you see the white boot
screen, press the "Delete" key a few times. Shortly you should be presented
with the blue BIOS configuration screen. Modify the following settings like so:

BIOS FEATURES SETUP / Boot From LAN First         --> Enabled
CHIPSET FEATURES SETUP / VGA Shared Memory Size   --> 4MB

To reduce boot time you may wish to disable the IDE controller as well. Exit the
BIOS configuration utility and save your changes.

Now connect the ThinkNIC to your LTSP network. You should be able to verify
the PXE booting function by rebooting the ThinkNIC and watching for successful
DHCP communication with your dhcp server.


                                LINUX KERNEL

I have provided a monolithic Linux 2.4.5 kernel with the accompanying software
distribution, as well as the kernel configuration file used to generate the
kernel. I have also successfully used a Linux 2.2.19 kernel, but the 2.4.5
kernel seems to perform better in the ThinkNIC. As an additional benefit,
the 2.4.5 kernel supports APM CPU idle calls to conserve electrical energy and
reduce heat generation. Install the kernel like so:

        cp vmlinuz.thinknic /tftpboot/

You may need to compile your own kernel since the one I have provided does not
provide IDE or USB support. Note that you must NOT use the "mknbi-linux" command
to modify a kernel used for PXE booting.


                                LTS.CONF

You may wish to place an entry in the "/tftpboot/lts/ltsroot/etc/lts.conf"
file for the ThinkNIC. I have supplied an example "lts.conf" file in the
accompanying software package.


                                PXELINUX

In order to use the PXE booting feature of the ThinkNIC it is necessary to
install the "pxelinux", part of the "syslinux" GPL'd software distribution
(http://www.kernel.org/pub/linux/utils/boot/syslinux/) on the server. I have
provided the necessary components in precompiled form as a part of the
accompanying software distribution. Install the components like so:

        cp -R pxelinux.0 pxelinux.cfg /tftpboot/

Take a look at the configuration files in the "/tftpboot/pxelinux.cfg/"
directory. You may need to modify them for your LTSP setup.

NOTE: pxelinux uses a novel approach to get the necessary kernel boot
parameters from a config file in the "/tftpboot/pxelinux.cfg/" directory by
directing the client to use TFTP to transfer a file (whose name is based on a
hexadecimal representation of the IP address of the client) from the server. If
this fails, pxelinux tries other file names by successively dropping the
rightmost character of the original file name. As a fail safe measure the file
name "default" is tried lastly. Unfortunately on the RH7.1 system I used for
development, relying on the fail safe file name "default" caused xinetd to hang
and stop providing TFTP service before the file could be transferred. To regain
TFTP service I had to stop xinetd, and then start it (a restart did not do the
trick). To work around the problem I had to provide a config file whose name was
based on a hexadecimal representation of the IP address of the client to reduce
the number of TFTP tries that pxelinux used to find the config file. This had me
stumped for a while - BEWARE!!!

Now you should be able to boot the ThinkNIC and use it as a CHAR type terminal
for LTSP.


                                XWINDOWS

The quality of the video signal generated by the ThinkNIC is substandard, and
will appear slightly out of focus, but usable, on a good quality 17" CRT
monitor. Using a flat panel display seems to provide a crisper image.

At the time of writing LTSP by default provides support for XFree86
version 3.3.x. The ThinkNIC will work with the supplied XF86_SVGA server. The
ThinkNIC's graphics hardware can support up to 1024x768 resolution at 24 bpp. I
understand that attempting higher resolutions can damage the hardware. You have
been warned. Let me know if it works ;^).

If you wish to significantly improve the graphics performance of the
ThinkNIC, then install XFree86 version 4.x.x. Version 4.x.x, among other things,
provides support for OpenGL based applications (albeit somewhat slow). I found
Byron Poland's howto (http://www.ltsp.org/documentation/nvidia.txt) to be a
straightforward set of instructions for doing so. Disregard the section of
Byron's howto concerning the installation of the proprietary nVidia drivers.

The accompanying software distribution includes an example XF86Config file for
XFree86 version 4.x.x, "XF86Config-thinknic".

Incidentally, using the fonts and xfs provided in XFree86 v4.1.0 yields
perfectly rendered fonts for viewing Micro$oft web sites.


                                SOUND

If you desire sound support then you will need to install Boris Reisig's
sound contribution
(http://prdownloads.sourceforge.net/ltsp/ltspsound-0.1a.tar.gz). You can
disregard the part about loading modules since the kernel I have provided has
sound support built in. Note that currently this only provides sound support
for applications that use the OSS sound API. Fortunately XMMS can be configured
to use OSS :-)


                                CONCLUSION

The ThinkNIC computer can be exploited as a cost effective, factory ready LTSP
terminal with minimal software configuration. Large deployments of LTSP should
consider the ThinkNIC when choosing the terminal hardware. Schools are likely to
be interested in the school donation program managed by the ThinkNIC company
(see http://www.thinknic.com).


                                MISCELLANEOUS

It is my sincere hope that all government institutions will take notice of LTSP
and this howto to save tax dollars and conserve electrical energy.

Please direct any questions about this document to John D.
Robertson (john@rrci.com).
