Fix headings in Image Guide

Partial-Bug: #1250515

author: diane fleming

Change-Id: I2378972adfd53803e5b3f7ff46439720d02dfe30
backport: none
This commit is contained in:
Diane Fleming 2013-11-13 14:54:50 -06:00
parent 4711f68e90
commit 8a16024a3a
7 changed files with 157 additions and 114 deletions

View File

@ -1,88 +1,118 @@
<?xml version="1.0" encoding="UTF-8"?>
<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>Creating 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>
<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>Ensuring 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:<screen><prompt>#</prompt> <userinput>virsh net-list</userinput>
<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>
<para>If the network is not active, start it by
doing:<screen><prompt>#</prompt> <userinput>virsh net-start default</userinput></screen>
</para>
<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>Using 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>
<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>
<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"/>
<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>
</mediaobject>You will be shown a series of dialog boxes
that will allow you to specify information about the
virtual machine.</para>
</section>
<section xml:id="virt-install">
<title>Using virt-install and connecting using a local VNC client</title>
<para>If you do not with to use virt-manager (e.g., you don't 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>Since VNC is a standard protocol, there are multiple clients available that implement
the VNC spec, including <link
<title>Use virt-install and connect by using a local VNC
client</title>
<para>If you do not with 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>
>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 \
@ -94,32 +124,45 @@ 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>This uses the KVM hypervisor to start up a virtual machine with the libvirt name of
<literal>centos-6.4</literal> with 1024MB of RAM, with a virtual CD-ROM drive
associated with the <filename>/data/CentOS-6.4-x86_64-netinstall.iso</filename> file,
and a local hard disk which is stored in the host at
<filename>/data/centos-6.4.qcow2</filename> that is 10GB in size in qcow2 format. 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>
<para>This uses the KVM hypervisor to start up a virtual
machine with the libvirt name of
<literal>centos-6.4</literal> with 1024MB of RAM, with
a virtual CD-ROM drive associated with the
<filename>/data/CentOS-6.4-x86_64-netinstall.iso</filename>
file, and a local hard disk which is stored in the host at
<filename>/data/centos-6.4.qcow2</filename> that is
10GB in size in qcow2 format. 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
<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>
<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>
<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"/>

View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<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_modifying_images">
<title>Modifying images</title>
<title>Modify images</title>
<?dbhtml stop-chunking?>
<para>Once you have obtained a virtual machine image, you may want to make some changes to it
before uploading it to the OpenStack Image service. Here we describe several tools available
@ -82,7 +82,7 @@ Type: 'help' for help on commands
command:<screen><prompt>>&lt;fs></prompt> <userinput>exit</userinput></screen></para>
</simplesect>
<simplesect>
<title>Going further with guestfish</title>
<title>Go further with guestfish</title>
<para>There is an enormous amount of functionality in guestfish and a full treatment is
beyond the scope of this document. Instead, we recommend that you read the <link
xlink:href="http://libguestfs.org/guestfs-recipes.1.html">guestfs-recipes</link>
@ -209,7 +209,7 @@ disk, carefully check that the resized disk boots and works correctly.
OS</link> by Daniel Berrangé for more details.</para>
</warning></para>
<simplesect>
<title>Mounting a raw image (without LVM)</title>
<title>Mount a raw image (without LVM)</title>
<para>If you have a raw virtual machine image that is not using LVM to manage its
partitions. First, use the <command>losetup</command> command to find an unused loop
device.
@ -239,7 +239,7 @@ brw-rw---- 1 root disk 43, 51 2012-03-05 15:32 /dev/mapper/loop0p3</computeroutp
<prompt>#</prompt> <userinput>losetup -d /dev/loop0</userinput></screen></para>
</simplesect>
<simplesect>
<title>Mounting a raw image (with LVM)</title>
<title>Mount a raw image (with LVM)</title>
<para>If your partitions are managed with LVM, use losetup and kpartx as in the previous
example to expose the partitions to the
host:</para><screen><prompt>#</prompt> <userinput>losetup -f</userinput>
@ -261,7 +261,7 @@ brw-rw---- 1 root disk 43, 51 2012-03-05 15:32 /dev/mapper/loop0p3</computeroutp
<prompt>#</prompt> <userinput>losetup -d /dev/loop0</userinput></screen>
</simplesect>
<simplesect>
<title>Mounting a qcow2 image (without LVM)</title>
<title>Mount a qcow2 image (without LVM)</title>
<para>You need the <literal>nbd</literal> (network block device) kernel module loaded to
mount qcow2 images. This will load it with support for 16 block devices, which is
fine for our purposes. As
@ -290,7 +290,7 @@ brw-rw---- 1 root disk 43, 51 2012-03-05 15:32 /dev/nbd0p3</computeroutput></scr
<prompt>#</prompt> <userinput>qemu-nbd -d /dev/g nbd0</userinput></screen>
</simplesect>
<simplesect>
<title>Mounting a qcow2 image (with LVM)</title>
<title>Mount a qcow2 image (with LVM)</title>
<para>If the image partitions are managed with LVM, after you use
<command>qemu-nbd</command> and <command>partprobe</command>, you must use
<command>vgscan</command> and <command>vgchange -ay</command> in order to expose

View File

@ -3,7 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_obtaining_images">
<title>Obtaining images</title>
<title>Get images</title>
<?dbhtml stop-chunking?>
<para>The simplest way to obtain a virtual machine image that works with OpenStack is to
download one that someone else has already created.</para>
@ -93,7 +93,7 @@
>rackerjoe/oz-image-build on Github</link>.</para>
</section>
<section xml:id="windows-images">
<title>Microsoft Windows Images</title>
<title>Microsoft Windows images</title>
<para>Cloudbase Solutions hosts an <link xlink:href="http://www.cloudbase.it/ws2012/"
>OpenStack Windows Server 2012 Standard Evaluation image</link> that runs on
Hyper-V, KVM, and XenServer/XCP.</para>

View File

@ -215,7 +215,7 @@
configured to download the ssh public key from the OpenStack metadata service or config
drive, at boot time.</para>
<simplesect>
<title>Using cloud-init to fetch the public key</title>
<title>Use cloud-init to fetch the public key</title>
<para>The cloud-init package will automatically fetch the public key from the metadata
server and place the key in an account. The account varies by distribution. On
Ubuntu-based virtual machines, the account is called "ubuntu". On Fedora-based
@ -229,7 +229,7 @@
line:<programlisting>user: admin</programlisting></para>
</simplesect>
<simplesect>
<title>Writing a custom script to fetch the public key</title>
<title>Write a custom script to fetch the public key</title>
<para>If you are unable or unwilling to install cloud-init inside the guest, you can
write a custom script to fetch the public and add it to a user account.</para>
<para>To fetch the ssh public key and add it to the root account, edit the
@ -318,7 +318,7 @@ done</programlisting>
that the image boots a kernel that has been compiled with Xen support.</para>
</section>
<section xml:id="image-cache-management">
<title>Managing the image cache</title>
<title>Manage the image cache</title>
<para>Use options in <filename>nova.conf</filename> to control whether, and for how long,
unused base images are stored in <filename>/var/lib/nova/instances/_base/</filename>. If
you have configured live migration of instances, all your compute nodes share one common

View File

@ -214,7 +214,7 @@
</itemizedlist></para>
</simplesect>
<simplesect>
<title>Using cloud-init to fetch the public key</title>
<title>Use cloud-init to fetch the public key</title>
<para>The cloud-init package will automatically fetch the public key from the metadata
server and place the key in an account. You can install cloud-init inside the CentOS
guest by adding the EPEL
@ -230,7 +230,7 @@
line:<programlisting>user: admin</programlisting></para>
</simplesect>
<simplesect>
<title>Writing a script to fetch the public key (if no cloud-init)</title>
<title>Write a script to fetch the public key (if no cloud-init)</title>
<para>If you are not able to install the cloud-init package in your image, to fetch the
ssh public key and add it to the root account, edit the
<filename>/etc/rc.local</filename> file and add the following lines before the line
@ -290,7 +290,7 @@ kernel <replaceable>...</replaceable> console=tty0 console=ttyS0,115200n8</progr
root:<screen><prompt>#</prompt> <userinput>/sbin/shutdown -h now</userinput></screen></para>
</simplesect>
<simplesect>
<title>Clean up (e.g., remove MAC address details)</title>
<title>Clean up (remove MAC address details)</title>
<para>The operating system records the MAC address of the virtual ethernet card in locations
such as <filename>/etc/sysconfig/network-scripts/ifcfg-eth0</filename> and
<filename>/etc/udev/rules.d/70-persistent-net.rules</filename> during the instance

View File

@ -3,12 +3,12 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="image-formats">
<title>Disk and Container Formats for Images</title>
<title>Disk and container formats for images</title>
<?dbhtml stop-chunking?>
<para>When you add an image to the Image Service, you can specify
its disk and container formats.</para>
<section xml:id="disk-format">
<title>Disk Formats</title>
<title>Disk formats</title>
<para>The disk format of a virtual machine image is the format
of the underlying disk image. Virtual appliance vendors
have different formats for laying out the information
@ -62,7 +62,7 @@
</itemizedlist>
</section>
<section xml:id="container-format">
<title>Container Formats</title>
<title>Container formats</title>
<para>The container format indicates whether the virtual
machine image is in a file format that also contains
metadata about the actual virtual machine.</para>

View File

@ -54,7 +54,7 @@
</simplesect>
<simplesect>
<title>Selecting a mirror</title>
<title>Select a mirror</title>
<para>The default mirror proposed by the installer should be fine.</para>
</simplesect>
<simplesect>
@ -171,7 +171,7 @@
root:<screen><prompt>#</prompt> <userinput>/sbin/shutdown -h now</userinput></screen></para>
</simplesect>
<simplesect>
<title>Clean up (e.g., remove MAC address details)</title>
<title>Clean up (remove MAC address details)</title>
<para>The operating system records the MAC address of the virtual ethernet card in locations
such as <filename>/etc/udev/rules.d/70-persistent-net.rules</filename> during the
instance process. However, each time the image boots up, the virtual ethernet card will