From e676eda7c278d6763f793128c14b6d32691131aa Mon Sep 17 00:00:00 2001 From: venkatamahesh Date: Thu, 10 Dec 2015 15:03:34 +0530 Subject: [PATCH] [Image-guide] Fix the RST mark-ups In this patch I added the RST mark-ups and 'the' article whereever needed Change-Id: I9dd8f8bda5a22b6e50adc1f839dfa586f7c17b24 --- doc/image-guide/source/centos-image.rst | 16 +++++++------- .../source/create-images-automatically.rst | 2 +- doc/image-guide/source/fedora-image.rst | 9 ++++---- doc/image-guide/source/freebsd-image.rst | 4 ++-- doc/image-guide/source/image-metadata.rst | 8 +++---- doc/image-guide/source/introduction.rst | 8 +++---- doc/image-guide/source/modify-images.rst | 15 +++++++------ doc/image-guide/source/obtain-images.rst | 14 ++++++------ doc/image-guide/source/openstack-images.rst | 22 +++++++++---------- doc/image-guide/source/ubuntu-image.rst | 18 +++++++-------- doc/image-guide/source/virt-manager.rst | 5 +++-- doc/image-guide/source/windows-image.rst | 10 ++++----- 12 files changed, 67 insertions(+), 64 deletions(-) diff --git a/doc/image-guide/source/centos-image.rst b/doc/image-guide/source/centos-image.rst index 69343368df..57b7dda070 100644 --- a/doc/image-guide/source/centos-image.rst +++ b/doc/image-guide/source/centos-image.rst @@ -26,9 +26,9 @@ Download a CentOS install ISO Start the installation process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Start the installation process using either :command:`virt-manager` -or :command:`virt-install` as described in the previous section. -If you use :command:`virt-install`, do not forget to connect your +Start the installation process using either the :command:`virt-manager` +or the :command:`virt-install` command as described in the previous section. +If you use the :command:`virt-install` command, do not forget to connect your VNC client to the virtual machine. Assume that: @@ -38,7 +38,7 @@ Assume that: to manipulate the state of the image. * You saved the netinstall ISO image to the ``/data/isos`` directory. -If you use :command:`virt-install`, the commands should look +If you use the :command:`virt-install` command, the commands should look something like this: .. code-block:: console @@ -66,7 +66,7 @@ Configure TCP/IP ~~~~~~~~~~~~~~~~ The default TCP/IP settings are fine. -In particular, ensure that Enable IPv4 support is enabled +In particular, ensure that ``Enable IPv4 support`` is enabled with DHCP, which is the default. .. figure:: figures/centos-tcpip.png @@ -212,7 +212,7 @@ the instance performs these tasks, use one of these methods: * Install a ``cloud-init`` RPM, which is a port of the Ubuntu `cloud-init `_ package. This is the recommended approach. -* Modify ``/etc/rc.local`` to fetch desired information from +* Modify the ``/etc/rc.local`` file to fetch desired information from the metadata service, as described in the next section. Use cloud-init to fetch the public key @@ -362,7 +362,7 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt: Image is complete ~~~~~~~~~~~~~~~~~ -The underlying image file that you created with -:command:`qemu-img create` is ready to be uploaded. +The underlying image file that you created with the +:command:`qemu-img create` command is ready to be uploaded. For example, you can upload the ``/tmp/centos-6.4.qcow2`` image to the Image service. diff --git a/doc/image-guide/source/create-images-automatically.rst b/doc/image-guide/source/create-images-automatically.rst index d02a7ba461..b6c39f06ff 100644 --- a/doc/image-guide/source/create-images-automatically.rst +++ b/doc/image-guide/source/create-images-automatically.rst @@ -160,7 +160,7 @@ VeeWee `VeeWee `_ is often used to build `Vagrant `_ boxes, -but it can also be used to build KVM images. +but it can also be used to build the KVM images. Packer ~~~~~~ diff --git a/doc/image-guide/source/fedora-image.rst b/doc/image-guide/source/fedora-image.rst index ecc5d2378f..cea9538a28 100644 --- a/doc/image-guide/source/fedora-image.rst +++ b/doc/image-guide/source/fedora-image.rst @@ -123,7 +123,7 @@ This procedure lets you create a Fedora 20 image. #. Run the following commands from the host to eject the disk and - reboot using :command:`virsh`, as root. + reboot using the :command:`virsh` command, as root. .. code-block:: console @@ -147,7 +147,7 @@ This procedure lets you create a Fedora 20 image. # yum install acpid # chkconfig acpid on -#. Install ``cloud-init`` package inside the Fedora guest by adding +#. Install the ``cloud-init`` package inside the Fedora guest by adding the EPEL repo: The ``cloud-init`` package automatically fetches the public key @@ -215,5 +215,6 @@ This procedure lets you create a Fedora 20 image. # virsh undefine fedora-20 -The underlying image file that you created with -:command:`qemu-img create` is ready to be uploaded to the Image service. +The underlying image file that you created with the +:command:`qemu-img create` command is ready to be uploaded to the +Image service. diff --git a/doc/image-guide/source/freebsd-image.rst b/doc/image-guide/source/freebsd-image.rst index 2507a15756..f53c01a1c7 100644 --- a/doc/image-guide/source/freebsd-image.rst +++ b/doc/image-guide/source/freebsd-image.rst @@ -151,8 +151,8 @@ a FreeBSD 9.2 image, follow these steps with the noted differences. #. Select the time zone appropriate to your environment. -#. From the list of services to start on boot, you must select ``ssh``. - Optionally, select other services. +#. From the list of services to start on boot, you must select + :guilabel:`ssh`. Optionally, select other services. #. Optionally, add users. diff --git a/doc/image-guide/source/image-metadata.rst b/doc/image-guide/source/image-metadata.rst index 97353589c2..af75f98c9f 100644 --- a/doc/image-guide/source/image-metadata.rst +++ b/doc/image-guide/source/image-metadata.rst @@ -18,9 +18,9 @@ hosts that satisfy that property. ``scheduler_default_filter`` value in the ``/etc/nova/nova.conf`` file. You can add metadata to Image service images by using the -``--property key=value`` parameter with the ``glance image-create`` -or ``glance image-update`` command. -More than one property can be specified. For example: +``--property key=value`` parameter with the +:command:`glance image-create` or :command:`glance image-update` +command. More than one property can be specified. For example: .. code-block:: console @@ -34,7 +34,7 @@ For a complete list of valid property keys and values, refer to the cli-reference/content/chapter_cli-glance-property.html>`_. All associated properties for an image can be displayed using the -``glance image-show`` command. For example: +:command:`glance image-show` command. For example: .. code-block:: console diff --git a/doc/image-guide/source/introduction.rst b/doc/image-guide/source/introduction.rst index 9aa76e1eed..5dcecc578a 100644 --- a/doc/image-guide/source/introduction.rst +++ b/doc/image-guide/source/introduction.rst @@ -13,10 +13,10 @@ machine images (which some people call "virtual appliances"). This guide describes how to obtain, create, and modify virtual machine images that are compatible with OpenStack. -To keep things brief, we will sometimes use the term image instead of -virtual machine image. +To keep things brief, we will sometimes use the term ``image`` +instead of virtual machine image. -What is a virtual machine image? +**What is a virtual machine image?** A virtual machine image is a single file which contains a virtual disk that has a bootable operating system installed on it. @@ -29,7 +29,7 @@ Raw supported by both KVM and Xen hypervisors. You can think of a raw image as being the bit-equivalent of a block device file, created as if somebody had copied, say, - ``/dev/sda`` to a file using the ``dd`` command. + ``/dev/sda`` to a file using the :command:`dd` command. .. note:: diff --git a/doc/image-guide/source/modify-images.rst b/doc/image-guide/source/modify-images.rst index 100fd9ff41..9f4e307034 100644 --- a/doc/image-guide/source/modify-images.rst +++ b/doc/image-guide/source/modify-images.rst @@ -10,7 +10,7 @@ Here we describe several tools available that allow you to modify images. Do not attempt to use these tools to modify an image that is attached to a running virtual machine. - These tools are designed only to modify images that + These tools are designed only to modify the images that are not currently running. guestfish @@ -36,7 +36,7 @@ any traces of the MAC address that was assigned to the virtual network interface card when the image was first created. This is because the MAC address is different when the virtual machine images boots. -This example shows how to use guestfish to remove +This example shows how to use the ``guestfish`` to remove references to the old MAC address by deleting the ``/etc/udev/rules.d/70-persistent-net.rules`` file and removing the ``HWADDR`` line from the @@ -267,7 +267,7 @@ resize to 50 GB. Loop devices, kpartx, network block devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you do not have access to libguestfs, you can mount +If you do not have access to the libguestfs, you can mount image file systems directly in the host using loop devices, kpartx, and network block devices. @@ -344,8 +344,8 @@ Once you are done, to clean up: Mount a raw image (with LVM) ---------------------------- -If your partitions are managed with LVM, use losetup -and kpartx as in the previous example to expose the +If your partitions are managed with LVM, use :command:`losetup` +and :command:`kpartx` commands as in the previous example to expose the partitions to the host. .. code-block:: console @@ -356,7 +356,8 @@ partitions to the host. # kpartx -av /dev/loop0 Next, you need to use the :command:`vgscan` command to identify the LVM -volume groups and then :command:`vgchange` to expose the volumes as devices: +volume groups and then the :command:`vgchange` command to expose the volumes +as devices: .. code-block:: console @@ -410,7 +411,7 @@ there should be one new device created for each partition: .. note:: If the network block device you selected was already in use, - the initial ``qemu-nbd`` command will fail silently, and the + the initial :command:`qemu-nbd` command will fail silently, and the ``/dev/nbd3p{1,2,3}`` device files will not be created. If the image partitions are not managed with LVM, diff --git a/doc/image-guide/source/obtain-images.rst b/doc/image-guide/source/obtain-images.rst index 3439a4841b..39f7ce3c3c 100644 --- a/doc/image-guide/source/obtain-images.rst +++ b/doc/image-guide/source/obtain-images.rst @@ -3,12 +3,12 @@ Get images ========== The simplest way to obtain a virtual machine image that works with -OpenStack is to download one that someone else has already created. -Most of the images contain the ``cloud-init`` package to support -SSH key pair and user data injection. +OpenStack is to download one that someone else has already +created. Most of the images contain the ``cloud-init`` package to +support the SSH key pair and user data injection. Because many of the images disable SSH password authentication by default, boot the image with an injected key pair. -You can SSH into the instance with the private key and default +You can ``SSH`` into the instance with the private key and default login account. See the `OpenStack End User Guide `_ for more information on how to create and inject key pairs with OpenStack. @@ -46,14 +46,14 @@ writing is `cirros-0.3.4-x86_64-disk.img Official Ubuntu images ~~~~~~~~~~~~~~~~~~~~~~ -Canonical maintains an `official set of Ubuntu-based images +Canonical maintains an official set of `Ubuntu-based images `_. Images are arranged by Ubuntu release, and by image release date, with ``current`` being the most recent. For example, the page that contains the most recently built image for Ubuntu 14.04 Trusty Tahr is http://cloud-images.ubuntu.com/trusty/current/. -Scroll to the bottom of the page for links to images that can be +Scroll to the bottom of the page for links to the images that can be downloaded directly. If your deployment uses QEMU or KVM, we recommend using the images @@ -99,7 +99,7 @@ SUSE provides images for `openSUSE `_. For SUSE Linux Enterprise Server (SLES), custom images can be built with a web-based tool called `SUSE Studio `_. -SUSE Studio can also be used to build custom openSUSE images. +SUSE Studio can also be used to build the custom openSUSE images. Official Debian images ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/image-guide/source/openstack-images.rst b/doc/image-guide/source/openstack-images.rst index 07cd696583..7d1c4a89fb 100644 --- a/doc/image-guide/source/openstack-images.rst +++ b/doc/image-guide/source/openstack-images.rst @@ -155,7 +155,7 @@ You should alter the following files: .. note:: If you delete the network persistent rules files, - you may get a udev kernel warning at boot time, + you may get a ``udev kernel`` warning at boot time, which is why we recommend replacing them with empty files instead. Ensure ssh server runs @@ -218,7 +218,7 @@ and add it to a user account. To fetch the ssh public key and add it to the root account, edit the ``/etc/rc.local`` file and add the following lines -before the line "touch /var/lock/subsys/local". +before the line ``touch /var/lock/subsys/local``. This code fragment is taken from the `rackerjoe oz-image-build CentOS 6 template `_. @@ -284,7 +284,7 @@ As the OpenStack metadata service is compatible with version Amazon EC2 documentation on `Using Instance Metadata `_ -for details on how to retrieve user data. +for details on how to retrieve the user data. The easiest way to support this type of functionality is to install the ``cloud-init`` package into your image, @@ -300,7 +300,7 @@ You must configure the image so that the kernel writes the boot log to the ``ttyS0`` device. In particular, the ``console=ttyS0`` argument must be passed to the kernel on boot. -If your image uses grub2 as the boot loader, +If your image uses ``grub2`` as the boot loader, there should be a line in the grub configuration file. For example, ``/boot/grub/grub.cfg``, which looks something like this: @@ -311,7 +311,7 @@ For example, ``/boot/grub/grub.cfg``, which looks something like this: If ``console=ttyS0`` does not appear, you must modify your grub configuration. In general, you should not update the ``grub.cfg`` directly, since it is automatically generated. -Instead, you should edit ``/etc/default/grub`` and modify the +Instead, you should edit the ``/etc/default/grub`` file and modify the value of the ``GRUB_CMDLINE_LINUX_DEFAULT`` variable: .. code-block:: bash @@ -319,7 +319,7 @@ value of the ``GRUB_CMDLINE_LINUX_DEFAULT`` variable: GRUB_CMDLINE_LINUX_DEFAULT="console=ttyS0" Next, update the grub configuration. On Debian-based -operating-systems such as Ubuntu, run this command: +operating systems such as Ubuntu, run this command: .. code-block:: console @@ -346,12 +346,12 @@ boots a kernel that has been compiled with Xen support. Manage the image cache ~~~~~~~~~~~~~~~~~~~~~~ -Use options in ``nova.conf`` to control whether, and for how long, -unused base images are stored in ``/var/lib/nova/instances/_base/``. +Use options in the ``nova.conf`` file to control whether, and for how long, +unused base images are stored in the ``/var/lib/nova/instances/_base/``. If you have configured live migration of instances, all your compute nodes share one common ``/var/lib/nova/instances/`` directory. -For information about libvirt images in OpenStack, see +For information about the libvirt images in OpenStack, see `The life of an OpenStack libvirt image from Pádraig Brady `_. @@ -403,5 +403,5 @@ In the ``/var/log/compute/compute.log`` file, look for the identifier: Because 86400 seconds (24 hours) is the default time for ``remove_unused_original_minimum_age_seconds``, you can either wait for that time interval to see the base image -removed, or set the value to a shorter time period in ``nova.conf``. -Restart all nova services after changing a setting in ``nova.conf``. +removed, or set the value to a shorter time period in the ``nova.conf`` file. +Restart all nova services after changing a setting in the ``nova.conf`` file. diff --git a/doc/image-guide/source/ubuntu-image.rst b/doc/image-guide/source/ubuntu-image.rst index 527d63d118..bbbf6ba44e 100644 --- a/doc/image-guide/source/ubuntu-image.rst +++ b/doc/image-guide/source/ubuntu-image.rst @@ -90,7 +90,7 @@ Internet, we recommend "Install security updates automatically". Software selection: OpenSSH server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Choose ``OpenSSH server`` so that you will be able to SSH into +Choose :guilabel:`OpenSSH server` so that you will be able to SSH into the virtual machine when it launches inside of an OpenStack cloud. .. figure:: figures/ubuntu-software-selection.png @@ -98,7 +98,7 @@ the virtual machine when it launches inside of an OpenStack cloud. Install GRUB boot loader ~~~~~~~~~~~~~~~~~~~~~~~~ -Select "Yes" when asked about installing the GRUB boot loader +Select :guilabel:`Yes` when asked about installing the GRUB boot loader to the master boot record. .. figure:: figures/ubuntu-grub.png @@ -144,7 +144,7 @@ You can confirm the appropriate target using the 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. +If you are using ``virt-manager``, you may use the GUI instead. .. code-block:: console @@ -164,7 +164,7 @@ 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 ``Exit``. +you about authentication tools, you can just choose :guilabel:`Exit`. Then, log in as root using the root password you specified. Install cloud-init @@ -187,15 +187,15 @@ service used by images in Amazon EC2. To set the metadata source to be used by the image run the :command:`dpkg-reconfigure` command against the ``cloud-init`` -package. When prompted select the ``EC2`` data source: +package. When prompted select the :guilabel:`EC2` data source: .. code-block:: console # dpkg-reconfigure cloud-init 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". +On Ubuntu-based virtual machines, the account is called ``ubuntu``. +On Fedora-based virtual machines, the account is called ``ec2-user``. You can change the name of the account used by cloud-init by editing the ``/etc/cloud/cloud.cfg`` file and adding a line with a different user. @@ -246,6 +246,6 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt: Image is complete ~~~~~~~~~~~~~~~~~ -The underlying image file that you created with -:command:`qemu-img create`, such as ``/tmp/trusty.qcow2``, +The underlying image file that you created with the +:command:`qemu-img create` command, such as ``/tmp/trusty.qcow2``, is now ready for uploading to the Image service. diff --git a/doc/image-guide/source/virt-manager.rst b/doc/image-guide/source/virt-manager.rst index f1f44edd20..d568a4ed1f 100644 --- a/doc/image-guide/source/virt-manager.rst +++ b/doc/image-guide/source/virt-manager.rst @@ -33,7 +33,8 @@ permissions to run libvirt, but has sudo privileges, do: 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 ``New`` button at the top-left and step through the instructions. +Click the :guilabel:`New` button at the top-left and step through the +instructions. .. figure:: figures/virt-manager.png :width: 100% @@ -45,5 +46,5 @@ to specify information about the virtual machine. When using qcow2 format images you should check the option ``customize before install``, go to disk properties and - explicitly select the qcow2 format. + explicitly select the :guilabel:`qcow2` format. This ensures the virtual machine disk size will be correct. diff --git a/doc/image-guide/source/windows-image.rst b/doc/image-guide/source/windows-image.rst index 6136d74980..b5fdfbf21f 100644 --- a/doc/image-guide/source/windows-image.rst +++ b/doc/image-guide/source/windows-image.rst @@ -3,7 +3,7 @@ Example: Microsoft Windows image ================================ This example creates a Windows Server 2012 qcow2 image, -using :command:`virt-install` and the KVM hypervisor. +using the :command:`virt-install` command and the KVM hypervisor. #. Follow these steps to prepare the installation: @@ -42,8 +42,8 @@ using :command:`virt-install` and the KVM hypervisor. When requested to choose an installation target, click :guilabel:`Load driver` and browse the file system to select the ``E:\WIN8\AMD64`` folder. The Windows installer displays - a list of drivers to install. Select the VirtIO SCSI and - network drivers, and continue the installation. + a list of drivers to install. Select the :guilabel:`VirtIO SCSI` and + :guilabel:`network drivers`, and continue the installation. Once the installation is completed, the VM restarts. Define a password for the administrator when prompted. @@ -57,7 +57,7 @@ using :command:`virt-install` and the KVM hypervisor. C:\pnputil -i -a E:\WIN8\AMD64\*.INF -#. To allow :term:`Cloudbase-Init` to run scripts during an instance +#. To allow the :term:`Cloudbase-Init` to run scripts during an instance boot, set the PowerShell execution policy to be unrestricted: .. code-block:: console @@ -65,7 +65,7 @@ using :command:`virt-install` and the KVM hypervisor. C:\powershell C:\Set-ExecutionPolicy Unrestricted -#. Download and install Cloudbase-Init: +#. Download and install the ``Cloudbase-Init``: .. code-block:: console