install-guide: minor fixes

Fix some minor issues in the first chapter of the install guide.

Add a note about installing a backported kernel for Networking on Ubuntu
12.04.

Don't install mysql/mariadb clients on compute and network nodes,
python-mysqldb is enough.

Change-Id: I36e91dce7d2f90b87cd8e725ec80c1e18058753c

doc/common/ch_getstart.xml

@@ -57,7 +57,7 @@
                 </td>
                 <td>Manages the lifecycle of compute instances in an
                     OpenStack environment. Responsibilities include
-                    spawning, scheduling and decomissioning of
+                    spawning, scheduling and decomissioning of virtual
                     machines on demand.</td>
             </tr>
             <tr>
@@ -160,8 +160,9 @@
                         ><glossterm>Heat</glossterm></link>
                 </td>
                 <td>Orchestrates multiple composite cloud applications by using
-                    either the native HOT template format or the AWS
+                    either the native <glossterm baseform="Heat Orchestration
-                    CloudFormation template format, through both an
+                        Template (HOT)">HOT</glossterm> template format or the
+                    AWS CloudFormation template format, through both an
                     OpenStack-native REST API and a CloudFormation-compatible
                     Query API.</td>
             </tr>

doc/install-guide/section_basics-database.xml

@@ -8,16 +8,16 @@
     services require a database to store information. These examples
     use a MySQL database that runs on the controller node. You must
     install the MySQL database on the controller node. You must
-    install MySQL client software on any additional nodes that
+    install the MySQL Python library on any additional nodes that
     access MySQL.</para>
   <para os="opensuse;sles">Most OpenStack services require a
     database to store information. This guide uses a MySQL database
     on SUSE Linux Enterprise Server and a compatible database on
     openSUSE running on the controller node. This compatible
     database for openSUSE is MariaDB. You must install the MariaDB
-    database on the controller node. You must install the MariaDB
+    database on the controller node. You must install the MySQL
-    client software on any nodes that access the MariaDB
+    Python library on any additional nodes that access MySQL or MariaDB.
-    database.</para>
+    </para>
   <section xml:id="basics-database-controller">
     <title>Controller setup</title>
     <para><phrase os="sles">For SUSE Linux Enterprise Server:
@@ -74,7 +74,7 @@ character-set-server = utf8</programlisting>
       os="rhel;fedora;centos">MySQL</phrase>
       <phrase os="opensuse;sles">MariaDB or MySQL</phrase> database
       server and set it to start automatically when the system
-      boots.</para>
+      boots:</para>
     <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>service mysqld start</userinput>
 <prompt>#</prompt> <userinput>chkconfig mysqld on</userinput></screen>
         <screen os="opensuse;sles"><prompt>#</prompt> <userinput>service mysql start</userinput>
@@ -105,16 +105,9 @@ character-set-server = utf8</programlisting>
   <section xml:id="basics-database-node">
     <title>Node setup</title>
     <para>On all nodes other than the controller node, install the
-      <phrase os="ubuntu;debian;rhel;fedora;centos"
+        MySQL Python library:</para>
-      >MySQL</phrase>
-      <phrase os="opensuse">MariaDB (on openSUSE)</phrase> client
-      and the MySQL Python library on any system that does not
-      host a MySQL database:</para>
     <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install python-mysqldb</userinput></screen>
-    <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>yum install mysql MySQL-python</userinput></screen>
+    <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>yum install MySQL-python</userinput></screen>
-    <screen os="opensuse"><prompt>#</prompt> <userinput>zypper install mariadb-client python-mysql</userinput></screen>
+    <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install python-mysql</userinput></screen>
-    <para os="sles">For SUSE Linux Enterprise, install
-      MySQL:</para>
-    <screen os="sles"><prompt>#</prompt> <userinput>zypper install mysql-client python-mysql</userinput></screen>
   </section>
 </section>

doc/install-guide/section_basics-ntp.xml

@@ -10,20 +10,20 @@
     node as the reference server and any additional nodes to set
     their time from the controller node.</para>
   <para>Install the <literal>ntp</literal> package on each system
-    running OpenStack services.</para>
+    running OpenStack services:</para>
   <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install ntp</userinput></screen>
   <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>yum install ntp</userinput></screen>
   <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install ntp</userinput></screen>
   <para os="rhel;fedora;centos;opensuse;sles">Set up the NTP server
     on your controller node so that it receives data by modifying
     the <filename>ntp.conf</filename> file and restarting the
