Debian specifics for keystone

This patch adds Debian specifics for the Keystone install
chapter.

Note that this is a break-down of:
https://review.openstack.org/54394/

into smaller patches.

backport: havana

Change-Id: I9c7383f3daffab06fbe12d35208923eda00b5207

doc/install-guide/ch_keystone.xml

@@ -3,8 +3,7 @@
     xmlns:xi="http://www.w3.org/2001/XInclude"
     xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
     xml:id="ch_keystone">
-
+    <title>Configure the Identity Service</title>
-    <title>Configuring the Identity Service</title>
     <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

@@ -11,29 +11,12 @@
       <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install keystone</userinput></screen>
       <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-keystone python-keystoneclient</userinput></screen>
       <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-keystone python-keystoneclient openstack-utils</userinput></screen>
-      <note os="debian"><title>Note for Debian users</title>
-      <para>Note that on Debian system, the above is all what is needed
-      to install the Identity Service. During the setup, the debconf system will prompt
-      the user for the database access information. It will then
-      automatically create the database, configure access rights,
-      and then modify <filename>/etc/keystone/keystone.conf</filename> to reflect this
-      configuration. Debconf will also be used to configure the AUTH_TOKEN
-      administrator password.</para>
-      <para>The Debian package will then perform the
-      <code>keystone-manage db_sync</code> for you, and create an "admin/admin" tenant
-      and user, which you can later use for setting-up the other OpenStack
-      service (later called "auth token" in this documentation). Finally,
-      the package will also ask the user to setup the keystone endpoint.
-      Therefore, if you use Debian, you can skip all the remaining steps below.</para>
-      <para>If you need to reconfigure Keystone, you can use:
-      <screen><prompt>#</prompt> <userinput>dpkg-reconfigure -plow keystone</userinput></screen>
-      or edit the configuration files and manually restart the daemon.</para>
-      <para>Remember that for using a database server that is installed remotely,
-      you need to call before installing the Identity Service:
-      <screen><prompt>#</prompt> <userinput>apt-get install dbconfig-common &amp;&amp; dpkg-reconfigure -plow dbconfig-common</userinput></screen></para>
-      </note>
     </step>
-    <step>
+    <step os="debian">
+      <para>Answer to the <systemitem class="library">debconf</systemitem> and
+      <systemitem class="library">dbconfig-common</systemitem> questions for setting-up the database.</para>
+    </step>
+    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
       <para>The Identity Service uses a database to store information.
       Specify the location of the database in the configuration file.
       In this guide, we use a MySQL database on the controller node
@@ -42,8 +25,8 @@
       with a suitable password for the database user.</para>
       <screen os="rhel;centos;fedora;opensuse;sles"><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;debian">Edit <filename>/etc/keystone/keystone.conf</filename> and change the <literal>[sql]</literal> section.</para>
+      <para os="ubuntu">Edit <filename>/etc/keystone/keystone.conf</filename> and change the <literal>[sql]</literal> section.</para>
-      <programlisting os="ubuntu;debian" language="ini">
+      <programlisting os="ubuntu" language="ini">
 ...
 [sql]
 # The SQLAlchemy connection string used to connect to the database
@@ -61,7 +44,7 @@ connection = mysql://keystone:KEYSTONE_DBPASS@controller/keystone
       <screen><prompt>#</prompt> <userinput>openstack-db --init --service keystone --password <replaceable>KEYSTONE_DBPASS</replaceable></userinput></screen>
     </step>
 
-    <step os="ubuntu;debian">
+    <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>
@@ -71,13 +54,73 @@ IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput>
 <prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' \
 IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput></screen>
     </step>
