openstack-manuals/doc/image-guide/section_centos-example.xml

<?xml version="1.0" encoding="UTF-8"?>
    <section
        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="centos-image">
        <title>Example: CentOS image</title>
        <para>We'll run through an example of installing a CentOS image. This will focus mainly on
        CentOS 6.4. Because the CentOS installation process may change across versions, if you are
        using a different version of CentOS the installer steps may differ.</para>
        <simplesect>
            <title>Download a CentOS install ISO</title>
            <para>
            <orderedlist>
                <listitem>
                    <para>Navigate to the <link
                            xlink:href="http://www.centos.org/modules/tinycontent/index.php?id=30"
                            >CentOS mirrors</link> page.</para>
                </listitem>
                <listitem>
                    <para>Click one of the <literal>HTTP</literal> links in the right-hand column
                        next to one of the mirrors.</para>
                </listitem>
                <listitem>
                    <para>Click the folder link of the CentOS version you want to use (e.g.,
                            <literal>6.4/</literal>).</para>
                </listitem>
                <listitem>
                    <para>Click the <literal>isos/</literal> folder link.</para>
                </listitem>
                <listitem>
                    <para>Click the <literal>x86_64/</literal> folder link for 64-bit images.</para>
                </listitem>
                <listitem>
                    <para>Click the ISO image you want to download. The netinstall ISO (e.g.,
                            <filename>CentOS-6.4-x86_64-netinstall.iso</filename>) is a good choice
                        since it's a smaller image that will download missing packages from the
                        Internet during the install process.</para>
                </listitem>
            </orderedlist>
        </para>
        </simplesect>
    <simplesect>
        <title>Start the install process</title>
        <para>Start the installation process using either <command>virt-manager</command> or
                <command>virt-install</command> as described in the previous section. If using
                <command>virt-install</command>, don't forget to connect your VNC client to the
            virtual machine.</para>
        <para>We will assume the name of your virtual machine image is
            <literal>centos-6.4</literal>, which we need to know when using <command>virsh</command>
            commands to manipulate the state of the image.</para>
        <para>If you're using virt-manager, the commands should look something like
            this:<screen><prompt>#</prompt> <userinput>qemu-img create -f qcow2 /tmp/centos-6.4.qcow2 10G</userinput>
<prompt>#</prompt> <userinput>virt-install --virt-type kvm --name centos-6.4 --ram 1024 \
--cdrom=/data/isos/CentOS-6.4-x86_64-netinstall.iso \
--disk /tmp/centos-6.4.qcow2,format=qcow2 \
--network network=default \
--graphics vnc,listen=0.0.0.0 --noautoconsole \
--os-type=linux --os-variant=rhel6</userinput></screen></para>
    </simplesect>
        <simplesect>
            <title>Step through the install</title>
            <para>At the initial Installer boot menu, choose the "Install or upgrade an existing system" option. Step through the
                install prompts, the defaults should be fine.</para>
            <mediaobject>
                <imageobject role="fo">
                    <imagedata fileref="figures/centos-install.png" format="PNG" scale="60"/>
                </imageobject>
                <imageobject role="html">
                    <imagedata fileref="figures/centos-install.png" format="PNG"/>
                </imageobject>
            </mediaobject>
        </simplesect>
        <simplesect>
            <title>Configure TCP/IP</title>
            <para>The default TCP/IP settings are fine. In particular, ensure
            that Enable IPv4 support is enabled with DHCP, which is the default.</para>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="figures/centos-tcpip.png" format="PNG" contentwidth="6in"/>
                </imageobject>
            </mediaobject>

        </simplesect>
        <simplesect>
            <title>Point the installer to a CentOS web server</title>
        <para>Choose URL as the installation method.</para>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="figures/install-method.png" format="PNG" contentwidth="6in"/>
                </imageobject>
            </mediaobject>
            <para>Depending on the version of CentOS, the net installer requires that the user
            specify either a URL, or the web site and a CentOS directory that corresponds to one of
            the CentOS mirrors. If the installer asks for a single URL, an example of a valid URL
            would be: <literal>http://mirror.umd/centos/6/os/x86_64</literal>.<note>
                <para>Consider using other mirrors as an alternative to mirror.umd.edu.</para>
            </note></para>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="figures/url-setup.png" format="PNG" contentwidth="6in"/>
                </imageobject>
            </mediaobject>

            <para>If the installer asks for web site name and CentOS directory separately, an example
            would be:</para>
        <para>
            <itemizedlist>
                <listitem>
                    <para>Web site name: <literal>mirror.umd.edu</literal>
                    </para>
                </listitem>
                <listitem>
                    <para>CentOS directory: <literal>centos/6/os/x86_64</literal></para>
                </listitem>
            </itemizedlist>
        </para>
            <para>See <link xlink:href="http://www.centos.org/modules/tinycontent/index.php?id=30"
                    >CentOS mirror page</link> to get a full list of mirrors, click on the "HTTP"
                link of a mirror to retrieve the web site name of a mirror.</para>
        </simplesect>
        <simplesect>
            <title>Storage devices</title>
            <para>If asked about what type of devices your installation involves, choose "Basic
            Storage Devices".</para>
        </simplesect>
        <simplesect>
            <title>Hostname</title>
            <para>The installer may ask you to choose a hostname. The default
                (<literal>localhost.localdomain</literal>) is fine. We will install the cloud-init
            packge later, which will set the hostname on boot when a new instance is provisioned
            using this image.</para>
        </simplesect>
        <simplesect>
            <title>Partition the disks</title>
            <para>There are different options for partitioning the disks. The default installation
            will use LVM partitions, and will create three partitions (<filename>/boot</filename>,
                <filename>/</filename>, swap), and this will work fine. Alternatively, you may wish
            to create a single ext4 partition, mounted to "<literal>/</literal>", should also work
            fine.</para>
        <para>If unsure, we recommend you use the installer's default partition scheme, since there
            is no clear advantage to one scheme of another.</para>
        </simplesect>
        <simplesect>
            <title>Step through the install</title>
            <para>Step through the install, using the default options. The simplest thing to do is
            to choose the "Basic Server" install (may be called "Server" install on older versions
            of CentOS), which will install an SSH server.</para>
        </simplesect>
        <simplesect>
            <title>Detach the CD-ROM and reboot</title>
            <para>Once the install completes, you will see the screen "Congratulations, your CentOS
            installation is complete".</para>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="figures/centos-complete.png" format="PNG" contentwidth="6in"/>
                </imageobject>
            </mediaobject>

            <para>To eject a disk using <command>virsh</command>, libvirt requires that you attach an
                empty disk at the same target that the CDROM was previously attached, which should be
                <literal>hdc</literal>. You can confirm the appropriate target using the
                <command>dom dumpxml <replaceable>vm-image</replaceable></command> command.</para>
            <screen><prompt>#</prompt> <userinput>virsh dumpxml centos-6.4</userinput>
<computeroutput>&lt;domain type='kvm'>
  &lt;name>centos-6.4&lt;/name>
...
    &lt;disk type='block' device='cdrom'>
      &lt;driver name='qemu' type='raw'/>
      &lt;target dev='hdc' bus='ide'/>
      &lt;readonly/>
      &lt;address type='drive' controller='0' bus='1' target='0' unit='0'/>
    &lt;/disk>
...
&lt;/domain>
</computeroutput></screen>
            <para>Run the following
            commands from the host to eject the disk and reboot using virsh, as root. If you are
            using virt-manager, the commands below will work, but you can also use the GUI to the
            detach and reboot it by manually stopping and
            starting.<screen><prompt>#</prompt> <userinput>virsh attach-disk --type cdrom --mode readonly centos-6.4 "" hdc</userinput>
<prompt>#</prompt> <userinput>virsh destroy centos-6.4</userinput>
<prompt>#</prompt> <userinput>virsh start centos-6.4</userinput></screen></para>
            <note><para>In theory, the <command>virsh reboot centos-6.4</command> command can be used instead of using
                destroy and start commands. However, in our testing we were unable to reboot
                successfully using the <command>virsh reboot</command> command.</para></note>

        </simplesect>
        <simplesect>
            <title>Log in to newly created image</title>
            <para>When you boot the first time after install, it may ask you about authentication
            tools, you can just choose "Exit". Then, log in as root using the root password you
            specified.</para>
        </simplesect>
        <simplesect>
            <title>Configure to fetch metadata</title>
            <para>An instance must perform several steps on start up by
            interacting with the metadata service (e.g., retrieve ssh public
            key, execute user data script). There are several ways to implement
            this functionality, including:<itemizedlist>
                <listitem>
                    <para>Install a cloud-init RPM, which is a port of the
                        Ubuntu <link
                            xlink:href="https://launchpad.net/cloud-init"
                            >cloud-init</link> package. This is the recommended
                        approach.</para>
                </listitem>
                <listitem>
                    <para>Modify <filename>/etc/rc.local</filename> to fetch
                        desired information from the metadata service, as
                        described below.</para>
                </listitem>
            </itemizedlist></para>
        </simplesect>
        <simplesect>
            <title>Using 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
            repo:<screen><prompt>#</prompt> <userinput>rpm -Uvh http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm</userinput>