-    service.</para>
+    service:</para>
   <screen os="rhel;fedora;centos;opensuse;sles"><prompt>#</prompt> <userinput>service ntpd start</userinput>
 <prompt>#</prompt> <userinput>chkconfig ntpd on</userinput></screen>
   <screen os="opensuse;sles"><prompt>#</prompt> <userinput>service ntp start</userinput>
 <prompt>#</prompt> <userinput>chkconfig ntp on</userinput></screen>
-  <para>On additional nodes, it is advised that you configure the
+  <para>It is advised that you configure additional nodes
-    other nodes to synchronize their time from the controller node
+    to synchronize their time from the controller node
     rather than from outside of your LAN. To do so, install the ntp
     daemon as above, then edit <filename>/etc/ntp.conf</filename>
     and change the <code>server</code> directive to use the

doc/install-guide/section_basics-packages.xml

@@ -16,7 +16,7 @@
     on Red Hat Enterprise Linux 6, compatible versions of CentOS,
     and Fedora 20. To enable the RDO repository, download and
     install the <package>rdo-release-icehouse</package>
-    package.</para>
+    package:</para>
   <screen os="fedora;centos;rhel"><prompt>#</prompt> <userinput>yum install http://repos.fedorapeople.org/repos/openstack/openstack-icehouse/rdo-release-icehouse-1.noarch.rpm</userinput></screen>
   <para os="fedora;centos;rhel">The EPEL package includes GPG keys
     for package signing and repository information. This should only
@@ -32,7 +32,7 @@
     programs that make installation and configuration easier. These
     programs are used throughout this guide. Install
     <package>openstack-utils</package>. This verifies that you can
-    access the RDO repository.</para>
+    access the RDO repository:</para>
   <screen os="fedora;centos;rhel"><prompt>#</prompt> <userinput>yum install openstack-utils</userinput></screen>
   <para os="opensuse;sles">Use the Open Build Service repositories
     for <glossterm>Icehouse</glossterm> based on your openSUSE or
@@ -67,7 +67,7 @@
     <package>openstack-selinux</package> package includes the
     policy files that are required to configure SELinux during
     OpenStack installation.
-    Install <package>openstack-selinux</package>.</para>
+    Install <package>openstack-selinux</package>:</para>
   <screen os="fedora;centos;rhel"><prompt>#</prompt> <userinput>yum install openstack-selinux</userinput></screen>
   <para os="fedora;centos;rhel;opensuse;sles">Upgrade your system packages:</para>
   <screen os="fedora;centos;rhel"><prompt>#</prompt> <userinput>yum upgrade</userinput></screen>
@@ -90,10 +90,22 @@
 <prompt>#</prompt> <userinput>add-apt-repository cloud-archive:icehouse</userinput></screen></para>
     </step>
     <step>
-      <para>Update the package database, upgrade your system, and reboot
+        <para>Update the package database and upgrade your system:</para>
-        for all changes to take effect:
+        <screen><prompt>#</prompt> <userinput>apt-get update</userinput>
-      <screen><prompt>#</prompt> <userinput>apt-get update &amp;&amp; apt-get dist-upgrade</userinput>
+<prompt>#</prompt> <userinput>apt-get dist-upgrade</userinput>
-<prompt>#</prompt> <userinput>reboot</userinput> </screen></para>
+<prompt>#</prompt> <userinput>reboot</userinput></screen>
+    </step>
+    <step>
+        <para>If you intend to use OpenStack Networking with Ubuntu 12.04,
+            you should install a backported Linux kernel to improve the
+            stability of your system. This installation is not needed if you
+            intend to use the legacy networking service.</para>
+        <para>Install the Ubuntu 13.10 backported kernel:</para>
+        <screen><prompt>#</prompt> <userinput>apt-get install linux-image-generic-lts-saucy linux-headers-generic-lts-saucy</userinput></screen>
+    </step>
+    <step>
+        <para>Reboot the system for all changes to take effect:</para>
+        <screen><prompt>#</prompt> <userinput>reboot</userinput></screen>
     </step>
   </procedure>
   <procedure xml:id="debian-cloud-archive" os="debian">

doc/install-guide/section_basics-passwords.xml

@@ -16,7 +16,7 @@
   </para>
   <para>This guide uses the convention that
     <literal><replaceable>SERVICE_PASS</replaceable></literal> is
-    password to access the service <literal>SERVICE</literal> and
+    the password to access the service <literal>SERVICE</literal> and
     <literal><replaceable>SERVICE_DBPASS</replaceable></literal> is
     the database password used by the service SERVICE to access the
     database.