Note for current versions:

After creating a diskless-image, the timezone must be manually set
using tzconfig, eg

chroot <imagedir> /usr/sbin/tzconfig

should do it.

=============================================================================
1. Introduction

This package comes with two programs, diskless-newimage, and
diskless_newhost to simplify setting up and maintaining diskless
clients.

It requires base2_1.tgz from the Debian boot disks, and one of
the diskless-image packages. As of writing this, the only
diskless-image package that has been tested in diskless-image-simple
(diskless-image-simple_0.3.0_all.deb).

The clients are setup to mount / as Read/Only from a shared point and
mount /etc as Read/Write before executing /sbin/init.

Please see /usr/doc/diskless/TODO for a list of known bugs.

-----------------------------------------------------------------------------
1.1 Conventions used in this documentation:

$VAR        /var/lib/diskless
$USR        /usr/lib/diskless
<imagedir>  is the where the imagedir (aka master image) is to be placed.
<hostsdir>  is the data specific to all hosts is placed.
<ip>        is the IP address of the host for the current operation.
<hostdir>   is the data specific to an individual host is placed.
	    this will be <hostsdir>/<ip>.

Note: if <imagedir> is exported read-write to the remote computer, it
will boot as the master system. Please ensure you have read-only export
permission if you don't want people altering it!

-----------------------------------------------------------------------------
1.2 Please support this software! Please tell me if you like it, hate it,
or even use it. I can be contacted at one of the following
addresses:

Brian May <bam@debian.org>
Brian May <bam@snoopy.apana.org.au>

=============================================================================
2. Getting Started

Steps to get going:
1. Build the kernel.
2. Configure BOOTP (I use dhcpd) and perhaps tftp.
3. Setup the group.
4. Setup the hosts within the group.
5. Setting up /etc/exports.
6. Boot remote NFS system (not described here).
7. Send me a details of any problems you encounter, to
bam@snoopy.apana.org.au.

Steps 3 and 4 should be repeated (in that order) whenever the
configuration on the masterdir has changed.

All steps should be conducted on the NFS-server (or another computer
that has access to the correct directories), unless stated otherwise.
-----------------------------------------------------------------------------
2.1 Building the kernel

The kernel should be configured for NFS-ROOT. I think the most important
options are:

CONFIG_NET=y
CONFIG_PNP=y
CONFIG_IP_PNP=y
CONFIG_IP_PNP_BOOTP=y
CONFIG_NFS_FS=y
CONFIG_ROOT_NFS=y

In addition, the desired network cards MUST be compiled into the kernel
(ie a module will not work).

Note: following section needs to be rewritten. In particular,
there is no need to install the kernel package on the nfs server
any more, instead it must be installed on the master system
(so modules can be found). See further below for details. However,
the kernel needs to be available somehow for boot (eg via tftpboot),
so some of the following still is applicable.

The kernel for the diskless systems should be built with the --flavour
nfs option of make-kpgkg, eg:

/usr/sbin/make-kpkg --flavour nfs --rootcmd fakeroot buildpackage

The makefile should not be patched as documented in
/usr/doc/kernel-package/Flavours.gz, rather the broken modules directory
name is auto-magically corrected by this package. This allows nfs kernel
images and non-nfs kernel images to reside on the master system at the
same time. If at same time this problem is fixed and future kernel
versions fully support flavours, then the renaming of the directories
will have to be removed from $VAR/template/group/rules-master.

The resultant package should be installed onto the root file-system and
in a place where it can be loaded by the remote system.

For example, I recommend (for kernel version 2.1.29):

dpkg -i kernel-image-2.1.129-nfs_1.00_i386.deb
mknbi-linux /boot/vmlinuz-2.1.129-nfs $VAR/boot/linux_2.1.129 -d rom

This requires the debian package netboot to be installed.

-----------------------------------------------------------------------------
2.2 Configure BOOTP and perhaps tftp

(this assumes you dhcpd installed; if you use bootp then you need
to look up the appropriate documentation).

I use:

shared-network mynet {

subnet 192.168.87.0 netmask 255.255.255.0 {
  option domain-name-servers 192.168.87.129;
  option domain-name "chocbit.org.au";
  option routers 192.168.87.129;
  option subnet-mask 255.255.255.0;
  option broadcast-address 192.168.87.255;
  default-lease-time 3600;
  max-lease-time 7200;
}

[...]
}

host louie {
        hardware ethernet 00:40:33:29:53:AB; # PN16CT Card ?
        fixed-address 192.168.87.131;
        server-name "snoopy";
        filename "linux_2.2.1";
}
[...]

Some of these details aren't used by Linux, but are used when the
computer is booted in Win98.

