1Apache Libcloud
2===============
3
4`Apache Libcloud`_ is an API wrapper around a range of cloud storage providers.
5It aims to provide a consistent API for dealing with cloud storage (and, more
6broadly, the many other services provided by cloud providers, such as device
7provisioning, load balancer configuration, and DNS configuration).
8
9Use pip to install apache-libcloud from PyPI::
10
11    pip install apache-libcloud
12
13As of v0.10.1, Libcloud supports the following cloud storage providers:
14    * `Amazon S3`_
15    * `Google Cloud Storage`_
16    * `Nimbus.io`_
17    * `Ninefold Cloud Storage`_
18    * `Rackspace CloudFiles`_
19
20Libcloud can also be configured with relatively little effort to support any provider
21using EMC Atmos storage, or the OpenStack API.
22
23.. _Apache Libcloud: http://libcloud.apache.org/
24.. _Amazon S3: http://aws.amazon.com/s3/
25.. _Google Cloud Storage: http://cloud.google.com/products/cloud-storage.html
26.. _Rackspace CloudFiles: http://www.rackspace.com/cloud/cloud_hosting_products/files/
27.. _Ninefold Cloud Storage: http://ninefold.com/cloud-storage/
28.. _Nimbus.io: http://nimbus.io
29
30Settings
31--------
32
33``LIBCLOUD_PROVIDERS``
34~~~~~~~~~~~~~~~~~~~~~~
35
36This setting is required to configure connections to cloud storage providers.
37Each entry corresponds to a single 'bucket' of storage. You can have multiple
38buckets for a single service provider (e.g., multiple S3 buckets), and you can
39define buckets at multiple providers. For example, the following configuration
40defines 3 providers: two buckets (``bucket-1`` and ``bucket-2``) on a US-based
41Amazon S3 store, and a third bucket (``bucket-3``) on Google::
42
43
44    LIBCLOUD_PROVIDERS = {
45        'amazon_1': {
46            'type': 'libcloud.storage.types.Provider.S3_US_STANDARD_HOST',
47            'user': '<your username here>',
48            'key': '<your key here>',
49            'bucket': 'bucket-1',
50        },
51        'amazon_2': {
52            'type': 'libcloud.storage.types.Provider.S3_US_STANDARD_HOST',
53            'user': '<your username here>',
54            'key': '<your key here>',
55            'bucket': 'bucket-2',
56        },
57        'google': {
58            'type': 'libcloud.storage.types.Provider.GOOGLE_STORAGE',
59            'user': '<Your Google APIv1 username>',
60            'key': '<Your Google APIv1 Key>',
61            'bucket': 'bucket-3',
62        },
63    }
64
65The values for the ``type``, ``user`` and ``key`` arguments will vary depending on
66your storage provider:
67
68    **Amazon S3**:
69
70        **type**: ``libcloud.storage.types.Provider.S3_US_STANDARD_HOST``,
71
72        **user**: Your AWS access key ID
73
74        **key**: Your AWS secret access key
75
76        If you want to use a availability zone other than the US default, you
77        can use one of ``S3_US_WEST_HOST``, ``S3_US_WEST_OREGON_HOST``,
78        ``S3_EU_WEST_HOST``, ``S3_AP_SOUTHEAST_HOST``, or
79        ``S3_AP_NORTHEAST_HOST`` instead of ``S3_US_STANDARD_HOST``.
80
81    **Google Cloud Storage**:
82
83        **type**: ``libcloud.storage.types.Provider.GOOGLE_STORAGE``,
84
85        **user**: Your Google APIv1 username (20 characters)
86
87        **key**: Your Google APIv1 key
88
89    **Nimbus.io**:
90
91        **type**: ``libcloud.storage.types.Provider.NIMBUS``,
92
93        **user**: Your Nimbus.io user ID
94
95        **key**: Your Nimbus.io access key
96
97    **Ninefold Cloud Storage**:
98
99        **type**: ``libcloud.storage.types.Provider.NINEFOLD``,
100
101        **user**: Your Atmos Access Token
102
103        **key**: Your Atmos Shared Secret
104
105    **Rackspace Cloudfiles**:
106
107        **type**: ``libcloud.storage.types.Provider.CLOUDFIULES_US`` or ``libcloud.storage.types.Provider.CLOUDFIULES_UK``,
108
109        **user**: Your Rackspace user ID
110
111        **key**: Your Rackspace access key
112
113You can specify any bucket name you want; however, the bucket must exist before you
114can start using it. If you need to create the bucket, you can use the storage API.
115For example, to create ``bucket-1`` from our previous example::
116
117    >>> from storages.backends.apache_libcloud import LibCloudStorage
118    >>> store = LibCloudStorage('amazon_1')
119    >>> store.driver.create_container('bucket-1')
120
121
122``DEFAULT_LIBCLOUD_PROVIDER``
123~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124
125Once you have defined your Libcloud providers, you have the option of
126setting one provider as the default provider of Libcloud storage. This
127is done setting ``DEFAULT_LIBCLOUD_PROVIDER`` to the key in
128``LIBCLOUD_PROVIDER`` that you want to use as the default provider.
129For example, if you want the ``amazon-1`` provider to be the default
130provider, use::
131
132    DEFAULT_LIBCLOUD_PROVIDER = 'amazon-1'
133
134If ``DEFAULT_LIBCLOUD_PROVIDER`` isn't set, the Libcloud backend will assume
135that the default storage backend is named ``default``. Therefore, you can
136avoid settings DEFAULT_LIBCLOUD_PROVIDER by simply naming one of your
137Libcloud providers ``default``::
138
139    LIBCLOUD_PROVIDERS = {
140        'default': {
141            'type': ...
142        },
143    }
144
145
146``DEFAULT_FILE_STORAGE``
147~~~~~~~~~~~~~~~~~~~~~~~~
148
149If you want your Libcloud storage to be the default Django file store, you can
150set::
151
152    DEFAULT_FILE_STORAGE = 'storages.backends.apache_libcloud.LibCloudStorage'
153
154Your default Libcloud provider will be used as the file store.
155
156Certificate authorities
157-----------------------
158
159Libcloud uses HTTPS connections, and in order to validate that these HTTPS connections are
160correctly signed, root CA certificates must be present. On some platforms
161(most notably, OS X and Windows), the required certificates may not be available
162by default. To test
163
164    >>> from storages.backends.apache_libcloud import LibCloudStorage
165    >>> store = LibCloudStorage('amazon_1')
166    Traceback (most recent call last):
167    ...
168    ImproperlyConfigured: Unable to create libcloud driver type libcloud.storage.types.Provider.S3_US_STANDARD_HOST: No CA Certificates were found in CA_CERTS_PATH.
169
170If you get this error, you need to install a certificate authority.
171`Download a certificate authority file`_, and then put the following two lines
172into your settings.py::
173
174    import libcloud.security
175    libcloud.security.CA_CERTS_PATH.append("/path/to/your/cacerts.pem")
176
177.. _Download a certificate authority file: http://curl.haxx.se/ca/cacert.pem
178