diff --git a/doc/image-guide-rst/source/centos-image.rst b/doc/image-guide-rst/source/centos-image.rst new file mode 100644 index 0000000000..2c8e872e45 --- /dev/null +++ b/doc/image-guide-rst/source/centos-image.rst @@ -0,0 +1,3 @@ +===================== +Example: CentOS image +===================== diff --git a/doc/image-guide-rst/source/create-images-manually.rst b/doc/image-guide-rst/source/create-images-manually.rst index f81fcfec7f..46f6ff9406 100644 --- a/doc/image-guide-rst/source/create-images-manually.rst +++ b/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 `_ +(Virtual Network Computing) protocol or the newer +`SPICE `_ protocol. +We will use the VNC protocol here, since you are more likely +to find a VNC client that works on your local desktop. diff --git a/doc/image-guide-rst/source/fedora-image.rst b/doc/image-guide-rst/source/fedora-image.rst new file mode 100644 index 0000000000..0743255bf9 --- /dev/null +++ b/doc/image-guide-rst/source/fedora-image.rst @@ -0,0 +1,3 @@ +===================== +Example: Fedora image +===================== diff --git a/doc/image-guide-rst/source/figures/virt-manager.png b/doc/image-guide-rst/source/figures/virt-manager.png new file mode 100644 index 0000000000..95c5203111 Binary files /dev/null and b/doc/image-guide-rst/source/figures/virt-manager.png differ diff --git a/doc/image-guide-rst/source/freebsd-image.rst b/doc/image-guide-rst/source/freebsd-image.rst new file mode 100644 index 0000000000..53ad01835d --- /dev/null +++ b/doc/image-guide-rst/source/freebsd-image.rst @@ -0,0 +1,3 @@ +====================== +Example: FreeBSD image +====================== diff --git a/doc/image-guide-rst/source/net-running.rst b/doc/image-guide-rst/source/net-running.rst new file mode 100644 index 0000000000..8f6093cc4a --- /dev/null +++ b/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 diff --git a/doc/image-guide-rst/source/ubuntu-image.rst b/doc/image-guide-rst/source/ubuntu-image.rst new file mode 100644 index 0000000000..5ff52d75a7 --- /dev/null +++ b/doc/image-guide-rst/source/ubuntu-image.rst @@ -0,0 +1,3 @@ +===================== +Example: Ubuntu image +===================== diff --git a/doc/image-guide-rst/source/virt-install.rst b/doc/image-guide-rst/source/virt-install.rst new file mode 100644 index 0000000000..1bb8f9f6a0 --- /dev/null +++ b/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 `_ (multiple platforms), +`TightVNC `_ (multiple platforms), +`RealVNC `_ (multiple platforms), +`Chicken `_ (Mac OS X), +`Krde `_ (KDE), +`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 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. diff --git a/doc/image-guide-rst/source/virt-manager.rst b/doc/image-guide-rst/source/virt-manager.rst new file mode 100644 index 0000000000..f1f44edd20 --- /dev/null +++ b/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. diff --git a/doc/image-guide-rst/source/windows-image.rst b/doc/image-guide-rst/source/windows-image.rst new file mode 100644 index 0000000000..fe1517b42a --- /dev/null +++ b/doc/image-guide-rst/source/windows-image.rst @@ -0,0 +1,3 @@ +================================ +Example: Microsoft Windows image +================================