<?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="ch_creating_images_manually">
    <title>Create images manually</title>
    <para>Creating a new image is a step done outside of your
        OpenStack installation. You create the new image manually on
        your own system and then upload the image to your
        cloud.</para>
    <para>To create a new image, you will need the installation CD or
        DVD ISO file for the guest operating system. You'll also need
        access to a virtualization tool. You can use KVM for this. Or,
        if you have a GUI desktop virtualization tool (such as, VMWare
        Fusion and VirtualBox), you can use that instead and just
        convert the file to raw once you're done.</para>
    <para>When you create a new virtual machine image, you will need
        to connect to the graphical console of the hypervisor, which
        acts as the virtual machine's display and allows you to
        interact with the guest operating system's installer using
        your keyboard and mouse. KVM can expose the graphical console
        using the <link
            xlink:href="https://en.wikipedia.org/wiki/Virtual_Network_Computing"
            >VNC</link> (Virtual Network Computing) protocol or the
        newer <link xlink:href="http://spice-space.org">SPICE</link>
        protocol. We'll use the VNC protocol here, since you're more
        likely to be able to find a VNC client that works on your
        local desktop.</para>
    <section xml:id="net-running">
        <title>Verify the libvirt default network is running</title>
        <para>Before starting a virtual machine with libvirt, verify
            that the libvirt "default" network has been started. This
            network must be active for your virtual machine to be able
            to connect out to the network. Starting this network will
            create a Linux bridge (usually called
                <literal>virbr0</literal>), iptables rules, and a
            dnsmasq process that will serve as a DHCP server.</para>
        <para>To verify that the libvirt "default" network is enabled,
            use the <command>virsh net-list</command> command and
            verify that the "default" network is active:</para>
        <screen><prompt>#</prompt> <userinput>virsh net-list</userinput>
<computeroutput>Name                 State      Autostart
-----------------------------------------
default              active     yes</computeroutput></screen>
        <para>If the network is not active, start it by doing:</para>
        <screen><prompt>#</prompt> <userinput>virsh net-start default</userinput></screen>
    </section>
    <section xml:id="virt-manager">
        <title>Use the virt-manager X11 GUI</title>
        <para>If you plan to create a virtual machine image on a
            machine that can run X11 applications, the simplest way to
            do so is to use the <command>virt-manager</command> GUI,
            which is installable as the
                <literal>virt-manager</literal> package on both
            Fedora-based and Debian-based systems. This GUI has an
            embedded VNC client in it that will let you view and
            interact with the guest's graphical console.</para>
        <para>If you are building the image on a headless server, and
            you have an X server on your local machine, you can launch
                <command>virt-manager</command> using ssh X11
            forwarding to access the GUI. Since virt-manager interacts
            directly with libvirt, you typically need to be root to
            access it. If you can ssh directly in as root (or with a
            user that has permissions to interact with libvirt),
            do:<screen><prompt>$</prompt> <userinput>ssh -X root@server virt-manager</userinput></screen></para>
        <para>If the account you use to ssh into your server does not
            have permissions to run libvirt, but has sudo privileges, do:<screen><prompt>$</prompt> <userinput>ssh -X root@server</userinput>
<prompt>$</prompt> <userinput>sudo virt-manager</userinput> </screen><note>
                <para>The <literal>-X</literal> flag passed to ssh
                    will enable X11 forwarding over ssh. If this does
                    not work, try replacing it with the
                        <literal>-Y</literal> flag.</para>
            </note></para>
        <para>Click the "New" button at the top-left and step through
            the instructions. <mediaobject>
                <imageobject>
                    <imagedata fileref="figures/virt-manager-new.png"
                        format="PNG" contentwidth="6in"/>
                </imageobject>
            </mediaobject>You will be shown a series of dialog boxes
            that will allow you to specify information about the
            virtual machine.</para>
            <note><para>
            When using qcow2 format images you should check the option
            'customize before install', go to disk properties and
            explicitly select the qcow2 format. This ensures the virtual
            machine disk size will be correct.
            </para></note>
    </section>
    <section xml:id="virt-install">
        <title>Use virt-install and connect by using a local VNC
            client</title>
        <para>If you do not wish to use virt-manager (for example, you
            do not want to install the dependencies on your server,
            you don't have an X server running locally, the X11
            forwarding over SSH isn't working), you can use the
                <command>virt-install</command> tool to boot the
            virtual machine through libvirt and connect to the
            graphical console from a VNC client installed on your
            local machine.</para>
        <para>Because VNC is a standard protocol, there are multiple
            clients available that implement the VNC spec, including
                <link
                xlink:href="http://sourceforge.net/apps/mediawiki/tigervnc/index.php?title=Welcome_to_TigerVNC"
                >TigerVNC</link> (multiple platforms), <link
                xlink:href="http://tightvnc.com/">TightVNC</link>
            (multiple platforms), <link
                xlink:href="http://realvnc.com/">RealVNC</link>
            (multiple platforms), <link
                xlink:href="http://sourceforge.net/projects/chicken/"
                >Chicken</link> (Mac OS X), <link
                xlink:href="http://userbase.kde.org/Krdc">Krde</link>
            (KDE), and <link
                xlink:href="http://projects.gnome.org/vinagre/"
                >Vinagre</link> (GNOME).</para>
        <para>The following example shows how to use the
                <command>qemu-img</command> command to create an empty
            image file <command>virt-install</command> command to
            start up a virtual machine using that image file. As
            root:</para>
        <screen><prompt>#</prompt> <command>qemu-img create -f qcow2 /data/centos-6.4.qcow2 10G</command>
<prompt>#</prompt> <userinput>virt-install --virt-type kvm --name centos-6.4 --ram 1024 \
--cdrom=/data/CentOS-6.4-x86_64-netinstall.iso \
--disk path=/data/centos-6.4.qcow2,size=10,format=qcow2 \
--network network=default\
--graphics vnc,listen=0.0.0.0 --noautoconsole \
--os-type=linux --os-variant=rhel6</userinput>
<computeroutput>
Starting install...
Creating domain...                                                                                                                                       |    0 B     00:00
Domain installation still in progress. You can reconnect to
the console to complete the installation process.</computeroutput></screen>
         <para>
            The KVM hypervisor starts the virtual machine with the
            libvirt name, <literal>centos-6.4</literal>, with
            1024&nbsp;MB of RAM. The virtual machine also has a virtual
            CD-ROM drive associated with the
            <filename>/data/CentOS-6.4-x86_64-netinstall.iso</filename>
            file and a local 10&nbsp;GB hard disk in qcow2 format that is
            stored in the host at
            <filename>/data/centos-6.4.qcow2</filename>.
            It configures networking to
            use libvirt's default network. There is a VNC server that
            is listening on all interfaces, and libvirt will not
            attempt to launch a VNC client automatically nor try to
            display the text console
                (<literal>--no-autoconsole</literal>). Finally,
            libvirt will attempt to optimize the configuration for a
            Linux guest running a RHEL 6.x distribution.<note>
                <para>When using the libvirt
                <literal>default</literal> network, libvirt will
                connect the virtual machine's interface to a bridge
                called <literal>virbr0</literal>. There is a dnsmasq
                process managed by libvirt that will hand out an IP
                address on the 192.168.122.0/24 subnet, and libvirt
                has iptables rules for doing NAT for IP addresses on
                this subnet.</para>
            </note></para>
        <para>Run the <command>virt-install --os-variant
                list</command> command to see a range of allowed
                <literal>--os-variant</literal> options.</para>
        <para>Use the <command>virsh vncdisplay
                    <replaceable>vm-name</replaceable></command>
            command to get the VNC port number.</para>
        <screen><prompt>#</prompt> <userinput>virsh vncdisplay centos-6.4</userinput>
<computeroutput>:1</computeroutput></screen>
        <para>In the example above, the guest
                <literal>centos-6.4</literal> uses VNC display
                <literal>:1</literal>, which corresponds to tcp port
                <literal>5901</literal>. You should be able to connect
            to a VNC client running on your local machine to display
            :1 on the remote machine and step through the installation
            process.</para>
    </section>
    <xi:include href="section_centos-example.xml"/>
    <xi:include href="section_ubuntu-example.xml"/>
    <xi:include href="section_windows-example.xml"/>
    <xi:include href="section_freebsd-example.xml"/>
</chapter>