Adds a new debconf chapter

This patch adds a new debconf chapter in the Debian docs.
It describe generalities about the Debconf OpenStack. It
explains how the following is handled:
- Database config (using dbconfig-common)
- RabbitMQ config
- API endpoint registrations
- keystone_authtoken config
- preseeding

Also, a number of screenshots are added.

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

into smaller patches.

backport: havana
Change-Id: Ia5d8e5fc3d397f9441ecb50ef4a3458672307bdc

doc/install-guide/bk_openstackinstallguide.xml

@@ -530,6 +530,7 @@
     <xi:include href="ch_preface.xml"/>
     <xi:include href="ch_overview.xml"/>
     <xi:include href="ch_basics.xml"/>
+    <xi:include href="ch_debconf.xml"/>
     <xi:include href="ch_keystone.xml"/>
     <xi:include href="ch_glance.xml"/>
     <xi:include href="ch_nova.xml"/>

doc/install-guide/ch_debconf.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="ch_debconf" os="debian">
+    <title>Configure OpenStack with Debconf</title>
+    <xi:include href="section_debconf-concepts.xml"/>
+    <xi:include href="section_debconf-dbconfig-common.xml"/>
+    <xi:include href="section_debconf-rabbitqm.xml"/>
+    <xi:include href="section_debconf-keystone_authtoken.xml"/>
+    <xi:include href="section_debconf-api-endpoints.xml"/>
+</chapter>

doc/install-guide/section_debconf-api-endpoints.xml

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xml:id="debconf-api-endpoints"
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+  <title>API end-points registration</title>
+  <para>Every Debian package that contains an API service contains the
+    debconf logic to register themselves into the Keystone end-point
+    catalogue (at the exception of the Orchestration service, which is
+    configured within the <systemitem class="service">heat-common</systemitem>
+    package and not in the <systemitem class="service">heat-api</systemitem>
+    package). This is very useful because the URLs and ports of each API
+    are difficult to remember.</para>
+    <para>When installing a package containing an API server, the first
+    debconf screen prompts users whether to register the service.
+    However, after the package is installed (or upgraded), the answer
+    to this prompt is immediately removed form the debconf database.
+    As a consequence, this debconf screen displays every time, which
+    enables the user to re-register the API in the Identity Service,
+    but making sure that it is registered only once.</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/api-endpoint_1_register_endpoint.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <para>If you answer <literal>yes</literal> to the previous prompt
+    and the API service is already registered in the Identity Service
+    database, do not answer <literal>yes</literal> again when you
+    upgrade.</para>
+  <para>The following debconf screens are necessary for the package to
+    reach Keystone and register itself in the catalog.</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/api-endpoint_2_keystone_server_ip.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <para>The following screen prompts for the value in the admin_token
+    of Keystone, which is necessary for registering an API server in
+    the Identity Service. This admin_token is normally configured
+    automatically when setting-up the <systemitem class="library">keystone</systemitem>
+    package.</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/api-endpoint_3_keystone_authtoken.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <para>The following screen is the IP addresses of the service that
+    the user is configuring. The configuration script automatically
+    detects the IP address by using <code>/sbin/route</code> and
+      <code>/sbin/ip</code> (detecting the IP address used by the
+    interface that is connected to the default route). So in most
+    cases, and unless you have a very specific network set up, you
+    simply press ENTER.</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/api-endpoint_4_service_endpoint_ip_address.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <para>The last parameter is the region name for the service you are
+    currently configuring. For example, <code>us-east-coast</code> or
+      <code>europe-paris</code>.</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/api-endpoint_5_region_name.png"
+      />
+    </imageobject>
+  </mediaobject>
+</section>

