###########################################################################
                     Using BPBATCH in the LTSP environment
		          Author: Darryl Bond
###########################################################################

INTRODUCTION
Bpbatch (www.bpbatch.org) is a PXE boot loader. The same binary works on any
PXE compliant NIC card. That is, it does not require a specific driver for
the NIC. 

The bpbatch bootloader must be downloaded from www.bpbatch.org. 
The files downloaded in the archive are:

INSTALL    bpbatch.hlp  mrbatch.exe     mrzip.exe     whatsnew
LICENSE    bpbatch.ovl  mrbatch.static  mrzip.static
bpbatch.P  mrbatch      mrzip           readme

Please read the license as it has some restrictions when being on-sold. 
Rename bpbatch.P to bpbatch for installation

There are 3 files of interest in a given installation under the tftp directory:

  * bpbatch     - is the bootstrap loader loaded from the tftp server 

  * bpbatch.ovl - is the command file interpreter. This is downloaded from the
                  tftp server by the bootstrap loader.

  * bpbatch.bpb - is the command file that instructs bpbatch what it must do.

It would be advisable that these files are stored in /tftpboot/lts/bpbatch.

The bpbatch command file in the LTSP environment instructs bpbatch to download
the LTSP kernel and initrd, load them into memory and boot the kernel much
like a normal LTSP startup.

The sequence of events for a bpbatch boot is as follows:

  1. PXE dhcp request gets the IP address and location of the boot
     file (bpbatch)

  2. PXE requests the bpbatch bootstrap loader from the tftp server.

  3. The bootstrap loader requests the bpbatch.ovl interpreter from
     the tftp server from the same directory as the bootstrap loader.

  4. The bootstrap loader requests the command file from the tftp server
     from the same directory as the bootstrap loader.

  5. The interpreter executes the command file which has instructions
     on where to load the Linux kernel and initrd.

  6. The LTSP kernel & initrd is loaded from the tftp server and
     installed in memory.

  7. The kernel is executed and booting proceeds as normal LTSP.


DHCP Configuration:

Bpbatch uses a standard bzImage kernel format and compressed initrd
filesystem. This is unlike etherboot which uses the two files together
in a tagged format. The advantage of bpbatch in the ltsp environment
is that the same image is used for all PXE clients. In a mixed etherboot
and bpbatch environment a simple test for a PXE client in the ISC3.X dhcp
server allows it to send the correct boot file.

An example ISC3.X dhcpd.conf for a bpbatch/etherboot environment:

############## /etc/dhcpd.conf ################################
not authoritative;
ddns-update-style             none;             # required for ISC v3.0
option option-128 code 128 = string;
option option-129 code 129 = text;

shared-network LTSP {
    subnet 192.168.0.0 netmask 255.255.255.0 {
      use-host-decl-names       on;
      option log-servers	192.168.0.254;
      option subnet-mask            255.255.255.0;
      option broadcast-address      192.168.0.255;
      option root-path              "/opt/ltsp/i386";
      option routers                192.168.0.254;
      server-identifier 	192.168.0.254;
    }
}

group {
    use-host-decl-names       on;
    option root-path "/opt/ltsp/i386";
    if substring (option vendor-class-identifier, 0, 9) = "PXEClient" {
	filename "/lts/bpbatch/bpbatch";
    } else {
	filename "/lts/vmlinuz-2.4.9-ltsp-4";
    }    

   host ws02 {
       hardware ethernet 00:40:63:c0:77:32;
       fixed-address 192.168.0.2;
   }
   host ws03 {
       hardware ethernet 00:30:1b:0c:2d:be;
       fixed-address 192.168.0.3;
   }

}
############# end /etc/dhcpd.conf ##############################

Note the test at the beginning of the group to determine whether the PXE
bootstrap is to be called or to use the etherboot tagged image.


BPBATCH Configuration:

