Install for UMLazi v1.0

  1. Edit the Makefile
  2. Build and install the package
  3. Configure a new UMLazi Guest
  4. Install Supplemental Files
  5. Create and Start the UMLazi Guest

Step 1 - Edit the Makefile

If desired, edit the Makefile and change DATADIR and PREFIX to your site's preferred installation directories. (/opt, /usr/local, whatever)

##
## James's preferred directory locations
##
PREFIX := /pkgs/umlazi/1.0
DATADIR := /data/umlazi
BINDIR := $(PREFIX)/bin
LIBDIR := $(PREFIX)/lib
CFGDIR := $(DATADIR)/cfgs
TEMPLATEDIR := $(DATADIR)/templates
KERNELDIR := $(DATADIR)/kernels

PREFIX is where static binaries/scripts go.  This directory may be distributed to all your UMLazi hosts without fear of local configuration data seeping in.

DATADIR contains host-specific data such as Guest configuration, guest jail directories, and logs.

Step 2 - Build and install the package

$ make
$ make install

Check $(PREFIX)/lib/lib_config to verify the paths are correct.

Step 3 - Install supplemental files

Install one or more UML kernels in $(KERNELDIR). Make a symlink named "default" to the one you want UMLs to boot with by default. To specify which kernel a specific UML uses to boot, put it's filename in a file named "kernel_version" in the guest's configuration directory.

Put one or more filesystem template directories in $(TEMPLATEDIR).A filesystem template directory should contain a file named "filesystem.tar.bz2" which contains a UNIX directory structure anchored at "/". At least one template should contain an actual Linux distribution, such as Debian or RedHat.

Step 4 - Configure a new UMLazi Guest

UMLazi uses a "configuration directory" structure. Configuration options are split  into individual files (rather  than stuffing them all  into a properly formatted  text file). This  makes it  easy to script  edits to UMLazi configurations; rather than write a script which searches through a text file and  replaces a chunk of text, all you  need do is overwrite the value stored in on of these files.

A template configuration directory will be put in $DATADIR/cfgs/

    TEMPLATE/hostname - The hostname of the Guest (from the perspective of the guest).  Used by UMLconfig to set the hostname.

    TEMPLATE/user - The UNIX username this user should run as. (If the user doesn't exist, UMLazi will create it. It's recommended that you allow UMLazi to create the user, rather than doing it yourself.)

    TEMPLATE/group - The UNIX group this user should run as.

    TEMPLATE/uml_dir - The home dir for this guest.  Usually "$(DATADIR)/systems/UMLNAME"

    TEMPLATE/mem - The amount of memory assigned to this Guest. (e.g. "32M").

    TEMPLATE/kerneloptions - Any additional kerneloptions to be passed to the UML kernel.

    TEMPLATE/enabled - A boolean value (1 or 0) specifying whether or not this guest should be started automatically on system bootup.

    TEMPLATE/templates - A list of filesystem templates which should be applied when this UML is created.

The templates listed in the "templates" file should match the names of directories in the $(TEMPLATEDIR) listed in your lib_config file. Each directory should contain a file named "filesystem.tar.bz2". When the UML is created, the filesystem.tar.bz2's for each template listed will be uncompressed into the root directory of the UML's blank UBD devices.

    TEMPLATE/root_password - This is used by UMLconfig to set the root password in the guest.

    TEMPLATE/dns - This directory is used by UMLconfig to configure DNS settings inside the guest.

    TEMPLATE/dns/nameservers - The IP addresses of your nameservers, one per line.

    TEMPLATE/dns/domain - Your domain name.

    TEMPLATE/dns/search - Your domain name search path.

    TEMPLATE/interfaces - This directory defines network interfaces for the Guest.  This is used by UMLazi to set up the
        appropriate host-side networking, and by UMLconfig to configure the guest's network interfaces.

    TEMPLATE/interfaces/eth0 - This directory defines network interface "eth0" (from the Guest perspective).  UMLazi currently supports TUNTAP and bridged interfaces.

Example of an interface using TUNTAP ( ".../type:tuntap" indicates that the file "type" contains the line "tuntap"):

    TEMPLATE/interfaces/eth0/type:tuntap
    TEMPLATE/interfaces/eth0/tundev:testuml
    TEMPLATE/interfaces/eth0/tunip:192.168.1.5
    TEMPLATE/interfaces/eth0/address:192.168.1.1
    TEMPLATE/interfaces/eth0/netmask:255.255.255.0

Example of an interface using Bridging:

    TEMPLATE/interfaces/eth0/type:bridge
    TEMPLATE/interfaces/eth0/tundev:testuml
    TEMPLATE/interfaces/eth0/bridge:breth0
    TEMPLATE/interfaces/eth0/netmask:255.255.255.0
    TEMPLATE/interfaces/eth0/address:10.170.32.12
    TEMPLATE/interfaces/eth0/gateway:10.170.32.1

If the bridge interface listed in "bridge" doesn't exist, it will be created and joined, otherwise it will just be joined.

    TEMPLATE/volumes - This directory defines block devices (disks) for the guest.

    TEMPLATE/volumes/ubd0 - This directory defines the block device "ubd0" (from the Guest perspective).  "type" is the filesystem type and can be any filesystem both your host and guest support -OR- it can be "umlconfig" to specify that it's a "umlconfig" configuration device.

Example of an XFS root device:

    TEMPLATE/volumes/ubd0/size:2G
    TEMPLATE/volumes/ubd0/type:xfs
    TEMPLATE/volumes/ubd0/mount_point:/
    TEMPLATE/volumes/ubd0/device:/dev/ubd/0
    TEMPLATE/volumes/ubd0/options:defaults
    TEMPLATE/volumes/ubd0/pass:0
    TEMPLATE/volumes/ubd0/dump:0

Example of a UMLconfig device:

    TEMPLATE/volumes/ubd4/type:umlconfig
    TEMPLATE/volumes/ubd4/device:/dev/ubd/4

UMLconfig is a collection of shell scripts installed into a UML guest if its filesystem template is specified in the "templates" file. It's used to pass essential UMLazi configuration variables into the guest, such as the root password, and networking information.

If a umlconfig block device is specified, then when the guest is started up, its UMLazi configuration directory is stored as a tarball in the device specified. The umlconfig scripts then untar the directory structure in /var/umlconfig, and do various things with the data therein.

Step 5 - Create and Start the UMLazi Guest

Due to the nature of these commands (setting ownerships, chrooting, etc), they must be run as root:

    # $(PREFIX)/bin/umlazi create GUESTNAME
    # $(PREFIX)/bin/umlazi start GUESTNAME

At this point, you should be able to attach to the console of the guest:

    # $(PREFIX)/bin/umlazi attach GUESTNAME

If this doesn't work, then look at the "console.log" file in thedirectory listed in uml_dir to see what went wrong.