Merge "Convert debconf files to RST"

doc/install-guide-rst/source/debconf/debconf-api-endpoints.rst

@@ -0,0 +1,78 @@
+======================
+Register API endpoints
+======================
+
+All Debian packages for API services, except the ``heat-api`` package,
+register the service in the Identity service catalog. This feature is
+helpful because API endpoints are difficult to remember.
+
+.. note::
+
+   The ``heat-common`` package and not the ``heat-api`` package configures the
+   Orchestration service.
+
+When you install a package for an API service, you are prompted to
+register that service. However, after you install or upgrade the package
+for an API service, Debian immediately removes your response to this
+prompt from the debconf database. Consequently, you are prompted to
+re-register the service with the Identity service. If you already
+registered the API service, respond ``no`` when you upgrade.
+
+.. image:: ../figures/debconf-screenshots/api-endpoint_1_register_endpoint.png
+
+|
+
+This screen registers packages in the Identity service catalog:
+
+.. image:: ../figures/debconf-screenshots/api-endpoint_2_keystone_server_ip.png
+
+|
+
+You are prompted for the Identity service ``admin_token`` value. The
+Identity Service uses this value to register the API service. When you
+set up the ``keystone`` package, this value is configured automatically.
+
+.. image:: ../figures/debconf-screenshots/api-endpoint_3_keystone_authtoken.png
+
+|
+
+This screen configures the IP addresses for the service. The
+configuration script automatically detects the IP address used by the
+interface that is connected to the default route (``/sbin/route`` and
+``/sbin/ip``).
+
+Unless you have a unique set up for your network, press **ENTER**.
+
+.. image:: ../figures/debconf-screenshots/api-endpoint_4_service_endpoint_ip_address.png
+
+|
+
+This screen configures the region name for the service. For example,
+``us-east-coast`` or ``europe-paris``.
+
+.. image:: ../figures/debconf-screenshots/api-endpoint_5_region_name.png
+
+|
+
+The Debian package post installation scripts will then perform the below
+commands for you:
+
+.. code-block:: ini
+   :linenos:
+
+   PKG_SERVICE_ID=$(pkgos_get_id keystone --os-token ${AUTH_TOKEN} \
+     --os-endpoint http://${KEYSTONE_ENDPOINT_IP}:35357/v2.0/ service-create \
+     --name ${SERVICE_NAME} --type ${SERVICE_TYPE} --description "${SERVICE_DESC}")
+   keystone --os-token ${AUTH_TOKEN} \
+     --os-endpoint http://${KEYSTONE_ENDPOINT_IP}:35357/v2.0/
+      endpoint-create \
+     --region "${REGION_NAME}" --service_id ${PKG_SERVICE_ID} \
+     --publicurl http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL} \
+     --internalurl http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL} \
+     --adminurl http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL})
+
+The values of ``AUTH_TOKEN``, ``KEYSTONE_ENDPOINT_IP``,
+``PKG_ENDPOINT_IP``, and ``REGION_NAME`` depend on the answer you will
+provide to the debconf prompts. But the values of ``SERVICE_NAME``,
+``SERVICE_TYPE``, ``SERVICE_DESC``, and ``SERVICE_URL`` are already
+pre-wired in each package, so you don't have to remember them.

doc/install-guide-rst/source/debconf/debconf-dbconfig-common.rst

