/ 
VUser-Install-0.1.0
River stage zero No dependents
/ VUser::Install

NAME

VUser::Install - vuser extension to manage netboot installs

REQUIRES

Text::Template

DESCRIPTION

Handles installs of new systems from netboot installs.

Diskless

Configures the DHCP server to give the new box a static IP address and sets up the root path and kernel options. Note: VUser::Install assumes that it is running on the DHCP server that the diskless box will boot off of.

If you need to partition a disk for scratch space or other things on the node, run the install-local script from the node.

Stand-alone

Packages a root tarball that can be unpackaged in / to install/upgrade a system. The included 'install-local' script can be run from the new system with the diskless setup.

The assumption here, is that you have a system root installed somewhere that can easily be packaged up after running a few scripts to change things based on IP address or host name.

install-local

This is an interactive script which is designed to run on a new server to make local changes to the server that cannot be done from the install server, e.g. partitioning disks.

Note: install-local currently tries to use sfdisk to partition drives. At some point, I hope to add disklabel support for systems that use that instead.

install-local requires that vsoapd is running on the installation server.

CONFIGURATION

[Extension_Install]
# Prototype roots are ${prototype dir}/$service
prototype dir = /prototypes

# Diskless roots are ${diskless dir}/$service/$ip
diskless dir = /diskless

# Directory to store server info used to write dhcp.conf
# The server file is called 'servers.dat'
data dir = /etc/vuser/

# Directory for VUser::Install service configs.
# Also, in this directory, templates for dhcp entries will be stored
# dhcp templates for a new host are used in this order:
# (Where $service, $mac and $ip are replaced with the values for this node)
#  $service-$mac.dhcp.tmpl
#  $service-$ip.dhcp.tmpl
#  $service.dhcp.tmpl
#
# The main dhcp.conf is dhcp.tmpl
config dir = /etc/vuser/install/

# DHCP settings
# dhcp config file
dhcp.conf = /etc/dhcp/dhcp.conf

# Command to run to restart dhcp
dhcp restart = /etc/init.d/dhcp restart

diskless node data file

IP|MAC|service|hostname|disk|kernel

Example data file:

192.168.1.100|00:0D:87:6A:4E:22|mail|mail1|hda|bzImage
192.168.1.101|00:0D:87:6A:4E:24|mail|mail2|hda|bzImage
192.168.2.100|00:0D:87:6A:4F:32|www|web1|sda|bzImage-smp
192.168.3.147|00:0D:87:6A:3F:27|desktop|desk47||bzImage

dhcp Templates

VUser::Install uses Text::Template to generate these files. Variables are inserted like so: << $foo >>.

See perldoc Text::Template for full details on the format of templates. The short version is that you can include any perl code between '<<' and '>>'. The return value (or the value of the $OUT variable) will replace the << >> block.

Node Template

These templates are used for idividual nodes. The following variables are available to the template:

$diskless