I have heard that there is another option, "option root-path" that
sets the default NFS-root path. I haven't been able to get it to
work though.

        option root-path                "/var/lib/diskless/<group>/root";

Replace <group> with the group of this host. This should avoid
the need for /tftpboot.

I recommend tftpd configured in /etc/inetd.conf with:

tftp            dgram   udp     wait    nobody  /usr/sbin/tcpd  /usr/sbin/in.tftpd /var/lib/diskless/boot

-----------------------------------------------------------------------------
2.3 diskless-newimage: Create/maintain new image/master directory

Syntax:

  diskless-newimage [<group> [option=<value>] ... ] 


Options:

  If any required information is omitted or invalid or the command
line, it will be prompted for. If the option "defaults=yes" is
supplied, default values will be used where possible. Valid options
are:

All of these values are checked to ensure that they are valid. Help may
be obtained by pushed ? at any prompt.

Description:

  This creates a new image using base2_1.tgz and diskless-image-*.deb in
the current directory. If these files cannot be found, then the process
will abort. Similarly, if more then one match for diskless-image*.deb
can be found the process will abort.

Some tasks are left incomplete:
1. Install kernel modules. It is easier if you can leave this until
later, but if you must do it now:

dpkg --root <imagedir> --install kernel-image-*.deb

WARNING: Do not tell the installation script to install lilo, as
it may replace your lilo setup on the NFS server.

2. To complete these tasks, export the image directory as read-write.
A sample entry can be found in /etc/diskless-image/exports on the
NFS-root image. Replace IP address with the IP address of the master
system.

3. Boot from it. If all goes well, you shouldn't see any fatal error
messages when the image boots, and you should get to the login prompt.
Currently I get errors that /etc/modules doesn't exist and the
pcmcia module could not be found. These can be safely ignored
(unless you really do want pcmcia support).

The following steps should be conducted on the newly booted system:

4. Log in as root. No password is required.

5. You may be asked to configure the keyboard. For me, this
produced the error that /etc/kbd/default.map could not be found.
If this occurs, push any key to continue.

6. Be careful in adding a standard user account and/or shadow
passwords if you use NIS. These options may not be desirable.

7. I recommend:
dpkg --purge lilo		( prevent potentially dangerous mistakes)
dpkg --purge pcmcia-cs			(unless you have pcmcia modules)
dpkg --install apt-*.deb	 	(slink version broken on NFS)
dpkg --install kernel-image-*.deb	 (if not already done)
dpkg --install ssmtpd_*.deb
dpkg --install anacron_*.deb

(Of course these packages must have been downloaded. You may be able to
use apt, but I found the version in slink broken. I had to move files
manually from the archives/partial directory to the archives directory
after apt had downloaded them. This problem has been fixed in the latest
potato version.)

8. If you installed the kernel-image modules, then please make sure
that the dependency information is up-to-date. This might occur
automatically, I am not yet sure.

9. Suggested X configuration. Put next line inside /etc/inittab:
7:23:respawn:/etc/init.d/X vt7 -query snoopy

This will automatically restart X on starup and when it is exited, and
contact the xdm server on snoopy (change to more appropriate name). It
will not start X if a valid XF86Config file doesn't exist. All output
will go to /var/log/X.log.

10. Consider changing the export entry to read-only
so that unauthorized users cannot change the setup. You
don't normally want to boot up in master mode anyway, unless
installing/removing packages.

If image dir already exists, diskless-newimage will allow you to
change the settings without having to boot from the image and
execute configure-diskless-image manually.

Note: If you want to change any config files under /etc, check to
ensure they aren't mentioned in /etc/diskless-image/config.sh .
config.sh is executed every time the package is is reconfigured (with
dpkg-reconfigure) or reinstalled, and will re-create the listed
configuration files. Updating the rules in /etc/diskless-image/config.sh
is prefered other updating the individual files. This file may be
replaced in the future with an alternative mechanism, depending on what
feed back I get.

-----------------------------------------------------------------------------
2.4 diskless-newhost: create/maintain new host

Syntax:

  diskless-newhost [<imagedir> [<ip1> [option=<value>] ... 
                             <ip2> [option=<value>] ...
			      ...      ...
			     <ipn> [option=<value>] ... ] ]

Note:

  If you want to be able to boot Linux without any command line
parameters or extra DHCPD parameters, /tftpboot must exist beforehand.
Create it with mkdir /tftpboot as root. Otherwise symlinks will not be
created, and you will have to manually specify the root NFS directory
before booting Linux.

  This program is very verbose while copying files.

Options:

  If any required information is omitted or invalid or the command
line, it will be prompted for. If the option "defaults=yes" is supplied,
default values will be used where possible. Valid options are host=...,
This will default to the DNS host home derived from the IP address if
possible. All values are checked to ensure that they are valid. Help may
be obtained by pushed ? at any prompt.


