# Virtualization

Virtualization is being adopted in many different environments and situations. If you are a developer, virtualization can provide you with a contained environment where you can safely do almost any sort of development safe from messing up your main working environment. If you are a systems administrator, you can use virtualization to more easily separate your services and move them around based on demand.

The default virtualization technology supported in Ubuntu is KVM, a technology that takes advantage of virtualization extensions built into Intel and AMD hardware. For hardware without virtualization extensions Xen and Qemu are popular solutions.

## libvirt

The libvirt library is used to interface with different virtualization technologies. Before getting started with libvirt it is best to make sure your hardware supports the necessary virtualization extensions for KVM. Enter the following from a terminal prompt:

    kvm-ok

A message will be printed informing you if your CPU does or does not support hardware virtualization.

On most computer whose processor supports virtualization, it is necessary to activate an option in the BIOS to enable it.

### Virtual Networking

There are a few different ways to allow a virtual machine access to the external network. The default virtual network configuration is usermode networking, which uses the SLIRP protocol and traffic is NATed through the host interface to the outside network.

To enable external hosts to directly access services on virtual machines a bridge needs to be configured. This allows the virtual interfaces to connect to the outside network through the physical interface, making them appear as normal hosts to the rest of the network. For information on setting up a bridge see .

### Installation

To install the necessary packages, from a terminal prompt enter:

    sudo apt-get install kvm libvirt-bin

After installing libvirt-bin, the user used to manage virtual machines will need to be added to the libvirtd group. Doing so will grant the user access to the advanced networking options.

In a terminal enter:

    sudo adduser $USER libvirtd

If the user chosen is the current user, you will need to log out and back in for the new group membership to take effect.

You are now ready to install a Guest operating system. Installing a virtual machine follows the same process as installing the operating system directly on the hardware. You either need a way to automate the installation, or a keyboard and monitor will need to be attached to the physical machine.

In the case of virtual machines a Graphical User Interface (GUI) is analogous to using a physical keyboard and mouse. Instead of installing a GUI the virt-viewer application can be used to connect to a virtual machine's console using VNC. See for more information.

There are several ways to automate the Ubuntu installation process, for example using preseeds, kickstart, etc. Refer to the Ubuntu Installation Guide for details.

Yet another way to install an Ubuntu virtual machine is to use ubuntu-vm-builder. ubuntu-vm-builder allows you to setup advanced partitions, execute custom post-install scripts, etc. For details see

### virt-install

virt-install is part of the python-virtinst package. To install it, from a terminal prompt enter:

    sudo apt-get install python-virtinst

There are several options available when using virt-install. For example:

    sudo virt-install -n web_devel -r 256 -f web_devel.img \
    -s 4 -c jeos.iso --accelerate \
    --connect=qemu:///system --vnc \
    --noautoconsole -v

- -n web_devel: the name of the new virtual machine will be web_devel in this example.

- -r 256: specifies the amount of memory the virtual machine will use.

- -f web_devel.img: indicates the path to the virtual disk which can be a file, partition, or logical volume. In this example a file named `web_devel.img`.

- -s 4: the size of the virtual disk.

- -c jeos.iso: file to be used as a virtual CDROM. The file can be either an ISO file or the path to the host's CDROM device.

- --accelerate: enables the kernel's acceleration technologies.

- --vnc: exports the guest's virtual console using VNC.

- --noautoconsole: will not automatically connect to the virtual machine's console.

- -v: creates a fully virtualized guest.

After launching virt-install you can connect to the virtual machine's console either locally using a GUI or with the virt-viewer utility.

### virt-clone

The virt-clone application can be used to copy one virtual machine to another. For example:

    sudo virt-clone -o web_devel -n database_devel -f /path/to/database_devel.img --connect=qemu:///system

- -o: original virtual machine.

- -n: name of the new virtual machine.

- -f: path to the file, logical volume, or partition to be used by the new virtual machine.

- --connect: specifies which hypervisor to connect to.

Also, use -d or --debug option to help troubleshoot problems with virt-clone.

Replace web_devel and database_devel with appropriate virtual machine names.

### Virtual Machine Management

#### virsh

There are several utilities available to manage virtual machines and libvirt. The virsh utility can be used from the command line. Some examples:

- To list running virtual machines:

      virsh -c qemu:///system list

- To start a virtual machine:

      virsh -c qemu:///system start web_devel

- Similarly, to start a virtual machine at boot:

      virsh -c qemu:///system autostart web_devel

- Reboot a virtual machine with:

      virsh -c qemu:///system reboot web_devel

- The state of virtual machines can be saved to a file in order to be restored later. The following will save the virtual machine state into a file named according to the date:

      virsh -c qemu:///system save web_devel web_devel-022708.state

  Once saved the virtual machine will no longer be running.

- A saved virtual machine can be restored using:

      virsh -c qemu:///system restore web_devel-022708.state

- To shutdown a virtual machine do:

      virsh -c qemu:///system shutdown web_devel

- A CDROM device can be mounted in a virtual machine by entering:

      virsh -c qemu:///system attach-disk web_devel /dev/cdrom /media/cdrom

In the above examples replace web_devel with the appropriate virtual machine name, and `web_devel-022708.state` with a descriptive file name.

#### Virtual Machine Manager

