Add sample architecture, fix ubuntu instructions

1) The install guide was lacking a sample architecture section

This adds one and includes an image, with a followup image
in the basic networking section.

2) The instructions for disabling NetworkManager were given for
all distributions. This is not necessary on Ubuntu Server or Suse
server

3) the network configuration samples were only for fedora
this adds one for ubuntu, and a placeholder for SUSE

4) you need to restart the network after making changes

5) ubuntu sets services to start on install, no need to
restart or chkconfig (which doesn't exist on ubuntu)

6) ubuntu does not have openstack-config or openstack-db

This install has now been verified for ubuntu from the beginning
to the end of the identity service install.

Change-Id: I4e41092ab3ae399c83bb01d491847b6ca1998cfa
Closes-Bug: 1237863
Closes-Bug: 1237890
Closes-Bug: 1237898
Closes-Bug: 1237906
Partial-Bug: 1236952

doc/install-guide/ch_basics.xml

@@ -36,13 +36,12 @@
       guide assumes that each node can reach the other nodes on the internal
       network using hostnames like <literal>controller</literal> and
         <literal>compute1</literal>.</para>
-
+    <para os="fedora">Start by disabling the <literal>NetworkManager</literal> service and
-    <para>Start by disabling the <literal>NetworkManager</literal> service and
       enabling the <literal>network</literal> service. The
         <literal>network</literal> service is more suitable for the static
       network configuration done in this guide.</para>
 
-    <screen><prompt>#</prompt> <userinput>service NetworkManager stop</userinput>
+    <screen os="fedora"><prompt>#</prompt> <userinput>service NetworkManager stop</userinput>
 <prompt>#</prompt> <userinput>service network start</userinput>
 <prompt>#</prompt> <userinput>chkconfig NetworkManager off</userinput>
 <prompt>#</prompt> <userinput>chkconfig network on</userinput></screen>
@@ -72,8 +71,16 @@
       creating the compute node, use <literal>192.168.0.11</literal> and
         <literal>10.0.0.11</literal> instead. Additional nodes added in later
       chapters will follow this pattern.</para>
+ <figure xml:id="basic-architecture-networking">
+  <title>Basic Architecture</title>
+  <mediaobject>
+    <imageobject>
+      <imagedata contentwidth="6in" fileref="figures/basic-architecture-networking.svg"/>
+    </imageobject>
+  </mediaobject>
+  </figure>
 
-    <example>
+    <example os="fedora">
       <title><filename>/etc/sysconfig/network-scripts/ifcfg-eth0</filename></title>
       <programlisting language="ini"># Internal Network
 DEVICE=eth0
@@ -85,7 +92,7 @@ DEFROUTE=yes
 ONBOOT=yes</programlisting>
     </example>
 
-    <example>
+    <example os="fedora">
       <title><filename>/etc/sysconfig/network-scripts/ifcfg-eth1</filename></title>
       <programlisting language="ini"># External Network
 DEVICE=eth1
@@ -97,6 +104,40 @@ DEFROUTE=yes
 ONBOOT=yes</programlisting>
     </example>
 
+    <example os="opensuse">
+      <title><filename>/etc/sysconfig/network-scripts/ifcfg-eth0</filename></title>
+      <programlisting language="ini"># Internal Network
+FIXME</programlisting>
+    </example>
+
+    <example os="opensuse">
+      <title><filename>/etc/sysconfig/network-scripts/ifcfg-eth1</filename></title>
+      <programlisting language="ini"># External Network
+FIXME</programlisting>
+    </example>
+
+    <example os="ubuntu">
+      <title><filename>/etc/network/interfaces</filename></title>
+      <programlisting language="ini"># Internal Network
+auto eth0
+iface eth0 inet static
+    address 192.168.0.10
+    netmask 255.255.255.0
+
+# External Network
+auto eth1
+iface eth1 inet static
+    address 10.0.0.10
+    netmask 255.255.255.0
+    </programlisting>
+    </example>
+
+   <para>Once you've configured the network, restart the daemon for changes to take effect:</para>
+
+    <screen os="ubuntu"><prompt>#</prompt> <userinput>service networking restart</userinput></screen>
+    <screen os="fedora"><prompt>#</prompt> <userinput>service network restart</userinput></screen>
+    <screen os="opensuse"><prompt>#</prompt> <userinput>service FIXME restart</userinput></screen>
+
     <para>Set the hostname of each machine. Name the controller node
         <literal>controller</literal> and the first compute node
         <literal>compute1</literal>. These are the hostnames used in the
@@ -149,14 +190,10 @@ ONBOOT=yes</programlisting>
     <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>yum install ntp</userinput></screen>
     <screen os="opensuse"><prompt>#</prompt> <userinput>zypper install ntp</userinput></screen>
 
