=head1 NAME

systemconfig.design - System Configurator Design document 

=head1 The Problem

System Configurator was initially dreamed up during a brain storming session
between Brian Finley, Rich Ferri, Michael Chase-Salerno, and Sean
Dague.  The intent of the session was to determine how, if at all, the
SystemImager and LUI projects could merge into something grander.

Coming to the table each project had its strengths and its
weaknesses. The strengths of SystemImager included a strong user base,
a very easy to use interface,and the use of rsync.  The strengths of
LUI included the ability to describe an abstract machine through the
use of resources.  This allowed for more heterogeneity then SystemImager.

The two projects decided that they could merge in the following way:

=over 4

=item *

Take the best pieces of LUI, and create a System Installer project which 
could build SystemImager images from an abstract description.

=item *

Create a new System Configurator project whose job was to define an installation
API for things like Networking and Boot loading.  In doing LUI ports to
SuSE and PPC, this was seen as the major difference between
distributions.  At that point there was a awful lot of code in
SystemImager to handle 2 releases of Debian and Red Hat, and it did
not handle SuSE at all.

=back

The System Configurator project would also add some rudimentary
Hardware detection.  This would allow the same image to be installed
on machines that only differed in the Network Interface Cards or SCSI
Cards that they used.  In order to support this fully, it would also
need the ability to generate Initial Ramdisks for Linux distributions
that did not compile SCSI drivers into their kernel by default.  This
feature had been considered critical to future versions of LUI, so
some research had been done on that already.

=head1 Footprinting

There were many concepts on the best way to do the System Configurator
project.  One proposal was a distribution centric model.  There would
be a distribution object which could be instantiated and would be able
to configure a particular Linux distribution.

This idea was rejected because of one simple fact... B<there are over 200 Linux distributions>.

Yes there are only a handful (12 or so most likely) that would be
considered "popular", but even within those 12, each version might
have enough incompatibilities with previous versions that chaos would
ensue.  For instance, Red Hat 6.2 might need to be considered
differently from Red Hat 7.1. The explosive growth of code in this 
environment would be dangerous to the goals of the project to be as
distribution agnostic as possible.

The idea of B<Footprinting> won out over other ideas for design.  The
concept of footprinting is simple.

  if($capability->footprint) {
     $capability->setup;
  }

That is, if the capability appears to be appropriate for the
environment, then setup that capability.  In the case of networking
configuration files, this is a very clear win.  

The reason that it is such a clear win, is that many Linux
distributions are just extensions on other distributions.  Although
Turbo Linux, Mandrake, Connectiva, and Red Hat are all very separate
entities, their underlying network configurations are nearly
identical.  By using footprints instead of Distributions, you have
normalized your problem.

This also means that if any new distribution comes along that uses
exactly the same networking as any type that is already supported, the
new distribution is supported for free!  And who said there is no such
thing as a free lunch?

head1 Tasks

System Configurator has 5 discreet tasks that it must perform.  

=over 4

=item Hardware Detection

This will generate alias in modules.conf or equivalent files

=item Network Setup

Sets up the network scripts for installation

=item Initial Ramdisk Generation

Generate the appropriate initial ramdisk for the system

=item Bootloader Config File Generation

Generate the Bootloader configuration files

=item Install Bootloader

Install the bootloader

=back

In order to provide maximum flexibility none of these tasks must rely
on any other task having completed.  That means there are 2 message
passing mechanism between tasks.  Both of these message passing
mechanisms allow the user to manually perform any part of the System
Configuration in the event that System Configurator can not properly
handle the special circumstances.

=head2 $config

The first is the use of a global $config object.  This object is
generated through parsing of (in this order): 

=over 4

=item B<1.> 

Command Line Arguments

=item B<2.> 

Standard In (if --stdin is specified)

=item B<3.> 

The config file.  This defaults to /etc/systemconfig/systemconfig.conf.

=back

Normally each subsection grabs the variables that it is interested in
via the C<varlist> method of $config.  Although $config should mostly
be used in a read only context, certain components, most noteably the
Initial Ramdisk section, can write information into the $config
object. 

The initial ramdisk code does this by specifying the initial ramdisk
file for each B<[KERNEL\d+]> section that it processes.  From the
perspective of the Bootloader setup code all it sees is:

  $config->kernel0_image
  $config->kernel0_initrd

It does not care that C<$config-E<gt>kernel0_initrd> comes from the
initial ramdisk code, or from the user specifying it in the config
file. 

=head2 Filesystem

The second message passing mechanism is the filesystem of the client
machine.  The most noteable example here is the hardware setup
mechanism. 

When the hardware detection code runs, it modifies modules.conf (or a
similar file) and sets up lines of the form:

  alias eth0 eepro100
  alias scsi_host_adapter ips

These lines are then read by the initial ramdisk component of System
Configurator to determine which modules will need to be added to the
initial ramdisk.  Many Linux distributions provide a kernel without
SCSI support.  On SCSI only systems, and initial ramdisk is required
to gain access to the root device during startup.

=head1 Module Design

The oldest, and most mature part of the System Configurator code is
the Networking code.  I will use this as an example for most

...

=head1 Test Cases

Modules should be written for automated testability.  The best way to
do this is to seperate out functions that are input / output
oriented from functions that are side effect oriented.

For instance, the generation of a file from inputs is input/output
oriented.  You can give it many different values of inputs and see
what values of outputs happen.  The running of a UNIX command is side
effect orriented.  The effects of those commands are often very hard
to test in a consistant manner.

Perl provides a testing harness mechanism during installation.  This
is used by System Configurator to validate the portions of the code
which can be easily validated.

=head1 AUTHORS

  Sean Dague <japh@us.ibm.com>

=head1 HISTORY

$Log: design.pod,v $
Revision 1.6  2001/08/21 12:54:17  sdague
minor changes to make 0.87 work.

Revision 1.5  2001/08/10 18:10:26  sdague
a few more items in design.pod
sc_coding.pod has more consistant markup
lib/Network.pm has propper docs
lib/SCConfig.pm has been purged of docs (they don't build anyway)
lib/Network/Generic.pm has propper docs

Revision 1.4  2001/08/09 15:46:51  sdague
still working...

Revision 1.3  2001/08/09 14:20:15  sdague
maybe first draft


=head1 SEE ALSO

L<systemconfigurator>, L<systemconfig.conf>, L<AppConfig>, L<Test>