Installation Instructions

This document is intended to help get oVirt quickly up and running using the released oVirt server RPMs and a two-machine, two-network setup.

Throughout this document, we give commands to type at a shell prompt. By convention, if a command is meant to be run by a non-privileged user, we will preface it with sudo.

Installing oVirt server from RPMS

Hardware and connectivity requirements

A test or production oVirt setup requires:

One or more machines to serve as managed nodes. These machines must have hardware virtualization capability and a minimum of two network interface cards. "Hardware virtualization" means a processor with either Intel VT or AMD AMD-V is required to run VMs on an oVirt node.
One machine to run the oVirt server (the "admin node"). This machine must have a minimum of two network cards, but it need not have hardware virtualization capability. However there are some advantages to running the server itself in a VM, in which case hardware virtualization on the server machine would be required.
One machine to act as a storage server (this can be the same as the oVirt server machine if necessary). The storage server configuration is up to the user. oVirt managed nodes can access NFS and iSCSI storage.
A hub or switch to connect the managed nodes, the admin node, and the storage server together on a private network (the "admin" network). The admin node provides all necessary network configuration services (dns, dhcp, etc.) for the admin network.
Network connectivity from the managed nodes and the admin node to an external network, the network you would like oVirt-managed guests to be able to access (we call this the "guest" network).

For a better understanding of the oVirt physical architecture and network requirements, see the architecture diagrams.

Note: It is possible to set up oVirt to run the oVirt server and a few VMs on a single machine. However this is tricky in practice and we recommend it only for developers with a lot of networking experience. For more information see the developer installation guide.

Software requirements

Fedora 10 or later: installed with latest updates on your server machine or VM.
ovirt-server, ovirt-server-installer, ovirt-node-image, and ovirt-node-image-pxe RPMs. These are available from the oVirt yum repository; installation instructions are below.
If you want to run the oVirt server in a VM, virt-manager makes it easy to install and manage a VM on a single machine.

Server machine configuration

Warning: the oVirt server installer makes significant changes to important files on your server machine, including your krb5.conf, resolv.conf, hostname, /etc/hosts, and network configuration (this is all necessary to make Kerberos work properly on the admin network). Especially if your server machine is already running in a kerberized environment, we strongly encourage you to set up a VM on that machine to run the server in; it can be annoying to recover a preexisting machine with a bad install.
As described above, the machine you intend to run the oVirt server on must have two nics, one of which should be connected to your LAN; the other should be connected to your oVirt node(s), forming your admin network.
If you will be installing the server on bare metal, you will want the LAN-connected NIC configured as usual (DHCP or static depending on your network configuration). The admin NIC must be set up with a static configuration. Example /etc/sysconfig/network-scripts/ files are below.
Public/guest network (assuming eth0, change to match your configuration)
/etc/sysconfig/network-scripts/ifcfg-eth0:
```
DEVICE=eth0
BOOTPROTO=dhcp
ONBOOT=yes
HWADDR=<your mac address here>
```
Admin network (assuming eth1, change to match your configuration)
/etc/sysconfig/network-scripts/ifcfg-eth1:
```
DEVICE=eth1
BOOTPROTO=static
ONBOOT=yes
PEERNTP=yes
IPADDR=192.168.50.1
NETMASK=255.255.255.0
HWADDR=<your mac address here>
```
The IPADDR here is arbitrary, any private IP range will do.
If you will be installing the server in a VM, you will need to set up bridges for both of these NICs so that the VM can access them. Example config files are below.
Public/guest network (assuming eth0, change to match your configuration)
/etc/sysconfig/network-scripts/ifcfg-eth0:
```
DEVICE=eth0
ONBOOT=yes
BRIDGE=breth0
```
/etc/sysconfig/network-scripts/ifcfg-breth0:
```
DEVICE=breth0
BOOTPROTO=dhcp
ONBOOT=yes
TYPE=Bridge
```
Admin network (assuming eth1, change to match your configuration)
/etc/sysconfig/network-scripts/ifcfg-eth1:
```
DEVICE=eth1
ONBOOT=yes
BRIDGE=breth1
```
/etc/sysconfig/network-scripts/ifcfg-breth1:
```
DEVICE=breth1
BOOTPROTO=none
ONBOOT=yes
TYPE=Bridge
PEERNTP=yes
```
Again, if you are installing the server in a VM (you can do this easily using virt-manager), create the VM with two NICs that are connected to the two bridges above, then configure the networking in the VM as described for the bare-metal case.

