<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.7//EN" 
               "/usr/lib/sgml/dtd/docbook-xml/docbookx.dtd">
<book>
  <title>Using the diskless package for nfsroot systems.</title>

  <chapter>
    <title>Notes for current version</title>
    <para> After creating a diskless-image, the timezone must be manually set
    using tzconfig, eg.</para>

    <screen>chroot <replaceable>imagedir</replaceable> /usr/sbin/tzconfig
    </screen>

    <para>should do it.
    </para>
  </chapter>

  <chapter>
    <title>Introduction</title>
<para>This package comes with two programs, diskless-newimage, and
diskless_newhost to simplify setting up and maintaining diskless
clients.</para>

    <para>
      It requires base.tgz created by createbasetgz script, and one of
      the diskless-image packages. As of writing this, the only
      diskless-image package that has been tested is diskless-image-simple
      (diskless-image-simple_0.3.0_all.deb).
    </para>
    
    <para>
      The clients are setup to mount / as Read/Only from a shared point and
      mount /etc as Read/Write before executing /sbin/init.
    </para>

    <para>
      Please see /usr/doc/diskless/TODO for a list of known bugs.
    </para>
    
    <section>
      <title>Conventions used in this documentation</title>
      <table>
        <title>Abbreviated Forms</title>
	<tgroup cols="2">
	  <tbody>
	    <row><entry>$VAR</entry><entry>/var/lib/diskless</entry></row>
	    <row><entry>$USR</entry><entry>/usr/lib/diskless</entry></row>
	    <row><entry><replaceable>imagedir</replaceable></entry><entry>is the where the imagedir (aka master image) is to be placed.</entry></row>
	    <row><entry><replaceable>hostsdir</replaceable></entry><entry>is the data specific to all hosts is placed.</entry></row>
	    <row><entry><replaceable>ip</replaceable></entry><entry>is the IP address of the host for the current operation.</entry></row>
	    <row><entry><replaceable>hostdir</replaceable></entry><entry>is the data specific to an individual host is placed.
		this will be <replaceable>hostsdir</replaceable>/<replaceable>ip</replaceable>.</entry></row>
	  </tbody>
	</tgroup>
      </table>
      <note>
        <para>if <replaceable>imagedir</replaceable> 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!
        </para>
      </note>
    </section>
    
    <section>
      <title>Your support is required.</title>
      <para>
	The original author for this program was :
      </para>
      <address>
	<email>bam@debian.org</email>
	<email>bam@snoopy.apana.org.au</email>
      </address>
      <para>
	The maintainership has been moved over to Junichi Uekawa. 
	Please give your feedback and bugreports. Please report them to the 
	Debian Bug Tracking System.
	It is possible to contact the current maintainer directly by the following address: 
      </para>
      <address>
	<email>dancer@debian.org</email>
	<email>dancer@netfort.gr.jp</email>
      </address>
    </section>
    
  </chapter>
  <chapter>
    <title>Getting Started</title>
    
    <para>Steps to get going:</para>
    <orderedlist>
      <listitem>
        <para>
          Build the kernel.
	</para>
      </listitem>
      <listitem>
        <para>
          Configure BOOTP (Someone may use dhcpd, I use rarpd) and perhaps tftp.
	</para>
      </listitem>
      <listitem>
        <para>
          Setup the group.
	</para>
      </listitem>
      <listitem>
        <para>
          Setup the hosts within the group.
	</para>
      </listitem>
      <listitem>
        <para>
          Setting up /etc/exports.
	</para>
      </listitem>
      <listitem>
        <para>
          Boot remote NFS system (not described here).
	</para>
      </listitem>
    </orderedlist>

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

    <para>
      All steps should be conducted on the NFS-server (or another computer
      that has access to the correct directories), unless stated otherwise.
    </para>

    <section>
      <title>Building the kernel</title>
      <para>
	The kernel should be configured for NFS-ROOT. I think the most important
	options are:
      </para>

      <screen>
