Merge pull request #37076 from jfindlay/proxy_doc

Document proxy settings

doc/ref/configuration/minion.rst

@@ -923,6 +923,57 @@ talking to the intended master.
 
     syndic_finger: 'ab:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:50:10'
 
+.. conf_minion:: proxy_host
+
+``proxy_host``
+--------------
+
+Default: ``''``
+
+The hostname used for HTTP proxy access.
+
+.. code-block:: yaml
+
+    proxy_host: proxy.my-domain
+
+.. conf_minion:: proxy_port
+
+``proxy_port``
+--------------
+
+Default: ``0``
+
+The port number used for HTTP proxy access.
+
+.. code-block:: yaml
+
+    proxy_port: 31337
+
+.. conf_minion:: proxy_username
+
+``proxy_username``
+--------------
+
+Default: ``''``
+
+The username used for HTTP proxy access.
+
+.. code-block:: yaml
+
+    proxy_username: charon
+
+.. conf_minion:: proxy_password
+
+``proxy_password``
+--------------
+
+Default: ``''``
+
+The password used for HTTP proxy access.
+
+.. code-block:: yaml
+
+    proxy_password: obolus
 
 Minion Module Management
 ========================

doc/topics/tutorials/http.rst

@@ -56,6 +56,9 @@ This function forms a basic query, but with some add-ons not present in the
 currently available in these libraries has been added, but can be in future
 iterations.
 
+HTTPS Request Methods
+`````````````````````
+
 A basic query can be performed by calling this function with no more than a
 single URL:
 
@@ -82,7 +85,10 @@ required by the remote server (XML, JSON, plain text, etc).
         data=json.loads(mydict)
     )
 
-Bear in mind that this data must be sent pre-formatted; this function will not
+Data Formatting and Templating
+``````````````````````````````
+
+Bear in mind that the data must be sent pre-formatted; this function will not
 format it for you. However, a templated file stored on the local system may be
 passed through, along with variables to populate it with. To pass through only
 the file (untemplated):
@@ -147,6 +153,9 @@ However, this can be changed to ``master`` if necessary.
         node='master'
     )
 
+Headers
+```````
+
 Headers may also be passed through, either as a ``header_list``, a
 ``header_dict``, or as a ``header_file``. As with the ``data_file``, the
 ``header_file`` may also be templated. Take note that because HTTP headers are
@@ -168,6 +177,9 @@ Because much of the data that would be templated between headers and data may be
 the same, the ``template_data`` is the same for both. Correcting possible
 variable name collisions is up to the user.
 
+Authentication
+``````````````
+
 The ``query()`` function supports basic HTTP authentication. A username and
 password may be passed in as ``username`` and ``password``, respectively.
 
@@ -179,6 +191,9 @@ password may be passed in as ``username`` and ``password``, respectively.
         password=`5700g3543v4r`,
     )
 
+Cookies and Sessions
+````````````````````
+
 Cookies are also supported, using Python's built-in ``cookielib``. However, they
 are turned off by default. To turn cookies on, set ``cookies`` to True.
 
@@ -232,6 +247,29 @@ The format of this file is msgpack, which is consistent with much of the rest
 of Salt's internal structure. Historically, the extension for this file is
 ``.p``. There are no current plans to make this configurable.
 
+Proxy
+`````
+
+If the ``tornado`` backend is used (``tornado`` is the default), proxy
+information configured in ``proxy_host``, ``proxy_port``, ``proxy_username``,
+and ``proxy_password`` from the ``__opts__`` dictionary will be used.  Normally
+these are set in the minion configuration file.
+
+.. code-block:: yaml
+
+    proxy_host: proxy.my-domain
+    proxy_port: 31337
+    proxy_username: charon
+    proxy_password: obolus
+
+.. code-block:: python
+
+    salt.utils.http.query(
+        'http://example.com',
+        opts=__opts__,
+        backend='tornado'
+    )
+
 Return Data
 ~~~~~~~~~~~