Description:

  This creates a new hosts belonging the imagedir or updates an existing
host. It prompts for information not supplied on the command line, and
can operate on multiple clients at the same time to increase efficiency.
Config information is saved in <hostdir>/etc/diskless-host. If any files
have been changed, the user will be prompted (see section 5).

  This program should be run whenever files under <imagedir> may have
changed, in order to make the <hostdir>s consistent.

Source:

It gets the files to convert from (in the following order, first takes
priority):

   directory tree                   rules_file
-----------------------------------------------------------------------------
1. <imagedir>/$USR/template        <imagedir>/$USR/rules-template
2. <imagedir>                      <imagedir>/$USR/rules-host

In addition, files under <imagedir>/$USR/template/etc will be processed
by m4, in order to add host specific information. It is recommended that
you do not change these files manually. If this is required, then please
tell me and I will add provision to do this under <imagedir>/$VAR.


Destination:

1. It creates files under <hostdir> (ie <hostsdir>/<ip>).

2. It creates sample entries for /etc/exports in
<hostdir>/etc/diskless-host/exports

3. It creates a symbolic link from /tftpboot/<IP> to $VAR/<group>/root
(the root file-system). Any existing symlink is deleted. This step is
bypassed if /tftpboot doesn't exist.

-----------------------------------------------------------------------------
2.5 Configure /etc/exports

Sample entries for /etc/exports for each host have been created in
$VAR/<group>/<ip>/exports, however, these will have to be somehow merged
together. I currently use something similar to:

--- start /etc/exports
/var/lib/diskless/chocbit/192.168.87.130 192.168.87.130(rw no_root_squash)
/var/lib/diskless/chocbit/192.168.87.133 192.168.87.133(rw no_root_squash)
/var/lib/diskless/chocbit/192.168.87.137 192.168.87.137(rw no_root_squash)
/home 192.168.87.0/255.255.255.0(rw no_root_squash)

/var/lib/diskless/chocbit/root 192.168.87.0/255.255.255.0(ro no_root_squash)
/usr 192.168.87.0/255.255.255.0(ro no_root_squash)
--- end /etc/exports

nfsd must be restarted after editing /etc/exports. I use (as root):
/etc/init.d/netstd_nfs stop
/etc/init.d/netstd_nfs start

This may also work:
/etc/init.d/netstd_nfs reload

=============================================================================
3. Format of rules files

Every rules file is preprocessed with M4, see
$VAR/template/group/rules-master for example. M4 is documented in
section 4.

Every file/directory/symlink/device in the source directory is searched
top to bottom in the rules file associated with the source directory.
The first matching entry is used and the rest are ignored.

--- [type] pattern@package
|||   |      |       |- optional - match entire list of files in Debian package
|||   |      |
|||   |    =string - match constant string
|||   |	   other   - match perl regular expression.
|||   |
|||   |- optional - [dir] only match directories
|||               - [symlink] only match symlinks
|||               - [device] only match devices
|||               - [file] only match normal files
|||
|||-C allow converting this file using M4 filter
||
||- c allow copying of this file
||
|-- d if matching file is a directory, then descend into it. (Note:
      if directory doesn't have c set, then either dir must be
      found in another source dir or destination must already
      exist).

If both a pattern and a package are specified, then the file must
match both.

Also supported are (these are parsed *before* the rules above):
@rename =<src>=<dst>=    Use with extreme caution, renaming individual
                         files is OK, using substitution is OK, however
			 may cause problems.
@ignore <src>            Source file is not copied, even if it exists in
                         a source directory with higher priority.

Potential problems with rename:
@rename =(.*)=/etc$1=    Should put all files from this source under
                         the etc dir, but will complain if this dir
			 doesn't exist, or doesn't exist in time.
@rename =(.*)=$1.old=    This is pure evil. DO NOT DO IT! For example,
                         consider:

			   /      ===>  /.old
			   /a     ===>  /a.old
			   /a/b   ===>  /a/b.old
			   /a/b/c ===>  /a/b/c.old

			 This is probably not intended, and will fail
			 if the /a/b directory doesn't already exist.

Do not use quotes in from expression, is the result is determined
through "eval", and quotes will mess this up. There may be other
things to watch out for.

=============================================================================
4. M4 file conversion

M4 is a file parsing and conversion program that should work on text
files of any format (eg shell scripts, config files, LaTeX, C, C++, etc)

For conversion of template files, it uses the config file
<imagedir>/etc/diskless-image/config.m4
<hostdir>/etc/diskless-host/config.m4

(settings in the <ip> directory take priority, put normally config
options wont overlap.)

