9baec75cdb
* Grammar mistakes corrected. * Not all corrections in the bug were made as it changed the meaning and/or were grammatically incorrect themselves. * Fix incorrect links Change-Id: I3ded1c9c65df64e71b64545d45b3cbdb678444fe Closes-bug: #1387850
269 lines
13 KiB
XML
269 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section [
|
|
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
|
|
%openstack;
|
|
]>
|
|
<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="example-freebsd-image">
|
|
<title>Example: FreeBSD image</title>
|
|
<para>This example creates a minimal FreeBSD image that is
|
|
compatible with OpenStack and
|
|
<application>bsd-cloudinit</application>. The
|
|
<application>bsd-cloudinit</application> program is
|
|
independently maintained and in active development. The best
|
|
source of information on the current state of the project is at
|
|
<link xlink:href="http://pellaeon.github.io/bsd-cloudinit/"
|
|
>http://pellaeon.github.io/bsd-cloudinit/</link>.</para>
|
|
<para>KVM with virtio drivers is used as the virtualization platform
|
|
because that is the most widely used among OpenStack operators. If
|
|
you use a different platform for your cloud virtualization, use
|
|
that same platform in the image creation step.</para>
|
|
<para>This example shows how to create a FreeBSD 10 image. To create
|
|
a FreeBSD 9.2 image, follow these steps with the noted
|
|
differences.</para>
|
|
<procedure>
|
|
<title>To create a FreeBSD image</title>
|
|
<step>
|
|
<para>Make a virtual drive:</para>
|
|
<screen><prompt>$</prompt> <userinput>qemu-img create -f qcow2 freebsd.qcow2 1G</userinput></screen>
|
|
<para>The minimum supported disk size for FreeBSD is 1 GB.
|
|
Because the goal is to make the smallest possible base image,
|
|
the example uses that minimum size. This size is sufficient to
|
|
include the optional <literal>doc</literal>,
|
|
<literal>games</literal>, and <literal>lib32</literal>
|
|
collections. To include the <literal>ports</literal>
|
|
collection, add another 1 GB. To include
|
|
<literal>src</literal>, add 512 MB.</para>
|
|
</step>
|
|
<step>
|
|
<para>Get the installer ISO:</para>
|
|
<screen><prompt>$</prompt> <userinput>curl ftp://ftp.freebsd.org/pub/FreeBSD/releases\
|
|
/amd64/amd64/ISO-IMAGES/10.0/FreeBSD-10.0-RELEASE-amd64-bootonly.iso >\
|
|
FreeBSD-10.0-RELEASE-amd64-bootonly.iso</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Launch a VM on your local workstation. Use the same
|
|
hypervisor, virtual disk, and virtual network drivers as you
|
|
use in your production environment.</para>
|
|
<para>The following command uses the minimum amount of RAM,
|
|
which is 128 MB:</para>
|
|
<screen><prompt>$</prompt> <userinput>kvm -smp 1 -m 128 -cdrom FreeBSD-10.0-RELEASE-amd64-bootonly.iso \
|
|
-drive if=virtio,file=freebsd.qcow2 \
|
|
-net nic,model=virtio -net user</userinput></screen>
|
|
<para>You can specify up to 1 GB additional RAM to make the
|
|
installation process run faster.</para>
|
|
<para>This VM must also have Internet access to download
|
|
packages.</para>
|
|
<note>
|
|
<para>By using the same hypervisor, you can ensure that you
|
|
emulate the same devices that exist in production. However,
|
|
if you use full hardware virtualization instead of
|
|
paravirtualization, you do not need to use the same
|
|
hypervisor; you must use the same type of virtualized
|
|
hardware because FreeBSD device names are related to their
|
|
drivers. If the name of your root block device or primary
|
|
network interface in production differs than the names used
|
|
during image creation, errors can occur.</para>
|
|
</note>
|
|
<para>You now have a VM that boots from the downloaded install
|
|
ISO and is connected to the blank virtual disk that you
|
|
created previously.</para>
|
|
</step>
|
|
<step>
|
|
<para>To install the operating system, complete the following
|
|
steps inside the VM:</para>
|
|
<substeps>
|
|
<step>
|
|
<para>When prompted, choose to run the ISO in
|
|
<guibutton>Install</guibutton> mode.</para>
|
|
</step>
|
|
<step>
|
|
<para>Accept the default keymap or select an appropriate
|
|
mapping for your needs.</para>
|
|
</step>
|
|
<step>
|
|
<para>Provide a host name for your image. If you use
|
|
<application>bsd-cloudinit</application>, it overrides
|
|
this value with the name provided by OpenStack when an
|
|
instance boots from this image.</para>
|
|
</step>
|
|
<step>
|
|
<para>When prompted about the optional
|
|
<literal>doc</literal>, <literal>games</literal>,
|
|
<literal>lib32</literal>, <literal>ports</literal>, and
|
|
<literal>src</literal> system components, select only
|
|
those that you need. It is possible to have a fully
|
|
functional installation without selecting additional
|
|
components selected. As noted previously, a minimal system
|
|
with a 1 GB virtual disk supports
|
|
<literal>doc</literal>, <literal>games</literal>, and
|
|
<literal>lib32</literal> inclusive. The
|
|
<literal>ports</literal> collection requires at least
|
|
1 GB additional space and possibly more if you plan
|
|
to install many ports. The <literal>src</literal>
|
|
collection requires an additional 512 MB.</para>
|
|
</step>
|
|
<step>
|
|
<para>Configure the primary network interface to use DHCP.
|
|
In this example, which uses a virtio network device, this
|
|
interface is named <literal>vtnet0</literal>.</para>
|
|
</step>
|
|
<step>
|
|
<para>Accept the default network mirror.</para>
|
|
</step>
|
|
<step>
|
|
<para>Set up disk partitioning.</para>
|
|
<para>Disk partitioning is a critical element of the image
|
|
creation process and the auto-generated default
|
|
partitioning scheme does not work with
|
|
<application>bsd-cloudinit</application> at this
|
|
time.</para>
|
|
<para>Because the default does not work, you must select
|
|
manual partitioning. The partition editor should list only
|
|
one block device. If you use virtio for the disk device
|
|
driver, it is named <literal>vtbd0</literal>. Select this
|
|
device and run the <command>create</command> command three
|
|
times:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select <guibutton>Create</guibutton> to create a
|
|
partition table. This action is the default when no
|
|
partition table exists. Then, select <guilabel>GPT
|
|
GUID Partition Table</guilabel> from the list. This
|
|
choice is the default.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Create two partitions:<itemizedlist>
|
|
<listitem>
|
|
<para>First partition: A 64 kB
|
|
<literal>freebsd-boot</literal> partition with
|
|
no mount point.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Second partition: A
|
|
<literal>freebsd-ufs</literal> partition with
|
|
a mount point of <filename>/</filename> with all
|
|
remaining free space.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>The following figure shows a completed partition table
|
|
with a 1 GB virtual disk:</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/freebsd-partitions.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
<para>Select <guibutton>Finish</guibutton> and then
|
|
<guibutton>Commit</guibutton> to commit your
|
|
changes.</para>
|
|
<note>
|
|
<para>If you modify this example, the root partition,
|
|
which is mounted on <filename>/</filename>, must be the
|
|
last partition on the drive so that it can expand at run
|
|
time to the disk size that your instance type provides.
|
|
Also note that <application>bsd-cloudinit</application>
|
|
currently has a hard-coded assumption that this is the
|
|
second partition.</para>
|
|
</note>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
<step>
|
|
<para>Select a root password.</para>
|
|
</step>
|
|
<step>
|
|
<para>Select the CMOS time zone.</para>
|
|
<para>The virtualized CMOS almost always stores its time in UTC,
|
|
so unless you know otherwise, select UTC.</para>
|
|
</step>
|
|
<step>
|
|
<para>Select the time zone appropriate to your
|
|
environment.</para>
|
|
</step>
|
|
<step>
|
|
<para>From the list of services to start on boot, you must
|
|
select <systemitem class="service">ssh</systemitem>.
|
|
Optionally, select other services.</para>
|
|
</step>
|
|
<step>
|
|
<para>Optionally, add users.</para>
|
|
<para>You do not need to add users at this time. The
|
|
<application>bsd-cloudinit</application> program adds a
|
|
<literal>freebsd</literal> user account if one does not
|
|
exist. The <systemitem class="service">ssh</systemitem> keys
|
|
for this user are associated with OpenStack. To customize this
|
|
user account, you can create it now. For example, you might
|
|
want to customize the shell for the user.</para>
|
|
</step>
|
|
<step>
|
|
<title>Final config</title>
|
|
<para>This menu enables you to update previous settings. Check
|
|
that the settings are correct, and click
|
|
<guibutton>exit</guibutton>.</para>
|
|
</step>
|
|
<step>
|
|
<para>After you exit, you can open a shell to complete manual
|
|
configuration steps. Select <guibutton>Yes</guibutton> to make
|
|
a few OpenStack-specific changes:</para>
|
|
<substeps>
|
|
<step>
|
|
<para>Set up the console:</para>
|
|
<screen><prompt>#</prompt> <userinput>echo 'console="comconsole,vidconsole"' >> /boot/loader.conf</userinput></screen>
|
|
<para>This sets console output to go to the serial console,
|
|
which is displayed by <command>nova consolelog</command>,
|
|
and the video console for sites with VNC or Spice
|
|
configured.</para>
|
|
</step>
|
|
<step>
|
|
<para>Minimize boot delay:</para>
|
|
<screen><prompt>#</prompt> <userinput>echo 'autoboot_delay="1"' >> /boot/loader.conf</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Download the latest
|
|
<application>bsd-cloudinit-installer</application>. The
|
|
download commands differ between FreeBSD 10.0 and 9.2
|
|
because of differences in how the <command>fetch</command>
|
|
command handles HTTPS URLs.</para>
|
|
<para>In FreeBSD 10.0 the <command>fetch</command> command
|
|
verifies SSL peers by default, so you need to install the
|
|
<package>ca_root_nss</package> package that contains
|
|
certificate authority root certificates and tell
|
|
<command>fetch</command> where to find them. For FreeBSD
|
|
10.0 run these commands:</para>
|
|
<screen><prompt>#</prompt> <userinput>pkg install ca_root_nss</userinput>
|
|
<prompt>#</prompt> <userinput>fetch --ca-cert=/usr/local/share/certs/ca-root-nss.crt \
|
|
https://raw.github.com/pellaeon/bsd-cloudinit-installer/master/installer.sh</userinput></screen>
|
|
<para>FreeBSD 9.2 <command>fetch</command> does not support
|
|
peer-verification for https. For FreeBSD 9.2, run this
|
|
command:</para>
|
|
<screen><prompt>#</prompt> <userinput>fetch https://raw.github.com/pellaeon/bsd-cloudinit-installer/master/installer.sh</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Run the installer:</para>
|
|
<screen><prompt>#</prompt> <userinput>sh ./installer.sh</userinput></screen>
|
|
<para>Issue this command to download and install the latest
|
|
<package>bsd-cloudinit</package> package, and install the
|
|
necessary prerequisites.</para>
|
|
</step>
|
|
<step>
|
|
<para>Install <package>sudo</package> and configure the
|
|
<literal>freebsd</literal> user to have passwordless
|
|
access:</para>
|
|
<screen><prompt>#</prompt> <userinput>pkg install sudo</userinput>
|
|
<prompt>#</prompt> <userinput>echo 'freebsd ALL=(ALL) NOPASSWD: ALL' > /usr/local/etc/sudoers.d/10-cloudinit</userinput></screen>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
<step>
|
|
<para>Power off the system:</para>
|
|
<screen><prompt>#</prompt> <userinput>shutdown -s now</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
</section>
|