VUser::Install - vuser extension to manage netboot installs




Handles installs of new systems from netboot installs.


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.


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.


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.


 # 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


Example data file:|00:0D:87:6A:4E:22|mail|mail1|hda|bzImage|00:0D:87:6A:4E:24|mail|mail2|hda|bzImage|00:0D:87:6A:4F:32|www|web1|sda|bzImage-smp|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:


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


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:


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); >>

Path to diskless (from Extention_Install::diskless dir


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:


The host's IP address


The host's MAC address.


The host's hostname.


The service for this host.


The prefered kernel for this host.


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


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 "";
 option domain-name-servers,;
 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.
 # 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 netmask {
   option subnet-mask;
   option broadcast-address;
   option routers;

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

Service configuration file

Note: service below, is the name of the 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.
 # 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=$service/
 tarball base url=
 # Given $service and $ip, what is the name of the tarball
 #tarball file=$service-default.tgz
 tarball file=$service-$ip.tgz




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



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


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


The available kernels for this service are saved in:


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


Each node's root directory is in:



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


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


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)


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
 use internal auth=yes
 auth modules=SQLite
 acl default=ALLOW
 [ACL SQLite]

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


Randy Smith <>


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