CONFIG_NET=y
CONFIG_PNP=y
CONFIG_IP_PNP=y
CONFIG_IP_PNP_BOOTP=y
CONFIG_NFS_FS=y
CONFIG_ROOT_NFS=y
      </screen>

      <para>
	Also, recent kernels (since 2.2.16 or somewhere around, and 2.4.x series, and 2.5.x series)
	do not boot off network by default, a one-line patch is required in 
	<filename>net/ipv4/ipconfig.c</filename> to change the value of the 
	variable.
      </para>

      <screen>
	int ic_enable __initdata = 0;                   /* IP config enabled? */
      </screen>
      <para>
	In addition, the desired network cards must be compiled into the kernel
	(ie a module will not work).
      </para>

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

      <para>
	For example, someone used to use (for kernel version 2.1.29):
      </para>
      <screen>
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
      </screen>
      <para>
	This requires the debian package netboot to be installed.
      </para>

      <para>
	However, putting the kernel image onto a place reachable by TFTP should suffice.
      </para>
    </section>

    <section>
      <title>Configuring BOOTP and TFTP</title>
      
      <note>
	<para>
	  this assumes that you have dhcpd installed; if you use bootp then you need
	  to look up the appropriate documentation.
	</para>
      </note>

      <para>
	To use rarpd, the configuration is very much simple. The file
	<filename>/etc/ethers</filename> on the server needs to contain a line like :
      </para>
      <screen>
00:40:33:29:53:AB 192.168.87.131
      </screen>

      <para>
	I (bam) used dhcpd, with the following configuration:
      </para>

      <screen>
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";
}
[...]
      </screen>

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

      <para>
	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.
      </para>

      <screen>
        option root-path                "<replaceable>imagedir</replaceable>/root";
      </screen>

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

      <para>I use tftpd configured in /etc/inetd.conf with:</para>

      <screen>
tftp            dgram   udp     wait    nobody  /usr/sbin/tcpd  /usr/sbin/in.tftpd /var/lib/diskless/boot
      </screen>
    </section>
    <section>
      <title>diskless-newimage: Create/maintain new image/master directory</title>
      <section>
        <title>Syntax</title>
	<cmdsynopsis>
	  <command>diskless-newimage</command>
	  <arg><replaceable>imagedir</replaceable></arg>
        </cmdsynopsis>
      </section>
      <section>
        <title>Options</title>
	<para>If any required information is omitted or invalid or the command
        line, it will be prompted for. </para>
	<para>All of these values are checked to ensure that they are valid. Help may
	be obtained by pushed ? at any prompt.</para>
      </section>
      <section>
        <title>Description</title>
	<para>
	  If any required information is omitted or invalid or the command
	  line, it will be prompted for. 
	</para>

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

	<para>
	  This creates a new image using base.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.
	</para>

	<para>
	  Some tasks are left incomplete:
	</para>

        <orderedlist>
	  <listitem>
	    <para>
	      Install kernel modules. It is easier if you can leave this until
              later, but if you must do it now:
	    </para>
	    <screen>dpkg --root <replaceable>imagedir</replaceable> --install kernel-image-*.deb
	    </screen>
            <warning>
	      <para>
	        Do not tell the installation script to install lilo, as
                it may replace your lilo setup on the NFS server.
              </para>
	    </warning>
	  </listitem>
	  <listitem>
	    <para>
	      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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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).
	    </para>
	  </listitem>
	</orderedlist>
	<para>The following steps should be conducted on the newly booted system:</para>
        <orderedlist>
	  <listitem>
	    <para>Log in as root. No password is required.
	    </para>
	  </listitem>
	  <listitem>
	    <para>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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>Be careful in adding a standard user account and/or shadow
	    passwords if you use NIS. These options may not be desirable.
	    </para>
	  </listitem>
	  <listitem>
	    <para>I recommend:</para>
	    <screen>
dpkg --purge lilo		( prevent potentially dangerous mistakes)
dpkg --purge pcmcia-cs			(unless you have pcmcia modules)
dpkg --install kernel-image-*.deb	 (if not already done)
dpkg --install ssmtpd_*.deb
dpkg --install anacron_*.deb
	    </screen>
	  </listitem>
	  <listitem>
	    <para>
	    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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>Suggested X configuration. Put next line inside /etc/inittab:
	    </para>
	    <screen>7:23:respawn:/etc/init.d/X vt7 -query snoopy
            </screen>
	    <para>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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	    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.
	    </para>

	    <para>
	    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.
	    </para>

	    <note><para>
	    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.
	    </para></note>
	  </listitem>
	</orderedlist>
      </section>
    </section>

    <section>
      <title>diskless-newhost: create/maintain new host</title>

      <section>
        <title>Syntax</title>
	<cmdsynopsis>
	  <command>diskless-newimage</command>
	  <arg rep="repeat"><replaceable>imagedir</replaceable>
	    <arg rep="repeat"><replaceable>ip</replaceable>
	      <arg><replaceable>option</replaceable>=<replaceable>value</replaceable></arg>
	    </arg>
	  </arg>
        </cmdsynopsis>
	<note><para>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.
	</para></note>
      </section>
      <section>
        <title>Options</title>
	<para>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.
	</para>
      </section>
      <section>
        <title>Description</title>
	<para>  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 <replaceable>hostdir</replaceable>/etc/diskless-host. If any files
	have been changed, the user will be prompted (see chapter 5).</para>

	<para>
	This program should be run whenever files under <replaceable>imagedir</replaceable> may have
	changed, in order to make each <replaceable>hostdir</replaceable> consistent.
	</para>
      </section>
      <section>
        <title>Source</title>
        <table>
          <title>Source Files</title>
	  <tgroup cols="2">
	    <thead>
	      <row><entry>directory tree</entry><entry>rules file</entry></row>
	    </thead>
	    <tbody>
	      <row><entry><replaceable>imagedir</replaceable>/$USR/template</entry><entry><replaceable>imagedir</replaceable>/$USR/rules-template</entry></row>
	      <row><entry><replaceable>imagedir</replaceable></entry><entry><replaceable>imagedir</replaceable>/$USR/rules-image</entry></row>
	    </tbody>
	  </tgroup>
        </table>
	<para>
	In addition, files under <replaceable>imagedir</replaceable>/$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 <replaceable>imagedir</replaceable>/$VAR.
	</para>
      </section>
      <section>
        <title>Destination</title>

	<para>Files are created in the following locations:</para>

        <orderedlist>
	  <listitem>
	    <para>
	    It creates files under <replaceable>hostdir</replaceable> (ie <replaceable>hostsdir</replaceable>/<replaceable>ip</replaceable>).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	    It creates sample entries for /etc/exports in
	    <replaceable>hostdir</replaceable>/etc/diskless-host/exports.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	    It creates a symbolic link from /tftpboot/$IP to <replaceable>hostsdir</replaceable>/root
	    (the root file-system). Any existing symlink is deleted. This step is
	    bypassed if /tftpboot doesn't exist.
	    </para>
	  </listitem>
	</orderedlist>
      </section>
    </section>
    <section>
      <title>Configure /etc/exports</title>
      <para>
      Sample entries for /etc/exports for each host have been created in
      <replaceable>hostsdir</replaceable>/<replaceable>ip</replaceable>/exports, however, these will have to be somehow merged
      together. I currently use something similar to:
      </para>

<screen>
/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)
</screen>

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

      <para>
	This may also work:
      </para>
<screen>
/etc/init.d/netstd_nfs reload
</screen>
    </section>
  </chapter>

  <chapter>
    <title>Actually booting the kernel on diskless hosts</title>
    <para>
      Here, the actual method for booting the kernel is explained.
    </para>
    <section>
      <title>Not-really diskless booting with grub</title>
      <para>
	It is possible to use grub from floppy disk to
	load up the kernel.
	Refer to grub manual for details, since the way
	to configure grub seems to change every so often.
	It is necessary to recompile grub from source,
	enabling the network boot option, and write
	the image to floppy disk.
      </para>
      <screen>
$ ./configure --enable-eepro100 && make
$ dd if=stage1/stage1 of=image
$ dd if=stage2/stage2 of=image bs=512 seek=1
$ dd if=image of=/dev/fd0 ; sync	
      </screen>
      <para>
	Test the disk with the following commands in
	the grub prompt (if the server is at 192.168.1.1):
      </para>
      <screen>
rarp     
kernel (nd)/boot/netboot init=/bin/sh root=/dev/nfs nfsroot=192.168.1.1:/
      </screen>
    </section>
    <section>
      <title>Doing real diskless booting</title>
      <para>
	There are many other methods to boot the kernel, using ROM
	images etc.
	netboot, and etherboot etc. 
	However, I have not tried them myself.
	Contributions are welcome.
      </para>
    </section>
  </chapter>


  <chapter>
    <title>Format of the Rules files</title>
    <para>
      Every rules file is preprocessed with M4, see
      $VAR/template/group/rules-master for example. M4 is documented in
      section 4.
    </para>

    <para>
      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.
    </para>

    <screen>
