Lessdisks is a "diskless" terminal "distribution" almost entirely based on
Debian GNU/Linux.  While it'll theoretically work on any linux or other unix
look-alike, that hasn't really been tested.

$Id: installation,v 1.8 2004/08/13 07:17:41 vagrant Exp $

This document assumes you have a working debian installation.  it has been
tested with both woody (3.0) and sarge(testing)


Configuring and Updated Apt

this step may not be necessary if using the official debian packages(currently
only in sarge/testing and sid/unstable).

To install lessdisks, include the lessdisks archive in your 
/etc/apt/sources.list:

deb http://lessdisks.net/debian/current /

then run:

apt-get update


Installing Lessdisks Package

apt-get install lessdisks

this will probably ask you the following questions, depending on your debconf
priority setting (if set to "low", you will get more questions, if set to
"high" it will not ask most of the questions):

terminal architecture (i386, powerpc, alpha, etc.. the architecture of the
  terminal must match the server currently)

debian distribution (woody, sarge, sid)

debconf frontend (the configuration frontend used during the lessdisks
  installation)

location of the lessdisks archive (lessdisks.net/debian/current /)

location of a standard debian archive (http.us.debian.org/debian)

http proxy information, used during install (http://localhost:3128)

lessdisks admins (users to manage lessdisks terminals)

use initrd (true/fasle, to use a standard debian kernel, you may require an
  initrd setup)

kernel packages (lessdisks-kernel, kernel-image-netbootable, kernels to
  install)

generate NBI image (true/false, generate network bootable kernel images for use
  etherboot)

  mknbi options (--ip=dhcp, options to pass to mknbi when generating a NBI
  image)

packages for terminal root (packages which will be installed into the root
  filesystem of the terminals, such as lessdisks-xterminal)

export type (a small web server used for exporting configuration files when
  configuring a terminal)



Running the Install Script

lessdisks-install

This will bring up a menu of options.  

1 Begin Install
2 Display Values
3 Simple Configuration
4 Advanced Configuration
5 Exit

"Display Values"

displays the values of the configuration file, /etc/lessdisks-install.conf

"Simple Configuration"

dpkg-reconfigure --priority=medium lessdisks

reconfigures the package, and also re-writes(and re-reads) the configuration
file, /etc/lessdisks-install.conf.  it will then re-display the menu.

"Advanced Configuration"

dpkg-reconfigure --priority=low lessdisks

the same as above, but will ask you every question lessdisks has to offer.


The Install Process

a base debian installation gets put into /var/lib/lessdisks, using debootstrap.
while this is happening, a progress bar will indicate approximately how far
along the install is.

once the progress bar stops, a number of other packages will get downloaded and
installed, and a lot of information may scroll by as it prepares the terminal's
root filesystem.

eventually, you should see: "lessdisks install finished!"


Configuring NFS

now you'll need to edit /etc/exports, and configure your NFS server, add a line:

/var/lib/lessdisks 192.168.1.0/255.255.255.0(ro,no_root_squash,async)

you can also take a look at /usr/share/doc/lessdisks/examples/exports.  you
will need to configure this line appropriate to your network, i.e. change
192.168.1.0 to some other ip address range.

once you have configured /etc/exports, restart NFS:

/etc/init.d/nfs-common restart
/etc/init.d/nfs-kernel-server restart


Configuring DHCP

you will probably need a DHCP server on the network.

in /etc/dhcpd.conf, you will probably need at least the following lines:

subnet 192.168.1.0 netmask 255.255.255.0 {
  range dynamic-bootp 192.168.1.200 192.168.1.254;
  default-lease-time 600;
  max-lease-time 7200;
  option subnet-mask 255.255.255.0;
  # next-server is only needed if the dhcp and nfs servers are different machines
  #next-server 192.168.1.9;
  filename "/var/lib/lessdisks/boot/vmlinuz.nb";
  option root-path "/var/lib/lessdisks/";
}

if dhcpd is running on a different machine from your NFS server, be sure to use
the next-server option to point to the NFS server.

modify them to suit your particular network, put them in /etc
and restart the services...

/etc/init.d/dhcp restart


PXE Support

lessdisks can work with pxe.  it requires dhcp3-server and a tftp daemon.

see pxe.txt from the lessdisks-doc package for more information.


More Defaults

look in /usr/share/doc/lessdisks/examples for example files for /etc/dhcpd.conf
and /etc/exports (for NFS).


X Windows

X Display Managers

there are numerous X display managers.  some of the most common ones are xdm, kdm & gdm, which all use the xdmcp protocol.  there is also a display manager called sdm, which uses ssh and X11Forwarding.


XDM and other XDMCP

apt-get install xdm

you will need to comment out or modify lines in /etc/X11/xdm/Xservers, so that
there are no entries with "-nolisten tcp" in them.

edit /etc/X11/xdm/Xaccess, and uncomment or create lines which will allow
terminals to connect to xdm, such as:

*     #any host can get a login window

you may need to edit /etc/X11/xdm/xdm-config and comment out (using "!") the following line:

DisplayManager.requestPort:    0

this process will be similar for kdm and gdm, though the exact files may be
different.


SDM

as an alternative to xdm or other xdmcp-based display managers, sdm uses ssh
X11Forwarding.  it is a little more resource-intensive on both the server and
terminal, but more secure, as most traffic between the terminal and server is
encrypted.

(note: sdm may not be available with a standard debian distribution- you can
get it from the lessdisks archive above.)

apt-get install sdm

edit /etc/ssh/sshd_config, and set:

X11Forwarding yes

/etc/init.d/ssh restart

you'll also need to install the sdm-terminal package as well:

lessdisks-aptget install sdm-terminal


Other X Programs

you will probably need a few other programs to make a useful xterminal, such as a x-window-manager and x-terminal-emulator.

x-terminal-emulators: xterm, aterm, rxvt
x-window-managers: icewm, blackbox, xfce, afterstep, kde, gnome, etc...
("apt-cache search x-terminal-emulator x-window-manager" for more options)

for example:

apt-get install aterm icewm


X Configuration with Swiftx

(note: x_config_ltsp comes with lessdisks-xterminal, and is now the default, it
can be run simply by calling x_config_ltsp)

swiftx is a simple X configuration program written in python.

lessdisks-aptget install swiftx

edit /var/lib/lessdisks/etc/swiftx/swiftx.conf:

x_config_dir='/var/state/lessdisks/etc/'

edit /var/lib/lessdisks/etc/swiftx/XF86Config-*.template:

add a line for the appropriate FontPath, such as:

FontPath "tcp/xapp:7100"

on a booted terminal:

swiftx

it should attempt to configure and test the X server...


X Fonts

if you plan to run X on the lessdisks terminals, you will need to install X
fonts.

you can install XFS and X fonts on the server:

apt-get install xfs xfonts-base xfonts-100dpi xfonts-75dpi xfonts-scalable

you will need to comment out the following line from /etc/X11/fs/config:

no-listen=tcp

/etc/init.d/xfs restart

or install the fonts into the terminal's root filesystems:

lessdisks-aptget install xfonts-base xfonts-100dpi xfonts-75dpi xfonts-scalable


Configuring a Terminal

if you were not asked anything about a root password, set it now:

lessdisks-chroot passwd

boot a terminal.  you should get to "default login", or X should come up:

if X was automatically configured, log into the server via X as a user in the
lessdisks group(the lessdisks_admins question above).

then run:

/usr/sbin/lessdisks-setup

if X was not configured, log into the terminal as root. run:
(this requires ssh, to install ssh: lessdisks-aptget install ssh)

lessdisks-terminal-setup

it will ask you which user you should log in as, choose the one you added to
the lessdisks group.  this just basically runs lessdisks-setup via ssh.

lessdisks-setup will ask you to name the terminal, ask what runlevel you'd like
to operate in, and possibly ask if you want to configure it as an X terminal.


More Tips and Tricks

Download Etherboot Floppy

http://rom-o-matic.org

download an image a specific network card, and configure with
DOWNLOAD_PROTO_NFS checked.

if using Debian's Sarge release, you can also get the etherboot package.
you will need to configure a tftp daemon to use the default etherboot images.

apt-get install etherboot


to make a floppy, look in /usr/share/etherboot to find the appropriate image
for your network card(or use the downloaded image from rom-o-matic), for
example:

dd if=/usr/share/etherboot/tulip.dsk of=/dev/fd0 bs=1k


Enabling Remote Syslogging

the server can be configured to recieve syslog messages from the terminals.

edit /etc/init.d/sysklogd:

SYSLOGD="-r"

/etc/init.d/sysklogd restart

add the following line to /var/lib/lessdisks/etc/syslog.conf:

*.* @disk

then, when a terminal boots, log messages should appear in the server's
/var/log/syslog, too.


For more suggestions, see the "tips" file!


Other Related Documentation

http://tldp.org/HOWTO/XDMCP-HOWTO
http://tldp.org/HOWTO/Remote-X-Apps
http://tldp.org/HOWTO/Xterminals


Other Diskless Terminal Implementations

http://plume.sourceforge.net
http://ltsp.org

TODO recommend installing dialog & xdialog