<prompt>#</prompt> <userinput>yum install cloud-init</userinput></screen></para>
            <para>The account varies by distribution. On Ubuntu-based virtual machines, the
                account is called "ubuntu". On Fedora-based virtual machines, the account is called
                "ec2-user".</para>
            <para>You can change the name of the account used by cloud-init by editing the
                    <filename>/etc/cloud/cloud.cfg</filename> file and adding a line with a
                different user. For example, to configure cloud-init to put the key in an account
                named "admin", edit the config file so it has the
                line:<programlisting>user: admin</programlisting></para>
        </simplesect>
        <simplesect>
            <title>Writing 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
                “<literal>touch /var/lock/subsys/local</literal>”</para>
            <programlisting>if [ ! -d /root/.ssh ]; then
  mkdir -p /root/.ssh
  chmod 700 /root/.ssh
fi

# Fetch public key using HTTP
ATTEMPTS=30
FAILED=0
while [ ! -f /root/.ssh/authorized_keys ]; do
  curl -f http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key > /tmp/metadata-key 2>/dev/null
  if [ \$? -eq 0 ]; then
    cat /tmp/metadata-key >> /root/.ssh/authorized_keys
    chmod 0600 /root/.ssh/authorized_keys
    restorecon /root/.ssh/authorized_keys
    rm -f /tmp/metadata-key
    echo "Successfully retrieved public key from instance metadata"
    echo "*****************"
    echo "AUTHORIZED KEYS"
    echo "*****************"
    cat /root/.ssh/authorized_keys
    echo "*****************"
done

</programlisting>
            <note>
                <para>Some VNC clients replace : (colon) with ; (semicolon) and _ (underscore) with
                    - (hyphen). Make sure it's http: not http; and authorized_keys not
                    authorized-keys.</para>
            </note>
            <note>
                <para>The above script only retrieves the ssh public key from the metadata server.
                    It does not retrieve <emphasis role="italic">user data</emphasis>, which is
                    optional data that can be passed by the user when requesting a new instance.
                    User data is often used for running a custom script when an instance comes
                    up.</para>
                <para>As the OpenStack metadata service is compatible with version 2009-04-04 of the
                    Amazon EC2 metadata service, consult the Amazon EC2 documentation on <link
                        xlink:href="http://docs.amazonwebservices.com/AWSEC2/2009-04-04/UserGuide/AESDG-chapter-instancedata.html"
                        >Using Instance Metadata</link> for details on how to retrieve user
                    data.</para>
            </note>
        </simplesect>
        <simplesect>
            <title>Configure console</title>
            <para>In order for <command>nova console-log</command> to work properly on CentOS 6.x,
                guests you may need to add the following lines to
                    <filename>/boot/grub/menu.lst</filename><programlisting>serial --unit=0 --speed=115200
terminal --timeout=10 console serial
# Edit the kernel line to add the console entries
kernel <replaceable>...</replaceable> console=tty0 console=ttyS0,115200n8</programlisting></para>
        </simplesect>
        <simplesect>
            <title>Shut down the instance</title>
            <para>From inside the instance, as
                root:<screen><prompt>#</prompt> <userinput>/sbin/shutdown -h now</userinput></screen></para>
        </simplesect>
    <simplesect>
        <title>Clean up (e.g., 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
            process. However, each time the image boots up, the virtual ethernet card will have a
            different MAC address, so this information must be deleted from the configuration file.</para>
        <para>There is a utility called <command>virt-sysprep</command>, that performs various
            cleanup tasks such as removing the MAC address references. It will clean up a virtual
            machine image in
            place:<screen><prompt>#</prompt> <userinput>virt-sysprep -d centos-6.4</userinput></screen></para>
    </simplesect>
    <simplesect>
        <title>Undefine the libvirt domain</title>
        <para>Now that the image is ready to be uploaded to the Image service,
            we know longer need to have this virtual machine image managed by
            libvirt. Use the <command>virsh undefine
                    <replaceable>vm-image</replaceable></command> command to
            inform
            libvirt.<screen><prompt>#</prompt> <userinput>virsh undefine centos-6.4</userinput></screen></para>
    </simplesect>
        <simplesect>
            <title>Image is complete</title>
            <para>The underlying image file you created with <command>qemu-img create</command> (e.g.
                <filename>/tmp/centos-6.4.qcow2</filename>) is now ready for uploading to the OpenStack
                Image service.</para>
        </simplesect>
    </section>