Virt-Factory

< name="toc">

Virt-Factory Installation & Setup Guide

Table of Contents

About this Document

This document explains how to install and set up a basic installation of Virt-Factory.

Back to top

Before You Start: Requirements

For the Virt-Factory Management Server:

Currently you will need a system running Fedora 7 to most easily install and setup an Virt-Factory management server.

You may also install an Virt-Factory management server using our source tarballs or our git code respository.

You will also need access to one of the Fedora 7 public rsync mirrors or a DVD ISO of Fedora 7 to enable the server to provision new guest systems.

For systems registering to the Virt-Factory Management Server:

You will want at least one additional system to register to the Virt-Factory management server. Using virt-factory to install guests on the same machine is possible, however.

Back to top

Getting the RPMs

Prebuilt RPMs are available for Fedora 7 for both x86 and x86_64. You may configure your system to use this repository by running the following command:

wget http://virt-factory.et.redhat.com/download/repo/virt-factory.repo --output-document=/etc/yum.repos.d/virt-factory.repo

We will install specific packages from this repository in the steps that follow.

Back to top

Installing the Management Server

Installing the Management Server Package

Run the following command on the system you would like to setup as an Virt-Factory management server:

yum install virt-factory-server

Configuring the Database

Virt-Factory uses PostgreSQL for it's database.

If you are not already using any PostgreSQL databases on the server, run the following command to set up the database to allow connections by the virt factory user:

vf_fix_db_auth

If the server already has a PostgreSQL installation that other applications are relying upon, do not run the above command, but instead manually change the server's pg_hba.conf file to allow "md5" authentication for all "host" connections, then restart the Postgresql service with:

/sbin/service postgresql restart

Setting Up Mirrors For Virtual Guest Deployment

As root, edit the /etc/virt-factory/settings file to include the address of a public rsync mirror for Fedora 7, or otherwise change the path to point to where you have a DVD or the DVD ISO mounted. This path settings will allow Virt-Factory to import a distribution mirror for use in installing virtual systems.

Note: A list of current public mirrors of Fedora 7, including rsync mirrors, is available here: http://mirrors.fedoraproject.org/publiclist/Fedora/7/.

We recommend that you import Fedora 7 as this is the operating system we provide pre-built profiles for. If you import something else, you will need to create a profile for it before you can deploy a virtual guest using it.

Tip: You might find the following redhat.com Knowledgebase article helpful in mounting a Fedora DVD ISO: Article #4633 - How do I view the contents of a .iso file?

Configuring Management Server IP Address

In /etc/virt-factory/settings, you should also configure the server address ("this_server") at this time. Do not leave it as 127.0.0.1 - replace that value with your server's IP address.

Starting Management Server Services

Now we're ready to start the puppetmaster and qpidd services:

sudo /sbin/service puppetmaster start
sudo /sbin/service qpidd start

You will probably also want to change the parameters for the puppetmaster, qpidd, apache, and virt-factory services so they start automatically when the system starts.

Tip: You might find the following redhat.com Knowledgebase article helpful in configuring these services for automatic startup on boot: Article #4407 - What is an initscript service and how do I start and stop it?

Now, start the virt-factory service:

sudo vf_server import

Tip: The import operation will take a while for the rsync to complete.

Finally, make sure ntpd is running on your server. This service is required for system provisioning, as the kickstarts use ntpdate to perform an initial time sync for provisioned systems.

Importing Profiles

Now you'll want to import some profiles to deploy to machines. To do this, you'll first of course need to find some profile files. We have some samples profiles available at: http://virt-factory.et.redhat.com/download/profiles.

We recommend that you download all of our sample profiles for starters. You can make your own profiles later if you want. For each profile you wish to deploy, run:

sudo rpm -Uvh /path/to/profile.noarch.rpm

Then after installing each profile RPM, run:

sudo vf_import

Set Up the Virt-Factory Management Server Web Interface

You'll need to install and start the web interface on the Virt-Factory management server using the following commands:

sudo yum install virt-factory-wui
sudo /sbin/service virt-factory-wui start

You will be able to access the web interface by visiting http://www.example.com/vf/, where www.example.com is your server's actual IP address or domain name.

Tip: You may also wish to configure the web interface to start automatically on reboot.

Alternatively, you can also install the web interface on a different machine than the one running the virt factory XMLRPC server. If the WUI is installed on a different box, edit /etc/sysconfig/virt-factory-wui/server to point to the XMLRPC server's hostname (rather than the default 127.0.0.1)

Management Server Security Configuration

Firewall

If you're running iptables you will need to open up access to the ports required for HTTP/HTTPS, the xmlrpc ports for virt-factory-server and cobbler, and the puppetmaster port. /usr/bin/vf_config_firewall will open up these ports, although without any local host-specific restrictions.