doc/install-guide/section_debconf-concepts.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xml:id="debconf-general-principles"
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+  <title>Debconf concepts</title>
+  <para>This chapter explains how to use the Debian <systemitem
+      class="library">debconf</systemitem> and <systemitem
+      class="library">dbconfig-common</systemitem> packages to
+    configure OpenStack services. If you are familiar with these
+    packages and pre-seeding, you can proceed to <xref
+      linkend="ch_keystone"/>.</para>
+  <section xml:id="debian_packages">
+    <title>The Debian packages</title>
+    <para>The rules described here are from the <link
+        xlink:href="http://www.debian.org/doc/debian-policy/"
+          ><citetitle>Debian Policy Manual</citetitle></link>. If any
+      rule described in this chapter is not respected, you have found
+      a serious bug that must be fixed.</para>
+    <para>When you install or upgrade a Debian package, all
+      configuration file values are preserved. Using the <systemitem
+        class="library">debconf</systemitem> database as a registry is
+      considered a bug in Debian. If you edit something in any
+      OpenStack configuration file, the <systemitem class="library"
+        >debconf</systemitem> package reads that value when it
+      prepares to prompt the user. For example, to change the log in
+      name for the RabbitMQ messaging queue for a service, you can
+      edit its value in the corresponding configuration file.</para>
+    <para>To opt out of using the <systemitem class="library"
+        >debconf</systemitem> package, run the
+        <command>dpkg-reconfigure</command> command and select
+      non-interactive mode:</para>
+    <screen><prompt>#</prompt> <userinput>dpkg-reconfigure -plow debconf</userinput></screen>
+    <para>Then, <systemitem class="library">debconf</systemitem> does
+      not prompt you.</para>
+    <para>Another way to disable the <systemitem class="library"
+        >debconf</systemitem> package is to prefix the
+        <command>apt</command> command with
+        <literal>DEBIAN_FRONTEND=noninteractive</literal>, as
+      follows:</para>
+    <screen><prompt>#</prompt> <userinput>DEBIAN_FRONTEND=noninteractive apt-get install nova-api</userinput></screen>
+    <para>If you configure a package with <systemitem class="library"
+        >debconf</systemitem> incorrectly, you can re-configure it, as
+      follows:</para>
+    <screen><prompt>#</prompt> <userinput>dpkg-reconfigure <replaceable>PACKAGE-NAME</replaceable></userinput></screen>
+    <para>This calls the post-installation script for the
+        <replaceable>PACKAGE-NAME</replaceable> package after the user
+      responds to all prompts. If you cannot install a Debian package
+      in a non-interactive way, you have found a release-critical bug
+      in Debian. Report it to the Debian bug tracking system.</para>
+    <para>Generally, the <systemitem class="library"
+        >-common</systemitem> packages install the configuration
+      files. For example, the <literal>glance-common</literal> package
+      installs the <filename>glance-api.conf</filename> and
+        <filename>glance-registry.conf</filename> files. So, for the
+      Image Service, you must re-configure the
+        <literal>glance-common</literal> package. The same applies for
+        <literal>cinder-common</literal>,
+        <literal>nova-common</literal>, and
+        <literal>heat-common</literal> packages.</para>
+    <para>In <systemitem class="library">debconf</systemitem>, the
+      higher the <firstterm>priority</firstterm> for a screen, the
+      greater the chance that the user sees that screen. If a
+        <systemitem class="library">debconf</systemitem> screen has
+        <literal>medium</literal> priority and you configure the
+      Debian system to show only <literal>critical</literal> prompts,
+      which is the default in Debian, the user does not see that
+        <systemitem class="library">debconf</systemitem> screen.
+      Instead, the default for the related package is used. In the
+      Debian OpenStack packages, a number of <systemitem
+        class="library">debconf</systemitem> screens are set with
+        <literal>medium</literal> priority. Consequently, if you want
+      to respond to all <systemitem class="library"
+        >debconf</systemitem> screens from the Debian OpenStack
+      packages, you must run the following command and select the
+        <literal>medium</literal> priority before you install any
+      packages:</para>
+    <screen><prompt>#</prompt> <userinput>dpkg-reconfigure debconf</userinput></screen>
+    <note>
+      <para>The packages do not require pre-depends. If <systemitem
+          class="library">dbconfig-common</systemitem> is already
+        installed on the system, the user sees all prompts. However,
+        you cannot define the order in which the <systemitem
+          class="library">debconf</systemitem> screens appear. The user
+        must make sense of it even if the prompts appear in an
+        illogical order.</para>
+    </note>
+  </section>
+  <xi:include href="section_debconf-preseeding.xml"/>
+</section>