The path to the diskless tree (From Extention_Install::diskless dir

%server

The server information. See entry in "Global Template" for a list of keys. Note: The entry key does not exist here since this template is what's used to create that.

Below is a sample template.

host << $server{hostname} >> {
  hardware ethernet << $server{mac} >>;
  fixed-address << $server{ip} >>;
  filename "<< $server{service} >>/pxelinux.0";
  option root-path "<< $diskless >>/<< $server{service} >>/<< $server{ip} >>";
}

Global Template

The global template gives you these variables:

@entries

These are the already created templates for each node. For simple networks, this is the easiest way of put the get the entries into the config file.

<< join("\n", @entries); >>
$diskless

Path to diskless (from Extention_Install::diskless dir

%servers

If you have a more complex setup, you can use %servers to do all sorts of fun stuff. The keys of %servers are the IP addresses of the servers. The values are hash refs with the following keys:

ip

The host's IP address

mac

The host's MAC address.

hostname

The host's hostname.

service

The service for this host.

disk
kernel

The prefered kernel for this host.

entry

The filled out template for this host. This matches the entry for the host in @entries.

$warning

A simple warning message that says the file was generated by vuser and the time it was created. See the example below.

# This file was written by vuser on Mon Sep 12 16:44:22 2005
# DO NOT EDIT THIS FILE. Manual changes to this file will be lost.

Below is a sample template.

# option definitions common to all supported networks...
option domain-name "vuser.org";
option domain-name-servers 192.168.100.1, 192.168.100.2;

default-lease-time 600;
max-lease-time 7200;

# If this DHCP server is the official DHCP server for the local
# network, the authoritative directive should be uncommented.
authoritative;

# Use this to send dhcp log messages to a different log file (you also
# have to hack syslog.conf to complete the redirection).
log-facility local7;

ddns-update-style none;

subnet 192.168.1.0 netmask 255.255.255.0 {
  option subnet-mask 255.255.255.0;
  option broadcast-address 192.168.1.255;
  option routers 192.168.1.1;

  range 192.168.1.125 192.168.1.127;
  next-server 192.168.1.120;

# Server entries here 
<< join("\n", @entries); >>
}

Service configuration file

Note: service below, is the name of the service.

[service]
# Is a local disk required. (yes|no)
disk required = yes

# Partition instructions.
# The values are pipe delimited with these fields:
#  partition instructions
#  file system.
#  mount point
#
# ex:
#  disk1=,4096,S|swap
#  disk2=;|reiserfs
#
# disk1 creates a 4GB partion at the start of the disk and will be
# use for swap space.
# disk2 will use the rest of the disk for reiserfs
#
# The partion instructions look like sfdisk commands
# for a reason. (See sfdisk(8) dir details) Size units are MBs.
#
# If the file system is not specified, no file system will be created
# on the partition.
# Filesystem types are:
# (Note: You must have the appropriate tools in your install 
# setup or that filesystem will fail.)
#  swap
#  reiserfs
#  ext2
#  ext3
#  jfs
#  xfs
#
# The mount point is specified here so that it can be used as a reference
# point for the setup scripts to initialize them. For example, if you are
# installing an MTA (such as postfix) you may want to have a local disk
# for the spool. That spool will need to have certain directories created
# after the disk is partitioned and the filesystem is created. In the case
# of postfix, the directory /var/spool/postfix would need to be created.
# You may also want to use the local disk for scratch space for a virus
# scanner or other things and so those directories will need to be created
# as well.
#
# The mount point may be left empty for swap disks.
disk1=,4096,S|swap|
disk2=;|reiserfs|/var

# Location to put tarballs of standalone systems for download
tarball dir=/tarballs

# Given $service and $ip, what is the base URL of the tarball
#tarball base url=http://download.example.com/tarballs/$service/
tarball base url=http://download.example.com/tarballs/

# Given $service and $ip, what is the name of the tarball
#tarball file=$service-default.tgz
tarball file=$service-$ip.tgz

FILE LAYOUTS

Prototypes

/prototypes

/prototypes/service is the root directory for the service prototype.

/prototypes/service

Diskless

/diskless here is set by Extension_Install::diskless. service and ip are the service and node IP address, respectively.

/diskless
/diskless/service/

The pxelinux bootstrap is pxelinux.0 and the config files for it are in pxelinux.cfg.

/diskless/service/pxelinux.0
/diskless/service/pxelinux.cfg/

The available kernels for this service are saved in:

/diskless/service/kernels

init holds scripts and various other files for configuring a node.

/diskless/service/init

Each node's root directory is in:

/diskless/service/ip

INIT SCRIPTS

Executable files in /diskless/service/init are called when a new service is installed. These scripts must be able to be run again even if the service is already install. (This is primarily for upgrade functionality.)

VUser::Install will cd to /diskless/service/init before running any init scripts. Each script will be passed the following command line parameters:

diskless root

This is the root directory for the new install (/diskless/service/ip).

service

The name of the service (from the --service option)

hostname

The hostname for this install (from --hostname)

ip address

This install's IP (from --ip)

NFS server

The NFS server this host will use. (From VUser-Install.ini service::nfs server)

Prototype Root

The path to the prototype root (from Extension_Install::prototype dir and --service; e.g /prototypes/service)

ADDING USERS

If you use install-local, you will need to create users to allow it to connect. These users will are user by vuser's SOAP daemon vsoapd to allow access.

1) Enable the ACL extension in vuser.conf:

extensions = Install ACL

[ACL]
use internal auth=yes
auth modules=SQLite
# ALLOW or DENY
acl default=ALLOW

[ACL SQLite]
file=/etc/vuser/install/acl.db

Note: This setup requires that DBD::SQLite be installed on the master server, i.e. the box running vsoapd.

AUTHOR

Randy Smith <perlstalker@vuser.org>

LICENSE

This file is part of vuser.

vuser 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.

vuser 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 vuser; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA