Viper - install, step 3/6 - preseed notes

After obtaining IP and related options thru DHCP in step 2, the host will request the preseed file, at url=http://server/d-i/DIST_NAME/preseed.cfg.

In our setup, that file is a CGI script, scripts/preseed, which performs a query to LDAP to produce the preseed file. LDAP is able to find the host for which the configuration should be generated based on the requestor's IP so no parameters have to be specified, but this and other options can be specified in the request URL via GET parameters.

Before you start the installation on the host, you would usually provide this on the command line:

url=http://IP.AD.DR.ESS

and that would ask for the said path /d-i/DIST_NAME/preseed.cfg on server IP.AD.DR.ESS.

Apache2 configuration

For the preseed CGI to be found at the default location, you would only need to symlink the script into /usr/lib/cgi-bin/ and add minimal Apache configuration:

1) ln -sf /path/to/scripts/preseed /usr/lib/cgi-bin/preseed.cfg

2) Before the end in /etc/apache2/sites-available/default, add:
    ScriptAlias /d-i/squeeze/ /usr/lib/cgi-bin/
    ScriptAlias /d-i/lenny/ /usr/lib/cgi-bin/
3) /etc/init.d/apache2 reload

The url= option of the debian installer also allows specifying full path, so if you've got the script at some other place, you can always specifically do url=http://ip.ad.dr.ess/path/to/preseed.cgi.

Notes from the preseed script

(This is the top of file with comments, if you want the whole source file, see scripts/preseed).

#!/usr/bin/perl
#
# SPINLOCK - Advanced GNU/Linux networks for commercial and education sectors.
#
# Copyright 2008-2009 SPINLOCK d.o.o., http://www.spinlocksolutions.com/
#                     Davor Ocelic, docelic@spinlocksolutions.com
#
# License: GPL v3 or later.
#
# The script runs as cgi, and:
#
# 1) takes any of the following optional CGI args in GET query string:
#
#  OPTION:          EXAMPLE:
#
#  ip=IP            ip=10.0.1.8
#  host=HOSTNAME    host=h2
#  client=CLI_NAME  client=c1.com (corresponds to o=c1.com,ou=clients in LDAP)
#  debug=0/1        debug=1
#  flag=FLAG        flag=preseed
#
# 2) finds LDAP entry for the specified host (based on IP or host+client)
#
# 3) prints out its preseed file
#
#
# NOTES ON CGI ARGUMENTS:
#
# If no arguments are specified, host/domain is autodiscovered based on
# requestor IP, which is how this CGI should be used in regular operation.
# This implies that the host entry must already exist in LDAP and have
# the appropriate dhcpHWAddress and ipHostNumber.
#
# It is intended that every client has its own non-overlapping private subnet,
# and that a search for an IP in the directory returns a single result.
# But if you have multiple clients with same subnet & IPs so that IP-based
# search would return multiple results, manually specify client when
# specifying preseed file, i.e. url=http://srv/preseed.cfg?client=CLIENTNAME
#
# NOTES ON SCRIPT BEHAVIOR:
#
# First, the script expects that it will be searching for entries in
# subtrees that conforms to Debconf LDAP structure (entries with objectClass
# debconfDbEntry).
#
# Second, the script looks for config and template data in three places each
# (in order: host-specific level, site-default level, global-default level). 
#
# Third, it is considered good practice not to preseed with all keys, but only
# those relevant for installation. So of all keys found, only those with the
# preseed flag set will be included in preseed file output. (see flag= above).
#
# Fourth, keys on the host-specific level are retrieved in one go (a search
# is made at the top of the tree and returns all first-level keys at once).
# Keys on other levels are also retrieved in one go (per level), but are not
# immediately added to the data set. Instead, only their names are recorded,
# and then those keys are individually retrieved by performing a specific
# lookup on cn=KEY_NAME,... *under the host-specific tree*. This of course
# requires that the LDAP server is configured to look in exactly the same
# place for defaults as is expected by this script, and ensures that even if
# a value comes from a default entry, it is subject to all parsing, expanding
# etc. as defined by client-specific tree (ou=clients or o=CLI.com,ou=clients,
# and not ou=defaults).
#
# OTHER NOTES:
#
# The script includes consistency checks -- at the end of preseed file
# output, it prints the list of keys which have a config value but no template
# (or vice versa).
# That output is prefixed with "BAD:" and, if it occurs, will break the
# preseed file format. Under normal circumstances this should never happen, so
# you shouldn't worry. But if it does happen, then those BAD: lines
# are printed unconditionally to draw your attention (even with debug=0).
#
# Under debug=1, it also prints an informational list, prefixed "INFO:", 
# with the list of keys that existed, but didn't match the flag.
#

Debugging

  1. Monitor tail -f /var/log/apache2/*log to see there are not Apache-related errors
  2. Use wget or graphical web browser to retrieve the preseed file, make sure you see at least something (not File not found)
  3. Specify IP and debug mode manually in the call to the preseed script, i.e. http://server/cgi-bin/preseed?debug=1&ip=10.0.1.8
  4. Monitor slapd log (in debug level -d 256), look at searches requested and their return values
  5. Repeat searches reported by slapd manually using ldapsearch and equivalent search params, see if data from LDAP comes out as you expect