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 (for i386 netbooting)

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

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


netbooting an alpha

To create a netbootable image, use netabootwrap to combine your kernel and
initrd, as follows:

netabootwrap -k vmlinuz-2.4.27-2-generic -i initrd.img-2.4.27-2-generic \
	-a "root=/dev/nfs nfsroot=/srv/nfs/alpha ip=dhcp nfs_opts=rw,async,nolock" \
	-r boot.img

Serve the boot.img via tftp.


netbooting an hppa

The debian hppa kernel is actually built with nfs root support, so you may
not need to install initrd-netboot-tools, unless the driver for your network
card is not built into the kernel. 

To create a netbootable image, use palo to combine your kernel and
initrd, as follows:

palo -f /dev/null -k vmlinux -b /usr/share/palo/iplboot \
	-c "0/linux root=/dev/nfs nfsroot=/srv/nfs/hppa ip=dhcp nfs_opts=rw,async,nolock" \
	-s boot.img

Serve the boot.img via tftp.


netbooting an ia64

Copy /usr/lib/elilo/elilo.efi from the ia64's chroot into your tftp boot
directory and configure your dhcp server to use it as the filename for the ia64
machine(s). In the same directory as the elilo.efi in your tftp server, copy in
a vmlimuz and initrd.gz from the ia64 and create an elilo.conf as follows:

default=Linux

image=vmlinuz
    label=Linux
    root=/dev/nfs
    initrd=initrd.img
    append="console=tty0 console=ttyS0,9600 root=/dev/nfs nfsroot=/srv/nfs/ia64 ip=dhcp"


netbooting a cobalt raq (mipsel)

To netboot a coalt raq, you will need to set up an /nfsroot directory
on your nfs server that holds the chroot. The raq firmware has this
directory hardcoded into it, and uses nfs to retreive the colo boot loader.
Create a /nfsroot/default.colo file like this:

#:CoLo:#
-serial on
nfs {dhcp-next-server} {dhcp-root-path} boot/vmlinux boot/initrd.gz
execute rd_start=0x{initrd-start} rd_size=0x{initrd-size} console=ttyS0,{console-speed} net:bootp root=/dev/nfs nfsroot=/nfsroot ip=dhcp nfs_opts=rw,async,nolock

Make sure that colo is installed in the chroot. Debian's mipsel kernels
do not support nfs root on their own, so you must use initrd-netboot-tools.
The mipsel kernels also do not support the cramfs filesystem that mkinitrd
uses by default. This setting in mkinitrd.conf will make it create an ext2
initrd instead:

MKIMAGE='genext2fs -b 7192 -d %s %s'

The maxiumum initrd size is 8 mb currently. If your initrd comes out larger
see the tips file. You will also need to set do_initrd = ys in
kernel-img.conf since mipsel does not use an initrd by default.


netbooting a sparc

You will probably need to edit initrd-netboot.conf to add the appropriate
kernel module for your sun's network card. For example:

nic_modules="sunhme"

Use eltoaout and piggyback64 from the sparc-utils package to generate a boot
image, as follows:

gzip -cd vmlinuz-2.4.27-2-sparc64 > boot.img.tmp
elftoaout -o boot.img boot.img.tmp
piggyback64 boot.img System.map-2.4.27-2-sparc64 initrd.img-2.4.27-2-sparc64

(Use piggyback on 32 bit sparcs.)

Serve the boot.img via tftp.


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