Getting oVirt RPMs

oVirt RPMs are provided in a yum repository hosted on the oVirt website. To access them from your Fedora 10 machine:

Install the ovirt-release RPM to get yum configured.

sudo rpm -ivh http://ovirt.org/repos/ovirt/ovirt-release-LATEST.noarch.rpm

Update any existing RPMs with newer RPMs available in the oVirt repository
```
sudo yum update --enablerepo=ovirt
```

Install additional RPMs from the oVirt repository

sudo yum install --enablerepo=ovirt ovirt-server ovirt-server-installer \
ovirt-node-image ovirt-node-image-pxe

The oVirt installer

The oVirt installer installs all the infrastructure the oVirt server needs to work. For production installs some of this infrastructure (DNS, DHCP, kerberos) may already exist; in that case the installer has options for not installing these services. For blank slate oVirt setups, the installer will install and configure everything the server needs to work. This includes:

FreeIPA LDAP and Kerberos, to manage and authenticate users, authenticate managed nodes, and secure communications with managed nodes
Dnsmasq, to provide DHCP, pxe, and DNS to managed nodes (fully functional DNS is required for FreeIPA's Kerberos authentication)
Qpid, the AMQP messaging and management framework, for communications between oVirt and managed nodes
Apache (if not already installed) with mod_nss, and the Ruby on Rails web application framework

Warning: To allow kerberos to work on the oVirt admin network, the installer must make some significant changes to your server machine. This includes changing the hostname, installing a local DNS/DHCP/PXE server, and modifying the following files:

/etc/hosts
/etc/resolv.conf
/etc/krb5.conf
/etc/httpd/conf/httpd.conf and other httpd config files

It is almost always better to run the oVirt server in a VM for this reason.

Running the oVirt installer

Run the oVirt install configurator. The install configurator collects information about your local environment to set up the oVirt installer correctly. Default values, when available, are surrounded by |pipes|. A sample install configurator session, with explanatory notes, is below:

[root@localhost ~]$ ovirt-installer
This installer will configure the ovirt installation based on a series
of questions. When complete, you will be asked to install oVirt or
do the installation manually. Would you like to continue? |y| y

SELinux must be set to permissive until support is finalized

SELinux enforcing, would you like to set it to permissive? |y| y
Setting SELinux permissive

Display detected networking devices. Here the installer will look for the active network devices on your machine. You should choose your local LAN for the "guest network" -- this is the network you will browse to the UI from (it is also probably the network you will connect your VMs to, although it doesn't have to be). You should choose the NIC that is connected directly to your node(s) for the "admin network" -- the server will use this network to control the oVirt nodes.

Below are the detected networking devices
mac address           interface        ip address
00:00:00:00:00:00   :   eth1    :    192.168.50.2
3e:f1:f4:2d:d6:93   :   virbr0    :    192.168.100.1
00:1b:77:02:85:25   :   eth0    :    192.168.1.197

Enter the interface for the Guest network: |eth0| eth0
 Enter the interface for the Admin network: |eth1| eth1

Set the hostname + domain name on your Admin network. This is what the nodes will communicate with, _not_ what will be seen from the Guest network. You should use a domain name that cannot be resolved outside the admin network.

Enter the hostname of the oVirt management server (example:
management.example.com): management.ovirt.priv

If you have an existing DNS server and wish to use it to provide DNS to your managed node, you will need to enter "y" below and configure it according to the documentation at XXX. If you do not have a DNS server on your network, enter "n" and we can provide one

The following DNS servers were found:
nameserver 172.16.52.28
nameserver 10.11.255.27

Use this systems's dns servers? n

DHCP Setup. Here you should choose the network you have already configured for your admin interface. In the example below, your oVirt server will have IP address 192.168.50.1 and will also function as the gateway, so any address within the subnet other than .1 is fair game for the DHCP pool. DHCP domain must match the FQDN you chose for the server hostname above. Note: If you have a DHCP/TFTP server on your admin network already, you can skip this step.

Does your Admin network already have dhcp? n
Enter the first 3 octets of the dhcp network you wish to use (example:  192.168.50): 192.168.50
Enter the dhcp pool start address (example: 3): 3
Enter the dhcp pool end addess (example: 100): 50
Enter the dhcp domain you wish to use (example: example.com): |localdomain| ovirt.priv 
Enter the network gateway for your Admin network (example:   192.168.50.254): 192.168.50.1
Provide pxe/tftp capability? y

Cobbler setup. Cobbler provides the PXE boot image for the oVirt nodes, and also manages ISO images to deploy as oVirt VMs. If you already have a Cobbler server on your admin network, you can skip this step.

Do you have a cobbler instance already that you wish to use? n
We will setup a cobbler instance, please provide the following information
Enter your cobbler username: cobbler
Enter your cobbler user password: ********

PostgreSQL setup. The installer automatically installs PostgreSQL and creates an oVirt db. Enter the password you want to use for the oVirt db below.

Enter a password for the ovirt postgres account: ********

Kerberos setup. The Kerberos realm you enter should probably match the FQDN you picked for the admin network.

Enter your realm name (example: example.com): ovirt.priv

NOTE: The following pasword will also be your ovirtadmin password
for the web management login # Enter an administrator password for
FreeIPA: ********

Run the ovirt installation. The command below will set up the various required oVirt services on your local machine. It will take several minutes. Even if it succeeds, it always exits with an error code of "1". Yes, this is a bug.

# ace -d -l <logfile> install ovirt

Post Install

Now that your server is up and running, you probably want to spin up some nodes, so you might want to set up an nfs mount. You can do this on the oVirt server, or on a different storage server. The easiest way to set up an NFS server on a Fedora system is to use system-config-nfs, making sure you select read/write. You will also need to make sure you have opened the correct ports on your server. oVirt also supports iSCSI storage; see the iSCSI setup page for setup instructions.
You will also want to add one or more profiles to cobbler, so you can install something on your new node. Assuming you have a Fedora install cd handy, do the following on your oVirt server:

# cobbler distro add --name F10-i386 --kernel=/tmp/isolinux/vmlinuz --initrd=/tmp/isolinux/initrd.img

Go to the https://<your-server>/cobbler/web page to add a repo. Add a name and the mirror location to the $installcd root directory (http/ftp are easiest if you can make it available by that). Uncheck mirror locally so we dont waste hours of importing. Click save.
Still in the cobbler web ui, add a profile - add a name, pick the distro to the one above, and go down and pick the repo we added.

Common Issues/Troubleshooting

Node Troubleshooting

If node shows 'unavailable(enabled)', but you know it is running, the best place to start is to run:

sudo ruby /usr/share/ovirt-server/qmf-libvirt-example.rb

This program lists all nodes, storage pools etc. on stdout every 5 seconds or so seperated by a set of dashes. If you see your node in there and it's still unavailable, then there is either something wrong with db-omatic or the time on your node is lagging behind.

You can try restarting the ovirt-db-omatic service and check the logs. If it never sees your node then chances are it's an authentication problem with kerberos (often time-skew related or maybe networking issues). Same with qmf-libvirt-example above. If db-omatic sees it, marks it available, and then unavailable again, then it may be caused by time skew on the node.

If you have access to the node (non-release builds), you can test the qpid connection to server:

service libvirt-qpid stop
export QPID_TRACE=1
libvirt-qpid --broker <hostname-of-server>

This will run libvirt-qpid normally (not as a daemon) and it will write some debug information to stdout. If this displays 'notice Initial object-id bank assigned: <some number>', then node is communicating successfully with the qpidd server.

Really there are a number of things that can go wrong:

Networking issues prevent node from communicating properly with server.
DNS configuration issues prevent getting DNS SRV records for various services.
DNS configuration issues cause kerberos authentication to fail.
Time skew causes kerberos authentication to fail.
Time skew causes timestamps from node sent to WUI to seem to be out of date and so get marked as unavailable (no recent keepalive).
Internal QPID/QMF issues prevent objects from showing up properly.

Accessing the Node

For developer builds, the root password is empty. You can log in as root from the console, but you will need to set a password for root to log in via ssh.
For production images, root password is disabled. To access the node:
- boot the Node image into single user by appending 1 or single to boot parameters (press TAB if booting from CD/USB, for PXE edit pxelinux.cfg or use cobbler system edit --kopts=)
- set the password for root by running passwd
- exit to continue boot.

Managing oVirt Nodes

Physical Nodes

If you have real physical hardware cabled up, you can boot up any physical hardware you have cabled to your private LAN. Make sure that your hardware is set to PXE boot first, otherwise it will boot to the normal operating system.