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