-    <para>Set up the NTP server on your controller node so that it receives data
+    <para os="rhel;fedora;centos;opensuse">Set up the NTP server on your
-      by modifying the <filename>ntp.conf</filename> file and restarting the
+      controller node so that it receives data by modifying the <filename>ntp.conf</filename>
-      service.</para>
+      file and restarting the service.</para>
 
-    <!-- FIXME: why is the sed necessary on ubuntu? -->
-    <screen os="ubuntu"><prompt>#</prompt> <userinput>sed -i 's/server ntp.ubuntu.com/server ntp.ubuntu.com\nserver 127.127.1.0\nfudge 127.127.1.0 stratum 10/g' /etc/ntp.conf</userinput>
-<prompt>#</prompt> <userinput>service ntp restart</userinput>
-<prompt>#</prompt> <userinput>chkconfig ntpd on</userinput></screen>
     <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>service ntpd start</userinput>
 <prompt>#</prompt> <userinput>chkconfig ntpd on</userinput></screen>
     <screen os="opensuse"><prompt>#</prompt> <userinput>systemctl start ntp.service</userinput>
@@ -197,18 +234,23 @@ hwclock -w</programlisting>
         <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>yum install mysql MySQL-python</userinput></screen>
         <screen os="opensuse"><prompt>#</prompt> <userinput>zypper install mysql-community-server-client python-mysql</userinput></screen></listitem>
     </itemizedlist>
-    <para>Start the MySQL database server and set it to start automatically when
+    <note os="ubuntu"><para>When you install the server package, you will
+    be asked to enter a root password for the database. Be sure to choose
+    a strong password and remember it - it will be needed later.</para></note>
+
+    <para os="rhel;centos;fedora;opensuse">Start the MySQL database server and set it to start automatically when
       the system boots.</para>
-    <screen os="rhel;centos;fedora;ubuntu"><prompt>#</prompt> <userinput>service mysqld start</userinput>
+    <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>service mysqld start</userinput>
 <prompt>#</prompt> <userinput>chkconfig mysqld on</userinput></screen>
     <screen os="opensuse"><prompt>#</prompt> <userinput>systemctl enable mysqld.service</userinput>
 <prompt>#</prompt> <userinput>systemctl enable mysqld.service</userinput></screen>
 
-    <para>Finally, it's a good idea to set a root password for your MySQL
+    <para os="rhel;centos;fedora;opensuse">Finally, it's a good idea to set a root password for your MySQL
       database. The OpenStack programs that set up databases and tables will
       prompt you for this password if it's set.</para>
 
-    <screen><prompt>#</prompt> <userinput>mysqladmin password <replaceable>newPassword</replaceable></userinput></screen>
+    <screen os="rhel;centos;fedora;opensuse"><prompt>#</prompt> <userinput>mysqladmin password <replaceable>newPassword</replaceable></userinput></screen>
+    <para os="rhel;centos;fedora;opensuse">Enter your desired password when prompted.</para>
   </section>
   <section xml:id="basics-queue">
     <title>Messaging Server</title>
@@ -247,7 +289,7 @@ hwclock -w</programlisting>
     <title>OpenStack Packages</title>
 
     <para>
-      Distributions releases and OpenStack releases are independent of
+      Distribution releases and OpenStack releases are often independent of
       each other and thus you might need to add some extra steps to access
       the latest OpenStack release after installation of the machine before
       installation of any OpenStack packages.
@@ -284,6 +326,9 @@ hwclock -w</programlisting>
 
     <procedure xml:id="ubuntu-cloud-archive" os="ubuntu">
       <title>To use the Ubuntu Cloud Archive for Havana</title>
+      <para>The <link xlink:href="https://wiki.ubuntu.com/ServerTeam/CloudArchive">Ubuntu Cloud Archive</link>
+      is a special repository that allows you to install newer releases of OpenStack on
+      the stable supported version of Ubuntu.</para>
       <step>
         <para>Install the keyring:
         <screen><prompt>#</prompt> <userinput>apt-get install ubuntu-cloud-keyring</userinput></screen>
@@ -302,7 +347,7 @@ hwclock -w</programlisting>
         </para>
       </step>
     </procedure>
-
+  <para>Congratulations, now you are ready to start installing OpenStack services!</para>
   </section>
 
 </chapter>

doc/install-guide/ch_keystone.xml

@@ -5,12 +5,6 @@
     xml:id="ch_keystone">
 
     <title>Configuring the Identity Service</title>
-
-    <!--
-        FIXME: Way too much stuff in the entire section. Just include part of
-        it for now. Might be worth just copying/rewriting directly.
-        TF: Fixed - by changing keystone_concepts.xml
-    -->
     <xi:include href="../common/section_keystone-concepts.xml"/>
     <xi:include href="section_keystone-install.xml"/>
     <xi:include href="section_keystone-users.xml"/>

doc/install-guide/section_keystone-install.xml

