saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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

Browse source 
Added salt-proxy release notes topic
Added note to pip state for Refs #21845
Regenerated and versioned man pages
This commit is contained in:
Jacob Hammons 2015-09-01 17:09:35 -06:00
parent e308a74f07
commit 701f47a658
23 changed files with 40155 additions and 17716 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/conf.py
View file

@ -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),

2
doc/man/salt-api.1
View file

@ -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
.

2
doc/man/salt-call.1
View file

@ -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
.

2
doc/man/salt-cloud.1
View file

@ -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
.

2
doc/man/salt-cp.1
View file

@ -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
.

2
doc/man/salt-key.1
View file

@ -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
.

2
doc/man/salt-master.1
View file

@ -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
.

2
doc/man/salt-minion.1
View file

@ -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
.

19
doc/man/salt-proxy.1
View file

@ -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
and communicates with devices unable to run a full minion.
Receives commands from a Salt master and proxies these commands to
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
to devices unable to run a minion, and replies with the results of said commands.
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.
.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 configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
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 \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

2
doc/man/salt-run.1
View file

@ -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
.

2
doc/man/salt-ssh.1
View file

@ -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
.

2
doc/man/salt-syndic.1
View file

@ -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
.

2
doc/man/salt-unity.1
View file

@ -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
.

2
doc/man/salt.1
View file

@ -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
.

57509
doc/man/salt.7
View file

File diff suppressed because it is too large Load diff

2
doc/man/spm.1
View file

@ -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
.

6
doc/ref/cli/index.rst
View file

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

73
doc/ref/cli/salt-proxy.rst Normal file
View file

@ -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)`

2
doc/topics/proxyminion/index.rst
View file

@ -1,3 +1,5 @@
.. _proxy-minion:
===============================
Salt Proxy Minion Documentation
===============================

5
doc/topics/releases/2015.8.0.rst
View file

@ -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
============

110
doc/topics/releases/includes/proxy-2015.8.0.rst Normal file
View file

@ -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>`.

6
salt/states/pip_state.py
View file

@ -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

2
setup.py
View file

@ -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',