The virt-manager package contains a graphical utility to manage local and remote virtual machines. To install virt-manager enter:

    sudo apt-get install virt-manager

Since virt-manager requires a Graphical User Interface (GUI) environment it is recommended to be installed on a workstation or test machine instead of a production server. To connect to the local libvirt service enter:

    virt-manager -c qemu:///system

You can connect to the libvirt service running on another host by entering the following in a terminal prompt:

    virt-manager -c qemu+ssh://virtnode1.mydomain.com/system

The above example assumes that SSH connectivity between the management system and virtnode1.mydomain.com has already been configured, and uses SSH keys for authentication. SSH keys are needed because libvirt sends the password prompt to another process. For details on configuring SSH see

### Virtual Machine Viewer

The virt-viewer application allows you to connect to a virtual machine's console. virt-viewer does require a Graphical User Interface (GUI) to interface with the virtual machine.

To install virt-viewer from a terminal enter:

    sudo apt-get install virt-viewer

Once a virtual machine is installed and running you can connect to the virtual machine's console by using:

    virt-viewer -c qemu:///system web_devel

Similar to virt-manager, virt-viewer can connect to a remote host using SSH with key authentication, as well:

    virt-viewer -c qemu+ssh://virtnode1.mydomain.com/system web_devel

Be sure to replace web_devel with the appropriate virtual machine name.

If configured to use a bridged network interface you can also setup SSH access to the virtual machine. See and for more details.

### Resources

- See the KVM home page for more details.

- For more information on libvirt see the libvirt home page

- The Virtual Machine Manager site has more information on virt-manager development.

- Also, stop by the #ubuntu-virt IRC channel on freenode to discuss virtualization technology in Ubuntu.

- Another good resource is the Ubuntu Wiki KVM page.

## JeOS and vmbuilder

### Introduction

#### What is JeOS

Ubuntu JeOS (pronounced "Juice") is an efficient variant of the Ubuntu Server operating system, configured specifically for virtual appliances. No longer available as a CD-ROM ISO for download, but only as an option either:

- While installing from the Server Edition ISO (pressing F4 on the first screen will allow you to pick "Minimal installation", which is the package selection equivalent to JeOS).

- Or to be built using Ubuntu's vmbuilder, which is described here.

JeOS is a specialized installation of Ubuntu Server Edition with a tuned kernel that only contains the base elements needed to run within a virtualized environment.

Ubuntu JeOS has been tuned to take advantage of key performance technologies in the latest virtualization products from VMware. This combination of reduced size and optimized performance ensures that Ubuntu JeOS Edition delivers a highly efficient use of server resources in large virtual deployments.

Without unnecessary drivers, and only the minimal required packages, ISVs can configure their supporting OS exactly as they require. They have the peace of mind that updates, whether for security or enhancement reasons, will be limited to the bare minimum of what is required in their specific environment. In turn, users deploying virtual appliances built on top of JeOS will have to go through fewer updates and therefore less maintenance than they would have had to with a standard full installation of a server.

#### What is vmbuilder

With vmbuilder, there is no need to download a JeOS ISO anymore. vmbuilder will fetch the various package and build a virtual machine tailored for your needs in about a minute. vmbuilder is a script that automates the process of creating a ready to use Linux based VM. The currently supported hypervisors are KVM and Xen.

You can pass command line options to add extra packages, remove packages, choose which version of Ubuntu, which mirror etc. On recent hardware with plenty of RAM, tmpdir in `/dev/shm` or using a tmpfs, and a local mirror, you can bootstrap a VM in less than a minute.

First introduced as a shell script in Ubuntu 8.04 LTS, ubuntu-vm-builder started with little emphasis as a hack to help developers test their new code in a virtual machine without having to restart from scratch each time. As a few Ubuntu administrators started to notice this script, a few of them went on improving it and adapting it for so many use case that Soren Hansen (the author of the script and Ubuntu virtualization specialist, not the golf player) decided to rewrite it from scratch for Intrepid as a python script with a few new design goals:

- Develop it so that it can be reused by other distributions.

- Use a plugin mechanisms for all virtualization interactions so that others can easily add logic for other virtualization environments.

- Provide an easy to maintain web interface as an option to the command line interface.

But the general principles and commands remain the same.

### Initial Setup

It is assumed that you have installed and configured libvirt and KVM locally on the machine you are using. For details on how to perform this, please refer to:

- The KVM Wiki page.

We also assume that you know how to use a text based text editor such as nano or vi. If you have not used any of them before, you can get an overview of the various text editors available by reading the PowerUsersTextEditors page. This tutorial has been done on KVM, but the general principle should remain on other virtualization technologies.

#### Install vmbuilder

The name of the package that we need to install is python-vm-builder. In a terminal prompt enter:

    sudo apt-get install python-vm-builder

If you are running Hardy, you can still perform most of this using the older version of the package named ubuntu-vm-builder, there are only a few changes to the syntax of the tool.

### Defining Your Virtual Machine

Defining a virtual machine with Ubuntu's vmbuilder is quite simple, but here are a few thing to consider:

- If you plan on shipping a virtual appliance, do not assume that the end-user will know how to extend disk size to fit their need, so either plan for a large virtual disk to allow for your appliance to grow, or explain fairly well in your documentation how to allocate more space. It might actually be a good idea to store data on some separate external storage.

