SmoothWall Kit Guide

By Lawrence Manning (guru@smoothwall.org)

Version: 1.0 - Date: 19/09/00

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.

TODO: Write more on this.

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.

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