The bpbatch interpreter has a simple syntax with variable substitution etc.
Comprehensive explanation of bpbatch syntax is outside the scope of this
document. Please refer to www.bpbatch.org for more information.

The bpbatch configuration file is kept in the same directory as the bootstrap
loader and must be named bpbatch.bpb.

An sample bootstrap configuration file for LTSP is:

################# /tftpboot/lts/bpbatch/bpbatch.bpb #############
set CacheNever="ON"
set len=@"$Basename"
set len=($len - 9)
set mybase="$Basename"[0-$len]
LinuxBoot "$mybase/bzImage-3.0.1-ltsp-4" "root=/dev/ram0 init=/linuxrc rw" "$mybase/initrd.ltsp.gz"
################# End /tftpboot/lts/bpbatch/bpbatch.bpb #########

Note that the interpreter calculates the directory that the kernel and initrd
is stored relative to the directory that the bootstrap loader is stored. It
expects the filenames to be fixed, hence the 9 character offset. This command
file allows any number of bpbatch directories if necessary.

The LinuxBoot line has the location of the kernel binary, kernel arguments
and the initrd root filesystem for LTSP.

Kernel image:

Bpbatch uses a standard kernel bzImage generated by a kernel compile. This
image is distributed with the ltsp_initrd_kit.  This bzImage file may be
copied into place ( /tftpboot/lts/bpbatch/ )and renamed to the filename
nominated in bpbatch.bpb (bzImage-3.0.1-ltsp-4 in this case). 

Initrd image:

The initrd is a more difficult to create. The ltsp_initrd_kit buildk script
generates an initrd in the process of creating a tagged image. This initrd
image may be copied into the bpbatch directory. The problem is that the buildk
script requires a kernel & modules to be built and installed from source. This
is unnecessary in our case as we simply want to use the standard distribution.
The buildk script can be modified to create the initrd from the distribution.

These steps will create a suitable initrd:

The ltsp packages kernel modules and initrd_kit images are downloaded and
unpacked to:

  * /tmp/ltsp/lts_kmods

  * /tmp/ltsp/ltsp_initrd_kit

The modified buildk script can then be run to create the image


################# Heavily Modified buildk script #######################
#
# build script for building the initrd for LTSP
#
# Copyright (C) 2001 James A. McQuillan <jam@McQuil.Com>
#
# This program 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; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# 09/02/2001 -jam- Initial writing of this script
# 20/07/2002 -db - Modified to use the stadard install files to create an initrd for bpbatch
#

#
# This is the size of the filesystem
#
SIZE=4096

#
# Create the filesystem image file
#
dd if=/dev/zero of=initrd.ltsp bs=1k count=${SIZE}
echo "y" | mke2fs initrd.ltsp ${SIZE}

#
# Mount the new image, so we can copy files to it
#
[ ! -d /mnt/initrd ] && mkdir -p /mnt/initrd
mount -t ext2 -o loop initrd.ltsp /mnt/initrd

#
# Copy the root tree to the new filesystem
#
echo "Copying the root tree"
cd standard
find ./ -print | sort | cpio -pmud /mnt/initrd
cd ..

# assume that there is only one set of modules avilable --- probably a bad idea.
cp ../ltsp_kmods/i386/lib/modules/*/kernel/drivers/net/*.o /mnt/initrd/lib/modules/net
cp ../ltsp_kmods/i386/lib/modules/*/kernel/drivers/net/tulip/*.o /mnt/initrd/lib/modules/net

echo 
echo "Checking size"
df -v /mnt/initrd
echo 
umount /mnt/initrd

#
# Compress it, to prepare it to be tacked onto the
# end of the tagged kernel
#
echo "gzipping initrd"
gzip -9 </tmp/initrd.ltsp >/tmp/initrd.ltsp.gz

############## End buildl script #########################################

The initrd suitable for use with bpbatch is located /tmp/initrd.ltsp.gz and
can be copied to /tftpboot/lts/bpbatch.

You are now ready to test your bpbatch installation.