- Given that RAM is much easier to allocate in a VM, RAM size should be set to whatever you think is a safe minimum for your appliance.

The vmbuilder command has 2 main parameters: the virtualization technology (hypervisor) and the targeted distribution. Optional parameters are quite numerous and can be found using the following command:

    vmbuilder --help

#### Base Parameters

As this example is based on KVM and Ubuntu &distro-rev; (&distro-version;), and we are likely to rebuild the same virtual machine multiple time, we'll invoke vmbuilder with the following first parameters:

    sudo vmbuilder kvm ubuntu --suite &distro-short-codename; --flavour virtual --arch i386  -o --libvirt qemu:///system

The --suite defines the Ubuntu release, the --flavour specifies that we want to use the virtual kernel (that's the one used to build a JeOS image), the --arch tells that we want to use a 32 bit machine, the -o tells vmbuilder to overwrite the previous version of the VM and the --libvirt tells to inform the local virtualization environment to add the resulting VM to the list of available machines.

Notes:

- Because of the nature of operations performed by vmbuilder, it needs to have root privilege, hence the use of sudo.

- If your virtual machine needs to use more than 3Gb of ram, you should build a 64 bit machine (--arch amd64).

- Until Ubuntu 8.10, the virtual kernel was only built for 32 bit architecture, so if you want to define an amd64 machine on Hardy, you should use --flavour server instead.

#### JeOS Installation Parameters

##### JeOS Networking

###### Assigning a fixed IP address

As a virtual appliance that may be deployed on various very different networks, it is very difficult to know what the actual network will look like. In order to simplify configuration, it is a good idea to take an approach similar to what network hardware vendors usually do, namely assigning an initial fixed IP address to the appliance in a private class network that you will provide in your documentation. An address in the range 192.168.0.0/255 is usually a good choice.

To do this we'll use the following parameters:

- --ip ADDRESS: IP address in dotted form (defaults to dhcp if not specified)

- --mask VALUE: IP mask in dotted form (default: 255.255.255.0)

- --net VALUE: IP net address (default: X.X.X.0)

- --bcast VALUE: IP broadcast (default: X.X.X.255)

- --gw ADDRESS: Gateway address (default: X.X.X.1)

- --dns ADDRESS: Name server address (default: X.X.X.1)

We assume for now that default values are good enough, so the resulting invocation becomes:

    sudo vmbuilder kvm ubuntu --suite &distro-short-codename; --flavour virtual --arch i386 -o --libvirt qemu:///system --ip 192.168.0.100

###### Modifying the libvirt Template to use Bridging

Because our appliance will be likely to need to be accessed by remote hosts, we need to configure libvirt so that the appliance uses bridge networking. To do this we use vmbuilder template mechanism to modify the default one.

In our working directory we create the template hierarchy and copy the default template:

    mkdir -p VMBuilder/plugins/libvirt/templates
    cp /etc/vmbuilder/libvirt/* VMBuilder/plugins/libvirt/templates/

We can then edit `VMBuilder/plugins/libvirt/templates/libvirtxml.tmpl` to change:

              <interface type='network'>
                <source network='default'/>
              </interface>

To:

              <interface type='bridge'>
                <source bridge='br0'/>
              </interface>

##### Partitioning

Partitioning of the virtual appliance will have to take into consideration what you are planning to do with is. Because most appliances want to have a separate storage for data, having a separate `/var` would make sense.

In order to do this vmbuilder provides us with --part:

    --part PATH
      Allows you to specify a partition table in a partition file, located at PATH. Each line of the partition file should specify
      (root first):
          mountpoint size
      where  size  is  in megabytes. You can have up to 4 virtual disks, a new disk starts on a
      line with ’---’.  ie :
          root 1000
          /opt 1000
          swap 256
          ---
          /var 2000
          /log 1500

In our case we will define a text file name `vmbuilder.partition` which will contain the following:

    root 8000
    swap 4000
    ---
    /var 20000

Note that as we are using virtual disk images, the actual sizes that we put here are maximum sizes for these volumes.

Our command line now looks like:

    sudo vmbuilder kvm ubuntu --suite &distro-short-codename; --flavour virtual --arch i386 \
             -o --libvirt qemu:///system --ip 192.168.0.100 --part vmbuilder.partition

Using a "\" in a command will allow long command strings to wrap to the next line.

##### User and Password

Again setting up a virtual appliance, you will need to provide a default user and password that is generic so that you can include it in your documentation. We will see later on in this tutorial how we will provide some security by defining a script that will be run the first time a user actually logs in the appliance, that will, among other things, ask him to change his password. In this example I will use 'user' as my user name, and 'default' as the password.

To do this we use the following optional parameters:

- --user USERNAME: Sets the name of the user to be added. Default: ubuntu.

- --name FULLNAME: Sets the full name of the user to be added. Default: Ubuntu.

- --pass PASSWORD: Sets the password for the user. Default: ubuntu.

Our resulting command line becomes:

    sudo vmbuilder kvm ubuntu --suite &distro-short-codename; --flavour virtual --arch i386 \
             -o --libvirt qemu:///system --ip 192.168.0.100 --part vmbuilder.partition \
             --user user --name user --pass default

#### Installing Required Packages

In this example we will be installing a package (Limesurvey) that accesses a MySQL database and has a web interface. We will therefore require our OS to provide us with:

- Apache

- PHP

- MySQL

- OpenSSH Server

- Limesurvey (as an example application that we have packaged)

This is done using vmbuilder by specifying the --addpkg option multiple times:

    --addpkg PKG
      Install PKG into the guest (can be specfied multiple times)

However, due to the way vmbuilder operates, packages that have to ask questions to the user during the post install phase are not supported and should instead be installed while interactivity can occur. This is the case of Limesurvey, which we will have to install later, once the user logs in.

Other packages that ask simple debconf question, such as mysql-server asking to set a password, the package can be installed immediately, but we will have to reconfigure it the first time the user logs in.

If some packages that we need to install are not in main, we need to enable the additional repositories using --comp and --ppa:

    --components COMP1,COMP2,...,COMPN
               A comma separated list of distro components to include (e.g. main,universe). This defaults
               to "main"
    --ppa=PPA  Add ppa belonging to PPA to the vm's sources.list.

Limesurvey not being part of the archive at the moment, we'll specify it's PPA (personal package archive) address so that it is added to the VM `/etc/apt/source.list`, so we add the following options to the command line:

    --addpkg apache2 --addpkg apache2-mpm-prefork --addpkg apache2-utils --addpkg apache2.2-common \
             --addpkg dbconfig-common --addpkg libapache2-mod-php5 --addpkg mysql-client --addpkg php5-cli \
             --addpkg php5-gd --addpkg php5-ldap --addpkg php5-mysql --addpkg wwwconfig-common \
             --addpkg mysql-server --ppa nijaba

##### OpenSSH

Another convenient tool that we want to have on our appliance is OpenSSH, as it will allow our admins to access the appliance remotely. However, pushing in the wild an appliance with a pre-installed OpenSSH server is a big security risk as all these server will share the same secret key, making it very easy for hackers to target our appliance with all the tools they need to crack it open in a breeze. As for the user password, we will instead rely on a script that will install OpenSSH the first time a user logs in so that the key generated will be different for each appliance. For this we'll use a --firstboot script, as it does not need any user interaction.

#### Speed Considerations

##### Package Caching

When vmbuilder creates builds your system, it has to go fetch each one of the packages that composes it over the network to one of the official repositories, which, depending on your internet connection speed and the load of the mirror, can have a big impact on the actual build time. In order to reduce this, it is recommended to either have a local repository (which can be created using apt-mirror) or using a caching proxy such as apt-proxy. The later option being much simpler to implement and requiring less disk space, it is the one we will pick in this tutorial. To install it, simply type:

    sudo apt-get install apt-proxy

Once this is complete, your (empty) proxy is ready for use on http://mirroraddress:9999 and will find ubuntu repository under /ubuntu. For vmbuilder to use it, we'll have to use the --mirror option:

    --mirror=URL  Use Ubuntu mirror at URL instead of the default, which
                  is http://archive.ubuntu.com/ubuntu for official
                  arches and http://ports.ubuntu.com/ubuntu-ports
                  otherwise

So we add to the command line:

    --mirror http://mirroraddress:9999/ubuntu

The mirror address specified here will also be used in the `/etc/apt/sources.list` of the newly created guest, so it is useful to specify here an address that can be resolved by the guest or to plan on reseting this address later on, such as in a --firstboot script.

##### Install a Local Mirror

If we are in a larger environment, it may make sense to setup a local mirror of the Ubuntu repositories. The package apt-mirror provides you with a script that will handle the mirroring for you. You should plan on having about 20 gigabyte of free space per supported release and architecture.

By default, apt-mirror uses the configuration file in `/etc/apt/mirror.list`. As it is set up, it will replicate only the architecture of the local machine. If you would like to support other architectures on your mirror, simply duplicate the lines starting with “deb”, replacing the deb keyword by /deb-{arch} where arch can be i386, amd64, etc... For example, on an amd64 machine, to have the i386 archives as well, you will have:

    deb  http://archive.ubuntu.com/ubuntu &distro-short-codename; main restricted universe multiverse
    /deb-i386  http://archive.ubuntu.com/ubuntu &distro-short-codename; main restricted universe multiverse

    deb  http://archive.ubuntu.com/ubuntu &distro-short-codename;-updates main restricted universe multiverse
    /deb-i386  http://archive.ubuntu.com/ubuntu &distro-short-codename;-updates main restricted universe multiverse

    deb http://archive.ubuntu.com/ubuntu/ &distro-short-codename;-backports main restricted universe multiverse
    /deb-i386  http://archive.ubuntu.com/ubuntu &distro-short-codename;-backports main restricted universe multiverse

    deb http://security.ubuntu.com/ubuntu &distro-short-codename;-security main restricted universe multiverse
    /deb-i386  http://security.ubuntu.com/ubuntu &distro-short-codename;-security main restricted universe multiverse

    deb http://archive.ubuntu.com/ubuntu &distro-short-codename; main/debian-installer restricted/debian-installer universe/debian-installer multiverse/debian-installer
    /deb-i386 http://archive.ubuntu.com/ubuntu &distro-short-codename; main/debian-installer restricted/debian-installer universe/debian-installer multiverse/debian-installer

Notice that the source packages are not mirrored as they are seldom used compared to the binaries and they do take a lot more space, but they can be easily added to the list.

Once the mirror has finished replicating (and this can be quite long), you need to configure Apache so that your mirror files (in `/var/spool/apt-mirror` if you did not change the default), are published by your Apache server. For more information on Apache see .

#### Installing in a RAM Disk

As you can easily imagine, writing to RAM is a LOT faster than writing to disk. If you have some free memory, letting vmbuilder perform its operation in a RAMdisk will help a lot and the option --tmpfs will help you do just that:

    --tmpfs OPTS  Use a tmpfs as the working directory, specifying its
                  size or "-" to use tmpfs default (suid,dev,size=1G).

So adding `--tmpfs -` sounds like a very good idea if you have 1G of free ram.

### Package the Application

Two option are available to us:

- The recommended method to do so is to make a Debian package. Since this is outside of the scope of this tutorial, we will not perform this here and invite the reader to read the documentation on how to do this in the Ubuntu Packaging Guide. In this case it is also a good idea to setup a repository for your package so that updates can be conveniently pulled from it. See the Debian Administration article for a tutorial on this.

- Manually install the application under `/opt` as recommended by the FHS guidelines.

In our case we'll use Limesurvey as example web application for which we wish to provide a virtual appliance. As noted before, we've made a version of the package available in a PPA (Personal Package Archive).

### Finishing Install

#### First Boot

As we mentioned earlier, the first time the machine boots we'll need to install openssh-server so that the key generated for it is unique for each machine. To do this, we'll write a script called `boot.sh` as follows:

    # This script will run the first time the virtual machine boots
    # It is ran as root.

    apt-get update
    apt-get install -qqy --force-yes openssh-server

And we add the `--firstboot boot.sh` option to our command line.

#### First Login

Mysql and Limesurvey needing some user interaction during their setup, we'll set them up the first time a user logs in using a script named login.sh. We'll also use this script to let the user specify:

- His own password

- Define the keyboard and other locale info he wants to use

So we'll define `login.sh` as follows:

    # This script is ran the first time a user logs in

    echo "Your appliance is about to be finished to be set up."
    echo "In order to do it, we'll need to ask you a few questions,"
    echo "starting by changing your user password."

    passwd

    #give the opportunity to change the keyboard
    sudo dpkg-reconfigure console-setup

    #configure the mysql server root password
    sudo dpkg-reconfigure mysql-server-5.0

    #install limesurvey
    sudo apt-get install -qqy --force-yes limesurvey

    echo "Your appliance is now configured.  To use it point your"
    echo "browser to http://serverip/limesurvey/admin"

And we add the `--firstlogin login.sh` option to our command line.

### Useful Additions

#### Configuring Automatic Updates

To have your system be configured to update itself on a regular basis, we will just install unattended-upgrades, so we add the following option to our command line:

    --addpkg unattended-upgrades

As we have put our application package in a PPA, the process will update not only the system, but also the application each time we update the version in the PPA.

#### ACPI Event Handling

For your virtual machine to be able to handle restart and shutdown events it is being sent, it is a good idea to install the acpid package as well. To do this we just add the following option:

    --addpkg acpid

### Final Command

Here is the command with all the options discussed above:

    sudo vmbuilder kvm ubuntu --suite &distro-short-codename; --flavour virtual --arch i386 -o \
             --libvirt qemu:///system --ip 192.168.0.100 --part vmbuilder.partition --user user \
             --name user --pass default --addpkg apache2 --addpkg apache2-mpm-prefork \
             --addpkg apache2-utils --addpkg apache2.2-common --addpkg dbconfig-common \
             --addpkg libapache2-mod-php5 --addpkg mysql-client --addpkg php5-cli \
             --addpkg php5-gd --addpkg php5-ldap --addpkg php5-mysql --addpkg wwwconfig-common \
             --addpkg mysql-server --addpkg unattended-upgrades --addpkg acpid --ppa nijaba \
             --mirror http://mirroraddress:9999/ubuntu --tmpfs - --firstboot boot.sh \
             --firstlogin login.sh es

### Resources

If you are interested in learning more, have questions or suggestions, please contact the Ubuntu Server Team at:

- IRC: #ubuntu-server on freenode

- Mailing list: ubuntu-server at lists.ubuntu.com

- Also, see the JeOSVMBuilder Ubuntu Wiki page.

## UEC

### Overview

This tutorial covers UEC installation from the Ubuntu &distro-rev; Server Edition CD, and assumes a basic network topology, with a single system serving as the "all-in-one controller", and one or more nodes attached.

From this Tutorial you will learn how to install, configure, register and perform several operations on a basic UEC setup that results in a cloud with a one controller "front-end" and one or several node(s) for running Virtual Machine (VM) instances. You will also use examples to help get you started using your own private compute cloud.

### Prerequisites

To deploy a minimal cloud infrastructure, you’ll need at least two dedicated systems:

- A front end.

- One or more node(s).

The following are recommendations, rather than fixed requirements. However, our experience in developing this documentation indicated the following suggestions.

#### Front End Requirements

Use the following table for a system that will run one or more of:

- Cloud Controller (CLC)

- Cluster Controller (CC)

- Walrus (the S3-like storage service)

- Storage Controller (SC)

UEC Front End Requirements

Hardware | Minimum | Suggested | Notes
--- | --- | --- | ---
CPU | 1 GHz | 2 x 2 GHz | For an all-in-one front end, it helps to have at least a dual core processor.
Memory | 512 MB | 2 GB | The Java web front end benefits from lots of available memory.
Disk | 5400 RPM IDE | 7200 RPM SATA | Slower disks will work, but will yield much longer instance startup times.
Disk Space | 40 GB | 200 GB | 40GB is only enough space for only a single image, cache, etc., Eucalyptus does not like to run out of disk space.
Networking | 100 Mbps | 1000 Mbps | Machine images are hundreds of MB, and need to be copied over the network to nodes.

#### Node Requirements

The other system(s) are nodes, which will run::

- the Node Controller (NC)

UEC Node Requirements

Hardware | Minimum | Suggested | Notes
--- | --- | --- | ---
CPU | VT Extensions | VT, 64-bit, Multicore | 64-bit can run both i386, and amd64 instances; by default, Eucalyptus will only run 1 VM per CPU core on a Node.
Memory | 1 GB | 4 GB | Additional memory means more, and larger guests.
Disk | 5400 RPM IDE | 7200 RPM SATA or SCSI | Eucalyptus nodes are disk-intensive; I/O wait will likely be the performance bottleneck.
Disk Space | 40 GB | 100 GB | Images will be cached locally, Eucalyptus does not like to run out of disk space.
Networking | 100 Mbps | 1000 Mbps | Machine images are hundreds of MB, and need to be copied over the network to nodes.

### Installing the Cloud/Cluster/Storage/Walrus Front End Server

- Download the Ubuntu &distro-rev; Server ISO file, and burn it to a CD.

- When you boot, select “Install Ubuntu Enterprise Cloud”.

- When asked whether you want a “Cluster” or a “Node” install, select “Cluster”.

- It will ask two other cloud-specific questions during the course of the install:

  - Name of your cluster.

    - e.g. cluster1.

  - A range of public IP addresses on the LAN that the cloud can allocate to instances.

    - e.g. 192.168.1.200-192.168.1.249.

### Installing the Node Controller(s)

The node controller install is even simpler. Just make sure that you are connected to the network on which the cloud/cluster controller is already running.

- Boot from the same ISO on the node(s).

- When you boot, select “Install Ubuntu Enterprise Cloud”.

- Select “Install Ubuntu Enterprise Cloud”.

- It should detect the Cluster and preselect “Node” install for you.

- Confirm the partitioning scheme.

- The rest of the installation should proceed uninterrupted; complete the installation and reboot the node.

### Register the Node(s)

Nodes are the physical systems within UEC that actually run the virtual machine instances of the cloud.

Once one or more Ubuntu Server node(s) are installed and running the eucalyptus-nc service, log onto the Cloud Controller (CLC) and run:

    sudo euca_conf --no-rsync --discover-nodes

This will discover the systems on the network running the eucalyptus-nc service, and the administrator can confirm the registration of each node by its IP address.

If you get prompted for passwords, or receive errors from scp, you may need to revisit the key synchronization instructions at UEC/NodeInstallation.

### Obtain Credentials

After installing and booting the Cloud Controller, users of the cloud will need to retrieve their credentials. This can be done either through a web browser, or at the command line.

#### From a Web Browser

- From your web browser (either remotely or on your Ubuntu server) access the following URL:

      https://<cloud-controller-ip-address>:8443/

  You must use a secure connection, so make sure you use "https" not "http" in your URL. You will get a security certificate warning. You will have to add an exception to view the page. If you do not accept it you will not be able to view the Eucalyptus configuration page.

- Use username 'admin' and password 'admin' for the first time login (you will be prompted to change your password).

- Then follow the on-screen instructions to update the admin password and email address.

- Once the first time configuration process is completed, click the 'credentials' tab located in the top-left portion of the screen.

- Click the 'Download Credentials' button to get your certificates.

- Save them to `~/.euca`.

- Unzip the downloaded zip file into a safe location (`~/.euca`).

      unzip -d ~/.euca mycreds.zip

#### From a Command Line

- Alternatively, if you are on the command line of the Cloud Controller, you can run:

      mkdir -p ~/.euca
      chmod 700 ~/.euca
      cd ~/.euca
      sudo euca_conf --get-credentials mycreds.zip
      unzip mycreds.zip
      cd -

#### Extracting and Using Your Credentials

Now you will need to setup EC2 API and AMI tools on your server using X.509 certificates.

- Source the included "eucarc" file to set up your Eucalyptus environment:

      . ~/.euca/eucarc

- You may additionally wish to add this command to your `~/.bashrc` file so that your Eucalyptus environment is set up automatically when you log in. Eucalyptus treats this set of credentials as 'administrator' credentials that allow the holder global privileges across the cloud. As such, they should be protected in the same way that other elevated-priority access is protected (e.g. should not be made visible to the general user population).

      echo "[ -r ~/.euca/eucarc ] && . ~/.euca/eucarc" >> ~/.bashrc

- Install the required cloud user tools:

      sudo apt-get install euca2ools

- To validate that everything is working correctly, get the local cluster availability details:

      . ~/.euca/eucarc
      euca-describe-availability-zones verbose
      AVAILABILITYZONE   myowncloud                 192.168.1.1
      AVAILABILITYZONE   |- vm types                free / max   cpu   ram  disk
      AVAILABILITYZONE   |- m1.small                0004 / 0004   1    128     2
      AVAILABILITYZONE   |- c1.medium               0004 / 0004   1    256     5
      AVAILABILITYZONE   |- m1.large                0002 / 0002   2    512    10
      AVAILABILITYZONE   |- m1.xlarge               0002 / 0002   2   1024    20
      AVAILABILITYZONE   |- c1.xlarge               0001 / 0001   4   2048    20

  Your output from the above command will vary.

### Running an Image

There are multiple ways to instantiate an image in UEC:

- Use the command line.

- Use one of the UEC compatible management tools such as Landscape.

- Use the ElasticFox extension to Firefox.

Here we will describe the process from the command line:

- Before running an instance of your image, you should first create a keypair (ssh key) that you can use to log into your instance as root, once it boots. The key is stored, so you will only have to do this once.

  Run the following command:

      if [ ! -e ~/.euca/mykey.priv ]; then
          touch ~/.euca/mykey.priv
          chmod 0600 ~/.euca/mykey.priv
          euca-add-keypair mykey > ~/.euca/mykey.priv
      fi

  You can call your key whatever you like (in this example, the key is called 'mykey'), but remember what it is called. If you forget, you can always run `euca-describe-keypairs` to get a list of created keys stored in the system.

- You must also allow access to port 22 in your instances:

      euca-describe-groups
      euca-authorize default -P tcp -p 22 -s 0.0.0.0/0

- Next, you can create instances of your registered image:

      euca-run-instances $EMI -k mykey -t c1.medium

  If you receive an error regarding image_id, you may find it by viewing Images page or click "How to Run" on the Store page to see the sample command.

- The first time you run an instance, the system will be setting up caches for the image from which it will be created. This can often take some time the first time an instance is run given that VM images are usually quite large.

  To monitor the state of your instance, run:

      watch -n5 euca-describe-instances

  In the output, you should see information about the instance, including its state. While first-time caching is being performed, the instance's state will be 'pending'.

- When the instance is fully started, the above state will become 'running'. Look at the IP address assigned to your instance in the output, then connect to it:

      IPADDR=$(euca-describe-instances | grep $EMI | grep running | tail -n1 | awk '{print $4}')
      ssh -i ~/.euca/mykey.priv ubuntu@$IPADDR

- And when you are done with this instance, exit your SSH connection, then terminate your instance:

      INSTANCEID=$(euca-describe-instances | grep $EMI | grep running | tail -n1 | awk '{print $2}')
      euca-terminate-instances $INSTANCEID

### Install an Image from the Store

The following is by far the simplest way to install an image. However, advanced users may be interested in learning how to Bundle their own image.

The simplest way to add an image to UEC is to install it from the Image Store on the UEC web interface.

- Access the web interface at the following URL (Make sure you specify https):

      https://<cloud-controller-ip-address>:8443/

- Enter your login and password (if requested, as you may still be logged in from earlier).

- Click on the Store tab.

- Browse available images.

- Click on install for the image you want.

Once the image has been downloaded and installed, you can click on "How to run?" that will be displayed below the image button to view the command to execute to instantiate (start) this image. The image will also appear on the list given on the Image tab.

### More Information

How to use the Storage Controller

Controlling eucalyptus services:

- sudo service eucalyptus [start|stop|restart] (on the CLC/CC/SC/Walrus side)

- sudo service eucalyptus-nc [start|stop|restart] (on the Node side)

Locations of some important files:

- Log files:

  - /var/log/eucalyptus

- Configuration files:

  - /etc/eucalyptus

- Database:

  - /var/lib/eucalyptus/db

- Keys:

  - /var/lib/eucalyptus

  - /var/lib/eucalyptus/.ssh

Don't forget to source your `~/.euca/eucarc` before running the client tools.

### References

- For information on loading instances see the Eucalyptus Wiki page.

- Eucalyptus Project Site (forums, documentation, downloads).

- Eucalyptus on Launchpad (bugs, code).

- Eucalyptus Troubleshooting (1.5).

- Register your cloud with RightScale.

- You can also find help in the #ubuntu-virt, #eucalyptus, and #ubuntu-server IRC channels on Freenode.

### Glossary

The Ubuntu Enterprise Cloud documentation uses terminology that might be unfamiliar to some readers. This page is intended to provide a glossary of such terms and acronyms.

- Cloud - A federated set of physical machines that offer computing resources through virtual machines, provisioned and recollected dynamically.

- Cloud Controller (CLC) - Eucalyptus component that provides the web UI (an https server on port 8443), and implements the Amazon EC2 API. There should be only one Cloud Controller in an installation of UEC. This service is provided by the Ubuntu eucalyptus-cloud package.

- Cluster - A collection of nodes, associated with a Cluster Controller. There can be more than one Cluster in an installation of UEC. Clusters are sometimes physically separate sets of nodes. (e.g. floor1, floor2, floor2).

- Cluster Controller (CC) - Eucalyptus component that manages collections of node resources. This service is provided by the Ubuntu eucalyptus-cc package.

- EBS - Elastic Block Storage.

- EC2 - Elastic Compute Cloud. Amazon's pay-by-the-hour, pay-by-the-gigabyte public cloud computing offering.

- EKI - Eucalyptus Kernel Image.

- EMI - Eucalyptus Machine Image.

- ERI - Eucalyptus Ramdisk Image.

- Eucalyptus - Elastic Utility Computing Architecture for Linking Your Programs To Useful Systems. An open source project originally from the University of California at Santa Barbara, now supported by Eucalyptus Systems, a Canonical Partner.

- Front-end - Physical machine hosting one (or more) of the high level Eucalyptus components (cloud, walrus, storage controller, cluster controller).

- Node - A node is a physical machine that's capable of running virtual machines, running a node controller. Within Ubuntu, this generally means that the CPU has VT extensions, and can run the KVM hypervisor.

- Node Controller (NC) - Eucalyptus component that runs on nodes which host the virtual machines that comprise the cloud. This service is provided by the Ubuntu package eucalyptus-nc.

- S3 - Simple Storage Service. Amazon's pay-by-the-gigabyte persistent storage solution for EC2.

- Storage Controller (SC) - Eucalyptus component that manages dynamic block storage services (EBS). Each 'cluster' in a Eucalyptus installation can have its own Storage Controller. This component is provided by the eucalyptus-sc package.

- UEC - Ubuntu Enterprise Cloud. Ubuntu's cloud computing solution, based on Eucalyptus.

- VM - Virtual Machine.

- VT - Virtualization Technology. An optional feature of some modern CPUs, allowing for accelerated virtual machine hosting.

- Walrus - Eucalyptus component that implements the Amazon S3 API, used for storing VM images and user storage using S3 bucket put/get abstractions.

## OpenNebula

OpenNebula allows virtual machines to be placed and re-placed dynamically on a pool of physical resources. This allows a virtual machine to be hosted from any location available.

This section will detail configuring an OpenNebula cluster using three machines: one Front-End host, and two Compute Nodes used to run the virtual machines. The Compute Nodes will also need a bridge configured to allow the virtual machines access to the local network. For details see .

### Installation

First, from a terminal on the Front-End enter:

    sudo apt-get install opennebula

On each Compute Node install:

    sudo apt-get install opennebula-node

In order to copy SSH keys, the oneadmin user will need to have a password. On each machine execute:

    sudo passwd oneadmin

Next, copy the oneadmin user's SSH key to the Compute Nodes, and to the Front-End's `authorized_keys` file:

    sudo scp /var/lib/one/.ssh/id_rsa.pub oneadmin@node01:/var/lib/one/.ssh/authorized_keys
    sudo scp /var/lib/one/.ssh/id_rsa.pub oneadmin@node02:/var/lib/one/.ssh/authorized_keys
    sudo sh -c "cat /var/lib/one/.ssh/id_rsa.pub >> /var/lib/one/.ssh/authorized_keys"

The SSH key for the Compute Nodes needs to be added to the `/etc/ssh/ssh_known_hosts` file on the Front-End host. To accomplish this ssh to each Compute Node as a user other than oneadmin. Then exit from the SSH session, and execute the following to copy the SSH key from `~/.ssh/known_hosts` to `/etc/ssh/ssh_known_hosts`:

    sudo sh -c "ssh-keygen -f .ssh/known_hosts -F node01 1>> /etc/ssh/ssh_known_hosts"
    sudo sh -c "ssh-keygen -f .ssh/known_hosts -F node02 1>> /etc/ssh/ssh_known_hosts"

Replace node01 and node02 with the appropriate host names.

This allows the oneadmin to use scp, without a password or manual intervention, to deploy an image to the Compute Nodes.

On the Front-End create a directory to store the VM images, giving the oneadmin user access to the directory:

    sudo mkdir /var/lib/one/images
    sudo chown oneadmin /var/lib/one/images/

Finally, copy a virtual machine disk file into `/var/lib/one/images`. You can create an Ubuntu virtual machine using vmbuilder, see for details.

### Configuration

The OpenNebula Cluster is now ready to be configured, and virtual machines added to the cluster.

From a terminal prompt enter:

    onehost create node01 im_kvm vmm_kvm tm_ssh
    onehost create node02 im_kvm vmm_kvm tm_ssh

Next, create a Virtual Network template file named `vnet01.template`:

    NAME            = "LAN"
    TYPE            = RANGED
    BRIDGE          = br0
    NETWORK_SIZE    = C
    NETWORK_ADDRESS = 192.168.0.0

Be sure to change 192.168.0.0 to your local network.

Using the onevnet utility, add the virtual network to OpenNebula:

    onevnet create vnet01.template

Now create a VM Template file named `vm01.template`:

    NAME   = vm01
    CPU    = 0.5
    MEMORY = 512

    OS      = [ BOOT   = hd ]

    DISK   = [
      source   = "/var/lib/one/images/vm01.qcow2",
      target   = "hda",
      readonly = "no" ]

    NIC    = [ NETWORK="LAN" ]

    GRAPHICS = [type="vnc",listen="127.0.0.1",port="-1"]

Start the virtual machine using onevm:

    onevm submit vm01.template

Use the onevm list option to view information about virtual machines. Also, the onevm show vm01 option will display more details about a specific virtual machine.

### References

- See the OpenNebula website for more information.

- You can also find help in the #ubuntu-virt and #ubuntu-server IRC channels on Freenode.

- Also, the OpenNebula Ubuntu Wiki page has more details.