@@ -0,0 +1,161 @@
+===========================================
+Configure the database with dbconfig-common
+===========================================
+
+Many of the OpenStack services need to be configured to access a
+database. These are configured through a DSN (Database Source Name)
+directive as follows:
+
+.. code-block:: ini
+
+   [database]
+   connection = mysql://keystone:0dec658e3f14a7d@localhost/keystonedb
+
+This ``connection`` directive will be handled by the ``dbconfig-common``
+package, which provides a standard Debian interface. It enables you to
+configure Debian database parameters. It includes localized prompts for
+many languages and it supports the following database backends: SQLite,
+MySQL, and PostgreSQL.
+
+By default, the ``dbconfig-common`` package configures the OpenStack
+services to use SQLite. So if you use debconf in non-interactive mode
+and without pre-seeding, the OpenStack services that you install will
+use SQLite.
+
+By default, ``dbconfig-common`` does not provide access to database servers
+over a network. If you want the ``dbconfig-common`` package to prompt for
+remote database servers that are accessed over a network and not through
+a UNIX socket file, reconfigure it, as follows:
+
+.. code-block:: console
+
+    # apt-get install dbconfig-common && dpkg-reconfigure dbconfig-common
+
+These screens appear when you re-configure the ``dbconfig-common`` package:
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_keep_admin_pass.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_used_for_remote_db.png
+
+|
+
+Unlike other debconf prompts, you cannot pre-seed the responses for the
+``dbconfig-common`` prompts by using ``debconf-set-selections``. Instead,
+you must create a file in :file:`/etc/dbconfig-common`. For example, you
+might create a keystone configuration file for ``dbconfig-common`` that is
+located in :file:`/etc/dbconfig-common/keystone.conf`, as follows:
+
+.. code-block:: ini
+   :linenos:
+
+   dbc_install='true'
+   dbc_upgrade='true'
+   dbc_remove=''
+   dbc_dbtype='mysql'
+   dbc_dbuser='keystone'
+   dbc_dbpass='PASSWORD'
+   dbc_dbserver=''
+   dbc_dbport=''
+   dbc_dbname='keystonedb'
+   dbc_dbadmin='root'
+   dbc_basepath=''
+   dbc_ssl=''
+   dbc_authmethod_admin=''
+   dbc_authmethod_user=''
+
+After you create this file, run this command:
+
+.. code-block:: console
+
+   # apt-get install keystone
+
+The Identity service is installed with MySQL as the database back end,
+``keystonedb`` as database name, and the localhost socket file. The
+corresponding DNS will then be:
+
+.. code-block:: ini
+
+   [database]
+   connection = mysql://keystone:PASSWORD@localhost/keystonedb
+
+The ``dbconfig-common`` package will configure MySQL for these access
+rights, and create the database for you. Since OpenStack 2014.1.1, all
+OpenStack packages in Debian are performing the following MySQL query
+after database creation (if you decide to use MySQL as a back-end):
+
+.. code-block:: ini
+
+   ALTER DATABASE keystone CHARACTER SET utf8 COLLATE utf8_unicode_ci
+
+So, if using Debian, you wont need to care about database creation,
+access rights and character sets. All that is handled for you by the
+packages.
+
+As an example, here are screenshots from the ``cinder-common`` package:
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_1_configure-with-dbconfig-yes-no.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_2_db-types.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_3_connection_method.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_4_mysql_root_password.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_5_mysql_app_password.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/dbconfig-common_6_mysql_app_password_confirm.png
+
+|
+
+By default in Debian, you can access the MySQL server from either
+localhost through the socket file or 127.0.0.1. To access it over the
+network, you must edit the :file:`/etc/mysql/my.cnf` file, and the
+``mysql.user`` table. To do so, Debian provides a helper script in the
+``openstack-deploy`` package. To use it, install the package and run:
+
+.. code-block:: console
+
+   # /usr/share/openstack-deploy/mysql-remote-root
+
+Alternatively, if you do not want to install this package, run this
+script to enable remote root access:
+
+.. code-block:: bash
+   :linenos:
+
+   #!/bin/sh
+
+   set -e
+
+   SQL="mysql --defaults-file=/etc/mysql/debian.cnf -Dmysql -e"
+
+   ROOT_PASS=`${SQL} "SELECT Password FROM user WHERE User='root' LIMIT 1;" \
+     | tail -n 1`
+   ${SQL} "REPLACE INTO user SET host='%', user='root',\
+     password='${ROOT_PASS}', Select_priv='Y', Insert_priv='Y',\
+     Update_priv='Y', Delete_priv='Y', Create_priv='Y', Drop_priv='Y',\
+     Reload_priv='Y', Shutdown_priv='Y', Process_priv='Y',  File_priv='Y',\
+     Grant_priv='Y', References_priv='Y', Index_priv='Y', Alter_priv='Y',\
+     Super_priv='Y', Show_db_priv='Y', Create_tmp_table_priv='Y',\
+     Lock_tables_priv='Y', Execute_priv='Y', Repl_slave_priv='Y',\
+     Repl_client_priv='Y', Create_view_priv='Y', Show_view_priv='Y',\
+     Create_routine_priv='Y', Alter_routine_priv='Y', Create_user_priv='Y',\
+     Event_priv='Y', Trigger_priv='Y' "
+   ${SQL} "FLUSH PRIVILEGES"
+   sed -i 's|^bind-address[ \t]*=.*|bind-address = 0.0.0.0|' /etc/mysql/my.cnf
+   /etc/init.d/mysql restart
+
+You must enable remote access before you install OpenStack services on
+multiple nodes.

