<PRE>
SmoothWall Kit Guide

By Lawrence Manning (guru@smoothwall.org)

Version: 1.1 - Date: 04/12/00

Changes from 1.0:

Wrote more on installer and added stuff about restartssh.

This is the SmoothWall develepment kit guide.  It describes, somewhat
roughly, how to build the setup disks and ISO images, as well as describing
various ways in which you can make changes to the smoothwall.tgz file.

1. Directory layout.

Under smoothwall/ you wll see the current directories and a couple of files:

kernel.config :       
	SmoothWall kernel config file.  The same config is used on the
install disk as in a running smoothie.
distrib/ :
	This is a placeholder for the contents of smoothwall.tgz.  Start by
installing a smoothwall.tgz from the CDROM into this directory.
docs/ :
	Documentation.
install/ :
	This directory contains stuff related to building the disk images
and cdrom image, as well as some helper scripts.
install/cdrom/ :
	Contains a copy of what will be on a final cdrom image.  This
includes the two floppy images and the smoothwall.tgz.
install/installroot/ :
	This is the contents of the rootfs part of disk1.  That is, it
contains a mini linux, cdrom modules, and the install program.  It's based
on VA 6.2.1 (RH 6.2) like the rest of smoothwall.  It uses the humungus
glibc, mostly because it makes it easy to compile programs on a normal linux
distrib that can be put streight on the floppy.
install/kernelfs :
	"kernelfs" is the name for the fs on disk1.  It contains the kernel,
gziped rootfs, lilo config, and the message file.
install/mnt :
	A empty dir.  This is used as a mountpoint for when the install root
image is created using loopback.  Basically a 4meg scratch file is created
that is used as /dev/loop0, mkfsed, and mounted here.  Then the contents of
installroot are copied in.  Its then unmounted, /dev/loop0 is deleted and
the scratch file gziped.  The scratch file becomes installrootimage.gz and
is copied into kernelfs.
install/{makeimage,makelilo} :
	Two little bash scripts.  These are explained below.
pictures/
	Pictures and archives of screengrabs.
programs/
	Directory for programs.  See Programs section.  Put the contents of
smoothwall-progs-X.Y.Z.tar.gz in here.
releases/
	Directory for finished stuff.
releases/images-X.Y.Z/
	Contains finished disk and cdrom images prior to uploading.
releases/sources-X.Y.Z/
	Contains sourcecode archives.

2. Description of bootdisk AKA disk1.

Creating a disk1 is a two stage process.

2.1. The rootfs

install/installroot contains the disk1 root filesystem, where the install
program and libraries live.  Space is *tight*.  There is currently no room
whatsoever.  I used the BootDisk-HOWTO to make this.  All binaries (except
modules) are stripped.  The install program runs on tty1, it uses tty2 for
logging.  Some other ttys run ash.  A small program I wrote (source in
programs/misc) called iowrap directs stdin/stdout/stderr to another
terminal.  Init kicks off iowrap, which kicks off ash.  See /etc/inittab and
the iowrap.c for more info.

The script makeimage makes installrootimage.gz from the files in installroot
and copies it to kernelfs.

The other thing to note is modules.  /lib/modules/2.2.16/cdrom contains the
cdrom modules.  The other directories (net etc) are sylinks into the cdrom
directory.  The creation of the modules.dep file is a pain, and is described
later on.

2.2. kernelfs