-    <step os="ubuntu;debian">
+    <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 os="debian">
+      <para>You need to define an authorization token that is used as a
+      shared secret between the Identity Service and other OpenStack services.
+      Fill-in the <systemitem class="library">debconf</systemitem> prompt with the value that will be put in the
+      <code>admin_token</code> directive of <filename>keystone.conf</filename>. It is
+      recommended to generate this password with <command>openssl rand -hex 10</command>.
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_1_admin_token.png"/>
+          </imageobject>
+        </mediaobject>
+      </para>
+      <para>Later on, you can verify that <filename>/etc/keystone/keystone.conf</filename>
+      contains the password you have set using <systemitem class="library">debconf</systemitem>:
+      <programlisting language="ini">
+[DEFAULT]
+# A "shared secret" between keystone and other openstack services
+admin_token = ADMIN_TOKEN
+...
+      </programlisting></para>
+    </step>
+    <step os="debian">
+      <para>Answer to the <systemitem class="library">debconf</systemitem> prompts to create an admin tenant.
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_2_register_admin_tenant_yes_no.png"/>
+          </imageobject>
+        </mediaobject>
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_3_admin_user_name.png"/>
+          </imageobject>
+        </mediaobject>
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_4_admin_user_email.png"/>
+          </imageobject>
+        </mediaobject>
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_5_admin_user_pass.png"/>
+          </imageobject>
+        </mediaobject>
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_6_admin_user_pass_confirm.png"/>
+          </imageobject>
+        </mediaobject>
+      </para>
+    </step>
     <step>
+      <para>If this is the first time you install Keystone, then you should
+      register Keystone in the Keystone catalogue of services:
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_7_register_endpoint.png"/>
+          </imageobject>
+        </mediaobject>
+      </para>
+    </step>
+    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
       <para>You need to define an authorization token that is used as a
       shared secret between the Identity Service and other OpenStack services.
       Use <command>openssl</command> to generate a random token, then store it
@@ -85,18 +128,17 @@ IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput></screen>
       <screen os="rhel;centos;fedora;opensuse;sles"><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;debian"><prompt>#</prompt> <userinput>openssl rand -hex 10</userinput></screen>
+      <screen os="ubuntu"><prompt>#</prompt> <userinput>openssl rand -hex 10</userinput></screen>
       <para os="sles;opensuse">For SUSE Linux Enterprise use instead as first command:</para>
       <screen os="opensuse;sles"><prompt>#</prompt> <userinput>ADMIN_TOKEN=$(openssl rand 10|hexdump  -e '1/1 "%.2x"')</userinput></screen>
-<para os="ubuntu;debian">Edit <filename>/etc/keystone/keystone.conf</filename> and
+<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;debian" language="ini">
+      <programlisting os="ubuntu" language="ini">
 [DEFAULT]
 # A "shared secret" between keystone and other openstack services
 admin_token = ADMIN_TOKEN
 ...
       </programlisting>
-
     </step>
 
 
@@ -116,7 +158,7 @@ admin_token = ADMIN_TOKEN
 <prompt>#</prompt> <userinput>sed -e "s,%SERVICE_HOST%,192.168.0.10,g" -e "s/%S3_SERVICE_PORT%/8080/" \
    $KEYSTONE_CATALOG.sample > $KEYSTONE_CATALOG</userinput></screen>
     </step>
-    <step os="ubuntu;debian">
+    <step os="ubuntu">
       <para>Restart the Identity service.</para>
       <screen><prompt>#</prompt> <userinput>service keystone restart</userinput></screen>
     </step>

doc/install-guide/section_keystone-services.xml

@@ -1,16 +1,9 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="keystone-services">
+         xml:id="keystone-services"
+         os="rhel;centos;fedora;opensuse;sles;ubuntu">
   <title>Defining Services and API Endpoints</title>
 
-  <note os="debian"><title>Note for Debian users</title>
-  <para>On Debian systems, the Keystone package
-  will prompt the user for automatically creating the service end API
-  endpoint of Keystone (in the Keystone database itself). So if you
-  directed the package to do so, you don't need to perform the commands
-  detailed in this section, as it will have been done automatically.
-  However, it is advised to still read it to understand what has been
-  done by the Keystone package.</para></note>
   <para>The Identity Service also tracks what OpenStack services are
   installed and where to locate them on the network. For each service
   on your OpenStack installation, you must call

doc/install-guide/section_keystone-users.xml

@@ -1,7 +1,7 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          version="5.0"
-         xml:id="keystone-users">
+         xml:id="keystone-users" os="rhel;centos;fedora;opensuse;sles;ubuntu">
   <title>Defining Users, Tenants, and Roles</title>
 
   <para>Once Keystone is installed and running, you set up users, tenants,