| Using an HTTP / HTTPS proxy |
| =========================== |
| |
| .. note:: |
| |
| 1. Support for HTTP proxies is available in Libcloud v0.16.0 and higher. |
| 2. Support for HTTPS proxies is available in Libcloud v2.5.1-dev and higher. |
| 3. In versions prior to v2.5.1-dev, ``driver.connection.set_http_proxy()`` |
| method is broken and you need to use |
| ``driver.connection.connection.set_http_proxy()`` instead. |
| |
| Libcloud supports using an HTTP / HTTPS proxy for outgoing HTTP and HTTPS |
| requests. |
| |
| Proxy support has been tested with the following Python versions: |
| |
| * Python 2.7 / PyPy |
| * Python 3.4 |
| * Python 3.6 |
| * Python 3.7 |
| |
| You can specify which HTTP(s) proxy to use using one of the approaches described |
| below: |
| |
| * By setting ``http_proxy`` / ``https_proxy`` environment variable (this |
| setting is system / process wide) |
| * By passing ``http_proxy`` argument to the |
| :class:`libcloud.common.base.LibcloudConnection` class constructor (this |
| setting is local to the connection instance) |
| * By calling :meth:`libcloud.common.base.LibcloudConnection.set_http_proxy` |
| method aka ``driver.connection.connection.set_http_proxy`` (this setting |
| is local to the connection instance) |
| |
| Known limitations |
| ----------------- |
| |
| * Only HTTP basic access authentication proxy authorization method is supported |
| * If you are using HTTPS proxy you need to configure Libcloud to use CA cert |
| bundle path which is used by the proxy server. See an example below on how to |
| do that. |
| |
| Examples |
| -------- |
| |
| This section includes some code examples which show how to use an HTTP(s) proxy |
| with Libcloud. |
| |
| 1. Using ``http_proxy`` / ``htps_proxy`` environment variable |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| By setting ``http_proxy`` / ``https_proxy`` environment variable you can |
| specify which proxy to use for all of the outgoing requests for a duration / |
| life-time of the process or a script. |
| |
| Without authentication (http proxy): |
| |
| .. sourcecode:: bash |
| |
| http_proxy=http://<proxy hostname>:<proxy port> python my_script.py |
| |
| Without authentication (https proxy): |
| |
| .. sourcecode:: bash |
| |
| http_proxy=https://<proxy hostname>:<proxy port> python my_script.py |
| # or |
| https_proxy=https://<proxy hostname>:<proxy port> python my_script.py |
| |
| |
| With basic auth authentication (http proxy): |
| |
| .. sourcecode:: bash |
| |
| http_proxy=http://<username>:<password>@<proxy hostname>:<proxy port> python my_script.py |
| |
| 2. Passing ``proxy_url`` argument to the connection class constructor |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| . note:: |
| |
| Some drivers don't correctly pass ``proxy_url`` argument to the connection |
| class and don't support ``proxy_url`` constructor argument. |
| |
| If you pass this argument to the driver constructor, but it doesn't appear |
| to be working, it's likely the driver doesn't support this method. |
| |
| In such scenarios, you are advised to use some other method of setting a |
| proxy (e.g. by setting an environment variable or by using |
| :meth:`libcloud.common.base.LibcloudConnection.set_http_proxy` method). |
| |
| By passing ``proxy_url`` argument to the |
| :class:`libcloud.common.base.Connection` class constructor, you can specify |
| which proxy to use for a particular connection. |
| |
| .. literalinclude:: /examples/http_proxy/constructor_argument.py |
| :language: python |
| |
| 3. Calling ``set_http_proxy`` method |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Calling ``set_http_proxy`` method allows you to specify which proxy to use |
| for all the outgoing requests which follow ``set_http_proxy`` method call. |
| |
| This method also allows you to use a different proxy for each request as shown |
| in the example below. |
| |
| .. literalinclude:: /examples/http_proxy/set_http_proxy_method.py |
| :language: python |
| |
| 4. Using an HTTPS proxy |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| This example shows how to use an HTTPS proxy. |
| |
| .. literalinclude:: /examples/http_proxy/https_proxy.py |
| :language: python |
| |
| To use an HTTPS proxy, you also need to configure Libcloud to use CA cert bundle |
| which is used by the HTTPS proxy server, to verify outgoing https request. If you |
| don't do that, you will see errors similar to the one below: |
| |
| .. sourcecode:: python |
| |
| SSLError(1, u'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed |
| |
| Keep in mind that you will also receive a similar error message if you try to |
| use HTTP proxy for HTTPS requests. |