This filesystem contains a kernel, lilo config, message file, and
installrootimage.gz.  It's is created "on the fly" by the makelilo script. 
To run this, have a disk in fd0.  There is currently no way to make disk1
directly to a image file :(

3. Disk2

The main thing to realise is that disk2 contains everything thats contained
on the CDROM, without the smoothwall.tgz and disk image files.  So it
contains:

lib/ :
	Modules live here.  Some are not included.  eg ISDN, MASQ helpers
etc.
bin/ :
	Currently contains: gzip, ifconfig, mke2fs, mksqp, fsdisk, tar and
wget.  All stripped.
partitiontable :
	This is fed into sfdisk by the installer to partition the disks.

There are no scripts for the creation of this disk yet.  The contents of
this disk are under install/cdrom.

Essentially, the last steps of creating a smoothwall release are:

Make a disk1 image.  Put the disk in the drive and dd it to a file
smoothwall-disk1-X.Y.Z in install/cdrom.

Copy bin, lib and partitiontable to a mounted floppy.  umount it, and dd it
to a disk2 file.  Put both disk images in the cdrom directory, along with
the smoothwall.tgz.

Make the ISO from the cdrom dir, setting the disk1 image as the boot image. 
Put the iso in release/images-X.Y.Z as smoothwall-cdrom-X.Y.Z.iso ready for
uploading.

4. Working with smoothwall.tgz

smoothwall.tgz is a minimised linux distribution.  The init scripts are very
simple and all live in /etc/rc.d.  rc.sysinit is executed by init, and it
calls rc.network and rc.firewall to set the network up, start deamons etc. 
Config settings are in /etc/sysconfig and are VAR=VAL pairs.  These are
written by the installer.

Ripping streight out of mail I wrote to Eric S. Johansson:

There are a number of ways to make changes to smoothwall.tgz.

Way 1. Make a directory on your main box called smoothwall/.  Untar
smoothwall.tgz into it.  Assuming your /etc/passwd etc match the
/etc/passwd, everything will be fine.  You can make your changes, tar up
the lot all relative to the smoothwall dir, and do a network install from
you test smoothwall box using your new smoothwall.tgz.

Way 2. Work on a live smoothwall.  Make your changes via telnet.  When you
are done and things are tested, copy the changed files back over your
local tree and tar up as before.

Way 3. Like 2, accept tar up on the smoothwall box itself.  This has
problems in that the "runtime" files (especially those in /var) will be in
you smoothwall.tgz.

I like Way 2.

5. That modules.dep

If you want to recompile the SmoothWall kernel, you will need to do some
hoop jumping to deal with modules.  I install my modules using the following
script which I run from /usr/src/linux.

#!/bin/sh
make INSTALL_MOD_PATH=/home/lawrence/smoothwall/distrib/ modules_install
cp ip_masq_icq-0.56/ip_masq_icq.o
/home/lawrence/smoothwall/distrib/lib/modules/2.2.16/ipv4/
depmod -F System.map -b /home/lawrence/smoothwall/distrib/ -C conf.modules
-n > /home/lawrence/smoothwall/distrib/lib/modules/2.2.16/modules.dep

The ip_masq_icq is an adition module for using icq over a masq link.  You
can get it from:
http://freshmeat.net/projects/ip_masq_icq/altdownload/ip_masq_icq-0.56.tar.gz
Rather worryingly the homepage seems to have vanished :(

The conf.modules file should contain:

path[block]=/lib/modules/2.2.16
path[fs]=/lib/modules/2.2.16
path[misc]=/lib/modules/2.2.16
path[net]=/lib/modules/2.2.16
path[scsi]=/lib/modules/2.2.16
path[usb]=/lib/modules/2.2.16
path[cdrom]=/lib/modules/2.2.16

That will write a modules.dep into your smoothwall tree under distrib/.  You
should copy that file to install/installroot/lib/modules/2.2.16 so it
appears on your disk1 also.

6. Programs

6.1 Installer

Sections each have their own file.  It mounts the cdrom (or disk2 for
network installs), fdisks and mkfses using the binaries on the cdrom.  Then
it configures networking, asks for some passwords and then writes the
settings to the various files.

The full sequence of events is:

a. Initalise logfile.  Install is parsed a argument, the name of the file
(or terminal or whatever) to use for logging.  We use standard fopen etc to
write to this flog.

b. Initalise libnewt and show welcome screen.

c. Look for an ide harddisk by trawling under /proc/ide.  A
ide.c:findidetype is a generic function for finding the first drive of a
given type.  If theres no harddisks, then fail.

d. A generic structure (struct devparms) holds info on a device, including
the devnode name and module parameters.  These are used to hold HD and CDROM
device details.

e. Ask for the install media.  If cdrom, go to f.  Otherwise go to g.

f. Look for an IDE CDROM and fill out a devparms.  If no IDE CDROM is found,
then we ask them to select the CDROM type from the list and try to load
modules for each one until we either succeed or they give up.  Eventaully we
should have a completed devparms with a devnode and a module name and params
(if they are needed).

g. Ask them to insert the SmoothWall CDROM/Floppy.  If we booted of CDROM, then it
will already be in the drive.  We treat floppy and cdrom the same; only the
arguments to mount are different.  For network installs we want a floppy
disk which has the drivers on it.

h. Warn about partitioning etc, then go and sfdisk using the file
/cdrom/partitiontable.  Afterwards mkswap partition 1 and mkfs partition 2.

i. mount harddisk partition 2 under /harddisk.

j. The network is setup.  Attempt to load each module in turn, and if it
succeeds go to l.

k. Ask for a module name and parameters and try to load it.

l. Ask for IP info and try to ifconfig the ethernet device.  At this point
we have working networking.

m. If this is a network install: use wget to download the smoothwall.tgz
into a temporary directory.  Ask them for a URL and call wget.

n. Untar smoothwall.tgz into /harddisk, showing progress as we go.  In tty2
we print the output from tar.

o. If its a network install: remove the smoothwall.tgz from the temp dir.

p. We must write configs now.  Everything will be done into the smoothwall
mounted under /harddisk.  First write /etc/sysconfig/main, which currently
just has the hostname: HOSTNAME=smoothwall.

q. Write the network settings into /etc/sysconfig/network.  This includes
the module name and parameters and IP address information.

r. Write /etc/hosts and tcp wrapper configs (/etc/hosts.[allow|deny]).

s. Ask for the root password and set it by chrooting /harddisk and piping
the inputted password to chpasswd.

t. Ask for the admin smoothwall password and set it by chrooting /hardding
and calling htpasswd. 

u. Make sylinks in /dev for the harddisk and its partition.  /dev/harddisk1
points to /dev/hdX1, etc.  This is done so we don't have to write out
/etc/fstab and /etc/lilo.conf.

v. Run lilo to install itself on the MBR.

w. Reboot.

6.2. iowrap

This is a simple program to direct fds 0, 1 and 2 to a file.  It's used by
init to put the install program on tty1, shells on tty3 etc.

6.2. setuid helpers

hupinet HUPs inet to get it to reread its configuration file.  It reads the
pid from /var/run/inetd.pid and sends it HUP.  Simple.

restartdhcp is simular, but slightly more complicated because it actually
has to kill dhcpd and restart it.  This is also called by rc.sysinit to
start dhcpd off initally.

restartssh is like restartdhcp but it restarts ssh.

smoothiedeath just does a shutdown.  I wrote it so I wouldn't have to setuid
shutdown itself.
</PRE>
