mirror of
https://github.com/saltstack/salt.git
synced 2025-04-16 09:40:20 +00:00
Doc updates
This commit is contained in:
C. R. Oldham
parent
f0a7a3caaf
commit
2de9672e95
4 changed files with 161 additions and 34 deletions
127
doc/man/salt-proxy.1
Normal file
127
doc/man/salt-proxy.1
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
.\" Man page generated from reStructuredText.
|
||||
.
|
||||
.TH "SALT-PROXY" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt"
|
||||
.SH NAME
|
||||
salt-proxy \- salt-proxy Documentation
|
||||
.
|
||||
.nr rst2man-indent-level 0
|
||||
.
|
||||
.de1 rstReportMargin
|
||||
\\$1 \\n[an-margin]
|
||||
level \\n[rst2man-indent-level]
|
||||
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
-
|
||||
\\n[rst2man-indent0]
|
||||
\\n[rst2man-indent1]
|
||||
\\n[rst2man-indent2]
|
||||
..
|
||||
.de1 INDENT
|
||||
.\" .rstReportMargin pre:
|
||||
. RS \\$1
|
||||
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
||||
. nr rst2man-indent-level +1
|
||||
.\" .rstReportMargin post:
|
||||
..
|
||||
.de UNINDENT
|
||||
. RE
|
||||
.\" indent \\n[an-margin]
|
||||
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.nr rst2man-indent-level -1
|
||||
.\" new: \\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.
|
||||
.SH SYNOPSIS
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
salt\-proxy [ options ]
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.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.
|
||||
.SH OPTIONS
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-\-proxyid
|
||||
The minion id that this proxy will assume. This is required.
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-\-version
|
||||
Print the version of Salt that is running.
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-\-versions\-report
|
||||
Show program\(aqs dependencies and version number, and then exit
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-h, \-\-help
|
||||
Show the help message and exit
|
||||
.UNINDENT
|
||||
.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\&.
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-u USER, \-\-user=USER
|
||||
Specify user to run salt\-proxy
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-d, \-\-daemon
|
||||
Run salt\-proxy as a daemon
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-\-pid\-file PIDFILE
|
||||
Specify the location of the pidfile. Default: /var/run/salt\-proxy-<id>\&.pid
|
||||
.UNINDENT
|
||||
.SS Logging Options
|
||||
.sp
|
||||
Logging options which override any settings defined on the configuration files.
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
|
||||
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
|
||||
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
|
||||
\fBwarning\fP\&.
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-\-log\-file=LOG_FILE
|
||||
Log file path. Default: /var/log/salt/minion\&.
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
|
||||
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
|
||||
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
|
||||
\fBwarning\fP\&.
|
||||
.UNINDENT
|
||||
.SH SEE ALSO
|
||||
.sp
|
||||
\fIsalt(1)\fP
|
||||
\fIsalt(7)\fP
|
||||
\fIsalt\-master(1)\fP
|
||||
\fIsalt\-minion(1)\fP
|
||||
.SH AUTHOR
|
||||
Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file
|
||||
.SH COPYRIGHT
|
||||
2015 SaltStack, Inc.
|
||||
.\" Generated by docutils manpage writer.
|
||||
.
|
||||
|
|
@ -19,6 +19,21 @@ your typical housecat would be excellent source material for a PhD thesis.
|
|||
Salt proxy-minions provide the 'plumbing' that allows device enumeration
|
||||
and discovery, control, status, remote execution, and state management.
|
||||
|
||||
|
||||
New in 2015.8
|
||||
-------------
|
||||
|
||||
Starting with the 2015.8 release of Salt, proxy processes are no longer forked off from a controlling minion.
|
||||
Instead, they have their own script ``salt-proxy`` which takes mostly the same arguments that the
|
||||
standard Salt minion does with the addition of ``--proxyid``. This is the id that the salt-proxy will
|
||||
use to identify itself to the master. Proxy configurations are still best kept in Pillar and their format
|
||||
has not changed.
|
||||
|
||||
This change allows for better process control and logging. Proxy processes can now be listed with standard
|
||||
process management utilities (``ps`` from the command line). Also, a full Salt minion is no longer
|
||||
required (though it is still strongly recommended) on machines hosting proxies.
|
||||
|
||||
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
|
|
@ -29,13 +44,11 @@ installation that includes proxy-minions:
|
|||
|
||||
The key thing to remember is the left-most section of the diagram. Salt's
|
||||
nature is to have a minion connect to a master, then the master may control
|
||||
the minion. However, for proxy minions, the target device cannot run a minion,
|
||||
and thus must rely on a separate minion to fire up the proxy-minion and make the
|
||||
initial and persistent connection.
|
||||
the minion. However, for proxy minions, the target device cannot run a minion.
|
||||
|
||||
After the proxy minion is started and initiates its connection to the 'dumb'
|
||||
device, it connects back to the salt-master and ceases to be affiliated in
|
||||
any way with the minion that started it.
|
||||
device, it connects back to the salt-master and for all intents and purposes
|
||||
looks like just another minion to the Salt master.
|
||||
|
||||
To create support for a proxied device one needs to create four things:
|
||||
|
||||
|
|
@ -46,8 +59,8 @@ To create support for a proxied device one needs to create four things:
|
|||
4. :ref:`Salt states <all-salt.states>` specific to the controlled device.
|
||||
|
||||
|
||||
Configuration parameters on the master
|
||||
######################################
|
||||
Configuration parameters
|
||||
########################
|
||||
|
||||
Proxy minions require no configuration parameters in /etc/salt/master.
|
||||
|
||||
|
|
@ -136,7 +149,7 @@ In the above example
|
|||
- dumbdevice7 is an SMS gateway connected to machine minioncontroller3 via a
|
||||
serial port.
|
||||
|
||||
Because of the way pillar works, each of the salt-minions that fork off the
|
||||
Because of the way pillar works, each of the salt-proxy processes that fork off the
|
||||
proxy minions will only see the keys specific to the proxies it will be
|
||||
handling. In other words, from the above example, only minioncontroller1 will
|
||||
see the connection information for dumbdevices 1, 2, and 3. Minioncontroller2
|
||||
|
|
@ -151,10 +164,6 @@ control devices because of some physical interface (e.g. i2c and serial above).
|
|||
Another reason to divide proxy services might be security. In more secure
|
||||
environments only certain machines may have a network path to certain devices.
|
||||
|
||||
Now our salt-minions know if they are supposed to spawn a proxy-minion process
|
||||
to control a particular device. That proxy-minion process will initiate
|
||||
a connection back to the master to enable control.
|
||||
|
||||
|
||||
.. _proxy_connection_module:
|
||||
|
||||
|
|
@ -174,10 +183,6 @@ Returning ``False`` will prevent the module from loading.
|
|||
a good place to bring up a persistent connection to a device, or authenticate
|
||||
to create a persistent authorization token.
|
||||
|
||||
``id(opts)``: Returns a unique, unchanging id for the controlled device. This is
|
||||
the "name" of the device, and is used by the salt-master for targeting and key
|
||||
authentication.
|
||||
|
||||
``shutdown()``: Code to cleanly shut down or close a connection to
|
||||
a controlled device goes here. This function must exist, but can contain only
|
||||
the keyword ``pass`` if there is no shutdown logic required.
|
||||
|
|
@ -186,10 +191,17 @@ the keyword ``pass`` if there is no shutdown logic required.
|
|||
be defined in the proxymodule. The code for ``ping`` should contact the
|
||||
controlled device and make sure it is really available.
|
||||
|
||||
Pre 2015.8 the proxymodule also must have an ``id()`` function. 2015.8 and following don't use
|
||||
this function because the proxy's id is required on the command line.
|
||||
|
||||
``id(opts)``: Returns a unique, unchanging id for the controlled device. This is
|
||||
the "name" of the device, and is used by the salt-master for targeting and key
|
||||
authentication.
|
||||
|
||||
Here is an example proxymodule used to interface to a *very* simple REST
|
||||
server. Code for the server is in the `salt-contrib GitHub repository <https://github.com/saltstack/salt-contrib/proxyminion_rest_example>`_
|
||||
|
||||
This proxymodule enables "service" enumration, starting, stopping, restarting,
|
||||
This proxymodule enables "service" enumeration, starting, stopping, restarting,
|
||||
and status; "package" installation, and a ping.
|
||||
|
||||
.. code-block:: python
|
||||
|
|
@ -372,8 +384,9 @@ and status; "package" installation, and a ping.
|
|||
|
||||
Grains are data about minions. Most proxied devices will have a paltry amount
|
||||
of data as compared to a typical Linux server. By default, a proxy minion will
|
||||
have no grains set at all. Salt core code requires values for ``kernel``,
|
||||
``os``, and ``os_family``. To add them (and others) to your proxy minion for
|
||||
have several grains taken from the host. Salt core code requires values for ``kernel``,
|
||||
``os``, and ``os_family``--all of these are forced to be ``proxy`` for proxy-minions.
|
||||
To add others to your proxy minion for
|
||||
a particular device, create a file in salt/grains named [proxytype].py and place
|
||||
inside it the different functions that need to be run to collect the data you
|
||||
are interested in. Here's an example:
|
||||
|
|
@ -439,10 +452,8 @@ Here is an excerpt from a module that was modified to support proxy-minions:
|
|||
def ping():
|
||||
|
||||
if 'proxymodule' in __opts__:
|
||||
if 'ping' in __opts__['proxyobject'].__attr__():
|
||||
return __opts['proxyobject'].ping()
|
||||
else:
|
||||
return False
|
||||
ping_cmd = __opts__['proxymodule'].loaded_base_name + '.ping'
|
||||
return __opts__['proxymodule'][ping_cmd]()
|
||||
else:
|
||||
return True
|
||||
|
||||
|
|
@ -1,4 +1,3 @@
|
|||
.. toctree::
|
||||
|
||||
syndic
|
||||
proxyminion/index
|
||||
|
|
@ -49,16 +49,6 @@ def init(opts):
|
|||
DETAILS['url'] += '/'
|
||||
|
||||
|
||||
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
|
||||
really confused and may stop talking to this minion
|
||||
'''
|
||||
r = salt.utils.http.query(opts['proxy']['url']+'id', decode_type='json', decode=True)
|
||||
return r['dict']['id'].encode('ascii', 'ignore')
|
||||
|
||||
|
||||
def grains():
|
||||
'''
|
||||
Get the grains from the proxied device
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue