Merge "[image-guide] Convert create images to RST"

doc/image-guide-rst/source/centos-image.rst

@@ -0,0 +1,3 @@
+=====================
+Example: CentOS image
+=====================

doc/image-guide-rst/source/create-images-manually.rst

@@ -1,3 +1,37 @@
 ======================
 Create images manually
 ======================
+
+.. toctree::
+   :maxdepth: 2
+
+   net-running.rst
+   virt-manager.rst
+   virt-install.rst
+   centos-image.rst
+   ubuntu-image.rst
+   fedora-image.rst
+   windows-image.rst
+   freebsd-image.rst
+
+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.
+
+To create a new image, you will need the installation CD or
+DVD ISO file for the guest operating system. You will 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 or VirtualBox), you can use that instead.
+Convert the file to raw once you are done.
+
+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
+`VNC <https://en.wikipedia.org/wiki/Virtual_Network_Computing>`_
+(Virtual Network Computing) protocol or the newer
+`SPICE <http://spice-space.org>`_ protocol.
+We will use the VNC protocol here, since you are more likely
+to find a VNC client that works on your local desktop.

doc/image-guide-rst/source/fedora-image.rst

@@ -0,0 +1,3 @@
+=====================
+Example: Fedora image
+=====================

doc/image-guide-rst/source/freebsd-image.rst

@@ -0,0 +1,3 @@
+======================
+Example: FreeBSD image
+======================

doc/image-guide-rst/source/net-running.rst

@@ -0,0 +1,28 @@
+=============================================
+Verify the libvirt default network is running
+=============================================
+
+Before starting a virtual machine with libvirt, verify
+that the libvirt ``default`` network has 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 ``virbr0``), iptables rules, and a dnsmasq process
+that will serve as a DHCP server.
+
+To verify that the libvirt ``default`` network is enabled,
+use the :command:`virsh net-list` command and verify
+that the ``default`` network is active:
+
+.. code-block:: console
+
+   # virsh net-list
+   Name                 State      Autostart
+   -----------------------------------------
+   default              active     yes
+
+If the network is not active, start it by doing:
+
+.. code-block:: console
+
+   # virsh net-start default

doc/image-guide-rst/source/ubuntu-image.rst

@@ -0,0 +1,3 @@
+=====================
+Example: Ubuntu image
+=====================

doc/image-guide-rst/source/virt-install.rst

@@ -0,0 +1,78 @@
+========================================================
+Use virt-install and connect by using a local VNC client
+========================================================
+
+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` tool to boot
+the virtual machine through libvirt and connect to the graphical
+console from a VNC client installed on your local machine.
+
+Because VNC is a standard protocol, there are multiple clients
+available that implement the VNC spec, including
+`TigerVNC <http://sourceforge.net/apps/mediawiki/tigervnc/
+index.php?title=Welcome_to_TigerVNC>`_ (multiple platforms),
+`TightVNC <http://tightvnc.com/>`_ (multiple platforms),
+`RealVNC <http://realvnc.com/>`_ (multiple platforms),
+`Chicken <http://sourceforge.net/projects/chicken/>`_ (Mac OS X),
+`Krde <http://userbase.kde.org/Krdc>`_ (KDE),
+`Vinagre <http://projects.gnome.org/vinagre/>`_ (GNOME).
+
+The following example shows how to use the :command:`qemu-img`
+command to create an empty image file, and :command:`virt-install`
+command to start up a virtual machine using that image file. As root:
+
+.. code-block:: console
+
+   # qemu-img create -f qcow2 /data/centos-6.4.qcow2 10G
+   # 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
+
+   Starting install...
+   Creating domain...                     |    0 B     00:00
+   Domain installation still in progress. You can reconnect to
+   the console to complete the installation process.
+
+The KVM hypervisor starts the virtual machine with the
+libvirt name, ``centos-6.4``, with 1024 MB of RAM.
+The virtual machine also has a virtual CD-ROM drive associated
+with the ``/data/CentOS-6.4-x86_64-netinstall.iso`` file and
+a local 10&nbsp;GB hard disk in qcow2 format that is stored
+in the host at ``/data/centos-6.4.qcow2``.
+It configures networking to use libvirt 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 (``--no-autoconsole``).
+Finally, libvirt will attempt to optimize the configuration
+for a Linux guest running a RHEL 6.x distribution.
+
+.. note::
+
+   When using the libvirt ``default`` network, libvirt will
+   connect the virtual machine's interface to a bridge
+   called ``virbr0``. 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.
+
+Run the :command:`virt-install --os-variant list` command
+to see a range of allowed ``--os-variant`` options.
+
+Use the :command:`virsh vncdisplay vm-name` command
+to get the VNC port number.
+
+.. code-block:: console
+
+   # virsh vncdisplay centos-6.4
+   :1
+
+In the example above, the guest ``centos-6.4`` uses VNC
+display ``:1``, which corresponds to TCP port ``5901``.
+You should be able to connect a VNC client running on
+your local machine to display ``:1`` on the remote
+machine and step through the installation process.

doc/image-guide-rst/source/virt-manager.rst

@@ -0,0 +1,49 @@
+============================
+Use the virt-manager X11 GUI
+============================
+
+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` GUI, which is installable as the
+``virt-manager`` package on both Fedora-based and Debian-based systems.
+This GUI has an embedded VNC client that will let you view and
+interact with the guest's graphical console.
+
+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` 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:
+
+.. code-block:: console
+
+   $ ssh -X root@server virt-manager
+
+If the account you use to ssh into your server does not have
+permissions to run libvirt, but has sudo privileges, do:
+
+.. code-block:: console
+
+   $ ssh -X root@server
+   $ sudo virt-manager
+
+.. note::
+
+   The ``-X`` flag passed to ssh will enable X11 forwarding over ssh.
+   If this does not work, try replacing it with the ``-Y`` flag.
+
+Click the ``New`` button at the top-left and step through the instructions.
+
+.. figure:: figures/virt-manager.png
+   :width: 100%
+
+You will be shown a series of dialog boxes that will allow you
+to specify information about the virtual machine.
+
+.. note::
+
+   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.

doc/image-guide-rst/source/windows-image.rst

@@ -0,0 +1,3 @@
+================================
+Example: Microsoft Windows image
+================================