<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
 version="5.0"
  xml:id="lab000-virtualbox-basics">
  <title>VirtualBox basics</title>
  <para><guilabel>Getting Started</guilabel></para>
  <para>The following methods are conventional for deploying
    OpenStack on Virtual Box for the sake of a test/sandbox or just to
    try out OpenStack on commodity hardware.</para>
    <para>1. DevStack</para>
    <para>2. Vagrant</para>
    <para>DevStack and Vagrant bring in some level of automated
      deployment as running the scripts will get your VirtualBox
      instance configured as the required OpenStack deployment. We
      will be manually deploying OpenStack on VirtualBox to
      get a better view of how OpenStack works.</para>
    <para><guilabel>Prerequisite:</guilabel></para>
    <para>Networking and Linux are required to get setup.</para>
    <para>The Virtual Machines and Virtual Networks will be given
      equal privileges as a physical machine on a physical
      network.</para>
    <para>For more information, refer to the following
        links:</para>
    <para>
      <emphasis role="bold">OpenStack:</emphasis> <link
      xlink:href="http://docs.openstack.org">OpenStack Official
      Documentation</link></para>
    <para><emphasis role="bold">Networking:</emphasis> Computer
    Networks (5th Edition) by Andrew S. Tanenbaum</para>
    <para><emphasis role="bold">VirtualBox:</emphasis> <link
    xlink:href="http://www.virtualbox.org/manual/UserManual.html">Virtual
    Box Manual</link></para>
    <para><emphasis role="bold">Requirements:</emphasis></para>
    <para>Operating Systems - I recommend Ubuntu Server 12.04 LTS,
    Ubuntu Server 13.10 or Debian Wheezy.</para>
    <note><para>Ubuntu 12.10 is not
       supporting OpenStack Grizzly Packages. Ubuntu team has decided not
       to package Grizzly Packages for Ubuntu 12.10.</para></note>
    <itemizedlist>
      <listitem>
          <para>Recommended Requirements:</para>
      </listitem>
    </itemizedlist>
    <informaltable class="c25">
      <tbody>
        <tr>
          <td rowspan="1" colspan="1">VT Enabled PC:</td>
          <td rowspan="1" colspan="1">Intel ix or AMD QuadCore</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">4&nbsp;GB RAM:</td>
          <td rowspan="1" colspan="1">DDR2/DDR3</td>
        </tr>
      </tbody>
    </informaltable>
    <itemizedlist>
      <listitem>
          <para>Minimum Requirements:</para>
      </listitem>
    </itemizedlist>
    <informaltable class="c25">
      <tbody>
        <tr>
          <td rowspan="1" colspan="1">Non-VT PC's:</td>
          <td rowspan="1" colspan="1">Intel Core 2 Duo or AMD Dual
            Core</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">2GB Ram:</td>
          <td rowspan="1" colspan="1">DDR2/DDR3</td>
        </tr>
      </tbody>
    </informaltable>
    <para>If you don't know whether your processor is VT enabled, you
      could check it by installing cpu-checker:</para>
      <screen><prompt>#</prompt> <userinput>apt-get install cpu-checker</userinput>
<prompt>#</prompt> <userinput>kvm-ok</userinput></screen>
    <para>If your device does not support VT it will show:</para>
    <screen><computeroutput>INFO:Your CPU does not support KVM extensions
