Web-Kickstart
=============

Version 3.0-ish.

Copyright 2002-2008 NC State University
Written by
   Jack Neely   <jjneely@pams.ncsu.edu>
   Elliot Peele <ebpeele2@pams.ncsu.edu>

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., 675 Mass Ave, Cambridge, MA 02139, USA.


Introduction
------------

Your IT team has thousands of workstations and servers to maintain just
like every other enterprise class organization or educational institution.
Hundreds of these machines run Red Hat Linux or a custom distribution
based on Red Hat Linux or Fedora Core.  Clearly you need an automated
solution to install these linux machines and configure them properly for
your environment.

With Red Hat Linux or Fedora Core this is where Kickstart comes into
play.  You simply have a custom boot disk that grabs the kickstart file
off a server and automates the complete install or just with the ks
boot option.  However, your kickstarts are mostly the same except for 
small bits, like a printer, and there's not an overly good way to have 
server based kickstart that can include other kickstarts.  Also, other 
folks in your IT team(s) may not know how a kickstart works enough to 
create them.  Kickstarts are long and tedious.

Here is where Web-Kickstart comes in.  Web-Kickstart reads small
config files from a central location, such as your distributed file
system or a server.  These files follow in a similar style to
<key> [value ...].  With two to four lines you can have a highly
customized and configure linux install.  Config files can include
other files, and you can even attach multiple %post's and %pre's.
Web-Kickstart takes this config file, loads it into a Cheetah template
that you can customize, dynamically generates a complete kickstart,
and sends it to the installing client via HTTP.  For example, I can
install a Realm Linux 9 machine (which is a customized version of
Red Hat Linux 9 used at NC State University) with something this
simple:

   version 9
   printer cox359a@print-server.ncsu.edu
   enable adminusers jjneely

This specifies the version to install which is the only required line,
specifies the proper default printer, and adds a user to the administrative
users for the machine.  The rest of the install is controlled by the
defaults in the class.  

Included is a template and documentation for installing stock RHEL
or Fedora.  These are the basis of the working templates I use at NC
State University to install Realm Linux as an example for how you can
customize the software.  

Feedback and patches welcome!


Installing
----------

The RPMs provided or generated from the Makefile should get everything
installed for you.  

You can run WebKickstart through Apache via mod_python or by using the 
stand alone basic server.  The ks.py file is the mod_python handler while
basicserver.py runs an HTTP server with Python's build it baseHTTPServer.

The basic server can be run like so

    python simplewebkickstart.py -C /path/to/conf/dir

The default for the configuration directory is /etc/webkickstart.

To do some quick testing and generation of kickstarts you can use the
following:

    python makekickstart.py -C /bah/foo foghorn.unity.ncsu.edu

To run the mod_python handler you need to make sure that

    AllowOverride FileInfo

is set in your Apache configuration for the directory you want to
run the handler from.  You can put the rest in a .htaccess file or
directly in Apache's configuration:

    AddHandler python-program .py
    PythonHandler webKickstart.ks
    PythonPath "sys.path + ['/extra/python/path']"
    PythonOption webKickstart.config /path/to/conf/dir/

The PythonPath line is only needed if WebKickstart is installed some other
place that where Python normally keeps its packages.  The 'webKickstart.config'
option can be used to specify where the main configuration directory is.

Configuring
-----------

All the configuration bits normally go in an /etc/webkickstart directory.
The main config file is webkickstart.conf inside that directory.  
The config files for each hosts by default live in /etc/webkickstart/hosts,
configuration for any user supplied plugins in /etc/webkickstart/pluginconf.d,
and the templates or profiles in /etc/webkickstart/profiles.

You may configure WebKickstart to use a different path other than
/etc/webkickstart for configuration information.  However, it still expects
for /you/custom/path/webkickstart.conf to exist.  See the default 
webkickstart.conf for details.

You may specify the keyword you want to use to indicate which template or
profile to use and which keywords will include other config files.  You
can also specify alternate locations for where the profiles and config
files live.  Each available configuration bit is documented in the
example webkickstart.conf.

The config file has a section for each template / profile.  The section
name (the name inside [ ]) is the name that your configs must use to
refer to the profile they want to use.  These are the options:

    enable = 1 -- Set to enable the usage of this profile
    plugins = <plugin1>... 
               -- The list of custom plugins to run in order
    template = <path>
    var.<foo> = <value>

Plugins are python modules that live in the webKickstart.plugins package.
The __init__.py file contains a super class for them and I've included
several examples.  These plugins give you added flexibility to add
variables and data to what the profile template can see.

Above in 'var.<foo>' the '<foo>' may be replaced by any text to insert
extra variables into the Template directly from the configuration.  This
is useful to store private keys or such only in the configuration rather
that code or templates.  Note that '<foo>' is not case preserving as
its groked with python's ConfigParser.

The 'template' configuration option selects the exact Cheetah Template
file that will be used.  Non-absolute paths are relative to the profiles
option in the [main] section.  If a default is not specified elsewhere in
the configuration file then '<section>.tmpl' is used where <section> is the
text inside the [ ] brackets for this section.

There may also be a [default] section that sets default values for each
template/profile.  This avoids having to type similar configuration information
for each template/profile.  This section cannot be used to set 'enable = 1'
however.

Profiles
--------

The profiles are normal Cheetah templates.  You can do anything you
normally would in that environment.  Each row from a config file turns 
into a variable the template can use that is named the same as the first
token in the row.  The variables are TemplateVar objects defined in the
templatevar.py file.  This makes the variable very easy to print out 
verbatim, reference each token via its index, match a regex pattern, and
iterate through multiple rows if the same key word is used multiple times.

The example profiles provide many examples for how to use the template 
variables.


WebKickstart Tools WebApp
-------------------------

A simple CherryPy based web application is provided in webapp.py in the
webKickstart package directory.  You'll need the Kid templating language
and CherryPy 2.3 for it to run.  This provides some handy tools that allow
you to debug your config files, check for collisions, etc.

Chose a location directive or a directory to use to serve out the web app.
It does not need to be the root of a domain.  Set up your Apache configuration
like so:

    PythonPath "sys.path + ['/extra/python/path']"
    PythonOption webKickstart.config /webKickstart/config/directory
    PythonOption webKickstart.appMount /webapp/url/path
    SetHandler python-program
    PythonHandler webKickstart.modpython_gateway::handler
    PythonOption wsgi.application cherrypy._cpwsgi::wsgiApp
    PythonOption wsgi.startup webKickstart.webapp::wsgi

Restart your Apache server and you should find the app running at

    http[s]://servername/webapp/url/path

You should use some sort of authentication and authorization to use these
tools.  That's left up to your implementation.


More Information
----------------

See the docs/ directory and the actual included web pages.