305f9b9d26
It's "user name". Also fix markup for them to use systemitem. Change-Id: I9bb9ac86587686a43cdd9aabd1d975cb7a7c320a
251 lines
12 KiB
XML
251 lines
12 KiB
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="ubuntu-image">
|
|
<title>Example: Ubuntu image</title>
|
|
<para>We'll run through an example of installing an Ubuntu image.
|
|
This will focus mainly on Ubuntu 12.04 (Precise Pangolin)
|
|
server. Because the Ubuntu installation process may change
|
|
across versions, if you are using a different version of
|
|
Ubuntu the installer steps may differ.</para>
|
|
<simplesect>
|
|
<title>Download an Ubuntu install ISO</title>
|
|
<para>In this example, we'll use the network installation ISO,
|
|
since it's a smaller image. The 64-bit 12.04 network
|
|
installer ISO is at <link
|
|
xlink:href="http://archive.ubuntu.com/ubuntu/dists/precise/main/installer-amd64/current/images/netboot/mini.iso"
|
|
>http://archive.ubuntu.com/ubuntu/dists/precise/main/installer-amd64/current/images/netboot/mini.iso</link></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>ubuntu-12.04</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/precise.qcow2 10G</userinput>
|
|
<prompt>#</prompt> <userinput>virt-install --virt-type kvm --name precise --ram 1024 \
|
|
--cdrom=/data/isos/precise-64-mini.iso \
|
|
--disk /tmp/precise.qcow2,format=qcow2 \
|
|
--network network=default \
|
|
--graphics vnc,listen=0.0.0.0 --noautoconsole \
|
|
--os-type=linux --os-variant=ubuntuprecise</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Step through the install</title>
|
|
<para>At the initial Installer boot menu, choose the "Install"
|
|
option. Step through the install prompts, the defaults
|
|
should be fine.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/ubuntu-install.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Hostname</title>
|
|
<para>The installer may ask you to choose a hostname. The
|
|
default (<literal>ubuntu</literal>) is fine. We will
|
|
install the cloud-init package later, which will set the
|
|
hostname on boot when a new instance is provisioned using
|
|
this image.</para>
|
|
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Select a mirror</title>
|
|
<para>The default mirror proposed by the installer should be
|
|
fine.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Step through the install</title>
|
|
<para>Step through the install, using the default options.
|
|
When prompted for a user name, the default
|
|
(<systemitem class="username">ubuntu</systemitem>) is fine.</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 or another.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Automatic updates</title>
|
|
<para>The Ubuntu installer will ask how you want to manage
|
|
upgrades on your system. This option depends on your
|
|
specific use case. If your virtual machine instances will
|
|
be connected to the internet, we recommend "Install
|
|
security updates automatically".</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Software selection: OpenSSH server</title>
|
|
<para>Choose "OpenSSH server"so that you will be able to SSH
|
|
into the virtual machine when it launches inside of an
|
|
OpenStack cloud.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata
|
|
fileref="figures/ubuntu-software-selection.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Install GRUB boot loader</title>
|
|
<para>Select "Yes" when asked about installing the GRUB boot
|
|
loader to the master boot record.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/ubuntu-grub.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Detach the CD-ROM and reboot</title>
|
|
<para>Select the defaults for all of the remaining options.
|
|
When the installation is complete, you will be prompted to
|
|
remove the CD-ROM.</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/ubuntu-finished.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
<para>
|
|
<note>
|
|
<para>When you hit "Continue" the virtual machine will
|
|
shut down, even though it says it will
|
|
reboot.</para>
|
|
</note>
|
|
</para>
|
|
|
|
<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 precise</userinput>
|
|
<computeroutput><domain type='kvm'>
|
|
<name>precise</name>
|
|
...
|
|
<disk type='block' device='cdrom'>
|
|
<driver name='qemu' type='raw'/>
|
|
<target dev='hdc' bus='ide'/>
|
|
<readonly/>
|
|
<address type='drive' controller='0' bus='1' target='0' unit='0'/>
|
|
</disk>
|
|
...
|
|
</domain>
|
|
</computeroutput></screen>
|
|
|
|
<para>Run the following commands in the host as root to start
|
|
up the machine again as paused, eject the disk and resume.
|
|
If you are using virt-manager, you may use the GUI
|
|
instead.<screen><prompt>#</prompt> <userinput>virsh start precise --paused</userinput>
|
|
<prompt>#</prompt> <userinput>virsh attach-disk --type cdrom --mode readonly precise "" hdc</userinput>
|
|
<prompt>#</prompt> <userinput>virsh resume precise</userinput></screen></para>
|
|
<note>
|
|
<para>In the example above, we start the instance paused,
|
|
eject the disk, and then unpause. In theory, we could
|
|
have ejected the disk at the "Installation complete"
|
|
screen. However, our testing indicates that the Ubuntu
|
|
installer locks the drive so that it cannot be ejected
|
|
at that point.</para>
|
|
</note>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Log in to newly created image</title>
|
|
<para>When you boot for 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>Install cloud-init</title>
|
|
<para>The <command>cloud-init</command> script starts on
|
|
instance boot and will search for a metadata provider to
|
|
fetch a public key from. The public key will be placed in
|
|
the default user account for the image.</para>
|
|
<para>Install the <package>cloud-init</package> package:</para>
|
|
<screen><prompt>#</prompt> <userinput>apt-get install cloud-init</userinput></screen>
|
|
<para>When building Ubuntu images
|
|
<command>cloud-init</command> must be explicitly
|
|
configured for the metadata source in use. The OpenStack
|
|
metadata server emulates the EC2 metadata service used by
|
|
images in Amazon EC2.</para>
|
|
<para>To set the metadata source to be used by the image run
|
|
the <command>dpkg-reconfigure</command> command against
|
|
the <package>cloud-init</package> package. When prompted
|
|
select the <literal>EC2</literal> data source:
|
|
<screen><prompt>#</prompt> <userinput>dpkg-reconfigure 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>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 (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 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 precise</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 no 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 precise</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Image is complete</title>
|
|
<para>The underlying image file that you created with
|
|
<command>qemu-img create</command>, such as
|
|
<filename>/tmp/precise.qcow2</filename>, is now ready
|
|
for uploading to the OpenStack Image Service.</para>
|
|
</simplesect>
|
|
</section>
|