doc/install-guide/section_debconf-dbconfig-common.xml

@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xml:id="debconf-dbconfig-common"
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+  <title>dbconfig-common package</title>
+  <para>The <systemitem class="library">dbconfig-common</systemitem>
+    package provides a standard Debian interface that enables you to
+    configure Debian database parameters. It includes localized
+    prompts for many languages and it supports OpenStack-supported
+    database back ends, which are SQLite, MySQL, and
+    PostgreSQL.</para>
+  <para>By default, the <systemitem class="library"
+      >dbconfig-common</systemitem> system will configure your packages to
+      use SQLite3. So if you use
+    <systemitem class="library">debconf</systemitem> in non-interactive
+    mode without using pre-seeding, the OpenStack services that you
+    install will be using SQLite3.</para>
+  <para>By default, <systemitem class="library"
+      >dbconfig-common</systemitem> does not provide access to
+    database servers over a network. If you want the <systemitem
+      class="library">dbconfig-common</systemitem> package to prompt
+    for remote database servers that are accessed over a network and
+    not through a UNIX socket file, you must reconfigure it, as
+    follows:</para>
+  <screen><prompt>#</prompt> <userinput>apt-get install dbconfig-common &amp;&amp; dpkg-reconfigure dbconfig-common</userinput></screen>
+  <para>Here is a snapshot of the two configuration screens that
+    appear when you re-configure the <systemitem class="service"
+      >dbconfig-common</systemitem> package:</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_keep_admin_pass.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_used_for_remote_db.png"/>
+    </imageobject>
+  </mediaobject>
+  <para>Unlike other debconf prompts, you cannot pre-seed the answers
+    for the <systemitem class="library">dbconfig-common</systemitem>
+    prompts by using <command>debconf-set-selections</command>. Instead, you
+    must create a file in <filename>/etc/dbconfig-common</filename>.
+    For example, you might create a keystone configuration file for
+      <systemitem class="library">dbconfig-common</systemitem> that is
+    located in
+    <filename>/etc/dbconfig-common/keystone.conf</filename>:</para>
+  <programlisting language="ini">dbc_install='true'
+dbc_upgrade='true'
+dbc_remove=''
+dbc_dbtype='mysql'
+dbc_dbuser='keystone'
+dbc_dbpass='MyKeyStoneDbPassWord'
+dbc_dbserver=''
+dbc_dbport=''
+dbc_dbname='keystonedb'
+dbc_dbadmin='root'
+dbc_basepath=''
+dbc_ssl=''
+dbc_authmethod_admin=''
+dbc_authmethod_user=''</programlisting>
+  <para>After you create this file, run the following command:</para>
+  <screen><prompt>#</prompt> <userinput>apt-get install keystone</userinput></screen>
+  <para>The Identity Service is installed with MySQL as the database
+    back end, keystonedb as database name, and the localhost socket
+    file.</para>
+  <para>The following screens are in the <systemitem class="service">cinder-common</systemitem>
+    package.</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_1_configure-with-dbconfig-yes-no.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_2_db-types.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_3_connection_method.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_4_mysql_root_password.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_5_mysql_app_password.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="40"
+        fileref="figures/debconf-screenshots/dbconfig-common_6_mysql_app_password_confirm.png"/>
+    </imageobject>
+  </mediaobject>
+</section>

