From 78179a67bf9658b8df86cc53b86e7deb19fa5ed2 Mon Sep 17 00:00:00 2001
From: Francesco Di Nucci <d1nuc0m@protonmail.com>
Date: Thu, 11 Jul 2024 12:34:21 +0200
Subject: [PATCH] docs: review manual image creation
* Add TOCs
* Divide Examples and Tools (make it easier to add others such as VBox,
VMware etc.)
* Merge all libvirt related content as a tool
* Modify headers as per Contributor Guide [1]
* Move pages to clarify hierarchy
Note: further work will be needed to update examples
[1] https://docs.openstack.org/doc-contrib-guide/rst-conv/titles.html
Change-Id: I78970ef578020c7df7e35ca59a1c7b8aed19bb6f
---
...-images-manually-example-centos-image.rst} | 46 +++++-----
...-images-manually-example-fedora-image.rst} | 38 ++++----
...images-manually-example-freebsd-image.rst} | 8 +-
...-images-manually-example-ubuntu-image.rst} | 20 ++--
...images-manually-example-windows-image.rst} | 11 +++
... create-images-manually-tools-libvirt.rst} | 91 ++++++++++++++++++-
.../source/create-images-manually.rst | 32 ++++---
doc/image-guide/source/net-running.rst | 28 ------
doc/image-guide/source/virt-manager.rst | 51 -----------
9 files changed, 182 insertions(+), 143 deletions(-)
rename doc/image-guide/source/{centos-image.rst => create-images-manually-example-centos-image.rst} (95%)
rename doc/image-guide/source/{fedora-image.rst => create-images-manually-example-fedora-image.rst} (94%)
rename doc/image-guide/source/{freebsd-image.rst => create-images-manually-example-freebsd-image.rst} (99%)
rename doc/image-guide/source/{ubuntu-image.rst => create-images-manually-example-ubuntu-image.rst} (96%)
rename doc/image-guide/source/{windows-image.rst => create-images-manually-example-windows-image.rst} (97%)
rename doc/image-guide/source/{virt-install.rst => create-images-manually-tools-libvirt.rst} (52%)
delete mode 100644 doc/image-guide/source/net-running.rst
delete mode 100644 doc/image-guide/source/virt-manager.rst
diff --git a/doc/image-guide/source/centos-image.rst b/doc/image-guide/source/create-images-manually-example-centos-image.rst
similarity index 95%
rename from doc/image-guide/source/centos-image.rst
rename to doc/image-guide/source/create-images-manually-example-centos-image.rst
index 99a9edefd9..0ada6c2957 100644
--- a/doc/image-guide/source/centos-image.rst
+++ b/doc/image-guide/source/create-images-manually-example-centos-image.rst
@@ -7,8 +7,10 @@ mainly on CentOS 7. Because the CentOS installation process
might differ across versions, the installation steps might
differ if you use a different version of CentOS.
+.. contents:: :depth: 2
+
Download a CentOS install ISO
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
#. Navigate to the `CentOS mirrors
<https://www.centos.org/download/mirrors/>`_ page.
@@ -24,7 +26,7 @@ Download a CentOS install ISO
packages from the Internet during installation.
Start the installation process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
Start the installation process using either the :command:`virt-manager`
or the :command:`virt-install` command as described previously.
@@ -52,7 +54,7 @@ something like this:
--location=/data/isos/CentOS-7-x86_64-NetInstall-1611.iso
Step through the installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
At the initial Installer boot menu, choose the
:guilabel:`Install CentOS 7` option. After the installation program starts,
@@ -63,7 +65,7 @@ installation summary. Accept the defaults.
:width: 100%
Change the Ethernet status
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
The default Ethernet setting is ``OFF``. Change the setting of
the Ethernet form ``OFF`` to ``ON``. In particular, ensure that
@@ -74,7 +76,7 @@ default.
:width: 100%
Hostname
---------
+~~~~~~~~
The installer allows you to choose a host name.
The default (``localhost.localdomain``) is fine.
@@ -83,7 +85,7 @@ which sets the host name on boot when a new instance
is provisioned using this image.
Point the installer to a CentOS web server
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Depending on the version of CentOS, the net installer requires
the user to specify either a URL or the web site and
@@ -109,13 +111,13 @@ to get a full list of mirrors, click on the ``HTTP`` link
of a mirror to retrieve the web site name of a mirror.
Storage devices
----------------
+~~~~~~~~~~~~~~~
If prompted about which type of devices your installation uses,
choose :guilabel:`Virtio Block Device`.
Partition the disks
--------------------
+~~~~~~~~~~~~~~~~~~~
There are different options for partitioning the disks.
The default installation uses LVM partitions, and creates
@@ -130,19 +132,19 @@ list will allow it to grow without crossing another
partition's boundary.
Select installation option
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Step through the installation, using the default options.
The simplest thing to do is to choose the ``Minimal Install``
install, which installs an SSH server.
Set the root password
----------------------
+~~~~~~~~~~~~~~~~~~~~~
During the installation, remember to set the root password when prompted.
Detach the CD-ROM and reboot
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Wait until the installation is complete.
@@ -181,7 +183,7 @@ and reboot it by manually stopping and starting.
# virsh reboot centos
Install the ACPI service
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
To enable the hypervisor to reboot or shutdown an instance,
you must install and run the ``acpid`` service on the guest system.
@@ -196,7 +198,7 @@ system boots:
# systemctl enable acpid
Configure to fetch metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
An instance must interact with the metadata service to perform
several tasks on start up. For example, the instance must get
@@ -210,7 +212,7 @@ the instance performs these tasks, use one of these methods:
the metadata service, as described in the next section.
Use cloud-init to fetch the public key
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
The ``cloud-init`` package automatically fetches the public key
from the metadata server and places the key in an account.
@@ -237,7 +239,7 @@ syntax in the configuration file:
(...)
Install cloud-utils-growpart to allow partitions to resize
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------------
In order for the root partition to properly resize, install the
``cloud-utils-growpart`` package, which contains the proper tools
@@ -248,7 +250,7 @@ to allow the disk to resize using cloud-init.
# yum install cloud-utils-growpart
Write a script to fetch the public key (if no cloud-init)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------
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,
@@ -303,7 +305,7 @@ before the line ``touch /var/lock/subsys/local``:
AESDG-chapter-instancedata.html>`_ for details on how to get user data.
Disable the zeroconf route
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
For the instance to access the metadata service,
you must disable the default zeroconf route:
@@ -313,7 +315,7 @@ you must disable the default zeroconf route:
# echo "NOZEROCONF=yes" >> /etc/sysconfig/network
Configure console
-~~~~~~~~~~~~~~~~~
+-----------------
For the :command:`nova console-log` command to work properly
on CentOS 7, you might need to do the following steps:
@@ -346,7 +348,7 @@ on CentOS 7, you might need to do the following steps:
done
Shut down the instance
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
From inside the instance, run as root:
@@ -355,7 +357,7 @@ From inside the instance, run as root:
# poweroff
Clean up (remove MAC address details)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
The operating system records the MAC address of the virtual Ethernet
card in locations such as ``/etc/sysconfig/network-scripts/ifcfg-eth0``
@@ -372,7 +374,7 @@ It will clean up a virtual machine image in place:
# virt-sysprep -d centos
Undefine the libvirt domain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
Now that you can upload the image to the Image service, you no
longer need to have this virtual machine image managed by libvirt.
@@ -383,7 +385,7 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt:
# virsh undefine centos
Image is complete
-~~~~~~~~~~~~~~~~~
+-----------------
The underlying image file that you created with the
:command:`qemu-img create` command is ready to be uploaded.
diff --git a/doc/image-guide/source/fedora-image.rst b/doc/image-guide/source/create-images-manually-example-fedora-image.rst
similarity index 94%
rename from doc/image-guide/source/fedora-image.rst
rename to doc/image-guide/source/create-images-manually-example-fedora-image.rst
index 70db3b4119..e9ff67ac8b 100644
--- a/doc/image-guide/source/fedora-image.rst
+++ b/doc/image-guide/source/create-images-manually-example-fedora-image.rst
@@ -7,8 +7,10 @@ mainly on Fedora 25. Because the Fedora installation process
might differ across versions, the installation steps might
differ if you use a different version of Fedora.
+.. contents:: :depth: 2
+
Download a Fedora install ISO
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
#. Visit the `Fedora download site <https://getfedora.org/>`_.
@@ -23,7 +25,7 @@ Download a Fedora install ISO
installation.
Start the installation process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
Start the installation process using either the :command:`virt-manager`
or the :command:`virt-install` command as described previously.
@@ -51,19 +53,19 @@ something like this:
--location=/tmp/Fedora-Server-netinst-x86_64-25-1.3.iso
Step through the installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
After the installation program starts, choose your preferred language and click
:guilabel:`Continue` to get to the installation summary. Accept the defaults.
Review the Ethernet status
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Ensure that the Ethernet setting is ``ON``. Additionally, make sure that
``IPv4 Settings' Method`` is ``Automatic (DHCP)``, which is the default.
Hostname
---------
+~~~~~~~~
The installer allows you to choose a host name.
The default (``localhost.localdomain``) is fine.
@@ -72,7 +74,7 @@ which sets the host name on boot when a new instance
is provisioned using this image.
Partition the disks
--------------------
+~~~~~~~~~~~~~~~~~~~
There are different options for partitioning the disks.
The default installation uses LVM partitions, and creates
@@ -87,19 +89,19 @@ list will allow it to grow without crossing another
partition's boundary.
Select software to install
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Step through the installation, using the default options.
The simplest thing to do is to choose the ``Minimal Install``
install, which installs an SSH server.
Set the root password
----------------------
+~~~~~~~~~~~~~~~~~~~~~
During the installation, remember to set the root password when prompted.
Detach the CD-ROM and reboot
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Wait until the installation is complete.
@@ -138,7 +140,7 @@ and reboot it by manually stopping and starting.
# virsh reboot fedora
Install the ACPI service
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
To enable the hypervisor to reboot or shutdown an instance,
you must install and run the ``acpid`` service on the guest system.
@@ -153,7 +155,7 @@ system boots:
# systemctl enable acpid
Configure cloud-init to fetch metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
An instance must interact with the metadata service to perform
several tasks on start up. For example, the instance must get
@@ -186,7 +188,7 @@ syntax in the configuration file:
(...)
Install cloud-utils-growpart to allow partitions to resize
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------------
In order for the root partition to properly resize, install the
``cloud-utils-growpart`` package, which contains the proper tools
@@ -197,7 +199,7 @@ to allow the disk to resize using cloud-init.
# dnf install cloud-utils-growpart
Disable the zeroconf route
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
For the instance to access the metadata service,
you must disable the default zeroconf route:
@@ -207,7 +209,7 @@ you must disable the default zeroconf route:
# echo "NOZEROCONF=yes" >> /etc/sysconfig/network
Configure console
-~~~~~~~~~~~~~~~~~
+-----------------
For the :command:`nova console-log` command to work properly
on Fedora, you might need to do the following steps:
@@ -235,7 +237,7 @@ on Fedora, you might need to do the following steps:
done
Shut down the instance
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
From inside the instance, run as root:
@@ -244,7 +246,7 @@ From inside the instance, run as root:
# poweroff
Clean up (remove MAC address details)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
The operating system records the MAC address of the virtual Ethernet
card in locations such as ``/etc/sysconfig/network-scripts/ifcfg-eth0``
@@ -261,7 +263,7 @@ It will clean up a virtual machine image in place:
# virt-sysprep -d fedora
Undefine the libvirt domain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
Now that you can upload the image to the Image service, you no
longer need to have this virtual machine image managed by libvirt.
@@ -272,7 +274,7 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt:
# virsh undefine fedora
Image is complete
-~~~~~~~~~~~~~~~~~
+-----------------
The underlying image file that you created with the
:command:`qemu-img create` command is ready to be uploaded.
diff --git a/doc/image-guide/source/freebsd-image.rst b/doc/image-guide/source/create-images-manually-example-freebsd-image.rst
similarity index 99%
rename from doc/image-guide/source/freebsd-image.rst
rename to doc/image-guide/source/create-images-manually-example-freebsd-image.rst
index 67f0cf1dbd..9b956deff9 100644
--- a/doc/image-guide/source/freebsd-image.rst
+++ b/doc/image-guide/source/create-images-manually-example-freebsd-image.rst
@@ -17,7 +17,10 @@ use that same platform in the image creation step.
This example shows how to create a FreeBSD 10 image. To create
a FreeBSD 9.2 image, follow these steps with the noted differences.
-**To create a FreeBSD image**
+.. contents:: :depth: 2
+
+Prerequisites
+-------------
#. Make a virtual drive:
@@ -71,6 +74,9 @@ a FreeBSD 9.2 image, follow these steps with the noted differences.
You now have a VM that boots from the downloaded install ISO and
is connected to the blank virtual disk that you created previously.
+Installation
+------------
+
#. To install the operating system, complete the following
steps inside the VM:
diff --git a/doc/image-guide/source/ubuntu-image.rst b/doc/image-guide/source/create-images-manually-example-ubuntu-image.rst
similarity index 96%
rename from doc/image-guide/source/ubuntu-image.rst
rename to doc/image-guide/source/create-images-manually-example-ubuntu-image.rst
index 5eec05d741..f26316ff6f 100644
--- a/doc/image-guide/source/ubuntu-image.rst
+++ b/doc/image-guide/source/create-images-manually-example-ubuntu-image.rst
@@ -6,8 +6,10 @@ This example installs an Ubuntu 18.04 (Bionic Beaver) image.
To create an image for a different version of Ubuntu,
follow these steps with the noted differences.
+.. contents:: :depth: 2
+
Download an Ubuntu installation ISO
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
Because the goal is to make the smallest possible base image,
this example uses the network installation ISO.
@@ -15,7 +17,7 @@ The Ubuntu 64-bit 18.04 network installation ISO is at the `Ubuntu download
page <http://archive.ubuntu.com/ubuntu/dists/bionic/main/installer-amd64/current/images/netboot/mini.iso>`_.
Start the installation process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
Start the installation process by using either :command:`virt-manager`
or :command:`virt-install` as described in the previous section.
@@ -44,7 +46,7 @@ the commands should look something like this:
--os-type=linux --os-variant=ubuntu18.04
Step through the installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
At the initial Installer boot menu, choose the :guilabel:`Install` option.
Step through the installation prompts, the defaults should be fine.
@@ -112,14 +114,14 @@ For more information on configuring Grub, see the section
called ":ref:`write-to-console`".
Log in to newly created image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
When you boot for the first time after install, it may ask
you about authentication tools, you can just choose :guilabel:`Exit`.
Then, log in as admin user using the password you specified.
Install cloud-init
-~~~~~~~~~~~~~~~~~~
+------------------
The :command:`cloud-init` script starts on instance boot and
will search for a metadata provider to fetch a public key from.
@@ -161,7 +163,7 @@ syntax in the configuration file:
(...)
Shut down the instance
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
From inside the instance, as root:
@@ -170,7 +172,7 @@ From inside the instance, as root:
# /sbin/shutdown -h now
Clean up (remove MAC address details)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
The operating system records the MAC address of the virtual Ethernet
card in locations such as ``/etc/udev/rules.d/70-persistent-net.rules``
@@ -187,7 +189,7 @@ It will clean up a virtual machine image in place:
# virt-sysprep -d bionic
Undefine the libvirt domain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
Now that the image is ready to be uploaded to the Image service,
you no longer need to have this virtual machine image managed by libvirt.
@@ -198,7 +200,7 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt:
# virsh undefine bionic
Image is complete
-~~~~~~~~~~~~~~~~~
+-----------------
The underlying image file that you created with the
:command:`qemu-img create` command, such as
diff --git a/doc/image-guide/source/windows-image.rst b/doc/image-guide/source/create-images-manually-example-windows-image.rst
similarity index 97%
rename from doc/image-guide/source/windows-image.rst
rename to doc/image-guide/source/create-images-manually-example-windows-image.rst
index 79d3c93e21..0dbc887447 100644
--- a/doc/image-guide/source/windows-image.rst
+++ b/doc/image-guide/source/create-images-manually-example-windows-image.rst
@@ -2,9 +2,14 @@
Example: Microsoft Windows image
================================
+.. contents:: :depth: 2
+
This example creates a Windows Server 2012 qcow2 image,
using the :command:`virt-install` command and the KVM hypervisor.
+Prerequisites
+-------------
+
#. Follow these steps to prepare the installation:
#. Download a Windows Server 2012 installation ISO.
@@ -19,6 +24,9 @@ using the :command:`virt-install` command and the KVM hypervisor.
$ qemu-img create -f qcow2 ws2012.qcow2 15G
+Installation
+------------
+
#. Start the Windows Server 2012 installation with the
:command:`virt-install` command:
@@ -94,6 +102,9 @@ using the :command:`virt-install` command and the KVM hypervisor.
Wait for the machine shutdown.
+Image ready
+-----------
+
Your image is ready to upload to the Image service:
.. code-block:: console
diff --git a/doc/image-guide/source/virt-install.rst b/doc/image-guide/source/create-images-manually-tools-libvirt.rst
similarity index 52%
rename from doc/image-guide/source/virt-install.rst
rename to doc/image-guide/source/create-images-manually-tools-libvirt.rst
index c32365b027..5d082d301d 100644
--- a/doc/image-guide/source/virt-install.rst
+++ b/doc/image-guide/source/create-images-manually-tools-libvirt.rst
@@ -1,6 +1,93 @@
-========================================================
+=====================================
+Tools: libvirt and virsh/virt-manager
+=====================================
+
+.. contents:: :depth: 3
+
+Prerequisites
+-------------
+
+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
+
+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 user@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 :guilabel:`Create a new virtual machine` button at the top-left,
+or go to :menuselection:`File --> New Virtual Machine`. Then, follow 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 configuration before install``, go to disk properties and
+ explicitly select the :guilabel:`qcow2` format.
+ This ensures the virtual machine disk size will be correct.
+
Use virt-install and connect by using a local VNC client
-========================================================
+--------------------------------------------------------
If you do not wish to use :command:`virt-manager` (for example,
you do not want to install the dependencies on your server, you do
diff --git a/doc/image-guide/source/create-images-manually.rst b/doc/image-guide/source/create-images-manually.rst
index 20e9f45097..663ab2c7ea 100644
--- a/doc/image-guide/source/create-images-manually.rst
+++ b/doc/image-guide/source/create-images-manually.rst
@@ -2,18 +2,6 @@
Create images manually
======================
-.. toctree::
- :maxdepth: 1
-
- 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.
@@ -39,3 +27,23 @@ to find a VNC client that works on your local desktop.
To create an image for the Database service,
see `Building Guest Images for OpenStack Trove
<https://docs.openstack.org/trove/latest/admin/building_guest_images.html>`_.
+
+Tools
+-----
+
+.. toctree::
+ :maxdepth: 1
+
+ create-images-manually-tools-libvirt.rst
+
+Examples
+--------
+
+.. toctree::
+ :maxdepth: 1
+
+ create-images-manually-example-centos-image.rst
+ create-images-manually-example-fedora-image.rst
+ create-images-manually-example-freebsd-image.rst
+ create-images-manually-example-windows-image.rst
+ create-images-manually-example-ubuntu-image.rst
diff --git a/doc/image-guide/source/net-running.rst b/doc/image-guide/source/net-running.rst
deleted file mode 100644
index 8f6093cc4a..0000000000
--- a/doc/image-guide/source/net-running.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-=============================================
-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/source/virt-manager.rst b/doc/image-guide/source/virt-manager.rst
deleted file mode 100644
index d235115c80..0000000000
--- a/doc/image-guide/source/virt-manager.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-============================
-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 user@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 :guilabel:`Create a new virtual machine` button at the top-left,
-or go to :menuselection:`File --> New Virtual Machine`. Then, follow 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 configuration before install``, go to disk properties and
- explicitly select the :guilabel:`qcow2` format.
- This ensures the virtual machine disk size will be correct.