SELinux

SELinux needs to grant some permissions so that apache can connect to the Mongrel server, which we use to power the web interface, so run the following as root:

setsebool httpd_can_network_connect true

Back to top

Logging In

The default username and password for the Virt-Factory Management Server web interface are the following:

  • Username: admin
  • Password: fedora

You'll want to change this in the user options after you log into the web interface. (Later we may support fancier authentication schemes.)

Back to top

Registering Virtual Host Systems to the Server

You'll want to add some systems that can serve as virtual hosts. Consider these machines part of your "machine farm". There are two ways to do this, all of which should be available in the fairly minimalistic web interface.

Registering Virtual Host Systems via PXE Provisioning

The easiest way to register a physical host system to the Virt-Factory management server is to use the "add a machine for PXE" item in the web interface. Type in a MAC address in the web form, and select a profile for the system to run after it PXE boots. Most likely, you'll want to pick the "Container" profile (available from our download page), because that profile means "This machine is going to run managed virtual guests". In fact, when assigning profiles to machines, always pick the "Container" profile. It will keep things simple. Once Virt-Factory is installed you can also use koan to reinstall any existing system you have to run a particular virt-factory profile. Use the --list-profiles option to browse the profiles that are available remotely and choose the Container profile.

To make PXE work, your dhcp server will need to specify that the address of the virt-factory management server is the "next-server" for that particular machine.

Registering Virtual Host Systems using a Registration Token on an pre-installed System

If you do not have access to your dhcp server to setup PXE, another option you have for registering host (bare-metal) systems is the registration tool (vf_register). Installing vf_register first requires installing client software. The target system must be running one of the operating systems required for an Virt-Factory registered system. Also, you'll need to make sure that the system is running a xen kernel so you may deploy virtual guest system on it.

To check if your system is running a xen kernel, run uname -a. In the output of that command, check to make sure the kernel has the string 'xen' in it. If not, you'll need to reboot the system into a xen kernel before attempting to provision guests on it. Alternatively, you can choose to use KVM -- in this case, don't run the Xen kernel, but install kvm, and qemu. In either case you will also need python-virtinst.

Then run the following commands, using one of the already imported profile names:

yum install virt-factory-nodes
vf_register --serverurl=http://www.example.com --profile=Container
/sbin/service start virt-factory-node-server

Now that system show up as managed in the Virt-Factory management server web interface. You are now ready (assuming you just configured it as a "Container" machine, to deploy virtualized systems running specific profiles.

NOTE: If you are intending for the system to host virtual instances, you should run vf_register with the additional flag "--allow-bridge-config" or set up a virtual network bridge yourself, as alluded to in the manpage for "koan". It's much easier if you let vf_register do it for you, and for PXE configurations (bare metal installs) this is the default. For bare-metal appliances this is not needed, nor is it currently needed for Xen virtualization types because xend creates it's own bridge. qemu/KVM does not.

Back to top

Viewing Imported Profiles

Click on the "Profiles" item in the web interface navbar and then choose the option to list profiles. Here you will see all of the various profiles you've imported that are available for deploying systems. You should already see the container profile you have used earlier, plus some additional ones. If you write your own, or download them from others, you can run vf_import on the management server as listed above to see them appear here.

Back to top

Deploying and Managing Virtual Guest Systems

Under the "Deployments" item in the web interface navbar, choose the "Add" item. Pick a system to host the virtual guest and choose which profile you would like to deploy onto the guest. The guest system will begin installing and will appear in the "creating" state until its installation is finished.

Go back to the deployment list and you can verify the system's state is shown to be in the "creating" state. An install from a local mirror will probably take 10-30 minutes approximately, depending on the profile used and machine/network speeds.

When finished, the guest will be listed as being in the "created" state.

Once an install is complete, you can click the "edit" link in the list tab to perform basic virtual system management operations on the deployment. You can pause and unpause the machine, start it, and shut it down.

Note: Virtual machine migrations aren't yet supported, but they will be in a future release.

Back to top

Creating Profiles

We have made some sample profiles available on our download page.

You may wish to refer to the Virt-Factory Profile Format documentation (note: this documentation needs an update). Follow the same format (XML file + puppet files and manifests) to create your own profiles for how your servers should run and be set up. Our Test1 profile is as minimalistic as it gets, and it's possible to create much more tailored profiles, including ones that set up web servers, application servers, and so forth - and keep them configured - using puppet.

Back to top

Upgrading the Database and Schema

Schema upgrades are supported. To upgrade between versions of virt-factory, just install the new version and restart virt-factory-server.

Back to top

Additional Notes

If you have corrections or clarifications for this page, please share them with et-mgmt-tools@redhat.com or #virt-factory on irc.freenode.net.

Back to top