Added rst source for salt-proxy man page, added build and copy lines for this man page to doc/conf.py and setup.py

Added salt-proxy release notes topic
Added note to pip state for Refs #21845
Regenerated and versioned man pages

doc/conf.py

@@ -386,6 +386,7 @@ man_pages = [
     ('ref/cli/salt-key', 'salt-key', 'salt-key Documentation', authors, 1),
     ('ref/cli/salt-cp', 'salt-cp', 'salt-cp Documentation', authors, 1),
     ('ref/cli/salt-call', 'salt-call', 'salt-call Documentation', authors, 1),
+    ('ref/cli/salt-proxy', 'salt-proxy', 'salt-proxy Documentation', authors, 1),
     ('ref/cli/salt-syndic', 'salt-syndic', 'salt-syndic Documentation', authors, 1),
     ('ref/cli/salt-run', 'salt-run', 'salt-run Documentation', authors, 1),
     ('ref/cli/salt-ssh', 'salt-ssh', 'salt-ssh Documentation', authors, 1),

doc/man/salt-api.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-API" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-API" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-api \- salt-api Command
 .

doc/man/salt-call.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-CALL" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-CALL" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-call \- salt-call Documentation
 .

doc/man/salt-cloud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-CLOUD" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-CLOUD" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-cloud \- Salt Cloud Command
 .

doc/man/salt-cp.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-CP" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-CP" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-cp \- salt-cp Documentation
 .

doc/man/salt-key.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-KEY" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-KEY" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-key \- salt-key Documentation
 .

doc/man/salt-master.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-MASTER" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-MASTER" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-master \- salt-master Documentation
 .

doc/man/salt-minion.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-MINION" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-MINION" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-minion \- salt-minion Documentation
 .

doc/man/salt-proxy.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-PROXY" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-PROXY" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-proxy \- salt-proxy Documentation
 .
@@ -31,8 +31,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
 .sp
-The Salt Proxy minion daemon, receives commands from a remote Salt master
+Receives commands from a Salt master and proxies these commands to
-and communicates with devices unable to run a full minion.
+devices that are unable to run a full minion.
 .SH SYNOPSIS
 .INDENT 0.0
 .INDENT 3.5
@@ -46,8 +46,9 @@ salt\-proxy [ options ]
 .UNINDENT
 .SH DESCRIPTION
 .sp
-The Salt proxy minion receives commands from the central Salt master, transmits apppropriate commands
+The Salt proxy minion receives commands from a Salt master, transmits
- to devices unable to run a minion, and replies with the results of said commands.
+appropriate commands to devices that are unable to run a minion, and replies
+with the results of said commands.
 .SH OPTIONS
 .INDENT 0.0
 .TP
@@ -72,9 +73,9 @@ Show the help message and exit
 .INDENT 0.0
 .TP
 .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
-The location of the Salt configuration directory. This directory contains
+The location of the Salt configuration directory. This directory
-the configuration files for Salt master and minions. The default location
+contains  the  configuration  files for Salt master and minions.
-on most systems is \fB/etc/salt\fP\&.
+The default location on most systems is \fB/etc/salt\fP\&.
 .UNINDENT
 .INDENT 0.0
 .TP
@@ -89,7 +90,7 @@ Run salt\-proxy as a daemon
 .INDENT 0.0
 .TP
 .B \-\-pid\-file PIDFILE
-Specify the location of the pidfile. Default: /var/run/salt\-proxy-<id>\&.pid
+Specify the location of the pidfile. Default: \fB/var/run/salt\-proxy\-<id>.pid\fP
 .UNINDENT
 .SS Logging Options
 .sp

doc/man/salt-run.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-RUN" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-RUN" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-run \- salt-run Documentation
 .

doc/man/salt-ssh.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-SSH" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-SSH" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-ssh \- salt-ssh Documentation
 .

doc/man/salt-syndic.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-SYNDIC" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-SYNDIC" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-syndic \- salt-syndic Documentation
 .

doc/man/salt-unity.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-UNITY" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT-UNITY" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt-unity \- salt-unity Command
 .

doc/man/salt.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SALT" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 salt \- salt
 .

doc/man/spm.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SPM" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
+.TH "SPM" "1" "September 01, 2015" "2015.8.0" "Salt"
 .SH NAME
 spm \- Salt Package Manager Command
 .

doc/ref/cli/index.rst

@@ -273,6 +273,12 @@ salt-minion
 
     salt-minion
 
+salt-proxy
+==========
+.. toctree::
+
+    salt-proxy
+
 salt-run
 ========
 .. toctree::

doc/ref/cli/salt-proxy.rst

@@ -0,0 +1,73 @@
+.. _salt-proxy-cli:
+
+==============
+``salt-proxy``
+==============
+
+Receives commands from a Salt master and proxies these commands to
+devices that are unable to run a full minion.
+
+Synopsis
+========
+
+.. code-block:: bash
+
+    salt-proxy [ options ]
+
+Description
+===========
+
+The Salt proxy minion receives commands from a Salt master, transmits
+appropriate commands to devices that are unable to run a minion, and replies
+with the results of said commands.
+
+Options
+=======
+
+.. program:: salt-proxy
+
+.. option:: --proxyid
+
+    The minion id that this proxy will assume.  This is required.
+
+.. option:: --version
+
+    Print the version of Salt that is running.
+
+.. option:: --versions-report
+
+    Show program's dependencies and version number, and then exit
+
+.. option:: -h, --help
+
+   Show the help message and exit
+
+.. option:: -c CONFIG_DIR, --config-dir=CONFIG_dir
+
+   The location of the Salt configuration directory. This directory
+   contains  the  configuration  files for Salt master and minions.
+   The default location on most systems is ``/etc/salt``.
+
+.. option:: -u USER, --user=USER
+
+   Specify user to run salt-proxy
+
+.. option:: -d, --daemon
+
+   Run salt-proxy as a daemon
+
+.. option:: --pid-file PIDFILE
+
+   Specify the location of the pidfile. Default: ``/var/run/salt-proxy-<id>.pid``
+
+.. include:: _includes/logging-options.rst
+.. |logfile| replace:: /var/log/salt/minion
+.. |loglevel| replace:: ``warning``
+
+See also
+========
+
+:manpage:`salt(1)`
+:manpage:`salt(7)`
+:manpage:`salt-master(1)`
+:manpage:`salt-minion(1)`

doc/topics/proxyminion/index.rst

@@ -1,3 +1,5 @@
+.. _proxy-minion:
+
 ===============================
 Salt Proxy Minion Documentation
 ===============================
@@ -243,7 +245,7 @@ and status; "package" installation, and a ping.
     # -*- coding: utf-8 -*-
     '''
     This is a simple proxy-minion designed to connect to and communicate with
-    the bottle-based web service contained in 
+    the bottle-based web service contained in
     https://github.com/saltstack/salt-contrib/proxyminion_rest_example
     '''
     from __future__ import absolute_import
@@ -276,12 +278,12 @@ and status; "package" installation, and a ping.
         log.debug('rest_sample proxy __virtual__() called...')
         return True
 
-    # Every proxy module needs an 'init', though you can 
+    # Every proxy module needs an 'init', though you can
     # just put a 'pass' here if it doesn't need to do anything.
     def init(opts):
         log.debug('rest_sample proxy init() called...')
 
-        # Save the REST URL 
+        # Save the REST URL
         DETAILS['url'] = opts['proxy']['url']
 
         # Make sure the REST URL ends with a '/'
@@ -292,7 +294,7 @@ and status; "package" installation, and a ping.
     def id(opts):
         '''
         Return a unique ID for this proxy minion.  This ID MUST NOT CHANGE.
-        If it changes while the proxy is running the salt-master will get 
+        If it changes while the proxy is running the salt-master will get
         really confused and may stop talking to this minion
         '''
         r = salt.utils.http.query(opts['proxy']['url']+'id', decode_type='json', decode=True)
@@ -479,7 +481,7 @@ Here is an excerpt from a module that was modified to support proxy-minions:
 .. code-block:: python
 
    __proxyenabled__ = ['*']
-   
+
    [...]
 
     def ping():

doc/topics/releases/2015.8.0.rst

@@ -56,6 +56,11 @@ performance.
        retrieved (:issue:`25718)
      - [freebsd] TCP transport not working in 2015.8.0rc3 (:issue:`26364`)
 
+Proxy Minion Enhancements
+=========================
+
+Proxy Minions have undergone a significant overhaul in 2015.8, see :ref:`Proxy Minion Enhancements <proxy-2015.8.0>`.
+
 Core Changes
 ============
 

doc/topics/releases/includes/proxy-2015.8.0.rst

@@ -0,0 +1,110 @@
+.. _proxy-2015.8.0:
+
+=========================
+Proxy Minion Enhancements
+=========================
+
+Proxy Minions have undergone a significant overhaul in 2015.8.
+
+- Proxies are now more of a first-class citizen in the Salt universe
+- Proxies are no longer started by a "parent minion", they are started on the
+  command line with the new ``salt-proxy`` command
+- The default configuration file for proxies is now ``/etc/salt/proxy``.
+- The default logfile for proxies is now ``/var/log/salt/proxy``.
+- ``salt-proxy`` takes a ``--proxyid`` switch.  This becomes the id of the proxy
+  minion, and thus the pillar key under which the configuration for the proxy is
+  looked up.
+- Proxies have been lightly tested with the new TCP transport.  They still do
+  not work with the RAET transport.
+- The pillar structure is therefore different than in previous releases.  In
+  earlier releases you might have something that looked like this:
+
+``/srv/pillar/top.sls``:
+
+.. code-block:: yaml
+
+    base:
+      minioncontroller:
+        - dumbdevice1
+        - dumbdevice2
+
+``/srv/pillar/dumbdevice1.sls``:
+
+.. code-block:: yaml
+
+    dumbdevice1:
+      proxy:
+        proxytype: networkswitch
+        host: 172.23.23.5
+        username: root
+        passwd: letmein
+
+``/srv/pillar/dumbdevice2.sls``:
+
+.. code-block:: yaml
+
+    dumbdevice2:
+      proxy:
+        proxytype: networkswitch
+        host: 172.23.23.6
+        username: root
+        passwd: letmein
+
+
+This would cause the minion with id ``minioncontroller`` to fork off two
+processes and rename their minion id's to ``dumbdevice1`` and ``dumbdevice2``.
+These processes would initiate a new connection to the master.
+
+For proxy minion controllers this made it quite difficult to tell which process
+was doing what.  Also, if the controlling minion died for any reason, it would
+take all the proxies with it.  The new pillar structure does away with the
+id's in the lower level pillar files and brings proxy configuration to the same
+level with all other minions.
+
+``/srv/pillar/top.sls``:
+
+.. code-block:: yaml
+
+    base:
+      dumbdevice1:
+        - dumbdevice1
+      dumbdevice2:
+        - dumbdevice2
+
+``/srv/pillar/dumbdevice1.sls``:
+
+.. code-block:: yaml
+
+proxy:
+  proxytype: networkswitch
+  host: 172.23.23.5
+  username: root
+  passwd: letmein
+
+``/srv/pillar/dumbdevice2.sls``:
+
+.. code-block:: yaml
+
+proxy:
+  proxytype: networkswitch
+  host: 172.23.23.6
+  username: root
+  passwd: letmein
+
+Proxies can be better tracked via system process utilities:
+
+..code-block:: bash
+
+    root@raring64:/var/log/salt# ps guax | grep p8
+    root     15215  pts/3    S+   10:57   0:00 python salt-proxy -l debug --proxyid=p8000
+    root     15275  pts/5    S+   10:57   0:00 python salt-proxy -l debug --proxyid=p8002
+
+Proxies still gather a significant number of grains from the host.  This is
+useful for targeting, but does not obviate the need for custom grains to better
+support your controlled devices.  See the proxy documentation for writing
+grains modules for your proxy.
+
+Future enhancements of proxy minions could include execution modules and states
+for easier proxy process management.
+
+See :ref:`Proxy Minion Documentation <proxy-minion>`.

salt/states/pip_state.py

@@ -250,6 +250,12 @@ def installed(name,
     '''
     Make sure the package is installed
 
+    .. note::
+
+        There is a known issue when using pip v1.0 that causes ``pip install`` to return
+        1 when executed without arguments. See :issue:`21845` for details and
+        potential workarounds.
+
     name
         The name of the python package to install. You can also specify version
         numbers here using the standard operators ``==, >=, <=``. If

setup.py

@@ -978,6 +978,7 @@ class SaltDistribution(distutils.dist.Distribution):
         if IS_WINDOWS_PLATFORM:
             data_files[0][1].extend(['doc/man/salt-cp.1',
                                      'doc/man/salt-minion.1',
+                                     'doc/man/salt-proxy.1',
                                      'doc/man/salt-unity.1'])
             return data_files
 
@@ -988,6 +989,7 @@ class SaltDistribution(distutils.dist.Distribution):
                                  'doc/man/salt-key.1',
                                  'doc/man/salt-master.1',
                                  'doc/man/salt-minion.1',
+                                 'doc/man/salt-proxy.1',
                                  'doc/man/salt-run.1',
                                  'doc/man/salt-ssh.1',
                                  'doc/man/salt-syndic.1',