doc/install-guide-rst/source/debconf/debconf-keystone-authtoken.rst

@@ -0,0 +1,56 @@
+======================================
+Services and the [keystone_authtoken]
+======================================
+
+Because most OpenStack services must access the Identity service, you
+must configure the IP address of the ``keystone`` server to be able to
+access it. You must also configure the ``admin_tenant_name``,
+``admin_user``, and ``admin_password`` options for each service to work.
+
+Generally, this section looks like this:
+
+.. code-block:: ini
+   :linenos:
+
+   [keystone_authtoken]
+   auth_uri = http://controller:5000/v2.0
+   identity_uri = http://controller:35357
+   admin_tenant_name = %SERVICE_TENANT_NAME%
+   admin_user = %SERVICE_USER%
+   admin_password = %SERVICE_PASSWORD%
+
+The debconf system helps users configure the ``auth_uri``,
+``identity_uri``, ``admin_tenant_name``, ``admin_user``, and
+``admin_password`` options.
+
+The following screens show an example Image service configuration:
+
+.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_server_hostname.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_admin_tenant_name.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_tenant_admin_user.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_admin_password.png
+
+This information is stored in the configuration file for each service.
+For example:
+
+.. code-block:: ini
+   :linenos:
+
+   /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
+
+The Debian OpenStack packages offer automation for this, so OpenStack
+users do not have to manually edit the configuration files.

doc/install-guide-rst/source/debconf/debconf-rabbitmq.rst

@@ -0,0 +1,34 @@
+===============================
+RabbitMQ credentials parameters
+===============================
+
+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 ``ceilometer-common`` package:
+
+.. image:: ../figures/debconf-screenshots/rabbitmq-host.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/rabbitmq-user.png
+
+|
+
+.. image:: ../figures/debconf-screenshots/rabbitmq-password.png
+
+|
+
+These debconf screens appear in: ``ceilometer-common``, ``cinder-common``,
+``glance-common``, ``heat-common``, ``neutron-common``, and ``nova-common``.
+
+This will configure the below directives (example from :file:`nova.conf`):
+
+.. code-block:: ini
+
+   [DEFAULT]
+   rabbit_host=localhost
+   rabbit_userid=guest
+   rabbit_password=guest
+
+The other directives concerning RabbitMQ will stay untouched.

doc/install-guide-rst/source/debconf/debconf.rst

@@ -6,9 +6,7 @@ Configure OpenStack with debconf
    :maxdepth: 2
 
    debconf-concepts.rst
-
-.. todo(karenb)
    debconf-dbconfig-common.rst
    debconf-rabbitmq.rst
-   debconf-keystone_authtoken.rst
+   debconf-keystone-authtoken.rst
    debconf-api-endpoints.rst