Add more configuration documentation

Add additional documentation for the configuration files,
through both comments on the config file and more explanation
in the documentation
Change-Id: Ibb772f09b076d7f28b5d5218a27e4e0de9aa975b

doc/source/installation.rst

@@ -40,8 +40,8 @@ To run the proxy with Apache in Ubuntu: ::
 Configuration
 =============
 The proxy searches for the configuration file ``mixmatch.conf`` in the
-current directory, the ``etc/mixmatch`` directory relative to the current directory or
-``/etc/mixmatch``
+current directory, the ``etc/mixmatch`` directory relative to the current
+directory or ``/etc/mixmatch``.
 
 A sample configuration file has been provided in the ``etc`` folder of the
 source code.
@@ -49,16 +49,22 @@ source code.
 The proxy will substitute the endpoint of the service it is proxying.
 Only Cinder and Glance are supported for now.
 
-For each SP, you must have a section in ``mixmatch.conf`` which contains the
-service provider name (as it is listed in Keystone's service catalog), and the
-URI for connecting to the notification messagebus in that OpenStack
-installation.  For instance::
+For each SP, you must have an option group in ``mixmatch.conf`` which contains
+the service provider name (as it is listed in Keystone's service catalog, but
+with the added prefix `sp_`), the URI for connecting to the notification
+messagebus in that OpenStack installation, the keystone auth url, and the
+endpoints for each of the services enabled under the enabled_services option.
+For instance::
 
     [sp_one]
     sp_name="keystone-sp1"
     messagebus="rabbit://rabbituser:rabbitpassword@192.168.7.20"
     image_endpoint="http://192.168.7.20:9292"
     volume_endpoint="http://192.168.7.20:8776"
+    enabled_services=image, volume
+
+You must also have each service provider's name listed under
+``service_providers`` in ``[DEFAULT]``.
 
 Keystone Configuration
 ----------------------

etc/mixmatch.conf.sample

@@ -1,53 +1,134 @@
+# Configuration for the Mixmatch proxy
+
+#------------------------------------------------------------------------------
+
 [DEFAULT]
+
+# Enable or disable the proxy's aggregation of responses from service providers
 aggregation=True
+
 search_by_broadcast=True
+
+# The names of the service providers
+# Each service provider should have an option group below
+# e.g. [sp_default], [sp_cornmeal-sp]
+# The names should match the ones registered on Keystone
 service_providers=default, cornmeal-sp
+
+# Available image API versions
 image_api_versions = v2.3, v2.2, v2.1, v2.0, v1.1, v1.0
+# Available volume API versions
 volume_api_versions = v3.0, v2.0, v1.0
 
+#------------------------------------------------------------------------------
+
 [database]
+
 connection="sqlite:////home/ubuntu/proxy.db"
 
+#------------------------------------------------------------------------------
+
 [auth]
+
+# URL for Keystone API
 auth_url="http://127.0.0.1:5000/v3"
+
+# Proxy account username
 username="admin"
+
+# Proxy account domain ID
 user_domain_id="default"
+
+# Proxy account password
 password="nomoresecrete"
+
+# Proxy project name
 project_name="admin"
+
+# Proxy project domain ID
 project_domain_id="default"
+
+# Enable/disable caching of auth tokens
 caching=True
 
+#------------------------------------------------------------------------------
+
 [cache]
+
 enabled=True
 backend=dogpile.cache.memory
 
+#------------------------------------------------------------------------------
+
+# Identity provider configuration group
+# Change to match your own identity provider
 [sp_default]
+
+# Name of this service provider
 sp_name=default
+
+# Message bus URI of this service provider
 messagebus="rabbit://stackrabbit:stackqueue@localhost"
+
+# Local Keystone (auth) endpoint on this service provider
 auth_url="http://127.0.0.1:5000/v3"
+
+# Glance (image) endpoint for this service provider
 image_endpoint="http://localhost:9292"
+
+# Local Cinder (volume) endpoint on this service provider
 volume_endpoint="http://localhost:8776"
+
+# Services that are enabled for this service provider
 enabled_services=image, volume
 
+#------------------------------------------------------------------------------
+
+# Service provider configuration group
+# Change to match your own service provider
 [sp_cornmeal-sp]
+
+# Name of this service provider
 sp_name=cornmeal-sp
+
+# Message bus URI of this service provider
 messagebus="rabbit://stackrabbit:stackqueue@192.168.0.141"
+
+# Local Keystone (auth) endpoint on this service provider
 auth_url="http://192.168.0.141:5000/v3"
+
+# Glance (image) endpoint for this service provider
 image_endpoint="http://192.168.0.141:9292"
+
+# Local Cinder (volume) endpoint on this service provider
 volume_endpoint="http://192.168.0.141:8776"
+
+# Services that are enabled for this service provider
 enabled_services=image, volume
 
+#------------------------------------------------------------------------------
+
 # Logging
 [loggers]
+
 keys = root
 
+#------------------------------------------------------------------------------
+
 [handlers]
+
 keys = stdout
 
+#------------------------------------------------------------------------------
+
 [formatters]
+
 keys = default
 
+#------------------------------------------------------------------------------
+
 [logger_root]
+
 level = DEBUG
 handlers = stdout
 formatter = default