KVM acceleration can NOT be used</computeroutput></screen>
    <para>You will still be able to use Virtual Box but the instances
      will be very slow.</para>
    <para>There are many ways to configure your OpenStack Setup. In this example, we
    will deploy OpenStack multi node using OVS as the network
    plug-in and QEMU/KVM as the hypervisor.</para>
  <para><emphasis role="bold">Host only connections:</emphasis></para>
    <itemizedlist>
      <listitem>
        <para>Host only connections provide an internal network
          between your host and the Virtual Machine instances on your host machine. This network is not traceable
          by other networks.</para>
      </listitem>
      <listitem>
        <para>You may even use bridged connections if you have a
          router/switch.</para>
      </listitem>
      <listitem>
        <para>The following are the host only connections that you
          will be setting up later on:</para>
          <orderedlist>
            <listitem>
              <para>vboxnet0 - OpenStack management network - host static IP
                10.10.10.1</para>
            </listitem>
            <listitem>
              <para>vboxnet1 - VM conf.network - host static IP
                10.20.20.1</para>
            </listitem>
            <listitem>
              <para>vboxnet2 - VM external network access (host
                machine) 192.168.100.1</para>
            </listitem>
          </orderedlist>
      </listitem>
    </itemizedlist>
  <figure>
    <title>Network diagram</title>
    <mediaobject>
      <imageobject>
        <imagedata  contentwidth="5in" fileref="figures/lab000-virtual-box/image03.png"/>
      </imageobject>
    </mediaobject>
  </figure>
  <!--
  <para>Publicly editable image source at <link
    xlink:href="https://docs.google.com/drawings/d/1GX3FXmkz3c_tUDpZXUVMpyIxicWuHs5fNsHvYNjwNNk/edit?usp=sharing"
    >https://docs.google.com/drawings/d/1GX3FXmkz3c_tUDpZXUVMpyIxicWuHs5fNsHvYNjwNNk/edit?usp=sharing</link></para>
  -->
  <para>Vboxnet0, Vboxnet1, Vboxnet2 - are virtual networks setup
      by virtual box with your host machine. This is the way your host
      can communicate with the virtual machines. These networks are in
      turn used by virtual box VM’s for OpenStack networks, so that
      OpenStack’s services can communicate with each other.
      For details, see the <link
      xlink:href="http://www.virtualbox.org/manual/ch06.html#network_hostonly">VirtualBox
      documentation</link>
  </para>
  <section xml:id="lab000-virtualbox-basics_setup_virtualbox">
  <title>Setup your VM environment</title>
  <para>Before you can start configuring your environment you need to
    download some of the following stuff:</para>
  <orderedlist>
    <listitem>
      <para><link xlink:href="https://www.virtualbox.org/wiki/Downloads">
        Oracle Virtual Box</link></para>
   <note><para>You cannot set up an AMD64 VM on a x86 machine.</para></note>
    </listitem>
    <listitem>
      <para><link xlink:href="http://www.ubuntu.com/download/server">
        Ubuntu 12.04 Server or Ubuntu 13.04 Server</link></para>
     </listitem>
   </orderedlist>
   <note><para>You need a x86 image for VM's if kvm-ok fails, even
      though you are on an AMD64 machine.</para></note>
   <note><para>Even though I'm using Ubuntu as host, the same is
      applicable to Windows, Mac and other Linux hosts.</para></note>
   <itemizedlist>
      <listitem>
        <para>If you have i5 or i7 2nd gen processor you can have VT
        technology inside VM's provided by VMware. This means that
        your OpenStack nodes (which are in turn VM's) will give
        positive result on KVM-OK. (I call it - nesting of type-2
        hypervisors). The rest of the configurations remain same except
        for the UI and a few other trivial differences.</para>
      </listitem>
    </itemizedlist>
  </section>
  <section xml:id="lab000-virtualbox-basics_setup_virtual_networks">
    <title>Configure virtual networks</title>

    <itemizedlist>
      <listitem>
        <para>This section of the guide will help you setup your
          networks for your Virtual Machine.</para>
      </listitem>
      <listitem>
        <para>Launch Virtual Box</para>
      </listitem>
    </itemizedlist>
    <itemizedlist>
      <listitem>
        <para>Click on <emphasis role="bold"
          >File>Preferences</emphasis> present on the menu bar of
        Virtual Box.</para>
      </listitem>
      <listitem>
        <para>Select the <emphasis role="bold">Network
        tab</emphasis>.</para>
      </listitem>
      <listitem>
        <para>On the right side you will see an option to add
        Host-Only networks.</para>
      </listitem>
    </itemizedlist>
  <figure>
    <title>Create host only networks</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image13.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <itemizedlist>
      <listitem>
        <para>Create three host-only network connections. As shown
          above.</para>
      </listitem>
      <listitem>
        <para>Edit the host-only connections to have the following
          settings.</para>
      </listitem>
    </itemizedlist>
    <para><emphasis role="bold">Vboxnet0</emphasis></para>

    <informaltable class="c25">
      <tbody>
        <tr>
          <th>Option</th>
          <th>Value</th>
        </tr>
        <tr>
          <td>IPv4 Address:</td>
          <td>10.10.10.1</td>
        </tr>
        <tr>
          <td>IPv4 Network Mask:</td>
          <td>255.255.255.0</td>
        </tr>
        <tr>
          <td>IPv6 Address:</td>
          <td>Can be left blank</td>
        </tr>
        <tr>
          <td>IPv6 Network Mask Length:</td>
          <td>Can be left blank</td>
        </tr>
      </tbody>
    </informaltable>
  <figure>
    <title>Vboxnet0</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image19.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Vboxnet1</emphasis></para>


    <informaltable class="c25">
      <tbody>
        <tr>
          <th rowspan="1" colspan="1">Option</th>
          <th rowspan="1" colspan="1">Value</th>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv4 Address:</td>
          <td rowspan="1" colspan="1">10.20.20.1</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv4 Network Mask:</td>
          <td rowspan="1" colspan="1">255.255.255.0</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv6 Address:</td>
          <td rowspan="1" colspan="1">Can be Left Blank</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv6 Network Mask Length :</td>
          <td rowspan="1" colspan="1">Can be Left Blank</td>
        </tr>
      </tbody>
    </informaltable>
  <figure>
    <title>Vboxnet1</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image16.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Vboxnet2</emphasis></para>

    <informaltable class="c25">
      <tbody>
        <tr>
          <th rowspan="1" colspan="1">Option</th>
          <th rowspan="1" colspan="1">Value</th>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv4 Address:</td>
          <td rowspan="1" colspan="1">192.168.100.1</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv4 Network Mask:</td>
          <td rowspan="1" colspan="1">255.255.255.0</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv6 Address:</td>
          <td rowspan="1" colspan="1">Can be Left Blank</td>
        </tr>
        <tr>
          <td rowspan="1" colspan="1">IPv6 Network Mask Length :</td>
          <td rowspan="1" colspan="1">Can be Left Blank</td>
        </tr>
      </tbody>
    </informaltable>
  <figure>
    <title>Image: Vboxnet2</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image08.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
  </section>
  <section xml:id="lab000-virtualbox-basics_setup_install_ssh_ftp">
    <title>Install SSH and FTP</title>
    <itemizedlist>
      <listitem>
        <para>You may benefit by installing SSH and FTP so that you
          can use your remote shell to login into the machine and
          use your terminal which is more convenient than using the
          Virtual Machines tty through the Virtual Box's UI. You get a
          few added features such as copy - paste commands into the
          remote terminal, which is not possible directly on VM.</para>
      </listitem>
      <listitem>
        <para>FTP is for transferring files to and from your local machine
          and the virtual machine. You can
          also use SFTP or install FTPD on both HOST and VM's.</para>
      </listitem>
      <listitem>
        <para>Installation of SSH and FTP with the configuration steps are
          out of the scope of this guide.</para>
      </listitem>
    </itemizedlist>
    <note><para>Set up the
      networks from inside the VM before trying to SSH and FTP into the
      machines.</para>
    </note>
  </section>
  <section xml:id="lab000-virtualbox-basics_setup_install_vm_instances">
    <title>Install your VM instances</title>

    <itemizedlist>
      <listitem>
        <para>During installation of the operating systems you will be
          asked for custom software to install. You may skip this step
          by pressing the <keycap>Enter</keycap> key without selecting
          any of the given options.</para>
      </listitem>
    </itemizedlist>
    <warning><para>Please do not install any of the other packages
      except for the packages that are mentioned below unless you are
      familiar with the process.</para>
    </warning>
  </section>
  <section xml:id="lab000-virtualbox-basics_setup_control_node">
    <title>Control node</title>

    <para>Create a new virtual machine and select Ubuntu Server.</para>
  <figure>
    <title>Create new virtual machine</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image11.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para>Select the appropriate amount of RAM. For the control node,
    the minimum is 512&nbsp;MB of RAM. For other settings, use the
    defaults. The hard disk size can be 8&nbsp;GB.</para>
    <para>Configure the networks</para>
    <para>(Ignore the IP Address for now, you will set it up from
      inside the VM)</para>

    <informaltable class="c25">
      <tbody>
        <tr>
          <th>Network Adapter</th>
          <th>Host-Only Adapter Name</th>
          <th>IP Address</th>
        </tr>
        <tr>
          <td>eth0</td>
          <td>Vboxnet0</td>
          <td>10.10.10.51</td>
        </tr>
        <tr>
          <td>eth1</td>
          <td>Vboxnet2</td>
          <td>192.168.100.51</td>
        </tr>
        <tr>
          <td>eth2</td>
          <td>NAT</td>
          <td>DHCP</td>
        </tr>
      </tbody>
    </informaltable>
    <para><emphasis role="bold">Adapter 1 (Vboxnet0)</emphasis></para>
  <figure>
    <title>Adapter1 - Vboxnet0</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image07.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Adapter 2 (Vboxnet2)</emphasis></para>
  <figure>
    <title>Adapter2 - Vboxnet2</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image18.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Adapter 3 (NAT)</emphasis></para>
  <figure>
    <title>Adapter3 - NAT</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image14.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para>Now install Ubuntu Server 12.04 or 13.04 on this
      machine.</para>
    <note><para>Install SSH server
      when asked for custom software to install. The rest of the packages
      are not required and may come in the way of OpenStack packages -
      like DNS servers etc. (not necessary). Unless you know what you
      are doing.</para>
    </note>
  </section>
  <section xml:id="lab000-virtualbox-basics_setup_network_node">
    <title>Network node</title>

    <para>Create a new virtual machine, minimum RAM is
      512&nbsp;MB. The remainder can be left as default. The minimum HDD
      space is 8&nbsp;GB.</para>

  <figure>
    <title>Create New Virtual Machine</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image12.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para>Configure the networks</para>
    <para>(Ignore the IP Address for now, you will set it up from
      inside the VM)</para>

    <informaltable class="c25">
      <tbody>
        <tr>
          <th>Network Adapter</th>
          <th>Host-Only Adapter Name</th>
          <th>IP Address</th>
        </tr>
        <tr>
          <td>eth0</td>
          <td>Vboxnet0</td>
          <td>10.10.10.52</td>
        </tr>
        <tr>
          <td>eth1</td>
          <td>Vboxnet1</td>
          <td>10.20.20.52</td>
        </tr>
        <tr>
          <td>eth2</td>
          <td>Vboxnet2</td>
          <td>192.168.100.52</td>
        </tr>
        <tr>
          <td>eth3</td>
          <td>NAT</td>
          <td>DHCP</td>
        </tr>
      </tbody>
    </informaltable>
    <para><emphasis role="bold">Adapter 1 (Vboxnet0)</emphasis></para>
  <figure>
    <title>Adapter 1 - Vboxnet0</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image05.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Adapter 2 (Vboxnet1)</emphasis></para>
  <figure>
    <title>Adapter2 - Vboxnet1</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image17.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Adapter 3 (Vboxnet2)</emphasis></para>
  <figure>
    <title>Adapter3 - Vboxnet2</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image02.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Adapter 4 (NAT)</emphasis></para>
  <figure>
    <title>Adapter4 - NAT</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image00.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para>Now install Ubuntu Server 12.04 or 13.04 on this
      machine.</para>
    <note><para>Install the SSH server when you are prompted for the
      custom software to install. The rest of the packages are not
      required and may come in the way of OpenStack packages - like DNS
      servers.</para>
    </note>
  </section>
  <section xml:id="lab000-virtualbox-basics_setup_compute_node">
    <title>Compute node</title>

    <para>Create a virtual machine with at least 1,000&nbsp;MB RAM and
    8&nbsp;GB HDD. For other settings, use the defaults.</para>
  <figure>
    <title>Create new virtual machine</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image04.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para>Configure the networks</para>
    <para>(Ignore the IP Address for now, you will set it up from
      inside the VM)</para>

    <informaltable class="c25">
      <tbody>
        <tr>
          <th>Network Adapter</th>
          <th>Host-Only Adapter Name</th>
          <th>IP Address</th>
        </tr>
        <tr>
          <td>eth0</td>
          <td>Vboxnet0</td>
          <td>10.10.10.53</td>
        </tr>
        <tr>
          <td>eth1</td>
          <td>Vboxnet1</td>
          <td>10.20.20.53</td>
        </tr>
        <tr>
          <td>eth2</td>
          <td>NAT</td>
          <td>DHCP</td>
        </tr>
      </tbody>
    </informaltable>
    <para><emphasis role="bold">Adapter 1 (Vboxnet0)</emphasis></para>
  <figure>
    <title>Adapter1 - Vboxnet0</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image15.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Adapter 2 (Vboxnet1)</emphasis></para>
  <figure>
    <title>Adapter2 - Vboxnet1</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image10.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para><emphasis role="bold">Adapter 3 (NAT)</emphasis></para>
  <figure>
    <title>Adapter3 - NAT</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/lab000-virtual-box/image01.png"
                   contentwidth="6in"/>
      </imageobject>
    </mediaobject>
  </figure>
    <para>Now install Ubuntu Server 12.04 or 13.04 on this
      machine.</para>
    <note><para>Install the SSH server
      when asked for custom software to install. The rest of the packages
      are not required and may come in the way of OpenStack packages -
      like DNS servers etc.</para>
    </note>
  </section>
  <section xml:id="lab000-virtualbox-basics_setup_warnings">
    <title>Warnings and advice</title>

    <para>Well there are a few warnings that I must give you out
       of experience due to common habits that most people may
       have.</para>
    <para>Sometimes shutting down your Virtual Machine may lead to
        the malfunctioning of OpenStack Services. Try not to directly
        shutdown your VM, in case your VM's don't get Internet.</para>
      <itemizedlist>
        <listitem>
          <para>From your VM instance, use the <command>ping</command>
          command to see whether Internet is on.</para>
          <screen><prompt>$</prompt> <userinput>ping www.google.com</userinput></screen>
        </listitem>
        <listitem>
          <para>If its not connected, restart networking
            service:</para>
      <screen><prompt>#</prompt> <userinput>service networking restart</userinput>
<prompt>#</prompt> <userinput>ping www.google.com</userinput></screen>
        </listitem>
        <listitem>
          <para>If this doesn't work, check your network
            settings from Virtual Box. Something may be missing or it may be
            misconfigured.</para>
        </listitem>
        <listitem>
          <para>This should reconnect your network about 99% of the
            time. If you are really unlucky you must be having some
            other problems or your Internet connection itself is not
            functioning.</para>
        </listitem>
        <listitem>
          <para>Note: There are known bugs with the ping under NAT.
            Although the latest versions of Virtual Box have better
            performance, sometimes ping may not work even if the
            Network is connected to the Internet.</para>
        </listitem>
      </itemizedlist>
      <para>Congrats, you are ready with the infrastructure for
        deploying OpenStack. Just make sure that you have installed
        Ubuntu Server on the above setup Virtual Box instances. In the
        next section we will go through deploying OpenStack using the
        above created Virtual Box instances.</para>
  </section>
</chapter>