--- [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).
    </screen>

    <para>
      If both a pattern and a package are specified, then the file must
      match both.
    </para>

    <para>
      Also supported are (these are parsed *before* the rules above):
    </para>

      <table>
        <title>Rules Commands</title>
	<tgroup cols="2">
	  <tbody>
	    <row><entry>@rename =$src=$dst=</entry><entry>
	    Use with extreme caution, renaming individual
	    files is OK, using substitution is OK, however
	    may cause problems.
	    </entry></row>

	    <row><entry>@ignore $src</entry><entry>
	    Source file is not copied, even if it exists in
	    a source directory with higher priority.
	    </entry></row>
	  </tbody>
	</tgroup>
      </table>

      <para>
      Potential problems with rename:
      </para>

      <table>
        <title>Pitfalls with rename</title>
	<tgroup cols="2">
	  <tbody>
	    <row><entry>@rename =(.*)=/etc$1=</entry><entry>
	    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.
            </entry></row>

	    <row><entry>@rename =(.*)=$1.old=</entry><entry>
	    This is pure evil. DO NOT DO IT! For example,
            consider:

<screen>
/      ===&gt;  /.old
/a     ===&gt;  /a.old
/a/b   ===&gt;  /a/b.old
/a/b/c ===&gt;  /a/b/c.old
</screen>

            This is probably not intended, and will fail
            if the /a/b directory doesn't already exist.
	    </entry></row>
	  </tbody>
	</tgroup>
      </table>

    <para>
      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.
    </para>
    
  </chapter>

  <chapter>
    <title>M4 File Filtering</title>
    <para>
      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)
    </para>

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

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

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

    <para>
      For more information on M4, please see the M4 info page.
    </para>
  </chapter>

  <chapter>
    <title>Default file copying rules</title>
    <para>
      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.
    </para>

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

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

    <para>
      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. 
    </para>

    <para>
      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.
    </para>
    
    <para>
      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:
    </para>

    <itemizedlist>
      <listitem>
        <para>
	  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.
	</para>
      </listitem>
      <listitem>
        <para>
	  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.
        </para>
      </listitem>
      <listitem>
        <para>
	  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".
	</para>
      </listitem>
    </itemizedlist>

    <para>
      As from autoinstall.pm::doit:
    </para>

    <screen>
         | <---------------- 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     |
-------------------------------------------------------------------
    </screen>
    <note>
      <para>
	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.
      </para>
    </note>

    <table>
      <title>Source File</title>
      <tgroup cols="2">
	 <tbody>
	  <row><entry>deleted</entry><entry>means the file is listed in .config.all but not there.</entry></row>
	  <row><entry>created</entry><entry>means the source file exists but not listed in .config.all
          (as it is not listed, there is nothing to compare it with).</entry></row>
	  <row><entry>same</entry><entry>source file not modified since last copied.</entry></row>
	  <row><entry>newer</entry><entry>source file is newer then reference.</entry></row>
	  <row><entry>older</entry><entry>source file is older then reference.</entry></row>
	  <row><entry>changed</entry><entry>source file has been determined different then reference
	  by some other check (eg file size).</entry></row>
	</tbody>
      </tgroup>
    </table>

    <table>
      <title>Destination File</title>
      <tgroup cols="2">
	 <tbody>
	  <row><entry>deleted</entry><entry>means the file is not there.</entry></row>
	  <row><entry>created</entry><entry>means the destination file exists but not listed in .config.all
	  (as it is not listed, there is nothing to compare it with).</entry></row>
	  <row><entry>same</entry><entry>destination file not modified since last copied.</entry></row>
	  <row><entry>newer</entry><entry>destination file is newer then reference.</entry></row>
	  <row><entry>older</entry><entry>destination file is older then reference.</entry></row>
	  <row><entry>changed</entry><entry>destination file has been determined different then reference
	  by some other check (eg file size).</entry></row>
	</tbody>
      </tgroup>
    </table>

    <table>
      <title>Options</title>
      <tgroup cols="2">
	<tbody>
	  <row>
	    <entry>ASK</entry>
	    <entry>
	      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.
	    </entry>
	  </row>
	  <row><entry>REPLACE</entry><entry>Replace destination file, if exists.</entry></row>
	  <row><entry>NOP</entry><entry>don't do anything.</entry></row>
	</tbody>
      </tgroup>
    </table>
  </chapter>
</book>