docs/backends/cloud.rst: add documentation for OpenStack config parameters.

Signed-off-by: David-Sarah Hopwood <david-sarah@jacaranda.org>

diff --git a/docs/backends/cloud.rst b/docs/backends/cloud.rst
index e6e43db86d7fd33c6eed1ab32731cbe5eb5c3bc7..7c5f0e6d0b7d5cc1d2bd1402675559939246ab52 100644 (file)
--- a/docs/backends/cloud.rst
+++ b/docs/backends/cloud.rst
@@ -19,7 +19,8 @@ To enable storing shares on S3, add the following keys to the server's
 
 ``backend = cloud.s3``
 
-    This turns off the local filesystem backend and enables use of S3.
+    This turns off the local filesystem backend and enables use of the cloud
+    backend with S3.
 
 ``s3.access_key_id = (string, required)``
 
@@ -57,3 +58,55 @@ are present when the server is started. It is currently assumed that only one
 user and product token pair is needed by a given storage server.
 
 .. _DevPay: http://docs.amazonwebservices.com/AmazonDevPay/latest/DevPayGettingStartedGuide/
+
+
+OpenStack and Rackspace Cloud Files
+===================================
+
+`OpenStack`_ is an open standard for cloud services, including cloud storage.
+Rackspace ( `<https://www.rackspace.com>`__ and `<https://www.rackspace.co.uk>`__ )
+provides a storage service called `Cloud Files`_ based on OpenStack.
+
+.. _OpenStack: https://www.openstack.org/
+.. _Cloud Files: http://www.rackspace.com/cloud/files/
+
+The authentication service is less precisely specified than other parts of
+the OpenStack standards, and so our implementation of it is currently specific
+to Rackspace. Other OpenStack storage providers may be supported in future.
+
+To enable storing shares on Rackspace Cloud Files, add the following keys
+to the server's ``tahoe.cfg`` file:
+
+``[storage]``
+
+``backend = cloud.openstack``
+
+    This turns off the local filesystem backend and enables use of the cloud
+    backend with OpenStack.
+
+``openstack.provider = (string, optional)``
+
+    The supported providers are ``rackspace.com`` and ``rackspace.co.uk``.
+    Use the one corresponding to the site on which the Rackspace user account
+    was created. The default is ``rackspace.com``.
+
+``openstack.username = (string, required)``
+
+    This identifies the Rackspace user account.
+
+    An API key for the account is also needed. It can be generated
+    by logging in at `<https://manage.rackspacecloud.com/APIAccess.do>`__.
+    The API key should be stored in a separate file named
+    ``private/openstack_api_key``.
+
+``openstack.container = (string, required)``
+
+    This controls which container will be used to hold shares. The Tahoe-LAFS
+    storage server will only modify and access objects in the configured
+    container. Multiple storage servers cannot share the same container.
+
+``openstack.url = (URL string, optional)``
+
+    This overrides the URL used to access the authentication service. It
+    does not need to be set when using a Rackspace account, because the
+    correct service is chosen based on ``openstack.provider`` by default.