Data is read from config file in format
define(<[option]>,<[value]>). The config.m4 files should correspond
to the config file in the same directory.

For more information on M4, please see the M4 info page.

=============================================================================
5. Default file copying rules:

When a file is copied, its details will be stored in .config.new,
and .config.new is renamed to .config.all at the end of successful
completion. This use of 2 files is so installed files can still be
tracked even if installation fails.

The status information for each file contains two sets of the following
fields, separated by '=':

1 - 12: output from lstat($file);
13: extra information depending on file type, eg MD5sum for normal files.
14: file type, as I couldn't work out how to extract it from fields 1 to 12.

The first set contains information about the source the last time the
file was installed. This is used to determine if the destination file
has changed. The second set contains information about the source
file the last time the installation was run. This is used to determine
if the source file has changed. If the first set is a '*' then
this file was never formally installed. If the second set is a '*', then it
is taken to be the same as the first set. 

The reason two sets of data are required (and not just one like
for dpkg conf files) is that the time and date of the files
is taken into consideration, and it is important that the reference
date for the destination remains the same unless it is updated.

Consider this worse case example: The source file and destination
file are modified to have the same date and time (ie coincidence).
The user runs the installation program but chooses not to
update the file. The installation can:
- don't update the reference. This means on the next install both
  files have a status of "newer", and you will always be prompted
  if you want to replace the destination file, increasing the risk
  of saying yes by mistake.
- update the reference to the new date and time of the source. This
  might look OK, but it now both files have a status of "same". This
  means if the source file is changed, it will overwrite the
  destination, no questions asked.
- save two references, one is the reference to the source when it was
  last installed, and one is the reference to the source now. This
  is a combination of the above two methods, and is what my program
  does. This means the source file will get a status of "same", but
  the destination file will continue to get a status of "newer".

As from autoinstall.pm::doit

         | <---------------- SOURCE FILE -----------------------> |
DST FILE | deleted | created | same | newer(1)| older(1)| changed |
---------+---------+---------+------+---------+---------+---------+
deleted  | ASK     | REPLACE | NOP  | ASK     | ASK     | ASK     | 
created  | ------- | ASK     | ---  | -----   | ------  | ------- |
same     | REPLACE | ------- | NOP  | REPLACE | REPLACE | REPLACE |
newer(1) | ASK     | ------- | NOP  | ASK     | ASK     | ASK     |
older(1) | ASK     | ------- | NOP  | ASK     | ASK     | ASK     |
changed  | ASK     | ------- | NOP  | ASK     | ASK     | ASK     |
-------------------------------------------------------------------

Note:
(1) As of version 0.1.8 the date/time comparison has been disabled,
since it was no longer required and broke when the source is controlled
by CVS.

SOURCE FILE
-----------
deleted - means the file is listed in .config.all but not there
created - means the source file exists but not listed in .config.all
          (as it is not listed, there is nothing to compare it with)
same - source file not modified since last copied
newer - source file is newer then reference
older - source file is older then reference
changed - source file has been determined different then reference
	by some other check (eg file size).

DESTINATION FILE
----------------
deleted - means the file is not there
created - means the destination file exists but not listed in .config.all
          (as it is not listed, there is nothing to compare it with)
same - destination file not modified since last copied
newer - destination file is newer then reference
older - destination file is older then reference
changed - destination file has been determined different then reference
	by some other check (eg file size).

OPTIONS
-------
ASK - ask user what to do. If the old file is required, the new one
	will be renamed to end with .ai-new; if the new file is
	required, the old file will be renamed to end in .ai-old;
	in any case the user will only be asked ONCE for each file.
REPLACE - Replace destination file, if exists
NOP - don't do anything

=============================================================================
6. Potential bugs:

Look in /usr/doc/diskless/TODO for a list of known problems.

Any uninitialized variable warnings should be treated as serious errors.
Please report them to me, and give as many details as possible.

If browsing the source code, please look out for a routine
which returns an error value (almost always 0 or undef), but does not
set $error. This is a bug. Almost all routines should return a value.

Furthermore, there may be instances where I have said

open(...);
if (!$rc)
{
...
}

where I should have said "$rc = open(...);".

$error, $$error, and \$error might be confused at places.

Please send me details of any bugs using the debian "bug" program
(preferred) or send them to me at my E-Mail address listed in section
1.3.

Feel free to fix any problems, but please email me first so we don't
clash.

The following template files in in diskless-image-*.deb aren't strictly
required, but have been included as the one on the master file system
may change regularly even though it shouldn't be constantly updated on
the diskless clients:

/etc/adjtime
/etc/motd
/etc/serial.conf

(consider not copying /etc/adjtime at all - is it required?)