doc/install-guide/section_debconf-keystone_authtoken.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xml:id="debconf-keystone_authtoken"
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+  <title>Services and keystone_authtoken</title>
+  <para>Because most OpenStack services must access the Identity
+    Service, you must configure the IP address of the
+      <code>keystone</code> server to be able to access it. You must
+    also configure the <code>admin_tenant_name</code>,
+      <code>admin_user</code>, and <code>admin_password</code> options
+    for each service to work.</para>
+  <para>Generally, this section looks like this:</para>
+  <programlisting language="ini">[keystone_authtoken]
+auth_host = 127.0.0.1
+auth_port = 35357
+auth_protocol = http
+admin_tenant_name = %SERVICE_TENANT_NAME%
+admin_user = %SERVICE_USER%
+admin_password = %SERVICE_PASSWORD%</programlisting>
+  <para>The debconf system helps users configure the
+      <code>auth_host</code>, <code>admin_tenant_name</code>,
+      <code>admin_user</code> and <code>admin_password</code>
+    options.</para>
+  <para>The following screens show an example Image Service
+    configuration:</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/service_keystone_authtoken_server_hostname.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/service_keystone_authtoken_admin_tenant_name.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/service_keystone_authtoken_tenant_admin_user.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/service_keystone_authtoken_admin_password.png"
+      />
+    </imageobject>
+  </mediaobject>
+  <para>This information is stored in the configuration file for each
+    service. For example:</para>
+  <programlisting os="ubuntu;debian" language="ini">/etc/ceilometer/ceilometer.conf
+/etc/nova/api-paste.ini
+/etc/glance/glance-api-paste.ini
+/etc/glance/glance-registry.ini
+/etc/cinder/cinder.conf
+/etc/neutron/neutron.conf</programlisting>
+  <para>The Debian OpenStack packages offer automation for this, so
+    OpenStack users do not have to manually edit the configuration
+    files.</para>
+</section>

doc/install-guide/section_debconf-preseeding.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xml:id="debconf-preseeding"
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+  <title>Debconf preseeding</title>
+  <para>You can <firstterm>pre-seed</firstterm> all <systemitem
+  class="library">debconf</systemitem> prompts.
+    To pre-seed means to write answers to the <systemitem
+    class="library">debconf</systemitem> database so that
+    the user is not prompted for an answer. Pre-seeding enables a
+    hands-free installation for users. The package maintainer creates
+    scripts that automatically configure the services.</para>
+  <para>The following example shows how to pre-seed an automated MySQL
+    Server installation:</para>
+  <programlisting language="bash">MYSQL_PASSWORD=<replaceable>MYSQL_PASSWORD</replaceable>
+echo "mysql-server-5.5 mysql-server/root_password password ${<replaceable>MYSQL_PASSWORD</replaceable>}
+mysql-server-5.5 mysql-server/root_password seen true
+mysql-server-5.5 mysql-server/root_password_again password ${<replaceable>MYSQL_PASSWORD</replaceable>}
+mysql-server-5.5 mysql-server/root_password_again seen true
+" | debconf-set-selections
+DEBIAN_FRONTEND=noninteractive apt-get install -y --force-yes mysql-server</programlisting>
+  <para>The <code>seen true</code> option tells <systemitem class="library">debconf</systemitem>
+  that a specified screen was already seen by the user, so do not show it
+  again. This option is useful for upgrades.</para>
+</section>

doc/install-guide/section_debconf-rabbitqm.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xml:id="debconf-rabbitqm"
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+  <title>RabbitMQ parameters</title>
+  <para>For every package that must connect to a Messaging Server, the
+    Debian package enables you to configure the IP address for that
+    server and the user name and password that is used to connect. The
+    following example shows configuration with the <systemitem
+      class="service">ceilometer-common</systemitem> package:</para>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/rabbitmq-host.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/rabbitmq-user.png"/>
+    </imageobject>
+  </mediaobject>
+  <mediaobject>
+    <imageobject>
+      <imagedata scale="50"
+        fileref="figures/debconf-screenshots/rabbitmq-password.png"/>
+    </imageobject>
+  </mediaobject>
+  <para>These debconf screens appear in: <systemitem class="service"
+      >ceilometer-common</systemitem>, <systemitem class="service"
+      >cinder-common</systemitem>, <systemitem class="service"
+      >glance-common</systemitem>, <systemitem class="service"
+      >heat-common</systemitem>, <systemitem class="service"
+      >neutron-common</systemitem> and <systemitem class="service"
+      >nova-common</systemitem>.</para>
+</section>