Move FAQ to a section-based format
Move to a section-based format, and add a TOC so we can see an
overview of the questions.
Change-Id: Ie480f2ab759a5a7081d4dc7d2491b44a85b6503a
diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index 0437ec2..87f8469 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -2,99 +2,120 @@
FAQ
===
-- `General Questions <#general>`__
-- `Operation and Configuration <#ops_conf>`__
-- `Miscellaneous <#misc>`__
+.. contents::
+ :local:
General Questions
=================
-Q: Can I use DevStack for production?
+Can I use DevStack for production?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- A: DevStack is targeted at developers and CI systems to use the
- raw upstream code. It makes many choices that are not appropriate
- for production systems.
+DevStack is targeted at developers and CI systems to use the raw
+upstream code. It makes many choices that are not appropriate for
+production systems.
- Your best choice is probably to choose a `distribution of
- OpenStack
- <https://www.openstack.org/marketplace/distros>`__.
+Your best choice is probably to choose a `distribution of OpenStack
+<https://www.openstack.org/marketplace/distros/distribution>`__.
-Q: Why a shell script, why not chef/puppet/...
- A: The script is meant to be read by humans (as well as ran by
- computers); it is the primary documentation after all. Using a
- recipe system requires everyone to agree and understand chef or
- puppet.
+Why a shell script, why not chef/puppet/...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Q: I'd like to help!
- A: That isn't a question, but please do! The source for DevStack is
- at
- `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
- and bug reports go to
- `LaunchPad <http://bugs.launchpad.net/devstack/>`__. Contributions
- follow the usual process as described in the `developer
- guide <http://docs.openstack.org/infra/manual/developers.html>`__. This Sphinx
- documentation is housed in the doc directory.
+The script is meant to be read by humans (as well as ran by
+computers); it is the primary documentation after all. Using a recipe
+system requires everyone to agree and understand chef or puppet.
-Q: Why not use packages?
- A: Unlike packages, DevStack leaves your cloud ready to develop -
- checkouts of the code and services running in screen. However, many
- people are doing the hard work of packaging and recipes for
- production deployments.
+I'd like to help!
+~~~~~~~~~~~~~~~~~
-Q: Why isn't $MY\_FAVORITE\_DISTRO supported?
- A: DevStack is meant for developers and those who want to see how
- OpenStack really works. DevStack is known to run on the
- distro/release combinations listed in ``README.md``. DevStack is
- only supported on releases other than those documented in
- ``README.md`` on a best-effort basis.
+That isn't a question, but please do! The source for DevStack is at
+`git.openstack.org
+<https://git.openstack.org/cgit/openstack-dev/devstack>`__ and bug
+reports go to `LaunchPad
+<http://bugs.launchpad.net/devstack/>`__. Contributions follow the
+usual process as described in the `developer guide
+<http://docs.openstack.org/infra/manual/developers.html>`__. This
+Sphinx documentation is housed in the doc directory.
-Q: Are there any differences between Ubuntu and Centos/Fedora support?
- A: Both should work well and are tested by DevStack CI.
+Why not use packages?
+~~~~~~~~~~~~~~~~~~~~~
-Q: Why can't I use another shell?
- A: DevStack now uses some specific bash-ism that require Bash 4, such
- as associative arrays. Simple compatibility patches have been accepted
- in the past when they are not complex, at this point no additional
- compatibility patches will be considered except for shells matching
- the array functionality as it is very ingrained in the repo and project
- management.
+Unlike packages, DevStack leaves your cloud ready to develop -
+checkouts of the code and services running in screen. However, many
+people are doing the hard work of packaging and recipes for production
+deployments.
-Q: Can I test on OS/X?
- A: Some people have success with bash 4 installed via
- homebrew to keep running tests on OS/X.
+Why isn't $MY\_FAVORITE\_DISTRO supported?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DevStack is meant for developers and those who want to see how
+OpenStack really works. DevStack is known to run on the distro/release
+combinations listed in ``README.md``. DevStack is only supported on
+releases other than those documented in ``README.md`` on a best-effort
+basis.
+
+Are there any differences between Ubuntu and Centos/Fedora support?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Both should work well and are tested by DevStack CI.
+
+Why can't I use another shell?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DevStack now uses some specific bash-ism that require Bash 4, such as
+associative arrays. Simple compatibility patches have been accepted in
+the past when they are not complex, at this point no additional
+compatibility patches will be considered except for shells matching
+the array functionality as it is very ingrained in the repo and
+project management.
+
+Can I test on OS/X?
+~~~~~~~~~~~~~~~~~~~
+
+Some people have success with bash 4 installed via homebrew to keep
+running tests on OS/X.
Operation and Configuration
===========================
-Q: Can DevStack handle a multi-node installation?
- A: Yes, see :doc:`multinode lab guide <guides/multinode-lab>`
+Can DevStack handle a multi-node installation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Q: How can I document the environment that DevStack is using?
- A: DevStack includes a script (``tools/info.sh``) that gathers the
- versions of the relevant installed apt packages, pip packages and
- git repos. This is a good way to verify what Python modules are
- installed.
+Yes, see :doc:`multinode lab guide <guides/multinode-lab>`
-Q: How do I turn off a service that is enabled by default?
- A: Services can be turned off by adding ``disable_service xxx`` to
- ``local.conf`` (using ``n-vol`` in this example):
+How can I document the environment that DevStack is using?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DevStack includes a script (``tools/info.sh``) that gathers the
+versions of the relevant installed apt packages, pip packages and git
+repos. This is a good way to verify what Python modules are
+installed.
+
+How do I turn off a service that is enabled by default?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Services can be turned off by adding ``disable_service xxx`` to
+``local.conf`` (using ``n-vol`` in this example):
::
disable_service n-vol
-Q: Is enabling a service that defaults to off done with the reverse of the above?
- A: Of course!
+Is enabling a service that defaults to off done with the reverse of the above?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Of course!
::
enable_service qpid
-Q: How do I run a specific OpenStack milestone?
- A: OpenStack milestones have tags set in the git repo. Set the
- appropriate tag in the ``*_BRANCH`` variables in ``local.conf``.
- Swift is on its own release schedule so pick a tag in the Swift repo
- that is just before the milestone release. For example:
+How do I run a specific OpenStack milestone?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenStack milestones have tags set in the git repo. Set the
+appropriate tag in the ``*_BRANCH`` variables in ``local.conf``.
+Swift is on its own release schedule so pick a tag in the Swift repo
+that is just before the milestone release. For example:
::
@@ -107,16 +128,16 @@
NEUTRON_BRANCH=stable/kilo
SWIFT_BRANCH=2.3.0
-Q: What can I do about RabbitMQ not wanting to start on my fresh new VM?
- A: This is often caused by ``erlang`` not being happy with the
- hostname resolving to a reachable IP address. Make sure your
- hostname resolves to a working IP address; setting it to 127.0.0.1
- in ``/etc/hosts`` is often good enough for a single-node
- installation. And in an extreme case, use ``clean.sh`` to eradicate
- it and try again.
+What can I do about RabbitMQ not wanting to start on my fresh new VM?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Q: How can I set up Heat in stand-alone configuration?
- A: Configure ``local.conf`` thusly:
+This is often caused by ``erlang`` not being happy with the hostname
+resolving to a reachable IP address. Make sure your hostname resolves
+to a working IP address; setting it to 127.0.0.1 in ``/etc/hosts`` is
+often good enough for a single-node installation. And in an extreme
+case, use ``clean.sh`` to eradicate it and try again.
+
+Configure ``local.conf`` thusly:
::
@@ -126,22 +147,25 @@
KEYSTONE_SERVICE_HOST=<keystone-host>
KEYSTONE_AUTH_HOST=<keystone-host>
-Q: Why are my configuration changes ignored?
- A: You may have run into the package prerequisite installation
- timeout. ``tools/install_prereqs.sh`` has a timer that skips the
- package installation checks if it was run within the last
- ``PREREQ_RERUN_HOURS`` hours (default is 2). To override this, set
- ``FORCE_PREREQ=1`` and the package checks will never be skipped.
+Why are my configuration changes ignored?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may have run into the package prerequisite installation
+timeout. ``tools/install_prereqs.sh`` has a timer that skips the
+package installation checks if it was run within the last
+``PREREQ_RERUN_HOURS`` hours (default is 2). To override this, set
+``FORCE_PREREQ=1`` and the package checks will never be skipped.
Miscellaneous
=============
-Q: ``tools/fixup_stuff.sh`` is broken and shouldn't 'fix' just one version of packages.
- A: [Another not-a-question] No it isn't. Stuff in there is to
- correct problems in an environment that need to be fixed elsewhere
- or may/will be fixed in a future release. In the case of
- ``httplib2`` and ``prettytable`` specific problems with specific
- versions are being worked around. If later releases have those
- problems than we'll add them to the script. Knowing about the broken
- future releases is valuable rather than polling to see if it has
- been fixed.
+``tools/fixup_stuff.sh`` is broken and shouldn't 'fix' just one version of packages.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Stuff in there is to correct problems in an environment that need to
+be fixed elsewhere or may/will be fixed in a future release. In the
+case of ``httplib2`` and ``prettytable`` specific problems with
+specific versions are being worked around. If later releases have
+those problems than we'll add them to the script. Knowing about the
+broken future releases is valuable rather than polling to see if it
+has been fixed.