@@ -19,11 +19,19 @@
       with the username <literal>keystone</literal>. Replace
       <literal><replaceable>KEYSTONE_DBPASS</replaceable></literal>
       with a suitable password for the database user.</para>
-      <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/keystone/keystone.conf \
+      <screen os="rhel;centos;fedora;opensuse"><prompt>#</prompt> <userinput>openstack-config --set /etc/keystone/keystone.conf \
   sql connection mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@controller/keystone</userinput></screen>
+      <para os="ubuntu">Edit <filename>/etc/keystone/keystone.conf</filename> and change the <literal>[sql]</literal> section.</para>
+      <programlisting os="ubuntu" language="ini">
+...
+[sql]
+# The SQLAlchemy connection string used to connect to the database
+connection = mysql://keystone:KEYSTONE_DBPASS@controller/keystone
+...
+      </programlisting>
     </step>
 
-    <step>
+    <step os="rhel;centos;fedora;opensuse">
       <para>Use the <command>openstack-db</command> command to create the
       database and tables, as well as a database user called
       <literal>keystone</literal> to connect to the database. Replace
@@ -32,6 +40,20 @@
       <screen><prompt>#</prompt> <userinput>openstack-db --init --service keystone --password <replaceable>KEYSTONE_DBPASS</replaceable></userinput></screen>
     </step>
 
+    <step os="ubuntu">
+      <para>First, we need to create a database user called <literal>keystone</literal>, by logging in
+      as root using the password we set earlier.</para>
+      <screen><prompt>#</prompt> <userinput>mysql -u root -p</userinput>
+<prompt>mysql></prompt> <userinput>CREATE DATABASE keystone;</userinput>
+<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' \
+IDENTIFIED BY 'KEYSTONE_DBPASS';</userinput></screen>
+    </step>
+    <step os="ubuntu">
+      <para>We now start the keystone service and create its tables.</para>
+      <screen><prompt>#</prompt> <userinput>keystone-manage db_sync</userinput>
+<prompt>#</prompt> <userinput>service keystone restart</userinput></screen>
+    </step>
+
     <step>
       <para>You need to define an authorization token that is used as a
       shared secret between the Identity Service and other OpenStack services.
@@ -40,20 +62,35 @@
       <screen os="rhel;centos;fedora;opensuse"><prompt>#</prompt> <userinput>ADMIN_TOKEN=$(openssl rand -hex 10)</userinput>
 <prompt>#</prompt> <userinput>echo $ADMIN_TOKEN</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/keystone/keystone.conf DEFAULT admin_token $ADMIN_TOKEN</userinput></screen>
+      <screen os="ubuntu"><prompt>#</prompt> <userinput>openssl rand -hex 10</userinput></screen>
+<para os="ubuntu">Edit <filename>/etc/keystone/keystone.conf</filename> and
+       change the <literal>[DEFAULT]</literal> section, replacing ADMIN_TOKEN with the results of the command.</para>
+      <programlisting os="ubuntu" language="ini">
+[DEFAULT]
+# A "shared secret" between keystone and other openstack services
+admin_token = ADMIN_TOKEN
+...
+      </programlisting>
+
     </step>
 
-    <step>
+
+    <step os="rhel;centos;fedora;opensuse">
       <para>By default Keystone will use PKI tokens. Create the signing
       keys and certificates.</para>
       <screen><prompt>#</prompt> <userinput>keystone-manage pki_setup --keystone-user keystone --keystone-group keystone</userinput>
 <prompt>#</prompt> <userinput>chown -R keystone:keystone /etc/keystone/* /var/log/keystone/keystone.log</userinput></screen>
     </step>
 
-    <step>
+    <step os="ubuntu">
-      <para>Start the Identiy Service and enable it so it start when
+      <para>Restart the Identity service.</para>
+      <screen><prompt>#</prompt> <userinput>service keystone restart</userinput></screen>
+    </step>
+
+
+    <step os="rhel;fedora;centos;opensuse">
+      <para>Start the Identity Service and enable it so it start when
       the system boots.</para>
-      <screen os="ubuntu"><prompt>#</prompt> <userinput>service keystone start</userinput>
-<prompt>#</prompt> <userinput>chkconfig keystone on</userinput></screen>
       <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>service openstack-keystone start</userinput>
 <prompt>#</prompt> <userinput>chkconfig openstack-keystone on</userinput></screen>
       <screen os="opensuse"><prompt>#</prompt> <userinput>systemctl start openstack-keystone.service</userinput>

www/trunk/index.html

@@ -176,7 +176,7 @@
 					<dd><a
 					       href="http://docs.openstack.org/trunk/install-guide/install/apt/content/"
 					       >Installation Guide for Ubuntu
-					       12.04 (LTS)</a></dd>
+					       12.04 (LTS) Server</a></dd>
 					<dd><a
 					       href="http://docs.openstack.org/trunk/install-guide/install/zypper/content/"
 					       >Installation Guide for